refactor: scan filenames at resolve, parse only selected agent at preflight

Manifest.resolve() now returns an empty-dict manifest with only directory
paths recorded (home_md, cwd_md). No content is read from any .md file
until load_for_agent() is called for a specific agent at preflight.

- Manifest.from_md_dirs: scan-only, no frontmatter parsing
- Manifest.load_for_agent: parses the selected agent file and its bottle
  chain; works on eager (from_json_obj) manifests too by returning self
- Manifest.all_agent_names: scans filenames in lazy mode
- backend._validate: calls load_for_agent and propagates upgraded spec
- cli/info.py, cli/list.py, cli/start.py: use load_for_agent / all_agent_names
- manifest_extends.py: reverted to original (no partial-resolve helpers)
- manifest_loader.py: only scan_agent_names + load_bottle_chain_from_dir
- Tests updated to call load_for_agent before accessing agents/bottles;
  test_md_agent_repos_deferred renamed to test_md_agent_repos_fails_at_preflight

bot_bottle/backend/__init__.py

@@ -37,7 +37,7 @@ import shlex
 import sys
 from abc import ABC, abstractmethod
 from contextlib import AbstractContextManager
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any, Generic, Sequence, TypeVar
 
@@ -45,7 +45,7 @@ from ..agent_provider import AgentProvisionPlan, get_provider, build_agent_provi
 from ..egress import EgressPlan
 from ..git_gate import GitGatePlan
 from ..log import die, info
-from ..manifest import ManifestGitEntry, Manifest
+from ..manifest import Manifest
 from ..supervise import SupervisePlan
 from ..util import expand_tilde
 from ..env import resolve_env, ResolvedEnv
@@ -289,7 +289,7 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
             write_launch_metadata,
         )
 
-        self._validate(spec)
+        spec = self._validate(spec)
 
         self._preflight()
 
@@ -355,18 +355,21 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
         """
         pass
 
-    def _validate(self, spec: BottleSpec) -> None:
-        """Cross-backend pre-launch checks. Confirms the agent exists,
-        the named skills are present on the host, and every git
-        IdentityFile resolves. Subclasses with additional preconditions
-        should override and call `super()._validate(spec)` first."""
-        manifest = spec.manifest
-        manifest.require_agent(spec.agent_name)
+    def _validate(self, spec: BottleSpec) -> BottleSpec:
+        """Cross-backend pre-launch checks. Parses the selected agent and
+        its bottle (raising ManifestError on invalid content), confirms
+        skills are present on the host, and every git IdentityFile resolves.
+
+        Returns a new BottleSpec whose manifest is fully loaded for the
+        selected agent. Subclasses with additional preconditions should
+        override and call `super()._validate(spec)` first, using the
+        returned spec for further checks."""
+        manifest = spec.manifest.load_for_agent(spec.agent_name)
+        spec = replace(spec, manifest=manifest)
         agent = manifest.agents[spec.agent_name]
-        bottle = manifest.bottle_for(spec.agent_name)
         self._validate_skills(agent.skills)
-        self._validate_git_entries(bottle.git)
         self._validate_agent_provider_dockerfile(spec)
+        return spec
 
     def _validate_skills(self, skills: Sequence[str]) -> None:
         """Each named skill must be a directory under the host's
@@ -380,16 +383,6 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
                     f"Create it under ~/.claude/skills/, then re-run."
                 )
 
-    def _validate_git_entries(self, entries: Sequence[ManifestGitEntry]) -> None:
-        """Each entry's IdentityFile must exist on the host (after
-        expanding leading ~) — the git-gate copies it in at start time
-        to authenticate the upstream push (PRD 0008). Shape is already
-        enforced by Manifest validation; this only checks presence."""
-        for entry in entries:
-            key = expand_tilde(entry.IdentityFile)
-            if not os.path.isfile(key):
-                die(f"git upstream key file not found for '{entry.Name}': {key}")
-
     def _validate_agent_provider_dockerfile(self, spec: BottleSpec) -> None:
         bottle = spec.manifest.bottle_for(spec.agent_name)
         dockerfile = bottle.agent_provider.dockerfile

bot_bottle/backend/resolve_common.py

