docs(prd): add PRD 0049 — named/labelled agents

Draft PRD for prompting operators for a custom label and optional
ANSI color at agent launch time, storing both in metadata.json, and
surfacing the label (in color) in the dashboard's active-agents pane.

Closes #171

docs/prds/0049-named-labelled-agents.md

@@ -0,0 +1,283 @@
+# PRD 0049: Named / Labelled Agents
+
+- **Status:** Draft
+- **Author:** didericis
+- **Created:** 2026-06-03
+- **Issue:** #171
+
+## Summary
+
+At agent launch time, prompt the operator for a short human-readable label
+(defaulting to the manifest agent key) and an optional color from the 16-color
+ANSI palette. Store both in the bottle's `metadata.json`. Display the label —
+rendered in the chosen color — in the dashboard's active-agents pane, replacing
+the bare manifest key. Inject the label and color into the in-container
+`claude.json` as `name` / `color` so Claude Code can surface them in its own
+harness when upstream support lands.
+
+## Problem
+
+The dashboard's agents pane identifies each running instance by its manifest
+agent key (e.g., `implementer`) plus a random slug suffix. When an operator
+runs three `implementer` bottles simultaneously — one each for three different
+repos — the pane shows:
+
+```
+  [docker] a3f9  implementer  started 14:02:11  [egress,pipelock]
+  [docker] b81c  implementer  started 14:03:45  [egress,pipelock]
+  [docker] d220  implementer  started 14:05:01  [egress,pipelock]
+```
+
+There is no way to tell which bottle is working on which task without attaching
+to each one in turn. The slug is opaque; the manifest key is shared. Operators
+working a multi-bottle session resort to keeping a mental map of slug→task,
+which breaks the moment they switch windows.
+
+## Goals / Success Criteria
+
+1. After the operator selects an agent name (dashboard picker or CLI argument),
+   they are prompted for a label. The prompt suggests the manifest key as the
+   default; pressing Enter (or providing no input) accepts it. The label may
+   contain any printable characters up to 64 bytes.
+2. After the label prompt, the operator is optionally prompted for a color from
+   the 16-color ANSI palette (names: `black`, `red`, `green`, `yellow`, `blue`,
+   `magenta`, `cyan`, `white`, `bright-black`, `bright-red`, `bright-green`,
+   `bright-yellow`, `bright-blue`, `bright-magenta`, `bright-cyan`,
+   `bright-white`). Pressing Enter without a selection skips color entirely.
+3. `label` and `color` are stored in `BottleMetadata` and written to the
+   bottle's `metadata.json`. Both fields default to `""` (empty / unset).
+4. `ActiveAgent` carries `label` and `color`; `enumerate_active()` reads them
+   from `metadata.json`.
+5. `_format_agent_row` uses the label when non-empty (falling back to
+   `agent_name`). If a non-empty color is set and the terminal supports it, the
+   label substring is rendered in that color.
+6. `BottleSpec` carries `label` and `color`; the docker backend's `prepare`
+   step copies them into `BottleMetadata`.
+7. `agent_provider.py` writes `label` → `"name"` and `color` → `"color"` into
+   the generated `claude.json`, alongside the existing fields. Fields are
+   omitted when empty.
+8. The dashboard's `_new_agent_flow` (PRD 0020) includes the label+color step
+   between agent selection and the backend picker.
+9. `cmd_start` (CLI) includes the label+color step after argument validation
+   and before prepare-with-preflight.
+10. All existing unit tests stay green; no new tests are required for this
+    change (the label/color fields are thin plumbing with no branching logic
+    worth unit-testing beyond the already-tested metadata read/write path).
+
+## Non-goals
+
+- Showing the agent label inside the Claude Code TUI (status line, terminal
+  title, custom header). That requires upstream Claude Code / codex support.
+  Writing to `claude.json` is best-effort scaffolding for when that lands.
+- Per-bottle color affecting anything outside the dashboard agents pane (e.g.,
+  proposal-pane highlights, log prefixes).
+- Validating or constraining label content beyond the 64-byte printable cap.
+- Persisting color-pair state across dashboard restarts (color pairs are
+  initialized fresh each session).
+- Editing the label or color of an already-running bottle.
+- Exposing label/color via `./cli.py list` (out of scope for v1; trivial to
+  add later since the field will be in metadata).
+
+## Design
+
+### Data flow
+
+```
+operator input
+     │
+     ▼
+BottleSpec.label, BottleSpec.color
+     │
+     ├─► docker/prepare.py → BottleMetadata.label / .color → metadata.json
+     │
+     └─► agent_provider.py → claude.json {"name": label, "color": color}
+                                              (omitted when empty)
+
+dashboard refresh
+     │
+     ▼
+enumerate_active() → read_metadata(slug) → ActiveAgent.label / .color
+     │
+     ▼
+_format_agent_row → label (colored) in the row string
+```
+
+### BottleSpec changes
+
+```python
+@dataclass(frozen=True)
+class BottleSpec:
+    manifest: Manifest
+    agent_name: str
+    copy_cwd: bool
+    user_cwd: str
+    identity: str = ""
+    label: str = ""   # operator-chosen display name; defaults to agent_name at render time
+    color: str = ""   # one of the 16 ANSI color names, or "" for terminal default
+```
+
+`label` and `color` default to `""` so all existing callers remain valid with
+no changes.
+
+### BottleMetadata changes
+
+Add two new fields with backward-compatible defaults:
+
+```python
+@dataclass
+class BottleMetadata:
+    identity: str
+    agent_name: str
+    cwd: str
+    copy_cwd: bool
+    started_at: str
+    compose_project: str
+    backend: str
+    label: str = ""
+    color: str = ""
+```
+
+`metadata.json` written by older bot-bottle versions won't have these keys;
+`read_metadata` already uses `dict.get` with defaults, so existing slugs load
+cleanly with `label=""`, `color=""`.
+
+### ActiveAgent changes
+
+```python
+@dataclass(frozen=True)
+class ActiveAgent:
+    backend_name: str
+    slug: str
+    agent_name: str
+    started_at: str
+    services: tuple[str, ...]
+    label: str = ""
+    color: str = ""
+```
+
+`enumerate_active()` copies `label` and `color` out of `BottleMetadata` when
+constructing each `ActiveAgent`. The smolmachines backend gets the same
+additions for symmetry; it reads from its own metadata path.
+
+### Dashboard row rendering
+
+`_format_agent_row` already falls through cleanly on missing fields. The
+change is:
+
+```python
+display_name = a.label if a.label else a.agent_name
+```
+
+Color rendering uses the existing `_try_init_green()` pattern as a model.
+A `_color_pair_for(color_name)` helper initialises a fresh curses color pair
+for the requested named color and returns its attr (or 0 on failure). Each
+unique color in the active agent list gets its own pair index. Color pairs are
+allocated lazily and cached in a `dict[str, int]` that lives for the duration
+of the dashboard session.
+
+The 16 ANSI color name → curses constant mapping:
+
+| Name | curses constant |
+|------|----------------|
+| `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` |
+| `bright-*` | same constant + `curses.A_BOLD` |
+
+Terminals that don't support color fall back to plain text (the helper returns
+0, which ORed in is a no-op — same pattern as `_try_init_green`).
+
+### Label + color prompt — dashboard
+
+In `_new_agent_flow`, after `_picker_modal` returns a non-None name and before
+`_backend_picker_modal`:
+
+```python
+label, color = _label_color_modal(stdscr, default_label=picked)
+```
+
+`_label_color_modal` uses `curses.endwin()` → text-mode prompts → restore
+(the same drop-and-resume pattern as the existing editor flow and preflight
+Y/N). Two sequential prompts:
+
+```
+bot-bottle: agent label [implementer]: <operator types>
+bot-bottle: color (red/green/blue/… or Enter to skip): <operator types>
+```
+
+Invalid color names are silently ignored (treated as empty). The function
+returns `(label, color)` — both strings, both possibly `""`.
+
+### Label + color prompt — CLI
+
+In `cmd_start`, after argument parsing and before `_launch_bottle`:
+
+```python
+label = _text_prompt_label(args.name)
+color = _text_prompt_color()
+```
+
+`_text_prompt_label(default)` writes `"bot-bottle: agent label [{default}]: "`
+to stderr and returns the stripped input (or `default` if blank).
+`_text_prompt_color()` writes the color prompt and returns the stripped input
+(or `""` if blank or invalid).
+
+Both use `read_tty_line()` (already in `start.py`) for the read.
+
+### Claude Code config injection
+
+In `agent_provider.py`, where `claude_config.write_text(...)` is called,
+expand the JSON dict conditionally:
+
+```python
+payload = {
+    "hasCompletedOnboarding": True,
+    "theme": "dark",
+    "bypassPermissionsModeAccepted": True,
+    "projects": claude_projects,
+}
+if spec.label:
+    payload["name"] = spec.label
+if spec.color:
+    payload["color"] = spec.color
+claude_config.write_text(json.dumps(payload, indent=2) + "\n")
+```
+
+`spec` here is the `AgentProvisionSpec` (or equivalent) that `agent_provider`
+already receives; it needs `label` and `color` threaded in from `BottleSpec`
+through whatever plan/provision object the provider operates on.
+
+## Implementation chunks
+
+Two PRs, each independently mergeable.
+
+### Chunk 1 — schema + storage
+
+- Add `label: str = ""` and `color: str = ""` to `BottleSpec`,
+  `BottleMetadata`, and `ActiveAgent`.
+- `docker/prepare.py`: copy `spec.label` / `spec.color` into `BottleMetadata`.
+- `docker/enumerate.py`: copy `metadata.label` / `metadata.color` into
+  `ActiveAgent`.
+- `agent_provider.py` (or the plan object it reads): thread label/color through
+  to `claude.json` write.
+- Smolmachines backend: parallel changes to metadata read/write and
+  `ActiveAgent` construction.
+- No prompt changes; no UI changes. All existing behavior is identical.
+
+### Chunk 2 — prompts + display
+
+- `start.py`: add `_text_prompt_label` and `_text_prompt_color`; call them in
+  `cmd_start` before `_launch_bottle`; pass `label` / `color` into `BottleSpec`.
+- `dashboard.py`: add `_label_color_modal` (drop-and-resume); call it in
+  `_new_agent_flow`; pass label/color into `BottleSpec`; add
+  `_color_pair_for` helper; update `_format_agent_row` to use `a.label` with
+  color rendering.
+
+## Open questions
+
+None.