@@ -33,8 +33,18 @@ from . import BottleSpec
 
 def mint_slug(spec: BottleSpec) -> str:
     """Return the bottle identity: the recorded identity for a resume,
-    or a freshly minted one for a new start."""
-    return spec.identity or bottle_identity(spec.agent_name)
+    or a freshly minted one for a new start.
+
+    When a label is provided it becomes the full slug (no random suffix),
+    so two launches with the same label collide by design.  When no label
+    is given the identity is minted with a random suffix to avoid
+    collisions between anonymous launches of the same agent."""
+    if spec.identity:
+        return spec.identity
+    if spec.label:
+        from .docker import util as docker_mod
+        return docker_mod.slugify(spec.label)
+    return bottle_identity(spec.agent_name)
 
 
 def write_launch_metadata(

bot_bottle/backend/terminal.py

@@ -12,22 +12,11 @@ import shlex
 # uses true/24-bit colors for its own chrome, which would otherwise bypass
 # the palette entirely.
 _COLORS: dict[str, tuple[int, str, int, str, str]] = {
-    "black":          (0,  "#2d2d2d", 8,  "#5c5c5c", "#0a0a0a"),
-    "red":            (1,  "#c0392b", 9,  "#e74c3c", "#1a0707"),
-    "green":          (2,  "#27ae60", 10, "#2ecc71", "#071a09"),
-    "yellow":         (3,  "#d4ac0d", 11, "#f1c40f", "#1a1507"),
-    "blue":           (4,  "#2471a3", 12, "#3498db", "#07071a"),
-    "magenta":        (5,  "#7d3c98", 13, "#9b59b6", "#12071a"),
-    "cyan":           (6,  "#148f77", 14, "#1abc9c", "#071a1a"),
-    "white":          (7,  "#bdc3c7", 15, "#ecf0f1", "#111111"),
-    "bright-black":   (8,  "#5c5c5c", 0,  "#2d2d2d", "#111111"),
-    "bright-red":     (9,  "#e74c3c", 1,  "#c0392b", "#200808"),
-    "bright-green":   (10, "#2ecc71", 2,  "#27ae60", "#082008"),
-    "bright-yellow":  (11, "#f1c40f", 3,  "#d4ac0d", "#201808"),
-    "bright-blue":    (12, "#3498db", 4,  "#2471a3", "#080820"),
-    "bright-magenta": (13, "#9b59b6", 5,  "#7d3c98", "#160820"),
-    "bright-cyan":    (14, "#1abc9c", 6,  "#148f77", "#082020"),
-    "bright-white":   (15, "#ecf0f1", 7,  "#bdc3c7", "#151515"),
+    "red":     (9,  "#e74c3c", 1,  "#c0392b", "#200808"),
+    "green":   (10, "#2ecc71", 2,  "#27ae60", "#082008"),
+    "yellow":  (11, "#f1c40f", 3,  "#d4ac0d", "#201808"),
+    "blue":    (12, "#3498db", 4,  "#2471a3", "#080820"),
+    "magenta": (13, "#9b59b6", 5,  "#7d3c98", "#160820"),
 }
 
 # OSC 104 resets all indexed palette entries; OSC 111 resets default background.

bot_bottle/cli/info.py

@@ -14,8 +14,9 @@ def cmd_info(argv: list[str]) -> int:
     parser.add_argument("name", help="agent name defined in bot-bottle.json")
     args = parser.parse_args(argv)
 
-    manifest = Manifest.resolve(USER_CWD)
-    manifest.require_agent(args.name)
+    names = Manifest.resolve(USER_CWD)
+    names.require_agent(args.name)
+    manifest = names.load_for_agent(args.name)
 
     agent = manifest.agents[args.name]
     bottle = manifest.bottle_for(args.name)

bot_bottle/cli/list.py

@@ -11,22 +11,11 @@ from ..manifest import Manifest
 from ._common import PROG, USER_CWD
 
 _ANSI_COLOR_CODES: dict[str, str] = {
-    "black": "\033[30m",
-    "red": "\033[31m",
-    "green": "\033[32m",
-    "yellow": "\033[33m",
-    "blue": "\033[34m",
-    "magenta": "\033[35m",
-    "cyan": "\033[36m",
-    "white": "\033[37m",
-    "bright-black": "\033[90m",
-    "bright-red": "\033[91m",
-    "bright-green": "\033[92m",
-    "bright-yellow": "\033[93m",
-    "bright-blue": "\033[94m",
-    "bright-magenta": "\033[95m",
-    "bright-cyan": "\033[96m",
-    "bright-white": "\033[97m",
+    "red": "\033[91m",
+    "green": "\033[92m",
+    "yellow": "\033[93m",
+    "blue": "\033[94m",
+    "magenta": "\033[95m",
 }
 _ANSI_RESET = "\033[0m"
 
@@ -52,7 +41,7 @@ def cmd_list(argv: list[str]) -> int:
 
     if args.scope == "available":
         manifest = Manifest.resolve(USER_CWD)
-        for name in manifest.agents.keys():
+        for name in manifest.all_agent_names:
             print(name)
         return 0
 

bot_bottle/cli/start.py

@@ -20,9 +20,11 @@ from ..agent_provider import runtime_for
 from ..backend import (
     Bottle,
     BottleSpec,
+    enumerate_active_agents,
     get_bottle_backend,
     known_backend_names,
 )
+from ..backend.docker import util as docker_mod
 from ..backend.docker.bottle_plan import DockerBottlePlan
 from ..bottle_state import (
     cleanup_state,
@@ -65,7 +67,7 @@ def cmd_start(argv: list[str]) -> int:
     agent_name: str | None = args.name
     if agent_name is None:
         agent_name = tui.filter_select(
-            sorted(manifest.agents.keys()),
+            manifest.all_agent_names,
             title="Select agent",
         )
         if agent_name is None:
@@ -74,6 +76,7 @@ def cmd_start(argv: list[str]) -> int:
     backend_name: str | None = args.backend
 
     label, color = tui.name_color_modal(default_label=agent_name)
+    label, color = _resolve_unique_label(label, color)
 
     spec = BottleSpec(
         manifest=manifest,
@@ -191,6 +194,21 @@ def _identity_from_plan(plan: object) -> str:
     return getattr(plan, "slug", "")
 
 
+def _resolve_unique_label(label: str, color: str) -> tuple[str, str]:
+    """Re-prompt with a disclaimer until the label's slug is not already
+    in use among running bottles.  Passes through unchanged when no
+    collision is found on the first check."""
+    while True:
+        slug_candidate = docker_mod.slugify(label)
+        active_slugs = {a.slug for a in enumerate_active_agents()}
+        if slug_candidate not in active_slugs:
+            return label, color
+        label, color = tui.name_color_modal(
+            default_label=label,
+            disclaimer=f'"{label}" is already in use',
+        )
+
+
 def _text_prompt_yes() -> bool:
     """Default `prompt_yes` for CLI use: reads y/N from the
     controlling tty via stderr prompt + tty-line read."""

bot_bottle/cli/tui.py

@@ -226,20 +226,15 @@ def _addstr_safe(screen: Any, row: int, col: int, text: str, attr: int = curses.
 # ---------------------------------------------------------------------------
 
 _ANSI_COLORS = [
-    "red", "green", "blue", "yellow", "magenta", "cyan", "white", "black",
-    "bright-red", "bright-green", "bright-blue", "bright-yellow",
-    "bright-magenta", "bright-cyan", "bright-white", "bright-black",
+    "red", "green", "yellow", "blue", "magenta",
 ]
 
 _CURSES_COLOR_MAP: dict[str, int] = {
-    "black": curses.COLOR_BLACK,
     "red": curses.COLOR_RED,
     "green": curses.COLOR_GREEN,
     "yellow": curses.COLOR_YELLOW,
     "blue": curses.COLOR_BLUE,
     "magenta": curses.COLOR_MAGENTA,
-    "cyan": curses.COLOR_CYAN,
-    "white": curses.COLOR_WHITE,
 }
 
 _COLOR_NONE = "(none)"
@@ -248,11 +243,15 @@ _COLOR_NONE = "(none)"
 def name_color_modal(
     default_label: str,
     *,
+    disclaimer: str = "",
     tty_path: str = "/dev/tty",
 ) -> tuple[str, str]:
     """Present a two-step curses modal: first edit the agent label,
     then optionally pick a color.
 
+    ``disclaimer`` is shown below the input field — use it to surface
+    an error from a previous attempt (e.g. name already in use).
+
     Returns ``(label, color)`` where ``color`` is one of the 16 ANSI
     color name strings or ``""`` for no color. Falls back to
     ``(default_label, "")`` on any error (terminal too small, not a tty).
@@ -264,14 +263,14 @@ def name_color_modal(
 
     try:
         fd_dup = os.dup(tty_fd.fileno())
-        return _run_name_color(default_label, tty_fd=fd_dup)
+        return _run_name_color(default_label, tty_fd=fd_dup, disclaimer=disclaimer)
     except Exception:  # noqa: BLE001  # pylint: disable=broad-exception-caught
         return default_label, ""
     finally:
         tty_fd.close()
 
 
-def _run_name_color(default_label: str, *, tty_fd: int) -> tuple[str, str]:
+def _run_name_color(default_label: str, *, tty_fd: int, disclaimer: str = "") -> tuple[str, str]:
     import io
     orig_stdin = sys.__stdin__
     orig_stdout = sys.__stdout__
@@ -286,7 +285,7 @@ def _run_name_color(default_label: str, *, tty_fd: int) -> tuple[str, str]:
         curses.cbreak()
         screen.keypad(True)
         try:
-            label = _label_step(screen, default_label)
+            label = _label_step(screen, default_label, disclaimer=disclaimer)
             color = _color_step(screen, label)
         finally:
             screen.keypad(False)
@@ -299,14 +298,14 @@ def _run_name_color(default_label: str, *, tty_fd: int) -> tuple[str, str]:
     return label, color
 
 
-def _label_step(screen: Any, default_label: str) -> str:
+def _label_step(screen: Any, default_label: str, *, disclaimer: str = "") -> str:
     """Step 1: edit the label. First printable key replaces the
     pre-fill; subsequent keys append. Enter confirms."""
     text = default_label
     replaced = False  # True once the user has typed their first char
 
     while True:
-        _render_label(screen, text)
+        _render_label(screen, text, disclaimer=disclaimer)
         try:
             key = screen.getch()
         except KeyboardInterrupt:
@@ -330,7 +329,7 @@ def _label_step(screen: Any, default_label: str) -> str:
                 text += chr(key)
 
 
-def _render_label(screen: Any, text: str) -> None:
+def _render_label(screen: Any, text: str, *, disclaimer: str = "") -> None:
     screen.erase()
     rows, cols = screen.getmaxyx()
     sep = "─" * min(cols - 1, 40)
@@ -338,8 +337,12 @@ def _render_label(screen: Any, text: str) -> None:
     _addstr_safe(screen, 1, 0, sep)
     _addstr_safe(screen, 2, 0, text[:cols - 1], curses.A_REVERSE)
     _addstr_safe(screen, 3, 0, sep)
-    if rows > 5:
-        _addstr_safe(screen, 5, 0, "[any key] edit  [Enter] confirm", curses.A_DIM)
+    row = 4
+    if disclaimer and rows > row + 1:
+        _addstr_safe(screen, row, 0, disclaimer[:cols - 1], curses.A_BOLD)
+        row += 1
+    if rows > row + 1:
+        _addstr_safe(screen, row, 0, "[any key] edit  [Enter] confirm", curses.A_DIM)
     screen.refresh()
 
 
@@ -379,13 +382,10 @@ def _init_color_pairs() -> dict[str, int]:
         curses.use_default_colors()
         pair_idx = 2  # pair 1 reserved for other uses
         for name in _ANSI_COLORS:
-            base = name.replace("bright-", "")
-            fg = _CURSES_COLOR_MAP.get(base, curses.COLOR_WHITE)
+            fg = _CURSES_COLOR_MAP.get(name, curses.COLOR_WHITE)
             try:
                 curses.init_pair(pair_idx, fg, -1)
-                attr = curses.color_pair(pair_idx)
-                if name.startswith("bright-"):
-                    attr |= curses.A_BOLD
+                attr = curses.color_pair(pair_idx) | curses.A_BOLD
                 attrs[name] = attr
                 pair_idx += 1
             except curses.error:

bot_bottle/contrib/claude/agent_provider.py

@@ -42,41 +42,19 @@ def _prompt_path(guest_home: str) -> str:
 
 
 _STATUS_LINE_COLORS = {
-    "black": "\033[30m",
-    "red": "\033[31m",
-    "green": "\033[32m",
-    "yellow": "\033[33m",
-    "blue": "\033[34m",
-    "magenta": "\033[35m",
-    "cyan": "\033[36m",
-    "white": "\033[37m",
-    "bright-black": "\033[90m",
-    "bright-red": "\033[91m",
-    "bright-green": "\033[92m",
-    "bright-yellow": "\033[93m",
-    "bright-blue": "\033[94m",
-    "bright-magenta": "\033[95m",
-    "bright-cyan": "\033[96m",
-    "bright-white": "\033[97m",
+    "red": "\033[91m",
+    "green": "\033[92m",
+    "yellow": "\033[93m",
+    "blue": "\033[94m",
+    "magenta": "\033[95m",
 }
 
 _CLAUDE_THEME_COLORS = {
-    "black": "black",
-    "red": "red",
-    "green": "green",
-    "yellow": "yellow",
-    "blue": "blue",
-    "magenta": "magenta",
-    "cyan": "cyan",
-    "white": "white",
-    "bright-black": "blackBright",
-    "bright-red": "redBright",
-    "bright-green": "greenBright",
-    "bright-yellow": "yellowBright",
-    "bright-blue": "blueBright",
-    "bright-magenta": "magentaBright",
-    "bright-cyan": "cyanBright",
-    "bright-white": "whiteBright",
+    "red": "redBright",
+    "green": "greenBright",
+    "yellow": "yellowBright",
+    "blue": "blueBright",
+    "magenta": "magentaBright",
 }
 
 

bot_bottle/manifest.py

@@ -193,6 +193,10 @@ class ManifestBottle:
 class Manifest:
     bottles: Mapping[str, ManifestBottle]
     agents: Mapping[str, ManifestAgent]
+    # Set by from_md_dirs; empty in from_json_obj (test/programmatic) mode.
+    # Stores the manifest root dirs so load_for_agent can locate files later.
+    home_md: Path | None = field(default=None)
+    cwd_md: Path | None = field(default=None)
 
     @classmethod
     def resolve(cls, cwd: str, *, missing_ok: bool = False) -> "Manifest":
@@ -249,24 +253,15 @@ class Manifest:
         home_dir: Path,
         cwd_dir: Path | None,
     ) -> "Manifest":
-        """Programmatic entry point. Loads bottles from
-        `<home_dir>/bottles/`, home agents from `<home_dir>/agents/`,
-        and (if `cwd_dir` is passed) cwd agents from
-        `<cwd_dir>/agents/`. Cwd agents override home agents on
-        name collision. A `bottles/` subdir under `cwd_dir` is
-        logged as a warning and ignored.
+        """Return a names-only Manifest. No file content is read; only
+        filenames are scanned for the agent selector.  Full parsing happens
+        later, per-agent, via `load_for_agent`.
+
+        A `bottles/` subdir under `cwd_dir` is logged as a warning and
+        ignored — the filesystem layout IS the trust boundary.
 
         Used by tests to build a Manifest from fixture directories
         without touching `os.environ`."""
-        bottles_dir = home_dir / "bottles"
-        from .manifest_loader import load_agents_from_dir, load_bottles_from_dir
-
-        bottles = load_bottles_from_dir(bottles_dir)
-
-        bottle_names = set(bottles.keys())
-        agents_dir = home_dir / "agents"
-        agents = load_agents_from_dir(agents_dir, bottle_names, source="$HOME")
-
         if cwd_dir is not None:
             stale_bottles = cwd_dir / "bottles"
             if stale_bottles.is_dir():
@@ -280,13 +275,7 @@ class Manifest:
                         f"live under $HOME/.bot-bottle/bottles/ "
                         f"(PRD 0011). Move them or delete."
                     )
-            cwd_agents_dir = cwd_dir / "agents"
-            cwd_agents = load_agents_from_dir(
-                cwd_agents_dir, bottle_names, source="$CWD"
-            )
-            agents = {**agents, **cwd_agents}
-
-        return cls(bottles=bottles, agents=agents)
+        return cls(bottles={}, agents={}, home_md=home_dir, cwd_md=cwd_dir)
 
     @classmethod
     def from_json_obj(cls, obj: object) -> "Manifest":
@@ -311,18 +300,113 @@ class Manifest:
         }
         return cls(bottles=bottles, agents=agents)
 
+    @property
+    def all_agent_names(self) -> list[str]:
+        """Sorted list of all discoverable agent names.
+
+        In names-only mode (from resolve/from_md_dirs) this scans agent
+        filenames without reading their content. In eager mode (from
+        from_json_obj) it returns the pre-parsed agents' names."""
+        if self.home_md is not None:
+            from .manifest_loader import scan_agent_names
+            home_names = set(scan_agent_names(self.home_md / "agents").keys())
+            cwd_names: set[str] = set()
+            if self.cwd_md is not None:
+                cwd_names = set(scan_agent_names(self.cwd_md / "agents").keys())
+            return sorted(home_names | cwd_names)
+        return sorted(self.agents.keys())
+
+    def load_for_agent(self, agent_name: str) -> "Manifest":
+        """Parse and return a full Manifest for `agent_name` and its bottle.
+
+        Only the selected agent's file and the bottle files in its extends
+        chain are read. Raises ManifestError if the agent or bottle is
+        invalid. Must be called on a names-only manifest (from resolve).
+        Backends call this at preflight to upgrade the spec's manifest."""
+        if self.home_md is None:
+            # Eager manifest (from_json_obj): already fully loaded; just validate name.
+            if agent_name not in self.agents:
+                available = ", ".join(sorted(self.agents.keys())) or "(none)"
+                raise ManifestError(
+                    f"agent '{agent_name}' not defined. Available: {available}"
+                )
+            return self
+        from .manifest_loader import load_bottle_chain_from_dir, scan_agent_names
+        from .manifest_schema import validate_agent_frontmatter_keys
+        from .yaml_subset import YamlSubsetError, parse_frontmatter
+
+        # Locate the agent file; cwd wins over home on name collision.
+        home_agents = scan_agent_names(self.home_md / "agents")
+        cwd_agents: dict[str, Path] = {}
+        if self.cwd_md is not None:
+            cwd_agents = scan_agent_names(self.cwd_md / "agents")
+        merged = {**home_agents, **cwd_agents}
+
+        if agent_name not in merged:
+            available = ", ".join(sorted(merged.keys())) or "(none)"
+            raise ManifestError(
+                f"agent '{agent_name}' not defined. Available: {available}"
+            )
+
+        agent_path = merged[agent_name]
+        try:
+            fm, body = parse_frontmatter(agent_path.read_text())
+        except OSError as e:
+            raise ManifestError(f"could not read {agent_path}: {e}") from e
+        except YamlSubsetError as e:
+            raise ManifestError(f"{agent_path}: {e}") from e
+
+        validate_agent_frontmatter_keys(agent_path, fm.keys())
+
+        bottle_name = fm.get("bottle")
+        if not isinstance(bottle_name, str) or not bottle_name:
+            raise ManifestError(
+                f"agent '{agent_name}' must declare a 'bottle' field "
+                f"naming a defined bottle"
+            )
+
+        # Load the bottle chain (may raise ManifestError).
+        bottles_dir = self.home_md / "bottles"
+        bottle = load_bottle_chain_from_dir(bottle_name, bottles_dir)
+
+        # Build and validate the full ManifestAgent.
+        agent_dict: dict[str, object] = {
+            "bottle": bottle_name,
+            "skills": fm.get("skills", []),
+            "prompt": body.strip(),
+        }
+        if "git-gate" in fm:
+            agent_dict["git-gate"] = fm["git-gate"]
+        agent = ManifestAgent.from_dict(agent_name, agent_dict, {bottle_name})
+
+        return Manifest(
+            bottles={bottle_name: bottle},
+            agents={agent_name: agent},
+            home_md=self.home_md,
+            cwd_md=self.cwd_md,
+        )
+
     def has_agent(self, name: str) -> bool:
         return name in self.agents
 
     def require_agent(self, name: str) -> None:
+        """Check that `name` is a discoverable agent. In names-only mode
+        this checks whether the .md file exists; in eager mode it checks
+        the pre-parsed agents dict. Does NOT parse file content."""
         if self.has_agent(name):
             return
-        available = ", ".join(self.agents.keys())
-        if available:
-            msg = f"agent '{name}' not defined in bot-bottle.json. Available: {available}"
-            raise ManifestError(msg)
+        if self.home_md is not None:
+            # Names-only mode: check file existence without parsing.
+            home_path = self.home_md / "agents" / f"{name}.md"
+            cwd_path = (
+                self.cwd_md / "agents" / f"{name}.md"
+                if self.cwd_md else None
+            )
+            if home_path.is_file() or (cwd_path and cwd_path.is_file()):
+                return
+        available = ", ".join(self.all_agent_names) or "(none)"
         raise ManifestError(
-            f"agent '{name}' not defined in bot-bottle.json (manifest is empty)."
+            f"agent '{name}' not defined. Available: {available}"
         )
 
     def has_bottle(self, name: str) -> bool:
@@ -356,8 +440,7 @@ class Manifest:
 
     def bottle_for(self, agent_name: str) -> ManifestBottle:
         """Resolve the Bottle the named agent references, with the
-        agent's git.user overlaid on top. The validator guarantees both
-        lookups succeed for a manifest built via from_json_obj.
+        agent's git.user overlaid on top.
 
         The overlay lives here, the single point both backends call to
         resolve an agent's bottle, so the docker / smolmachines git

bot_bottle/manifest_extends.py

@@ -5,16 +5,20 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from .manifest import ManifestBottle, ManifestGitEntry
+    from .manifest import ManifestBottle
     from .manifest_egress import ManifestEgressConfig
 
 
 def resolve_bottles(raws: dict[str, dict[str, object]]) -> dict[str, ManifestBottle]:
     """Apply `extends:` chains and return resolved ManifestBottle objects."""
     cache: dict[str, ManifestBottle] = {}
+    # Per-bottle effective git-gate.repos, as raw dicts keyed by repo name.
+    # Threaded alongside `cache` so a child can field-merge against its
+    # parent's repos without reconstructing them from parsed entries.
+    repos_cache: dict[str, dict[str, object]] = {}
     for name in raws:
         if name not in cache:
-            _resolve_one_bottle(name, raws, cache, ())
+            _resolve_one_bottle(name, raws, cache, repos_cache, ())
     return cache
 
 
@@ -22,6 +26,7 @@ def _resolve_one_bottle(
     name: str,
     raws: dict[str, dict[str, object]],
     cache: dict[str, ManifestBottle],
+    repos_cache: dict[str, dict[str, object]],
     seen: tuple[str, ...],
 ) -> ManifestBottle:
     from .manifest import ManifestBottle, ManifestError
@@ -41,6 +46,7 @@ def _resolve_one_bottle(
     if parent_name_raw is None:
         bottle = ManifestBottle.from_dict(name, child_raw)
         cache[name] = bottle
+        repos_cache[name] = _resolve_repos_raw({}, child_raw)
         return bottle
 
     if not isinstance(parent_name_raw, str):
@@ -60,20 +66,33 @@ def _resolve_one_bottle(
             f"bottle '{name}' extends '{parent_name}' which is not "
             f"defined. Available bottles: {avail}"
         )
-    parent = _resolve_one_bottle(parent_name, raws, cache, seen + (name,))
-    bottle = _merge_bottles(parent, child_raw, name)
+    parent = _resolve_one_bottle(
+        parent_name, raws, cache, repos_cache, seen + (name,)
+    )
+    merged_repos_raw = _resolve_repos_raw(repos_cache[parent_name], child_raw)
+    bottle = _merge_bottles(parent, child_raw, merged_repos_raw, name)
     cache[name] = bottle
+    repos_cache[name] = merged_repos_raw
     return bottle
 
 
 def _merge_bottles(
     parent: ManifestBottle,
     child_raw: dict[str, object],
+    merged_repos_raw: dict[str, object],
     name: str,
 ) -> ManifestBottle:
     """Apply PRD 0025 merge rules."""
     from .manifest import ManifestBottle, ManifestGitUser
     from .manifest_egress import validate_egress_routes
+    from .manifest_util import as_json_object
+
+    # git-gate.repos: when the child declares repos, inject the already
+    # name-merged repo set (computed by _resolve_repos_raw) so the child
+    # parses with the full inherited+overridden list (issue #237).
+    if _child_declares_git_gate_repos(child_raw):
+        git_raw = as_json_object(child_raw.get("git-gate", {}), "child git-gate")
+        child_raw = {**child_raw, "git-gate": {**git_raw, "repos": merged_repos_raw}}
 
     # Parse the child's declared fields into a ManifestBottle (with the
     # usual defaults for anything missing). Validation runs the same
@@ -92,11 +111,11 @@ def _merge_bottles(
         email=child.git_user.email or parent.git_user.email,
     )
 
-    # git-gate.repos: missing means inherit; an explicit empty object
-    # clears; otherwise parent and child merge by UpstreamHost with
-    # child entries replacing duplicate hosts.
+    # git-gate.repos: when declared, child.git already holds the merged
+    # set (an explicit empty dict clears parent, leaving child.git empty).
+    # When omitted, the parent's entries are inherited verbatim.
     if _child_declares_git_gate_repos(child_raw):
-        merged_git = _merge_git_remotes(parent.git, child.git) if child.git else ()
+        merged_git = child.git
     else:
         merged_git = parent.git
 
@@ -130,6 +149,45 @@ def _merge_bottles(
     )
 
 
+def _resolve_repos_raw(
+    parent_repos: dict[str, object],
+    child_raw: dict[str, object],
+) -> dict[str, object]:
+    """Compute a bottle's effective git-gate.repos as raw dicts.
+
+    Repos are keyed by name. When the child omits git-gate.repos it
+    inherits the parent's set verbatim; an explicit empty dict clears it.
+    Otherwise parent and child unite by name, with same-name entries
+    field-merged (parent fields are defaults, child fields win)."""
+    from .manifest_util import as_json_object
+
+    if not _child_declares_git_gate_repos(child_raw):
+        return parent_repos
+    child_repos = _declared_repos_raw(child_raw)
+    if not child_repos:
+        return {}
+    # Parent entries keep their order; child-only names are appended.
+    names = list(parent_repos) + [n for n in child_repos if n not in parent_repos]
+    return {
+        name: {
+            **as_json_object(parent_repos.get(name, {}), "parent git-gate repo"),
+            **as_json_object(child_repos.get(name, {}), "child git-gate repo"),
+        }
+        for name in names
+    }
+
+
+def _declared_repos_raw(child_raw: dict[str, object]) -> dict[str, object]:
+    """Return the child's explicitly declared git-gate.repos as raw dicts,
+    or an empty dict when none are declared."""
+    from .manifest_util import as_json_object
+
+    if not _child_declares_git_gate_repos(child_raw):
+        return {}
+    git_raw = as_json_object(child_raw.get("git-gate", {}), "child git-gate")
+    return as_json_object(git_raw.get("repos", {}), "child git-gate.repos")
+
+
 def _child_declares_git_gate_repos(child_raw: dict[str, object]) -> bool:
     from .manifest_util import as_json_object
 
@@ -140,16 +198,6 @@ def _child_declares_git_gate_repos(child_raw: dict[str, object]) -> bool:
     return "repos" in git_obj
 
 
-def _merge_git_remotes(
-    parent: tuple[ManifestGitEntry, ...],
-    child: tuple[ManifestGitEntry, ...],
-) -> tuple[ManifestGitEntry, ...]:
-    by_host = {entry.UpstreamHost: entry for entry in parent}
-    for entry in child:
-        by_host[entry.UpstreamHost] = entry
-    return tuple(by_host.values())
-
-
 def _merge_egress(
     parent: ManifestEgressConfig,
     child: ManifestEgressConfig,

bot_bottle/manifest_loader.py

@@ -8,21 +8,19 @@ from typing import TYPE_CHECKING
 from .log import warn
 from .manifest_schema import (
     entity_name_from_path,
-    validate_agent_frontmatter_keys,
     validate_bottle_frontmatter_keys,
 )
+from .manifest_util import ManifestError
 from .yaml_subset import YamlSubsetError, parse_frontmatter
 
 if TYPE_CHECKING:
-    from .manifest import ManifestAgent, ManifestBottle
+    from .manifest import ManifestBottle
 
 
 def check_stale_json(dir_path: Path, md_dir: Path, label: str) -> None:
     """Die if `<dir_path>/bot-bottle.json` exists but `md_dir` does
     not. The manifest format changed in PRD 0011 and we do not want
     to silently leave the JSON content unused."""
-    from .manifest import ManifestError
-
     legacy = dir_path / "bot-bottle.json"
     if legacy.is_file() and not md_dir.exists():
         raise ManifestError(
@@ -34,48 +32,13 @@ def check_stale_json(dir_path: Path, md_dir: Path, label: str) -> None:
         )
 
 
-def load_bottles_from_dir(bottles_dir: Path) -> dict[str, ManifestBottle]:
-    """Walk `<bottles_dir>/*.md`, parse each as a bottle, and return
-    `{name: Bottle}`. Missing dir returns an empty dict."""
-    from .manifest import ManifestError
-    from .manifest_extends import resolve_bottles
+def scan_agent_names(agents_dir: Path) -> dict[str, Path]:
+    """Scan `<agents_dir>/*.md` for valid filenames and return `{name: path}`.
 
-    raws: dict[str, dict[str, object]] = {}
-    if not bottles_dir.is_dir():
-        return {}
-    for path in sorted(bottles_dir.glob("*.md")):
-        name = entity_name_from_path(path)
-        if name is None:
-            warn(
-                f"skipping {path}: filename must match "
-                f"[a-z][a-z0-9-]*.md (got {path.name!r})"
-            )
-            continue
-        try:
-            fm, _body = parse_frontmatter(path.read_text())
-        except OSError as e:
-            raise ManifestError(f"could not read {path}: {e}") from e
-        except YamlSubsetError as e:
-            raise ManifestError(f"{path}: {e}") from e
-        validate_bottle_frontmatter_keys(path, fm.keys())
-        raws[name] = fm
-    return resolve_bottles(raws)
-
-
-def load_agents_from_dir(
-    agents_dir: Path,
-    bottle_names: set[str],
-    *,
-    source: str,  # noqa: F841 — unused, but required by interface
-) -> dict[str, ManifestAgent]:
-    """Walk `<agents_dir>/*.md`, parse each as an agent, and return
-    `{name: Agent}`. The Markdown body becomes the agent's prompt.
-    Missing dir returns an empty dict."""
-    from .manifest import ManifestAgent, ManifestError
-
-    out: dict[str, ManifestAgent] = {}
+    No file content is read. Invalid filenames are skipped with a warning."""
+    result: dict[str, Path] = {}
     if not agents_dir.is_dir():
-        return out
+        return result
     for path in sorted(agents_dir.glob("*.md")):
         name = entity_name_from_path(path)
         if name is None:
@@ -84,22 +47,45 @@ def load_agents_from_dir(
                 f"[a-z][a-z0-9-]*.md (got {path.name!r})"
             )
             continue
+        result[name] = path
+    return result
+
+
+def load_bottle_chain_from_dir(
+    bottle_name: str, bottles_dir: Path
+) -> ManifestBottle:
+    """Load `bottle_name` and its full `extends:` chain from `bottles_dir`,
+    returning the resolved ManifestBottle.
+
+    Only the files in the extends chain are read — unrelated bottle files
+    are never touched. Raises ManifestError on parse or validation failure."""
+    from .manifest_extends import resolve_bottles
+
+    raws: dict[str, dict[str, object]] = {}
+    to_load = [bottle_name]
+    while to_load:
+        name = to_load.pop()
+        if name in raws:
+            continue
+        path = bottles_dir / f"{name}.md"
+        if not path.is_file():
+            avail = ", ".join(
+                p.stem for p in sorted(bottles_dir.glob("*.md")) if p.is_file()
+            ) or "(none)"
+            raise ManifestError(
+                f"bottle '{name}' not found at {path}. "
+                f"Available: {avail}"
+            )
         try:
-            fm, body = parse_frontmatter(path.read_text())
+            fm, _body = parse_frontmatter(path.read_text())
         except OSError as e:
             raise ManifestError(f"could not read {path}: {e}") from e
         except YamlSubsetError as e:
             raise ManifestError(f"{path}: {e}") from e
-        validate_agent_frontmatter_keys(path, fm.keys())
-        # Build the dict Agent.from_dict expects. The body becomes
-        # prompt; Claude Code passthrough fields stay in fm and get
-        # ignored by Agent.from_dict (reads bottle/skills/git-gate/prompt).
-        agent_dict: dict[str, object] = {
-            "bottle": fm.get("bottle"),
-            "skills": fm.get("skills", []),
-            "prompt": body.strip(),
-        }
-        if "git-gate" in fm:
-            agent_dict["git-gate"] = fm["git-gate"]
-        out[name] = ManifestAgent.from_dict(name, agent_dict, bottle_names)
-    return out
+        validate_bottle_frontmatter_keys(path, fm.keys())
+        raws[name] = dict(fm)
+        parent = fm.get("extends")
+        if isinstance(parent, str):
+            to_load.append(parent)
+
+    return resolve_bottles(raws)[bottle_name]

tests/integration/test_sandbox_escape.py

@@ -92,10 +92,9 @@ class TestSandboxEscape(unittest.TestCase):
                     "on PATH: curl -sSL https://smolmachines.com/install.sh | sh"
                 )
 
-        # Throwaway "identity file" so the manifest's _validate_git_entries
-        # passes (it only checks `os.path.isfile`, not that the content is
-        # a real SSH key). Test 5 reaches gitleaks before any SSH attempt
-        # anyway.
+        # Throwaway "identity file" for the git-gate's `identity` field.
+        # It need not be a real SSH key: test 5 reaches gitleaks before
+        # any SSH attempt anyway.
         fd, kp = tempfile.mkstemp(prefix="sandbox-test-key.")
         os.close(fd)
         cls._key_path = Path(kp)

tests/unit/test_agent_provider.py

@@ -74,7 +74,7 @@ class TestAgentProviderRuntime(unittest.TestCase):
                 instance_name="bot-bottle-test",
                 prompt_file=prompt_file,
                 label="review-api",
-                color="bright-cyan",
+                color="cyan",
             )
             prompt = prompt_file.read_text()
             config = Path(tmp, "codex-config.toml").read_text()

tests/unit/test_backend_prepare.py

@@ -16,6 +16,7 @@ from bot_bottle import bottle_state
 from bot_bottle import supervise
 from bot_bottle.backend import BottleSpec
 from bot_bottle.backend.docker import DockerBottleBackend
+from bot_bottle.backend.resolve_common import mint_slug
 from bot_bottle.backend.smolmachines import SmolmachinesBottleBackend
 from bot_bottle.manifest import Manifest
 
@@ -115,5 +116,36 @@ class TestSmolmachinesPrepare(_FakeStateMixin, unittest.TestCase):
         )
 
 
+class TestMintSlug(unittest.TestCase):
+    def _spec(self, *, label: str = "", identity: str = "") -> BottleSpec:
+        manifest = _manifest()
+        return BottleSpec(
+            manifest=manifest,
+            agent_name="demo",
+            copy_cwd=False,
+            user_cwd="/tmp",
+            label=label,
+            identity=identity,
+        )
+
+    def test_no_label_uses_agent_name_with_random_suffix(self) -> None:
+        slug = mint_slug(self._spec(label=""))
+        self.assertTrue(slug.startswith("demo-"), slug)
+        # random suffix present — slug is longer than just "demo"
+        self.assertGreater(len(slug), len("demo-"))
+
+    def test_label_becomes_exact_slug(self) -> None:
+        slug = mint_slug(self._spec(label="my-run"))
+        self.assertEqual("my-run", slug)
+
+    def test_label_with_spaces_slugified_no_suffix(self) -> None:
+        slug = mint_slug(self._spec(label="My Feature Run"))
+        self.assertEqual("my-feature-run", slug)
+
+    def test_identity_takes_precedence_over_label(self) -> None:
+        slug = mint_slug(self._spec(label="my-run", identity="fixed-id"))
+        self.assertEqual("fixed-id", slug)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_backend_terminal.py

@@ -11,14 +11,14 @@ class TestPalettePrintf(unittest.TestCase):
     def test_known_color_returns_printf(self):
         cmd = palette_printf("red")
         self.assertTrue(cmd.startswith("printf '"))
-        self.assertIn("\\033]4;1;", cmd)   # normal red
-        self.assertIn("\\033]4;9;", cmd)   # bright red
+        self.assertIn("\\033]4;9;", cmd)   # bright-red slot
+        self.assertIn("\\033]4;1;", cmd)   # normal-red slot
         self.assertIn("\\033]11;", cmd)    # default background tint
 
-    def test_bright_variant_sets_both_slots(self):
-        cmd = palette_printf("bright-blue")
-        self.assertIn("\\033]4;12;", cmd)  # bright-blue
-        self.assertIn("\\033]4;4;", cmd)   # blue
+    def test_color_sets_both_palette_slots(self):
+        cmd = palette_printf("blue")
+        self.assertIn("\\033]4;12;", cmd)  # bright-blue slot
+        self.assertIn("\\033]4;4;", cmd)   # normal-blue slot
 
     def test_unknown_color_returns_empty(self):
         self.assertEqual("", palette_printf(""))
@@ -26,10 +26,7 @@ class TestPalettePrintf(unittest.TestCase):
 
     def test_all_named_colors_produce_output(self):
         colors = [
-            "black", "red", "green", "yellow",
-            "blue", "magenta", "cyan", "white",
-            "bright-black", "bright-red", "bright-green", "bright-yellow",
-            "bright-blue", "bright-magenta", "bright-cyan", "bright-white",
+            "red", "green", "yellow", "blue", "magenta",
         ]
         for color in colors:
             with self.subTest(color=color):
@@ -65,7 +62,7 @@ class TestExecShellScript(unittest.TestCase):
         self.assertFalse(agent_part.startswith("exec "))
 
     def test_title_and_color_both_appear(self):
-        script = exec_shell_script(self._ARGV, terminal_title="bot", terminal_color="cyan")
+        script = exec_shell_script(self._ARGV, terminal_title="bot", terminal_color="magenta")
         assert script is not None
         self.assertIn("bot", script)
         self.assertIn("\\033]4;", script)

tests/unit/test_cli_start_selector.py

@@ -14,11 +14,13 @@ from unittest.mock import MagicMock, patch
 
 import bot_bottle.cli.start as start_mod
 import bot_bottle.cli.tui as tui_mod
+from bot_bottle.backend import ActiveAgent
 
 
 def _make_manifest(agent_names: list[str]):
     manifest = MagicMock()
     manifest.agents = {name: MagicMock() for name in agent_names}
+    manifest.all_agent_names = sorted(agent_names)
     return manifest
 
 
@@ -133,5 +135,63 @@ class TestCmdStartSelector(unittest.TestCase):
         self._launch_mock.assert_not_called()
 
 
+def _active_agent(slug: str) -> ActiveAgent:
+    return ActiveAgent(
+        backend_name="docker",
+        slug=slug,
+        agent_name="demo",
+        started_at="2026-01-01T00:00:00+00:00",
+        services=(),
+    )
+
+
+class TestCmdStartLabelCollision(unittest.TestCase):
+    """cmd_start re-prompts when the label's slug is already running."""
+
+    def setUp(self):
+        self._manifest = _make_manifest(["researcher"])
+        patch("bot_bottle.cli.start.Manifest.resolve", return_value=self._manifest).start()
+        self._launch_mock = patch(
+            "bot_bottle.cli.start._launch_bottle", return_value=0,
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def test_no_collision_proceeds_without_reprompt(self):
+        with (
+            patch.object(tui_mod, "name_color_modal", return_value=("researcher", "")) as modal,
+            patch("bot_bottle.cli.start.enumerate_active_agents", return_value=[]),
+        ):
+            rc = start_mod.cmd_start(["researcher"])
+        self.assertEqual(0, rc)
+        modal.assert_called_once()
+        self._launch_mock.assert_called_once()
+
+    def test_collision_reprompts_with_disclaimer(self):
+        collision_agent = _active_agent("researcher")
+        call_count = 0
+
+        def _modal(default_label: str, *, disclaimer: str = "", **_kw: object) -> tuple[str, str]:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return "researcher", ""
+            return "researcher-2", ""
+
+        with (
+            patch.object(tui_mod, "name_color_modal", side_effect=_modal) as modal,
+            patch(
+                "bot_bottle.cli.start.enumerate_active_agents",
+                side_effect=[[collision_agent], []],
+            ),
+        ):
+            rc = start_mod.cmd_start(["researcher"])
+
+        self.assertEqual(0, rc)
+        self.assertEqual(2, modal.call_count)
+        second_call_kwargs = modal.call_args_list[1][1]
+        self.assertIn("researcher", second_call_kwargs.get("disclaimer", ""))
+        self.assertIn("already in use", second_call_kwargs.get("disclaimer", ""))
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_contrib_claude_provider.py

@@ -276,7 +276,7 @@ class TestClaudeUiProvision(unittest.TestCase):
                 instance_name="bot-bottle-demo-abc12",
                 prompt_file=prompt_file,
                 label="research-ui",
-                color="bright-cyan",
+                color="blue",
             )
             settings = json.loads((state_dir / "claude-settings.json").read_text())
             statusline = (state_dir / "claude-statusline.sh").read_text()
@@ -288,9 +288,9 @@ class TestClaudeUiProvision(unittest.TestCase):
         self.assertEqual("~/.claude/statusline.sh", settings["statusLine"]["command"])
         self.assertEqual("custom:bot-bottle-research-ui", settings["theme"])
         self.assertIn("research-ui", statusline)
-        self.assertIn("\x1b[96m", statusline)
+        self.assertIn("\x1b[94m", statusline)
         self.assertEqual("dark", theme["base"])
-        self.assertEqual("ansi:cyanBright", theme["overrides"]["claude"])
+        self.assertEqual("ansi:blueBright", theme["overrides"]["claude"])
 
     def test_runs_verify_commands(self):
         provision = AgentProvisionPlan(

tests/unit/test_contrib_codex_provider.py

@@ -158,7 +158,7 @@ class TestCodexProvisionPrompt(unittest.TestCase):
                 instance_name="bot-bottle-demo-abc12",
                 prompt_file=prompt_file,
                 label="research-ui",
-                color="bright-cyan",
+                color="cyan",
             )
             config = (state_dir / "codex-config.toml").read_text()
             prompt_text = prompt_file.read_text()

tests/unit/test_manifest_agent_git_user.py

@@ -217,7 +217,7 @@ class TestAgentGitUserMdLoader(unittest.TestCase):
     def test_md_agent_git_user_overlays_bottle(self):
         self._write("bottles/dev.md", _BOTTLE_DEV)
         self._write("agents/impl.md", _AGENT_WITH_GIT)
-        m = Manifest.resolve(str(self.home))
+        m = Manifest.resolve(str(self.home)).load_for_agent("impl")
         u = m.bottle_for("impl").git_user
         self.assertEqual("agent-name", u.name)
         self.assertEqual("bottle@example.com", u.email)
@@ -226,10 +226,17 @@ class TestAgentGitUserMdLoader(unittest.TestCase):
             m.git_identity_summary("impl"),
         )
 
-    def test_md_agent_repos_dies(self):
+    def test_md_agent_repos_fails_at_preflight(self):
+        """git-gate.repos on an agent is an error; resolve() still succeeds
+        so other agents remain accessible, but load_for_agent raises."""
         self._write("bottles/dev.md", _BOTTLE_DEV)
         self._write("agents/impl.md", _AGENT_WITH_REPOS)
-        msg = _error_message(Manifest.resolve, str(self.home))
+        from bot_bottle.manifest import ManifestError
+        names = Manifest.resolve(str(self.home))
+        self.assertIn("impl", names.all_agent_names)
+        with self.assertRaises(ManifestError) as ctx:
+            names.load_for_agent("impl")
+        msg = str(ctx.exception)
         self.assertIn("git-gate.repos", msg)
         self.assertIn("bottle-only", msg)
 

tests/unit/test_manifest_extends.py

@@ -113,8 +113,8 @@ class TestExtendsEnvMerge(unittest.TestCase):
 
 
 class TestExtendsGitMerge(unittest.TestCase):
-    """git-gate.user overlays by field; git-gate.repos merges by upstream
-    host, with child entries replacing duplicate hosts."""
+    """git-gate.user overlays by field; git-gate.repos merges by name,
+    with same-name child entries merging field-by-field (child wins)."""
 
     _GIT_ENTRY_A = {"url": "ssh://git@host-a/a.git", "key": {"provider": "static", "path": "/dev/null"}}
     _GIT_ENTRY_B = {"url": "ssh://git@host-b/b.git", "key": {"provider": "static", "path": "/dev/null"}}
@@ -130,19 +130,21 @@ class TestExtendsGitMerge(unittest.TestCase):
         names = [e.Name for e in m.bottles["child"].git]
         self.assertEqual(["a", "b"], names)
 
-    def test_child_git_repo_replaces_same_host(self):
-        replacement = {"url": "ssh://git@host-a/replacement.git", "key": {"provider": "static", "path": "/dev/null"}}
+    def test_child_git_repo_different_name_same_host_coexists(self):
+        # Repos are keyed by Name, not UpstreamHost: two repos with
+        # different names on the same host both survive the merge.
+        same_host_b = {"url": "ssh://git@host-a/b.git", "key": {"provider": "static", "path": "/dev/null"}}
         m = _build(
             base={"git-gate": {"repos": {"a": self._GIT_ENTRY_A}}},
             child={
                 "extends": "base",
-                "git-gate": {"repos": {"a2": replacement}},
+                "git-gate": {"repos": {"a2": same_host_b}},
             },
         )
         entries = m.bottles["child"].git
-        self.assertEqual(1, len(entries))
-        self.assertEqual("a2", entries[0].Name)
-        self.assertEqual("replacement.git", entries[0].UpstreamPath)
+        self.assertEqual(2, len(entries))
+        names = {e.Name for e in entries}
+        self.assertEqual({"a", "a2"}, names)
 
     def test_child_omits_git_gate_inherits_full_list(self):
         m = _build(
@@ -164,6 +166,77 @@ class TestExtendsGitMerge(unittest.TestCase):
         )
         self.assertEqual((), m.bottles["child"].git)
 
+    def test_child_same_name_repo_merges_key_field(self):
+        # Issue #237: child repo with same name as parent should merge
+        # field-by-field. Child overrides only `key`; parent's url and
+        # host_key are preserved.
+        parent_entry = {
+            "url": "ssh://git@host-a/repo.git",
+            "host_key": "ecdsa-sha2-nistp256 AAAA",
+            "key": {"provider": "static", "path": "/keys/id_rsa"},
+        }
+        m = _build(
+            base={"git-gate": {"repos": {"repo": parent_entry}}},
+            child={
+                "extends": "base",
+                "git-gate": {"repos": {"repo": {
+                    "key": {"provider": "gitea", "forge_token_env": "GITEA_TOKEN"},
+                }}},
+            },
+        )
+        entries = m.bottles["child"].git
+        self.assertEqual(1, len(entries))
+        e = entries[0]
+        self.assertEqual("repo", e.Name)
+        self.assertEqual("ssh://git@host-a/repo.git", e.Upstream)
+        self.assertEqual("ecdsa-sha2-nistp256 AAAA", e.KnownHostKey)
+        self.assertEqual("gitea", e.Key.provider)
+        self.assertEqual("GITEA_TOKEN", e.Key.forge_token_env)
+
+    def test_child_same_name_repo_overrides_url(self):
+        # Child can override url on a same-name repo; other parent fields
+        # fall through.
+        parent_entry = {
+            "url": "ssh://git@host-a/old.git",
+            "key": {"provider": "static", "path": "/keys/id_rsa"},
+        }
+        m = _build(
+            base={"git-gate": {"repos": {"repo": parent_entry}}},
+            child={
+                "extends": "base",
+                "git-gate": {"repos": {"repo": {
+                    "url": "ssh://git@host-b/new.git",
+                    "key": {"provider": "static", "path": "/keys/id_rsa"},
+                }}},
+            },
+        )
+        entries = m.bottles["child"].git
+        self.assertEqual(1, len(entries))
+        self.assertEqual("ssh://git@host-b/new.git", entries[0].Upstream)
+
+    def test_child_same_name_plus_new_repo(self):
+        # Same-name repo is field-merged; a distinct new name in child
+        # is appended.
+        parent_entry = {
+            "url": "ssh://git@host-a/repo.git",
+            "key": {"provider": "static", "path": "/keys/id_rsa"},
+        }
+        m = _build(
+            base={"git-gate": {"repos": {"repo": parent_entry}}},
+            child={
+                "extends": "base",
+                "git-gate": {"repos": {
+                    "repo": {"key": {"provider": "gitea", "forge_token_env": "TOK"}},
+                    "other": self._GIT_ENTRY_B,
+                }},
+            },
+        )
+        child = m.bottles["child"]
+        names = {e.Name for e in child.git}
+        self.assertEqual({"repo", "other"}, names)
+        repo_entry = next(e for e in child.git if e.Name == "repo")
+        self.assertEqual("gitea", repo_entry.Key.provider)
+
     def test_child_git_user_inherits_parent_repos(self):
         m = _build(
             base={"git-gate": {"repos": {"a": self._GIT_ENTRY_A}}},

tests/unit/test_manifest_md_load.py

@@ -77,12 +77,12 @@ class _ResolveCase(unittest.TestCase):
 
 class TestBottleFileParses(_ResolveCase):
     """SC #1: a bottle file under $HOME/.bot-bottle/bottles/
-    parses into the expected Bottle shape."""
+    parses into the expected Bottle shape via load_for_agent."""
 
     def test_loads(self):
         _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
-        m = self.resolve()
+        m = self.resolve().load_for_agent("implementer")
         self.assertIn("dev", m.bottles)
         routes = m.bottles["dev"].egress.routes
         self.assertEqual(2, len(routes))
@@ -94,13 +94,13 @@ class TestBottleFileParses(_ResolveCase):
 
 class TestAgentFileParses(_ResolveCase):
     """SC #2: an agent file under $HOME/.bot-bottle/agents/
-    parses, the body becomes the prompt, the frontmatter fields
-    map to Agent fields."""
+    parses via load_for_agent; the body becomes the prompt, the
+    frontmatter fields map to Agent fields."""
 
     def test_loads(self):
         _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
-        m = self.resolve()
+        m = self.resolve().load_for_agent("implementer")
         a = m.agents["implementer"]
         self.assertEqual("dev", a.bottle)
         self.assertEqual(("init-prd",), a.skills)
@@ -128,7 +128,7 @@ class TestCwdAgentOverridesHome(_ResolveCase):
             CWD-OVERRIDE-PROMPT
             """,
         )
-        m = self.resolve()
+        m = self.resolve().load_for_agent("implementer")
         self.assertIn("CWD-OVERRIDE-PROMPT", m.agents["implementer"].prompt)
         # Home bottle still present
         self.assertEqual(2, len(m.bottles["dev"].egress.routes))
@@ -155,7 +155,7 @@ class TestCwdBottlesIgnored(_ResolveCase):
             ---
             """,
         )
-        m = self.resolve()
+        m = self.resolve().load_for_agent("implementer")
         # Home value wins because cwd bottles are ignored entirely.
         self.assertEqual(
             "api.anthropic.com",
@@ -215,7 +215,7 @@ class TestAgentFileDoublesAsClaudeCodeSubagent(_ResolveCase):
             Agent prompt body.
             """,
         )
-        m = self.resolve()
+        m = self.resolve().load_for_agent("implementer")
         self.assertEqual("dev", m.agents["implementer"].bottle)
         self.assertEqual(("init-prd",), m.agents["implementer"].skills)
 
@@ -228,7 +228,7 @@ class TestManifestEntryPointParity(_ResolveCase):
         _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
 
-        md_manifest = self.resolve()
+        md_manifest = self.resolve().load_for_agent("implementer")
         json_manifest = Manifest.from_json_obj({
             "bottles": {
                 "dev": {
@@ -294,34 +294,48 @@ class TestManifestEntryPointParity(_ResolveCase):
         self.assertEqual("dev", manifest.agents["implementer"].bottle)
 
 
-class TestUnknownAgentKeyDies(_ResolveCase):
-    """A typo'd / unknown frontmatter key on an agent file dies
-    rather than silently ignoring."""
+class TestBrokenAgentOnlyFailsAtPreflight(_ResolveCase):
+    """A typo'd / unknown frontmatter key on an agent file does NOT crash
+    resolve(). The agent appears in all_agent_names for the selector.
+    The error surfaces only when load_for_agent is called for that agent."""
 
-    def test_dies(self):
+    def test_resolve_succeeds_despite_broken_agent(self):
         _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(
-            self.home_cb / "agents" / "implementer.md",
+            self.home_cb / "agents" / "bad.md",
             """
             ---
             bottle: dev
             skillz: [init-prd]
             ---
-
-            ...
             """,
         )
-        with self.assertRaises(ManifestError):
-            self.resolve()
+        _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
+        m = self.resolve()
+        # Resolve itself does not raise; broken agent appears in the name list.
+        self.assertIn("bad", m.all_agent_names)
+        self.assertIn("implementer", m.all_agent_names)
 
-
-class TestUnknownBottleKeyDies(_ResolveCase):
-    """A typo'd / unknown frontmatter key on a bottle file dies
-    rather than silently ignoring."""
-
-    def test_dies(self):
+    def test_load_for_agent_raises_for_broken_agent(self):
+        _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(
-            self.home_cb / "bottles" / "dev.md",
+            self.home_cb / "agents" / "bad.md",
+            """
+            ---
+            bottle: dev
+            skillz: [init-prd]
+            ---
+            """,
+        )
+        m = self.resolve()
+        with self.assertRaises(ManifestError):
+            m.load_for_agent("bad")
+
+    def test_broken_bottle_only_fails_at_preflight(self):
+        """A broken bottle does not crash resolve; only load_for_agent for
+        an agent that references it raises. Unrelated agents still work."""
+        _write(
+            self.home_cb / "bottles" / "bad.md",
             """
             ---
             credproxy:
@@ -329,9 +343,26 @@ class TestUnknownBottleKeyDies(_ResolveCase):
             ---
             """,
         )
+        _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
+        _write(
+            self.home_cb / "agents" / "broken-agent.md",
+            """
+            ---
+            bottle: bad
+            ---
+            """,
+        )
+        m = self.resolve()
+        # Both agents appear in the name list at resolve time.
+        self.assertIn("implementer", m.all_agent_names)
+        self.assertIn("broken-agent", m.all_agent_names)
+        # Valid agent loads fine.
+        full = m.load_for_agent("implementer")
+        self.assertIn("implementer", full.agents)
+        # Broken bottle's agent raises at preflight.
         with self.assertRaises(ManifestError):
-            self.resolve()
+            m.load_for_agent("broken-agent")
 
 
 class TestStaleJsonDies(_ResolveCase):
@@ -359,11 +390,11 @@ class TestNoManifestDies(_ResolveCase):
         self.assertEqual({}, dict(m.agents))
 
 
-class TestUnknownBottleReferenceDies(_ResolveCase):
-    """An agent file naming a bottle that doesn't exist on disk
-    dies with the existing "bottle not defined" error."""
+class TestUnknownBottleReferenceFailsAtPreflight(_ResolveCase):
+    """An agent file naming a non-existent bottle appears in all_agent_names
+    at resolve time; the error only surfaces when load_for_agent is called."""
 
-    def test_dies(self):
+    def test_stray_bottle_reference_fails_at_preflight(self):
         _write(self.home_cb / "bottles" / "dev.md", _BOTTLE_DEV)
         _write(
             self.home_cb / "agents" / "stray.md",
@@ -373,8 +404,17 @@ class TestUnknownBottleReferenceDies(_ResolveCase):
             ---
             """,
         )
+        _write(self.home_cb / "agents" / "implementer.md", _AGENT_IMPL)
+        m = self.resolve()
+        # Both names visible at resolve time.
+        self.assertIn("stray", m.all_agent_names)
+        self.assertIn("implementer", m.all_agent_names)
+        # Valid agent loads fine.
+        full = m.load_for_agent("implementer")
+        self.assertIn("implementer", full.agents)
+        # Stray agent fails at preflight.
         with self.assertRaises(ManifestError):
-            self.resolve()
+            m.load_for_agent("stray")
 
 
 class TestFilenameValidation(_ResolveCase):
@@ -388,9 +428,9 @@ class TestFilenameValidation(_ResolveCase):
         # This file should be skipped — capital letters not allowed.
         _write(self.home_cb / "agents" / "BadName.md", _AGENT_IMPL)
         m = self.resolve()
-        self.assertIn("implementer", m.agents)
-        self.assertNotIn("BadName", m.agents)
-        self.assertNotIn("badname", m.agents)
+        self.assertIn("implementer", m.all_agent_names)
+        self.assertNotIn("BadName", m.all_agent_names)
+        self.assertNotIn("badname", m.all_agent_names)
 
 
 if __name__ == "__main__":