CB-559: a profile's launch settings are deferred, not hot

The shipped docs and javadoc said a profile's `model` and `tabLabel` take effect on
the next spawn. They do not, and ConfigRef did not detect the change either, so a
reload logged a clean "config reloaded" and silently did nothing. That is the worst
outcome a reload can produce: the operator has no reason to doubt it.

What makes a key hot is who reads it and when, not that it is config. Placement
reads weight and maxLoad through a supplier on CompositePeerLauncher, so those are
genuinely hot. HerdrPeerLauncher takes Map.copyOf(profiles) at construction and
resolves every spawn out of that copy, so model, baseUrl, argv, env and the rest
cannot move until the daemon restarts.

changedDeferredKeys now compares every launch component of an existing profile,
excluding weight and maxLoad, and names the profiles that need a restart. The
javadoc and bridged.example.yaml say the same thing. Two tests pin the pair:
weight/maxLoad reports nothing deferred, a changed model reports the profile by name.

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "claude-bridge",
+  "description": "Tooling for orchestrating a fleet of delegated coding agents through the bridged MCP gateway.",
+  "owner": {
+    "name": "LTMS"
+  },
+  "plugins": [
+    {
+      "name": "claude-bridge",
+      "source": "./plugin",
+      "description": "Make a project bridge-ready: mount the bridged MCP gateway and apply standard Claude Code settings so a session can orchestrate delegated workers. Ships no credentials.",
+      "version": "0.1.0",
+      "author": {
+        "name": "LTMS"
+      }
+    }
+  ]
+}

.claude/skills/implementer/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: implementer
+description: Implementer-role procedure for a bridged worker — verify your worktree, implement the scope, commit, push, open your own PR, and hand off the PR URL. Load this when the lead delegates you an implementation task over bridged.
+---
+
+# Implementer worker — procedure
+
+The turn contract (one `bridge_reply`, `bridge_ask` for the lead's decisions, honest reporting,
+never merge, never commit `.mcp.json` or `wiki/`) is in **`CLAUDE.md` → Bridge communication →
+Worker** and already applies. This skill is only the *implement-and-hand-off procedure*.
+
+You run in an **isolated git worktree on your own branch** — a full peer of the primary (same repo,
+`CLAUDE.md`, skills), differing in the model behind you and the branch you sit on. Your MCP surface
+is **only what your launcher mounted** (the bridge): the primary's IDE and forge servers are not
+yours, and the worktree's `.mcp.json` is deliberately emptied so you cannot inherit them.
+The worktree model is documented in [`docs/Worker-Git-Workflow.md`](../../../docs/Worker-Git-Workflow.md).
+
+## 1. Confirm where you are — then never leave
+
+Before touching anything:
+
+```bash
+git rev-parse --show-toplevel   # your worktree root — NOT the primary's main tree
+git branch --show-current       # your dedicated branch: worker/<ticket>-<nonce>
+git status                      # should be clean at the start
+```
+
+Do **all** work here, on this branch. Never `git checkout main`, never rebase onto or push to
+`main`. The branch is your isolation — respect it.
+
+**Every path you read, edit, or build is relative to that root.** Work from `$PWD`; if a tool, a
+brief, or your own memory hands you an absolute path, check it starts with your worktree root
+before you touch it, and stop if it doesn't. An absolute path pointing anywhere else is the
+primary's checkout — editing there while building here means **every build you run is of code that
+does not contain your changes**, and it passes while your work goes nowhere. This has happened:
+a worker made all 59 of its edits in the primary's tree and never noticed.
+
+```bash
+test "$(git rev-parse --show-toplevel)" = "$PWD" || cd "$(git rev-parse --show-toplevel)"
+```
+
+## 2. Implement
+
+- Implement exactly the scope the lead named. Keep the diff focused; note anything out of scope
+  in your reply instead of widening it.
+- Match the surrounding code's style, naming, and idioms.
+
+**Acceptance criterion — a green build, quoted.** Your work is not done until this passes *inside
+your worktree*:
+
+```bash
+cd "$(git rev-parse --show-toplevel)/bridged" && mvn clean install
+echo "exit=$?"
+```
+
+Read its **full** output — never pipe it through `tail`/`head`/`grep`, which hide a failure behind
+a zero exit. Then quote the real `Tests run: … Failures: … Errors: …` line and the
+`BUILD SUCCESS`/`FAILURE` verbatim in your reply. If it does not go green, say so with the actual
+error; a failing build honestly reported is a usable result, a claimed-green one is not. You have
+no IDE MCP tools, so `mvn` is your only verification — never claim a check you had no way to run.
+
+## 3. Commit
+
+```bash
+git add <the files you changed>     # explicitly — never `git add -A` / `git add .`
+git commit -m "<ticket>: <clear one-line summary>"
+```
+
+`.mcp.json` is neutralized and `--skip-worktree` in your worktree — never `git add` it, and never
+"restore" it from the primary's copy. Same for `wiki/` (a submodule with its own remote).
+
+## 4. Push
+
+```bash
+git push -u origin HEAD
+```
+
+Push is over SSH as the same user — no extra credential needed. Never force-push over anything
+you did not create.
+
+## 5. Open your own PR to `main`
+
+Via the gitea REST API. The daemon injected a **repo-scoped token** (`GITEA_TOKEN`) and the forge
+host (`GITEA_HOST`) into your env for exactly this — the token can create a PR but **cannot
+merge**.
+
+```bash
+API="${GITEA_HOST%/}/api/v1/repos/lms/claude-bridge/pulls"
+BRANCH="$(git branch --show-current)"
+curl -sS -X POST "$API" \
+  -H "Authorization: token ${GITEA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "$(cat <<JSON
+{"head": "${BRANCH}", "base": "main",
+ "title": "<ticket>: <concise change summary>",
+ "body": "<what changed and why; reference the ticket; note tests run and their result>"}
+JSON
+)"
+```
+
+The response JSON carries `"html_url"` — that is your PR URL. On a non-2xx, read the error body,
+fix it if the cause is yours (e.g. branch not pushed yet), and report the failure rather than
+inventing a URL. If `GITEA_TOKEN` is unset your profile was not granted PR-create: push the branch
+and report its name so the lead opens the PR.
+
+## 6. Hand off — what goes in `bridge_reply`
+
+The reply is the entire handoff; the lead cannot see your terminal.
+
+```
+PR:      <html_url from step 5, or "not created: <reason>" + branch name>
+branch:  <your branch>
+root:    <git rev-parse --show-toplevel — proves you worked in your own worktree>
+files:   <worktree-relative paths you changed>
+build:   <the verbatim "Tests run: …" and BUILD SUCCESS/FAILURE lines — or "not run: <why>">
+summary: <2-3 lines: what you implemented and any caveat the reviewer needs>
+```
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant L as Lead
+    participant I as Implementer (you)
+    participant G as git / gitea
+
+    L->>I: delegated task (you are in a worktree on your branch)
+    I->>I: "implement here — every path under $PWD"
+    I->>I: "mvn clean install in this worktree, unpiped, until green"
+    I->>G: git commit (never .mcp.json / wiki)
+    I->>G: git push -u origin HEAD
+    I->>G: POST /pulls (GITEA_TOKEN) — open PR to main
+    G-->>I: html_url
+    I->>L: bridge_reply(PR url, branch, files, tests)
+    Note over L,G: the lead reviews the PR and merges on green — you never merge
+```
+
+*The implement turn: work in the worktree, commit → push → open the PR, hand off the URL.*

.claude/skills/port-to-opencode/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: port-to-opencode
+description: Make an OpenCode session a first-class participant in a Claude Code workspace — instructions, MCP servers, and secrets — without duplicating config. Use when onboarding opencode to a project that already has CLAUDE.md and .mcp.json, or when an opencode peer needs the same tools and rules as the Claude session.
+---
+
+# Porting a Claude Code workspace to OpenCode
+
+**The headline: there is almost nothing to port.** OpenCode reads `CLAUDE.md` natively. The only
+artifact you create is one `opencode.json` mapping MCP servers. Do not translate instructions, do
+not generate a second rules file, and do not install a sync tool — every one of those makes the
+workspace worse.
+
+Everything below was verified against `opencode 1.18.16` and the OpenCode docs.
+
+## 1. Know what you get for free
+
+OpenCode's instruction search order:
+
+```
+1. walking up from cwd:   AGENTS.md , then CLAUDE.md
+2. global:                ~/.config/opencode/AGENTS.md
+3. Claude Code global:    ~/.claude/CLAUDE.md          (unless disabled)
+```
+
+*"The first matching file wins in each category."*
+
+Consequences that decide the whole procedure:
+
+- **A project `CLAUDE.md` is already read.** No port needed.
+- **Your user-level `~/.claude/CLAUDE.md` is already read too.** Global preferences carry over.
+- **An `AGENTS.md` in the repo SHADOWS `CLAUDE.md`.** If one exists from a previous Codex port,
+  **delete it** — otherwise opencode reads the stale translated copy instead of the real rules.
+  This is the single most likely way to get this wrong.
+
+## 2. Create `opencode.json` for MCP servers only
+
+Project config lives at `opencode.json` in the repo root; the global one is
+`~/.config/opencode/opencode.json`. **Configs merge, they do not replace** — so machine-local
+servers belong in the global file and shared ones in the project file.
+
+Map each entry from `.mcp.json`:
+
+| `.mcp.json` | `opencode.json` |
+|---|---|
+| `"type": "http"` / `"sse"` | `"type": "remote"`, `"url"` |
+| `"type": "stdio"` | `"type": "local"`, `"command": ["bin", "arg"]` |
+| `"command"` + `"args"` | single `"command"` array |
+| `"env"` | `"environment"` |
+| `"headers"` | `"headers"` |
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["CLAUDE.md"],
+  "mcp": {
+    "bridged":  { "type": "remote", "url": "http://127.0.0.1:8765/mcp", "enabled": true },
+    "context7": { "type": "remote", "url": "https://example.dev/mcp", "enabled": true,
+                  "headers": { "Authorization": "Bearer {env:CONTEXT7_TOKEN}" } },
+    "gitea":    { "type": "local", "command": ["gitea-mcp", "-t", "stdio"], "enabled": true,
+                  "environment": { "GITEA_ACCESS_TOKEN": "{env:GITEA_ACCESS_TOKEN}" } }
+  }
+}
+```
+
+Set `instructions` explicitly even though `CLAUDE.md` is found anyway — the fallback only applies
+while no `AGENTS.md` exists, and being explicit survives someone adding one later.
+
+## 3. Reference secrets, never embed them
+
+OpenCode substitutes at load time, in both `headers` and `environment`:
+
+```
+{env:VARIABLE_NAME}      value from the environment
+{file:~/.secrets/token}  value read from a file
+```
+
+**No credential ever belongs in `opencode.json`.** With `{env:…}` there is no reason to write one,
+which is what makes this file safe to commit — and it must be committable, because a peer running
+in a git worktree receives tracked files only.
+
+**But `{env:…}` reads OpenCode's *process* environment — and OpenCode has no env store of its
+own.** A Claude Code `env` block in `~/.claude/settings.json` or `.claude/settings.local.json` does
+**not** reach it: those files are Claude Code's, and the variables exist only inside processes
+Claude Code spawned. Verify with a clean login shell, not the shell your agent hands you:
+
+```bash
+env -u MY_TOKEN zsh -lc 'echo "${MY_TOKEN:-NOT IN PROFILE}"'
+```
+
+So `{env:…}` only works if something puts the variable in the environment first. Pick the supply
+route by who launches opencode:
+
+| Launcher | Route |
+|---|---|
+| a human, from a terminal | `{file:…}` — see below |
+| a spawner (bridge, CI, IDE) | `{env:…}`, with the spawner injecting the variable |
+
+For the human case prefer **`{file:…}` with a workspace-relative path**, kept in a gitignored
+`.secrets/` directory beside `opencode.json`:
+
+```json
+"headers": { "Authorization": "Bearer {file:.secrets/api-token}" }
+```
+
+Verified: opencode resolves relative `{file:}` paths against the project root, so this needs no
+shell setup at all — no rc export leaking the secret to every process, no direnv dependency.
+
+**The catch, and state it out loud:** `.secrets/` is gitignored, so a peer running in a git worktree
+does **not** get it — worktrees receive tracked files only, the same rule that makes `opencode.json`
+itself worth committing. Spawned peers must therefore be fed through `{env:…}` by whatever launches
+them. Check the variable *names* match: a spawner often injects under a different name than your
+shell uses, and the config has no fallback.
+
+## 4. Do not port machine-local MCP servers
+
+IDE indexes, language servers, editor bridges — anything bound to *your* checkout — stay out of the
+project file. Put them in `~/.config/opencode/opencode.json` if you want them personally.
+
+A committed project config reaches every worktree. A worker that mounts servers whose paths point
+into the primary's checkout will edit the primary's files while building in its own — every build
+passes, every change lands in the wrong tree.
+
+Port the servers the work needs. Leave the rest.
+
+## 5. Verify against the running agent, not the file
+
+A file on disk proves nothing about what the agent loaded.
+
+```bash
+opencode run "In one line: state a rule from this project's instructions."
+```
+
+The answer must reflect the actual `CLAUDE.md`. If it answers generically, the instructions did not
+reach the model and everything after this is built on sand.
+
+Then confirm the tools are mounted:
+
+```bash
+opencode mcp list
+```
+
+**"connected" does not mean "working".** A stdio server with a missing credential still completes
+the MCP handshake and reports green; only a real tool call reveals it. Verified: `gitea` showed
+`✓ connected` with no token, then failed the first call with `token is required`. A remote server
+is more honest (`⚠ needs authentication`), but do not rely on that difference — **exercise one
+authenticated tool per server**:
+
+```bash
+opencode run "Call <server>'s <tool>. Report the result or the exact error. One line."
+```
+
+Check too that no server you deliberately withheld is present.
+
+## 6. Report
+
+State what you changed, which servers crossed and which you withheld and why, and quote the
+verification answer verbatim. If any server failed to connect, say so plainly — a partially mounted
+peer is worse than a missing one, because it looks configured.
+
+## Gotchas
+
+- **A leftover `AGENTS.md` silently wins over `CLAUDE.md`.** Check for one before anything else.
+- **`opencode.json` is merged, not overridden** — a global entry and a project entry with the same
+  server name both matter; keep names distinct unless you intend to layer them.
+- **`enabled: false`** turns a server off without deleting its config — prefer it over removal when
+  you may want the server back.
+- **OAuth-based servers** store tokens in `~/.local/share/opencode/mcp-auth.json` after
+  `opencode mcp auth <server>`; that is machine state, never config to commit.
+- **Skills and subagents do not port.** OpenCode uses its own agent markdown under
+  `.opencode/agents/`; `.claude/skills/**` is not read. If a delegation brief tells a peer to load a
+  skill by name, that instruction has no effect on an opencode peer — spell the procedure out in the
+  brief, or author the equivalent agent file.

.claude/skills/reviewer/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: reviewer
+description: Reviewer-role procedure for a bridged worker — how to work a review scope and the exact shape of the finding to report. Load this when the lead delegates you a code review over bridged.
+---
+
+# Reviewer worker — procedure
+
+The turn contract (one `bridge_reply`, `bridge_ask` for the lead's decisions, honest reporting,
+never merge) is in **`CLAUDE.md` → Bridge communication → Worker** and already applies. This
+skill is only the *review procedure*: how to work the scope, and the exact shape of what you
+send back.
+
+## 1. Read the whole scope before you judge
+
+The delegation names your scope — a file, a diff, a PR, a function. **Read all of it first.**
+A review that fires on a snippet misses the caller that makes it safe (or the one that makes it
+a bug). Reviewing part of the scope and guessing the rest is the most common way a reviewer is
+wrong.
+
+## 2. Stay in the scope
+
+- Review **only** what you were assigned. Something elsewhere looks wrong? One line in your
+  reply — do not go hunt it. Wandering is how two reviewers report the same thing and neither
+  covers what it was given.
+- Do **not** edit files or run the build. You review; the owner acts.
+
+## 3. Reach for `bridge_ask` only for a genuine fork
+
+Ambiguous requirement, a missing acceptance criterion, "intended or a bug?", or two defensible
+fixes with different consequences — those are the lead's call, and guessing produces a
+confident-but-wrong finding. Anything you could settle by reading more code is yours to settle.
+
+## 4. The finding — what goes in `bridge_reply`
+
+Report the **single most important** real issue in the scope, in these four lines, under
+~90 words:
+
+```
+1. <path>:<line>
+2. issue: <one sentence — what is wrong and why it matters>
+3. fix: <one line — the concrete change>
+4. severity: high | medium | low
+```
+
+- **Nothing real after reading?** Reply `NO ISSUE` and one line saying why. A clean review is a
+  valid result; a fabricated issue is worse than none.
+- **Severity:** `high` = wrong result, data loss, security, or a hang/crash on a real path ·
+  `medium` = a real bug on an edge path, or a correctness risk under load/concurrency ·
+  `low` = clarity, a latent foot-gun, or a smell with no current failure.
+- Be specific and verifiable: a line number and a one-line repro beat an adjective. If you can't
+  point at where it goes wrong, you haven't found it yet.

.gitea/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # The wiki submodule is docs only and is not needed to build — leave it unfetched so CI
+      # does not depend on the wiki repo being reachable.
+      - uses: actions/checkout@v4
+
+      # The runner image ships an older default-jdk; bridged sets maven.compiler.release=25, so
+      # provision the JDK explicitly rather than apt-installing whatever "default" means today.
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+          cache: maven
+
+      # setup-java provisions the JDK only — it does NOT install Maven, and the runner image has
+      # no mvn on PATH (a bare `mvn` exits 127). Install it separately. apt pulls a default JRE as
+      # a dependency; JAVA_HOME from setup-java still wins, which the version check below proves.
+      - name: Install Maven
+        run: |
+          apt-get update && apt-get install -y --no-install-recommends maven
+          mvn -version
+
+      - name: Build and test
+        working-directory: bridged
+        # This IS the mock-socket surface CB-503 asks for: the pom's `default-excludes` profile
+        # already sets excludedGroups=contract, so the @Tag("contract") tests — which need a live
+        # herdr socket and a RabbitMQ container — are excluded without any flag here. Everything
+        # that runs does so against the fake UDS herdr and fake ccs/claude stubs.
+        run: mvn -B clean install
+
+      # Deliberately NOT actions/upload-artifact: this Gitea instance presents as GHES, and
+      # @actions/artifact v2+ (i.e. upload-artifact@v4) refuses to run there —
+      # "GHESNotSupportedError ... not currently supported on GHES", which red-Xes an otherwise
+      # green build. Since the artifact could not be retrieved anyway, dump the failing tests into
+      # the log instead, where they are actually readable.
+      - name: Failing test output
+        if: failure()
+        working-directory: bridged
+        run: |
+          for f in target/surefire-reports/*.txt; do
+            [ -f "$f" ] || continue
+            grep -qE "Failures: [1-9]|Errors: [1-9]" "$f" && { echo "===== $f ====="; cat "$f"; }
+          done
+          exit 0
+
+  # CB-521 — actually run the AMQP contract test in CI, against a REAL broker. The broker is a
+  # RabbitMQ SERVICE CONTAINER, not Testcontainers-with-Docker: the runner image has no Docker, so
+  # AmqpReplyInboxContractTest reads AMQP_URI (set below to the service's network alias) and binds
+  # straight to it — no Docker, no skipped tests. This separation (build job hermetic and
+  # Docker-free; contract job broker-provided) is deliberate — see the default-excludes/contract
+  # profiles in bridged/pom.xml. `setup-java` provides the JDK only; Maven is installed separately,
+  # exactly as in the build job above.
+  contract:
+    runs-on: ubuntu-latest
+    services:
+      rabbitmq:
+        image: rabbitmq:3.13          # same AMQP 0-9-1 engine the local Testcontainers fixture uses
+        env:
+          RABBITMQ_DEFAULT_USER: guest
+          RABBITMQ_DEFAULT_PASS: guest
+        ports:
+          - 5672:5672
+    env:
+      # Service containers are reachable from the job by their network alias on their internal port.
+      AMQP_URI: amqp://guest:guest@rabbitmq:5672
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '25'
+          cache: maven
+
+      - name: Install Maven
+        run: |
+          apt-get update && apt-get install -y --no-install-recommends maven
+          mvn -version
+
+      # The `contract` profile clears the default-excludes group, so the @Tag("contract") AMQP test
+      # runs against the RabbitMQ service container (AMQP_URI). Pinned to the one contract test to
+      # avoid re-running the unit suite already covered by the `build` job.
+      - name: Contract tests
+        working-directory: bridged
+        run: mvn -B -Pcontract test -Dtest=AmqpReplyInboxContractTest
+
+      - name: Failing test output
+        if: failure()
+        working-directory: bridged
+        run: |
+          for f in target/surefire-reports/*.txt; do
+            [ -f "$f" ] || continue
+            grep -qE "Failures: [1-9]|Errors: [1-9]" "$f" && { echo "===== $f ====="; cat "$f"; }
+          done
+          exit 0

.gitignore

@@ -0,0 +1,12 @@
+# Workspace-scoped secrets for tools that read no settings cascade of their own
+# (opencode resolves these via {file:.secrets/...} in opencode.json).
+.secrets/
+
+# Settings backups inherit the env block — and secrets with it.
+.claude/settings.local.json.bak*
+
+# Daemon runtime artefacts. bridged appends its log wherever it is launched from, so both the
+# repo root and bridged/ collect one; neither belongs in git.
+bridged.out
+bridged/bridged.out
+logs/

CLAUDE.md

@@ -1,7 +1,237 @@
 # claude-bridge — project instructions
 
+## Bridge communication (enforced — read this first)
+
+> **Canonical block.** Everything down to §Layering is the portable bridge charter, copied verbatim
+> into every project that mounts the bridge MCP. Keep it byte-identical with the template in the
+> wiki ([Use Cases](https://git.ltms.dev/lms/claude-bridge/wiki/7-Use-Cases) → *The portable
+> CLAUDE.md block*); improvements go to the template first, then out to each project. Anything
+> specific to *this* repo lives under §Project addendum below, never inline above it.
+
+If no `bridge_*` MCP tools are mounted in this session, this section does not apply — skip it.
+
+`bridged` is the **sole communication gateway** between agents here. The orchestrating session (the
+**primary**) and every delegated peer (a **worker**) mount the *same* MCP server and talk only
+through its `bridge_*` tools. No session addresses a peer, a broker, or the network directly.
+
+### Which role am I? — settle this before acting
+
+**Both roles read this file.** A worker runs in a git worktree of this same repo, so it inherits
+this `CLAUDE.md` verbatim, and every rule below is role-conditional.
+
+**Call `bridge_whoami`.** It returns `{"role":"primary"}` or `{"role":"worker","sessionId":…,
+"profile":…,"worktree":…,"branch":…}`, resolved by the daemon from your connection — unforgeable,
+and the same resolution its authorization gate uses. Don't infer what you can ask.
+
+Only if that call is unavailable, fall back to these — each is one-way, so keep reading until one
+fires: the reply charter in your system prompt (*"You are an off-subscription worker in the
+claude-bridge fleet"*) ⇒ **worker**; bridge tools prefixed `mcp__bridge__*` ⇒ **worker** (the
+launcher fixes that mount name; a primary's mount is named by whoever wrote its `.mcp.json`, so it
+varies); `ANTHROPIC_BASE_URL` set ⇒ **worker** (Claude-model workers run on a clean env, so its
+*absence* proves nothing). **Still unsure ⇒ act as a worker.** The two mistakes are not symmetric: a
+primary acting as a worker is refused by the authorization gate — loud and self-correcting — while a
+worker acting as the primary ends its turn with no `bridge_reply`, and the sender silently receives
+nothing. Fail toward the recoverable error.
+
+### Invariants — both roles, no exceptions
+
+1. **Never set, export, or forward `ANTHROPIC_BASE_URL`** (or `ANTHROPIC_AUTH_TOKEN`). The primary
+   stays on subscription; only the bridge puts a worker off it, at spawn. Mounting the bridge must
+   never move a session across that boundary.
+2. **The bridge is the only channel.** Text you print in your terminal reaches nobody — the other
+   side cannot see your screen. An answer that isn't in a `bridge_*` call is silently discarded.
+3. **Identity comes from the connection, never an argument.** Workers never pass a target; you
+   cannot act as another session. Spawn/stop/send/drain are lead-only; reply/ask are
+   only-as-itself — any peer may answer for its own pane, and for no other. A call outside your
+   role is refused, not queued.
+4. **Delivery is status-gated: one message per turn.** Don't busy-poll a peer's terminal and don't
+   re-send because a call looks slow — the bridge delivers when the peer is `idle`/`blocked`.
+5. **Never drive the terminal multiplexer directly** (no `herdr` CLI, no socket). The bridge owns
+   policy; the multiplexer owns PTYs. Going around the bridge bypasses every rule above.
+
+### Primary (lead) — run this on every task, in order
+
+**Delegate by default — that is the job.** With the bridge mounted you are an orchestrator on a
+metered subscription, and workers are cheap, parallel, and disposable. The default answer to "who
+does this?" is **a worker**, not you. Reach for `bridge_send` before you reach for `Edit`. The steps
+below are the procedure — run them in order, every task, not only the big ones.
+
+0. **Know your role** — `bridge_whoami`, once per session, before anything else.
+1. **Split.** Write the unit list. Every unit carries: scope · the files or PR in question ·
+   acceptance criteria · exactly what to report back. A unit with no acceptance criteria is not
+   ready to delegate — refine it or keep it.
+2. **Gate each unit** on one question: **"can I write a brief good enough for a worker to
+   succeed?"** — *not* "could I do this faster myself?" (usually you could; doing it yourself costs
+   your context and your subscription, while a wasted worker turn costs a worker turn). Yes ⇒
+   delegate. The keep-list is closed: the conversation with the user, decomposition and planning,
+   the final judgment call, verification, merges, and anything that depends on context only you
+   hold. Nothing else is yours by default.
+3. **Spawn every delegated unit first** — `bridge_spawn{profile, worktree:true, ticket}`, one per
+   unit, *before* sending any. Pass `profile` explicitly: profiles differ in model and cost, not in
+   tier, so the default is rarely what you want.
+4. **Then send them all** — `bridge_send{sessionId, content, wait:false}`. Line 1 of every brief is
+   `Load the <name> skill.` naming the worker's playbook; those skills are opt-in and that line is
+   what makes them reliable. Where the project ships no such skill, spell the procedure out in the
+   brief instead. The brief is self-contained — the worker sees your message and the repo, nothing
+   of your context, your plan, or your screen.
+5. **Collect** — `bridge_poll{ticket}` → `bridge_ack{ticket, msgId}`. Answer a worker's `bridge_ask`
+   with `bridge_send{turnId, content}` — **not** `sessionId`. A worker gone quiet is diagnosed with
+   `bridge_status`, never by reading its terminal.
+6. **Verify yourself.** Re-run the build and the checks. A worker mounts only the bridge MCP and
+   cannot run your other tooling, and a piped command (`… | tail`) hides failures behind a zero
+   exit — never promote a worker's "clean" to a fact.
+7. **Review — fan out.** Spawn reviewers against the diff, one per dimension or per file, with
+   `wait:false`. Never the implementer of the scope it reviews, and brief them from the diff — not
+   from the implementer's rationale, which carries its own blind spot. Dispatch each PR's reviewers
+   as it lands; don't wait for the last implementer. Under ~50 changed lines, skip the fan-out and
+   read it yourself.
+8. **Adjudicate, merge, tear down — yours alone.** Read the diff yourself: fully if it is small,
+   targeted at the reported findings and the risky paths if it is large. Reviewer findings direct
+   your attention; they never substitute for it. Then merge, then `bridge_stop{paneId}`.
+
+**Steps 3 and 4 are separate on purpose** — spawning and sending in one loop is how parallel work
+silently becomes serial, and it is the most common way this layer is wasted. For the same reason,
+prefer `wait:false` + `bridge_poll` for anything non-trivial: a blocking `bridge_send` is capped by
+*your own* MCP client call timeout (~60s), well below the task's real runtime.
+
+**Delegating does not delegate responsibility.** Workers open PRs; you are the gate. Never delegate
+the merge — and merging on a reviewer's word is delegating it by proxy.
+
+| Intent | Tool |
+|---|---|
+| Confirm your own role | `bridge_whoami` |
+| See backends available | `bridge_profiles` |
+| Start a worker | `bridge_spawn{profile?, cwd?, worktree?, ticket?}` → `sessionId` + `paneId` |
+| See the fleet | `bridge_list` → `leads` (your peers) + `workers` · one peer's state: `bridge_status{sessionId}` |
+| Delegate (blocking) | `bridge_send{sessionId, content}` |
+| Delegate (long task) | `bridge_send{sessionId, content, wait:false}` → ticket → `bridge_poll{ticket}` |
+| Answer a worker's `bridge_ask` | `bridge_send{turnId, content}` — **not** `sessionId` |
+| Message a **peer lead** | `bridge_send{sessionId: <their terminal>, content}` — `bridge_list` → `leads` reports it. Coordination only, **never** a task |
+| Answer a peer lead that messaged you | `bridge_reply{content}` — the one case a lead replies |
+| Collect a held reply | `bridge_poll{target}` · then `bridge_ack{target, msgId}` |
+| Tear down | `bridge_stop{paneId}` |
+
+### Lead ↔ lead — coordinate, never delegate
+
+`bridge_list` returns `leads` alongside `workers`; your own row carries `self: true`. Every other row
+is a peer — an orchestrator with its own context, its own workers, and its own judgment. An empty
+`workers` array means no workers are spawned; it says nothing about peers.
+
+**A lead never assigns a task to another lead.** Work goes to workers — only ever downward, never
+sideways. Sending a peer a brief with acceptance criteria is a category error: a brief is a worker's
+artefact, and a peer is not yours to task. If a unit needs doing and it falls in your area, spawn a
+worker and delegate it yourself; if it falls in the peer's area, say so and let the peer assign it.
+The traffic between leads is coordination and nothing else:
+
+1. **Divide the map, not the work.** Agree who owns which area, then each of you assigns inside your
+   own. Split by **context ownership** — whoever already holds the context owns that area — and say
+   who takes what, in one message, before either of you starts. Two leads silently working the same
+   unit is the failure mode here, and neither notices until the merge.
+2. **Share findings, hazards, and corrections.** What you have already discovered, what broke, what
+   the next person will trip on. This is the traffic that actually pays for the channel: it costs one
+   message and saves a peer a rediscovery.
+3. **Verify a peer exactly as you verify yourself.** Peer status buys nothing: check the claim
+   against the code, and re-run the build. A peer's correction gets the same treatment — right or
+   wrong on the evidence, not on who said it. Neither of you merges the other's work unreviewed.
+
+Being messaged by a peer does not make you its worker: answer with `bridge_reply`, and push back on
+the substance if it is wrong. A peer that simply complies has thrown away the reason there are two of
+you.
+
+### Worker — the turn contract
+
+1. **Load the playbook skill the lead named** before doing anything else.
+2. **Do the assigned scope only.** Note anything you spot outside it in one line; don't go hunt it.
+3. **`bridge_ask{question}`** when a decision is genuinely the lead's (ambiguous requirement, two
+   defensible fixes, "bug or intended?"). It blocks and you resume the *same* turn with the answer.
+   Don't ask what you could decide yourself.
+4. **End the turn with exactly one `bridge_reply{content}`**, carrying your complete answer. This is
+   the whole handoff. No `bridge_reply` ⇒ the sender gets nothing and the exchange stalls.
+5. **Report honestly.** State only what you actually ran and its real output, including failures.
+   You mount **only** the bridge MCP — the primary's other servers (IDE, forge, docs) are not yours,
+   so never claim the result of a check you had no way to run.
+6. **Never merge.** Stage files explicitly — never `git add -A` — and leave alone anything the
+   project marks as not-yours-to-commit.
+
+### Where each rule lives (don't duplicate — extend the right layer)
+
+| Layer | Scope | Reaches |
+|---|---|---|
+| the launcher's reply charter | the one rule that must survive with no repo: *end every turn with `bridge_reply`* | every worker, at launch, every peer kind |
+| **this section** | protocol + orchestration policy | primary **and** every Claude worker — tracked in git, so worktrees inherit it |
+| role playbook skills | per-job procedure (commit/PR recipe, finding format) | a worker told to load one |
+| the bridge's own docs | design detail, flows, error model | on demand |
+
+A rule belongs in **exactly one** layer — the outermost one that must obey it. Peers that don't read
+`CLAUDE.md` (non-Claude adapters) get the charter only, so any rule *they* must obey belongs in the
+charter, not here.
+
+## Project addendum — claude-bridge (not part of the canonical block)
+
+- **This repo is the bridge.** The daemon is `bridged`, its MCP mount is `http://127.0.0.1:8765/mcp`,
+  and the code behind the rules above is `mcp/BridgeMcp` (tools), `auth/Authz` (the role table),
+  `mcp/ConnectionIdentity` (connection→role), and `worker/*Launcher` (`REPLY_CHARTER`).
+- **Skills available to delegate:** `implementer` (worktree → commit → push → own PR) and
+  `reviewer` (scoped review → one structured finding). Name one in every delegation.
+- **Primary-side skills** (not delegation playbooks — a worker cannot use them):
+  `port-to-opencode` (make an OpenCode session a participant in this workspace).
+- **Never commit** `.mcp.json` (the primary's local copy, flagged `--skip-worktree`) or `wiki/`
+  (a submodule with its own remote).
+- **Flows and the error model** — rendezvous, `bridge_ask`, detached delivery, turn-done fallback —
+  are diagrammed in `docs/MCP-Contract.md` §6, kept out of this file because it loads into every
+  session's context.
+
+### The prompt is part of the product — update it with the code (mandatory)
+
+This repo *is* the bridge, so the canonical block above is not documentation about someone else's
+system: it is the instruction surface this codebase ships. **Every change here must end by asking
+whether the block still tells the truth.** A code change that silently invalidates it is an
+incomplete change — the agents reading it have no other source.
+
+Before you call any work done, check the row that matches what you touched:
+
+| You changed… | Re-read and update… |
+|---|---|
+| a `bridge_*` tool — added, removed, renamed, or its params/semantics | the primary's intent→tool table; any rule that names that tool |
+| `Authz` / the role table | invariant 3, and the primary-only vs worker-only claims |
+| `ConnectionIdentity` / how a caller is resolved | the `bridge_whoami` paragraph and the fallback ladder |
+| `REPLY_CHARTER`, or a launcher's mount/flags | the fallback ladder (`mcp__bridge__*`), and the layering table's top row |
+| the injector / status gating | invariant 4 |
+| worktree provisioning or the parity overlay | the "both roles read this file" premise — it rests on the worker's worktree being a checkout of this repo |
+| `.claude/skills/**` | the addendum's skill list, and the "name the playbook" rule |
+| a new peer kind (non-Claude adapter) | what that peer can read — anything it must obey belongs in its charter, not in the block |
+| **anything an operator can use, configure, or observe** — an MCP tool, a `bridged.yaml` knob, an endpoint, a visible behaviour | **[Features](wiki/11-Features.md)** — one entry: what it does · the knob that turns it on · **why it exists** · the gotcha |
+
+That last row is not bookkeeping. Chapters 1–10 answer *how is this built* and *why this way*;
+none of them has a home for *what can it do and how do I turn it on*, so for twenty tickets a
+shipped capability landed nowhere and the Roadmap went on claiming the stage was finished. The
+*why* line is the one that matters — without it a decision gets re-litigated from scratch a month
+later. Internal contract changes go to `wiki/9-Implementation.md` instead; test and coverage work
+is a Roadmap line. A change that touches none of the three earns no entry, and that is a normal
+outcome rather than an omission.
+
+Then **propagate**: the block in this file and the template in the wiki
+([Use Cases](https://git.ltms.dev/lms/claude-bridge/wiki/7-Use-Cases) → *The portable `CLAUDE.md`
+block*) must stay byte-identical, and other projects carrying the block need the same edit. Verify
+rather than trust:
+
+```bash
+python3 - <<'PY'
+import pathlib
+c = pathlib.Path("CLAUDE.md").read_text()
+w = pathlib.Path("wiki/7-Use-Cases.md").read_text()
+S, E = "## Bridge communication (enforced", "## Project addendum — claude-bridge"
+block = c[c.index(S):c.index(E)].rstrip() + "\n"
+i = w.index("```markdown\n") + len("```markdown\n")
+print("in sync:", w[i:w.index("\n```\n", i) + 1] == block)
+PY
+```
+
 ## IDE MCP tools & validation workflow (enforced)
 
+> **Primary only.** Workers have no IDE MCP mount — if you are a worker, skip this section and
+> report the build/test output you actually ran (see §Bridge communication → Worker).
+
 Two IDE MCP servers are connected: **intellij-index** (semantic code intelligence) and
 **jetbrains** (file problems, reformat, debugger). IntelliJ has multiple projects open; our
 module is **`bridged`**. Always pass these to IDE MCP tools:
@@ -20,6 +250,15 @@ module is **`bridged`**. Always pass these to IDE MCP tools:
    test run). A per-file-clean file can still break the build or another module. This is the
    whole-project gate before declaring work done or committing.
 
+**Whenever dependencies change (or a `pom.xml` edit), validate CVEs with
+`jetbrains get_file_problems{filePath: "bridged/pom.xml"}`** — its Mend.io check reflects the
+dependencies on disk. (Note: `ide_diagnostics` / intellij-index does NOT re-resolve dependencies
+after a pom edit without a full Maven reimport, so it reports stale CVE results — don't trust it
+for this.) Treat a CVE warning like any other: bump to a patched version and confirm
+`mvn clean install` still passes. If the latest available version is still flagged (EOL line,
+"insufficient information", or config-file-only advisories), document it as accepted in the pom
+rather than chasing a fix that doesn't exist.
+
 ### Use IDE MCP tools for navigation, refactoring, and diagnostics only
 
 - **Navigate (prefer over Grep/Read for symbols):** `ide_find_definition`, `ide_find_class`,

README.md

@@ -50,8 +50,9 @@ flowchart LR
   plain daemon (no Anthropic quota), so it may poll/subscribe freely.
 - **One gateway (unified MCP setup):** `bridged` is the **sole communication path** for every
   Claude session. Primary and workers each mount it as an MCP server (one `claude mcp add`
-  line, same on both) and talk over MCP tools — `bridge_send` / `bridge_reply` / `bridge_ask` /
-  `bridge_status`. **No Claude session ever addresses a broker, a peer, or the network
+  line, same on both) and talk over MCP tools — `bridge_send` / `bridge_reply` /
+  `bridge_status` (with `bridge_ask` planned for the blocked-worker path). **No Claude session
+  ever addresses a broker, a peer, or the network
   directly**; any queue is `bridged`-internal. MCP tool I/O never sets `ANTHROPIC_BASE_URL`, so
   mounting the bridge is subscription-safe by construction.
 - **How the primary consumes a reply:** a single **blocking MCP call** (`bridge_send`);
@@ -85,6 +86,38 @@ Gitea wiki.
 
 ## Status
 
-🟢 Design — herdr-centric **`bridged`** message server selected as the primary approach
-(2026-07-11), superseding the AgentAPI plan (2026-07-08). AgentAPI retained as fallback
-injector.
+🟢 **Implemented & dogfooded** — the herdr-centric **`bridged`** message server is built and in
+real use: an Opus primary delegates tasks to off-subscription workers that reply through the
+bridge (code reviews delegated this way have produced committed bug fixes). Selected as the
+primary approach 2026-07-11, superseding the AgentAPI plan (2026-07-08); AgentAPI retained as a
+fallback injector.
+
+**Shipped** (Java 25 · Maven · 266 unit/acceptance tests green; the live-herdr and broker contract
+tests run separately via `mvn test -Pcontract`):
+
+- **Core gateway** — herdr socket client (contract-tested vs live 0.7.0); guard-checked worker
+  spawn with `ANTHROPIC_BASE_URL` injected only into the worker's env; status-gated injector;
+  blocking `bridge_send` with reply rendezvous; MCP server as a thin adapter over the REST core.
+- **MCP tools** — `bridge_send` / `bridge_reply` / `bridge_status` (messaging) and `bridge_spawn`
+  / `bridge_list` / `bridge_stop` / `bridge_profiles` / `bridge_poll` (fleet). Caller identity is
+  connection-based (loopback peer PID → herdr pane), so the same mount serves primary and workers.
+- **Delivery reliability** — completion fallback (a confirmed `working→idle` turn resolves a
+  send); async fire-and-poll (beats the caller's MCP call timeout for long tasks); and failure
+  detection for wedged (`unknown`), vanished, and never-ready workers so a send never hangs.
+- **Fleet** — multiple worker profiles, each with an independent base_url guard check; workers
+  inherit the primary's working directory (never `$HOME`); a readiness gate holds delivery until
+  a worker's Claude has connected the bridge MCP (no paste lost into its boot window).
+- **Blocked-worker path** — `bridge_ask` reverse rendezvous: a worker pauses its delegated turn to
+  ask the primary and resumes the *same* turn with the answer (CB-205).
+- **Session lifecycle** — session manager with spawn/reuse/recycle, `idle_ttl` reaper, `context_cap`,
+  and graceful drain on shutdown (CB-301/CB-303); per-worker git worktrees on their own branch with
+  a config-parity overlay, so parallel implementers never stomp each other (CB-301-ext).
+- **Reliable worker→primary delivery** — a durable `ReplyInbox` (in-memory by default, AMQP/LavinMQ
+  for cross-restart durability) holds a reply that arrives with no open send, and an active
+  status-gated push loop nudges the primary to drain it (CB-307).
+- **Pluggable peers** — a `PeerLauncher` SPI with two in-tree adapters, `claude-code` and `opencode`,
+  routed by a `kind:` discriminator (CB-401/CB-402).
+
+**Next** (see the [roadmap](wiki/8-Roadmap.md)) — Stage 5 hardening (auth/TLS, `/metrics`, CI,
+service supervision, per-session authz + audit), then cross-host: CB-308 multi-host federation and
+CB-500 multi-tier coordination.

bridged/.gitignore

@@ -5,6 +5,9 @@ dependency-reduced-pom.xml
 # Local runtime config (copy from bridged.example.yaml)
 bridged.yaml
 
+# CB-505 audit trail + daemon stdout/stderr — runtime records, never source
+logs/
+
 # Editor / OS
 *.iml
 .idea/

bridged/bridged.example.yaml

@@ -3,31 +3,389 @@
 # bridged is the sole gateway between primary/worker Claude sessions and herdr.
 # It is NOT a Claude process and must never carry ANTHROPIC_BASE_URL.
 
-# REST + MCP listen address. Keep it on loopback — bridged is same-host in Stage-1.
+# REST + MCP listen address. Keep it on loopback unless you also switch auth.mode to `token`
+# below — bridged REFUSES TO START on a non-loopback bind under loopback-trust (see auth).
 bind:
   host: 127.0.0.1
-  port: 8080
+  port: 8765
+
+# API authentication (CB-501). Governs how a caller that is NOT an on-host worker pane proves it
+# is the primary. Worker identity never depends on this: a loopback peer PID that maps to a herdr
+# pane is unforgeable and is always honoured, so turning auth on cannot lock the fleet out.
+#
+#   mode: loopback-trust  → DEFAULT, and the historical behaviour: any loopback caller that is not
+#                           a worker is the primary, no credential needed. Sound ONLY because the
+#                           OS refuses remote connections to a loopback socket.
+#   mode: token           → such a caller must send `Authorization: Bearer <token>`; without it it
+#                           is anonymous and authorized for nothing. REQUIRED for a non-loopback
+#                           bind — the daemon fails fast otherwise, because "unauthenticated ⇒
+#                           primary" on a reachable port would hand spawn/stop/send to anyone.
+#   tokenEnv              → host env var holding the token (never the literal value). Default
+#                           BRIDGED_API_TOKEN. Read only in token mode; empty ⇒ startup fails.
+#
+# TLS is deliberately NOT terminated in the daemon (CB-501 D3): run a reverse proxy in front and
+# let it own certificate lifecycle, e.g.
+#     location / { proxy_pass http://127.0.0.1:8765; proxy_set_header Authorization $http_authorization; }
+# The broker link gets TLS from its own URI (amqps://…) — see `broker` below.
+# auth:
+#   mode: token
+#   tokenEnv: BRIDGED_API_TOKEN
+
+# Optional pinned primary terminal (CB-307). Names the herdr pane the PRIMARY itself runs in:
+# a caller whose connection maps to this pane resolves as the primary (no credential needed —
+# the pane mapping is as unforgeable as a worker's), and reply nudges are pushed to it.
+# REQUIRED when the primary runs inside a herdr pane — without it the pane match reads the
+# primary as a worker and refuses spawn/send/stop. Get the id from bridge_whoami; re-pin if
+# the primary moves panes.
+# primary:
+#   terminal: term_0123456789abcd
+#   pushReminders: 5      # max nudges before giving up (default 5)
+#   pushBackoffMs: 15000  # delay between nudges (default 15000)
+
+# CB-530: MORE THAN ONE LEAD. `primary:` above is singular by construction — every other pane
+# resolves as a worker — which is right for one lead driving a fleet and wrong the moment two leads
+# (say a Claude lead and an opencode lead) work as peers: the second is silently demoted and refused
+# every orchestration call. List each lead's pane here and all of them resolve as leads.
+#
+#   terminal → the ONLY field identity depends on; get it from that session's bridge_whoami
+#   kind/model → descriptive; they document what runs in the pane and are echoed by bridge_whoami
+#
+# A lead is never spawned — it pre-exists, which is exactly why it must be named rather than created.
+# `bridge_whoami` reports `{"role":"primary","leader":"<name>"}`; role stays "primary" because a lead
+# IS a primary for authorization, so nothing that keys on the role breaks.
+#
+# KEEP `primary:` when adding leads: it still addresses the CB-307 push loop, which needs a single
+# destination for its nudges. If both name the same terminal, the `fleet.leaders:` entry wins.
+#
+# Leads are configured under `fleet.leaders:` — see THE FLEET further down.
+#
+# Two things stop the tab-name convention from becoming a way to claim leadership: the configured
+# member spaces are excluded from the scan, so nothing bridged places can land in a matching tab;
+# and startup REFUSES a `tabPrefix` that the fleet tabLabel template, or any per-profile `tabLabel`
+# override, also matches — so the two namespaces cannot overlap by accident. The label is a NAME,
+# never a capability: what a pane may do is decided by the role the daemon resolves for it.
+
+# CB-551: IDLE-LEAD HEARTBEAT — nudge the single lead back to work when it has been continuously
+# idle (no open bridge_send driving it) past the quiet period. The fleet is one lead + architects +
+# workers, so a lead that stalls is a single point of failure; the ReplyPushLoop only nudges when a
+# reply lands, and this timer catches the gap where nothing lands and the lead just sits idle.
+#
+# Opt-in on purpose — it SPENDS the operator's subscription on its own initiative (each nudge starts
+# a lead turn nobody asked for), so upgrading the daemon must never switch it on for you. Absent
+# block = feature off, exactly as before.
+#
+# Three knobs, each with a default that errs on the side of not burning context:
+#   idleAfterSeconds: 300   # how long the lead must stay idle before the FIRST nudge (default 300 —
+#                           # absorbs normal post-turn pauses; re-prompting every pause burns context)
+#   backoffMs: 60000        # re-check cadence / spacing between nudges past the quiet period (default 60000)
+#   quietNudgeCap: 3        # cap on consecutive nudges that find NOTHING pending, then it stops
+#                           # until real state appears (default 3 — never nag an empty fleet forever)
+# leadHeartbeat:
+#   idleAfterSeconds: 300
+#   backoffMs: 60000
+#   quietNudgeCap: 3
 
 # herdr Unix socket. Omit to use the client default
 # (${HERDR_SOCKET_PATH:-~/.config/herdr/herdr.sock}).
 herdrSocket: ~/.config/herdr/herdr.sock
 
-# How a worker session is spawned. Stage-1 uses the existing ccs `ltms-local`
-# profile, whose .claude.json routes to the gx00 vLLM below.
-worker:
-  profile: ltms-local
-  baseUrl: http://gx00.gw:8000     # the gx00 vLLM (models: coder / deepseek-v4-flash)
-  model: coder
-  # Placement: each worker lands in its OWN tab inside a dedicated worker space, so it
-  # never splits or clutters your real work spaces. Use `pane` for the legacy behaviour
-  # (split the currently-focused tab).
-  placement: tab                   # tab | pane
-  workspace: bridged-workers       # the dedicated worker space (found-or-created, shared)
-  tabLabel: "worker: {profile} #{n}"  # {profile}/{model}/{n} substituted; {n} keeps sibling tabs distinct
+# How member sessions are spawned. Define one or more named profiles (backends) under
+# `profiles`; each key is the profile name (also the ccs profile). A profile says only WHICH
+# BACKEND — model, CLI adapter, credentials, cost. It says nothing about what a member spawned on
+# it is for; that is the member's role, and roles live under `fleet:` below. Which profile an
+# unqualified spawn lands on comes from that role's pool, not from a global default.
+#
+# Shared knobs (placement/workspace) can be repeated per profile; they usually match.
+#   placement: tab   → each worker lands in its OWN tab in a dedicated worker space (default).
+#                      Use `pane` for the legacy behaviour (split the focused tab).
+#   mcpUrl           → bridged mounts the bridge MCP (--mcp-config, inline) + reply charter
+#                      (--append-system-prompt) as launch flags; nothing is written to the profile.
+#   tokenEnv         → host env var holding the worker's auth token (value never stored in config);
+#                      omit for a backend that needs no token (e.g. a local ollama).
+#   cwd              → pin this profile's working directory (CB-112). Omit to inherit the primary's
+#                      cwd on an MCP spawn, else the daemon's cwd — never $HOME. See
+#                      docs/Worker-Startup-and-Trust.md.
+#   configDir        → CLAUDE_CONFIG_DIR for the worker, so it inherits that profile's
+#                      skills/MCP/hooks. Omit to leave the worker on the host default.
+#   parityOverlay    → repo-relative paths copied primary→worktree so a worker in a provisioned
+#                      worktree sees the same local config (CB-301-ext). Omit for the default set:
+#                      [.claude/settings.local.json, .env, .envrc].
+#
+#                      Do NOT add .mcp.json (CB-525). A worker's tools are whatever its launcher
+#                      mounts — the bridge, and nothing else. Replicating the primary's MCP config
+#                      handed a worker the primary's IDE servers, which are bound to the primary's
+#                      checkout, so its navigation returned paths OUTSIDE its own worktree: one
+#                      worker made all 59 of its edits in the primary tree while compiling its
+#                      worktree, and every build it ran was of code that did not contain them.
+#                      bridged neutralizes a provisioned worktree's .mcp.json for this reason;
+#                      listing it here would copy the primary's back over that.
+#   gitTokenEnv      → host env var holding the git-forge API token. When set, its value is injected
+#                      as GITEA_TOKEN so the worker can open its OWN PR at checkpoint (CB-302).
+#                      Opt-in by design — omit and the worker gets no PR-create grant (push over
+#                      SSH is unaffected). The token value itself is never stored in this file.
+#   gitHostEnv       → host env var holding the forge host (default GITEA_HOST). Injected as
+#                      GITEA_HOST *only* alongside a resolved gitTokenEnv.
+#   env              → extra environment for this profile's workers, as a literal key/value map
+#                      (CB-511). Use it to give workers a toolchain.
+#
+#                      A worker's environment does NOT come from your shell. bridged hands herdr an
+#                      explicit env map and herdr merges it into ITS OWN process env — so before
+#                      CB-511 a worker inherited whatever PATH the herdr server happened to be
+#                      started with, which on a long-lived herdr can predate your toolchain entirely
+#                      and leave workers unable to run `mvn` or `java` at all.
+#                      bridged now propagates ITS OWN PATH to every worker by default; set `env:`
+#                      only to override that or add more (JAVA_HOME, …). Since the default is the
+#                      daemon's PATH, make sure the daemon is started with a good one — see the PATH
+#                      lines in deploy/dev.ltms.bridged.plist and deploy/bridged.service.
+#
+#                      Adapter-owned variables always win over `env:`: ANTHROPIC_BASE_URL and the
+#                      rest of the ANTHROPIC_*/CLAUDE_* wiring are applied after it, so an `env:`
+#                      entry cannot repoint a worker past the SubscriptionGuard — which is checked
+#                      against `baseUrl` alone.
+# Put `defaultMode: "auto"` in each ccs profile so the worker runs autonomously.
+profiles:
+  gx10:                              # ccs profile name (NOT a hostname)
+    kind: claude-code                # which adapter spawns this profile (default; may omit)
+    baseUrl: http://gx01.gw:8000     # the vLLM host this profile targets (gx00.gw / gx01.gw)
+    model: coder
+    placement: tab
+    workspace: bridged-workers
+    # tabLabel: an optional per-profile override; the fleet template usually covers it
+    mcpUrl: http://127.0.0.1:8765/mcp
+    tokenEnv: BRIDGED_WORKER_TOKEN
+    argv: ["ccs", "gx10"]
+    weight: 0.5                       # relative selection weight for placement: weighted
+    maxLoad: 2                        # max live workers on this profile (omit for unlimited)
+    # gitTokenEnv: GITEA_TOKEN        # opt-in: let this profile's workers open their own PR (CB-302)
+    # gitHostEnv: GITEA_HOST          # defaults to GITEA_HOST; injected only with gitTokenEnv
+    # configDir: /Users/me/.ccs/instances/gx10   # CLAUDE_CONFIG_DIR — inherit that profile's skills/MCP
+    # cwd: /Users/me/src/myrepo       # pin the working dir; omit to inherit the primary's
+    # parityOverlay: [".claude/settings.local.json", ".env", ".envrc"]   # never add .mcp.json — see above
+  gx11:                              # a second backend, so `placement: weighted` has a choice
+    baseUrl: http://gx01.gw:8000     # self-hosted; ccs handles the model + token
+    placement: tab
+    workspace: bridged-workers
+    # tabLabel: an optional per-profile override; the fleet template usually covers it
+    mcpUrl: http://127.0.0.1:8765/mcp
+    argv: ["ccs", "gx11"]
+    weight: 0.5
+    maxLoad: 2
+    # Pin an auto-compact window BELOW the served model's context ceiling. The global
+    # ~/.claude/settings.json value is shared by every ccs instance and the primary, so the
+    # per-profile override belongs here. Equal to the ceiling means auto-compact never fires
+    # before the server rejects the prompt, which kills a worker mid-turn (CB-523).
+    env:
+      CLAUDE_CODE_AUTO_COMPACT_WINDOW: "280000"
+  # CB-402: a second coding-agent kind, proving the PeerLauncher SPI is provider-neutral.
+  # opencode is provider-agnostic and uses NONE of Claude's private seams: no ANTHROPIC_BASE_URL /
+  # SubscriptionGuard (so it needs no `guard` host entry), no --mcp-config / --append-system-prompt.
+  # The bridge MCP + reply charter mount via a generated OPENCODE_CONFIG file, and the model is a
+  # `provider/model` selector. Placement, tabs, cwd, and the readiness gate are shared with Claude.
+  #
+  # Dogfood-verified 2026-07-29 against opencode 1.18.5 (spawn → readiness gate → bridge_send →
+  # structured bridge_reply → teardown). The `opencode/*-free` models run on opencode's own gateway
+  # and need NO credentials — check `opencode models` for the current free list, since the names
+  # change. That also makes the worker off-subscription by construction.
+  #   opencode-free:
+  #     kind: opencode
+  #     model: opencode/north-mini-code-free  # `provider/model` selector, injected as `-m`
+  #     placement: tab
+  #     workspace: bridged-workers
+  #     tabLabel: "opencode: {profile} #{n}"
+  #     mcpUrl: http://127.0.0.1:8765/mcp
+  #     argv: ["opencode"]
+  #
+  # CB-508: point an opencode profile at your OWN OpenAI-compatible endpoint (local vLLM, llama.cpp,
+  # LM Studio, TGI…) instead of opencode's gateway. Setting `baseUrl` on a `kind: opencode` profile
+  # makes the bridge emit a custom `provider` block into the generated opencode.json — opencode has
+  # no ANTHROPIC_BASE_URL seam, so this is how the endpoint is pinned.
+  #   baseUrl → a bare host:port gets `/v1` appended (where these servers mount the API); a URL that
+  #             already has a path is used verbatim, so a custom mount point still works.
+  #   model   → MUST be "<provider>/<model>". The provider half names the generated block; the model
+  #             half must match an id the server reports at /v1/models. One field drives both the
+  #             declaration and the `-m` flag, so they cannot drift apart. A bare model name with a
+  #             baseUrl set is rejected at spawn rather than silently using the default gateway.
+  #   tokenEnv → optional; its value becomes the provider apiKey. Most local servers ignore the key,
+  #             so a placeholder is used when unset (the AI SDK still requires a non-empty one).
+  # NOTE: no `guard` entry is needed even with a baseUrl set. The SubscriptionGuard exists to stop a
+  # worker borrowing the primary's Anthropic subscription, and an opencode process has no Anthropic
+  # credential path at all.
+  #   opencode-local:
+  #     kind: opencode
+  #     baseUrl: http://127.0.0.1:8000
+  #     model: local-vllm/deepseek-v4-flash
+  #     placement: tab
+  #     workspace: bridged-workers
+  #     tabLabel: "opencode: {profile} #{n}"
+  #     mcpUrl: http://127.0.0.1:8765/mcp
+  #     argv: ["opencode"]
+# How an unqualified spawn chooses a profile: fixed (default, reproduces pre-CB-518 behaviour),
+# round-robin, or weighted. Omitting this key is a strict no-op for existing configs.
+placement: weighted
+
+# Re-read this file without restarting the daemon (CB-559). Off unless you add this block, so an
+# upgraded bridged keeps the old behaviour: the file is read once at boot and never again.
+#   enabled          → turn the watch on. bridged checks the file's modified time on a timer and
+#                      reloads when it moves.
+#   intervalSeconds  → how often to check (default 10). One `stat` per tick, so this is cheap.
+#
+# Not every key can move under a running daemon, and the difference is about what already exists
+# when the reload happens — not about how important the key is:
+#   HOT       → takes effect on the next spawn: the whole `fleet:` block (every role pool and
+#               `tabLabel`), `placement:`, and an existing profile's weight / maxLoad. Those are
+#               hot because the placement policy reads them through a supplier — being config is
+#               not by itself enough to make a key hot.
+#   DEFERRED  → accepted into the new config, but the wiring built at startup keeps the old value
+#               until you restart: `lifecycle:`, `leadHeartbeat:`, `guard:`, `worktreeRoot:`,
+#               `spawnReadyTimeoutMs` / `spawnReadyPollMs`, ADDING or REMOVING a profile (a new
+#               backend needs its own launcher, and launchers are built once), AND an existing
+#               profile's launch settings — model, baseUrl, argv, env, configDir, mcpUrl, tabLabel.
+#               The launcher takes a copy of `profiles:` at startup and resolves every spawn out of
+#               that copy, so those never reach a launch until you restart. The reload logs them by
+#               name rather than pretending they applied.
+#   COLD      → cannot change at all: `bind:`, `herdrSocket:`, `broker:` and `auth:`. The socket is
+#               bound, the broker connection is open, and the auth mode decides who may reach the
+#               port that is already listening.
+#
+# A changed COLD key refuses the WHOLE reload — not the hot half applied and the cold half warned
+# about. A half-applied reload would leave the daemon matching no file on disk, which is the worst
+# thing a reload can do to an operator debugging one. A file that fails to parse or fails a startup
+# validator is refused the same way, and the running config stays live.
+# configReload:
+#   enabled: true
+#   intervalSeconds: 10
+
+# THE FLEET (CB-557) — who the daemon may run, and under which role. This one block replaced four
+# older keys: `leaders:`, `members:`, `leadScan:` and `defaultProfile:`.
+#
+# A member is anything a lead spawns, and every member has two INDEPENDENT attributes:
+#   role    — which contract: architect, dev or reviewer. It picks the launch charter, the role
+#             file, the playbook skill and the authz row.
+#   profile — which backend: one of the `profiles:` keys above (model, CLI adapter, cost).
+# They vary on their own. A reviewer may run on the same profile as the dev whose diff it reads,
+# which is why the two cannot be one field.
+#
+# The ROLE IS THE CONTAINING KEY, not a `role:` field. That is not only tidier: a misspelled role
+# used to parse into a member with no contract at all, while a misspelled pool name here simply
+# declares nothing.
+#
+# Each pool lists the profiles that role MAY run on — these are pools, not identities. That is also
+# what replaced `defaultProfile:`: an unqualified spawn names a role, and that role's pool supplies
+# the candidates, in definition order. A dev and a reviewer staying anonymous is exactly compatible
+# with being listed here; the entry key just names the entry.
+fleet:
+  # Optional. Template for a member tab's label; {role}, {profile}, {model} and {n} are substituted.
+  # {n} counts per role+profile, so `dev: sonnet #2` really is the second sonnet dev. Because {role}
+  # comes from a closed enum, a generated label can never begin with a lead's tabPrefix.
+  # tabLabel: "{role}: {profile} #{n}"
+
+  # Panes that orchestrate rather than are orchestrated. A lead may now be CREATED as well as
+  # recognised: give it a `profile:` and the daemon launches the shortfall when fewer than
+  # `instances` are live. Give it only a `terminal:` and it is recognise-only, as before.
+  #
+  # `tabPrefix` is the naming convention that finds a lead without pasting a terminal id: label the
+  # tab `lead: <name>` when you open it and the pane is recognised on the next rescan. Reopen the
+  # tab later and the id changes; the label does not.
+  #
+  # A lead the daemon launches is labelled BY the daemon, using the same convention, so it is found
+  # by the same scan. A lead counts as live only when herdr also reports a running agent in that
+  # tab — a label left behind by a session that died does not block the relaunch.
+  #
+  # An auto-launched lead is NOT a member: it gets no worker reply charter, is never registered with
+  # the session lifecycle (the idle reaper would kill your orchestrator), and stays on the
+  # subscription — ANTHROPIC_BASE_URL/AUTH_TOKEN are stripped from its env whatever the profile says.
+  # leaders:
+  #   opus-5.0:
+  #     profile: opus                # omit to never create this lead, only recognise it
+  #     instances: 1                 # desired live count; only the shortfall is launched. 0 = off
+  #     terminal: term_0123456789abcd  # optional hand-pin; usually found by tabPrefix instead.
+  #                                  # A running agent on this terminal also counts as live, so a
+  #                                  # lead you opened by hand is not relaunched under you.
+  #     tabPrefix: "lead:"           # `lead: opus-5.0` ⇒ a lead named opus-5.0 (case-insensitive)
+  #     scanIntervalSeconds: 10      # rescan cadence, and the worst case before a new tab is seen
+  #     workspace: leads             # where a launched lead's tab is created (default "leads").
+  #                                  # MUST NOT be a member workspace — those are excluded from the
+  #                                  # scan, so a lead placed in one is never found again.
+  #     cwd: /path/to/repo           # the launched lead's working directory (default: bridged's own)
+  #     kind: claude                 # descriptive; reported by bridge_whoami
+  #   gpt-sol-5.6:
+  #     terminal: term_fedcba9876543
+  #     kind: opencode
+  #     model: openai/gpt-5.6-terra
+
+  # architects:
+  #   architect-1:
+  #     profile: opus                # a strong model, on the operator's subscription
+  #   architect-2:
+  #     profile: sol                 # a different vendor on purpose — two architects that share a
+  #                                  # model share its blind spots
+  developers:
+    gx10:
+      profile: gx10
+  # reviewers:
+  #   gx10:
+  #     profile: gx10                # the same backend may serve two roles; that is the point
 
 # Subscription boundary. A worker's base_url host MUST be one of these; the primary
-# must carry none. Grounded in ltms-local's real endpoints.
+# must carry none. Every profile above must have its host listed here.
 guard:
   offSubscriptionHosts:
     - gx00.gw
-    - ollama.ltms.dev
+    - gx01.gw
+
+# Spawn-readiness gate (CB-306). The launcher blocks until the worker's herdr status is
+# injectable (IDLE/BLOCKED/DONE) or the timeout elapses. 0 disables the gate.
+# NOTE: keys are camelCase — config is bound by plain Jackson with no naming strategy and
+# unknown keys are ignored, so a snake_case key would be silently dropped (default kept).
+# spawnReadyTimeoutMs: 20000
+# spawnReadyPollMs: 300
+
+# Worktree provisioning root (CB-301-ext). Where per-worker git worktrees are checked out so
+# each worker owns an isolated branch instead of sharing the primary's tree. Omit to default
+# to a sibling directory of the repo root.
+# worktreeRoot: /Users/me/src/.bridged-worktrees
+
+# Session lifecycle limits (CB-303). All knobs are opt-in; omit or set to null to keep
+# the feature disabled. By default the daemon never reaps, caps, or drains sessions.
+#   idleTtlSeconds     → reap READY/DONE sessions idle longer than this (never BUSY/SPAWNING)
+#   contextCap         → force-release a session after this many delegated turns
+#   drainTimeoutSeconds → seconds to wait for BUSY sessions on shutdown before forced teardown
+# lifecycle:
+#   idleTtlSeconds: 300
+#   contextCap: 10
+#   drainTimeoutSeconds: 5
+
+# Durable reply delivery (CB-307 Stage 2). OMIT this block entirely to keep the default
+# in-memory, soft-state reply inbox (late worker replies are held only until a daemon bounce).
+# Set a broker uri to swap in the AMQP-backed inbox: worker replies with no open send are held
+# on a durable per-target queue (agent.<target>.inbox) and survive a restart — the broker
+# redelivers anything the primary had not yet drained. Production default is LavinMQ; a stock
+# RabbitMQ speaks the same AMQP 0-9-1, so it is a URI-only swap.
+#   uri → AMQP connection URI. No trailing slash ⇒ the default vhost "/"; an empty path ("/")
+#         is vhost "" and will NOT connect. Encode a named vhost as .../%2Fmyvhost.
+# broker:
+#   uri: amqp://guest:guest@127.0.0.1:5672
+
+# Active push-to-primary (CB-307 Stage 3). When a worker reply lands with no open bridge_send,
+# the ReplyPushLoop injects a *drain nudge* (never the payload) into the primary's own herdr
+# pane — status-gated (only when injectable, never mid-turn) and bounded. Ack = drain: the loop
+# stops as soon as the primary's inbox is empty.
+#   terminal       → pin the primary's herdr terminal id. Omit to learn it from the connection on
+#                    the first orchestration-side MCP call (the normal case). An off-host or
+#                    non-herdr primary leaves this unresolved → the loop is a no-op and delivery
+#                    degrades to pull; the reply is still never lost.
+#
+#                    REQUIRED (CB-522) if the primary itself runs inside a herdr pane. Caller
+#                    identity resolves a loopback PID to its herdr pane, and PaneLocator scans
+#                    EVERY pane — not just bridged-spawned ones — so such a primary is otherwise
+#                    classified as a WORKER and refused SPAWN/SEND/STOP. That failure is
+#                    self-locking: the learned terminal is populated by the very orchestration
+#                    calls being refused, so only this pinned value can break the cycle. Read the
+#                    id off bridge_whoami (it reports the current terminal even while
+#                    misclassified) and re-pin whenever the primary moves panes.
+#   pushReminders  → max nudges before giving up (default 5)
+#   pushBackoffMs  → delay between nudges in ms (default 15000)
+# primary:
+#   terminal: term_65619bd6174568
+#   pushReminders: 5
+#   pushBackoffMs: 15000

bridged/docs/CB-307-Push-Loop.md

@@ -0,0 +1,142 @@
+# CB-307 — Active push-to-primary + reminder loop (the reliability layer)
+
+**Status:** design (2026-07-19). Builds directly on the shipped durable landing zone
+(`AmqpReplyInbox`, main `2bc5f3a`, dogfooded live). gitea #5.
+
+## Why this exists
+
+Stage 2 gave a worker→primary reply a **durable place to wait** when no `bridge_send` is
+open: it lands in `agent.<target>.inbox` on the broker and survives a daemon bounce. But
+delivery is still **pull** — the primary only sees the reply if it happens to call
+`bridge_poll(target)` / `GET /sessions/{id}/replies`. A reply can sit indefinitely while
+the primary works on something else.
+
+This layer makes delivery **active**: the bridge *pushes* a nudge to the primary the moment
+a reply lands, and keeps reminding (bounded) until the primary drains it. At-least-once,
+dedup by `msgId`, and — critically — it never loses the reply even if every push fails,
+because the durable inbox is the backstop.
+
+## The hard constraint it works around
+
+The bridge is an MCP **server**; the primary is an MCP **client**. A server cannot call
+into a client. So "push to the primary" cannot be an MCP response — it needs a *sideband*
+channel. The chosen channel: **inject a synthetic user-turn into the primary's own herdr
+terminal pane** — the same mechanism the bridge already uses to deliver tasks to workers,
+pointed at the primary's pane instead.
+
+```mermaid
+flowchart LR
+    W["worker"] -->|"bridge_reply (no open send)"| MS["MessageService.reply"]
+    MS -->|"inbox.publish"| INBOX[("agent.&lt;target&gt;.inbox<br/>(durable, LavinMQ)")]
+    MS -->|"notify"| LOOP["ReplyPushLoop"]
+    LOOP -->|"status-gated inject"| PANE["primary's herdr pane"]
+    PANE -->|"primary drains"| DRAIN["bridge_poll(target)<br/>= peek + ack"]
+    DRAIN -->|"inbox now empty"| LOOP
+    LOOP -.->|"still non-empty →<br/>re-inject on backoff"| PANE
+    classDef store fill:#2c5282,stroke:#1a365d,color:#ffffff;
+    class INBOX store
+```
+
+*Figure 1 — a reply lands in the durable inbox; the push loop nudges the primary's pane;
+the primary's drain acks it; a still-full inbox triggers a bounded re-nudge.*
+
+## Three increments
+
+### Increment 1 — learn & store the primary's terminal_id
+
+**Finding (seam map):** `ConnectionIdentity.resolve(remoteAddr, remotePort)` already returns
+the caller's herdr `terminal_id` for *every* MCP call, via `PaneLocator.terminalForPid`
+(walks `pane.list`, matches the caller PID to a pane's process tree). It is non-null whenever
+the caller runs in a herdr pane on this host. Today it's discarded for the primary
+(`presence.markPresent` is a no-op on it).
+
+**Plan:** a single-slot `PrimaryRegistry` (thread-safe) holding the primary's `terminal_id`.
+Populate it from the **orchestration-side** MCP tools — `bridge_send`, `bridge_spawn`,
+`bridge_poll`, `bridge_list`, `bridge_status`, `bridge_profiles` — capturing
+`callerTerminal(exchange)` when it is (a) non-null and (b) **not** a registered worker
+session in `SessionManager`. That caller is, by construction, the primary. Worker-side tools
+(`bridge_reply`, `bridge_ask`) never set it.
+
+- **Config override / pin:** a `primary: { terminal: "<id>" }` block in `BridgedConfig`
+  (nested record, same shape as `Broker`). Lets an operator pin it, or supply it when
+  derivation can't (see degrade case).
+- **Degrade:** if the primary is off-host or in a non-herdr terminal, `terminalForPid`
+  returns null and no override is set → **the registry stays empty → the push loop is a
+  no-op and we fall back to pull** (today's behaviour). The reply is never lost; it's just
+  not actively pushed. This is a safe, explicit degradation, not a failure.
+
+### Increment 2 — the push loop
+
+A `ReplyPushLoop` component, notified at the single no-waiter call site
+(`MessageService.reply` → the `inbox.publish` branch, `MessageService.java:192`).
+
+- **Inject a nudge, not the payload.** The injected turn tells the primary *to drain*
+  (e.g. "Worker `<target>` returned a reply — run `bridge_poll(target=<target>)` to collect
+  it"), it does **not** carry the reply text. Rationale: replies can be large/multiline and
+  terminal injection would mangle them; the drain response is the clean transport. Keeps the
+  push idempotent — re-nudging is harmless.
+- **Ack = drain.** The primary draining (`drainReplies` = peek + ack) is the acknowledgement.
+  The loop's **stop condition is `inbox.peek(target).isEmpty()`** — the reply is gone from the
+  inbox because it was acked. No new `bridge_ack` tool needed for v1 (see Increment 3).
+- **Status-gated injection (mechanism (b), chosen).** A dedicated lightweight scheduled loop,
+  **not** the worker `Injector`. It injects via `AgentControl.send(primaryTerminal, nudge)`
+  (the same herdr `agent.send` = `pane send-text` + submit that delivers to workers) only when
+  `AgentControl.status(primaryTerminal).injectable()` (IDLE/BLOCKED) — never mid-turn. This keeps
+  the primary path fully isolated from `WorkerPresence`/`StatusPoller` (which are worker-scoped),
+  and makes it unit-testable with a fake `AgentControl` + an injected clock (per the CB-306
+  `LongSupplier` clock + `Runnable` sleeper seam). Rejected (a) reuse-the-Injector: it would force
+  the primary terminal into the worker poller set and couple to worker-presence semantics — more
+  integration surface, harder to test, no real gain for a bounded reminder.
+- **Bounded reminder / backoff.** While `peek(target)` stays non-empty, re-inject on a
+  backoff schedule up to a cap (N reminders or a max duration; config
+  `primary.push_reminders` / `primary.push_backoff_ms`). After the cap, **stop reminding** —
+  the reply remains in the durable inbox and the next natural poll (or a later worker reply's
+  nudge) still surfaces it. Bounded so the bridge never spams the primary.
+
+### Increment 3 — optional per-`msgId` `bridge_ack` tool (deferred)
+
+Drain-as-ack is coarse: it clears *all* pending replies for a target at once. If finer
+control is ever needed (ack one reply, leave others held), add a `bridge_ack(msgId)` tool
+mapping to `inbox.ack(target, msgId)` — the port already supports per-`msgId` ack. Not built
+in v1; the stop-on-empty loop is sufficient.
+
+## The two subtleties (decided here)
+
+1. **Which caller is "the primary"?** Connection-derived, not self-reported: the caller whose
+   resolved terminal is non-null **and not a registered worker session**, seen on an
+   orchestration-side tool. This never mislabels a worker (workers are in `SessionManager`)
+   and needs no new env var or argument (identity stays connection-derived, per the existing
+   `BridgeMcp` invariant).
+
+2. **Readiness-gate mismatch → dedicated loop.** The existing `Injector` gates delivery on
+   `ready.test(target)` = `WorkerPresence` (the *worker's* MCP connected). The primary is not
+   in `WorkerPresence`, so reusing `Injector` would mean forcing the primary terminal into the
+   worker `StatusPoller` set and swapping the `ready` predicate — extra integration surface with
+   worker-scoped machinery. Decision: **mechanism (b)** — a small dedicated scheduled loop that
+   calls `AgentControl.status(primaryTerminal).injectable()` then `AgentControl.send(...)`, with
+   an injected clock. Isolated from worker presence, trivially unit-testable, sufficient for a
+   bounded reminder. (Verified live: this primary resolves to `term_656c8cc03e1f0b1`, pane
+   `w2:pY` — the primary genuinely runs in a herdr pane on this host, so the path is exercisable.)
+
+## Boundary note
+
+This is the first time the bridge **writes into the primary's pane** — a new direction of
+control. It stays within the communication-bus identity: the injection is a **nudge** (a
+synthetic "go drain your replies" turn), **status-gated** so it never interrupts a turn,
+**bounded** so it never spams, carries **no env** and **never crosses the subscription
+boundary**. The bridge is signalling the primary that it has mail — not driving its work.
+
+## Test plan
+
+- **Unit (hermetic):** `PrimaryRegistry` set/clear/override; the "caller is primary iff
+  non-null terminal AND not a registered session" predicate; the loop's stop-on-empty and
+  bounded-reminder logic with an injected clock + a fake injector (no real herdr).
+- **Live dogfood (primary-side):** with the daemon on the broker jar + a real worker,
+  delegate a task, let the worker reply after the `bridge_send` window closes, and observe the
+  bridge inject a drain nudge into *this* primary pane; confirm draining stops the reminders;
+  confirm an unreachable primary (registry empty) degrades to pull with no loss.
+
+## Out of scope
+
+Multi-host (CB-308) — the push loop is local-only; a remote primary is reached by its own
+local gateway, not cross-host injection. Federation reuses this loop per-gateway.

bridged/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>dev.ltms</groupId>
     <artifactId>bridged</artifactId>
-    <version>0.1.0-SNAPSHOT</version>
+    <version>1.0.0</version>
     <packaging>jar</packaging>
 
     <name>bridged</name>
@@ -17,13 +17,74 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <mainClass>dev.ltms.bridged.Bridged</mainClass>
 
-        <jackson.version>2.18.2</jackson.version>
-        <javalin.version>6.3.0</javalin.version>
+        <jackson.version>2.19.0</jackson.version>
+        <javalin.version>6.7.0</javalin.version>
+        <jetty.version>11.0.25</jetty.version>
+        <mcp.version>2.0.0</mcp.version>
         <slf4j.version>2.0.16</slf4j.version>
-        <logback.version>1.5.15</logback.version>
+        <logback.version>1.5.18</logback.version>
         <junit.version>5.11.4</junit.version>
+        <amqp.version>5.22.0</amqp.version>
+        <testcontainers.version>1.20.4</testcontainers.version>
+        <commons-compress.version>1.27.1</commons-compress.version>
+        <commons-lang3.version>3.18.0</commons-lang3.version>
     </properties>
 
+    <!--
+      Dependency security (validate with the JetBrains analyzer's Mend.io check on this pom).
+      Deps are pinned to the latest available versions. Residual advisories with NO upstream fix,
+      accepted for this loopback-bound daemon that processes no untrusted config:
+        - jetty-http 11.0.25 (via Javalin): CVE-2026-2332, CVE-2025-11143 — Jetty 11 is EOL;
+          fixed only in Jetty 12, which needs a Javalin major (6.x rides Jetty 11).
+        - logback-core 1.5.18: CVE-2025-11226, CVE-2026-1225 — both require a MALICIOUS
+          logback.xml (attacker with config write already has code execution); ours is trusted.
+        - jackson-core 2.19.0: WS-2026-0003 — "insufficient information", no fixed version published.
+        - tools.jackson.core (Jackson 3) 3.0.3 via the MCP SDK: CVE-2026-29062 (nesting-depth
+          resource exhaustion). The SDK 2.0.0 is pinned to Jackson 3.0.3 + jackson-annotations
+          3.0-rc5; bumping Jackson 3 to the patched 3.2.x breaks the SDK (annotation mismatch).
+          Only the loopback /mcp endpoint parses this JSON, from trusted local Claude clients.
+      The 11.0.23 -> 11.0.25 bump did clear jetty CVE-2024-8184 (5.9) and CVE-2024-6763.
+    -->
+
+    <!-- Force the latest patched Jetty 11.x across all Javalin-pulled Jetty modules (no version
+         skew). Javalin 6.x rides Jetty 11; a move to Jetty 12 needs a Javalin major. -->
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.eclipse.jetty</groupId>
+                <artifactId>jetty-bom</artifactId>
+                <version>${jetty.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+            <!-- The MCP SDK (Jackson 3) needs jackson-annotations with JsonFormat.Shape.POJO
+                 (the 3.0 line); it shares the com.fasterxml.jackson.annotation package with our
+                 Jackson 2.19 databind, so both must resolve to the same jar. 3.0 is built to work
+                 with Jackson 2.19 databind too — pin it to reconcile the two. -->
+            <dependency>
+                <groupId>com.fasterxml.jackson.core</groupId>
+                <artifactId>jackson-annotations</artifactId>
+                <version>3.0-rc5</version>
+            </dependency>
+            <!-- Testcontainers 1.20.4 pulls commons-compress 1.24.0 (test scope), which carries
+                 CVE-2024-25710 (8.1) + CVE-2024-26308 — both fixed in 1.26.0. Pin the patched line.
+                 Test-scope only (never shipped in the jar), but bumped per the CVE policy. -->
+            <dependency>
+                <groupId>org.apache.commons</groupId>
+                <artifactId>commons-compress</artifactId>
+                <version>${commons-compress.version}</version>
+            </dependency>
+            <!-- Testcontainers 1.20.4 also pulls commons-lang3 3.16.0 (test scope): CVE-2025-48924
+                 (uncontrolled recursion in ClassUtils), fixed in 3.18.0. Pin the patched line.
+                 Test-scope only (never shipped in the jar), bumped per the CVE policy. -->
+            <dependency>
+                <groupId>org.apache.commons</groupId>
+                <artifactId>commons-lang3</artifactId>
+                <version>${commons-lang3.version}</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
     <dependencies>
         <!-- JSON + YAML (config, herdr wire format, REST bodies) -->
         <dependency>
@@ -44,6 +105,24 @@
             <version>${javalin.version}</version>
         </dependency>
 
+        <!-- MCP server: the SERVER face. Streamable-HTTP servlet mounted on Javalin's Jetty at
+             /mcp, exposing bridge_send/bridge_reply/bridge_status as thin adapters over REST. -->
+        <dependency>
+            <groupId>io.modelcontextprotocol.sdk</groupId>
+            <artifactId>mcp</artifactId>
+            <version>${mcp.version}</version>
+        </dependency>
+
+        <!-- Broker client (CB-307 Stage 2): AMQP 0-9-1. Default deploy targets LavinMQ; this same
+             client speaks to RabbitMQ unchanged (URI-only swap), so integration tests run against a
+             stock RabbitMQ container. Only wired when a broker: block is present in config; absent →
+             the in-memory ReplyInbox. -->
+        <dependency>
+            <groupId>com.rabbitmq</groupId>
+            <artifactId>amqp-client</artifactId>
+            <version>${amqp.version}</version>
+        </dependency>
+
         <!-- Logging -->
         <dependency>
             <groupId>org.slf4j</groupId>
@@ -63,6 +142,22 @@
             <version>${junit.version}</version>
             <scope>test</scope>
         </dependency>
+
+        <!-- Testcontainers RabbitMQ: spins a real broker for the @Tag("contract") AMQP integration
+             test only. Excluded from the default build (contract group), so `mvn clean install`
+             stays hermetic and green without Docker; run under -Pcontract with Docker present. -->
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>rabbitmq</artifactId>
+            <version>${testcontainers.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${testcontainers.version}</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -74,6 +169,30 @@
                 <version>3.14.0</version>
             </plugin>
 
+            <!--
+              Coverage (CB-509). Build-time tooling only — never a compile/runtime dependency, so
+              it adds nothing to the shipped jar. Report lands at target/site/jacoco/index.html and
+              target/site/jacoco/jacoco.csv. No `check` rule / threshold is wired: a coverage gate
+              rewards writing tests that execute lines, which is the failure mode this project is
+              trying to avoid, not encourage.
+            -->
+            <plugin>
+                <groupId>org.jacoco</groupId>
+                <artifactId>jacoco-maven-plugin</artifactId>
+                <version>0.8.13</version>
+                <executions>
+                    <execution>
+                        <id>prepare-agent</id>
+                        <goals><goal>prepare-agent</goal></goals>
+                    </execution>
+                    <execution>
+                        <id>report</id>
+                        <phase>test</phase>
+                        <goals><goal>report</goal></goals>
+                    </execution>
+                </executions>
+            </plugin>
+
             <!-- Unit tests run by default; contract tests (live herdr) are tag-excluded. -->
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -116,7 +235,27 @@
         </profile>
         <profile>
             <id>contract</id>
-            <properties><excludedGroups></excludedGroups></properties>
+            <properties><excludedGroups/></properties>
+            <build>
+                <plugins>
+                    <plugin>
+                        <artifactId>maven-surefire-plugin</artifactId>
+                        <configuration>
+                            <!-- Docker-engine compat (see "Running the contract tests" in
+                                 docs/CB-307-Reliable-Delivery.md): Testcontainers 1.20.4's docker-java
+                                 client defaults to Docker API 1.32 when no version is set, but modern
+                                 engines (OrbStack on this dev host, min 1.40) reject that as too old —
+                                 which surfaces as "Could not find a valid Docker environment". Pinning
+                                 api.version=1.43 works on OrbStack and Docker 24+, and is overridable
+                                 per-host via -Dapi.version. Only active under -Pcontract, so the
+                                 default hermetic build never sets it. -->
+                            <systemPropertyVariables>
+                                <api.version>1.43</api.version>
+                            </systemPropertyVariables>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
         </profile>
     </profiles>
 </project>

bridged/src/main/java/dev/ltms/bridged/Bridged.java

@@ -1,19 +1,65 @@
 package dev.ltms.bridged;
 
 import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.config.ConfigRef;
+import dev.ltms.bridged.config.ConfigWatcher;
 import dev.ltms.bridged.guard.SubscriptionGuard;
 import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.HerdrClient;
+import dev.ltms.bridged.herdr.HerdrException;
+import dev.ltms.bridged.herdr.LeadTabScanner;
+import dev.ltms.bridged.lead.LeadLauncher;
+import dev.ltms.bridged.herdr.PaneLocator;
 import dev.ltms.bridged.herdr.UnixSocketHerdrClient;
 import dev.ltms.bridged.herdr.WorkspaceControl;
+import dev.ltms.bridged.inject.CompletionResolver;
 import dev.ltms.bridged.inject.Injector;
 import dev.ltms.bridged.inject.StatusPoller;
+import dev.ltms.bridged.inject.TurnListener;
+import dev.ltms.bridged.inject.MemberPresence;
+import dev.ltms.bridged.auth.MemberRegistry;
+import dev.ltms.bridged.auth.CallerResolver;
+import dev.ltms.bridged.mcp.BridgeMcp;
+import dev.ltms.bridged.mcp.ConnectionIdentity;
+import dev.ltms.bridged.metrics.BridgedMetrics;
+import dev.ltms.bridged.metrics.Metrics;
+import dev.ltms.bridged.mcp.PrimaryRegistry;
+import dev.ltms.bridged.mcp.LsofPeerPidLookup;
+import dev.ltms.bridged.mcp.LsofProcessCwdLookup;
+import dev.ltms.bridged.msg.AmqpReplyInbox;
+import dev.ltms.bridged.msg.InMemoryReplyInbox;
+import dev.ltms.bridged.msg.MessageService;
+import dev.ltms.bridged.msg.Rendezvous;
+import dev.ltms.bridged.msg.ReplyInbox;
+import dev.ltms.bridged.msg.LeadHeartbeatLoop;
+import dev.ltms.bridged.msg.ReplyPushLoop;
 import dev.ltms.bridged.rest.BridgedApp;
-import dev.ltms.bridged.worker.WorkerService;
+import dev.ltms.bridged.session.GitWorktrees;
+import dev.ltms.bridged.session.SessionManager;
+import dev.ltms.bridged.peer.PeerLauncher;
+import dev.ltms.bridged.session.SessionReaper;
+import dev.ltms.bridged.member.ClaudeCodeLauncher;
+import dev.ltms.bridged.member.CompositePeerLauncher;
+import dev.ltms.bridged.member.HerdrPeerLauncher;
+import dev.ltms.bridged.member.OpenCodeLauncher;
 import io.javalin.Javalin;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Function;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+import java.util.stream.Collectors;
 
 /**
  * {@code bridged} entry point. Wires the real herdr socket client to the REST app and
@@ -27,38 +73,416 @@ public final class Bridged {
     /** How often the injector samples a busy worker's status while it has queued work. */
     private static final long INJECT_POLL_MILLIS = 250;
 
+    /** CB-504: how long to wait at startup for herdr's socket before serving degraded. */
+    private static final long HERDR_WAIT_SECONDS = 30;
+    private static final long HERDR_WAIT_POLL_MILLIS = 500;
+
     static void main(String[] args) {
         Path configPath = Path.of(args.length > 0 ? args[0] : "bridged.yaml");
         BridgedConfig cfg = BridgedConfig.load(configPath);
+        // CB-559: `cfg` stays the startup snapshot — every validation and every piece of one-time
+        // wiring below reads it, and must, because those decisions cannot be unmade. `config` is the
+        // live reference the hot paths read per use. Which keys can actually move is ConfigRef's
+        // contract; adding a reader here does not make a key reloadable by itself.
+        ConfigRef config = new ConfigRef(configPath, cfg);
 
         // The primary/host env that launched bridged must not be tainted.
         SubscriptionGuard guard = new SubscriptionGuard(cfg.guard().hostSet());
         guard.assertPrimaryClean(System.getenv());
 
+        // CB-501: refuse to start if the bind is wider than the auth mode can defend. Under
+        // loopback-trust, "not a known worker" means "the primary" — sound only because the OS
+        // refuses remote connections to a loopback socket. This throws rather than warns so the
+        // dangerous configuration cannot be reached by ignoring a log line.
+        cfg.validateAuthExposure();
+        cfg.validateLeadTabPrefixes();
+        // CB-542: a subscription:true profile whose env: reseats ANTHROPIC_BASE_URL/AUTH_TOKEN would
+        // reach an unguarded endpoint (the launcher skips SubscriptionGuard for it). Refuse at load.
+        cfg.validateSubscriptionProfiles();
+        // CB-548: every architect slot must name a configured workers: profile — the strong-model
+        // backend the future spawn lifecycle would read. A stale reference dies here, not later.
+        cfg.validateMembers();
+
         Path socket = cfg.herdrSocket() != null && !cfg.herdrSocket().isBlank()
                 ? Path.of(cfg.herdrSocket())
                 : UnixSocketHerdrClient.defaultSocketPath();
 
         UnixSocketHerdrClient herdr = UnixSocketHerdrClient.connect(socket, new com.fasterxml.jackson.databind.ObjectMapper());
-        Runtime.getRuntime().addShutdownHook(new Thread(herdr::close));
 
         AgentControl agents = new AgentControl(herdr);
         WorkspaceControl spaces = new WorkspaceControl(herdr);
-        WorkerService workers = new WorkerService(agents, spaces, guard, cfg.worker(), System::getenv);
+        // CB-402: one adapter per configured peer kind, fronted by a composite router. A profile's
+        // `kind:` selects its adapter — claude-code (the default) and opencode partition the profile
+        // set — and the composite dispatches each SPI call to the adapter that owns the profile/pane.
+        Map<String, BridgedConfig.Profile> claudeProfiles = new LinkedHashMap<>();
+        Map<String, BridgedConfig.Profile> opencodeProfiles = new LinkedHashMap<>();
+        cfg.profiles().forEach((name, w) -> {
+            if (w.isOpenCode()) {
+                opencodeProfiles.put(name, w);
+            } else {
+                claudeProfiles.put(name, w);
+            }
+        });
+        List<HerdrPeerLauncher> adapters = new ArrayList<>();
+        // The claude-code adapter is the always-present default; keep it even with no profiles (so a
+        // bridge configured with no workers, or opencode-only, still has a well-defined base adapter)
+        // unless opencode is the only kind configured.
+        if (!claudeProfiles.isEmpty() || opencodeProfiles.isEmpty()) {
+            adapters.add(new ClaudeCodeLauncher(agents, spaces, guard,
+                    claudeProfiles, cfg.effectiveDefaultProfile(), System::getenv,
+                    cfg.spawnReadyTimeoutMs(), cfg.spawnReadyPollMs(),
+                    () -> config.get().fleet().tabLabel()));
+        }
+        if (!opencodeProfiles.isEmpty()) {
+            adapters.add(new OpenCodeLauncher(agents, spaces,
+                    opencodeProfiles, cfg.effectiveDefaultProfile(), System::getenv,
+                    cfg.spawnReadyTimeoutMs(), cfg.spawnReadyPollMs(),
+                    () -> config.get().fleet().tabLabel()));
+        }
+        AtomicReference<Function<String, Integer>> liveCountRef = new AtomicReference<>(_ -> 0);
+        PeerLauncher workers = new CompositePeerLauncher(
+                adapters,
+                cfg.effectiveDefaultProfile(),
+                config,
+                profileName -> liveCountRef.get().apply(profileName));
+        // CB-504: under supervision (launchd/systemd) bridged can start before herdr's socket
+        // exists. The client itself is lazy — it connects per call — but the orphan reap below is
+        // the first thing that actually talks to herdr, so without this wait a boot-order race
+        // would crash the daemon into a restart loop. Wait, then degrade rather than die: serving
+        // with /healthz reporting "degraded" is strictly more useful than exiting.
+        boolean herdrUp = awaitHerdr(herdr);
+        if (herdrUp) {
+            // CB-117: herdr keeps worker panes alive across a daemon restart, and their ids died
+            // with the previous process — reap those leaked orphans now, before we start serving.
+            workers.reapOrphanWorkers();
+        } else {
+            log.warn("herdr did not answer within {}s — starting anyway; /healthz will report "
+                    + "degraded until it comes up. Orphaned worker panes (if any) were NOT reaped.",
+                    HERDR_WAIT_SECONDS);
+        }
+
+        // CB-301: authoritative session registry + lifecycle FSM on top of ClaudeCodeLauncher.
+        // CB-301-ext: worktree provisioning seam, optionally rooted at a configured directory.
+        // CB-303 part 2: context cap is opt-in and disabled (0) when absent/null.
+        int contextCap = 0;
+        if (cfg.lifecycle() != null && cfg.lifecycle().contextCap() != null
+                && cfg.lifecycle().contextCap() > 0) {
+            contextCap = cfg.lifecycle().contextCap();
+        }
+        boolean clearAfterTurn = cfg.lifecycle() != null && cfg.lifecycle().clearAfterTurn();
+        SessionManager sessions = new SessionManager(workers, new GitWorktrees(cfg.worktreeRoot()),
+                System::nanoTime, contextCap, clearAfterTurn);
+        liveCountRef.set(profileName -> (int) sessions.roster().stream()
+                .filter(s -> profileName.equals(s.profile()))
+                .count());
+
+        // CB-303 part 1: idle-ttl reaper — only when configured, defaults to disabled.
+        final SessionReaper reaper;
+        if (cfg.lifecycle() != null
+                && cfg.lifecycle().idleTtlSeconds() != null
+                && cfg.lifecycle().idleTtlSeconds() > 0) {
+            reaper = new SessionReaper(sessions, cfg.lifecycle().idleTtlSeconds());
+            reaper.start();
+        } else {
+            reaper = null;
+        }
+
+        // CB-530: every pane the config names as a lead, merged from `leaders:` and the legacy
+        // singular pin. PrimaryRegistry below still tracks ONE terminal — it addresses the push
+        // loop's nudges, which need a single destination — so it keeps the legacy pin.
+        Map<String, String> leadTerminals = cfg.leaderTerminals();
+        if (leadTerminals.size() > 1) {
+            log.info("leads: {} panes recognised {}", leadTerminals.size(), leadTerminals.values());
+        }
+        // CB-531: on top of the static registry, discover leads by the tab labels the operator
+        // writes. CB-557 moved the settings onto the lead they describe, so scanning is on whenever
+        // a `fleet.leaders:` entry exists — with no leads configured the supplier is a constant and
+        // never touches herdr, exactly as a missing `leadScan:` block used to behave.
+        final Supplier<Map<String, String>> leads;
+        var leaders = cfg.fleet().leaders();
+        if (!leaders.isEmpty()) {
+            // One scanner, so one prefix and one interval. Distinct per-lead prefixes would need a
+            // scanner each; until a config actually wants that, take the first entry's settings and
+            // say so, rather than silently honouring one lead's prefix and dropping another's.
+            var scan = leaders.values().iterator().next();
+            Set<String> memberSpaces = cfg.profiles().values().stream()
+                    .map(BridgedConfig.Profile::workspace)
+                    .filter(Objects::nonNull)
+                    .collect(Collectors.toSet());
+            leads = new LeadTabScanner(herdr, scan.tabPrefix(), memberSpaces, leadTerminals,
+                    TimeUnit.SECONDS.toNanos(scan.scanIntervalSeconds()), System::nanoTime);
+            log.info("lead scan: tabs labelled '{}…' host a lead (rescan every {}s, member spaces {} "
+                            + "excluded)",
+                    scan.tabPrefix(), scan.scanIntervalSeconds(), memberSpaces);
+            long distinctPrefixes = leaders.values().stream()
+                    .map(BridgedConfig.Leader::tabPrefix).distinct().count();
+            if (distinctPrefixes > 1) {
+                log.warn("fleet.leaders declares {} different tabPrefix values; only '{}' is scanned "
+                                + "for. Give every lead the same tabPrefix, or leads under the others "
+                                + "will not be discovered.",
+                        distinctPrefixes, scan.tabPrefix());
+            }
+        } else {
+            leads = () -> leadTerminals;
+        }
+
+        // CB-558: start any declared lead that is not already running. After the scanner is built,
+        // because both read the same tab labels and the ordering makes that dependency visible; and
+        // only when herdr answered, because the launcher's whole safety property is that it can
+        // count live leads first — it must never guess and risk a second orchestrator.
+        if (herdrUp && !leaders.isEmpty()) {
+            int launched = new LeadLauncher(agents, spaces, cfg).ensureLeads();
+            if (launched > 0) {
+                log.info("lead auto-launch: {} lead(s) started", launched);
+            }
+        }
+
+        // CB-548: config-declared architect slots. Config supplies only the stable name → profile
+        // map; the terminal → slot binding is owned by the registry and is empty at startup, so no
+        // pane resolves to an architect until the later spawn lifecycle binds one. The registry is
+        // what CallerResolver resolves against and what that lifecycle will read profiles from;
+        // nothing here spawns a slot.
+        MemberRegistry members = new MemberRegistry(cfg.fleet());
+        if (!members.slots().isEmpty()) {
+            log.info("member slots: {} configured {} — none bound yet (a slot is idle until the "
+                            + "spawn lifecycle binds a live terminal to it)",
+                    members.slots().size(), members.slots().keySet());
+        }
 
         // Status-gated injector (CB-103): the single writer into workers, fed by a poller.
         // The blocking message endpoint (CB-104) is the producer; the poller is inert until then.
-        Injector injector = new Injector(agents);
+        // CB-106: a confirmed turn completion resolves a blocked send whose worker never replied.
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver completion = new CompletionResolver(agents, rendezvous);
+        // CB-113: deliver only to an available worker (its MCP is connected), never its boot window.
+        // CB-301: the manager's presence bridge records availability and drives SPAWNING → READY.
+        MemberPresence presence = sessions.asPresence();
+        TurnListener turnListener = new TurnListener() {
+            @Override
+            public void onTurnComplete(String target) {
+                completion.onTurnComplete(target);
+                sessions.onTurnComplete(target);
+            }
+
+            @Override
+            public boolean hasPostTurnAction(String target) {
+                return sessions.hasPostTurnAction(target);
+            }
+
+            @Override
+            public boolean onTurnCompleteWithPostAction(String target) {
+                completion.resolveBeforePostAction(target);
+                return sessions.onTurnCompleteWithPostAction(target);
+            }
+
+            @Override
+            public void onDelivered(String target) {
+                completion.onDelivered(target);
+                sessions.onDelivered(target);
+            }
+
+            @Override
+            public void onTurnFailed(String target) {
+                completion.onTurnFailed(target);
+                sessions.onTurnFailed(target);
+            }
+        };
+        Injector injector = new Injector(agents, turnListener, deliverableTo(presence, leads),
+                presence::forget);
         StatusPoller poller = new StatusPoller(agents, injector, INJECT_POLL_MILLIS);
         poller.start();
-        Runtime.getRuntime().addShutdownHook(new Thread(poller::stop));
 
-        Javalin app = new BridgedApp(herdr, workers).build();
+        // CB-307: reply inbox. A broker: block (with a uri) selects the AMQP-backed durable adapter;
+        // absent, bridged stays soft-state on the in-memory inbox. The AMQP inbox owns a broker
+        // connection, so keep the reference to close it in the ordered shutdown hook.
+        final ReplyInbox replyInbox;
+        if (cfg.broker() != null && cfg.broker().isConfigured()) {
+            replyInbox = AmqpReplyInbox.open(cfg.broker().uri());
+            log.info("reply inbox: AMQP broker (durable) at {}", cfg.broker().uri());
+        } else {
+            replyInbox = new InMemoryReplyInbox();
+            log.info("reply inbox: in-memory (soft-state)");
+        }
+        // CB-307: learn the primary's terminal from orchestration tool calls (or pin from config).
+        // The pin also feeds CallerResolver below: a primary running inside a herdr pane would
+        // otherwise resolve as a worker and be refused every orchestration tool.
+        String pinnedPrimaryTerminal = cfg.primary() != null ? cfg.primary().terminal() : null;
+        PrimaryRegistry primaryRegistry = new PrimaryRegistry(pinnedPrimaryTerminal);
+        // CB-532: `primary.terminal` is superseded and no longer needed for either of its jobs —
+        // identity comes from `leaders:`/`leadScan:`, and reply nudges now follow the delegating
+        // lead. Say so once at startup rather than leaving a redundant pin to look load-bearing.
+        if (pinnedPrimaryTerminal != null && !pinnedPrimaryTerminal.isBlank()) {
+            log.warn("primary.terminal is DEPRECATED (CB-532) and can be deleted: identity now comes "
+                    + "from leaders:/leadScan:, and reply nudges follow the lead that delegated. "
+                    + "It still works, and is still the fallback nudge destination when a restart "
+                    + "has lost the delegation map. Its pushReminders/pushBackoffMs stay valid.");
+        }
+        // CB-307: active push-to-primary loop — nudge the primary when replies land without an
+        // open bridge_send. Uses its own lightweight scheduled executor, separate from the injector.
+        int maxReminders = cfg.primary() != null ? cfg.primary().remindersOrDefault() : 5;
+        long backoffMs = cfg.primary() != null ? cfg.primary().backoffMsOrDefault() : 15_000L;
+        var pushScheduler = Executors.newSingleThreadScheduledExecutor(r ->
+                Thread.ofVirtual().name("bridge-push-").unstarted(r));
+        // CB-502: the registry is built before the service and the push loop so send/reply outcomes
+        // are counted at their single funnel rather than at each of the two caller-facing surfaces.
+        // CB-512: the push loop takes it too, so nudge outcomes (delivered|exhausted) are counted.
+        Metrics metrics = BridgedMetrics.create(sessions, replyInbox);
+        var pushLoop = new ReplyPushLoop(primaryRegistry, agents, replyInbox,
+                pushScheduler, maxReminders, backoffMs, metrics);
+        // CB-551: idle-lead heartbeat. Opt-in; absent `leadHeartbeat:` this is never constructed, so
+        // an upgraded daemon cannot silently start spending subscription on nudging an idle lead.
+        // It has its own single-thread scheduler and holds its own scheduler shutdown via close().
+        final LeadHeartbeatLoop heartbeat;
+        var heartbeatScheduler = Executors.newSingleThreadScheduledExecutor(r ->
+                Thread.ofVirtual().name("bridge-heartbeat-").unstarted(r));
+        if (cfg.leadHeartbeat() != null) {
+            var hb = cfg.leadHeartbeat();
+            heartbeat = new LeadHeartbeatLoop(primaryRegistry, agents, replyInbox, sessions::roster,
+                    pushLoop, heartbeatScheduler, System::nanoTime,
+                    TimeUnit.SECONDS.toNanos(hb.idleAfterSeconds()), hb.backoffMs(), hb.quietNudgeCap(),
+                    metrics);
+            heartbeat.start();
+        } else {
+            heartbeat = null;
+            heartbeatScheduler.shutdownNow();
+        }
+        MessageService messages = new MessageService(agents, injector, rendezvous, replyInbox,
+                pushLoop, metrics);
+
+        // CB-520: the reply inbox only consumes for agents this gateway owns. own on acquire,
+        // release on teardown. Do this before CB-516 so the inbox is owned before any reply can land.
+        sessions.onAcquire(replyInbox::own);
+        // CB-516: releasing a worker must fail whatever send was waiting on it. Without this a
+        // torn-down delegation kept reporting PENDING until the 30-minute async timeout, and never
+        // reached /metrics — the delegation was unresolvable and nothing said so.
+        sessions.onRelease(terminal -> {
+            messages.abandon(terminal, "the worker session was released before it replied");
+            replyInbox.release(terminal);
+            primaryRegistry.forgetDelegation(terminal); // CB-532: don't leak the lead binding
+        });
+
+        // MCP server face (CB-105): bridge_send/bridge_reply/bridge_status, mounted at /mcp.
+        // Caller identity is resolved from the connection (peer PID → herdr pane), not arguments.
+        ConnectionIdentity identity = new ConnectionIdentity(
+                new PaneLocator(herdr), new LsofPeerPidLookup(), new LsofProcessCwdLookup());
+
+        // CB-501: one resolver behind both entry paths. Worker identity still comes from the
+        // connection and is never token-gated, so enabling token mode cannot lock the fleet out.
+        final CallerResolver callers;
+        if (cfg.auth().tokenMode()) {
+            String token = System.getenv(cfg.auth().tokenEnv());
+            if (token == null || token.isBlank()) {
+                throw new IllegalStateException("auth.mode=token but env var " + cfg.auth().tokenEnv()
+                        + " is unset or empty — export it before starting bridged");
+            }
+            callers = CallerResolver.withLeadsAndMembers(identity, true, token, leads,
+                    members::snapshot);
+            log.info("auth: token mode (bearer required for non-worker callers, env {})",
+                    cfg.auth().tokenEnv());
+        } else {
+            callers = CallerResolver.withLeadsAndMembers(identity, false, null, leads,
+                    members::snapshot);
+            log.info("auth: loopback-trust (any loopback non-worker caller is the primary)");
+        }
+
+        BridgeMcp mcp = new BridgeMcp(messages, workers, sessions, identity, presence,
+                primaryRegistry, callers, metrics);
+
+        // CB-559: opt-in config reload. With no `configReload:` block nothing is constructed, so an
+        // upgraded daemon behaves exactly as before — the file is read once at boot and never again.
+        final ConfigWatcher configWatcher;
+        if (cfg.configReload() != null && cfg.configReload().isEnabled()) {
+            configWatcher = new ConfigWatcher(config, cfg.configReload().intervalSeconds());
+            configWatcher.start();
+        } else {
+            configWatcher = null;
+        }
+
+        // CB-303 part 3: single ordered shutdown hook. Drain sessions first while herdr is still
+        // open (so releases reach the daemon), then stop poller/message/mcp/reaper, and close herdr
+        // last. This replaces the earlier independent hooks that could race and close herdr early.
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            sessions.close(cfg.lifecycle() != null ? cfg.lifecycle().drainTimeoutSeconds() : null);
+            poller.stop();
+            messages.close();
+            pushLoop.close();
+            if (heartbeat != null) heartbeat.close(); // CB-551: stop the idle-lead heartbeat scheduler
+            if (configWatcher != null) configWatcher.stop(); // CB-559: stop polling the config file
+            mcp.close();
+            if (reaper != null) reaper.stop();
+            // Release the broker connection last among message resources (no-op for the in-memory inbox).
+            if (replyInbox instanceof AutoCloseable closeable) {
+                try {
+                    closeable.close();
+                } catch (Exception e) {
+                    log.debug("reply inbox close: {}", e.toString());
+                }
+            }
+            herdr.close();
+        }));
+
+        Javalin app = new BridgedApp(herdr, workers, sessions, messages, presence, mcp.servlet(),
+                callers, metrics).build();
         app.start(cfg.bind().host(), cfg.bind().port());
         log.info("bridged listening on {}:{}, herdr socket {}",
                 cfg.bind().host(), cfg.bind().port(), socket);
     }
 
+    /**
+     * The {@link Injector}'s readiness gate (CB-534): a target is deliverable if it is a worker whose
+     * agent has connected the bridge MCP, <em>or</em> a lead.
+     *
+     * <p>The gate exists for one reason — to hold a delivery out of a <em>spawned</em> worker's boot
+     * window, where herdr already reports {@code idle} but the TUI would drop an injected paste. That
+     * hazard is a property of spawning. A lead is never spawned: the operator started it and named it
+     * (or labelled its tab) only once it was up, so there is no boot window to guard.
+     *
+     * <p>A lead is also never enrolled in {@link MemberPresence} — {@code BridgeMcp} marks presence
+     * only for a worker, deliberately, since that map doubles as the worker roster's availability
+     * signal and a lead counted there would show up as an available worker. So without the second
+     * disjunct a lead is permanently un-deliverable: every lead→lead send sat on the gate for
+     * {@code READINESS_GRACE_POLLS} (~60s) and then failed having never been typed into the pane.
+     *
+     * <p>The lead set is read through the supplier on each call rather than snapshotted, so a lead
+     * discovered by {@code leadScan} after startup becomes deliverable without a restart.
+     */
+    static Predicate<String> deliverableTo(MemberPresence presence, Supplier<Map<String, String>> leads) {
+        return target -> presence.isPresent(target) || leads.get().containsKey(target);
+    }
+
+    /**
+     * Poll herdr's {@code ping} until it answers or {@link #HERDR_WAIT_SECONDS} elapses (CB-504).
+     *
+     * @return true if herdr answered, false if it never did
+     */
+    private static boolean awaitHerdr(HerdrClient herdr) {
+        long deadline = System.nanoTime() + HERDR_WAIT_SECONDS * 1_000_000_000L;
+        boolean waited = false;
+        while (true) {
+            try {
+                herdr.call("ping");
+                if (waited) {
+                    log.info("herdr is up");
+                }
+                return true;
+            } catch (HerdrException e) {
+                if (System.nanoTime() >= deadline) {
+                    return false;
+                }
+                if (!waited) {
+                    log.info("waiting up to {}s for the herdr socket…", HERDR_WAIT_SECONDS);
+                    waited = true;
+                }
+                try {
+                    Thread.sleep(HERDR_WAIT_POLL_MILLIS);
+                } catch (InterruptedException ie) {
+                    Thread.currentThread().interrupt();
+                    return false;
+                }
+            }
+        }
+    }
+
     private Bridged() {
     }
 }

bridged/src/main/java/dev/ltms/bridged/auth/AuditLog.java

@@ -0,0 +1,72 @@
+package dev.ltms.bridged.auth;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+
+/**
+ * Append-only record of privileged actions (CB-505).
+ *
+ * <p>Writes JSON lines to a dedicated {@code audit} logger — its own appender, separate from the
+ * chatty app log — so the trail stays greppable and can later be shipped without dragging debug
+ * noise along.
+ *
+ * <p><strong>Message content is never recorded.</strong> This bridge carries the user's source
+ * code, diffs, and prompts; an audit trail that quietly accumulated them would be a transcript
+ * archive wearing a security control's clothing. Records carry <em>who / what / against what /
+ * outcome</em> and correlation ids only.
+ */
+public final class AuditLog {
+
+    private static final Logger AUDIT = LoggerFactory.getLogger("audit");
+    private static final DateTimeFormatter TS =
+            DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSXXX").withZone(ZoneOffset.UTC);
+
+    private AuditLog() {
+    }
+
+    /** Record an allowed action. */
+    public static void allowed(Principal caller, Authz.Action action, String target) {
+        write(caller, action, target, "allowed", null);
+    }
+
+    /** Record a refused action and why. */
+    public static void denied(Principal caller, Authz.Action action, String target, String reason) {
+        write(caller, action, target, "denied", reason);
+    }
+
+    /** Record an action that was authorized but then failed downstream (guard, timeout, herdr). */
+    public static void failed(Principal caller, Authz.Action action, String target, String reason) {
+        write(caller, action, target, "failed", reason);
+    }
+
+    private static void write(Principal caller, Authz.Action action, String target,
+                              String outcome, String reason) {
+        Principal c = caller != null ? caller : Principal.anonymous();
+        StringBuilder sb = new StringBuilder(200);
+        // The timestamp is built here rather than by the appender pattern: a pattern that wrapped
+        // literal braces around the message collides with logback's own variable substitution.
+        sb.append("{\"ts\":\"").append(TS.format(Instant.now())).append('"')
+                .append(",\"role\":\"").append(c.role()).append('"')
+                .append(",\"actor\":\"").append(esc(c.describe())).append('"')
+                .append(",\"pid\":").append(c.pid())
+                .append(",\"action\":\"").append(action).append('"')
+                .append(",\"target\":").append(target == null ? "null" : '"' + esc(target) + '"')
+                .append(",\"outcome\":\"").append(outcome).append('"');
+        if (reason != null) {
+            sb.append(",\"reason\":\"").append(esc(reason)).append('"');
+        }
+        sb.append('}');
+        // The appender supplies the timestamp, so it cannot disagree with the app log's clock.
+        AUDIT.info(sb.toString());
+    }
+
+    /** Minimal JSON string escaping — these values are ids and short reasons, never free text. */
+    private static String esc(String s) {
+        return s.replace("\\", "\\\\").replace("\"", "\\\"")
+                .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t");
+    }
+}

bridged/src/main/java/dev/ltms/bridged/auth/Authz.java

@@ -0,0 +1,82 @@
+package dev.ltms.bridged.auth;
+
+/**
+ * The authorization table (CB-505), stated once and enforced on both entry paths.
+ *
+ * <p>Most of these rules are already true de facto — {@code BridgeMcp} derives a worker's identity
+ * from the connection rather than reading it from an argument, so a worker has never been able to
+ * reply <em>as</em> another worker over MCP. What was missing is that the REST surface trusted the
+ * session id in the URL path, and neither surface checked role at all. This class makes the
+ * invariant explicit and testable rather than emergent.
+ */
+public final class Authz {
+
+    private Authz() {
+    }
+
+    /** A privileged operation, named for the audit trail. */
+    public enum Action {
+        /** Spawn a worker peer. */
+        SPAWN,
+        /** Tear a worker peer down. */
+        STOP,
+        /** Deliver a turn to a session (or answer a worker's question). */
+        SEND,
+        /** A worker's terminal reply for its own turn. */
+        REPLY,
+        /** A worker's mid-turn question to the primary. */
+        ASK,
+        /** Collect held replies from a session's inbox. */
+        DRAIN,
+        /** Read-only observation: status, roster, profiles, task polling. */
+        READ,
+        /** Scrape the metrics endpoint. */
+        METRICS
+    }
+
+    /**
+     * Whether {@code caller} may perform {@code action} against {@code targetSession}.
+     *
+     * @param targetSession the session id in the request path; only consulted for the worker-scoped
+     *                      actions ({@code REPLY}, {@code ASK}), ignored otherwise, may be
+     *                      {@code null}
+     */
+    public static boolean permits(Principal caller, Action action, String targetSession) {
+        if (caller == null || caller.isAnonymous()) {
+            return false; // authenticated as nothing ⇒ authorized for nothing
+        }
+        return switch (action) {
+            // Fleet lifecycle is the primary's alone — spawn, stop, drain. An architect
+            // deliberately does NOT get these (CB-548), so it cannot tear down or stand up workers
+            // even though it coordinates them; and a worker driving any of these would be a worker
+            // escalating into the orchestrator role.
+            case SPAWN, STOP, DRAIN -> caller.isPrimary();
+
+            // Delivering a turn is open to the primary and the architect: an architect delegates
+            // to workers (that is the role's point) but still has no lifecycle rights. A worker is
+            // excluded — sending would be it escalating.
+            case SEND -> caller.isPrimary() || caller.isArchitect();
+
+            // The load-bearing rule: a caller acts only as the pane it occupies. CB-532 widened who
+            // that can be — a lead answering another lead is replying for its OWN terminal, which
+            // this already permits — while the rule itself is unchanged, and is what stops anyone
+            // forging a reply for a rendezvous someone else is waiting on. An architect's own pane
+            // passes through the same check, so it can answer a funnel that delegated to it. An
+            // unnamed primary (token/loopback, no pane) owns nothing and is still excluded.
+            case REPLY, ASK -> caller.ownsSession(targetSession);
+
+            // Observation is open to every authenticated role: a worker legitimately polls its own
+            // status, and the roster carries no secrets.
+            case READ, METRICS -> caller.isPrimary() || caller.isWorker() || caller.isArchitect();
+        };
+    }
+
+    /**
+     * Why a request was refused, for the error body. Distinguishes "you are nobody" from "you are
+     * somebody, but not the right somebody" — the first is a credential problem (401), the second
+     * an authorization one (403).
+     */
+    public static boolean isUnauthenticated(Principal caller) {
+        return caller == null || caller.isAnonymous();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/auth/CallerResolver.java

@@ -0,0 +1,260 @@
+package dev.ltms.bridged.auth;
+
+import dev.ltms.bridged.mcp.ConnectionIdentity;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.Map;
+import java.util.function.Supplier;
+
+/**
+ * Resolves every caller to a {@link Principal}, for both entry paths into the core (CB-501).
+ *
+ * <p>There are two of them and they are not layered the way the docs suggest: {@code BridgeMcp}
+ * calls the service layer directly and is mounted as a raw servlet (so it never passes through a
+ * Javalin filter), while the REST routes historically resolved no identity at all. Both now
+ * delegate here, so the authorization rules are stated once instead of drifting apart.
+ *
+ * <p><strong>Resolution order</strong> — connection identity first, token second, nothing third:
+ * <ol>
+ *   <li>A loopback peer PID that maps to a pane named by {@code leaders:}, by the legacy
+ *       {@code primary.terminal} pin, or by an operator-labelled lead tab (CB-307, CB-530, CB-531)
+ *       ⇒ {@link Role#PRIMARY}, carrying that lead's
+ *       name. The pane mapping is as unforgeable as a worker's, and the config explicitly names
+ *       that pane as a lead's own — without this rule a lead running <em>inside</em> a herdr pane
+ *       is misread as a worker and locked out of orchestration. More than one pane may be named,
+ *       so two leads can work as peers rather than one being demoted.</li>
+ *   <li>A loopback peer PID that maps to a pane bound to a CB-548 architect slot ⇒
+ *       {@link Role#ARCHITECT}, carrying the slot name. Just unforgeable as a worker's, and
+ *       resolved from the <em>live</em> terminal→slot binding (never a request argument), before
+ *       the generic worker fallback.</li>
+ *   <li>A loopback peer PID that maps to any other herdr pane ⇒ {@link Role#WORKER}. This is
+ *       unforgeable (the OS reports the PID, herdr owns the PID→pane map) and is honoured
+ *       regardless of auth mode, so enabling auth never breaks the fleet.</li>
+ *   <li>Otherwise, under {@code token} mode, a valid bearer token ⇒ {@link Role#PRIMARY}.</li>
+ *   <li>Otherwise, under {@code loopback-trust}, a loopback caller ⇒ {@link Role#PRIMARY}
+ *       (the historical behaviour, now an explicit configured choice).</li>
+ *   <li>Otherwise {@link Role#ANONYMOUS}.</li>
+ * </ol>
+ */
+public final class CallerResolver {
+
+    private final ConnectionIdentity identity;
+    private final boolean tokenMode;
+    private final byte[] expectedToken; // null unless tokenMode
+    /**
+     * terminal_id → lead name; empty when nothing is pinned. CB-530.
+     *
+     * <p>A supplier rather than a map because the registry is no longer fixed at startup: CB-531
+     * discovers leads by scanning herdr for operator-labelled tabs, so a lead that opens its tab
+     * after the daemon booted must still be recognised. Consulted per resolve; the scanner behind
+     * it is TTL-cached, so this is a map lookup in the common case.
+     */
+    private final Supplier<Map<String, String>> leadTerminals;
+    /**
+     * terminal_id → architect slot name; empty when nothing is configured. CB-548.
+     *
+     * <p>Like {@link #leadTerminals}, a supplier rather than a fixed map, so a binding injected
+     * after startup — when the later spawn lifecycle establishes a live architect session, or an
+     * operator pins one — takes effect without a restart. Consulted per resolve; today's wiring
+     * in {@code Bridged} reads a constant from config, which is the degenerate live case.
+     */
+    private final Supplier<Map<String, String>> architectTerminals;
+
+    /** Loopback-trust resolver: no token required, historical behaviour. */
+    public CallerResolver(ConnectionIdentity identity) {
+        this(identity, false, null, Map.of());
+    }
+
+    /** As {@link #CallerResolver(ConnectionIdentity, boolean, String, Map)} with no leads pinned. */
+    public CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token) {
+        this(identity, tokenMode, token, Map.of());
+    }
+
+    /**
+     * Single-pin form for the legacy {@code primary.terminal}-only configuration — one lead, named
+     * {@code primary}.
+     *
+     * <p>A static factory rather than a fourth constructor overload on purpose: {@code String} and
+     * {@code Map} overloads are ambiguous for a literal {@code null} argument, which is a compile
+     * error at the call site and exactly the shape "unpinned" is written in.
+     *
+     * @param pinnedPrimaryTerminal the primary's own herdr {@code terminal_id}
+     *                              ({@code null}/blank = unpinned)
+     */
+    public static CallerResolver pinnedTo(ConnectionIdentity identity, boolean tokenMode,
+                                          String token, String pinnedPrimaryTerminal) {
+        return new CallerResolver(identity, tokenMode, token,
+                pinnedPrimaryTerminal == null || pinnedPrimaryTerminal.isBlank()
+                        ? Map.of() : Map.of(pinnedPrimaryTerminal, "primary"));
+    }
+
+    /**
+     * @param identity       connection-based worker identification
+     * @param tokenMode      when true, a non-worker caller must present a valid bearer token
+     * @param token          the expected bearer token; required (non-blank) when {@code tokenMode}
+     * @param leadTerminals  herdr {@code terminal_id} → lead name for every configured lead
+     *                       (CB-530). A caller resolving to one of these panes is that lead — a
+     *                       {@link Role#PRIMARY} — rather than a worker. Empty = nothing pinned,
+     *                       so every pane resolves as a worker.
+     */
+    public CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token,
+                          Map<String, String> leadTerminals) {
+        this(identity, tokenMode, token, fixed(leadTerminals), null);
+    }
+
+    /**
+     * Map-form of both registries (CB-548): lead terminals and the initial architect terminal
+     * bindings, each snapshotted at construction (a handed-over map is not offered as live state).
+     */
+    public CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token,
+                          Map<String, String> leadTerminals,
+                          Map<String, String> architectTerminals) {
+        this(identity, tokenMode, token, fixed(leadTerminals), fixed(architectTerminals));
+    }
+
+    /**
+     * Live-registry form: {@code leadTerminals} is consulted on every resolve, so leads discovered
+     * after startup (CB-531's tab scan) take effect without a restart.
+     *
+     * <p>A static factory rather than a fourth constructor overload, for the same reason as
+     * {@link #pinnedTo}: {@code Map} and {@code Supplier} overloads are ambiguous for a literal
+     * {@code null}.
+     */
+    public static CallerResolver withLeads(ConnectionIdentity identity, boolean tokenMode,
+                                           String token,
+                                           Supplier<Map<String, String>> leadTerminals) {
+        return new CallerResolver(identity, tokenMode, token, leadTerminals, null);
+    }
+
+    /**
+     * Live-registry form for both {@code leadTerminals} and the CB-548 architect registry: both
+     * are consulted on every resolve, so a slot binding injected after startup takes effect
+     * without a restart.
+     *
+     * <p>A static factory rather than a constructor overload, for the same reason as
+     * {@link #pinnedTo}: too many {@code Map}/{@code Supplier} combinations to make {@code null}
+     * unambiguous.
+     */
+    public static CallerResolver withLeadsAndMembers(ConnectionIdentity identity,
+                                                        boolean tokenMode, String token,
+                                                        Supplier<Map<String, String>> leadTerminals,
+                                                        Supplier<Map<String, String>> architectTerminals) {
+        return new CallerResolver(identity, tokenMode, token, leadTerminals, architectTerminals);
+    }
+
+    private static Supplier<Map<String, String>> fixed(Map<String, String> leadTerminals) {
+        Map<String, String> snapshot = leadTerminals == null ? Map.of() : Map.copyOf(leadTerminals);
+        return () -> snapshot;
+    }
+
+    private CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token,
+                           Supplier<Map<String, String>> leadTerminals,
+                           Supplier<Map<String, String>> architectTerminals) {
+        if (tokenMode && (token == null || token.isBlank())) {
+            throw new IllegalArgumentException(
+                    "auth.mode=token requires a non-empty token; check that the env var named by "
+                            + "auth.tokenEnv is exported to the daemon's environment");
+        }
+        this.identity = identity;
+        this.tokenMode = tokenMode;
+        this.expectedToken = tokenMode ? token.getBytes(StandardCharsets.UTF_8) : null;
+        this.leadTerminals = leadTerminals == null ? Map::of : leadTerminals;
+        this.architectTerminals = architectTerminals == null ? Map::of : architectTerminals;
+    }
+
+    /**
+     * The currently-recognised leads, {@code terminal_id → name} (CB-535).
+     *
+     * <p>Deliberately read from the same supplier {@link #resolve} consults, rather than from a
+     * second copy handed to the roster: a lead that is <em>listed</em> but would not <em>resolve</em>
+     * (or the reverse) is an address a peer cannot actually reach, and the two answers drifting apart
+     * is precisely the confusion this exists to end. Live, so a lead discovered by the tab scan after
+     * startup appears without a restart.
+     */
+    public Map<String, String> leads() {
+        return leadTerminals.get();
+    }
+
+    /**
+     * The currently-recognised architect slots, {@code terminal_id → slot name} (CB-548).
+     *
+     * <p>Read from the same supplier {@link #resolve} consults, so a slot that is <em>listed</em>
+     * here but would not <em>resolve</em> (or the reverse) cannot drift apart. Live for the same
+     * reason as {@link #leads()}.
+     */
+    public Map<String, String> members() {
+        return architectTerminals.get();
+    }
+
+    /**
+     * Resolve the caller of a request.
+     *
+     * @param remoteAddr           the connection's remote address
+     * @param remotePort           the connection's remote port (used for the peer-PID lookup)
+     * @param authorizationHeader  the raw {@code Authorization} header, or {@code null}
+     */
+    public Principal resolve(String remoteAddr, int remotePort, String authorizationHeader) {
+        ConnectionIdentity.Caller c = identity.resolve(remoteAddr, remotePort);
+        if (c.terminal() != null) {
+            String lead = leadTerminals.get().get(c.terminal());
+            if (lead != null) {
+                // The config names this pane as a lead's own. The pane mapping is exactly as
+                // unforgeable as a worker's, so it outranks the token path — no credential needed.
+                // Checked before the architect registry so a pane named in BOTH is still the lead
+                // (CB-548 preserves every existing leader behaviour).
+                return Principal.leader(lead, c.terminal(), c.pid());
+            }
+            String slot = architectTerminals.get().get(c.terminal());
+            if (slot != null) {
+                // The config/live binding names this pane as an architect slot's own. Same
+                // unforgeable pane mapping; the live binding, never a request argument, decides.
+                // Checked before the generic worker fallback, per the CB-548 precedence order.
+                return Principal.architect(slot, c.terminal(), c.pid());
+            }
+            return Principal.worker(c.terminal(), c.pid()); // unforgeable; never token-gated
+        }
+
+        if (tokenMode) {
+            return presentedTokenMatches(authorizationHeader)
+                    ? Principal.primary(c.pid())
+                    : Principal.anonymous();
+        }
+
+        // loopback-trust: same-host callers that are not workers are the primary. A non-loopback
+        // caller is anonymous even here — and startup refuses that combination anyway
+        // (BridgedConfig.validateAuthExposure), so this is defence in depth, not the control.
+        return isLoopback(remoteAddr) ? Principal.primary(c.pid()) : Principal.anonymous();
+    }
+
+    private boolean presentedTokenMatches(String authorizationHeader) {
+        String presented = bearerValue(authorizationHeader);
+        if (presented == null) {
+            return false;
+        }
+        // Constant-time: MessageDigest.isEqual does not short-circuit on the first differing byte,
+        // so a token cannot be recovered a byte at a time by timing the response.
+        return MessageDigest.isEqual(presented.getBytes(StandardCharsets.UTF_8), expectedToken);
+    }
+
+    /** Extract the credential from {@code Authorization: Bearer <token>}, or {@code null}. */
+    private static String bearerValue(String header) {
+        if (header == null) {
+            return null;
+        }
+        String h = header.trim();
+        if (h.length() < 7 || !h.regionMatches(true, 0, "Bearer ", 0, 7)) {
+            return null;
+        }
+        String token = h.substring(7).trim();
+        return token.isEmpty() ? null : token;
+    }
+
+    private static boolean isLoopback(String remoteAddr) {
+        if (remoteAddr == null) {
+            return false;
+        }
+        return remoteAddr.equals("127.0.0.1") || remoteAddr.equals("::1")
+                || remoteAddr.equals("0:0:0:0:0:0:0:1") || remoteAddr.startsWith("127.");
+    }
+}

bridged/src/main/java/dev/ltms/bridged/auth/MemberRegistry.java

@@ -0,0 +1,192 @@
+package dev.ltms.bridged.auth;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.peer.MemberRole;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * The architect-slot registry (CB-548): every gateway-local architect name and the strong-model
+ * profile it points at, plus the <em>live</em> bindings from a live architect's herdr terminal to
+ * its slot.
+ *
+ * <p>Two halves, split by who owns each:
+ * <ul>
+ *   <li><b>slots</b> — configured once, keyed by the gateway-local unique name; each carries the
+ *       {@code profile} reference the spawn lifecycle reads when it stands the slot up. A read-only
+ *       snapshot taken at construction.</li>
+ *   <li><b>terminal bindings</b> — owned by this registry and initially <em>empty</em>. Config
+ *       declares no architect terminal, so at startup every slot is idle and nothing resolves to an
+ *       architect; a session only becomes one when the spawn lifecycle {@linkplain #bind(String,
+ *       String) binds} its terminal to a slot. {@link CallerResolver} reads this through
+ *       {@link #snapshot()} to turn a pane into an {@link Role#ARCHITECT}.</li>
+ * </ul>
+ *
+ * <p>Spawning/lifecycle is deliberately a separate unit: this class only owns the bindings and
+ * exposes the map the resolver resolves against plus the profile lookup lifecycle will call.
+ * Nothing here creates or manages an architect session.
+ */
+public final class MemberRegistry {
+
+    /**
+     * One flattened {@code fleet:} entry.
+     *
+     * <p>Flattened because a slot name is unique only <em>within</em> its pool — {@code sonnet} may
+     * legitimately be both a developer and a reviewer — while a terminal binds to exactly one thing.
+     * The qualified {@link #key()} is what that binding uses.
+     *
+     * @param name    the slot's key inside its pool
+     * @param role    the pool it came from
+     * @param profile the backend it runs on
+     */
+    public record Entry(String name, MemberRole role, String profile) {
+        /** {@code "architect:opus"} — unique across pools, unlike {@link #name()}. */
+        public String key() {
+            return role.wireName() + ":" + name;
+        }
+    }
+
+    private final Map<String, Entry> slots;
+    /** Live {@code terminal_id → qualified slot key}; guarded by {@code this}. */
+    private final Map<String, String> terminalToSlot = new HashMap<>();
+
+    /** Flatten every role pool in {@code fleet} into one registry. Leaders are not members. */
+    public MemberRegistry(BridgedConfig.Fleet fleet) {
+        Map<String, Entry> flat = new LinkedHashMap<>();
+        if (fleet != null) {
+            for (MemberRole role : MemberRole.values()) {
+                fleet.pool(role).forEach((name, slot) -> {
+                    if (slot != null) {
+                        Entry e = new Entry(name, role, slot.profile());
+                        flat.put(e.key(), e);
+                    }
+                });
+            }
+        }
+        this.slots = Collections.unmodifiableMap(flat);
+    }
+
+    /** The configured slots, keyed by qualified {@link Entry#key()}. Unmodifiable snapshot. */
+    public Map<String, Entry> slots() {
+        return slots;
+    }
+
+    /** The slots belonging to {@code role}, in definition order. */
+    public Map<String, Entry> slotsFor(MemberRole role) {
+        Map<String, Entry> out = new LinkedHashMap<>();
+        slots.forEach((key, e) -> {
+            if (e.role() == role) {
+                out.put(key, e);
+            }
+        });
+        return Collections.unmodifiableMap(out);
+    }
+
+    /**
+     * An immutable copy of the live {@code terminal_id → slot name} bindings.
+     *
+     * <p>Passed to {@link CallerResolver} as the source of architect identity, and what
+     * {@code bridge_whoami}/the roster will read to say which slot a pane hosts. Empty until the
+     * spawn lifecycle binds a slot.
+     */
+    public Map<String, String> snapshot() {
+        synchronized (terminalToSlot) {
+            return Map.copyOf(terminalToSlot);
+        }
+    }
+
+    /** The slot a live terminal is bound to, or {@code null} if it is not an architect slot. */
+    public String slotForTerminal(String terminal) {
+        if (terminal == null) {
+            return null;
+        }
+        synchronized (terminalToSlot) {
+            return terminalToSlot.get(terminal);
+        }
+    }
+
+    /**
+     * The strong-model profile a slot runs under — what the spawn lifecycle reads.
+     *
+     * @return the slot's configured {@code profile}, or {@code null} if the slot is unknown or
+     *         declares none
+     */
+    public String profileForSlot(String slotName) {
+        Entry e = slots.get(slotName);
+        return (e == null || e.profile() == null) ? null : e.profile();
+    }
+
+    /** The role a qualified slot key belongs to, or {@code null} when the key is unknown. */
+    public MemberRole roleForSlot(String slotName) {
+        Entry e = slots.get(slotName);
+        return e == null ? null : e.role();
+    }
+
+    /** True when {@code slotName} is a configured architect slot. */
+    public boolean isSlot(String slotName) {
+        return slots.containsKey(slotName);
+    }
+
+    /**
+     * Bind {@code terminal} to {@code slot} (CB-548).
+     *
+     * <p>The spawn lifecycle calls this when it stands a slot up. The bind is atomic and preserves
+     * the two cardinality invariants: a terminal may occupy at most one slot, and a slot may host at
+     * most one terminal. Binding the same terminal to the same slot again is a harmless no-op.
+     *
+     * @param slot     a configured slot name, or the bind is refused
+     * @param terminal the pane that will act as this architect
+     * @return {@code true} if the binding is now {@code terminal → slot}; {@code false} if it was
+     *         refused — an unknown slot, a terminal already bound to a different slot, or a slot
+     *         already hosting a different terminal
+     */
+    public boolean bind(String slot, String terminal) {
+        if (slot == null || terminal == null || terminal.isBlank()) {
+            return false;
+        }
+        synchronized (terminalToSlot) {
+            if (!isSlot(slot)) {
+                return false; // unknown slot — nothing to bind to
+            }
+            String existingSlot = terminalToSlot.get(terminal);
+            if (existingSlot != null) {
+                return slot.equals(existingSlot); // already this slot (idempotent) or a different one
+            }
+            if (terminalToSlot.containsValue(slot)) {
+                return false; // slot already hosts a terminal — no second one
+            }
+            terminalToSlot.put(terminal, slot);
+            return true;
+        }
+    }
+
+    /**
+     * Compare-safe unbind of {@code expectedTerminal} from {@code slot} (CB-548).
+     *
+     * <p>The spawn lifecycle calls this when it tears a slot down. Only the exact binding
+     * {@code expectedTerminal → slot} is removed; if that terminal was since rebound to a different
+     * slot (or the slot to a different terminal), the call is a no-op returning {@code false} — a
+     * stale unbind must never remove a replacement.
+     *
+     * @param slot             the slot the caller believes the terminal is bound to
+     * @param expectedTerminal the terminal it expects to be bound there
+     * @return {@code true} if {@code expectedTerminal → slot} was removed; {@code false} if nothing
+     *         was (no such binding, or the binding had already moved)
+     */
+    public boolean unbind(String slot, String expectedTerminal) {
+        if (slot == null || expectedTerminal == null) {
+            return false;
+        }
+        synchronized (terminalToSlot) {
+            String current = terminalToSlot.get(expectedTerminal);
+            if (current == null || !slot.equals(current)) {
+                return false; // absent, or a replacement/moved binding — leave it in place
+            }
+            terminalToSlot.remove(expectedTerminal);
+            return true;
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/auth/Principal.java

@@ -0,0 +1,117 @@
+package dev.ltms.bridged.auth;
+
+/**
+ * A resolved caller: its {@link Role}, and — for a worker — the herdr {@code terminal_id} that
+ * identifies which worker it is (CB-501).
+ *
+ * @param role     what this caller is authorized to act as
+ * @param terminal the herdr {@code terminal_id} of the pane this caller occupies — a worker's, or
+ *                 (since CB-532) a named lead's; {@code null} for an unnamed primary resolved off a
+ *                 token or loopback trust, and for {@code ANONYMOUS}
+ * @param pid      the connecting process id, or {@code -1} when not resolvable (audit context)
+ * @param name     for a lead resolved from the CB-530 {@code leaders:} registry, which lead it is;
+ *                 for an architect resolved from the CB-548 {@code architects:} registry, which
+ *                 slot it occupies; {@code null} for every other caller, including an unnamed primary
+ */
+public record Principal(Role role, String terminal, long pid, String name) {
+
+    /**
+     * Three-arg form for the callers that have no name to carry (workers, anonymous, and the
+     * token/loopback primary paths). Kept so adding CB-530's {@code name} did not churn every
+     * construction site — and so a reconstructed principal without a stashed name still works.
+     */
+    public Principal(Role role, String terminal, long pid) {
+        this(role, terminal, pid, null);
+    }
+
+    /** A caller authenticated as nothing — the default when no check establishes anything else. */
+    public static Principal anonymous() {
+        return new Principal(Role.ANONYMOUS, null, -1);
+    }
+
+    /** The orchestrating session, unnamed (token or loopback-trust path). */
+    public static Principal primary(long pid) {
+        return new Principal(Role.PRIMARY, null, pid);
+    }
+
+    /**
+     * A named lead from the {@code leaders:} registry (CB-530).
+     *
+     * <p>Carries {@link Role#PRIMARY}: a lead <em>is</em> a primary as far as authorization goes,
+     * so every existing {@code isPrimary()} gate keeps working unchanged and the role table needed
+     * no new entry. The name is reporting only — it lets {@code bridge_whoami} say <em>which</em>
+     * lead is asking once more than one is configured.
+     *
+     * <p><strong>CB-532: a lead now carries the terminal it was matched by.</strong> Under CB-530 it
+     * deliberately did not, because {@code terminal} meant "which worker pane" everywhere and a
+     * non-null one would have enrolled the lead in the worker presence map. That reading was what
+     * made a lead unaddressable: {@link #ownsSession} could never be true for it, so
+     * {@code bridge_reply} was refused and one lead could send to another but never be answered.
+     * The terminal now means "which pane is this caller", the presence map keys on
+     * {@link #isWorker()} instead, and a lead is a peer that can both send and receive.
+     */
+    public static Principal leader(String name, String terminal, long pid) {
+        return new Principal(Role.PRIMARY, terminal, pid, name);
+    }
+
+    /** A worker peer, identified by its herdr pane. */
+    public static Principal worker(String terminal, long pid) {
+        return new Principal(Role.WORKER, terminal, pid);
+    }
+
+    /**
+     * An architect (CB-548), identified by the slot it occupies and the pane bound to it.
+     *
+     * <p>Carries {@link Role#ARCHITECT}. {@code slotName} is reporting only — it lets
+     * {@code bridge_whoami} say <em>which</em> architect slot is asking, and it is the key the
+     * (future) spawn lifecycle reads a profile back from. Identity is the {@code terminal}: like a
+     * worker's it comes from the connection and the live terminal→slot binding, so
+     * {@code ownsSession} works exactly as it does for a worker — an architect acts as its own
+     * pane and no other.
+     */
+    public static Principal architect(String slotName, String terminal, long pid) {
+        return new Principal(Role.ARCHITECT, terminal, pid, slotName);
+    }
+
+    public boolean isPrimary() {
+        return role == Role.PRIMARY;
+    }
+
+    public boolean isArchitect() {
+        return role == Role.ARCHITECT;
+    }
+
+    public boolean isWorker() {
+        return role == Role.WORKER;
+    }
+
+    public boolean isAnonymous() {
+        return role == Role.ANONYMOUS;
+    }
+
+    /**
+     * Whether this caller may act <em>as</em> {@code sessionId} — the "own session only" rule that
+     * keeps one peer from replying or asking on another's behalf.
+     *
+     * <p>The rule is about <em>identity</em>, not rank: a caller may act as the pane it demonstrably
+     * occupies, and as no other. CB-532 dropped the extra {@code isWorker()} conjunct that used to
+     * be here. It was not what enforced the rule — {@code terminal.equals(sessionId)} is, and that
+     * terminal comes from the connection, so it cannot be forged either way. All the conjunct did
+     * was make a lead permanently unable to answer anyone, since a lead's terminal was null and a
+     * lead is not a worker. A caller with no terminal at all (an off-host or token-authenticated
+     * primary) still owns nothing, which is the case the null check covers.
+     */
+    public boolean ownsSession(String sessionId) {
+        return terminal != null && terminal.equals(sessionId);
+    }
+
+    /** Short, non-sensitive description for audit lines and error details. */
+    public String describe() {
+        return switch (role) {
+            case WORKER -> "worker:" + terminal;
+            case ARCHITECT -> "architect:" + name;
+            case PRIMARY -> name == null ? "primary" : "leader:" + name;
+            case ANONYMOUS -> "anonymous";
+        };
+    }
+}

bridged/src/main/java/dev/ltms/bridged/auth/Role.java

@@ -0,0 +1,39 @@
+package dev.ltms.bridged.auth;
+
+/**
+ * What a caller is allowed to be on the bus (CB-501).
+ *
+ * <p>The ordering matters conceptually: {@link #PRIMARY} is the <em>most</em> privileged role
+ * (it spawns, stops, sends to any session, and drains any inbox), not the least. Before CB-501
+ * the daemon reached {@code PRIMARY} by <em>failing</em> every other check — any caller that did
+ * not resolve to a known worker pane was treated as the primary. That is inverted here:
+ * {@link #ANONYMOUS} is the fallback, and {@code PRIMARY} must be established.
+ */
+public enum Role {
+
+    /**
+     * The orchestrating session. Established either by being a loopback caller that is not a
+     * worker pane (under {@code loopback-trust}) or by presenting a valid bearer token (under
+     * {@code token} mode).
+     */
+    PRIMARY,
+
+    /**
+     * A worker peer, identified by its herdr pane. Unforgeable: derived from the connection's
+     * loopback peer PID via herdr's PID→pane map, never from a request argument.
+     */
+    WORKER,
+
+    /**
+     * A config-declared architect slot (CB-548): a gateway-local named session on a strong-model
+     * profile that coordinates and delegates turns but does not own the fleet. Unforgeable like a
+     * worker's — derived from the connection's pane and the live terminal→slot binding, never from
+     * a request argument. May {@code SEND} a turn, {@code REPLY}/{@code ASK} only as its own pane,
+     * and {@code READ}/{@code METRICS}; may <em>not</em> {@code SPAWN}/{@code STOP}/{@code DRAIN}
+     * (those stay the primary's, to keep lifecycle in one pair of hands).
+     */
+    ARCHITECT,
+
+    /** Authenticated as nothing. Authorized for nothing but {@code /healthz}. */
+    ANONYMOUS
+}

bridged/src/main/java/dev/ltms/bridged/config/ConfigRef.java

@@ -0,0 +1,269 @@
+package dev.ltms.bridged.config;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Supplier;
+
+/**
+ * The daemon's live configuration, re-readable without a restart (CB-559).
+ *
+ * <p>Consumers hold this, not a {@link BridgedConfig}, and read through {@link #get()} at the point
+ * of use. A component that captures {@code ref.get()} into a field at construction has opted out of
+ * reload — which is sometimes right (see <em>deferred</em> below), but it must then be a deliberate
+ * choice rather than an accident of where the field was initialised.
+ *
+ * <h2>Not every key can change under a running daemon</h2>
+ * Keys fall into three classes, and the difference is about what already exists when the reload
+ * happens — not about how important the key is.
+ *
+ * <ul>
+ *   <li><strong>Hot</strong> — re-read per use, so a reload takes effect on the next spawn:
+ *       {@code fleet:} (every role pool and {@code tabLabel}), {@code placement:}, and an existing
+ *       profile's {@code weight} / {@code maxLoad}. Those three are read through a supplier on
+ *       {@code CompositePeerLauncher}, which is what makes them hot — not the fact that they are
+ *       config.</li>
+ *   <li><strong>Deferred</strong> — accepted into the new snapshot, but the wiring built at startup
+ *       keeps the old value until a restart: {@code lifecycle:}, {@code leadHeartbeat:},
+ *       {@code spawnReadyTimeoutMs} / {@code spawnReadyPollMs}, {@code guard:},
+ *       {@code worktreeRoot:}, adding or removing a profile (a new backend needs its own launcher,
+ *       which is constructed once), <em>and an existing profile's launch settings</em> —
+ *       {@code model}, {@code baseUrl}, {@code argv}, {@code env}, {@code mcpUrl} and the rest.
+ *       {@code HerdrPeerLauncher} takes {@code Map.copyOf(profiles)} at construction and resolves
+ *       each spawn out of that copy, so those never reach a launch until the daemon restarts. A
+ *       reload logs these rather than pretending they applied.</li>
+ *   <li><strong>Cold</strong> — cannot change at all under a running daemon: {@code bind:},
+ *       {@code herdrSocket:}, {@code broker:} and {@code auth:}. The socket is bound, the broker
+ *       connection is open, and the auth mode decides who may reach the port that is already
+ *       listening.</li>
+ * </ul>
+ *
+ * <p><strong>A cold change refuses the whole reload.</strong> Not the hot half applied and the cold
+ * half warned about: that would leave the running daemon in a state matching no file on disk, which
+ * is the worst thing a reload can do to an operator debugging one. Refusing keeps the invariant that
+ * the live config is always some version of the file, and the message names the keys that must
+ * change through a restart.
+ *
+ * <p>A reload that fails to parse or fails validation is also refused, and the previous config keeps
+ * running. A config file being edited is normally read once mid-save; degrading a working daemon
+ * because it caught a half-written file would be a bad trade.
+ */
+public final class ConfigRef implements Supplier<BridgedConfig> {
+
+    private static final Logger log = LoggerFactory.getLogger(ConfigRef.class);
+
+    /** Keys that cannot change under a running daemon — see the class doc. */
+    private static final Set<String> COLD_KEYS =
+            Set.of("bind", "herdrSocket", "broker", "auth");
+
+    private final Path path;
+    private final AtomicReference<BridgedConfig> current;
+
+    public ConfigRef(Path path, BridgedConfig initial) {
+        this.path = path;
+        this.current = new AtomicReference<>(Objects.requireNonNull(initial, "initial config"));
+    }
+
+    /** A fixed reference that never reloads — for tests and for wiring built from a config in code. */
+    public static ConfigRef fixed(BridgedConfig cfg) {
+        return new ConfigRef(null, cfg);
+    }
+
+    /** The live configuration. Read this per use; do not cache it in a field. */
+    @Override
+    public BridgedConfig get() {
+        return current.get();
+    }
+
+    /** The file this ref reloads from, or {@code null} for a {@link #fixed} ref. */
+    public Path path() {
+        return path;
+    }
+
+    /**
+     * What a reload attempt did.
+     *
+     * @param applied  true when the new config is now live
+     * @param coldKeys cold keys whose value changed, which is why an unapplied reload was refused
+     * @param deferred keys that changed and were accepted, but whose effect waits for a restart
+     * @param error    the parse or validation failure that refused the reload, else {@code null}
+     */
+    public record Outcome(boolean applied, List<String> coldKeys, List<String> deferred,
+                          String error) {
+
+        public Outcome {
+            coldKeys = List.copyOf(coldKeys);
+            deferred = List.copyOf(deferred);
+        }
+
+        static Outcome refusedCold(List<String> keys) {
+            return new Outcome(false, keys, List.of(), null);
+        }
+
+        static Outcome failed(String error) {
+            return new Outcome(false, List.of(), List.of(), error);
+        }
+
+        /** A one-line summary for the operator — the reason, not just the verdict. */
+        public String summary() {
+            if (error != null) {
+                return "config reload refused — " + error;
+            }
+            if (!applied) {
+                return "config reload refused — these keys cannot change under a running daemon: "
+                        + String.join(", ", coldKeys) + ". Restart bridged to apply them.";
+            }
+            if (!deferred.isEmpty()) {
+                return "config reloaded; these changes need a restart to take effect: "
+                        + String.join(", ", deferred);
+            }
+            return "config reloaded";
+        }
+    }
+
+    /**
+     * Re-read the file, validate it, and swap it in when nothing cold changed.
+     *
+     * <p>Never throws: a reload is a best-effort operation on a daemon that is already serving, and
+     * a bad edit must not take it down. Every failure path leaves the previous config live and is
+     * reported through the returned {@link Outcome}.
+     */
+    public Outcome reload() {
+        if (path == null) {
+            return Outcome.failed("this config was built in code and has no file to reload from");
+        }
+        BridgedConfig old = current.get();
+        BridgedConfig fresh;
+        try {
+            fresh = BridgedConfig.load(path);
+            // The same gate startup runs. A config that would have refused to boot must not be able
+            // to slip in through a reload — that is how a daemon ends up in a state it could never
+            // have started in, which is the hardest kind to debug.
+            fresh.validateAuthExposure();
+            fresh.validateLeadTabPrefixes();
+            fresh.validateSubscriptionProfiles();
+            fresh.validateMembers();
+        } catch (RuntimeException e) {
+            String msg = e.getMessage() == null ? e.toString() : e.getMessage();
+            log.warn("config reload from {} refused, keeping the running config: {}", path, msg);
+            return Outcome.failed(msg);
+        }
+
+        List<String> cold = changedColdKeys(old, fresh);
+        if (!cold.isEmpty()) {
+            Outcome out = Outcome.refusedCold(cold);
+            log.warn(out.summary());
+            return out;
+        }
+
+        List<String> deferred = changedDeferredKeys(old, fresh);
+        current.set(fresh);
+        Outcome out = new Outcome(true, List.of(), deferred, null);
+        log.info(out.summary());
+        return out;
+    }
+
+    /** Cold keys whose value differs between the running config and the candidate. */
+    private static List<String> changedColdKeys(BridgedConfig old, BridgedConfig fresh) {
+        List<String> changed = new ArrayList<>();
+        if (!Objects.equals(old.bind(), fresh.bind())) {
+            changed.add("bind");
+        }
+        if (!Objects.equals(old.herdrSocket(), fresh.herdrSocket())) {
+            changed.add("herdrSocket");
+        }
+        if (!Objects.equals(old.broker(), fresh.broker())) {
+            changed.add("broker");
+        }
+        if (!Objects.equals(old.auth(), fresh.auth())) {
+            changed.add("auth");
+        }
+        // Kept in step with COLD_KEYS so the doc and the code cannot drift apart silently.
+        assert COLD_KEYS.containsAll(changed) : "a cold key was reported that COLD_KEYS omits";
+        return changed;
+    }
+
+    /** Changed keys that were accepted but whose effect waits for a restart. */
+    private static List<String> changedDeferredKeys(BridgedConfig old, BridgedConfig fresh) {
+        List<String> changed = new ArrayList<>();
+        if (!Objects.equals(old.lifecycle(), fresh.lifecycle())) {
+            changed.add("lifecycle");
+        }
+        if (!Objects.equals(old.leadHeartbeat(), fresh.leadHeartbeat())) {
+            changed.add("leadHeartbeat");
+        }
+        if (!Objects.equals(old.guard(), fresh.guard())) {
+            changed.add("guard");
+        }
+        if (!Objects.equals(old.worktreeRoot(), fresh.worktreeRoot())) {
+            changed.add("worktreeRoot");
+        }
+        if (!Objects.equals(old.spawnReadyTimeoutMs(), fresh.spawnReadyTimeoutMs())
+                || !Objects.equals(old.spawnReadyPollMs(), fresh.spawnReadyPollMs())) {
+            changed.add("spawnReady*");
+        }
+        Map<String, BridgedConfig.Profile> before =
+                old.profiles() == null ? Map.of() : old.profiles();
+        Map<String, BridgedConfig.Profile> after =
+                fresh.profiles() == null ? Map.of() : fresh.profiles();
+        // Adding or removing a profile is deferred: a new backend needs its own launcher, and
+        // launchers are built once at startup.
+        if (!before.keySet().equals(after.keySet())) {
+            Set<String> diff = new LinkedHashSet<>(before.keySet());
+            diff.addAll(after.keySet());
+            diff.removeIf(p -> before.containsKey(p) && after.containsKey(p));
+            changed.add("profiles (added/removed: " + String.join(", ", diff) + ")");
+        }
+        // An EXISTING profile's launch settings are deferred too, and this is easy to get wrong:
+        // `HerdrPeerLauncher` takes `Map.copyOf(profiles)` at construction and `spawn` resolves the
+        // profile out of that snapshot, so a reloaded model/baseUrl/argv/env never reaches a launch.
+        // Only weight and maxLoad are genuinely hot, because placement reads them through the
+        // supplier on the composite rather than from the adapter's copy. Without this check a
+        // changed model would report "config reloaded" and silently do nothing — the worst outcome
+        // a reload can produce, because the operator has no reason to doubt it.
+        List<String> relaunch = new ArrayList<>();
+        before.forEach((name, was) -> {
+            BridgedConfig.Profile now = after.get(name);
+            if (now != null && !sameLaunchSettings(was, now)) {
+                relaunch.add(name);
+            }
+        });
+        if (!relaunch.isEmpty()) {
+            changed.add("profiles." + String.join("/", relaunch) + " launch settings "
+                    + "(model, baseUrl, argv, env, …) — the launcher holds a startup snapshot");
+        }
+        return changed;
+    }
+
+    /**
+     * Whether two versions of a profile would launch a peer identically. Compares every component
+     * the launcher reads at spawn; {@code weight} and {@code maxLoad} are excluded because those are
+     * read live by the placement policy and really do take effect on the next spawn.
+     */
+    private static boolean sameLaunchSettings(BridgedConfig.Profile a, BridgedConfig.Profile b) {
+        return Objects.equals(a.baseUrl(), b.baseUrl())
+                && Objects.equals(a.model(), b.model())
+                && Objects.equals(a.configDir(), b.configDir())
+                && Objects.equals(a.tokenEnv(), b.tokenEnv())
+                && Objects.equals(a.argv(), b.argv())
+                && Objects.equals(a.placement(), b.placement())
+                && Objects.equals(a.workspace(), b.workspace())
+                && Objects.equals(a.tabLabel(), b.tabLabel())
+                && Objects.equals(a.mcpUrl(), b.mcpUrl())
+                && Objects.equals(a.cwd(), b.cwd())
+                && Objects.equals(a.parityOverlay(), b.parityOverlay())
+                && Objects.equals(a.gitTokenEnv(), b.gitTokenEnv())
+                && Objects.equals(a.gitHostEnv(), b.gitHostEnv())
+                && Objects.equals(a.kind(), b.kind())
+                && Objects.equals(a.env(), b.env())
+                && Objects.equals(a.subscription(), b.subscription());
+    }
+}

bridged/src/main/java/dev/ltms/bridged/config/ConfigWatcher.java

@@ -0,0 +1,96 @@
+package dev.ltms.bridged.config;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Polls {@code bridged.yaml}'s modified time and asks {@link ConfigRef} to reload when it moves
+ * (CB-559). Opt-in through {@code configReload.enabled}.
+ *
+ * <p><strong>Why polling and not a filesystem watch.</strong> {@code WatchService} on macOS has no
+ * native backend — it falls back to polling internally anyway, at an interval this code does not
+ * control — and editors save config files in ways that produce a different event mix per editor
+ * (write-in-place, write-and-rename, write-temp-and-swap). A modified-time check treats all of them
+ * the same and is a single {@code stat} per tick, which at a ten-second cadence costs nothing worth
+ * measuring.
+ *
+ * <p><strong>A missing or unreadable file is not a reason to act.</strong> Many editors briefly
+ * unlink the file during a save. Reloading on "it vanished" would mean reloading from a file that no
+ * longer exists; reporting an error every tick would bury the log. So an unreadable file is skipped
+ * silently and the next tick tries again — the running config stays live, which is the correct
+ * outcome either way.
+ */
+public final class ConfigWatcher {
+
+    private static final Logger log = LoggerFactory.getLogger(ConfigWatcher.class);
+
+    private final ConfigRef ref;
+    private final long intervalSeconds;
+    private final ScheduledExecutorService scheduler;
+
+    private volatile long lastSeenMillis;
+
+    public ConfigWatcher(ConfigRef ref, long intervalSeconds) {
+        this.ref = ref;
+        this.intervalSeconds = intervalSeconds;
+        this.lastSeenMillis = modifiedMillis(ref.path());
+        this.scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
+            Thread t = new Thread(r, "config-watcher");
+            // A daemon thread: an operator's config watch must never be the reason the JVM refuses
+            // to exit after everything else has shut down.
+            t.setDaemon(true);
+            return t;
+        });
+    }
+
+    /** Begin watching. A ref with no file (a fixed one) is a no-op rather than an error. */
+    public void start() {
+        if (ref.path() == null) {
+            log.debug("config watch not started — this config has no file behind it");
+            return;
+        }
+        scheduler.scheduleWithFixedDelay(this::tick, intervalSeconds, intervalSeconds,
+                TimeUnit.SECONDS);
+        log.info("config watch: {} re-read when it changes (every {}s)", ref.path(), intervalSeconds);
+    }
+
+    /** One poll. Never throws — an exception here would silently cancel the schedule. */
+    void tick() {
+        try {
+            long now = modifiedMillis(ref.path());
+            if (now == 0 || now == lastSeenMillis) {
+                return;
+            }
+            // Stamp BEFORE reloading. A file whose reload is refused (a bad edit, or a cold key)
+            // must not be retried every tick — that would log the same refusal forever. The next
+            // save moves the timestamp again and earns a fresh attempt.
+            lastSeenMillis = now;
+            ref.reload();
+        } catch (RuntimeException e) {
+            log.warn("config watch tick failed, still watching: {}", e.getMessage());
+        }
+    }
+
+    private static long modifiedMillis(Path path) {
+        if (path == null) {
+            return 0;
+        }
+        try {
+            return Files.getLastModifiedTime(path).toMillis();
+        } catch (IOException e) {
+            return 0; // mid-save, or gone: say nothing and try again next tick
+        }
+    }
+
+    /** Stop polling. Called from the daemon's ordered shutdown hook, alongside the other loops. */
+    public void stop() {
+        scheduler.shutdownNow();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/herdr/Agent.java

@@ -15,6 +15,10 @@ import com.fasterxml.jackson.databind.JsonNode;
  * @param agentType  detected agent kind, e.g. {@code "claude"}, or {@code null} before herdr
  *                   has detected it (the start-time shape)
  * @param status     current lifecycle state
+ * @param name       the unique label the agent was started with — for a bridge worker this is
+ *                   {@code claude-<profile>-<nonce>-<seq>} (CB-117 keys orphan reaping on the
+ *                   nonce); {@code null} for agents the bridge did not start, e.g. a user's own
+ *                   Claude session
  */
 public record Agent(
         String terminalId,
@@ -23,7 +27,8 @@ public record Agent(
         String tabId,
         String sessionId,
         String agentType,
-        AgentStatus status) {
+        AgentStatus status,
+        String name) {
 
     /** Project a herdr {@code agent} node. Tolerates the start-time shape (no session yet). */
     public static Agent from(JsonNode a) {
@@ -42,6 +47,7 @@ public record Agent(
                 a.path("tab_id").asText(null),
                 sessionId,
                 type,
-                AgentStatus.fromWire(a.path("agent_status").asText(null)));
+                AgentStatus.fromWire(a.path("agent_status").asText(null)),
+                a.path("name").asText(null));
     }
 }

bridged/src/main/java/dev/ltms/bridged/herdr/AgentControl.java

@@ -6,12 +6,18 @@ import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
 
 /**
  * Domain layer over herdr's native {@code agent.*} namespace — the worker south side.
- * Chosen in the CB-102 spike over the pane + {@code send_text} fallback because
- * {@code agent.start} takes a first-class {@code env} map (clean, guard-checked
- * subscription injection) and herdr tracks each worker's Claude session UUID itself.
+ * Chosen in the CB-102 spike over the pane + {@code send_text} fallback because herdr
+ * tracks each worker's Claude session UUID itself.
+ *
+ * <p>Ported to herdr protocol 19 (herdr 0.8.0, CB-521): {@code agent.start} now starts a
+ * <em>supported</em> agent ({@code kind}) into an <em>existing</em> pane, so the worker's
+ * {@code env}/{@code cwd} move to pane creation ({@code tab.create}/{@code pane.split} — see
+ * {@link WorkspaceControl}), and {@code agent.send} is replaced by {@code agent.prompt}
+ * (which submits in one call) plus {@code agent.send_keys} for the raw Enter nudge.
  *
  * <p>Every method is one herdr call through the injected {@link HerdrClient}, so this
  * layer is unit-testable with a fake and contract-tested against a live daemon.
@@ -20,42 +26,100 @@ public final class AgentControl {
 
     private final HerdrClient herdr;
 
+    /**
+     * Protocol 19 dropped {@code terminal_id} as an {@code agent.*} target — herdr now resolves
+     * targets by pane id or agent name only, while the bridge keys every session on the terminal.
+     * This caches the terminal→pane mapping (stable for a worker's lifetime) so callers keep
+     * addressing agents by terminal; entries are invalidated on {@code agent_not_found}.
+     */
+    private final Map<String, String> paneByTerminal = new ConcurrentHashMap<>();
+
     public AgentControl(HerdrClient herdr) {
         this.herdr = herdr;
     }
 
-    /**
-     * Spawn an agent. {@code env} is applied to the process environment verbatim — this
-     * is where a worker's {@code ANTHROPIC_BASE_URL} lives, and the ONLY place it should.
-     *
-     * @param name label/kind for herdr status detection (e.g. {@code "claude"})
-     * @param argv launch command, e.g. {@code ["claude"]}
-     * @param env  process environment additions ({@code ANTHROPIC_BASE_URL}, token, …)
-     */
-    public Agent start(String name, List<String> argv, Map<String, String> env) {
-        return start(name, argv, env, null);
+    /** One agent-targeted call, translating a terminal id to its pane id (retrying once fresh). */
+    private JsonNode agentCall(String method, String target, Map<String, Object> extra) {
+        String resolved = resolveTarget(target);
+        try {
+            return herdr.call(method, withTarget(resolved, extra));
+        } catch (HerdrException e) {
+            if (!"agent_not_found".equals(e.code()) || resolved.equals(target)) throw e;
+            paneByTerminal.remove(target); // the cached pane went away — re-resolve once
+            String fresh = resolveTarget(target);
+            if (fresh.equals(resolved)) throw e;
+            return herdr.call(method, withTarget(fresh, extra));
+        }
+    }
+
+    private static Map<String, Object> withTarget(String target, Map<String, Object> extra) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("target", target);
+        m.putAll(extra);
+        return m;
+    }
+
+    /** The pane id behind a terminal-id target, or the target verbatim for pane ids / names. */
+    private String resolveTarget(String target) {
+        if (target == null || !target.startsWith("term_")) {
+            return target;
+        }
+        String cached = paneByTerminal.get(target);
+        if (cached != null) {
+            return cached;
+        }
+        for (JsonNode a : herdr.call("agent.list").path("agents")) {
+            if (target.equals(a.path("terminal_id").asText(null))) {
+                String pane = a.path("pane_id").asText(null);
+                if (pane != null) {
+                    paneByTerminal.put(target, pane);
+                    return pane;
+                }
+            }
+        }
+        return target; // unknown terminal — let herdr report it against the original target
     }
 
     /**
-     * Spawn an agent into a specific tab. With a non-null {@code tabId} the worker lands
-     * in that tab (the placement policy's dedicated worker tab); with {@code null} herdr
-     * splits the currently-focused tab (legacy pane placement).
+     * Start an agent into {@code paneId}, which must be sitting at its interactive shell prompt —
+     * the seed pane of a freshly-created worker tab, or a fresh split. The pane's shell already
+     * carries the worker's env ({@code ANTHROPIC_BASE_URL}, token, …) and cwd from pane creation;
+     * herdr resolves the executable from {@code kind} and waits (its default timeout) until the
+     * agent is detected and ready for input.
+     *
+     * @param name unique label for this agent ({@code <kind>-<profile>-<nonce>-<seq>})
+     * @param kind supported agent kind and canonical executable, e.g. {@code "claude"},
+     *             {@code "opencode"}
+     * @param args extra arguments after the executable, e.g. {@code --mcp-config …}
+     * @param paneId the pane to start the agent in
      */
-    public Agent start(String name, List<String> argv, Map<String, String> env, String tabId) {
+    public Agent start(String name, String kind, List<String> args, String paneId) {
         Map<String, Object> params = new LinkedHashMap<>();
         params.put("name", name);
-        params.put("argv", argv);
-        params.put("env", env);
-        if (tabId != null) {
-            params.put("tab_id", tabId);
-        }
+        params.put("kind", kind);
+        params.put("pane_id", paneId);
+        params.put("args", args);
         JsonNode result = herdr.call("agent.start", params);
         return Agent.from(result.get("agent"));
     }
 
-    /** Deliver {@code text} to an agent (its next prompt input). */
+    /**
+     * Deliver {@code text} to an agent as its next prompt <em>and submit it</em> — herdr's
+     * {@code agent.prompt} pastes the text (embedded newlines preserved verbatim) and submits it
+     * in the same call, replacing the pre-protocol-19 two-event {@code agent.send} dance.
+     */
     public void send(String target, String text) {
-        herdr.call("agent.send", Map.of("target", target, "text", text));
+        agentCall("agent.prompt", target, Map.of("text", text));
+    }
+
+    /**
+     * Re-send the submit keystroke (Enter) to {@code target}. The submit that accompanies a
+     * delivery can race the paste — especially right as the worker's TUI becomes interactive —
+     * leaving the text unsubmitted; the injector nudges it with this until the worker actually
+     * picks up (CB-113).
+     */
+    public void submit(String target) {
+        agentCall("agent.send_keys", target, Map.of("keys", List.of("enter")));
     }
 
     /**
@@ -64,13 +128,13 @@ public final class AgentControl {
      * @param source one of {@code visible|recent|recent_unwrapped|detection}
      */
     public String read(String target, String source) {
-        JsonNode result = herdr.call("agent.read", Map.of("target", target, "source", source));
+        JsonNode result = agentCall("agent.read", target, Map.of("source", source));
         return result.path("read").path("text").asText("");
     }
 
     /** Current agent record (status, session UUID, pane). */
     public Agent get(String target) {
-        return Agent.from(herdr.call("agent.get", Map.of("target", target)).get("agent"));
+        return Agent.from(agentCall("agent.get", target, Map.of()).get("agent"));
     }
 
     /** Just the lifecycle status — what the status-gated injector checks before send. */

bridged/src/main/java/dev/ltms/bridged/herdr/AgentStatus.java

@@ -2,28 +2,38 @@ package dev.ltms.bridged.herdr;
 
 /**
  * A herdr agent's lifecycle state, as reported by {@code agent_status}. Drives the
- * status-gated injector: a worker is safe to inject into only when {@link #IDLE} or
- * {@link #BLOCKED}, never mid-turn ({@link #WORKING}).
+ * status-gated injector: a worker is safe to inject into only when {@link #IDLE},
+ * {@link #BLOCKED}, or {@link #DONE}, never mid-turn ({@link #WORKING}).
  */
 public enum AgentStatus {
     IDLE,
     WORKING,
     BLOCKED,
+    /**
+     * The worker has finished its turn and is settled at an idle prompt. herdr emits this
+     * (observed live alongside {@code idle}) as a turn-complete marker; earlier code mapped the
+     * unrecognized string to {@link #UNKNOWN}, which both wedged delivery (not {@link #injectable})
+     * and mis-fired the CB-109 stall-failure on a worker that had actually answered. It is a
+     * turn-boundary equivalent to {@link #IDLE}: injectable, and a {@code working → done} edge is a
+     * real completion.
+     */
+    DONE,
     UNKNOWN;
 
-    /** Map herdr's wire string ({@code idle|working|blocked|unknown}) to the enum. */
+    /** Map herdr's wire string ({@code idle|working|blocked|done|unknown}) to the enum. */
     public static AgentStatus fromWire(String s) {
         if (s == null) return UNKNOWN;
         return switch (s.toLowerCase()) {
             case "idle" -> IDLE;
             case "working" -> WORKING;
             case "blocked" -> BLOCKED;
+            case "done" -> DONE;
             default -> UNKNOWN;
         };
     }
 
     /** Whether {@code bridged} may inject a message now without stepping on a live turn. */
     public boolean injectable() {
-        return this == IDLE || this == BLOCKED;
+        return this == IDLE || this == BLOCKED || this == DONE;
     }
 }

bridged/src/main/java/dev/ltms/bridged/herdr/LeadTabScanner.java

@@ -0,0 +1,175 @@
+package dev.ltms.bridged.herdr;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.LongSupplier;
+import java.util.function.Supplier;
+
+/**
+ * Discovers which panes host a lead by scanning herdr for tabs the operator labelled by convention
+ * (CB-531), and hands {@link dev.ltms.bridged.auth.CallerResolver} the resulting
+ * {@code terminal_id → lead name} map.
+ *
+ * <p><strong>Why scan at all.</strong> A lead is never spawned — a human opens a tab and starts an
+ * agent in it — so the daemon cannot learn a lead's {@code terminal_id} at creation time the way it
+ * does a worker's. CB-530 solved that by having the operator paste each id into {@code leaders:},
+ * which works but costs a config edit and a daemon restart per lead, and the id is only obtainable
+ * by first starting the session and asking it. Scanning closes that loop: label the tab, and the
+ * pane is recognised on the next resolve.
+ *
+ * <p><strong>Direction of trust.</strong> The label names the lead; it never <em>grants</em>
+ * anything a pane could take for itself. Three properties keep that honest:
+ * <ol>
+ *   <li>Worker spaces are excluded wholesale ({@code excludedWorkspaceLabels}), so a worker cannot
+ *       become a lead by being placed — as a split, say — inside a matching tab.</li>
+ *   <li>A worker cannot rename a tab: {@code tab.rename} is reachable only through
+ *       {@link WorkspaceControl}, which no {@code bridge_*} tool exposes. The label is writable by
+ *       the human at the terminal and by nobody the bridge is defending against.</li>
+ *   <li>The label is a <em>name</em>, not a capability. What a pane may do is decided by
+ *       {@code Authz} against the role {@code CallerResolver} returns; a tab that calls itself a
+ *       lead still cannot act as one unless the daemon's own registry agrees.</li>
+ * </ol>
+ *
+ * <p><strong>CB-558 — bridged now writes lead labels too.</strong> This class used to be able to say
+ * that bridged never renames a lead tab, so the label was always the human's own writing and there
+ * was no round-trip from the daemon's rename back into its next decision.
+ * {@code dev.ltms.bridged.lead.LeadLauncher} ends that: an auto-launched lead is labelled by the
+ * daemon and found again by this scan. The trust direction above is unaffected — bridged writing a
+ * name for a lead it just started is not a pane promoting itself — but <em>staleness</em> becomes
+ * real: a label left behind by a session that has since died would read as a live lead forever.
+ * This scanner does not solve that (its job is naming, and a stale name costs nothing here); the
+ * launcher does, by requiring a running agent in the tab before it counts the lead as live. If you
+ * ever make a decision that <em>removes</em> something based on this map, add the same check.
+ * The remaining hazard is an <em>operator</em> one — a worker {@code tabLabel} template that
+ * happens to start with the same prefix would promote the whole fleet — and that is refused at
+ * startup by {@code BridgedConfig.validateLeadScan} rather than documented here.
+ *
+ * <p><strong>Caching.</strong> {@link #get()} is on the request path (every resolve), so the scan
+ * is TTL-cached and a stale-but-valid map is preferred to a herdr round-trip. A failed scan keeps
+ * the previous answer instead of emptying it — a herdr hiccup must not silently demote a live lead
+ * mid-session.
+ */
+public final class LeadTabScanner implements Supplier<Map<String, String>> {
+
+    private static final Logger log = LoggerFactory.getLogger(LeadTabScanner.class);
+
+    private final HerdrClient herdr;
+    private final String tabPrefix;
+    private final Set<String> excludedWorkspaceLabels;
+    private final Map<String, String> configuredLeads;
+    private final long ttlNanos;
+    private final LongSupplier clock;
+
+    private Map<String, String> cached;
+    private long scannedAtNanos;
+    private boolean everScanned;
+
+    /**
+     * @param herdr                   the herdr client to query ({@code workspace.list},
+     *                                {@code tab.list}, {@code pane.list} — all read-only)
+     * @param tabPrefix               a tab whose label starts with this (case-insensitively) hosts a
+     *                                lead; the rest of the label, trimmed, is the lead's name
+     * @param excludedWorkspaceLabels workspaces never scanned — the configured worker spaces
+     * @param configuredLeads         the static {@code leaders:}/{@code primary:} registry, merged
+     *                                over every scan result. Explicit config outranks the
+     *                                convention, and survives a scan that cannot run at all
+     * @param ttlNanos                how long a scan result is reused before the next one
+     * @param clock                   nanosecond time source ({@code System::nanoTime} in production)
+     */
+    public LeadTabScanner(HerdrClient herdr, String tabPrefix, Set<String> excludedWorkspaceLabels,
+                          Map<String, String> configuredLeads, long ttlNanos, LongSupplier clock) {
+        this.herdr = herdr;
+        this.tabPrefix = tabPrefix == null || tabPrefix.isBlank() ? "lead:" : tabPrefix.strip();
+        this.excludedWorkspaceLabels = excludedWorkspaceLabels == null
+                ? Set.of() : Set.copyOf(excludedWorkspaceLabels);
+        this.configuredLeads = configuredLeads == null ? Map.of() : Map.copyOf(configuredLeads);
+        this.ttlNanos = ttlNanos;
+        this.clock = clock;
+        this.cached = this.configuredLeads;
+    }
+
+    /**
+     * The current {@code terminal_id → lead name} map, rescanning when the cache has expired.
+     *
+     * <p>Synchronized so a burst of concurrent calls produces one scan rather than one each; a scan
+     * is a handful of RPCs over a Unix socket and is rate-limited to one per TTL.
+     */
+    @Override
+    public synchronized Map<String, String> get() {
+        long now = clock.getAsLong();
+        if (everScanned && now - scannedAtNanos < ttlNanos) {
+            return cached;
+        }
+        // Stamp before scanning, not after: a herdr that is down must cost one attempt per TTL, not
+        // one per request.
+        scannedAtNanos = now;
+        everScanned = true;
+        try {
+            Map<String, String> fresh = scan();
+            if (!fresh.equals(cached)) {
+                log.info("lead panes: {}", fresh);
+            }
+            cached = fresh;
+        } catch (HerdrException e) {
+            log.warn("lead-tab scan failed, keeping the {} lead(s) already known: {}",
+                    cached.size(), e.getMessage());
+        }
+        return cached;
+    }
+
+    /** One full pass: labelled tabs → their panes → those panes' terminals. */
+    private Map<String, String> scan() {
+        Map<String, String> nameByTab = new LinkedHashMap<>();
+        for (JsonNode w : herdr.call("workspace.list").path("workspaces")) {
+            Workspace ws = Workspace.from(w);
+            if (ws.workspaceId() == null || excludedWorkspaceLabels.contains(ws.label())) {
+                continue;
+            }
+            for (JsonNode t : herdr.call("tab.list", Map.of("workspace_id", ws.workspaceId())).path("tabs")) {
+                Tab tab = Tab.from(t);
+                String name = leadNameOf(tab.label());
+                if (name != null && tab.tabId() != null) {
+                    nameByTab.put(tab.tabId(), name);
+                }
+            }
+        }
+
+        Map<String, String> byTerminal = new LinkedHashMap<>();
+        if (!nameByTab.isEmpty()) {
+            // One pane.list for every tab: panes carry tab_id, so the join is local.
+            for (JsonNode p : herdr.call("pane.list", Map.of()).path("panes")) {
+                String name = nameByTab.get(p.path("tab_id").asText(null));
+                String terminal = p.path("terminal_id").asText(null);
+                if (name != null && terminal != null && !terminal.isBlank()) {
+                    byTerminal.put(terminal, name);
+                }
+            }
+        }
+        byTerminal.putAll(configuredLeads); // an explicit pin outranks a label
+        return Collections.unmodifiableMap(byTerminal);
+    }
+
+    /**
+     * The lead name a tab label declares, or {@code null} if it declares none.
+     *
+     * <p>{@code "lead: opus-5.0"} → {@code "opus-5.0"}. A bare {@code "lead:"} names nobody and is
+     * rejected: an unnamed lead would resolve as {@code PRIMARY} with nothing to attribute it to.
+     */
+    private String leadNameOf(String label) {
+        if (label == null) {
+            return null;
+        }
+        String l = label.strip();
+        if (!l.regionMatches(true, 0, tabPrefix, 0, tabPrefix.length())) {
+            return null;
+        }
+        String name = l.substring(tabPrefix.length()).strip();
+        return name.isEmpty() ? null : name;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/herdr/PaneLocator.java

@@ -0,0 +1,59 @@
+package dev.ltms.bridged.herdr;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+import java.util.Map;
+
+/**
+ * Resolves which herdr pane a process belongs to — the herdr half of connection-based MCP
+ * identity (CB-105). Given the PID that opened an MCP connection, {@link #terminalForPid} finds
+ * the agent pane whose process tree contains it, so {@code bridged} can tell <em>which worker</em>
+ * is calling without the worker sending anything spoofable.
+ *
+ * <p>herdr owns the PID→pane truth: {@code pane.process_info} reports each pane's {@code shell_pid}
+ * and foreground process PIDs. This scans agent panes; a spawn-time {@code pid→terminal} cache is
+ * the obvious optimization once wired into {@code ClaudeCodeLauncher}.
+ */
+public final class PaneLocator {
+
+    private final HerdrClient herdr;
+
+    public PaneLocator(HerdrClient herdr) {
+        this.herdr = herdr;
+    }
+
+    /**
+     * The {@code terminal_id} of the agent pane whose process tree contains {@code pid}, or
+     * {@code null} if no agent pane owns it (e.g. the caller is the primary, or off-host).
+     */
+    public String terminalForPid(long pid) {
+        if (pid <= 0) {
+            return null;
+        }
+        for (JsonNode pane : herdr.call("pane.list", Map.of()).path("panes")) {
+            String paneId = pane.path("pane_id").asText(null);
+            if (paneId != null && paneOwnsPid(paneId, pid)) {
+                return pane.path("terminal_id").asText(null);
+            }
+        }
+        return null;
+    }
+
+    private boolean paneOwnsPid(String paneId, long pid) {
+        JsonNode info;
+        try {
+            info = herdr.call("pane.process_info", Map.of("pane_id", paneId)).path("process_info");
+        } catch (HerdrException e) {
+            return false; // pane vanished mid-scan — just skip it
+        }
+        if (info.path("shell_pid").asLong(-1) == pid) {
+            return true;
+        }
+        for (JsonNode p : info.path("foreground_processes")) {
+            if (p.path("pid").asLong(-1) == pid) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/herdr/Tab.java

@@ -23,9 +23,9 @@ public record Tab(String tabId, String workspaceId, String label, int paneCount)
     }
 
     /**
-     * A freshly-created tab together with the placeholder shell pane herdr seeds it with.
-     * The caller starts the worker into {@link #tab()} then closes {@link #rootPaneId()} so
-     * only the worker pane remains.
+     * A freshly-created tab together with the shell pane herdr seeds it with. Under protocol 19
+     * the caller starts the worker <em>into</em> {@link #rootPaneId()} — the seed pane's shell
+     * carries the worker's cwd and env from {@code tab.create}, and becomes the worker pane.
      */
     public record Created(Tab tab, String rootPaneId) {
         /** Project a {@code tab_created} result ({@code {tab, root_pane}}). */

bridged/src/main/java/dev/ltms/bridged/herdr/WorkspaceControl.java

@@ -5,6 +5,7 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.util.ArrayList;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -40,6 +41,16 @@ public final class WorkspaceControl {
         return out;
     }
 
+    /** Every tab in {@code workspaceId}, in herdr's order. */
+    public List<Tab> listTabs(String workspaceId) {
+        JsonNode result = herdr.call("tab.list", Map.of("workspace_id", workspaceId));
+        List<Tab> out = new ArrayList<>();
+        for (JsonNode t : result.path("tabs")) {
+            out.add(Tab.from(t));
+        }
+        return out;
+    }
+
     /** The first workspace with this exact label, if any. */
     public Optional<Workspace> findByLabel(String label) {
         return listWorkspaces().stream()
@@ -65,13 +76,37 @@ public final class WorkspaceControl {
     }
 
     /**
-     * A brand-new tab in {@code workspaceId} plus the placeholder shell pane herdr seeds
-     * it with. Start the worker into the tab, then {@code pane.close} the root pane so the
-     * tab holds only the worker.
+     * A brand-new tab in {@code workspaceId} plus the shell pane herdr seeds it with. Under
+     * protocol 19 that seed pane is where the worker <em>starts</em>: its shell carries
+     * {@code cwd} and {@code env} (the worker's {@code ANTHROPIC_BASE_URL} — this is the
+     * subscription-injection seam now), and {@code agent.start} launches the agent into it.
      */
-    public Tab.Created createTab(String workspaceId) {
-        JsonNode result = herdr.call("tab.create", Map.of("workspace_id", workspaceId));
-        return Tab.Created.from(result);
+    public Tab.Created createTab(String workspaceId, String cwd, Map<String, String> env) {
+        Map<String, Object> params = new LinkedHashMap<>();
+        params.put("workspace_id", workspaceId);
+        if (cwd != null && !cwd.isBlank()) {
+            params.put("cwd", cwd);
+        }
+        if (env != null && !env.isEmpty()) {
+            params.put("env", env);
+        }
+        return Tab.Created.from(herdr.call("tab.create", params));
+    }
+
+    /**
+     * Split the currently-focused tab and return the new pane's id — the legacy pane placement's
+     * seed pane, carrying {@code cwd} and {@code env} exactly as {@link #createTab}'s does.
+     */
+    public String splitPane(String cwd, Map<String, String> env) {
+        Map<String, Object> params = new LinkedHashMap<>();
+        params.put("direction", "right");
+        if (cwd != null && !cwd.isBlank()) {
+            params.put("cwd", cwd);
+        }
+        if (env != null && !env.isEmpty()) {
+            params.put("env", env);
+        }
+        return herdr.call("pane.split", params).path("pane").path("pane_id").asText(null);
     }
 
     /** Give a worker's tab a human label in the tab bar. */

bridged/src/main/java/dev/ltms/bridged/inject/CompletionResolver.java

@@ -0,0 +1,265 @@
+package dev.ltms.bridged.inject;
+
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.msg.Rendezvous;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * The CB-106 completion fallback: bridges the {@link Injector}'s turn-completion signal to the
+ * {@link Rendezvous} so a blocking {@code bridge_send} resolves even when the worker finishes its
+ * task without ever calling {@code bridge_reply} — the common case for a real delegated coding task.
+ *
+ * <p>On a confirmed {@code working → idle} boundary it scrapes the worker's recent transcript and
+ * resolves the awaiting send with that tail (a {@link Rendezvous.Kind#COMPLETION} resolution, so the
+ * caller can tell a scrape from a structured reply). It scrapes only when a send is actually waiting
+ * — a fleet worker's own turns, or a send that already timed out, cost no herdr traffic. An explicit
+ * {@code bridge_reply} that raced in first wins; {@link Rendezvous#resolveCompletion} is then a no-op.
+ *
+ * <p>It also handles the CB-109 stall signal ({@link #onTurnFailed}): a worker that ran a turn then
+ * wedged in an {@code unknown} state resolves the send as a failure (with the error screen as
+ * context) rather than leaving it to time out.
+ *
+ * <p>The scrape is cleaned to the last {@code ⏺} assistant block (stripping TUI chrome) and guarded
+ * against misattribution (CB-115): the pane content is baselined on delivery ({@link #onDelivered}),
+ * and a completion whose scrape is unchanged from that baseline — the previous turn's wind-down
+ * sampled as this turn's boundary on a rapid back-to-back send — is suppressed rather than resolving
+ * the send with a stale answer.
+ *
+ * <p><strong>Waiter-specific resolution (CB-116).</strong> On delivery we also capture the exact
+ * {@link Rendezvous} waiter this turn belongs to, and the completion/failure fallbacks resolve
+ * <em>that</em> waiter — never "whatever send is waiting now". A completion fallback runs on a virtual
+ * thread and can land after the worker's {@code bridge_reply} already resolved the turn and the
+ * <em>next</em> send opened its own waiter on the same session; resolving the current waiter would
+ * then deliver turn N's stale scrape as turn N+1's answer. Targeting the captured waiter makes a late
+ * completion a harmless no-op (its waiter is already done) instead of a cross-turn stale reply.
+ *
+ * <p>Wired as the {@link Injector}'s {@link TurnListener}; the handlers hand off to a virtual thread
+ * so the scrape's herdr round-trip never stalls the status poller. The captured waiter is read on the
+ * poller thread (before any next-turn delivery can overwrite it) and passed into the virtual thread.
+ */
+public final class CompletionResolver implements TurnListener {
+
+    private static final Logger log = LoggerFactory.getLogger(CompletionResolver.class);
+
+    /**
+     * herdr {@code agent.read} source for the completion scrape. {@code recent} returns the tail of
+     * the transcript (the worker's last output), which is what a delegator wants when the worker
+     * didn't structure a reply.
+     */
+    static final String SCRAPE_SOURCE = "recent";
+
+    /** Cap the scraped tail so a long transcript can't return an unbounded blob. */
+    static final int MAX_SCRAPE_CHARS = 4000;
+
+    private final AgentControl agents;
+    private final Rendezvous rendezvous;
+
+    /**
+     * Per-target record of the turn currently in flight: the exact {@link Rendezvous} waiter its
+     * delivering send opened, plus the assistant block present when it was delivered.
+     *
+     * <p>The {@code waiter} is what makes a late fallback safe (CB-116): we resolve it, not "whoever
+     * is waiting now", so a completion that fires after the next send has opened its own waiter is a
+     * no-op rather than a cross-turn stale reply. The {@code baseline} is the CB-115 staleness
+     * reference: a completion scrape equal to it means the worker produced no new output (the previous
+     * turn's wind-down sampled as this boundary), so it is suppressed. Overwritten on each delivery;
+     * cleared when the turn resolves. Package-private so tests can capture and replay a specific turn.
+     */
+    record InFlight(CompletableFuture<Rendezvous.Resolution> waiter, String baseline) {
+    }
+
+    private final ConcurrentHashMap<String, InFlight> inFlight = new ConcurrentHashMap<>();
+
+    public CompletionResolver(AgentControl agents, Rendezvous rendezvous) {
+        this.agents = agents;
+        this.rendezvous = rendezvous;
+    }
+
+    @Override
+    public void onDelivered(String target) {
+        // Capture the exact waiter this turn belongs to (CB-116) and snapshot the pane's pre-turn
+        // content — what it shows *before* the just-delivered turn produces output — as the staleness
+        // reference (CB-115). Done synchronously (like the delivering send itself) so both are in
+        // place before this turn's completion can fire.
+        captureBaseline(target);
+    }
+
+    /** Capture the in-flight turn: its waiter and pre-turn baseline (the testable core of {@link #onDelivered}). */
+    void captureBaseline(String target) {
+        CompletableFuture<Rendezvous.Resolution> waiter = rendezvous.currentWaiter(target);
+        if (waiter == null) {
+            inFlight.remove(target); // no send is waiting on this delivery — nothing to resolve later
+            return;
+        }
+        String baseline;
+        try {
+            // Clip to the same cap resolve() applies to the tail (line ~134): the CB-115 misattribution
+            // guard compares baseline.equals(tail), so both sides must be the same capped representation.
+            // An unclipped baseline vs a clipped tail would never match for a >MAX_SCRAPE_CHARS block,
+            // defeating the guard and letting a stale completion resolve the send.
+            baseline = clip(lastAssistantBlock(agents.read(target, SCRAPE_SOURCE)));
+        } catch (RuntimeException e) {
+            baseline = null; // fail open: no baseline ⇒ no suppression
+            log.debug("delivery baseline for {} failed: {}", target, e.getMessage());
+        }
+        inFlight.put(target, new InFlight(waiter, baseline));
+    }
+
+    /** The turn currently baselined for {@code target}, or {@code null} — a test hook for the captureBaseline path. */
+    InFlight inFlight(String target) {
+        return inFlight.get(target);
+    }
+
+    @Override
+    public void onTurnComplete(String target) {
+        // Read the in-flight turn on the poller thread — before any next-turn delivery can overwrite
+        // it — then off-load the scrape (a herdr round-trip we must not block polling on) to a vthread.
+        InFlight turn = inFlight.get(target);
+        Thread.ofVirtual().name("completion-" + target).start(() -> resolve(target, turn));
+    }
+
+    /**
+     * Resolve the completed turn before adapter housekeeping can erase its rendered output. This is
+     * intentionally synchronous and used only when a post-turn context reset is enabled; the normal
+     * path remains off-loaded so polling is not blocked by a scrape.
+     */
+    public void resolveBeforePostAction(String target) {
+        resolve(target, inFlight.get(target));
+    }
+
+    @Override
+    public void onTurnFailed(String target) {
+        InFlight turn = inFlight.get(target);
+        Thread.ofVirtual().name("turn-failed-" + target).start(() -> fail(target, turn));
+    }
+
+    /** Synchronous resolve (the unit-testable core of {@link #onTurnComplete}). */
+    void resolve(String target, InFlight turn) {
+        CompletableFuture<Rendezvous.Resolution> waiter = turn == null ? null : turn.waiter();
+        if (waiter == null || waiter.isDone()) {
+            // Nobody is blocked on THIS turn (it had no send, or its bridge_reply already won). Skip
+            // the scrape; resolving the current waiter here would be the CB-116 cross-turn stale reply.
+            inFlight.remove(target, turn);
+            return;
+        }
+        String tail;
+        boolean scrapeFailed = false;
+        try {
+            tail = clip(lastAssistantBlock(agents.read(target, SCRAPE_SOURCE)));
+        } catch (RuntimeException e) {
+            // The worker finished but we couldn't read its screen — still resolve the send so the
+            // caller unblocks; an empty tail beats hanging until the caller's timeout.
+            log.warn("completion scrape for {} failed; resolving with an empty tail: {}",
+                    target, e.getMessage());
+            tail = "";
+            scrapeFailed = true;
+        }
+        // Misattribution guard (CB-115): if the scrape is byte-identical to the pane content at
+        // delivery, this turn produced no new output — the boundary belongs to the previous turn's
+        // wind-down (common on rapid back-to-back sends). Suppress rather than resolve the send with
+        // a stale answer; the real bridge_reply (or a later genuine completion) resolves it instead.
+        // A scrape that failed to read is exempt — an empty tail there is "couldn't see", not "no change".
+        String baseline = turn.baseline();
+        if (!scrapeFailed && baseline != null && baseline.equals(tail)) {
+            log.debug("suppressing misattributed completion for {} (no output change since delivery)",
+                    target);
+            return; // keep the in-flight record: a later genuine completion still needs it
+        }
+        if (rendezvous.resolveCompletion(waiter, tail)) {
+            inFlight.remove(target, turn);
+            log.debug("resolved send to {} via turn-completion fallback ({} chars scraped)",
+                    target, tail.length());
+        }
+    }
+
+    /** Synchronous fail (the unit-testable core of {@link #onTurnFailed}). */
+    void fail(String target, InFlight turn) {
+        // A never-delivered readiness failure has no in-flight record but still has a blocked send;
+        // fall back to the currently-registered waiter (unambiguous — that send never completed, so
+        // no next turn exists to confuse it with).
+        CompletableFuture<Rendezvous.Resolution> waiter =
+                turn != null ? turn.waiter() : rendezvous.currentWaiter(target);
+        if (waiter == null || waiter.isDone()) {
+            inFlight.remove(target, turn); // nobody blocked on this worker — nothing to fail
+            return;
+        }
+        String reason;
+        try {
+            reason = clip(agents.read(target, SCRAPE_SOURCE));
+        } catch (RuntimeException e) {
+            reason = "";
+        }
+        if (reason.isBlank()) {
+            // No screen to scrape — either the worker is stuck (CB-109) or gone (CB-110).
+            reason = "worker did not reply; its turn ended in an unrecoverable state "
+                    + "(worker unreachable or stuck)";
+        }
+        if (rendezvous.resolveFailure(waiter, reason)) {
+            inFlight.remove(target, turn);
+            log.debug("failed send to {} via turn-stall fallback", target);
+        }
+    }
+
+    private static String clip(String s) {
+        if (s == null) return "";
+        String trimmed = s.strip();
+        return trimmed.length() <= MAX_SCRAPE_CHARS
+                ? trimmed
+                : trimmed.substring(trimmed.length() - MAX_SCRAPE_CHARS);
+    }
+
+    /**
+     * Extract the last assistant message from a raw Claude Code pane scrape (CB-115). Claude Code
+     * prefixes each assistant turn with {@code ⏺}; the delegator wants that answer, not the TUI
+     * chrome around it. Take everything from the final {@code ⏺} onward and stop at the <em>first</em>
+     * hard interface boundary below it — the spinner/status line, input box, {@code ❯} prompt (which
+     * may echo the <em>next</em> turn's text), footer, or tips/warnings. Stopping at the first
+     * boundary (rather than trimming only trailing chrome) is what keeps a following turn's echoed
+     * prompt out of this reply. Blank lines are not boundaries, so a multi-paragraph answer survives;
+     * trailing blanks are trimmed at the end. With no {@code ⏺} marker (an unusual render) the whole
+     * text is scanned the same way, so we never lose the reply.
+     *
+     * <p>Package-private and pure so it is unit-testable without herdr.
+     */
+    static String lastAssistantBlock(String raw) {
+        if (raw == null || raw.isBlank()) return "";
+        int marker = raw.lastIndexOf('⏺');
+        String block = marker >= 0 ? raw.substring(marker + 1) : raw;
+        StringBuilder out = new StringBuilder();
+        int kept = 0;
+        for (String line : block.split("\n", -1)) {
+            if (isBoundary(line)) break; // first TUI boundary ends the assistant message
+            if (kept++ > 0) out.append('\n');
+            out.append(line);
+        }
+        return out.toString().strip();
+    }
+
+    /**
+     * A hard TUI boundary line that marks the end of an assistant message and the start of interface
+     * chrome (input box, prompt, spinner, footer, tips/warnings). Blank lines are <em>not</em>
+     * boundaries — an answer may contain them — so they are kept and trimmed only if trailing.
+     */
+    private static boolean isBoundary(String line) {
+        String t = line.strip();
+        if (t.isEmpty()) return false;
+        // A horizontal rule / all box-drawing separators (e.g. "──────").
+        if (t.chars().allMatch(c -> c == '─' || c == '—' || c == '━' || c == '═' || c == '-')) {
+            return true;
+        }
+        String lower = t.toLowerCase();
+        return t.startsWith("╭") || t.startsWith("│") || t.startsWith("╰") || t.startsWith("┌")
+                || t.startsWith("└") || t.startsWith("❯") || t.startsWith("⏵")
+                || t.startsWith("⎿") || t.startsWith("⚠")
+                // Status/spinner lines Claude Code renders below a settled or in-flight turn,
+                // e.g. "✻ Baked for 21s", "✶ Forming…".
+                || t.startsWith("✻") || t.startsWith("✳") || t.startsWith("✽") || t.startsWith("·")
+                || t.startsWith("●") || t.startsWith("◐") || t.startsWith("✢") || t.startsWith("✶")
+                || lower.contains("auto mode") || lower.contains("for shortcuts")
+                || lower.contains("esc to interrupt") || lower.contains("bypass permissions");
+    }
+}

bridged/src/main/java/dev/ltms/bridged/inject/Injector.java

@@ -12,6 +12,8 @@ import java.util.List;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Consumer;
+import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
 /**
@@ -32,6 +34,14 @@ import java.util.stream.Collectors;
  * a transient {@code unknown} — counts as a real pickup, so a detection glitch can't prematurely
  * release the latch. Perfectly reliable turn boundaries require a herdr {@code events.subscribe}
  * stream; that is the intended upgrade and would replace only the sampling, not this queue.
+ *
+ * <p><strong>Turn completion (CB-106).</strong> Beyond delivery, the injector reports when a
+ * delegated turn <em>finishes</em>: after a delivery is picked up (a real {@code working} sample),
+ * the next injectable sample is a confirmed {@code working → idle} boundary and fires
+ * {@link TurnListener#onTurnComplete}. Completion is only ever synthesized from a <em>confirmed</em>
+ * turn — the pickup-grace path (a turn too fast to sample) unwedges the queue but does not fire
+ * completion, since without a sampled {@code working} there is no trustworthy "the worker just
+ * finished the task" signal to act on.
  */
 public final class Injector {
 
@@ -45,11 +55,68 @@ public final class Injector {
      */
     private static final int PICKUP_GRACE_POLLS = 8;
 
+    /**
+     * How many consecutive {@code unknown} samples while a delegation is outstanding before we
+     * declare it stalled and fire {@link TurnListener#onTurnFailed} (CB-109). A worker wedged in a
+     * state herdr can't classify (e.g. an API-error screen) stays {@code unknown} indefinitely and
+     * would otherwise never resolve; any {@code working}/{@code idle} sample resets the streak, so a
+     * transient detection glitch cannot trip it. At the 250ms poll interval this is ~30s — far longer
+     * than any real detection blip, and still vastly better than the async send's timeout.
+     */
+    private static final int TURN_STALL_GRACE_POLLS = 120;
+
+    /**
+     * How many consecutive injectable samples a queued-but-undelivered message may wait on the
+     * {@link #ready} gate before we give up and fail it (CB-114). The gate holds a message out of a
+     * worker's boot window (herdr reports {@code idle} while its Claude is still starting), but a
+     * worker whose Claude crashes during boot — or never connects the bridge MCP — stays "idle and
+     * not ready" forever: {@link #ready} never accepts it, the message is never delivered, and the
+     * target would be polled indefinitely with its caller's future never completing. After this
+     * grace the queued messages are failed and the target released. At the 250ms poll interval this
+     * is ~60s — deliberately longer than {@link #TURN_STALL_GRACE_POLLS}, since a first boot (spawn
+     * + model load + MCP connect) legitimately takes longer than an in-turn detection blip.
+     */
+    private static final int READINESS_GRACE_POLLS = 240;
+
     private final AgentControl agents;
+    private final TurnListener turnListener;
+    private final Predicate<String> ready; // CB-113: a target is deliverable only when available
+    private final Consumer<String> forget; // CB-114: clear a gone worker's readiness/presence
     private final ConcurrentHashMap<String, Target> targets = new ConcurrentHashMap<>();
 
+    /** Delivery only; completion signalling is a no-op and every target is treated as available. */
     public Injector(AgentControl agents) {
+        this(agents, TurnListener.NOOP);
+    }
+
+    /** Delivery plus turn-completion signalling (CB-106); every target is treated as available. */
+    public Injector(AgentControl agents, TurnListener turnListener) {
+        this(agents, turnListener, _ -> true);
+    }
+
+    /**
+     * Delivery, completion signalling (CB-106), and a readiness gate (CB-113): a message is delivered
+     * only when {@code ready} accepts the target — i.e. the worker's Claude has connected the bridge
+     * MCP. This holds the first delivery out of the worker's boot window, where herdr already reports
+     * {@code idle} but the TUI would drop an injected paste.
+     */
+    public Injector(AgentControl agents, TurnListener turnListener, Predicate<String> ready) {
+        this(agents, turnListener, ready, _ -> {
+        });
+    }
+
+    /**
+     * Delivery, completion signalling (CB-106), a readiness gate (CB-113), and readiness cleanup
+     * (CB-114): {@code forget} is invoked with a target when its worker is gone — dropped
+     * (pane crash) or timed out on the readiness gate — so its stale presence/readiness is cleared
+     * and does not linger past the worker's life.
+     */
+    public Injector(AgentControl agents, TurnListener turnListener, Predicate<String> ready,
+                    Consumer<String> forget) {
         this.agents = agents;
+        this.turnListener = turnListener;
+        this.ready = ready;
+        this.forget = forget;
     }
 
     /** A pending message and the future that completes when it has been delivered. */
@@ -59,8 +126,16 @@ public final class Injector {
     /** Per-worker delivery state, guarded by its own monitor (single writer per worker). */
     private static final class Target {
         final Deque<Pending> queue = new ArrayDeque<>();
-        boolean awaitingPickup;   // sent a message, waiting for the worker to pick it up
+        boolean awaitingPickup;    // sent a message, waiting for the worker to pick it up
         int injectableSincePickup; // consecutive injectable samples while awaitingPickup
+        boolean awaitingCompletion; // a delivered message's turn is not yet known-complete
+        boolean turnObserved;      // saw a real `working` sample since that delivery (turn ran)
+        int unknownSinceTurn;      // consecutive `unknown` samples while a delegation is outstanding (CB-109)
+        int notReadySincePoll;     // consecutive injectable samples a queued message waited on the readiness gate (CB-114)
+        boolean postTurnPending;   // completion observed; adapter housekeeping has not started yet
+        boolean awaitingPostTurnPickup;
+        boolean postTurnObserved;
+        int injectableSincePostTurnPickup;
 
         synchronized void add(Pending p) {
             queue.add(p);
@@ -99,63 +174,191 @@ public final class Injector {
 
         Pending sent = null;
         RuntimeException sendError = null;
+        boolean turnCompleted = false;
+        boolean turnFailed = false;
+        boolean resubmit = false;
+        boolean startPostTurn = false;
+        List<Pending> notReady = null; // queued messages failed because the worker never became ready
         synchronized (t) {
             if (status == AgentStatus.WORKING) {
-                // Definitive pickup: the worker is busy on our last message.
+                if (t.awaitingPostTurnPickup) {
+                    t.awaitingPostTurnPickup = false;
+                    t.injectableSincePostTurnPickup = 0;
+                    t.postTurnObserved = true;
+                }
+                // Definitive pickup: the worker is busy on our last message, and (if a delivery is
+                // outstanding) a real turn is now confirmed to be running.
                 t.awaitingPickup = false;
                 t.injectableSincePickup = 0;
+                t.unknownSinceTurn = 0;
+                t.notReadySincePoll = 0;
+                if (t.awaitingCompletion) t.turnObserved = true;
             } else if (status.injectable()) { // IDLE or BLOCKED
-                if (t.awaitingPickup && ++t.injectableSincePickup >= PICKUP_GRACE_POLLS) {
-                    // Pickup edge was never sampled (turn faster than the poll, or status lag).
-                    // The worker has plainly moved on — release the latch rather than wedge.
-                    t.awaitingPickup = false;
-                    t.injectableSincePickup = 0;
+                t.unknownSinceTurn = 0;
+                if (t.awaitingPostTurnPickup) {
+                    if (++t.injectableSincePostTurnPickup >= PICKUP_GRACE_POLLS) {
+                        t.awaitingPostTurnPickup = false;
+                        t.injectableSincePostTurnPickup = 0;
+                    } else {
+                        resubmit = true;
+                    }
+                } else if (t.postTurnObserved) {
+                    t.postTurnObserved = false;
+                }
+                if (t.awaitingPickup) {
+                    if (++t.injectableSincePickup >= PICKUP_GRACE_POLLS) {
+                        // Pickup edge was never sampled (turn faster than the poll, or status lag).
+                        // Release the latch rather than wedge — and give up on synthesizing a
+                        // completion for this message, since without a confirmed `working` we cannot
+                        // trust that a task-processing turn actually ran.
+                        t.awaitingPickup = false;
+                        t.injectableSincePickup = 0;
+                        t.awaitingCompletion = false;
+                        t.turnObserved = false;
+                    } else {
+                        // Delivered but still idle → the worker hasn't picked it up; the submit
+                        // keystroke likely raced the paste (esp. right as the TUI became ready).
+                        // Re-nudge Enter (CB-113) until the worker starts (WORKING) or the grace ends.
+                        resubmit = true;
+                    }
                 }
                 if (!t.awaitingPickup) {
-                    Pending p = t.queue.peek();
-                    if (p != null) {
-                        try {
-                            agents.send(target, p.text());
-                            t.queue.poll();
-                            t.awaitingPickup = true;
-                            t.injectableSincePickup = 0;
-                            sent = p;
-                        } catch (RuntimeException e) {
-                            // Delivery failed at herdr; drop the poisoned message and surface it
-                            // rather than blocking the queue behind it.
-                            t.queue.poll();
-                            sent = p;
-                            sendError = e;
+                    // A confirmed turn (a `working` sample was seen) that has now returned to idle is
+                    // a trustworthy `working → idle` completion boundary.
+                    if (t.awaitingCompletion && t.turnObserved) {
+                        t.awaitingCompletion = false;
+                        t.turnObserved = false;
+                        turnCompleted = true;
+                        if (turnListener.hasPostTurnAction(target)) {
+                            t.postTurnPending = true;
+                            startPostTurn = true;
+                        }
+                    }
+                    // Deliver the next queued message only once the prior turn is fully settled, so a
+                    // completion is never confused with the pickup of the following message — and only
+                    // once the worker is available (CB-113), so we never paste into its boot window.
+                    if (!t.awaitingCompletion && !t.postTurnPending
+                            && !t.awaitingPostTurnPickup && !t.postTurnObserved) {
+                        Pending p = t.queue.peek();
+                        if (p != null && ready.test(target)) {
+                            t.notReadySincePoll = 0;
+                            try {
+                                agents.send(target, p.text());
+                                t.queue.poll();
+                                t.awaitingPickup = true;
+                                t.awaitingCompletion = true;
+                                t.turnObserved = false;
+                                t.injectableSincePickup = 0;
+                                sent = p;
+                            } catch (RuntimeException e) {
+                                // Delivery failed at herdr; drop the poisoned message and surface it
+                                // rather than blocking the queue behind it.
+                                t.queue.poll();
+                                sent = p;
+                                sendError = e;
+                            }
+                        } else if (p != null && ++t.notReadySincePoll >= READINESS_GRACE_POLLS) {
+                            // The worker has been idle-but-not-ready for the whole grace: its Claude
+                            // never connected the bridge MCP (crashed during boot, or wedged on a
+                            // startup prompt). The readiness gate would hold this message forever, so
+                            // fail every queued message and release the target (CB-114) instead of
+                            // polling it indefinitely with the caller's future never completing.
+                            notReady = new ArrayList<>(t.queue);
+                            t.queue.clear();
+                            t.notReadySincePoll = 0;
                         }
                     }
                 }
+            } else {
+                // UNKNOWN (or any other non-injectable, non-working): not a safe window nor a
+                // reliable pickup signal, so we never deliver or release the pickup latch here. But
+                // an outstanding delegation whose worker has gone unresponsive — stuck in a state
+                // herdr can't classify (CB-109) — will never yield a working→idle boundary. After a
+                // sustained streak, declare it failed so the awaiting send resolves rather than
+                // riding out the async timeout. (This also frees a delivery that wedged before it
+                // was ever picked up, which the injectable-only pickup grace could never release.)
+                if (t.awaitingCompletion && ++t.unknownSinceTurn >= TURN_STALL_GRACE_POLLS) {
+                    t.awaitingPickup = false;
+                    t.awaitingCompletion = false;
+                    t.turnObserved = false;
+                    t.unknownSinceTurn = 0;
+                    turnFailed = true;
+                }
             }
-            // UNKNOWN (and any other non-injectable, non-working): do nothing — neither a safe
-            // window nor a reliable pickup signal, so we must not deliver or release the latch.
 
-            // Reclaim the entry once the worker is fully quiescent, so the map cannot grow without
-            // bound across many short-lived workers.
-            if (t.queue.isEmpty() && !t.awaitingPickup) {
+            // Reclaim the entry once the worker is fully quiescent (nothing queued, no pickup or
+            // completion awaited), so the map cannot grow without bound across short-lived workers.
+            if (t.queue.isEmpty() && !t.awaitingPickup && !t.awaitingCompletion
+                    && !t.postTurnPending && !t.awaitingPostTurnPickup && !t.postTurnObserved) {
                 targets.remove(target, t);
             }
         }
 
+        // Fire listeners / herdr calls after releasing the monitor so nothing runs on the poller
+        // thread while it holds the target lock.
+        if (resubmit) {
+            try {
+                agents.submit(target); // nudge a raced Enter so the pending paste submits
+            } catch (RuntimeException e) {
+                log.debug("resubmit to {} failed (will retry next poll): {}", target, e.getMessage());
+            }
+        }
+        if (notReady != null) {
+            // Worker never became available: forget its (never-set) readiness, unblock every queued
+            // caller, and route the awaiting send through the same failure path as a stalled turn so
+            // a blocking or async waiter resolves WORKER_FAILED rather than riding out the timeout.
+            forget.accept(target);
+            RuntimeException cause = new IllegalStateException(
+                    target + " never became available (no bridge MCP connection within the boot window)");
+            for (Pending p : notReady) {
+                p.delivered().completeExceptionally(cause);
+            }
+            turnListener.onTurnFailed(target);
+        }
+        if (turnCompleted) {
+            if (startPostTurn) {
+                boolean started = turnListener.onTurnCompleteWithPostAction(target);
+                synchronized (t) {
+                    t.postTurnPending = false;
+                    if (started) {
+                        t.awaitingPostTurnPickup = true;
+                        t.injectableSincePostTurnPickup = 0;
+                    }
+                    if (t.queue.isEmpty() && !t.awaitingPostTurnPickup) {
+                        targets.remove(target, t);
+                    }
+                }
+            } else {
+                turnListener.onTurnComplete(target);
+            }
+        }
+        if (turnFailed) {
+            turnListener.onTurnFailed(target);
+        }
         if (sent != null) {
             if (sendError != null) {
                 log.warn("inject to {} failed, dropped message: {}", target, sendError.getMessage());
                 sent.delivered().completeExceptionally(sendError);
             } else {
+                // Baseline the pane's pre-turn content so a misattributed completion (no new output)
+                // can't resolve this send with the previous turn's stale answer (CB-115).
+                turnListener.onDelivered(target);
                 sent.delivered().complete(null);
             }
         }
     }
 
-    /** Targets the poller must keep sampling: those with a queued message or an awaited pickup. */
+    /**
+     * Targets the poller must keep sampling: those with a queued message, an awaited pickup, or an
+     * awaited turn completion (so the {@code working → idle} boundary is observed).
+     */
     public Set<String> activeTargets() {
         return targets.entrySet().stream()
                 .filter(e -> {
                     synchronized (e.getValue()) {
-                        return !e.getValue().queue.isEmpty() || e.getValue().awaitingPickup;
+                        Target t = e.getValue();
+                        return !t.queue.isEmpty() || t.awaitingPickup || t.awaitingCompletion
+                                || t.postTurnPending || t.awaitingPostTurnPickup || t.postTurnObserved;
                     }
                 })
                 .map(java.util.Map.Entry::getKey)
@@ -163,20 +366,34 @@ public final class Injector {
     }
 
     /**
-     * Forget a target whose worker is gone, failing every still-queued message so awaiting
-     * callers unblock instead of hanging forever. Futures are completed after the monitor is
-     * released.
+     * Forget a target whose worker is gone, failing every still-queued message so awaiting callers
+     * unblock instead of hanging forever. If a message had already been <em>delivered</em> but its
+     * turn was not yet resolved (CB-110 — the worker vanished mid-turn, e.g. its pane crashed), fire
+     * {@link TurnListener#onTurnFailed} for it: a delivered message is no longer in the queue, so
+     * failing queued waiters alone would leave that send's rendezvous hanging until the async
+     * timeout. Futures and listeners are completed after the monitor is released.
      */
     public void drop(String target, Throwable cause) {
         Target t = targets.remove(target);
         if (t == null) return;
         List<Pending> pending;
+        boolean hadDeliveredTurn;
         synchronized (t) {
             pending = new ArrayList<>(t.queue);
             t.queue.clear();
+            hadDeliveredTurn = t.awaitingCompletion;
+            t.awaitingCompletion = false;
+            t.awaitingPickup = false;
+            t.postTurnPending = false;
+            t.awaitingPostTurnPickup = false;
+            t.postTurnObserved = false;
         }
+        forget.accept(target); // the worker is gone — clear its readiness/presence too (CB-114)
         for (Pending p : pending) {
             p.delivered().completeExceptionally(cause);
         }
+        if (hadDeliveredTurn) {
+            turnListener.onTurnFailed(target);
+        }
     }
 }

bridged/src/main/java/dev/ltms/bridged/inject/MemberPresence.java

@@ -0,0 +1,38 @@
+package dev.ltms.bridged.inject;
+
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.Set;
+
+/**
+ * Tracks which workers are <em>available</em> — their Claude has booted and connected its MCP client
+ * to the bridge (CB-113). This is the reliable readiness signal, unlike herdr's {@code agent_status},
+ * which reports {@code idle} for a worker whose Claude is still booting. Delivering into that boot
+ * window pastes into a not-yet-ready TUI (the text is lost) and wedges the worker's delivery state,
+ * so the {@link Injector} holds the first delivery until the worker is present here.
+ *
+ * <p>Populated from the MCP transport: any MCP request whose connection resolves to a worker terminal
+ * marks that worker present (its {@code initialize} is the first such contact). A worker that never
+ * mounts the bridge MCP is never marked present — its sends stay queued until they time out, which is
+ * correct (it could not have replied anyway).
+ */
+public class MemberPresence {
+
+    private final Set<String> present = ConcurrentHashMap.newKeySet();
+
+    /** Record that {@code terminal}'s worker has connected its MCP client (is available). */
+    public void markPresent(String terminal) {
+        if (terminal != null && !terminal.isBlank()) {
+            present.add(terminal);
+        }
+    }
+
+    /** Whether {@code terminal}'s worker is available (has been seen on the bridge MCP). */
+    public boolean isPresent(String terminal) {
+        return present.contains(terminal);
+    }
+
+    /** Forget a torn-down worker so its terminal id does not linger as "present". */
+    public void forget(String terminal) {
+        present.remove(terminal);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/inject/StatusPoller.java

@@ -23,13 +23,20 @@ public final class StatusPoller {
 
     private final AgentControl agents;
     private final Injector injector;
+    private final StatusRefiner refiner;
     private final long intervalMillis;
     private volatile boolean running;
     private Thread thread;
 
     public StatusPoller(AgentControl agents, Injector injector, long intervalMillis) {
+        this(agents, injector, new StatusRefiner(agents), intervalMillis);
+    }
+
+    public StatusPoller(AgentControl agents, Injector injector, StatusRefiner refiner,
+                        long intervalMillis) {
         this.agents = agents;
         this.injector = injector;
+        this.refiner = refiner;
         this.intervalMillis = intervalMillis;
     }
 
@@ -47,7 +54,9 @@ public final class StatusPoller {
             for (String target : active) {
                 if (!running) return;
                 try {
-                    AgentStatus status = agents.status(target);
+                    // herdr's agent_status can misreport a settled worker as `unknown`; refine it
+                    // against the pane content before it drives delivery/completion (CB-115).
+                    AgentStatus status = refiner.refine(target, agents.status(target));
                     injector.onStatus(target, status);
                 } catch (HerdrException e) {
                     // The worker's agent is gone — stop trying and unblock its waiters.

bridged/src/main/java/dev/ltms/bridged/inject/StatusRefiner.java

@@ -0,0 +1,89 @@
+package dev.ltms.bridged.inject;
+
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.AgentStatus;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Refines an unreliable {@link AgentStatus#UNKNOWN} into a real state by reading the worker's
+ * terminal content (CB-115).
+ *
+ * <p>Some workers' panes are misclassified by herdr as {@code unknown} even when the worker is
+ * plainly settled at an idle prompt (empty {@code ❯}, "auto mode on" footer, a completed
+ * {@code ⏺} answer above). Left as {@code UNKNOWN} that both <em>wedges delivery</em> — the
+ * status-gated {@link Injector} only injects into an {@link AgentStatus#injectable} worker — and
+ * <em>mis-fires the CB-109 stall failure</em> on a worker that has actually answered. herdr's
+ * {@code agent_status} is a heuristic; the pane content is the ground truth.
+ *
+ * <p>The refinement only ever runs on a raw {@code UNKNOWN} sample (every other status is trusted
+ * as-is), so a healthy worker adds zero extra herdr traffic; a persistently-{@code unknown} worker
+ * costs one extra {@code agent.read} per poll while it has work outstanding. Classification is
+ * deliberately conservative — it upgrades {@code UNKNOWN} to {@link AgentStatus#WORKING} or
+ * {@link AgentStatus#IDLE} only on a clear signal, and leaves a genuinely unclassifiable screen
+ * (e.g. a wedged error state) as {@code UNKNOWN} so the CB-109 stall path can still fail it.
+ */
+public final class StatusRefiner {
+
+    private static final Logger log = LoggerFactory.getLogger(StatusRefiner.class);
+
+    /**
+     * herdr {@code agent.read} source used to inspect the pane. {@code detection} is the region
+     * herdr itself uses for status detection (the prompt/footer tail), which is exactly what we
+     * need to tell "idle at prompt" from "mid-turn".
+     */
+    static final String PROBE_SOURCE = "detection";
+
+    private final AgentControl agents;
+
+    public StatusRefiner(AgentControl agents) {
+        this.agents = agents;
+    }
+
+    /**
+     * Return a trustworthy status for {@code target}. Any non-{@code UNKNOWN} {@code raw} is returned
+     * unchanged; an {@code UNKNOWN} triggers a pane read and content classification. A read failure
+     * leaves it {@code UNKNOWN} (the safe default: no delivery, and the stall path still applies).
+     */
+    public AgentStatus refine(String target, AgentStatus raw) {
+        if (raw != AgentStatus.UNKNOWN) return raw;
+        String pane;
+        try {
+            pane = agents.read(target, PROBE_SOURCE);
+        } catch (RuntimeException e) {
+            log.debug("status refine read for {} failed; leaving UNKNOWN: {}", target, e.getMessage());
+            return AgentStatus.UNKNOWN;
+        }
+        AgentStatus refined = classify(pane);
+        if (refined != AgentStatus.UNKNOWN) {
+            log.debug("refined {} from UNKNOWN to {} via pane content", target, refined);
+        }
+        return refined;
+    }
+
+    /**
+     * Classify a Claude Code TUI pane tail. Package-private and pure so it is unit-testable without
+     * herdr.
+     *
+     * <ul>
+     *   <li>An active-generation marker ({@code esc to interrupt}) ⇒ {@link AgentStatus#WORKING} —
+     *       never inject here.</li>
+     *   <li>Otherwise, an interactive input prompt with no active-turn marker ({@code ❯}, the
+     *       {@code │ >} input box, or the idle {@code auto mode} / shortcuts footer) ⇒
+     *       {@link AgentStatus#IDLE} — settled and safe to inject / a completed turn.</li>
+     *   <li>Anything else (blank, or an unrecognizable screen) ⇒ {@link AgentStatus#UNKNOWN}.</li>
+     * </ul>
+     */
+    static AgentStatus classify(String pane) {
+        if (pane == null || pane.isBlank()) return AgentStatus.UNKNOWN;
+        String lower = pane.toLowerCase();
+        // Claude Code shows "(esc to interrupt)" only while a turn is actively generating.
+        if (lower.contains("esc to interrupt")) return AgentStatus.WORKING;
+        // A settled, ready input prompt with no active-turn marker = idle-at-prompt.
+        boolean readyPrompt = pane.contains("❯")
+                || pane.contains("│ >")
+                || lower.contains("auto mode on")
+                || lower.contains("? for shortcuts");
+        return readyPrompt ? AgentStatus.IDLE : AgentStatus.UNKNOWN;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/inject/TurnListener.java

@@ -0,0 +1,58 @@
+package dev.ltms.bridged.inject;
+
+/**
+ * Notified when a worker's delegated turn is observed to complete — a confirmed
+ * {@code WORKING → IDLE} transition after a delivery. This is the CB-106 completion signal the
+ * {@code CompletionResolver} uses to resolve a blocked send whose worker never called
+ * {@code bridge_reply}. Kept as a seam so the {@link Injector} needs no dependency on the message
+ * layer and stays unit-testable with a capturing fake.
+ */
+@FunctionalInterface
+public interface TurnListener {
+
+    /** A worker's delegated turn finished (worker returned to idle after visibly working). */
+    void onTurnComplete(String target);
+
+    /**
+     * Whether completion must pause ordinary delivery while adapter-specific housekeeping starts.
+     * This is queried before the injector considers the next queued message, closing the same-tick
+     * ordering gap. Implementations must not mutate state here.
+     */
+    default boolean hasPostTurnAction(String target) {
+        return false;
+    }
+
+    /**
+     * Complete the delegated turn and start its non-turn housekeeping operation.
+     *
+     * @return true when the injector must observe that operation settle before the next delivery
+     */
+    default boolean onTurnCompleteWithPostAction(String target) {
+        onTurnComplete(target);
+        return false;
+    }
+
+    /**
+     * A worker that visibly ran a delegated turn then wedged in a non-idle, non-working state
+     * (CB-109) — e.g. an error screen herdr classifies as {@code unknown} — so no
+     * {@code working → idle} completion boundary will ever arrive. A default no-op keeps this a
+     * functional interface; the completion resolver overrides it to fail the awaiting send.
+     */
+    default void onTurnFailed(String target) {
+    }
+
+    /**
+     * A message was just delivered into {@code target}'s pane (CB-115). Fired so the completion
+     * resolver can snapshot the pane's pre-turn content: a later {@link #onTurnComplete} whose
+     * scrape is unchanged from this baseline is a <em>misattributed</em> boundary (e.g. the prior
+     * turn's wind-down sampled as this turn's completion on rapid back-to-back sends) and must not
+     * resolve the send with the previous turn's stale answer. A default no-op keeps the interface
+     * functional for callers that don't scrape.
+     */
+    default void onDelivered(String target) {
+    }
+
+    /** No-op default for callers that only need delivery, not completion signalling. */
+    TurnListener NOOP = _ -> {
+    };
+}

bridged/src/main/java/dev/ltms/bridged/lead/LeadLauncher.java

@@ -0,0 +1,304 @@
+package dev.ltms.bridged.lead;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.HerdrException;
+import dev.ltms.bridged.herdr.Tab;
+import dev.ltms.bridged.herdr.Workspace;
+import dev.ltms.bridged.herdr.WorkspaceControl;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * Starts the leads {@code fleet.leaders:} declares, when none is already running (CB-558).
+ *
+ * <p><strong>A lead is not a member, and this class exists to keep it that way.</strong> Every other
+ * spawn path in the daemon goes through {@code HerdrPeerLauncher}, which does three things a lead
+ * must never receive:
+ * <ol>
+ *   <li>it appends the <em>reply charter</em> — "you are an off-subscription worker … end every turn
+ *       with {@code bridge_reply}". A lead is the orchestrator; telling it that it is a worker is
+ *       exactly backwards.</li>
+ *   <li>it registers the session with {@code SessionManager}, which subjects it to the idle reaper,
+ *       the context cap and the shutdown drain. An idle lead is the normal state of a lead, so the
+ *       reaper would kill the orchestrator for doing its job.</li>
+ *   <li>it can move a peer off the subscription via {@code ANTHROPIC_BASE_URL}. A lead stays on the
+ *       operator's subscription, always.</li>
+ * </ol>
+ * So this launcher talks to {@link AgentControl}/{@link WorkspaceControl} directly. The duplication
+ * with the member launchers (argv and env assembly) is deliberate and is the cheaper half of the
+ * trade: entangling the worker path with a not-a-worker case is how the three rules above get
+ * broken later, quietly.
+ *
+ * <p><strong>Liveness, and the label round-trip.</strong> {@code LeadTabScanner} used to be able to
+ * promise that bridged never writes a lead label. That is no longer true — an auto-launched lead is
+ * labelled by this class, and the scanner reads that label back. The risk this opens is not
+ * privilege escalation (the tab label never granted anything a pane could take for itself; see that
+ * class's javadoc), but <em>staleness</em>: a label left behind by a crashed session would otherwise
+ * read as a live lead forever, and the lead would never be relaunched. So a lead counts as live only
+ * when herdr also reports a <em>running agent</em> in that tab — see {@link #liveLeads}. A labelled
+ * tab with no agent in it is not a lead.
+ */
+public final class LeadLauncher {
+
+    private static final Logger log = LoggerFactory.getLogger(LeadLauncher.class);
+
+    private final AgentControl agents;
+    private final WorkspaceControl spaces;
+    private final BridgedConfig cfg;
+
+    /**
+     * @param agents herdr agent control (start, list)
+     * @param spaces workspace / tab control (ensure, create, label, list)
+     * @param cfg    the loaded config — {@code fleet.leaders}, {@code profiles} and the lead pins
+     */
+    public LeadLauncher(AgentControl agents, WorkspaceControl spaces, BridgedConfig cfg) {
+        this.agents = agents;
+        this.spaces = spaces;
+        this.cfg = cfg;
+    }
+
+    /**
+     * Bring every declared lead up to its {@code instances} count, and return how many were started.
+     *
+     * <p>Never throws: a daemon that cannot start a lead must still serve. herdr being unreachable,
+     * a profile that does not exist, a failed {@code agent.start} — each is logged and skipped, and
+     * the remaining leads are still attempted.
+     */
+    public int ensureLeads() {
+        Map<String, BridgedConfig.Leader> leaders = cfg.fleet().leaders();
+        if (leaders.isEmpty()) {
+            return 0;
+        }
+
+        Map<String, Integer> live;
+        try {
+            live = liveLeads(leaders);
+        } catch (HerdrException e) {
+            // Counting is the whole safety mechanism against double-spawning. If we cannot count, we
+            // must not guess — spawning a second orchestrator is worse than starting none.
+            log.warn("lead auto-launch skipped — cannot tell which leads are live: {}", e.getMessage());
+            return 0;
+        }
+
+        int started = 0;
+        for (Map.Entry<String, BridgedConfig.Leader> e : leaders.entrySet()) {
+            String name = e.getKey();
+            BridgedConfig.Leader lead = e.getValue();
+            int running = live.getOrDefault(name, 0);
+            int wanted = lead.instances();
+
+            if (running >= wanted) {
+                log.info("lead '{}': {} live, {} wanted — nothing to start", name, running, wanted);
+                continue;
+            }
+            if (!lead.isCreatable()) {
+                // A lead with a `terminal:` pin and no `profile:` is recognise-only by design: the
+                // operator opens it by hand. Say so once rather than looking like a silent failure.
+                log.info("lead '{}' is not live, and names no profile — it can be recognised but not "
+                        + "launched. Add `profile:` under fleet.leaders.{} to have bridged start it.",
+                        name, name);
+                continue;
+            }
+
+            BridgedConfig.Profile profile = cfg.profiles().get(lead.profile());
+            if (profile == null) {
+                log.warn("lead '{}' names profile '{}', which is not configured — not launching",
+                        name, lead.profile());
+                continue;
+            }
+
+            for (int i = running; i < wanted; i++) {
+                if (launch(name, lead, profile)) {
+                    started++;
+                }
+            }
+        }
+        return started;
+    }
+
+    /**
+     * How many live leads exist per configured name.
+     *
+     * <p>Two independent pieces of evidence, because either alone double-spawns:
+     * <ul>
+     *   <li>a running agent in a tab labelled {@code "<tabPrefix> <name>"} — how an auto-launched
+     *       lead, or an operator following the labelling convention, is found;</li>
+     *   <li>a running agent on a terminal the config pins in {@code fleet.leaders.<name>.terminal} —
+     *       how a lead the operator opened and pinned by hand is found. Without this, a pinned lead
+     *       whose tab carries no matching label would be relaunched on every boot.</li>
+     * </ul>
+     * Member workspaces are excluded, exactly as the scanner excludes them: a member must not be
+     * counted as a lead because it happens to sit in a matching tab.
+     */
+    private Map<String, Integer> liveLeads(Map<String, BridgedConfig.Leader> leaders) {
+        Set<String> memberSpaces = cfg.profiles().values().stream()
+                .map(BridgedConfig.Profile::workspace)
+                .filter(w -> w != null && !w.isBlank())
+                .collect(Collectors.toSet());
+
+        // tabId → the lead name its label declares.
+        Map<String, String> nameByTab = new LinkedHashMap<>();
+        for (Workspace ws : spaces.listWorkspaces()) {
+            if (ws.workspaceId() == null || memberSpaces.contains(ws.label())) {
+                continue;
+            }
+            for (Tab tab : spaces.listTabs(ws.workspaceId())) {
+                String declared = leadNameOf(tab.label(), leaders);
+                if (declared != null && tab.tabId() != null) {
+                    nameByTab.put(tab.tabId(), declared);
+                }
+            }
+        }
+
+        // terminalId → the lead name the config pins it to.
+        Map<String, String> nameByPinnedTerminal = new LinkedHashMap<>();
+        leaders.forEach((name, lead) -> {
+            if (lead.terminal() != null && !lead.terminal().isBlank()) {
+                nameByPinnedTerminal.put(lead.terminal().strip(), name);
+            }
+        });
+
+        Map<String, Integer> counts = new LinkedHashMap<>();
+        for (Agent a : agents.list()) {
+            String name = nameByTab.get(a.tabId());
+            if (name == null) {
+                name = nameByPinnedTerminal.get(a.terminalId());
+            }
+            if (name != null) {
+                counts.merge(name, 1, Integer::sum);
+            }
+        }
+        return counts;
+    }
+
+    /**
+     * The configured lead a tab label names, or {@code null} for a label that names none.
+     *
+     * <p>Matched against the declared lead names rather than by splitting on the prefix, so an
+     * operator's {@code "lead: something-else"} tab is not mistaken for a configured lead.
+     */
+    private String leadNameOf(String label, Map<String, BridgedConfig.Leader> leaders) {
+        if (label == null) {
+            return null;
+        }
+        String l = label.strip();
+        for (Map.Entry<String, BridgedConfig.Leader> e : leaders.entrySet()) {
+            if (l.equalsIgnoreCase(e.getValue().tabLabel(e.getKey()).strip())) {
+                return e.getKey();
+            }
+        }
+        return null;
+    }
+
+    /** Start one lead. Returns false (having logged) rather than throwing on any failure. */
+    private boolean launch(String name, BridgedConfig.Leader lead, BridgedConfig.Profile profile) {
+        String label = lead.tabLabel(name);
+        String cwd = (lead.cwd() == null || lead.cwd().isBlank())
+                ? System.getProperty("user.dir") : lead.cwd();
+
+        Tab.Created tab = null;
+        try {
+            Workspace ws = spaces.ensureWorkspace(lead.workspace());
+            tab = spaces.createTab(ws.workspaceId(), cwd, leadEnv(profile));
+            if (tab.rootPaneId() == null) {
+                throw new IllegalStateException("tab " + tab.tab().tabId()
+                        + " came back with no seed pane — nowhere to start the lead");
+            }
+            // Same shape as the member launchers: herdr resolves the executable from `kind`, so
+            // argv[0] (the configured launcher, e.g. `ccs`) is dropped and only the rest is passed.
+            List<String> argv = leadArgv(profile);
+            Agent started = agents.start("lead-" + name, herdrKind(profile),
+                    argv.isEmpty() ? argv : argv.subList(1, argv.size()), tab.rootPaneId());
+
+            // Label AFTER the start succeeds. A label written before would survive a failed start
+            // and then read back as a live lead on the next boot, which is the exact staleness the
+            // agent-liveness check exists to prevent — no need to create the case ourselves.
+            spaces.renameTab(tab.tab().tabId(), label);
+
+            log.info("lead '{}' launched: profile={} tab={} pane={} terminal={} label='{}' cwd={}",
+                    name, profile.profile(), tab.tab().tabId(), started.paneId(),
+                    started.terminalId(), label, cwd);
+            return true;
+        } catch (RuntimeException e) {
+            log.warn("lead '{}' failed to launch on profile '{}': {}",
+                    name, profile.profile(), e.getMessage());
+            if (tab != null && tab.tab() != null && tab.tab().tabId() != null) {
+                try {
+                    spaces.closeTab(tab.tab().tabId());
+                } catch (RuntimeException cleanup) {
+                    log.warn("could not close the orphaned lead tab {}: {}",
+                            tab.tab().tabId(), cleanup.getMessage());
+                }
+            }
+            return false;
+        }
+    }
+
+    /**
+     * The herdr agent kind for this profile — the same value the matching member adapter passes, so
+     * herdr resolves the same executable for a lead as it does for a member on that backend.
+     */
+    private static String herdrKind(BridgedConfig.Profile profile) {
+        return profile.isOpenCode() ? "opencode" : "claude";
+    }
+
+    /**
+     * The lead's argv: the profile's own command, the model pin, and the bridge MCP mount.
+     *
+     * <p>No {@code --append-system-prompt}. That flag carries the worker reply charter, and a lead
+     * is not a worker — it reads its orchestration rules from the project's {@code CLAUDE.md} like
+     * any other primary. This is the single most important difference from the member launchers;
+     * do not "unify" it back.
+     */
+    private List<String> leadArgv(BridgedConfig.Profile profile) {
+        List<String> argv = new ArrayList<>(profile.argv());
+        if (profile.hasMcp()) {
+            argv.add("--mcp-config");
+            argv.add("{\"mcpServers\":{\"bridge\":{\"type\":\"http\",\"url\":\""
+                    + profile.mcpUrl() + "\"}}}");
+        }
+        // Appended last, for the same reason the member launcher does it (CB-533): the argv is
+        // usually a wrapper such as `ccs <profile>`, which exports its own model family over
+        // whatever it inherited, and --model outranks the environment.
+        if (profile.model() != null && !profile.model().isBlank()) {
+            argv.add("--model");
+            argv.add(profile.model());
+        }
+        return argv;
+    }
+
+    /**
+     * The lead's environment: the profile's {@code env:} block, and nothing that could move it off
+     * the subscription.
+     *
+     * <p>{@code ANTHROPIC_BASE_URL} and {@code ANTHROPIC_AUTH_TOKEN} are stripped unconditionally —
+     * not defaulted, not guarded, stripped. A lead runs on the operator's subscription by
+     * definition, so there is no configuration under which pointing it elsewhere is correct, and a
+     * profile that carries them (a member profile reused as a lead's backend) must not leak them in.
+     */
+    private Map<String, String> leadEnv(BridgedConfig.Profile profile) {
+        Map<String, String> out = new LinkedHashMap<>();
+        if (profile.env() != null) {
+            out.putAll(profile.env());
+        }
+        out.remove("ANTHROPIC_BASE_URL");
+        out.remove("ANTHROPIC_AUTH_TOKEN");
+        if (profile.configDir() != null && !profile.configDir().isBlank()) {
+            out.put("CLAUDE_CONFIG_DIR", profile.configDir());
+        }
+        // Deliberately no git token: a lead reviews and merges through the operator's own
+        // credentials, and never needs the scoped write:repository token a member is granted.
+        out.values().removeIf(Objects::isNull);
+        return out;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/mcp/BridgeMcp.java

@@ -0,0 +1,963 @@
+package dev.ltms.bridged.mcp;
+
+import dev.ltms.bridged.auth.AuditLog;
+import dev.ltms.bridged.auth.Authz;
+import dev.ltms.bridged.auth.CallerResolver;
+import dev.ltms.bridged.auth.Principal;
+import dev.ltms.bridged.auth.Role;
+import dev.ltms.bridged.guard.GuardException;
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.metrics.BridgedMetrics;
+import dev.ltms.bridged.metrics.Metrics;
+import dev.ltms.bridged.inject.MemberPresence;
+import dev.ltms.bridged.herdr.HerdrException;
+import dev.ltms.bridged.msg.MessageService;
+import dev.ltms.bridged.msg.Rendezvous;
+import dev.ltms.bridged.peer.PeerUnreachableException;
+import dev.ltms.bridged.session.SessionManager;
+import dev.ltms.bridged.session.MemberSession;
+import dev.ltms.bridged.session.WorktreeRequest;
+import dev.ltms.bridged.peer.MemberRole;
+import dev.ltms.bridged.peer.PeerLauncher;
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.jackson3.JacksonMcpJsonMapperSupplier;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpSchema;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.servlet.http.HttpServlet;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+/**
+ * The MCP SERVER face (CB-105): a Streamable-HTTP MCP server whose tools are <em>thin adapters</em>
+ * over the same {@link MessageService}/{@link Rendezvous} the REST routes use — so the two are
+ * validated by parity, not by re-implementing behaviour. The primary Opus calls {@code bridge_send}
+ * / {@code bridge_status}; the worker calls {@code bridge_reply}.
+ *
+ * <p>Beyond delegation the primary also manages the fleet here (CB-108): {@code bridge_spawn} /
+ * {@code bridge_list} / {@code bridge_stop} drive the {@link PeerLauncher} SPI so a worker's whole
+ * lifecycle is managed through MCP, with each adapter's subscription boundary enforced inside it.
+ *
+ * <p>The tool <em>logic</em> lives in package-private static methods returning a
+ * {@link McpSchema.CallToolResult}, so it is unit-testable without standing up the HTTP transport;
+ * the SDK owns the wire protocol. Mount {@link #servlet()} at {@code /mcp} on the daemon's Jetty.
+ */
+public final class BridgeMcp {
+
+    private static final long DEFAULT_TIMEOUT_MS = 25_000;
+    private static final long MAX_TIMEOUT_MS = 120_000;
+    // bridge_ask blocks the WORKER's own MCP call, which its client caps near 60s — default under
+    // that so the bridge returns a clean timeout before the client severs the call (CB-205).
+    private static final long ASK_DEFAULT_TIMEOUT_MS = 55_000;
+    private static final long ASK_MAX_TIMEOUT_MS = 115_000;
+    private static final ObjectMapper MAPPER = new ObjectMapper(); // worker-view JSON projections
+
+    /** Transport-context key under which the extractor stashes the resolved caller identity. */
+    static final String CALLER_TERMINAL = "callerTerminal";
+    /** Transport-context key under which the extractor stashes the caller's PID (for cwd inherit). */
+    static final String CALLER_PID = "callerPid";
+    /** Transport-context key under which the extractor stashes the resolved {@link Role} (CB-501). */
+    static final String CALLER_ROLE = "callerRole";
+    /** Transport-context key for the lead's configured name, when the caller is one (CB-530). */
+    static final String CALLER_NAME = "callerName";
+
+    private final HttpServletStreamableServerTransportProvider transport;
+    private final McpSyncServer server;
+    private final CallerResolver authz; // CB-501: null → authorization not enforced (legacy)
+    private final Metrics metrics;      // CB-502: null → auth failures not counted
+
+    /**
+     * Legacy constructor — no authorization. Retained so existing tests exercise tool behaviour
+     * without an auth fixture.
+     */
+    public BridgeMcp(MessageService messages, PeerLauncher workers,
+                     SessionManager sessions, ConnectionIdentity identity, MemberPresence presence,
+                     PrimaryRegistry primaryRegistry) {
+        this(messages, workers, sessions, identity, presence, primaryRegistry, null, null);
+    }
+
+    /**
+     * @param callers resolves each call's {@link Principal}; {@code null} disables authorization.
+     *                This surface needs its own enforcement: {@code /mcp} is a raw servlet on
+     *                Jetty's context handler and never passes through Javalin's {@code before}
+     *                filter, so the REST guard does not cover it.
+     * @param metrics registry for auth-failure counting; may be {@code null}
+     */
+    public BridgeMcp(MessageService messages, PeerLauncher workers,
+                     SessionManager sessions, ConnectionIdentity identity, MemberPresence presence,
+                     PrimaryRegistry primaryRegistry, CallerResolver callers, Metrics metrics) {
+        McpJsonMapper json = new JacksonMcpJsonMapperSupplier().get();
+        this.transport = HttpServletStreamableServerTransportProvider.builder()
+                .jsonMapper(json)
+                .mcpEndpoint("/mcp")
+                // Resolve the caller from the connection (peer PID → herdr pane) in one lookup: the
+                // worker terminal for bridge_reply (no spoofable arg), and the PID so bridge_spawn can
+                // inherit the primary's cwd (CB-112). Any contact from a worker marks it available
+                // (CB-113) — its MCP initialize is the reliable "the agent is up" signal.
+                .contextExtractor(req -> {
+                    // One resolution per call, shared with the REST surface via CallerResolver so
+                    // the two paths cannot drift on who a caller is.
+                    Principal p = callers != null
+                            ? callers.resolve(req.getRemoteAddr(), req.getRemotePort(),
+                                    req.getHeader("Authorization"))
+                            : legacyPrincipal(identity, req.getRemoteAddr(), req.getRemotePort());
+                    // CB-532: guard on the ROLE, not on the terminal being null. A named lead now
+                    // carries its pane too, and enrolling a lead in the worker presence map would
+                    // have it counted as an available worker.
+                    if (p.isWorker()) presence.markPresent(p.terminal());
+                    return McpTransportContext.create(Map.of(
+                            CALLER_TERMINAL, orEmpty(p.terminal()),
+                            CALLER_PID, Long.toString(p.pid()),
+                            CALLER_ROLE, p.role().name(),
+                            CALLER_NAME, orEmpty(p.name())));
+                })
+                .build();
+        this.server = McpServer.sync(transport)
+                .serverInfo("bridge", "0.1.0")
+                .capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+                .toolCall(sendTool(), (exchange, req) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.SEND,
+                            str(req.arguments(), "sessionId"));
+                    if (denied != null) return denied;
+                    String caller = callerTerminal(exchange);
+                    // CB-548: only a PRIMARY caller may claim the legacy singleton "primary" fallback.
+                    // An architect delegates as its own pane but must never become the fallback that
+                    // no-delegation inbox nudges target as if it were the primary (the per-target
+                    // delegation map does not cure the singleton).
+                    recordPrimarySingleton(primaryRegistry, caller, principal(exchange));
+                    Map<String, Object> a = req.arguments();
+                    String target = str(a, "sessionId");
+                    String content = str(a, "content");
+                    String turnId = str(a, "turnId");
+                    if (turnId != null && !turnId.isBlank()) {
+                        // Answering a worker's bridge_ask (CB-205): resolve its blocked question and
+                        // block for the worker's reply as it resumes the same turn. This is the same
+                        // delegation, so ownership is left untouched (CB-548) — never re-recorded.
+                        return answer(messages, turnId, content, timeoutMs(a));
+                    }
+                    // CB-548: delegator ownership (which lead's reply nudge this worker routes to,
+                    // CB-532) is recorded only once the send is ACCEPTED — MessageService has won the
+                    // session lock and queued delivery — via the accepted-delivery callback, never at
+                    // request time. A concurrent sender that times out BUSY therefore cannot steal a
+                    // live turn's reply routing without ever owning the turn.
+                    Runnable onAccepted = () -> primaryRegistry.recordDelegation(target, caller);
+                    // wait defaults to true (block for the reply); wait:false is fire-and-poll.
+                    return Boolean.FALSE.equals(a.get("wait"))
+                            ? sendAsync(messages, target, content, onAccepted)
+                            : send(messages, target, content, timeoutMs(a), onAccepted);
+                })
+                // bridge_reply's identity is the CONNECTION, never an argument — so the authz check
+                // is "is this caller a worker at all", and it can only ever reply as itself.
+                .toolCall(replyTool(), (exchange, req) -> {
+                    String self = callerTerminal(exchange);
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.REPLY, self);
+                    if (denied != null) return denied;
+                    return reply(messages, self, str(req.arguments(), "content"));
+                })
+                // bridge_ask (CB-205): a worker's mid-turn question — identity from the CONNECTION.
+                .toolCall(askTool(), (exchange, req) -> {
+                    String self = callerTerminal(exchange);
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.ASK, self);
+                    if (denied != null) return denied;
+                    return ask(messages, self, str(req.arguments(), "question"), timeoutMs(req.arguments()));
+                })
+                .toolCall(statusTool(), (exchange, req) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    if (denied != null) return denied;
+                    return status(messages, str(req.arguments(), "sessionId"));
+                })
+                .toolCall(pollTool(), (exchange, req) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    if (denied != null) return denied;
+                    Map<String, Object> a = req.arguments();
+                    return poll(messages, str(a, "ticket"), str(a, "target"));
+                })
+                // CB-307 Increment 3: per-msgId ack (not needed in v1 but supported by the inbox).
+                // Acking removes a reply from the inbox, so it is a drain, not a read.
+                .toolCall(ackTool(), (exchange, req) -> {
+                    Map<String, Object> a = req.arguments();
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.DRAIN, str(a, "target"));
+                    if (denied != null) return denied;
+                    return ack(messages, str(a, "target"), str(a, "msgId"));
+                })
+                // Fleet management (CB-108): spawn/list/stop over ClaudeCodeLauncher.
+                .toolCall(spawnTool(), (exchange, req) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.SPAWN, null);
+                    if (denied != null) return denied;
+                    String caller = callerTerminal(exchange);
+                    // SPAWN is already auth-gated to PRIMARY (architects can never call it), but
+                    // enforce the same invariant here: only a PRIMARY may claim the legacy singleton.
+                    recordPrimarySingleton(primaryRegistry, caller, principal(exchange));
+                    Map<String, Object> a = req.arguments();
+                    // CB-112: worker inherits the primary's cwd unless the call pins one.
+                    // CB-301: carry the caller's identity as the session owner (null for the primary).
+                    // CB-301-ext: optional isolated worktree for parallel implementers.
+                    String callerCwd = identity.cwdForPid(callerPid(exchange));
+                    return spawn(sessions, str(a, "profile"), str(a, "role"), str(a, "cwd"), callerCwd,
+                            callerTerminal(exchange), worktreeRequest(a));
+                })
+                .toolCall(listTool(), (exchange, _) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    if (denied != null) return denied;
+                    return listFleet(workers, sessions,
+                            callers == null ? Map.of() : callers.leads(),
+                            callerTerminal(exchange));
+                })
+                .toolCall(stopTool(), (exchange, req) -> {
+                    String paneId = str(req.arguments(), "paneId");
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.STOP, paneId);
+                    if (denied != null) return denied;
+                    return stop(sessions, paneId);
+                })
+                .toolCall(profilesTool(), (exchange, _) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    if (denied != null) return denied;
+                    return profiles(workers);
+                })
+                .toolCall(whoamiTool(), (exchange, _) -> {
+                    McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
+                    if (denied != null) return denied;
+                    return whoami(principal(exchange), sessions);
+                })
+                .build();
+        this.authz = callers;
+        this.metrics = metrics;
+    }
+
+    /**
+     * Pre-CB-501 identity: worker if the connection maps to a pane, otherwise the primary. Used
+     * only by the legacy constructor, where authorization is not enforced anyway.
+     */
+    private static Principal legacyPrincipal(ConnectionIdentity identity, String addr, int port) {
+        ConnectionIdentity.Caller c = identity.resolve(addr, port);
+        return c.terminal() != null
+                ? Principal.worker(c.terminal(), c.pid())
+                : Principal.primary(c.pid());
+    }
+
+    /** The caller reconstructed from the transport context. */
+    private static Principal principal(McpSyncServerExchange exchange) {
+        return principalFrom(exchange.transportContext().get(CALLER_ROLE),
+                callerTerminal(exchange), callerPid(exchange), callerName(exchange));
+    }
+
+    /**
+     * Rebuild a {@link Principal} from the three values the context extractor stashed.
+     *
+     * <p>Split out from {@link #principal(McpSyncServerExchange)} so the identity rules are
+     * reachable without an {@code McpSyncServerExchange} — that is an SDK type this project has no
+     * mocking library to fabricate, which is why this logic had no test at all until CB-513.
+     *
+     * @param role     the stashed {@link Role} name, or {@code null} on the legacy path
+     * @param terminal the worker terminal, or {@code null} for a non-worker
+     * @param pid      the calling pid, or {@code -1}
+     */
+    static Principal principalFrom(Object role, String terminal, long pid) {
+        return principalFrom(role, terminal, pid, null);
+    }
+
+    /** As {@link #principalFrom(Object, String, long)}, carrying a lead's name (CB-530). */
+    static Principal principalFrom(Object role, String terminal, long pid, String name) {
+        if (role == null) {
+            // No role stashed (legacy path): fall back to the historical interpretation.
+            return terminal != null ? Principal.worker(terminal, pid) : Principal.primary(pid);
+        }
+        return new Principal(Role.valueOf(role.toString()), terminal, pid, name);
+    }
+
+    /**
+     * Gate a tool call on the CB-505 table. Returns {@code null} when the call may proceed, or the
+     * error result to return when it may not.
+     */
+    private McpSchema.CallToolResult deny(McpSyncServerExchange exchange, Authz.Action action,
+                                          String target) {
+        return denyFor(principal(exchange), action, target);
+    }
+
+    /**
+     * The policy half of {@link #deny}: everything except pulling the caller out of the MCP
+     * exchange. Kept separate so the authorization decision — the actual control — is unit-testable
+     * without fabricating an SDK {@code McpSyncServerExchange}.
+     *
+     * <p>This surface exists because the enforcement was previously unreachable from a test: no
+     * test constructs a {@code BridgeMcp}, so the whole MCP-side gate ran zero times in the suite
+     * while the REST-side equivalent had ten tests. A security control nothing exercises is a
+     * claim, not a control.
+     *
+     * @return {@code null} when the call may proceed, or the error result to return when it may not
+     */
+    McpSchema.CallToolResult denyFor(Principal caller, Authz.Action action, String target) {
+        // The enforcement switch lives HERE rather than in the exchange-facing wrapper: any future
+        // tool that calls this directly must not be able to skip the gate by accident.
+        if (authz == null) {
+            return null; // legacy constructor: authorization not enforced
+        }
+        if (Authz.permits(caller, action, target)) {
+            if (action != Authz.Action.READ) {
+                AuditLog.allowed(caller, action, target); // reads would drown the trail
+            }
+            return null;
+        }
+        String reason = Authz.isUnauthenticated(caller) ? "unauthenticated" : "forbidden";
+        AuditLog.denied(caller, action, target, reason);
+        if (metrics != null) {
+            metrics.inc(BridgedMetrics.AUTH_FAILURES, "reason", reason);
+        }
+        return error(reason + ": " + caller.describe() + " may not " + action);
+    }
+
+    /**
+     * Update the legacy singleton "primary" fallback used for no-delegation inbox nudges (CB-548).
+     *
+     * <p>Only {@link Role#PRIMARY} callers — the unnamed primary and named leads alike — may claim
+     * it. An architect delegates as its own pane but must never become the fallback: the per-target
+     * delegation map ({@code PrimaryRegistry#recordDelegation}) does not cure the singleton, so an
+     * architect left here would draw nudges that belong to a primary. The decision uses the resolved
+     * role, never name/kind sniffing. A null {@code caller} (legacy/no-auth path) records nothing.
+     *
+     * <p>Split out of the tool handlers so the guard is unit-testable without fabricating an SDK
+     * {@code McpSyncServerExchange} (same pattern as {@link #denyFor}/{@link #principalFrom}).
+     */
+    static void recordPrimarySingleton(PrimaryRegistry registry, String callerTerminal, Principal caller) {
+        if (caller != null && caller.isPrimary()) {
+            registry.record(callerTerminal);
+        }
+    }
+
+    /** The worker identity resolved from this call's connection, or {@code null} if the primary. */
+    private static String callerTerminal(McpSyncServerExchange exchange) {
+        Object v = exchange.transportContext().get(CALLER_TERMINAL);
+        String s = v == null ? null : v.toString();
+        return (s == null || s.isBlank()) ? null : s;
+    }
+
+    /** The lead name resolved from this call's connection, or {@code null} (CB-530). */
+    private static String callerName(McpSyncServerExchange exchange) {
+        Object v = exchange.transportContext().get(CALLER_NAME);
+        String s = v == null ? null : v.toString();
+        return (s == null || s.isBlank()) ? null : s;
+    }
+
+    /** The caller's PID resolved from this call's connection, or {@code -1} if unknown. */
+    private static long callerPid(McpSyncServerExchange exchange) {
+        Object v = exchange.transportContext().get(CALLER_PID);
+        try {
+            return v == null ? -1 : Long.parseLong(v.toString());
+        } catch (NumberFormatException e) {
+            return -1;
+        }
+    }
+
+    private static String orEmpty(String s) {
+        return s == null ? "" : s;
+    }
+
+    /** The Streamable-HTTP servlet to mount at {@code /mcp} on the daemon's Jetty. */
+    public HttpServlet servlet() {
+        return transport;
+    }
+
+    /** Graceful shutdown of the MCP server. */
+    public void close() {
+        server.closeGracefully();
+    }
+
+    // --- tool logic (thin adapters over the services; unit-testable) ---------------------------
+
+    /** {@code bridge_send}: delegate {@code content} to a worker session and block for its reply. */
+    static McpSchema.CallToolResult send(MessageService messages, String sessionId, String content, Long timeoutMs) {
+        return send(messages, sessionId, content, timeoutMs, null);
+    }
+
+    /**
+     * As {@link #send(MessageService, String, String, Long)}, wiring an accepted-delivery hook
+     * (CB-548): {@code onAccepted} records delegator ownership the instant the send is accepted, so
+     * a BUSY interloper never claims a turn it did not win. {@code null} disables recording.
+     */
+    static McpSchema.CallToolResult send(MessageService messages, String sessionId, String content,
+                                         Long timeoutMs, Runnable onAccepted) {
+        if (isBlank(sessionId) || isBlank(content)) {
+            return error("sessionId and content are required");
+        }
+        long timeout = clamp(timeoutMs == null ? DEFAULT_TIMEOUT_MS : timeoutMs);
+        try {
+            return formatReply(messages.send(sessionId, content, timeout, onAccepted), timeout);
+        } catch (HerdrException e) {
+            return error("herdr error contacting session " + sessionId + ": " + e.getMessage());
+        }
+    }
+
+    /**
+     * {@code bridge_send} carrying a {@code turnId}: the primary's answer to a worker's
+     * {@code bridge_ask} (CB-205). Resolves the worker's blocked question and blocks for its reply as
+     * it resumes the same turn — surfaced to the primary identically to a normal send.
+     */
+    static McpSchema.CallToolResult answer(MessageService messages, String turnId, String content, Long timeoutMs) {
+        if (isBlank(turnId) || isBlank(content)) {
+            return error("turnId and content are required to answer a worker's question");
+        }
+        long timeout = clamp(timeoutMs == null ? DEFAULT_TIMEOUT_MS : timeoutMs);
+        return formatReply(messages.answer(turnId, content, timeout), timeout);
+    }
+
+    /**
+     * {@code bridge_ask} (CB-205): a worker pauses its delegated turn to ask the primary, blocking
+     * until the primary answers. The worker is identified by its connection ({@code callerTerminal}),
+     * never an argument — a {@code null} means the caller is not a known worker.
+     */
+    static McpSchema.CallToolResult ask(MessageService messages, String callerTerminal, String question, Long timeoutMs) {
+        if (callerTerminal == null) {
+            return error("bridge_ask is for workers only — could not identify the calling worker "
+                    + "from the connection");
+        }
+        if (isBlank(question)) {
+            return error("question is required");
+        }
+        long timeout = Math.clamp(timeoutMs == null ? ASK_DEFAULT_TIMEOUT_MS : timeoutMs, 1, ASK_MAX_TIMEOUT_MS);
+        MessageService.AskResult r = messages.ask(callerTerminal, question, timeout);
+        return switch (r.outcome()) {
+            case ANSWERED -> text(r.answer());
+            case NO_WAITER -> error("no primary is awaiting this turn — bridge_ask only works while a "
+                    + "bridge_send delegation is open to answer it");
+            case TIMED_OUT -> text("[no answer within " + timeout + "ms — the primary did not respond; "
+                    + "proceed on your best judgement, then call bridge_reply to end the turn]");
+        };
+    }
+
+    /** Render a {@link MessageService.Reply} as a tool result — shared by {@link #send} and {@link #answer}. */
+    private static McpSchema.CallToolResult formatReply(MessageService.Reply r, long timeout) {
+        return switch (r.outcome()) {
+            case REPLIED -> text(r.text());
+            // The worker's turn finished but it never called bridge_reply — hand back the scraped
+            // transcript tail, flagged so the primary knows it isn't a structured reply.
+            case COMPLETED_UNREPLIED -> text(
+                    "[worker finished without a structured bridge_reply — transcript tail follows]\n" + r.text());
+            // The worker ran the turn then wedged (CB-109) — surface the error context.
+            case WORKER_FAILED -> text("[worker failed — turn ended in an unrecoverable state]\n" + r.text());
+            // The worker paused mid-turn to ask (CB-205) — tell the primary how to answer in-turn.
+            case QUESTION -> text("[question] the worker paused to ask before it can finish:\n" + r.text()
+                    + "\n\nAnswer it by calling bridge_send again with turnId=\"" + r.turnId()
+                    + "\" and content set to your answer; the worker resumes the same turn.");
+            case STALE_TURN -> error("that question is no longer open — it timed out or was already "
+                    + "answered (turnId stale)");
+            case TIMED_OUT_WORKING, TIMED_OUT_QUEUED, BUSY -> text("[no reply within " + timeout + "ms — worker "
+                    + r.outcome().name().toLowerCase().replace("timed_out_", "") + "; retry or poll status]");
+        };
+    }
+
+    /**
+     * {@code bridge_send} with {@code wait:false}: delegate {@code content} and return a ticket
+     * immediately (fire-and-poll), so a long task isn't cut off by the caller's MCP call timeout.
+     */
+    static McpSchema.CallToolResult sendAsync(MessageService messages, String sessionId, String content) {
+        return sendAsync(messages, sessionId, content, null);
+    }
+
+    /**
+     * As {@link #sendAsync(MessageService, String, String)}, wiring the accepted-delivery hook
+     * (CB-548) so an async flooding send records delegator ownership exactly once it is accepted.
+     */
+    static McpSchema.CallToolResult sendAsync(MessageService messages, String sessionId, String content,
+                                              Runnable onAccepted) {
+        if (isBlank(sessionId) || isBlank(content)) {
+            return error("sessionId and content are required");
+        }
+        String ticket = messages.sendAsync(sessionId, content, onAccepted);
+        return text("accepted — task delegated. Poll bridge_poll with ticket=" + ticket);
+    }
+
+    /** {@code bridge_poll}: check an async delegation by ticket, or drain a worker's inbox by target. */
+    static McpSchema.CallToolResult poll(MessageService messages, String ticket, String target) {
+        if (!isBlank(target)) {
+            var replies = messages.drainReplies(target);
+            if (replies.isEmpty()) {
+                return text("[]");
+            }
+            return text(json(replies));
+        }
+        if (isBlank(ticket)) {
+            return error("ticket (or target) is required");
+        }
+        MessageService.TaskView v = messages.poll(ticket);
+        if (v == null) {
+            return error("unknown ticket: " + ticket + " (never issued, or expired)");
+        }
+        return switch (v.phase()) {
+            case DONE -> text(v.replySource() != null && v.replySource().equals("transcript")
+                    ? "[done — worker finished without a structured bridge_reply; transcript tail follows]\n" + v.reply()
+                    : v.reply());
+            case PENDING -> text("[pending — " + v.detail() + "]");
+            case FAILED -> text("[failed — " + v.detail() + "]");
+        };
+    }
+
+    /**
+     * {@code bridge_reply}: the worker returns its structured answer, resolving the awaiting send
+     * or — when no send is open — queueing the reply in the inbox for later drain (CB-307).
+     * {@code callerTerminal} is resolved from the connection (never an argument); a {@code null}
+     * means the caller is not a known worker (e.g. the primary called it by mistake).
+     */
+    static McpSchema.CallToolResult reply(MessageService messages, String callerTerminal, String content) {
+        if (callerTerminal == null) {
+            return error("bridge_reply is for workers only — could not identify the calling worker "
+                    + "from the connection");
+        }
+        if (content == null) {
+            return error("content is required");
+        }
+        messages.reply(callerTerminal, content);
+        return text("delivered");
+    }
+
+    /** {@code bridge_ack}: acknowledge (remove) a specific reply from the inbox. */
+    static McpSchema.CallToolResult ack(MessageService messages, String target, String msgId) {
+        if (isBlank(target) || isBlank(msgId)) {
+            return error("target and msgId are required");
+        }
+        messages.ackReply(target, msgId);
+        return text("acknowledged " + msgId);
+    }
+
+    /** {@code bridge_status}: the live lifecycle status of a worker session. */
+    static McpSchema.CallToolResult status(MessageService messages, String sessionId) {
+        if (isBlank(sessionId)) {
+            return error("sessionId is required");
+        }
+        try {
+            return text(messages.status(sessionId).name().toLowerCase());
+        } catch (HerdrException e) {
+            return error("herdr error for session " + sessionId + ": " + e.getMessage());
+        }
+    }
+
+    /**
+     * {@code bridge_whoami}: the caller's own identity, as the daemon already resolved it.
+     *
+     * <p>Every other tool <em>consumes</em> this identity — the authorization gate, the reply
+     * rendezvous, the cwd inherit — but none reported it, so an agent had to infer its own role
+     * from side channels the daemon does not control: a charter string in its system prompt, the
+     * name its MCP mount happens to carry, or {@code ANTHROPIC_BASE_URL} (which Claude-model
+     * workers do not set). The failure mode of guessing is asymmetric and silent: a primary that
+     * mistakes itself for a worker is refused by {@link Authz} and learns immediately, while a
+     * worker that mistakes itself for the primary ends its turn without {@code bridge_reply} and
+     * the sender simply receives nothing. This tool removes the guess.
+     *
+     * <p>For a worker the session registry adds what it knows about that session. A worker the
+     * registry has no record of — one that outlived a daemon restart — still gets its role and
+     * {@code sessionId}, which is the load-bearing part.
+     */
+    static McpSchema.CallToolResult whoami(Principal caller, SessionManager sessions) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("role", caller.role().name().toLowerCase());
+        if (caller.isArchitect()) {
+            // CB-548: the role reads "architect"; the name is the gateway-local slot the pane is
+            // bound to, and the pane itself so a peer knows where to reach it.
+            if (caller.name() != null) {
+                m.put("architect", caller.name());
+            }
+            if (caller.terminal() != null) {
+                m.put("sessionId", caller.terminal());
+            }
+            return text(json(m));
+        }
+        if (!caller.isWorker()) {
+            // CB-530: which lead, once more than one pane is configured as one. `role` deliberately
+            // still reads "primary" — the fallback ladder in CLAUDE.md keys on it, and a lead IS a
+            // primary for authorization; the name is additive so no existing reader breaks.
+            if (caller.name() != null) {
+                m.put("leader", caller.name());
+            }
+            // CB-532: a lead's own pane, so it can tell a peer where to reach it — and so an
+            // operator can read off which tab hosts which lead without going to herdr.
+            if (caller.terminal() != null) {
+                m.put("sessionId", caller.terminal());
+            }
+            return text(json(m));
+        }
+        m.put("sessionId", caller.terminal());
+        sessions.roster().stream()
+                .filter(s -> caller.terminal().equals(s.terminalId()))
+                .findFirst()
+                .ifPresent(s -> {
+                    m.put("paneId", s.paneId());
+                    m.put("profile", s.profile());
+                    m.put("state", s.state().name().toLowerCase());
+                    if (s.worktree() != null) {
+                        m.put("worktree", s.worktree());
+                    }
+                    if (s.branch() != null) {
+                        m.put("branch", s.branch());
+                    }
+                    if (s.ownerTerminal() != null) {
+                        m.put("owner", s.ownerTerminal());
+                    }
+                });
+        return text(json(m));
+    }
+
+    // --- fleet management logic (CB-108 / CB-301) --------------------------------------------
+
+    /** {@code bridge_spawn} without cwd/caller context (default resolution). */
+    static McpSchema.CallToolResult spawn(SessionManager sessions, String profile) {
+        return spawn(sessions, profile, null, null, null, null, null);
+    }
+
+    /**
+     * {@code bridge_spawn}: launch a guard-checked member for {@code profile} (blank → the default
+     * profile) under {@code role} (blank → {@code dev}), and return its session id + pane id. The
+     * member's cwd is {@code requestedCwd} if given, else the profile's config, else
+     * {@code callerCwd} (the primary's directory), else the daemon's.
+     * CB-301: the session is registered with {@code ownerTerminal} as its owner.
+     * CB-301-ext: {@code worktreeRequest} non-null provisions an isolated git worktree.
+     *
+     * <p>{@code role} and {@code profile} are independent: the role picks the contract, the profile
+     * picks the backend. A reviewer on the same profile as the dev it reviews is a normal spawn.
+     */
+    static McpSchema.CallToolResult spawn(SessionManager sessions, String profile, String role,
+                                          String requestedCwd, String callerCwd,
+                                          String ownerTerminal, WorktreeRequest worktreeRequest) {
+        MemberRole memberRole;
+        try {
+            memberRole = isBlank(role) ? MemberRole.DEV : MemberRole.parse(role);
+        } catch (IllegalArgumentException e) {
+            return error(e.getMessage());
+        }
+        try {
+            MemberSession member = sessions.acquire(isBlank(profile) ? null : profile, memberRole,
+                    requestedCwd, callerCwd, ownerTerminal, worktreeRequest);
+            return text(json(memberView(member)));
+        } catch (GuardException e) {
+            return error("subscription boundary: " + e.getMessage());
+        } catch (IllegalArgumentException e) {
+            return error(e.getMessage()); // unknown / no-default profile
+        } catch (PeerUnreachableException e) {
+            return error("spawn timed out — worker pane never reached injectable state: " + e.getMessage());
+        } catch (HerdrException e) {
+            return error("herdr error spawning worker: " + e.getMessage());
+        }
+    }
+
+    /** Build a {@link WorktreeRequest} from {@code bridge_spawn}'s optional {@code worktree}/{@code ticket} args. */
+    private static WorktreeRequest worktreeRequest(Map<String, Object> a) {
+        Object w = a.get("worktree");
+        if (w == null || Boolean.FALSE.equals(w)) {
+            return null;
+        }
+        String ticket = str(a, "ticket");
+        if (w instanceof String s) {
+            if (s.isBlank() || "false".equalsIgnoreCase(s)) {
+                return null;
+            }
+            if ("true".equalsIgnoreCase(s)) {
+                if (isBlank(ticket)) {
+                    throw new IllegalArgumentException("worktree=true requires a ticket slug");
+                }
+                return new WorktreeRequest(ticket, null);
+            }
+            return new WorktreeRequest(s, null);
+        }
+        if (w instanceof Boolean b && b) {
+            if (isBlank(ticket)) {
+                throw new IllegalArgumentException("worktree=true requires a ticket slug");
+            }
+            return new WorktreeRequest(ticket, null);
+        }
+        return null;
+    }
+
+    /** {@code bridge_profiles}: the configured worker profiles and the default. */
+    static McpSchema.CallToolResult profiles(PeerLauncher workers) {
+        return text(json(Map.of(
+                "profiles", workers.profiles(),
+                "default", workers.defaultProfile() == null ? "" : workers.defaultProfile())));
+    }
+
+    /**
+     * {@code bridge_list}: the whole fleet — {@code leads} and {@code workers} — each merged with
+     * live herdr status. CB-519 decoupled the registry key (a host-unique id) from the herdr pane
+     * coordinate, so the join is on the terminal id, which both the session and the live agent carry.
+     *
+     * <p>CB-535 added the {@code leads} half. Until then this listed the worker roster alone, and a
+     * lead asking "who else is here?" got an empty array — which reads as <em>no peers</em> but
+     * actually means <em>no workers spawned</em>. There was no way at all for a lead to learn a
+     * peer's address; it had to be carried across by a human. Both halves are reported even when a
+     * half is empty, so an empty {@code workers} can no longer be mistaken for an empty fleet.
+     *
+     * <p>Leads are drawn from the resolver rather than from a second registry, so an address listed
+     * here is one that would actually resolve as a lead — see {@link CallerResolver#leads()}. The
+     * caller's own row is flagged {@code "self": true}: a peer needs to tell its own pane apart from
+     * a peer's, and the alternative is every lead calling {@code bridge_whoami} to subtract itself.
+     *
+     * @param leads    terminal_id → lead name, live from the resolver
+     * @param selfTerm the calling pane's terminal id, or blank for a caller with no pane
+     */
+    static McpSchema.CallToolResult listFleet(PeerLauncher workers, SessionManager sessions,
+                                              Map<String, String> leads, String selfTerm) {
+        try {
+            Map<String, Agent> live = workers.list().stream()
+                    .map(Agent.class::cast)
+                    .filter(a -> a.terminalId() != null)
+                    .collect(Collectors.toMap(Agent::terminalId, Function.identity(), (_, b) -> b));
+            List<Map<String, Object>> leadRows = leads.entrySet().stream()
+                    .sorted(Map.Entry.comparingByValue())
+                    .map(e -> leadView(e.getKey(), e.getValue(), live.get(e.getKey()), selfTerm))
+                    .toList();
+            List<Map<String, Object>> out = sessions.roster().stream()
+                    .map(s -> SessionManager.rosterView(s, live.get(s.terminalId())))
+                    .toList();
+            return text(json(Map.of("leads", leadRows, "members", out)));
+        } catch (HerdrException e) {
+            return error("herdr error listing the fleet: " + e.getMessage());
+        }
+    }
+
+    /**
+     * One lead's row: its address, its name, and whether it can be reached right now.
+     *
+     * <p>{@code status} is herdr's live view, and {@code unknown} when herdr is not tracking that
+     * pane as an agent — the honest answer, and the one that matters: a lead whose pane herdr cannot
+     * see is a lead a {@code bridge_send} cannot be typed into. It is reported rather than hidden,
+     * because a peer that has gone unreachable is exactly what the sender needs to know.
+     */
+    private static Map<String, Object> leadView(String terminal, String name, Agent live,
+                                                String selfTerm) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("sessionId", terminal);
+        m.put("name", name);
+        m.put("status", live == null || live.status() == null
+                ? "unknown" : live.status().name().toLowerCase());
+        if (terminal.equals(selfTerm)) {
+            m.put("self", true);
+        }
+        return m;
+    }
+
+    /** {@code bridge_stop}: tear a worker down by its pane id. */
+    static McpSchema.CallToolResult stop(SessionManager sessions, String paneId) {
+        if (isBlank(paneId)) {
+            return error("paneId is required");
+        }
+        try {
+            sessions.release(paneId);
+            return text("stopped " + paneId);
+        } catch (HerdrException e) {
+            return error("herdr error stopping " + paneId + ": " + e.getMessage());
+        }
+    }
+
+    /** CB-301 projection from the authoritative session registry. */
+    private static Map<String, Object> memberView(MemberSession s) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("sessionId", s.terminalId());
+        m.put("paneId", s.paneId());
+        // Echo the role back so the caller can see what it actually got, not what it meant to ask
+        // for — a spawn that silently fell back to dev is otherwise invisible.
+        m.put("role", s.role() == null ? "dev" : s.role().wireName());
+        m.put("profile", s.profile());
+        m.put("status", s.state().name().toLowerCase());
+        if (s.worktree() != null) {
+            m.put("worktree", s.worktree());
+        }
+        if (s.branch() != null) {
+            m.put("branch", s.branch());
+        }
+        return m;
+    }
+
+    private static String json(Object o) {
+        try {
+            return MAPPER.writeValueAsString(o);
+        } catch (Exception e) {
+            return String.valueOf(o);
+        }
+    }
+
+    // --- tool schemas --------------------------------------------------------------------------
+
+    private static McpSchema.Tool sendTool() {
+        return tool("bridge_send",
+                "Delegate a task to a worker session. By default blocks until the worker replies and "
+                        + "returns its reply (or a 'still working / queued' note on timeout). Pass wait:false "
+                        + "for a long task to return a ticket immediately, then poll it with bridge_poll. To "
+                        + "answer a worker's bridge_ask, pass its turnId (with content) instead of sessionId.",
+                objectSchema(Map.of(
+                        "sessionId", stringProp("The worker session id (herdr terminal_id) to delegate to"),
+                        "content", stringProp("The task/message to send to the worker (or your answer, with turnId)"),
+                        "timeoutMs", Map.of("type", "integer", "description", "Max ms to wait for a reply (blocking mode)"),
+                        "wait", Map.of("type", "boolean",
+                                "description", "Block for the reply (default true); false returns a ticket to poll"),
+                        "turnId", stringProp("When answering a worker's bridge_ask, its question turnId — "
+                                + "routes your answer back into the same turn (omit for a normal delegation)")),
+                        List.of("content")));
+    }
+
+    private static McpSchema.Tool askTool() {
+        // No target/session arg — the worker's identity is resolved from the connection.
+        return tool("bridge_ask",
+                "Pause your current delegated turn to ask the primary a question, blocking until it "
+                        + "answers — then resume the same turn with the answer. Use this when only the "
+                        + "primary has a decision or detail you need to continue. You do not address the "
+                        + "primary; identity is resolved from your connection.",
+                objectSchema(Map.of(
+                        "question", stringProp("The question to put to the primary"),
+                        "timeoutMs", Map.of("type", "integer",
+                                "description", "Max ms to wait for the primary's answer")),
+                        List.of("question")));
+    }
+
+    private static McpSchema.Tool pollTool() {
+        return tool("bridge_poll",
+                "Check an async delegation (a bridge_send with wait:false) by its ticket: "
+                        + "pending, done (with the worker's reply), or failed. When target (a worker "
+                        + "session id) is present instead of ticket, drain that worker's inbox of "
+                        + "replies delivered when no send was open.",
+                objectSchema(Map.of(
+                        "ticket", stringProp("The ticket returned by bridge_send wait:false"),
+                        "target", stringProp("Worker session id to drain pending replies from (optional)")),
+                        List.of()));
+    }
+
+    private static McpSchema.Tool ackTool() {
+        return tool("bridge_ack",
+                "Acknowledge (remove) a specific reply from a worker's inbox. Use when the primary "
+                        + "has processed a reply and wants to confirm it, leaving other pending replies "
+                        + "in the inbox for later drain.",
+                objectSchema(Map.of(
+                        "target", stringProp("Worker session id whose inbox to ack from"),
+                        "msgId", stringProp("The message id to acknowledge")),
+                        List.of("target", "msgId")));
+    }
+
+    private static McpSchema.Tool spawnTool() {
+        return tool("bridge_spawn",
+                "Spawn a new off-subscription member session. A member has two independent attributes: "
+                        + "role (what it is for) and profile (which backend it runs on). Pass role to pick "
+                        + "the contract — 'dev' implements a unit and opens its own PR, 'reviewer' reviews a "
+                        + "diff it did not write, 'architect' refines a ticket before anyone builds it; omit "
+                        + "it for 'dev'. Pass profile (from bridge_profiles) to pick the backend, or omit it "
+                        + "for the default. The two are independent: a reviewer may run on the same profile "
+                        + "as the dev it reviews. The member opens your current directory by default; pass "
+                        + "cwd to pin a different one. Pass worktree:true (with ticket) or "
+                        + "worktree:<ticket-slug> to provision an isolated git worktree. Returns the member's "
+                        + "sessionId (use with bridge_send) and paneId (use with bridge_stop).",
+                objectSchema(Map.of(
+                        "role", stringProp("What the member is for: architect, dev or reviewer (default dev)"),
+                        "profile", stringProp("Which backend to run it on (omit for the default profile)"),
+                        "cwd", stringProp("Working directory for the member (omit to inherit yours)"),
+                        "worktree", Map.of("type", "string", "description", "'true' or a ticket slug — requests an isolated git worktree"),
+                        "ticket", stringProp("Ticket slug when worktree:true")),
+                        List.of()));
+    }
+
+    private static McpSchema.Tool profilesTool() {
+        return tool("bridge_profiles",
+                "List the configured worker profiles (backends) and which one bridge_spawn uses by default.",
+                objectSchema(Map.of(), List.of()));
+    }
+
+    private static McpSchema.Tool listTool() {
+        return tool("bridge_list",
+                "List the whole fleet the bridge tracks, in two parts. 'leads' are your PEERS — other "
+                        + "orchestrators, each with its sessionId (the address to bridge_send to), "
+                        + "name, live status, and 'self': true on your own row; this is how you "
+                        + "discover a peer lead without being told its address. 'members' are the "
+                        + "sessions delegated to — each with sessionId, paneId, role (architect/dev/"
+                        + "reviewer), profile (the backend it runs on), state, optional "
+                        + "worktree/branch/owner, and live herdr status. An empty 'members' "
+                        + "means no members are spawned; it says nothing about peers.",
+                objectSchema(Map.of(), List.of()));
+    }
+
+    private static McpSchema.Tool stopTool() {
+        return tool("bridge_stop",
+                "Tear down a worker session by its paneId (from bridge_spawn or bridge_list).",
+                objectSchema(Map.of(
+                        "paneId", stringProp("The worker's paneId to stop")),
+                        List.of("paneId")));
+    }
+
+    private static McpSchema.Tool replyTool() {
+        // No session/target arg — the caller's identity is resolved from the connection.
+        return tool("bridge_reply",
+                "Return your structured answer for a message you were sent, resolving the sender's "
+                        + "blocked bridge_send. A worker MUST end every delegated turn with exactly "
+                        + "one of these. A lead uses it only to answer another lead that messaged "
+                        + "it — never to answer a worker, whose turn it is not.",
+                objectSchema(Map.of(
+                        "content", stringProp("Your reply/answer")),
+                        List.of("content")));
+    }
+
+    private static McpSchema.Tool statusTool() {
+        return tool("bridge_status",
+                "Get the live lifecycle status (idle/working/blocked/unknown) of a worker session.",
+                objectSchema(Map.of(
+                        "sessionId", stringProp("The worker session id to query")),
+                        List.of("sessionId")));
+    }
+
+    private static McpSchema.Tool whoamiTool() {
+        return tool("bridge_whoami",
+                "Report who YOU are on the bridge — your role is resolved from your connection "
+                        + "(unforgeable), never from anything you claim. Returns role 'primary' (you "
+                        + "orchestrate: spawn/send/stop; reply ONLY to answer a peer lead that "
+                        + "messaged you, never to answer a worker), 'architect' (you delegate turns "
+                        + "and reply/ask as your own pane, but cannot spawn/stop/drain), or 'worker' "
+                        + "(you were delegated to: you must end every turn with exactly one "
+                        + "bridge_reply, and cannot spawn or send), plus 'leader'/'architect' naming "
+                        + "which one you are, your own sessionId, and profile/worktree/branch when "
+                        + "you are a worker. Call this first when following role-conditional "
+                        + "instructions rather than guessing.",
+                objectSchema(Map.of(), List.of()));
+    }
+
+    // --- small helpers -------------------------------------------------------------------------
+
+    // The SDK 2.0.0 deprecates its own Tool builders without a stable replacement — isolate it here.
+    @SuppressWarnings("deprecation")
+    private static McpSchema.Tool tool(String name, String description, Map<String, Object> inputSchema) {
+        return McpSchema.Tool.builder(name).description(description).inputSchema(inputSchema).build();
+    }
+
+    private static Map<String, Object> objectSchema(Map<String, Object> properties, List<String> required) {
+        return Map.of("type", "object", "properties", properties, "required", required);
+    }
+
+    private static Map<String, Object> stringProp(String description) {
+        return Map.of("type", "string", "description", description);
+    }
+
+    private static McpSchema.CallToolResult text(String s) {
+        return McpSchema.CallToolResult.builder().addTextContent(s == null ? "" : s).build();
+    }
+
+    private static McpSchema.CallToolResult error(String s) {
+        return McpSchema.CallToolResult.builder().addTextContent(s).isError(true).build();
+    }
+
+    private static String str(Map<String, Object> args, String key) {
+        Object v = args.get(key);
+        return v == null ? null : v.toString();
+    }
+
+    private static Long timeoutMs(Map<String, Object> args) {
+        Object v = args.get("timeoutMs");
+        return v instanceof Number n ? n.longValue() : null;
+    }
+
+    private static long clamp(long ms) {
+        return Math.clamp(ms, 1, MAX_TIMEOUT_MS);
+    }
+
+    private static boolean isBlank(String s) {
+        return s == null || s.isBlank();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/mcp/ConnectionIdentity.java

@@ -0,0 +1,66 @@
+package dev.ltms.bridged.mcp;
+
+import dev.ltms.bridged.herdr.PaneLocator;
+
+/**
+ * Resolves <em>who is calling</em> an MCP tool from the connection alone — the anti-spoofing
+ * identity model of the MCP contract. It ties the connection's loopback peer PID (from the OS)
+ * to a herdr agent pane (from herdr), yielding the caller's worker {@code terminal_id}. A caller
+ * that maps to no worker pane — the primary, or an off-host client — resolves to {@code null}.
+ *
+ * <p>Both sources are authoritative and unforgeable: the OS reports the real connecting PID, and
+ * herdr owns the PID→pane mapping. A worker cannot claim to be another worker, nor the primary.
+ * Single-host only (the herd shares the {@code bridged} host); the token path is the split-host
+ * fallback.
+ */
+public final class ConnectionIdentity {
+
+    private final PaneLocator panes;
+    private final PeerPidLookup pids;
+    private final ProcessCwdLookup cwds;
+
+    /** Identity only (no cwd resolution — {@link #cwdForPid} returns {@code null}). */
+    public ConnectionIdentity(PaneLocator panes, PeerPidLookup pids) {
+        this(panes, pids, _ -> null);
+    }
+
+    /** Identity plus cwd resolution (CB-112 — inherit the primary's directory on spawn). */
+    public ConnectionIdentity(PaneLocator panes, PeerPidLookup pids, ProcessCwdLookup cwds) {
+        this.panes = panes;
+        this.pids = pids;
+        this.cwds = cwds;
+    }
+
+    /**
+     * The caller resolved from the connection: its worker {@code terminal} (or {@code null} for the
+     * primary / an off-host client) and its {@code pid} (or {@code -1} if not resolvable).
+     */
+    public record Caller(String terminal, long pid) {
+    }
+
+    /** Resolve the caller's terminal and PID from one peer-PID lookup. */
+    public Caller resolve(String remoteAddr, int remotePort) {
+        if (!isLoopback(remoteAddr)) {
+            return new Caller(null, -1); // only same-host callers can be workers
+        }
+        long pid = pids.pidForLocalPort(remotePort);
+        return new Caller(panes.terminalForPid(pid), pid);
+    }
+
+    /**
+     * The calling worker's {@code terminal_id}, or {@code null} if the caller is not a known
+     * on-host worker (treat as the primary).
+     */
+    public String callerTerminal(String remoteAddr, int remotePort) {
+        return resolve(remoteAddr, remotePort).terminal();
+    }
+
+    /** The working directory of {@code pid} (the primary's cwd on an MCP spawn), or {@code null}. */
+    public String cwdForPid(long pid) {
+        return pid > 0 ? cwds.cwdForPid(pid) : null;
+    }
+
+    private static boolean isLoopback(String addr) {
+        return "127.0.0.1".equals(addr) || "::1".equals(addr) || "0:0:0:0:0:0:0:1".equals(addr);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/mcp/LsofPeerPidLookup.java

@@ -0,0 +1,58 @@
+package dev.ltms.bridged.mcp;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * {@link PeerPidLookup} via {@code lsof} (present on macOS and Linux). For a loopback TCP source
+ * {@code port}, both the client and this daemon appear on that port — so we exclude our own PID
+ * and take the other end, which is the calling process.
+ */
+public final class LsofPeerPidLookup implements PeerPidLookup {
+
+    private static final Logger log = LoggerFactory.getLogger(LsofPeerPidLookup.class);
+
+    private final long selfPid = ProcessHandle.current().pid();
+
+    @Override
+    public long pidForLocalPort(int port) {
+        try {
+            Process p = new ProcessBuilder("lsof", "-nP", "-FpP", "-iTCP:" + port)
+                    .redirectErrorStream(true).start();
+            long found = -1;
+            try (BufferedReader r = new BufferedReader(
+                    new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8))) {
+                long current = -1;
+                String line;
+                // -Fp emits records: a 'p<pid>' line, then the ports/files under that pid.
+                while ((line = r.readLine()) != null) {
+                    if (line.startsWith("p")) {
+                        current = parse(line.substring(1));
+                    } else if (current > 0 && current != selfPid) {
+                        found = current; // first process on this port that isn't us = the client
+                    }
+                }
+            }
+            if (!p.waitFor(2, TimeUnit.SECONDS)) {
+                p.destroyForcibly();
+            }
+            return found;
+        } catch (Exception e) {
+            log.debug("lsof peer-pid lookup for port {} failed: {}", port, e.getMessage());
+            return -1;
+        }
+    }
+
+    private static long parse(String s) {
+        try {
+            return Long.parseLong(s.trim());
+        } catch (NumberFormatException e) {
+            return -1;
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/mcp/LsofProcessCwdLookup.java

@@ -0,0 +1,48 @@
+package dev.ltms.bridged.mcp;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * {@link ProcessCwdLookup} via {@code lsof} (present on macOS and Linux): {@code lsof -a -p <pid>
+ * -d cwd -Fn} prints the process's cwd on the {@code n…} line. Used to inherit the primary's
+ * working directory for a spawned worker (CB-112).
+ */
+public final class LsofProcessCwdLookup implements ProcessCwdLookup {
+
+    private static final Logger log = LoggerFactory.getLogger(LsofProcessCwdLookup.class);
+
+    @Override
+    public String cwdForPid(long pid) {
+        if (pid <= 0) {
+            return null;
+        }
+        try {
+            Process p = new ProcessBuilder("lsof", "-a", "-p", Long.toString(pid), "-d", "cwd", "-Fn")
+                    .redirectErrorStream(true).start();
+            String cwd = null;
+            try (BufferedReader r = new BufferedReader(
+                    new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8))) {
+                String line;
+                while ((line = r.readLine()) != null) {
+                    if (line.startsWith("n")) { // 'n<path>' is the file-name field for the cwd fd
+                        cwd = line.substring(1);
+                        break;
+                    }
+                }
+            }
+            if (!p.waitFor(2, TimeUnit.SECONDS)) {
+                p.destroyForcibly();
+            }
+            return (cwd == null || cwd.isBlank()) ? null : cwd;
+        } catch (Exception e) {
+            log.debug("lsof cwd lookup for pid {} failed: {}", pid, e.getMessage());
+            return null;
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/mcp/PeerPidLookup.java

@@ -0,0 +1,13 @@
+package dev.ltms.bridged.mcp;
+
+/**
+ * Resolves the OS PID that owns a loopback TCP source port — the OS half of connection-based MCP
+ * identity. Java exposes no peer PID for a TCP socket, so this shells out. Injectable so
+ * {@link ConnectionIdentity} is testable without a real connection.
+ */
+@FunctionalInterface
+public interface PeerPidLookup {
+
+    /** The PID whose socket has local (source) {@code port} on loopback, or {@code -1} if unknown. */
+    long pidForLocalPort(int port);
+}

bridged/src/main/java/dev/ltms/bridged/mcp/PrimaryRegistry.java

@@ -0,0 +1,117 @@
+package dev.ltms.bridged.mcp;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Single-slot, thread-safe registry for the primary's herdr {@code terminal_id}.
+ *
+ * <p>Populated from the caller terminal of orchestration-side MCP tools
+ * ({@code bridge_send}, {@code bridge_spawn}) — tools that only the primary calls.
+ * A pinned terminal (from config) seeds the registry at construction and makes
+ * subsequent {@link #record(String)} calls no-ops.
+ *
+ * <p>The push loop ({@code ReplyPushLoop}) uses {@link #isKnown()} to decide
+ * whether active nudging is possible; an empty registry means the primary is
+ * off-host or non-herdr and delivery falls back to pull.
+ */
+public final class PrimaryRegistry {
+
+    private static final Logger log = LoggerFactory.getLogger(PrimaryRegistry.class);
+
+    private final AtomicReference<String> terminal = new AtomicReference<>();
+    private final boolean pinned;
+
+    /**
+     * CB-532: worker terminal → the lead that delegated to it. The single slot above answers "who is
+     * THE primary", a question with no correct answer once two leads orchestrate the same fleet:
+     * whichever called {@code bridge_send} first captured every nudge, including nudges for the
+     * other lead's delegations. This map answers the question that actually matters — "who is
+     * waiting on THIS worker" — and is what lets {@code primary.terminal} be retired.
+     */
+    private final ConcurrentHashMap<String, String> leadByTarget = new ConcurrentHashMap<>();
+
+    /**
+     * @param pinnedTerminal an optional pinned terminal from config ({@code null}/blank = unpinned)
+     */
+    public PrimaryRegistry(String pinnedTerminal) {
+        if (pinnedTerminal != null && !pinnedTerminal.isBlank()) {
+            this.terminal.set(pinnedTerminal);
+            this.pinned = true;
+            log.info("primary terminal pinned: {}", pinnedTerminal);
+        } else {
+            this.pinned = false;
+        }
+    }
+
+    /**
+     * Record a terminal_id. No-op when:
+     * <ul>
+     *   <li>the registry is pinned (config override),
+     *   <li>{@code terminalId} is {@code null} or blank (non-herdr caller).
+     * </ul>
+     */
+    public void record(String terminalId) {
+        if (pinned) return;
+        if (terminalId == null || terminalId.isBlank()) return;
+        String prev = terminal.getAndSet(terminalId);
+        if (prev == null) {
+            log.debug("primary terminal learned: {}", terminalId);
+        } else if (!prev.equals(terminalId)) {
+            log.debug("primary terminal changed: {} -> {}", prev, terminalId);
+        }
+    }
+
+    /**
+     * Record that {@code leadTerminal} owns the accepted delegation of worker {@code target} (CB-532).
+     *
+     * <p>Called from the {@code MessageService} accepted-delivery hook — only after a send has won
+     * the session's send lock and queued delivery — where both halves are known (CB-548). It is
+     * deliberately <em>not</em> called at {@code bridge_send} request time: a concurrent sender that
+     * times out {@code BUSY} must not steal a live delegation's reply routing without ever owning
+     * the turn. Last writer wins — if a second lead's later send is accepted, replies follow the
+     * lead that most recently delegated to it, which is the one waiting.
+     */
+    public void recordDelegation(String target, String leadTerminal) {
+        if (target == null || target.isBlank() || leadTerminal == null || leadTerminal.isBlank()) {
+            return;
+        }
+        leadByTarget.put(target, leadTerminal);
+    }
+
+    /** Forget a worker's delegating lead — call on release, so a torn-down session leaks nothing. */
+    public void forgetDelegation(String target) {
+        if (target != null) {
+            leadByTarget.remove(target);
+        }
+    }
+
+    /**
+     * Where a nudge about {@code target}'s reply should go: the lead that delegated to it, falling
+     * back to the single known primary.
+     *
+     * <p>The fallback matters after a daemon restart, which loses the map while the durable inbox
+     * keeps the reply. With one lead the fallback is unambiguous and correct. With several and no
+     * recorded delegation there is no right answer, so this returns empty rather than guessing —
+     * delivery degrades to pull, which is exactly what the durable inbox is for, instead of
+     * interrupting the wrong lead with someone else's result.
+     */
+    public Optional<String> nudgeTargetFor(String target) {
+        String lead = target == null ? null : leadByTarget.get(target);
+        return lead != null ? Optional.of(lead) : Optional.ofNullable(terminal.get());
+    }
+
+    /** The known primary terminal, or empty if not yet learned (and not pinned). */
+    public Optional<String> primaryTerminal() {
+        return Optional.ofNullable(terminal.get());
+    }
+
+    /** {@code true} once a terminal has been recorded (or was pinned at construction). */
+    public boolean isKnown() {
+        return terminal.get() != null;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/mcp/ProcessCwdLookup.java

@@ -0,0 +1,13 @@
+package dev.ltms.bridged.mcp;
+
+/**
+ * Resolves a process's current working directory from its PID — the OS half of CB-112's
+ * "a worker inherits the primary's directory." Injectable so {@link ConnectionIdentity} stays
+ * testable without shelling out.
+ */
+@FunctionalInterface
+public interface ProcessCwdLookup {
+
+    /** The working directory of {@code pid}, or {@code null} if unknown. */
+    String cwdForPid(long pid);
+}

bridged/src/main/java/dev/ltms/bridged/member/ClaudeCodeLauncher.java

@@ -0,0 +1,350 @@
+package dev.ltms.bridged.member;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.guard.SubscriptionGuard;
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.WorkspaceControl;
+import dev.ltms.bridged.peer.Capability;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.function.Function;
+import java.util.function.LongSupplier;
+import java.util.function.Supplier;
+
+/**
+ * The {@link HerdrPeerLauncher} adapter for <strong>Claude Code</strong> — the safe path from a
+ * delegation request to a running off-subscription Claude.
+ *
+ * <p>Everything transport-related (tab/pane placement, the CB-306 spawn-readiness gate, unique
+ * naming, CB-117 orphan reap, teardown, listing, cwd resolution) lives in the base. This class
+ * supplies only the two Claude-specific seams:
+ * <ul>
+ *   <li>the {@code claude} name prefix (so reap matches {@code claude-*} panes, never another
+ *       adapter's), and</li>
+ *   <li>{@link #buildLaunch}, which encodes the subscription boundary: build the worker env with
+ *       {@code ANTHROPIC_BASE_URL}, assert that host is on the allowlist <em>before</em> touching
+ *       herdr, and mount the bridge MCP + reply charter as inline launch flags. A worker's base_url
+ *       lives in the env map handed to herdr and nowhere else; {@code bridged}'s own environment is
+ *       never mutated, and nothing is written to the worker's profile.</li>
+ * </ul>
+ */
+public final class ClaudeCodeLauncher extends HerdrPeerLauncher {
+
+    /** Label prefix for this adapter's herdr agent names (drives naming + orphan reap). */
+    private static final String NAME_PREFIX = "claude";
+
+    private static final Logger log = LoggerFactory.getLogger(ClaudeCodeLauncher.class);
+
+    private final SubscriptionGuard guard;
+
+    /**
+     * Standing instruction appended to the worker's system prompt so it returns its result via
+     * {@code bridge_reply}. Injected as a launch flag, so nothing is written to the worker's
+     * profile — it is guidance, and a worker that never replies is caught by the send's timeout.
+     */
+    static final String REPLY_CHARTER =
+            "You are an off-subscription worker in the claude-bridge fleet. Every message you "
+            + "receive arrives through the bridge, and the ONLY channel back to the sender is the "
+            + "bridge_reply MCP tool. Text you write in your terminal is NOT sent anywhere — the "
+            + "sender cannot see your screen, so an in-terminal answer is silently discarded. "
+            + "Therefore you MUST end EVERY turn by calling bridge_reply with `content` set to your "
+            + "complete response. This holds for every message without exception — tasks, questions, "
+            + "clarifications, acknowledgements, and ordinary back-and-forth conversation. Call "
+            + "bridge_reply exactly once, as the final action of your turn, with your full answer in "
+            + "`content`; never wait for confirmation first. If you end a turn without calling "
+            + "bridge_reply, the sender receives nothing and the exchange stalls.";
+
+    /**
+     * Production constructor — disables the spawn-ready gate ({@code spawnReadyTimeoutMs == 0}) so
+     * existing deployments and tests keep the legacy non-blocking spawn semantics.
+     */
+    public ClaudeCodeLauncher(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
+                              Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                              Function<String, String> env) {
+        this(agents, spaces, guard, profiles, defaultProfile, env, 0,
+                System::currentTimeMillis, () -> sleepUninterruptibly(300));
+    }
+
+    /**
+     * Production constructor with spawn-ready gate enabled. The gate polls {@code agents.status()}
+     * until the pane reports an injectable state or {@code spawnReadyTimeoutMs} elapses.
+     */
+    public ClaudeCodeLauncher(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
+                              Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                              Function<String, String> env,
+                              long spawnReadyTimeoutMs, long spawnReadyPollMs) {
+        this(agents, spaces, guard, profiles, defaultProfile, env,
+                spawnReadyTimeoutMs, spawnReadyPollMs, null);
+    }
+
+    /**
+     * Production constructor carrying the fleet-wide tab-label template (CB-557). The template comes
+     * from {@code fleet.tabLabel}, which a profile cannot know because it names the member's
+     * <em>role</em>; a profile may still override it with its own {@code tabLabel}.
+     */
+    public ClaudeCodeLauncher(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
+                              Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                              Function<String, String> env,
+                              long spawnReadyTimeoutMs, long spawnReadyPollMs,
+                              Supplier<String> tabLabelTemplate) {
+        this(agents, spaces, guard, profiles, defaultProfile, env,
+                spawnReadyTimeoutMs,
+                System::currentTimeMillis, () -> sleepUninterruptibly(spawnReadyPollMs),
+                tabLabelTemplate);
+    }
+
+    /**
+     * Full testability constructor. Every injectable collaborator is explicit so unit tests supply
+     * fakes for the clock ({@code nowMillis}) and poll-loop wait ({@code sleeper}). The
+     * {@code sleeper} is never called when the gate is disabled ({@code spawnReadyTimeoutMs == 0}).
+     *
+     * @param agents               herdr agent control (start, status, close)
+     * @param spaces               workspace / tab control (ensure, create, close)
+     * @param guard                subscription-boundary guard (checked before spawning)
+     * @param profiles             configured worker profiles
+     * @param defaultProfile       profile a no-argument spawn uses (nullable)
+     * @param env                  host env lookup (injectable for tests)
+     * @param spawnReadyTimeoutMs  max ms to wait for injectable state (0 disables the gate)
+     * @param nowMillis            monotonic clock source (e.g. {@code System::currentTimeMillis})
+     * @param sleeper              sleep/wait hook (e.g. {@code () -> Thread.sleep(pollMs)}); it
+     *                             already encodes the poll interval, so the 8th positional argument
+     *                             (poll ms) is accepted for API symmetry but otherwise unused here
+     */
+    public ClaudeCodeLauncher(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
+                              Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                              Function<String, String> env,
+                              long spawnReadyTimeoutMs,
+                              LongSupplier nowMillis, Runnable sleeper) {
+        this(agents, spaces, guard, profiles, defaultProfile, env,
+                spawnReadyTimeoutMs, nowMillis, sleeper, null);
+    }
+
+    /**
+     * Full testability constructor, plus the fleet-wide tab-label template (CB-557).
+     *
+     * @param tabLabelTemplate {@code fleet.tabLabel}; {@code null}/blank ⇒
+     *                         {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}
+     */
+    public ClaudeCodeLauncher(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
+                              Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                              Function<String, String> env,
+                              long spawnReadyTimeoutMs,
+                              LongSupplier nowMillis, Runnable sleeper,
+                              Supplier<String> tabLabelTemplate) {
+        super(NAME_PREFIX, agents, spaces, profiles, defaultProfile, env,
+                spawnReadyTimeoutMs, nowMillis, sleeper, tabLabelTemplate);
+        this.guard = guard;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>A legacy spawn with no session identity is a fresh, launcher-derived session — delegate to
+     * the session-aware form with no name and no resume id.
+     */
+    @Override
+    protected Launch buildLaunch(BridgedConfig.Profile cfg) {
+        return buildLaunch(cfg, null, null);
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>The spawn sequence encodes the subscription boundary: assert the profile's base_url is on
+     * the allowlist <em>before</em> any herdr call, then build the worker env with
+     * {@code ANTHROPIC_*}, the parity-neutral git-forge grant, and the bridge MCP + reply charter
+     * mounted as inline launch flags. When the request carries session identity (CB-547a) it is
+     * applied here — see {@link #applySessionIdentity}.
+     */
+    @Override
+    protected Launch buildLaunch(BridgedConfig.Profile cfg, String sessionName, String resumeSessionId) {
+        // CB-539: a profile may deliberately opt into the subscription (subscription: true) when no
+        // off-subscription endpoint exists for it — e.g. `sonnet` on `ccs`. That profile gets no
+        // ANTHROPIC_BASE_URL/AUTH_TOKEN (there is nothing to point them at) and the guard's base_url
+        // requirement is skipped FOR IT ONLY. Every other profile keeps the hard boundary below.
+        boolean onSubscription = cfg.isSubscription();
+        String baseUrl = cfg.baseUrl();
+
+        if (onSubscription) {
+            // NO SILENT CONTRADICTION: subscription:true + a baseUrl state opposite intents; refuse
+            // loudly rather than pick a winner.
+            if (baseUrl != null && !baseUrl.isBlank()) {
+                throw new IllegalStateException("profile '" + cfg.profile()
+                        + "' sets both subscription: true and a baseUrl ('" + baseUrl + "') — the two "
+                        + "are contradictory: a subscription profile must not point at an endpoint. "
+                        + "Drop baseUrl, or drop subscription: true.");
+            }
+            // Visible without anyone going looking for it: this worker bills the subscription.
+            log.warn("spawning profile '{}' on the Claude subscription (subscription: true) — this "
+                    + "worker WILL bill the operator's subscription", cfg.profile());
+        } else {
+            guard.assertWorker(baseUrl); // hard stop before we spawn anything
+        }
+
+        Map<String, String> workerEnv = baseEnv(cfg);
+        if (onSubscription) {
+            // CB-542 belt-and-braces: on the subscription path no guard vets these two keys, and the
+            // profile's env: is layered in by baseEnv — so strip any that rode in there. Config load
+            // already rejects this (loudly, naming the profile); this makes the boundary hold even
+            // for a profile built in code that never passed through that validation.
+            workerEnv.remove("ANTHROPIC_BASE_URL");
+            workerEnv.remove("ANTHROPIC_AUTH_TOKEN");
+        } else {
+            workerEnv.put("ANTHROPIC_BASE_URL", baseUrl);
+            putIfPresent(workerEnv, "ANTHROPIC_AUTH_TOKEN", env.apply(cfg.tokenEnv()));
+        }
+        putIfPresent(workerEnv, "ANTHROPIC_MODEL", cfg.model());
+        putIfPresent(workerEnv, "CLAUDE_CONFIG_DIR", cfg.configDir());
+        applyGitToken(workerEnv, cfg);
+
+        // CB-547a: Claude Code can MINT its own session id, so bridged chooses it — a fresh spawn
+        // gets a UUID we pass as --session-id and return from agentSessionId(), so the resume
+        // handle is known BEFORE the agent has written anything; a resume spawn adopts its prior
+        // id via -r and passes no --session-id (the two conflict). Both are injected before the
+        // model flag so --model keeps outranking the operator's own argv.
+        // mutableArgv: argvWithBridge may hand back the profile's own (immutable) List.of when it
+        // has no MCP — session flags must be added into a list we own.
+        List<String> argv = mutableArgv(argvWithBridge(cfg));
+        String agentSessionId = applySessionIdentity(argv, sessionName, resumeSessionId);
+        return new Launch(workerEnv, argvWithModel(argv, cfg), agentSessionId);
+    }
+
+    /**
+     * Add the Claude-specific session-identity flags to {@code argv} and return the peer's OWN
+     * session id — the resume handle. A resume request passes the prior id via {@code -r} and
+     * returns that id; a fresh named session mints a new UUID, passes it via {@code --session-id},
+     * and returns the mint. The bridge's logical name rides along as {@code -n} when present. When
+     * <em>no</em> identity is requested (sessionName and resumeSessionId both blank) this adds
+     * nothing and returns {@code null}, keeping the legacy no-identity launch byte-identical.
+     */
+    private static String applySessionIdentity(List<String> argv, String sessionName, String resumeSessionId) {
+        boolean resuming = resumeSessionId != null && !resumeSessionId.isBlank();
+        boolean named = sessionName != null && !sessionName.isBlank();
+        if (!resuming && !named) {
+            return null; // no identity requested — keep the legacy launch byte-identical
+        }
+        if (named) {
+            argv.add("-n");
+            argv.add(sessionName);
+        }
+        if (resuming) {
+            argv.add("-r");
+            argv.add(resumeSessionId);
+            return resumeSessionId;
+        }
+        String minted = UUID.randomUUID().toString();
+        argv.add("--session-id");
+        argv.add(minted);
+        return minted;
+    }
+
+    /**
+     * The launch argv, plus — when {@code worker.mcpUrl} is set — inline {@code --mcp-config} for
+     * the bridge server and {@code --append-system-prompt} for the {@link #REPLY_CHARTER}. Neither
+     * touches the profile's config; both are pure command-line flags. This inline-flag mount is
+     * Claude Code specific — other adapters mount MCP and instructions their own way.
+     */
+    private List<String> argvWithBridge(BridgedConfig.Profile cfg) {
+        if (!cfg.hasMcp()) {
+            return cfg.argv();
+        }
+        String mcpJson = "{\"mcpServers\":{\"bridge\":{\"type\":\"http\",\"url\":\""
+                + cfg.mcpUrl() + "\"}}}";
+        List<String> argv = mutableArgv(cfg.argv());
+        argv.add("--mcp-config");
+        argv.add(mcpJson);
+        argv.add("--append-system-prompt");
+        argv.add(REPLY_CHARTER);
+        return argv;
+    }
+
+    /**
+     * Pin the model on the command line as well as in {@code ANTHROPIC_MODEL} (CB-533).
+     *
+     * <p>The env var alone is not a reliable pin for this adapter, because the argv is usually a
+     * launcher rather than {@code claude} itself — {@code ["ccs", "<profile>"]} — and {@code ccs}
+     * exports its profile's own model family ({@code ANTHROPIC_MODEL}, {@code DEFAULT_OPUS/SONNET/
+     * HAIKU}, {@code CLAUDE_CODE_SUBAGENT_MODEL}) over whatever it inherited. A worker profile that
+     * set {@code model:} therefore got silently overruled by its own launcher. Claude Code's
+     * {@code --model} flag outranks the environment, and {@code ccs <profile> [claude-args...]}
+     * passes trailing arguments through, so the flag survives the wrapper.
+     *
+     * <p>Appended last so it also outranks anything in the operator's own {@code argv}. Profiles
+     * that deliberately leave {@code model:} unset (letting {@code ccs} own model selection, as
+     * {@code gx10} does) are untouched — this adds nothing when there is nothing to add. This is
+     * the {@code kind: claude} counterpart of the opencode adapter's {@code -m provider/model}.
+     */
+    private static List<String> argvWithModel(List<String> argv, BridgedConfig.Profile cfg) {
+        if (cfg.model() == null || cfg.model().isBlank()) {
+            return argv;
+        }
+        List<String> withModel = mutableArgv(argv);
+        withModel.add("--model");
+        withModel.add(cfg.model());
+        return withModel;
+    }
+
+    // --- Agent-returning convenience spawns (used by callers/tests that want the herdr Agent) ---
+
+    /** Spawn a worker for the default profile in the resolved default cwd. */
+    public Agent spawn() {
+        return spawnInternal(null, null, null);
+    }
+
+    /** Spawn a worker for a named profile (null → default) in the resolved default cwd. */
+    public Agent spawn(String profileName) {
+        return spawnInternal(profileName, null, null);
+    }
+
+    /** Spawn a worker for a named profile with an explicit requested/caller cwd (CB-112). */
+    public Agent spawn(String profileName, String requestedCwd, String callerCwd) {
+        return spawnInternal(profileName, requestedCwd, callerCwd);
+    }
+
+    // --- capabilities --------------------------------------------------------------------------
+
+    @Override
+    public Set<Capability> capabilities() {
+        Set<Capability> caps = EnumSet.of(Capability.MID_TURN_ASK, Capability.WORKTREE,
+                Capability.CONTEXT_RESET, Capability.ORPHAN_REAP,
+                Capability.SESSION_NAME, Capability.SESSION_RESUME);
+        if (hasGitTokenProfile()) {
+            caps.add(Capability.SELF_PR);
+        }
+        return Set.copyOf(caps);
+    }
+
+    @Override
+    public boolean clearContext(String id) {
+        String target = agentTarget(id);
+        if (target == null) {
+            return false;
+        }
+        // This deliberately bypasses Injector: /clear is housekeeping, not a delegated turn.
+        agents().send(target, "/clear");
+        return true;
+    }
+
+    /** Whether any configured profile opts into a git-forge token (required for {@link Capability#SELF_PR}). */
+    private boolean hasGitTokenProfile() {
+        return profileConfigs().stream().anyMatch(BridgedConfig.Profile::hasGitToken);
+    }
+
+    // --- CB-117 reap predicate (Claude prefix), kept for direct unit testing -------------------
+
+    /**
+     * Whether {@code name} is a Claude Code bridge worker started by a <em>different</em> process
+     * than {@code currentNonce}. A thin {@code claude}-prefix binding of
+     * {@link HerdrPeerLauncher#isForeignWorker(String, String, String)}.
+     */
+    static boolean isForeignWorker(String name, String currentNonce) {
+        return HerdrPeerLauncher.isForeignWorker(NAME_PREFIX, name, currentNonce);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/member/CompositePeerLauncher.java

@@ -0,0 +1,422 @@
+package dev.ltms.bridged.member;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.peer.Capability;
+import dev.ltms.bridged.peer.MemberRole;
+import dev.ltms.bridged.peer.PeerHandle;
+import dev.ltms.bridged.peer.PeerLauncher;
+import dev.ltms.bridged.peer.PeerUnreachableException;
+import dev.ltms.bridged.peer.SpawnRequest;
+import dev.ltms.bridged.placement.PlacementCandidate;
+import dev.ltms.bridged.placement.PlacementContext;
+import dev.ltms.bridged.placement.PlacementException;
+import dev.ltms.bridged.placement.PlacementPolicies;
+import dev.ltms.bridged.placement.PlacementPolicy;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+/**
+ * The {@link PeerLauncher} the core actually holds when more than one adapter is configured — a thin
+ * router in front of one {@link HerdrPeerLauncher} per peer {@code kind} (Claude Code, opencode, …).
+ * It owns no transport of its own; it dispatches each SPI call to the delegate that owns the profile
+ * involved, and fans the fleet-wide queries (list/reap/caps/profiles) across all delegates.
+ *
+ * <p>Routing rules:
+ * <ul>
+ *   <li><strong>By profile</strong> — {@link #spawn}, {@link #effectiveCwd}, {@link #parityOverlay}
+ *       resolve the profile (a null/blank name → the global {@link #defaultProfile}) and delegate to
+ *       the single adapter that declares it. Profiles partition cleanly across adapters: the
+ *       constructor rejects a name claimed by two.</li>
+ *   <li><strong>By pane id</strong> — {@link #stop} routes to the adapter that spawned that pane
+ *       (recorded at spawn time). A pane the composite never spawned (only real for a caller that
+ *       hand-rolls an id) falls back to the first delegate; teardown is pane-id addressed and
+ *       tab cleanup is single-occupant guarded, so it is safe either way.</li>
+ *   <li><strong>Fleet-wide</strong> — {@link #reapOrphanWorkers} and {@link #capabilities} fan out
+ *       and combine. {@link #list} is deduplicated by pane id because every herdr-backed delegate
+ *       shares one herdr connection and so reports the same global agent set.</li>
+ * </ul>
+ *
+ * <p>CB-518: an unqualified spawn is routed through a {@link PlacementPolicy}. The default
+ * {@code fixed} policy reproduces the historical default-profile behaviour; {@code weighted} uses
+ * smooth weighted round-robin with {@code maxLoad} gating. If a chosen profile fails with
+ * {@link PeerUnreachableException}, the composite advances to the next available candidate and
+ * retries, bounded by the number of candidates.
+ */
+public final class CompositePeerLauncher implements PeerLauncher {
+
+    private static final Logger log = LoggerFactory.getLogger(CompositePeerLauncher.class);
+
+    private final List<HerdrPeerLauncher> delegates;
+    private final Map<String, HerdrPeerLauncher> byProfile;
+    private final String defaultProfile;
+
+    /** paneId → the delegate that spawned it, so {@link #stop} tears down through the right adapter. */
+    private final Map<String, HerdrPeerLauncher> spawnedBy = new ConcurrentHashMap<>();
+
+    private final Function<String, Integer> liveCount;
+
+    /**
+     * CB-559: the placement inputs are read <em>per spawn</em>, not captured at construction, so a
+     * config reload changes where the next member lands without a restart. These are the hot keys —
+     * role pools, an existing profile's weight/maxLoad, and the placement policy. What cannot change
+     * this way is the set of adapters ({@link #byProfile}), because a new backend needs a launcher
+     * and launchers are built once; {@code ConfigRef} classifies that as deferred and says so.
+     */
+    private final Supplier<Map<String, BridgedConfig.Profile>> profileConfigs;
+    private final Supplier<PlacementPolicy> placementPolicy;
+
+    /**
+     * CB-557: the role pools an unqualified spawn draws its candidates from. A supplier that yields
+     * {@code null}, and an empty pool for a role, both fall back to every configured profile — the
+     * pre-CB-557 behaviour.
+     */
+    private final Supplier<BridgedConfig.Fleet> fleet;
+
+    /**
+     * Backward-compatible constructor: fixed placement, no live-counting. Use this for tests and
+     * simple wiring; it preserves the pre-CB-518 behaviour exactly.
+     *
+     * @param delegates      one adapter per configured peer kind; must be non-empty and declare
+     *                       disjoint profile-name sets
+     * @param defaultProfile the profile a no-argument spawn resolves to (may be null)
+     * @throws IllegalArgumentException if {@code delegates} is empty or two adapters claim one profile
+     */
+    public CompositePeerLauncher(List<HerdrPeerLauncher> delegates, String defaultProfile) {
+        this(delegates, defaultProfile, Map.of(), PlacementPolicies.fixed(), _ -> 0);
+    }
+
+    /**
+     * Production constructor with a placement policy and live-worker counter.
+     *
+     * @param delegates      one adapter per configured peer kind; must be non-empty and declare
+     *                       disjoint profile-name sets
+     * @param defaultProfile the profile a no-argument spawn resolves to under {@code fixed} policy
+     * @param profileConfigs all configured worker profiles (used for candidate weights/caps)
+     * @param placementPolicy which policy governs unqualified spawns
+     * @param liveCount      live worker count per profile (must never return {@code null})
+     */
+    public CompositePeerLauncher(List<HerdrPeerLauncher> delegates,
+                                 String defaultProfile,
+                                 Map<String, BridgedConfig.Profile> profileConfigs,
+                                 PlacementPolicy placementPolicy,
+                                 Function<String, Integer> liveCount) {
+        this(delegates, defaultProfile, profileConfigs, placementPolicy, liveCount, null);
+    }
+
+    /**
+     * Production constructor with role pools (CB-557). An unqualified spawn draws its candidates from
+     * {@code fleet.<role>} instead of from every configured profile, so a reviewer is placed on a
+     * reviewer backend and never on, say, the architect-only one.
+     *
+     * @param fleet the configured role pools; {@code null} ⇒ every profile is a candidate for every
+     *              role, which is the pre-CB-557 behaviour
+     */
+    public CompositePeerLauncher(List<HerdrPeerLauncher> delegates,
+                                 String defaultProfile,
+                                 Map<String, BridgedConfig.Profile> profileConfigs,
+                                 PlacementPolicy placementPolicy,
+                                 Function<String, Integer> liveCount,
+                                 BridgedConfig.Fleet fleet) {
+        // LinkedHashMap, not Map.copyOf: candidates() promises definition order and the weighted
+        // policy breaks exact-weight ties on it, so a salted iteration order would make placement
+        // differ from one JVM run to the next.
+        this(delegates, defaultProfile,
+                constant(Collections.unmodifiableMap(new LinkedHashMap<>(profileConfigs))),
+                constant(placementPolicy), liveCount, constant(fleet));
+    }
+
+    /**
+     * Production constructor that re-reads its placement inputs per spawn (CB-559), so a config
+     * reload retargets the next member without a restart.
+     *
+     * @param config the live configuration — read at every spawn, never captured
+     */
+    public CompositePeerLauncher(List<HerdrPeerLauncher> delegates,
+                                 String defaultProfile,
+                                 Supplier<BridgedConfig> config,
+                                 Function<String, Integer> liveCount) {
+        this(delegates, defaultProfile,
+                () -> config.get().profiles(),
+                () -> PlacementPolicies.fromName(config.get().placement()),
+                liveCount,
+                () -> config.get().fleet());
+    }
+
+    /** The all-suppliers form every other constructor funnels into. */
+    private CompositePeerLauncher(List<HerdrPeerLauncher> delegates,
+                                  String defaultProfile,
+                                  Supplier<Map<String, BridgedConfig.Profile>> profileConfigs,
+                                  Supplier<PlacementPolicy> placementPolicy,
+                                  Function<String, Integer> liveCount,
+                                  Supplier<BridgedConfig.Fleet> fleet) {
+        this.fleet = fleet;
+        if (delegates.isEmpty()) {
+            throw new IllegalArgumentException("at least one peer adapter must be configured");
+        }
+        this.delegates = List.copyOf(delegates);
+        this.defaultProfile = defaultProfile;
+        this.profileConfigs = profileConfigs;
+        this.placementPolicy = placementPolicy;
+        this.liveCount = liveCount;
+        Map<String, HerdrPeerLauncher> index = new LinkedHashMap<>();
+        for (HerdrPeerLauncher d : this.delegates) {
+            for (String profile : d.profiles()) {
+                HerdrPeerLauncher prev = index.putIfAbsent(profile, d);
+                if (prev != null) {
+                    throw new IllegalArgumentException(
+                            "worker profile '" + profile + "' is claimed by two peer adapters");
+                }
+            }
+        }
+        // Order-preserving for the same reason, and because profiles() is user-visible (bridge_profiles).
+        this.byProfile = Collections.unmodifiableMap(index);
+    }
+
+    /** A supplier of a value fixed at construction — how the non-reloading constructors funnel in. */
+    private static <T> Supplier<T> constant(T value) {
+        return () -> value;
+    }
+
+    /**
+     * The currently-configured profiles, never null.
+     *
+     * <p>Read fresh on every call so a reload is visible; a caller that needs two consistent reads
+     * takes one local, as {@link #poolFor} does.
+     */
+    private Map<String, BridgedConfig.Profile> profiles0() {
+        Map<String, BridgedConfig.Profile> m = profileConfigs.get();
+        return m == null ? Map.of() : m;
+    }
+
+    /** The adapter owning {@code profileName} (null/blank → the default). Throws on an unknown profile. */
+    private HerdrPeerLauncher route(String profileName) {
+        String resolved = (profileName == null || profileName.isBlank()) ? defaultProfile : profileName;
+        if (resolved == null) {
+            // No profile and no default configured — hand to the first delegate so it raises the
+            // same "no default" error it would on its own; keeps the SPI contract single-sourced.
+            return delegates.getFirst();
+        }
+        HerdrPeerLauncher d = byProfile.get(resolved);
+        if (d == null) {
+            throw new IllegalArgumentException("unknown worker profile: " + resolved);
+        }
+        return d;
+    }
+
+    @Override
+    public PeerHandle spawn(SpawnRequest req) {
+        String requestedProfile = req.profileName();
+        if (requestedProfile != null && !requestedProfile.isBlank()) {
+            // An explicit profile bypasses the placement policy, but not the capacity cap: maxLoad
+            // is documented as an unconditional limit on this profile (BridgedConfig.Profile), and
+            // the charter makes explicit-profile spawns the normal path — so skipping the check
+            // here would leave the cap dead config in real operation.
+            HerdrPeerLauncher d = route(requestedProfile);
+            enforceMaxLoad(requestedProfile);
+            PeerHandle handle = d.spawn(req);
+            spawnedBy.put(handle.id(), d);
+            return handle;
+        }
+
+        // CB-557: an unqualified spawn is placed inside the pool of the role it asked for, not across
+        // the whole profile list. An EXPLICIT profile (above) is left alone on purpose — it is the
+        // operator overriding, and refusing it would break `bridge_spawn{profile:"opus"}`, which
+        // carries no role and so would be judged against the dev pool it was never meant for.
+        List<PlacementCandidate> candidates = candidates(req.role());
+        String roleDefault = defaultProfileFor(req.role());
+        Set<String> unreachable = new HashSet<>();
+        PlacementContext ctx = new PlacementContext(roleDefault, candidates, liveCount, unreachable);
+
+        int maxAttempts = candidates.isEmpty() ? 1 : candidates.size();
+        for (int attempt = 0; attempt < maxAttempts; attempt++) {
+            // Deliberately uncaught: when no candidate is left (all at cap, or all unreachable) the
+            // policy already throws a clear message. Catching it to rethrow a generic
+            // PeerUnreachableException would replace a precise diagnosis with a vague one.
+            PlacementCandidate chosen = placementPolicy.get().select(ctx);
+
+            HerdrPeerLauncher d = byProfile.get(chosen.profile());
+            if (d == null) {
+                // A configured profile with no adapter is a wiring bug; fail fast.
+                unreachable.add(chosen.profile());
+                continue;
+            }
+
+            // CB-547a: route the chosen profile but keep the caller's session identity — dropping it
+            // here would silently sever the resume handle on every policy-routed spawn. CB-557: the
+            // role rides along for the same reason, or a routed spawn would be labelled as a dev.
+            SpawnRequest routedReq = new SpawnRequest(chosen.profile(), req.requestedCwd(), req.callerCwd(),
+                    req.sessionName(), req.resumeSessionId(), req.role());
+            try {
+                PeerHandle handle = d.spawn(routedReq);
+                spawnedBy.put(handle.id(), d);
+                return handle;
+            } catch (PeerUnreachableException e) {
+                log.warn("spawn on profile {} unreachable, will retry next candidate if any: {}",
+                        chosen.profile(), e.getMessage());
+                unreachable.add(chosen.profile());
+                // Update the context for the next selection so the policy excludes this profile.
+                ctx = new PlacementContext(roleDefault, candidates, liveCount, unreachable);
+            }
+        }
+
+        throw new PeerUnreachableException(
+                "no reachable worker profile available after trying " + unreachable.size()
+                        + " candidate(s): " + String.join(", ", unreachable));
+    }
+
+    /**
+     * Refuse an explicit-profile spawn when the profile is at its {@code maxLoad} cap.
+     *
+     * <p>maxLoad is a documented, unconditional capacity limit (see {@code BridgedConfig.Profile#maxLoad}),
+     * and the charter makes explicit-profile spawns the normal path — so enforcing it only in placement
+     * ({@code PlacementPolicyUtil}, package-private, hence not linked) would leave the cap dead config
+     * on every call that names a profile. Same rule as placement: {@code live >= cap} is at capacity.
+     *
+     * <p>Deliberately no fallback to another profile: the caller named {@code profile} for a cost/model
+     * reason, and silently re-routing a paid-tier (subscription) request elsewhere is worse than
+     * refusing it. A caller that wants placement should omit the profile and let the policy pick.
+     *
+     * <p>Known TOCTOU limitation — documented, not fixed. {@link #liveCount} is read outside any lock and
+     * {@code SessionManager} registers a session only after {@code launcher.spawn} returns, so two
+     * genuinely concurrent spawns can both pass this check. The race already exists on the placement
+     * path. Closing it needs slot reservation in the registry; serializing spawn here would block on
+     * the readiness gate and is a far worse trade.
+     *
+     * @param profile the profile the caller explicitly named
+     * @throws PlacementException when the profile is at capacity
+     */
+    private void enforceMaxLoad(String profile) {
+        // Absent config, or a config whose maxLoad normalized to null (non-positive ⇒ unlimited at
+        // load), means no cap — never cap what wasn't configured.
+        BridgedConfig.Profile cfg = profiles0().get(profile);
+        Integer cap = (cfg == null) ? null : cfg.maxLoad();
+        if (cap == null) {
+            return;
+        }
+        int live = liveCount.apply(profile);
+        if (live >= cap) {
+            throw new PlacementException("worker profile '" + profile + "' is at maxLoad: " + live
+                    + " live >= " + cap + " cap; refusing spawn — no fallback to another profile");
+        }
+    }
+
+    /**
+     * The profile names {@code role} may be placed on, in definition order.
+     *
+     * <p>An empty or absent pool means "unconstrained", not "nothing allowed": a config that declares
+     * no pool for a role must keep spawning, so it falls back to every configured profile. Names in a
+     * pool that no adapter declares are dropped here rather than thrown — config load already rejects
+     * a pool entry with no profile, so a survivor is a profile this particular composite does not own.
+     */
+    private List<String> poolFor(MemberRole role) {
+        Map<String, BridgedConfig.Profile> configured = profiles0();
+        BridgedConfig.Fleet f = fleet.get();
+        List<String> pool = (f == null) ? List.of() : f.profilesFor(role);
+        List<String> known = pool.stream().filter(configured::containsKey).toList();
+        return known.isEmpty() ? List.copyOf(configured.keySet()) : known;
+    }
+
+    /** The profile an unqualified spawn for {@code role} falls back to under {@code fixed} placement. */
+    private String defaultProfileFor(MemberRole role) {
+        List<String> pool = poolFor(role);
+        return pool.isEmpty() ? defaultProfile : pool.getFirst();
+    }
+
+    /** Build the candidate list from {@code role}'s pool, in definition order. */
+    private List<PlacementCandidate> candidates(MemberRole role) {
+        List<PlacementCandidate> out = new ArrayList<>();
+        for (String name : poolFor(role)) {
+            BridgedConfig.Profile w = profiles0().get(name);
+            if (w != null) {
+                out.add(new PlacementCandidate(name, null, w.weight(), w.maxLoad()));
+            }
+        }
+        return out;
+    }
+
+    @Override
+    public String effectiveCwd(SpawnRequest req) {
+        return route(req.profileName()).effectiveCwd(req);
+    }
+
+    @Override
+    public List<String> parityOverlay(String profileName) {
+        return route(profileName).parityOverlay(profileName);
+    }
+
+    @Override
+    public void stop(String id) {
+        HerdrPeerLauncher d = spawnedBy.remove(id);
+        if (d == null) {
+            log.debug("stop({}) — no recorded owner, routing to the first adapter (pane-addressed)", id);
+            d = delegates.getFirst();
+        }
+        d.stop(id);
+    }
+
+    @Override
+    public boolean clearContext(String id) {
+        HerdrPeerLauncher delegate = spawnedBy.get(id);
+        if (delegate == null) {
+            log.debug("clearContext({}) ignored — no recorded owning adapter", id);
+            return false;
+        }
+        return delegate.clearContext(id);
+    }
+
+    @Override
+    public Set<String> profiles() {
+        return byProfile.keySet();
+    }
+
+    @Override
+    public String defaultProfile() {
+        return defaultProfile;
+    }
+
+    /** Every herdr agent, deduplicated by pane id (all delegates share one herdr and list globally). */
+    @Override
+    public List<Agent> list() {
+        Map<String, Agent> byPane = new LinkedHashMap<>();
+        for (HerdrPeerLauncher d : delegates) {
+            for (Agent a : d.list()) {
+                if (a.paneId() != null) {
+                    byPane.putIfAbsent(a.paneId(), a);
+                }
+            }
+        }
+        return List.copyOf(byPane.values());
+    }
+
+    @Override
+    public int reapOrphanWorkers() {
+        int reaped = 0;
+        for (HerdrPeerLauncher d : delegates) {
+            reaped += d.reapOrphanWorkers();
+        }
+        return reaped;
+    }
+
+    /** The union of every adapter's capabilities — a capability any adapter offers, the fleet offers. */
+    @Override
+    public Set<Capability> capabilities() {
+        EnumSet<Capability> caps = EnumSet.noneOf(Capability.class);
+        for (HerdrPeerLauncher d : delegates) {
+            caps.addAll(d.capabilities());
+        }
+        return Set.copyOf(caps);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/member/HerdrPeerLauncher.java

@@ -0,0 +1,738 @@
+package dev.ltms.bridged.member;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.HerdrException;
+import dev.ltms.bridged.herdr.Tab;
+import dev.ltms.bridged.herdr.Workspace;
+import dev.ltms.bridged.herdr.WorkspaceControl;
+import dev.ltms.bridged.peer.MemberRole;
+import dev.ltms.bridged.peer.PeerHandle;
+import dev.ltms.bridged.peer.PeerLauncher;
+import dev.ltms.bridged.peer.PeerUnreachableException;
+import dev.ltms.bridged.peer.SpawnRequest;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.security.SecureRandom;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.Function;
+import java.util.function.LongSupplier;
+import java.util.function.Supplier;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Abstract base for {@link PeerLauncher} adapters that materialize a peer as a <em>herdr</em>
+ * agent (a CLI coding agent running in a herdr tab/pane). It owns everything that is the same
+ * regardless of <em>which</em> coding agent runs: tab/pane placement, the CB-306 spawn-readiness
+ * gate, unique naming, CB-117 orphan reap, teardown, {@link #list() listing}, and cwd resolution.
+ *
+ * <p>Two seams are peer-specific and supplied by the concrete adapter:
+ * <ul>
+ *   <li>{@code namePrefix} (constructor arg) — the label prefix ({@code claude}, {@code opencode})
+ *       that drives both unique naming and the orphan-reap pattern, so each adapter reaps only its
+ *       own kind of pane and never another's.</li>
+ *   <li>{@link #buildLaunch(BridgedConfig.Profile)} — the peer-specific env map + argv, including any
+ *       subscription/guard check, MCP mount, and instruction injection. The base never sees how the
+ *       peer is configured; it only places and starts the returned {@link Launch}.</li>
+ * </ul>
+ *
+ * <p>Placement: in the default {@code tab} policy a peer lands in its own tab inside a dedicated
+ * worker space (found-or-created once, then shared), so peers never split or clutter the user's
+ * real work spaces. Teardown removes the peer's pane <em>and</em> its now-empty tab, tolerating an
+ * already-gone peer so a repeated DELETE is harmless.
+ */
+public abstract class HerdrPeerLauncher implements PeerLauncher {
+
+    private static final Logger log = LoggerFactory.getLogger(HerdrPeerLauncher.class);
+
+    /** herdr rejects a duplicate agent {@code name}; we retry a bumped name this many times. */
+    private static final int NAME_RETRIES = 8;
+
+    /**
+     * Retries for {@code agent.start} against a seed pane whose shell has not reached its prompt
+     * yet — {@code tab.create}/{@code pane.split} return as soon as the pane exists, and herdr
+     * refuses to start an agent in a pane that is not "an available shell" ({@code agent_pane_busy}).
+     */
+    private static final int SHELL_READY_RETRIES = 20;
+
+    private final String namePrefix;                       // label prefix: naming + reap scheme
+    private final AgentControl agents;
+    private final WorkspaceControl spaces;
+    private final Map<String, BridgedConfig.Profile> profiles; // profile name → spawn settings
+    private final String defaultProfile;                      // profile a no-arg spawn uses (nullable)
+
+    /** Host env lookup (injectable for tests); adapters read it in {@link #buildLaunch}. */
+    protected final Function<String, String> env;
+
+    private final AtomicLong nameSeq = new AtomicLong(); // per-peer counter (herdr agent names only)
+
+    /**
+     * The {@code fleet.tabLabel} template; a {@code null} supplier or a {@code null}/blank value ⇒
+     * {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}. A profile's own {@code tabLabel} still
+     * overrides it.
+     *
+     * <p>CB-559: a supplier rather than a String, so a config reload renames the <em>next</em> tab
+     * without a restart. Existing tabs keep the label they were given — bridged does not rewrite a
+     * label it already wrote.
+     */
+    private final Supplier<String> tabLabelTemplate;
+
+    /**
+     * Tab numbers, counted per {@code role/profile} pair (CB-557).
+     *
+     * <p>Deliberately not {@link #nameSeq}. That counter is shared by every profile this launcher
+     * serves, because its job is to make herdr <em>agent names</em> unique. Reusing it for the tab
+     * label made the numbers global, so sibling tabs read {@code #4}, {@code #9}, {@code #17} — gaps
+     * that look like a member died. Counting per role+profile makes {@code dev: sonnet #2} mean the
+     * second sonnet dev, which is what a reader assumes it means.
+     *
+     * <p>Resets when the daemon restarts, and that is fine: the label is a human-facing hint, not an
+     * identity. Identity is {@link PeerHandle#id()}.
+     */
+    private final ConcurrentMap<String, AtomicLong> labelSeq = new ConcurrentHashMap<>();
+
+    private final long spawnReadyTimeoutMs; // 0 = disable gate (legacy non-blocking spawn)
+    private final LongSupplier nowMillis; // monotonic clock (injectable for tests)
+    private final Runnable sleeper; // sleep/wait hook (injectable for tests; never real-sleep in unit tests)
+
+    // Per-process token mixed into each peer name so a fresh process (nameSeq back at 0) cannot
+    // collide with same-profile peers that outlived a restart. See startUniquelyNamed.
+    private final String nameNonce = String.format("%06x", new SecureRandom().nextInt(1 << 24));
+
+    // CB-519: PeerHandle.id() is a host-unique opaque UUID, decoupled from the herdr pane id. The
+    // routing/registry key is the UUID; the herdr pane id is a launcher-private placement/teardown
+    // coordinate. This map bridges the two so stop(id) can resolve a host-unique key back to the
+    // exact pane it must tear down. The pane id is launcher-private (never the routing key) — see
+    // PeerHandle.id().
+    private final ConcurrentMap<String, String> paneByAgentId = new ConcurrentHashMap<>();
+    private final AtomicBoolean resetUnsupportedLogged = new AtomicBoolean();
+
+    /**
+     * @param namePrefix          label prefix for this peer kind (drives naming and reap)
+     * @param agents              herdr agent control (start, status, close)
+     * @param spaces              workspace / tab control (ensure, create, close)
+     * @param profiles            configured peer profiles
+     * @param defaultProfile      profile a no-argument spawn uses (nullable)
+     * @param env                 host env lookup (injectable for tests)
+     * @param spawnReadyTimeoutMs max ms to wait for injectable state (0 disables the gate)
+     * @param nowMillis           monotonic clock source (e.g. {@code System::currentTimeMillis})
+     * @param sleeper             sleep/wait hook (never called when the gate is disabled); the poll
+     *                            interval is baked into this hook, so the base needs no poll field
+     */
+    protected HerdrPeerLauncher(String namePrefix, AgentControl agents, WorkspaceControl spaces,
+                                Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                                Function<String, String> env,
+                                long spawnReadyTimeoutMs,
+                                LongSupplier nowMillis, Runnable sleeper) {
+        this(namePrefix, agents, spaces, profiles, defaultProfile, env, spawnReadyTimeoutMs,
+                nowMillis, sleeper, null);
+    }
+
+    /**
+     * As above, plus the {@code fleet.tabLabel} template (CB-557).
+     *
+     * @param tabLabelTemplate fleet-wide tab-label template, read per spawn (CB-559); {@code null},
+     *                         or a supplier yielding {@code null}/blank ⇒
+     *                         {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}. A separate constructor
+     *                         rather than a new parameter on the one above, so every existing call
+     *                         site keeps the default without an edit.
+     */
+    protected HerdrPeerLauncher(String namePrefix, AgentControl agents, WorkspaceControl spaces,
+                                Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                                Function<String, String> env,
+                                long spawnReadyTimeoutMs,
+                                LongSupplier nowMillis, Runnable sleeper,
+                                Supplier<String> tabLabelTemplate) {
+        this.tabLabelTemplate = tabLabelTemplate;
+        this.namePrefix = namePrefix;
+        this.agents = agents;
+        this.spaces = spaces;
+        this.profiles = Map.copyOf(profiles);
+        this.defaultProfile = defaultProfile;
+        this.env = env;
+        this.spawnReadyTimeoutMs = spawnReadyTimeoutMs;
+        this.nowMillis = nowMillis;
+        this.sleeper = sleeper;
+    }
+
+    // --- adapter seams -------------------------------------------------------------------------
+
+    /**
+     * Build the peer-specific launch for {@code cfg}: the environment map and argv handed to herdr.
+     * Any subscription/guard check, MCP mount, and instruction injection happen here. The env map
+     * and argv are adapter-private; the base only places and starts what is returned.
+     */
+    protected abstract Launch buildLaunch(BridgedConfig.Profile cfg);
+
+    /**
+     * Session-aware variant of {@link #buildLaunch(BridgedConfig.Profile)} (CB-547a). Default
+     * discards the session identity and delegates to the profile-only form, so an adapter that
+     * carries no durable peer session (opencode, say) inherits byte-identical behaviour and needs
+     * no change. An adapter that does (Claude Code) overrides this to mint/resume the id and to
+     * surface it on the returned {@link Launch#agentSessionId()}.
+     *
+     * @param cfg               the resolved profile to spawn
+     * @param sessionName       the bridge's logical session name, or null/blank for launcher-derived
+     * @param resumeSessionId   the peer's own prior session id to resume, or null/blank for fresh
+     */
+    protected Launch buildLaunch(BridgedConfig.Profile cfg, String sessionName, String resumeSessionId) {
+        return buildLaunch(cfg);
+    }
+
+    /** Direct transport access for peer-specific, non-turn control operations. */
+    protected final AgentControl agents() {
+        return agents;
+    }
+
+    /** Resolve the public peer id to the launcher's private herdr target. */
+    protected final String agentTarget(String id) {
+        return paneByAgentId.get(id);
+    }
+
+    @Override
+    public boolean clearContext(String id) {
+        if (resetUnsupportedLogged.compareAndSet(false, true)) {
+            log.warn("context reset is unsupported for peer kind {}; clearAfterTurn is a no-op",
+                    namePrefix);
+        }
+        return false;
+    }
+
+    /**
+     * A peer-specific launch: the herdr {@code env} map and {@code argv}, plus — for an adapter
+     * that carries durable session identity (CB-547a) — the peer's OWN session id
+     * ({@link PeerHandle#agentSessionId()}), known before the peer has written anything. Null for
+     * a launch that carries no identity.
+     */
+    protected record Launch(Map<String, String> env, List<String> argv, String agentSessionId) {
+
+        /** A launch without a discoverable agent session id (an adapter that carries none). */
+        Launch(Map<String, String> env, List<String> argv) {
+            this(env, argv, null);
+        }
+    }
+
+    // --- profile surface -----------------------------------------------------------------------
+
+    /** The configured peer profile names (what {@code spawn(profile)} accepts). */
+    @Override
+    public Set<String> profiles() {
+        return profiles.keySet();
+    }
+
+    /** The parity-overlay file list for {@code profileName} (default list when unset). */
+    @Override
+    public List<String> parityOverlay(String profileName) {
+        String name = (profileName == null || profileName.isBlank()) ? defaultProfile : profileName;
+        if (name == null || name.isBlank()) {
+            return List.of();
+        }
+        BridgedConfig.Profile cfg = profiles.get(name);
+        return cfg == null ? List.of() : cfg.parityOverlay();
+    }
+
+    /** The profile a no-argument spawn uses, or {@code null} if none is configured. */
+    @Override
+    public String defaultProfile() {
+        return defaultProfile;
+    }
+
+    /** The configured profiles, for adapter capability decisions (e.g. any git-token grant). */
+    protected Collection<BridgedConfig.Profile> profileConfigs() {
+        return profiles.values();
+    }
+
+    /** Resolve {@code profileName} (null/blank → default) to its config, or throw with the options. */
+    protected BridgedConfig.Profile requireProfile(String profileName) {
+        String name = (profileName == null || profileName.isBlank()) ? defaultProfile : profileName;
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("no default worker profile is configured — "
+                    + "pass a profile; configured: " + profiles.keySet());
+        }
+        BridgedConfig.Profile cfg = profiles.get(name);
+        if (cfg == null) {
+            throw new IllegalArgumentException("unknown worker profile '" + name
+                    + "' — configured: " + profiles.keySet());
+        }
+        return cfg;
+    }
+
+    // --- spawn ---------------------------------------------------------------------------------
+
+    /** A started peer plus the launch's agent-session id (the resume handle, or null). */
+    private record Spawned(Agent agent, String agentSessionId) {
+    }
+
+    /**
+     * Spawn a peer. {@code profileName} null/blank → the default profile. The working directory
+     * (CB-112) is resolved by {@link #resolveCwd}: an explicit {@code requestedCwd}, else the
+     * profile's configured {@code cwd}, else {@code callerCwd} (the primary's cwd, when the spawn
+     * came from the primary over MCP), else the daemon's cwd — never assumed to be {@code $HOME}.
+     * The adapter's {@link #buildLaunch} runs before any herdr call.
+     */
+    protected Agent spawnInternal(String profileName, String requestedCwd, String callerCwd) {
+        return spawnInternal(profileName, requestedCwd, callerCwd, null, null).agent();
+    }
+
+    /** Pre-CB-557 shape: no explicit role, so the tab is labelled as a {@code dev}. */
+    protected Spawned spawnInternal(String profileName, String requestedCwd, String callerCwd,
+                                    String sessionName, String resumeSessionId) {
+        return spawnInternal(profileName, requestedCwd, callerCwd, sessionName, resumeSessionId,
+                MemberRole.DEV);
+    }
+
+    /**
+     * Spawn a peer with session identity (CB-547a). {@code sessionName} and {@code resumeSessionId}
+     * are threaded from the {@link SpawnRequest} into {@link #buildLaunch(BridgedConfig.Profile,
+     * String, String)}, and the launch's resolved agent-session id is returned alongside the agent
+     * so the caller can put it on the {@link PeerHandle}.
+     */
+    protected Spawned spawnInternal(String profileName, String requestedCwd, String callerCwd,
+                                    String sessionName, String resumeSessionId, MemberRole role) {
+        BridgedConfig.Profile cfg = requireProfile(profileName);
+        Launch launch = buildLaunch(cfg, sessionName, resumeSessionId);
+        String cwd = resolveCwd(requestedCwd, cfg, callerCwd);
+        Agent agent = cfg.tabPlacement()
+                ? spawnInTab(cfg, launch.env(), launch.argv(), cwd, role)
+                : spawnAsPane(cfg, launch.env(), launch.argv(), cwd);
+        return new Spawned(agent, launch.agentSessionId());
+    }
+
+    /**
+     * The next tab number for {@code role} on {@code profile}, starting at 1.
+     *
+     * <p>Starts at 1 rather than 0 because the number is read by a person: {@code "dev: sonnet #1"}
+     * is the first one, and {@code #0} invites the question of where {@code #1} went.
+     */
+    private long nextLabelSeq(MemberRole role, String profile) {
+        String key = (role == null ? "" : role.wireName()) + "/" + profile;
+        return labelSeq.computeIfAbsent(key, _ -> new AtomicLong()).incrementAndGet();
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Delegates to {@link #spawnInternal} and wraps the resulting herdr {@link Agent} in a
+     * {@link WorkerHandle} whose {@link PeerHandle#id()} is a fresh <em>host-unique</em> opaque
+     * UUID (CB-519), deliberately decoupled from the herdr pane id: the id is the registry/routing
+     * key and must never collide across daemon processes on the same host, while the herdr pane id
+     * stays a launcher-private placement/teardown coordinate, remembered here so {@link #stop}
+     * can resolve the host-unique key back to its pane. When {@code spawnReadyTimeoutMs > 0},
+     * blocks until the peer's herdr status is injectable or the timeout elapses; on timeout the
+     * pane is closed (no orphan) and a {@link PeerUnreachableException} is thrown.
+     */
+    @Override
+    public PeerHandle spawn(SpawnRequest req) {
+        Spawned spawned = spawnInternal(req.profileName(), req.requestedCwd(), req.callerCwd(),
+                req.sessionName(), req.resumeSessionId(), req.role());
+        Agent agent = spawned.agent();
+        String paneId = agent.paneId();
+        if (spawnReadyTimeoutMs > 0) {
+            waitUntilInjectableOrThrow(paneId);
+        }
+        // CB-519: the handle id is a host-unique UUID; the herdr pane it maps to stays internal.
+        String id = UUID.randomUUID().toString();
+        paneByAgentId.put(id, paneId);
+        return new WorkerHandle(id, agent.terminalId(), requireProfile(req.profileName()).profile(),
+                req.sessionName(), spawned.agentSessionId());
+    }
+
+    @Override
+    public String effectiveCwd(SpawnRequest req) {
+        return effectiveCwd(req.profileName(), req.requestedCwd(), req.callerCwd());
+    }
+
+    /**
+     * CB-301: the effective working directory a spawn for {@code profileName} would use, without
+     * actually spawning.
+     */
+    private String effectiveCwd(String profileName, String requestedCwd, String callerCwd) {
+        return resolveCwd(requestedCwd, requireProfile(profileName), callerCwd);
+    }
+
+    /**
+     * CB-112 cwd resolution: spawn arg → profile config → the primary's cwd → the daemon's cwd.
+     * Never returns {@code null}/blank: {@code "."} (the daemon's own working directory) is the
+     * guaranteed last resort so a pathological environment with an unset {@code user.dir} still
+     * honours the "never assume {@code $HOME}" contract rather than letting herdr default the pane.
+     */
+    private static String resolveCwd(String requestedCwd, BridgedConfig.Profile cfg, String callerCwd) {
+        return firstNonBlank(requestedCwd, cfg.cwd(), callerCwd, System.getProperty("user.dir"), ".");
+    }
+
+    private static String firstNonBlank(String... values) {
+        for (String v : values) {
+            if (v != null && !v.isBlank()) return v;
+        }
+        return null;
+    }
+
+    /** Dedicated worker space → own tab (carrying cwd+env) → start the peer into the seed pane. */
+    private Agent spawnInTab(BridgedConfig.Profile cfg, Map<String, String> workerEnv,
+                             List<String> argv, String cwd, MemberRole role) {
+        Workspace space = spaces.ensureWorkspace(cfg.workspace());
+        Tab.Created tab = spaces.createTab(space.workspaceId(), cwd, workerEnv);
+        log.info("spawning {} profile={} space={} tab={} cwd={}",
+                namePrefix, cfg.profile(), space.workspaceId(), tab.tab().tabId(), cwd);
+
+        Started started;
+        try {
+            if (tab.rootPaneId() == null) {
+                // Protocol 19 starts the agent INTO the seed pane — without one there is nowhere
+                // to start, and a partial tab would be left behind.
+                throw new IllegalStateException("tab " + tab.tab().tabId()
+                        + " had no seed pane in the create response — cannot start a peer in it");
+            }
+            started = startUniquelyNamed(cfg, argv, tab.rootPaneId());
+        } catch (RuntimeException e) {
+            // The peer never started — don't leave the tab we just created orphaned.
+            // Best-effort cleanup; never let it mask the real spawn failure.
+            try {
+                spaces.closeTab(tab.tab().tabId());
+            } catch (RuntimeException cleanup) {
+                log.warn("failed to close orphaned tab {} after spawn error: {}",
+                        tab.tab().tabId(), cleanup.getMessage());
+            }
+            throw e;
+        }
+
+        // The peer is LIVE now, in the seed pane itself (no shell pane to drop — protocol 19).
+        // Labelling is cosmetic: it must not fail the spawn or orphan the running peer — on error
+        // we log and still return it so the caller gets its paneId and can tear it down.
+        tidy("label tab " + tab.tab().tabId(),
+                () -> spaces.renameTab(tab.tab().tabId(),
+                        cfg.renderTabLabel(
+                                tabLabelTemplate == null ? null : tabLabelTemplate.get(),
+                                role, nextLabelSeq(role, cfg.profile()))));
+        log.info("{} started pane={} tab={} terminal={}",
+                namePrefix, started.agent().paneId(), started.agent().tabId(), started.agent().terminalId());
+        return started.agent();
+    }
+
+    /** Run a best-effort post-start cleanup step, logging (not throwing) on failure. */
+    private void tidy(String what, Runnable step) {
+        try {
+            step.run();
+        } catch (RuntimeException e) {
+            log.warn("post-start step failed ({}) — peer is running regardless: {}", what, e.getMessage());
+        }
+    }
+
+    /** Legacy placement: split the currently-focused tab; the peer still starts in {@code cwd}. */
+    private Agent spawnAsPane(BridgedConfig.Profile cfg, Map<String, String> workerEnv,
+                              List<String> argv, String cwd) {
+        log.info("spawning {} (pane placement) profile={} cwd={} argv={}",
+                namePrefix, cfg.profile(), cwd, argv);
+        String paneId = spaces.splitPane(cwd, workerEnv);
+        if (paneId == null) {
+            throw new IllegalStateException("pane.split returned no pane — cannot start a peer");
+        }
+        Agent peer = startUniquelyNamed(cfg, argv, paneId).agent();
+        log.info("{} started pane={} terminal={}", namePrefix, peer.paneId(), peer.terminalId());
+        return peer;
+    }
+
+    /** A started peer together with the sequence its unique name/label used. */
+    private record Started(Agent agent, long seq) {
+    }
+
+    /**
+     * Start the peer under a unique herdr agent name. herdr requires each running agent's
+     * {@code name} to be distinct (a 2nd identical {@code name} fails {@code agent_name_taken}) —
+     * the exact case that makes multiple peers useful. The name is
+     * {@code <prefix>-<profile>-<nonce>-<seq>}: {@code seq} distinguishes peers within this process,
+     * and the per-process {@code nonce} keeps a fresh process (whose {@code seq} restarts at 0) from
+     * colliding with same-profile peers that outlived a restart. The retry is a belt-and-braces
+     * backstop for the astronomically unlikely nonce+seq clash; the name is a label only — herdr
+     * detects kind and status from terminal output, not from it.
+     */
+    private Started startUniquelyNamed(BridgedConfig.Profile cfg, List<String> argv, String paneId) {
+        // Protocol 19 resolves the executable from the agent kind (== namePrefix here), so
+        // argv[0] — the configured executable — is dropped and only the extra args are passed.
+        List<String> args = argv.isEmpty() ? argv : argv.subList(1, argv.size());
+        HerdrException last = null;
+        for (int attempt = 0; attempt < NAME_RETRIES; attempt++) {
+            long seq = nameSeq.incrementAndGet();
+            String name = namePrefix + "-" + cfg.profile() + "-" + nameNonce + "-" + seq;
+            try {
+                return new Started(startAwaitingShellPrompt(name, args, paneId), seq);
+            } catch (HerdrException e) {
+                if (!"agent_name_taken".equals(e.code())) throw e;
+                log.debug("peer name '{}' taken, retrying", name);
+                last = e;
+            }
+        }
+        throw last;
+    }
+
+    /** Start the agent into {@code paneId}, waiting out the seed shell's boot with the sleeper. */
+    private Agent startAwaitingShellPrompt(String name, List<String> args, String paneId) {
+        HerdrException busy = null;
+        for (int attempt = 0; attempt < SHELL_READY_RETRIES; attempt++) {
+            try {
+                return agents.start(name, namePrefix, args, paneId);
+            } catch (HerdrException e) {
+                if (!"agent_pane_busy".equals(e.code())) throw e;
+                log.debug("pane {} not at its shell prompt yet, retrying agent.start", paneId);
+                busy = e;
+                sleeper.run();
+            }
+        }
+        throw busy;
+    }
+
+    // --- discovery + reap ----------------------------------------------------------------------
+
+    /** All herdr-tracked agents — discovery for "what peers exist". */
+    @Override
+    public List<Agent> list() {
+        return agents.list();
+    }
+
+    /**
+     * Reap peer panes left behind by an earlier daemon process (CB-117). herdr keeps a peer's pane
+     * alive across a daemon restart <em>by design</em>, and that pane's id is held only by its
+     * spawner — so a peer whose owning process exited before issuing the matching teardown leaks
+     * with nothing tracking it. On boot we scan herdr for agents whose name matches our
+     * {@code <prefix>-<profile>-<nonce>-<seq>} scheme with a nonce <em>other</em> than this
+     * process's {@link #nameNonce}, and tear each one down (its pane and, via {@link #stop}, its
+     * now-empty dedicated tab). A current-nonce peer is ours and live, so it is left running; a
+     * user's own session carries no such name and is never touched. A peer from a <em>different</em>
+     * adapter (different prefix) is likewise never touched. Best-effort: a failed listing, or a
+     * failure to stop any one peer, is logged and never aborts startup.
+     *
+     * @return the number of orphaned peers reaped
+     */
+    @Override
+    public int reapOrphanWorkers() {
+        List<Agent> all;
+        try {
+            all = agents.list();
+        } catch (RuntimeException e) {
+            log.warn("orphan-peer reap skipped — agent.list failed: {}", e.getMessage());
+            return 0;
+        }
+        int reaped = 0;
+        for (Agent a : all) {
+            if (!isForeignWorker(namePrefix, a.name(), nameNonce)) continue;
+            try {
+                stop(a.paneId());
+                reaped++;
+                log.info("reaped orphan {} {} (pane={} tab={}) left by a prior daemon",
+                        namePrefix, a.name(), a.paneId(), a.tabId());
+            } catch (RuntimeException e) {
+                log.warn("could not reap orphan {} {} (pane={}): {}",
+                        namePrefix, a.name(), a.paneId(), e.getMessage());
+            }
+        }
+        if (reaped > 0) {
+            log.info("orphan-peer reap complete — {} stale {} peer(s) removed at startup", reaped, namePrefix);
+        }
+        return reaped;
+    }
+
+    /** The {@code <prefix>-<profile>-<nonce>-<seq>} name pattern; group 1 captures the 6-hex nonce. */
+    static Pattern workerNamePattern(String prefix) {
+        return Pattern.compile(prefix + "-.*-([0-9a-f]{6})-\\d+");
+    }
+
+    /**
+     * Whether {@code name} is a peer of kind {@code prefix} started by a <em>different</em> process
+     * than {@code currentNonce} — the reap predicate (CB-117). True only for the prefix's naming
+     * scheme with a foreign nonce: a non-peer name, a different adapter's name, or our own live
+     * nonce is excluded. Pure and package-private so the decision is unit-testable without herdr.
+     */
+    static boolean isForeignWorker(String prefix, String name, String currentNonce) {
+        String nonce = workerNonce(prefix, name);
+        return nonce != null && !nonce.equals(currentNonce);
+    }
+
+    /** The 6-hex nonce embedded in a {@code prefix} peer name, or {@code null} if not one. */
+    static String workerNonce(String prefix, String name) {
+        if (name == null) return null;
+        Matcher m = workerNamePattern(prefix).matcher(name);
+        return m.matches() ? m.group(1) : null;
+    }
+
+    /** This process's peer-name nonce (a label component only; exposed for reaper tests). */
+    String nameNonce() {
+        return nameNonce;
+    }
+
+    // --- teardown ------------------------------------------------------------------------------
+
+    /**
+     * Tear a peer down: close the pane, and close its tab <em>only</em> when the peer is that tab's
+     * sole occupant. The single-pane check is what makes this safe regardless of how the peer was
+     * placed (or a placement-config change across a restart): a pane-placement peer sitting in one
+     * of the user's shared tabs has siblings, so its tab is never closed — we only ever remove a
+     * tab we created to hold one peer.
+     *
+     * <p>{@code idOrPane} is the {@link PeerHandle#id()} of a peer this launcher spawned (CB-519's
+     * host-unique opaque UUID), resolved through {@link #paneByAgentId} to the pane it must tear
+     * down. An argument that is not one of our ids is treated as a raw herdr pane id — the
+     * {@link #reapOrphanWorkers() orphan-reap} and spawn-gate-timeout paths, plus any caller that
+     * passes a pane directly, keep working without an owning id.
+     *
+     * <p>Resolves the tab from the pane <em>before</em> closing it. An already-gone pane/tab
+     * (repeated DELETE, crashed peer) is treated as success; any other failure propagates so a
+     * genuinely failed teardown is not reported as done.
+     */
+    @Override
+    public void stop(String idOrPane) {
+        // Teardown knows only the pane, not which profile spawned it. Attempt tab cleanup when any
+        // profile uses tab placement (so the bridge may have created a dedicated peer tab); the
+        // single-occupant check below is what actually protects the user's shared tabs.
+        String paneId = paneByAgentId.remove(idOrPane);
+        if (paneId == null) {
+            paneId = idOrPane; // raw-pane fallback (reap, gate timeout, pane-addressed callers)
+        }
+        WorkspaceControl.PaneLocation loc = usesTabPlacement() ? spaces.locatePane(paneId) : null;
+        try {
+            agents.close(paneId);
+        } catch (HerdrException e) {
+            if (!isAlreadyGone(e)) throw e;
+            log.debug("pane.close({}) ignored — already gone: {}", paneId, e.getMessage());
+        }
+        if (loc != null && loc.tabPaneCount() == 1) {
+            spaces.closeTab(loc.tabId());
+        } else if (loc != null) {
+            log.debug("not closing tab {} — it holds {} panes (not a dedicated peer tab)",
+                    loc.tabId(), loc.tabPaneCount());
+        }
+    }
+
+    /** Whether any configured profile places peers in their own tab (so tabs may need cleanup). */
+    private boolean usesTabPlacement() {
+        return profiles.values().stream().anyMatch(BridgedConfig.Profile::tabPlacement);
+    }
+
+    /** True when a herdr error means the target is already gone (safe to treat as done). */
+    private static boolean isAlreadyGone(HerdrException e) {
+        return e.code() != null && e.code().endsWith("_not_found");
+    }
+
+    // --- spawn-readiness gate (CB-306) ---------------------------------------------------------
+
+    /**
+     * Poll {@link AgentControl#status} until the pane reports an injectable state or the configured
+     * timeout elapses. On timeout, close the pane (self-reap) and throw.
+     */
+    private void waitUntilInjectableOrThrow(String paneId) {
+        long deadline = nowMillis.getAsLong() + spawnReadyTimeoutMs;
+        while (nowMillis.getAsLong() < deadline) {
+            if (agents.status(paneId).injectable()) {
+                log.debug("peer pane={} reached injectable state", paneId);
+                return;
+            }
+            sleeper.run();
+        }
+        log.warn("peer pane={} did not become injectable within {}ms — closing", paneId, spawnReadyTimeoutMs);
+        stop(paneId);
+        throw new PeerUnreachableException(
+                "worker pane " + paneId + " did not reach injectable state within "
+                        + spawnReadyTimeoutMs + "ms");
+    }
+
+    /**
+     * A concrete {@link PeerHandle} wrapping herdr agent coordinates, the profile that spawned it,
+     * and the session identity the launch resolved (CB-547a): the bridge's logical name and the
+     * peer's own session id, both null when the spawn carried no identity.
+     */
+    private record WorkerHandle(String id, String terminalId, String profile,
+                                String sessionName, String agentSessionId) implements PeerHandle {
+    }
+
+    // --- shared helpers ------------------------------------------------------------------------
+
+    /** Put {@code k → v} only when {@code v} is present (non-null, non-blank). */
+    protected static void putIfPresent(Map<String, String> m, String k, String v) {
+        if (v != null && !v.isBlank()) {
+            m.put(k, v);
+        }
+    }
+
+    /** Host env lookup that tolerates an unconfigured (null/blank) var name — returns null then. */
+    protected String resolveEnv(String name) {
+        return (name == null || name.isBlank()) ? null : env.apply(name);
+    }
+
+    /**
+     * The parity-neutral git-forge token grant (CB-302): when {@code cfg} opts in via
+     * {@code gitTokenEnv} and the token resolves, inject {@code GITEA_TOKEN} plus its paired
+     * {@code GITEA_HOST}. Push over SSH is unaffected; the only incremental grant is PR-create.
+     * Peer-neutral, so every herdr adapter reuses it unchanged.
+     */
+    protected void applyGitToken(Map<String, String> workerEnv, BridgedConfig.Profile cfg) {
+        if (!cfg.hasGitToken()) {
+            return;
+        }
+        String gitToken = resolveEnv(cfg.gitTokenEnv());
+        if (gitToken != null) {
+            workerEnv.put("GITEA_TOKEN", gitToken);
+            putIfPresent(workerEnv, "GITEA_HOST", resolveEnv(cfg.gitHostEnv()));
+        }
+    }
+
+    /** A fresh mutable env map — the conventional starting point for {@link #buildLaunch}. */
+    /**
+     * Seed a worker's environment (CB-511): the daemon's own {@code PATH}, then the profile's
+     * {@code env:} entries.
+     *
+     * <p>Why this exists: bridged passes herdr an explicit env map, and herdr merges it into
+     * <em>its own</em> process environment. So before this, a worker inherited whatever PATH the
+     * herdr server happened to be started with — on this host, one from weeks earlier with no JDK
+     * and no Maven, which left workers unable to run the build they were being asked to run. The
+     * worker's toolchain must follow from configuration, not from how a long-lived daemon was
+     * launched.
+     *
+     * <p>Adapter-specific variables are layered on top of this by {@code buildLaunch} and therefore
+     * win. That ordering is deliberate and load-bearing: it stops a profile's {@code env:} from
+     * overriding {@code ANTHROPIC_BASE_URL} and slipping past {@link
+     * dev.ltms.bridged.guard.SubscriptionGuard}, which is checked against the profile's
+     * {@code baseUrl} and nothing else.
+     */
+    protected Map<String, String> baseEnv(BridgedConfig.Profile cfg) {
+        Map<String, String> workerEnv = new LinkedHashMap<>();
+        String path = env.apply("PATH");
+        if (path != null && !path.isBlank()) {
+            workerEnv.put("PATH", path);
+        }
+        if (cfg != null && cfg.env() != null) {
+            workerEnv.putAll(cfg.env());
+        }
+        return workerEnv;
+    }
+
+    /** Defensive copy of {@code argv} plus room to append launch flags. */
+    protected static List<String> mutableArgv(List<String> argv) {
+        return new ArrayList<>(argv);
+    }
+
+    /**
+     * Uninterruptible sleep — the production {@link #sleeper}. Tests supply their own no-op /
+     * fast-faking sleeper so they never real-sleep.
+     */
+    protected static void sleepUninterruptibly(long ms) {
+        try {
+            Thread.sleep(ms);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            // preserve the interrupt flag but continue — poll loops should not be aborted by an
+            // interrupt that was not meant for them.
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/member/OpenCodeLauncher.java

@@ -0,0 +1,507 @@
+package dev.ltms.bridged.member;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.WorkspaceControl;
+import dev.ltms.bridged.peer.Capability;
+import dev.ltms.bridged.peer.PeerHandle;
+import dev.ltms.bridged.peer.SpawnRequest;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Function;
+import java.util.function.LongSupplier;
+import java.util.function.Supplier;
+
+/**
+ * The {@link HerdrPeerLauncher} adapter for <strong>opencode</strong> — an open-source,
+ * provider-agnostic terminal coding agent. Its whole reason for existing is to prove the
+ * {@code PeerLauncher} SPI is genuinely provider-neutral: opencode shares none of Claude Code's
+ * private launch seams, yet reuses every line of shared transport in the base (tab/pane placement,
+ * the CB-306 readiness gate, unique naming + CB-117 reap, teardown, listing, cwd).
+ *
+ * <p>The divergences from {@link ClaudeCodeLauncher}, all confined to {@link #buildLaunch}:
+ * <ul>
+ *   <li><strong>No subscription boundary.</strong> opencode carries no {@code ANTHROPIC_BASE_URL}
+ *       and there is no {@link dev.ltms.bridged.guard.SubscriptionGuard} — the guard is a
+ *       Claude-private concern, not part of the SPI. opencode reads the operator's own provider
+ *       credentials from its global {@code auth.json}; the bridge injects none.</li>
+ *   <li><strong>File-based MCP mount + instructions.</strong> opencode has no inline
+ *       {@code --mcp-config}/{@code --append-system-prompt}. Instead the bridge writes an ephemeral
+ *       {@code opencode.json} that declares the bridge as a {@code remote} MCP server and lists a
+ *       reply-charter file under {@code instructions}, then points the worker at it with
+ *       {@code OPENCODE_CONFIG}. This is the one place the launcher touches disk — Claude never did.</li>
+ *   <li><strong>Model as a flag.</strong> the {@code provider/model} selector is passed as
+ *       {@code -m}, not an env var.</li>
+ *   <li><strong>{@code opencode} name prefix</strong> so reap matches {@code opencode-*} panes and
+ *       never another adapter's.</li>
+ * </ul>
+ */
+public final class OpenCodeLauncher extends HerdrPeerLauncher {
+
+    /** Label prefix for this adapter's herdr agent names (drives naming + orphan reap). */
+    private static final String NAME_PREFIX = "opencode";
+
+    /** Writer for the generated {@code opencode.json}. */
+    private static final ObjectMapper JSON = new ObjectMapper();
+
+    /**
+     * Standing instruction written to the charter file and mounted via the config's
+     * {@code instructions} so the worker returns its result through {@code bridge_reply}. Kept on
+     * disk (not a launch flag) because opencode's {@code instructions} takes file paths, not inline
+     * text — the file is regenerated per spawn and never touches the worker's own profile.
+     */
+    static final String REPLY_CHARTER =
+            "You are an off-subscription worker in the claude-bridge fleet, running under opencode. "
+            + "Every message you receive arrives through the bridge, and the ONLY channel back to the "
+            + "sender is the bridge_reply MCP tool. Text you write in your terminal is NOT sent "
+            + "anywhere — the sender cannot see your screen, so an in-terminal answer is silently "
+            + "discarded. Therefore you MUST end EVERY turn by calling bridge_reply with `content` set "
+            + "to your complete response. This holds for every message without exception — tasks, "
+            + "questions, clarifications, acknowledgements, and ordinary back-and-forth conversation. "
+            + "Call bridge_reply exactly once, as the final action of your turn, with your full answer "
+            + "in `content`; never wait for confirmation first. If you end a turn without calling "
+            + "bridge_reply, the sender receives nothing and the exchange stalls.";
+
+    /** Root under which per-spawn opencode config dirs are created (injectable for tests). */
+    private final Path configRoot;
+
+    /**
+     * The current spawn's resume-target session id, threaded from {@link #spawn(SpawnRequest)} to
+     * {@link #buildLaunch} across the base's {@code spawn -> spawnInternal -> buildLaunch} chain,
+     * which carries no request. A plain field would race under concurrent spawns (the base supports
+     * them), so it is thread-local: each spawn captures its own request's id on its own thread, and
+     * {@code buildLaunch}, synchronous and same-thread, reads exactly that one. Set only around the
+     * {@code super.spawn} call and cleared in {@code finally}, so a paused/leftover value can never
+     * bleed into the next spawn.
+     */
+    private final ThreadLocal<String> resumeSessionId = new ThreadLocal<>();
+
+    /**
+     * Session discovery against opencode's on-disk storage ({@link OpenCodeSessionDiscovery}) —
+     * the one seam that knows opencode's private session-file layout. Its root is injectable for
+     * tests so they never touch the operator's real {@code ~/.local/share/opencode}.
+     */
+    private final OpenCodeSessionDiscovery discovery;
+
+    /**
+     * Production constructor — disables the spawn-ready gate ({@code spawnReadyTimeoutMs == 0}) so it
+     * matches the legacy non-blocking spawn semantics. Config dirs are created under the JVM temp dir.
+     */
+    public OpenCodeLauncher(AgentControl agents, WorkspaceControl spaces,
+                            Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                            Function<String, String> env) {
+        this(agents, spaces, profiles, defaultProfile, env, 0,
+                System::currentTimeMillis, () -> sleepUninterruptibly(300),
+                defaultConfigRoot(), defaultDiscoveryRoot());
+    }
+
+    /**
+     * Production constructor with the spawn-ready gate enabled. Polls {@code agents.status()} until
+     * the pane reports an injectable state or {@code spawnReadyTimeoutMs} elapses.
+     */
+    public OpenCodeLauncher(AgentControl agents, WorkspaceControl spaces,
+                            Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                            Function<String, String> env,
+                            long spawnReadyTimeoutMs, long spawnReadyPollMs) {
+        this(agents, spaces, profiles, defaultProfile, env,
+                spawnReadyTimeoutMs, spawnReadyPollMs, null);
+    }
+
+    /**
+     * Production constructor carrying the fleet-wide tab-label template (CB-557). The template comes
+     * from {@code fleet.tabLabel}, which a profile cannot know because it names the member's
+     * <em>role</em>; a profile may still override it with its own {@code tabLabel}.
+     */
+    public OpenCodeLauncher(AgentControl agents, WorkspaceControl spaces,
+                            Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                            Function<String, String> env,
+                            long spawnReadyTimeoutMs, long spawnReadyPollMs,
+                            Supplier<String> tabLabelTemplate) {
+        this(agents, spaces, profiles, defaultProfile, env, spawnReadyTimeoutMs,
+                System::currentTimeMillis, () -> sleepUninterruptibly(spawnReadyPollMs),
+                defaultConfigRoot(), defaultDiscoveryRoot(), tabLabelTemplate);
+    }
+
+    /**
+     * Full testability constructor. Every injectable collaborator is explicit so unit tests supply a
+     * fake clock ({@code nowMillis}), poll-loop wait ({@code sleeper}), and a temp {@code configRoot}
+     * they can inspect the generated {@code opencode.json}/charter under.
+     *
+     * @param agents              herdr agent control (start, status, close)
+     * @param spaces              workspace / tab control (ensure, create, close)
+     * @param profiles            configured worker profiles
+     * @param defaultProfile      profile a no-argument spawn uses (nullable)
+     * @param env                 host env lookup (injectable for tests)
+     * @param spawnReadyTimeoutMs max ms to wait for injectable state (0 disables the gate)
+     * @param nowMillis           monotonic clock source (e.g. {@code System::currentTimeMillis})
+     * @param sleeper             sleep/wait hook (encodes the poll interval; never called when the
+     *                            gate is disabled)
+     * @param configRoot          existing directory under which per-spawn config dirs are created
+     * @param discoveryRoot       opencode's on-disk storage root to scan for session records
+     *                            (injectable for tests; opencode's layout is matched at
+     *                            {@link OpenCodeSessionDiscovery})
+     */
+    public OpenCodeLauncher(AgentControl agents, WorkspaceControl spaces,
+                            Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                            Function<String, String> env,
+                            long spawnReadyTimeoutMs,
+                            LongSupplier nowMillis, Runnable sleeper,
+                            Path configRoot, Path discoveryRoot) {
+        this(agents, spaces, profiles, defaultProfile, env, spawnReadyTimeoutMs,
+                nowMillis, sleeper, configRoot, discoveryRoot, null);
+    }
+
+    /**
+     * Full testability constructor, plus the fleet-wide tab-label template (CB-557).
+     *
+     * @param tabLabelTemplate {@code fleet.tabLabel}; {@code null}/blank ⇒
+     *                         {@link BridgedConfig.Fleet#DEFAULT_TAB_LABEL}
+     */
+    public OpenCodeLauncher(AgentControl agents, WorkspaceControl spaces,
+                            Map<String, BridgedConfig.Profile> profiles, String defaultProfile,
+                            Function<String, String> env,
+                            long spawnReadyTimeoutMs,
+                            LongSupplier nowMillis, Runnable sleeper,
+                            Path configRoot, Path discoveryRoot,
+                            Supplier<String> tabLabelTemplate) {
+        super(NAME_PREFIX, agents, spaces, profiles, defaultProfile, env,
+                spawnReadyTimeoutMs, nowMillis, sleeper, tabLabelTemplate);
+        this.configRoot = configRoot;
+        this.discovery = new OpenCodeSessionDiscovery(discoveryRoot);
+    }
+
+    private static Path defaultConfigRoot() {
+        return Path.of(System.getProperty("java.io.tmpdir"));
+    }
+
+    /** The default opencode storage root: {@code ~/.local/share/opencode} (the XDG data dir). */
+    private static Path defaultDiscoveryRoot() {
+        return Path.of(System.getProperty("user.home"), ".local", "share", "opencode");
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Builds the opencode launch: no {@code ANTHROPIC_*} and no guard (opencode reads its own
+     * provider credentials); when the profile mounts the bridge MCP, generate an ephemeral
+     * {@code opencode.json} (remote MCP server + reply-charter instructions) and point the worker at
+     * it via {@code OPENCODE_CONFIG}; carry the parity-neutral git-forge grant; and select the model
+     * with {@code -m}.
+     */
+    @Override
+    protected Launch buildLaunch(BridgedConfig.Profile cfg) {
+        Map<String, String> workerEnv = baseEnv(cfg);
+        // A config file is needed for the bridge MCP mount, for a pinned endpoint (CB-508), or both.
+        if (cfg.hasMcp() || hasCustomProvider(cfg)) {
+            workerEnv.put("OPENCODE_CONFIG", writeConfig(cfg).toString());
+        }
+        applyGitToken(workerEnv, cfg);
+        return new Launch(workerEnv, argvWithResume(argvWithModel(argvWithAuto(cfg), cfg)));
+    }
+
+    /**
+     * True when this profile pins its own OpenAI-compatible endpoint (CB-508) rather than using
+     * whatever provider opencode resolves by default.
+     *
+     * <p>Note this reuses {@code baseUrl}, the same field the Claude adapter injects as
+     * {@code ANTHROPIC_BASE_URL} — but it does <em>not</em> go through {@code SubscriptionGuard}.
+     * That asymmetry is deliberate and safe: the guard exists to stop a worker borrowing the
+     * primary's Anthropic subscription, and an opencode process has no Anthropic credential path
+     * at all. Pointing it at a local vLLM cannot leak the subscription.
+     */
+    private static boolean hasCustomProvider(BridgedConfig.Profile cfg) {
+        return cfg.baseUrl() != null && !cfg.baseUrl().isBlank();
+    }
+
+    /**
+     * The launch argv plus the unconditional {@code --auto} flag, which auto-approves the
+     * permissions opencode does not explicitly deny. It is unconditional, not a preference: a
+     * spawned peer has no human at its pane — the bridge spawned it — so one that stops at an
+     * approval prompt is a wedged agent, indistinguishable from a legitimate mid-turn wait and
+     * unable to end its turn with {@code bridge_reply}. opencode's own help calls this
+     * "dangerous!", but the blast radius here is already bounded by design: a worker runs in its
+     * own git worktree on its own branch, is off-subscription, and cannot merge — the lead is the
+     * gate.
+     */
+    private List<String> argvWithAuto(BridgedConfig.Profile cfg) {
+        List<String> argv = mutableArgv(cfg.argv());
+        argv.add("--auto");
+        return argv;
+    }
+
+    /**
+     * The launch argv plus, on a resumed spawn, opencode's {@code -s <id>} flag to continue a prior
+     * conversation by its session id. {@code -s, --session <id>} resumes an existing session; on a
+     * fresh spawn (no resume target) no flag is added, letting opencode start a brand-new session.
+     * The id comes from the current spawn request's {@code resumeSessionId}, threaded per-thread by
+     * {@link #spawn(SpawnRequest)}.
+     */
+    private List<String> argvWithResume(List<String> argv) {
+        String id = resumeSessionId.get();
+        if (id == null || id.isBlank()) {
+            return argv;
+        }
+        List<String> withResume = mutableArgv(argv);
+        withResume.add("-s");
+        withResume.add(id);
+        return withResume;
+    }
+
+    /** The launch argv plus, when a model is configured, the opencode {@code -m provider/model} flag. */
+    private List<String> argvWithModel(List<String> argv, BridgedConfig.Profile cfg) {
+        if (cfg.model() != null && !cfg.model().isBlank()) {
+            argv.add("-m");
+            argv.add(cfg.model());
+        }
+        return argv;
+    }
+
+    /**
+     * Write an ephemeral {@code opencode.json} (and the reply-charter file it references) into a
+     * fresh per-spawn directory under {@link #configRoot}, and return the config file's path for
+     * {@code OPENCODE_CONFIG}. The dir is unique per spawn so concurrent workers never race on it;
+     * it is best-effort cleaned on JVM exit (worker config is disposable — regenerated every spawn).
+     */
+    private Path writeConfig(BridgedConfig.Profile cfg) {
+        try {
+            Path dir = Files.createTempDirectory(configRoot, "bridged-opencode-");
+            dir.toFile().deleteOnExit();
+
+            ObjectNode root = JSON.createObjectNode();
+            root.put("$schema", "https://opencode.ai/config.json");
+            // CB-523, opencode side: a worker that runs out of context dies mid-turn, and its reply
+            // — the entire point of the turn — is lost with it. Auto-compaction is therefore not an
+            // operator preference for a bridged worker, it is a condition of the turn contract.
+            //
+            // Stated deliberately even though it is redundant today: OPENCODE_CONFIG is MERGED over
+            // ~/.config/opencode/config.json rather than replacing it, so a worker already inherits
+            // an `auto: true` set at home. We do not want that inheritance to be what the guarantee
+            // rests on — the home file is outside this repo, differs per machine, and is not ours.
+            //
+            // Know the cost before removing it: this key WINS over the home config (verified — an
+            // OPENCODE_CONFIG value overrides the home value, it does not defer to it), so an
+            // operator who sets `compaction.auto: false` at home cannot turn it off for bridged
+            // workers. That is the intended trade for peers we spawn and whose turns we must land;
+            // if per-profile control is ever wanted, add a profile knob rather than dropping this.
+            root.putObject("compaction").put("auto", true);
+
+            if (cfg.hasMcp()) {
+                Path charter = dir.resolve("reply-charter.md");
+                Files.writeString(charter, REPLY_CHARTER);
+                charter.toFile().deleteOnExit();
+
+                ObjectNode bridge = root.putObject("mcp").putObject("bridge");
+                bridge.put("type", "remote");
+                bridge.put("url", cfg.mcpUrl());
+                bridge.put("enabled", true);
+                root.putArray("instructions").add(charter.toAbsolutePath().toString());
+            }
+            if (hasCustomProvider(cfg)) {
+                addCustomProvider(root, cfg);
+            }
+
+            Path cfgFile = dir.resolve("opencode.json");
+            // Built with Jackson rather than string concatenation: the provider block is nested and
+            // carries operator-supplied values (URL, model id, api key), so escaping must be real.
+            Files.writeString(cfgFile, JSON.writerWithDefaultPrettyPrinter().writeValueAsString(root));
+            cfgFile.toFile().deleteOnExit();
+            return cfgFile;
+        } catch (IOException e) {
+            throw new UncheckedIOException(
+                    "cannot write opencode config for profile " + cfg.profile(), e);
+        }
+    }
+
+    /**
+     * Declare a custom OpenAI-compatible provider so the worker talks to a pinned endpoint (a local
+     * vLLM, say) instead of opencode's default gateway (CB-508).
+     *
+     * <p>The provider id comes from the {@code provider/model} selector in {@code model:}, so one
+     * field drives both the declaration and the {@code -m} flag and they cannot drift apart.
+     */
+    private void addCustomProvider(ObjectNode root, BridgedConfig.Profile cfg) {
+        String[] parts = splitModelSelector(cfg);
+        String providerId = parts[0];
+        String modelId = parts[1];
+
+        ObjectNode provider = root.putObject("provider").putObject(providerId);
+        provider.put("npm", "@ai-sdk/openai-compatible");
+        provider.put("name", providerId + " (bridged)");
+
+        ObjectNode options = provider.putObject("options");
+        options.put("baseURL", openAiBaseUrl(cfg.baseUrl()));
+        // vLLM and friends usually ignore the key, but the AI SDK still requires a non-empty one.
+        String token = resolveEnv(cfg.tokenEnv());
+        options.put("apiKey", (token == null || token.isBlank()) ? "bridged-local-noauth" : token);
+
+        provider.putObject("models").putObject(modelId).put("name", modelId);
+    }
+
+    /**
+     * Split {@code model:} into its {@code provider} and {@code model} halves. A pinned endpoint
+     * needs both, so a bare model name is rejected loudly rather than silently falling back to the
+     * default gateway — a worker quietly talking to the wrong endpoint is the failure this avoids.
+     */
+    private static String[] splitModelSelector(BridgedConfig.Profile cfg) {
+        String model = cfg.model();
+        int slash = model == null ? -1 : model.indexOf('/');
+        if (model == null || model.isBlank() || slash <= 0 || slash == model.length() - 1) {
+            throw new IllegalArgumentException(
+                    "profile " + cfg.profile() + " sets baseUrl (a pinned opencode endpoint) so"
+                            + " model: must be \"<provider>/<model>\", e.g."
+                            + " \"local-vllm/deepseek-v4-flash\"; got "
+                            + (model == null ? "null" : '"' + model + '"'));
+        }
+        return new String[]{model.substring(0, slash), model.substring(slash + 1)};
+    }
+
+    /**
+     * The OpenAI-compatible base URL for {@code baseUrl}. A bare {@code host:port} gets {@code /v1}
+     * appended (where these servers put the API); a URL that already carries a path is taken as-is,
+     * so an endpoint mounted somewhere unusual is still reachable.
+     */
+    private static String openAiBaseUrl(String baseUrl) {
+        String trimmed = baseUrl.trim();
+        while (trimmed.endsWith("/")) {
+            trimmed = trimmed.substring(0, trimmed.length() - 1);
+        }
+        int schemeEnd = trimmed.indexOf("://");
+        String afterScheme = schemeEnd < 0 ? trimmed : trimmed.substring(schemeEnd + 3);
+        return afterScheme.contains("/") ? trimmed : trimmed + "/v1";
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>adds this adapter's session-identity work around the base's spawn — as opencode cannot be
+     * told its session id at spawn (see {@link Capability#SESSION_RESUME} vs
+     * {@link Capability#SESSION_NAME}), identity is only ever adopted after the fact:
+     * <ul>
+     *   <li>the request's {@code resumeSessionId} is remembered for {@link #buildLaunch} to turn
+     *       into {@code -s <id>}; and</li>
+     *   <li>the returned handle is wrapped so its
+     *       {@link dev.ltms.bridged.peer.PeerHandle#agentSessionId()} performs lazy session
+     *       discovery against opencode's storage (see {@link OpenCodeSessionDiscovery}) — always
+     *       non-blocking, {@code null} until opencode has persisted the session record.</li>
+     * </ul>
+     */
+    @Override
+    public PeerHandle spawn(SpawnRequest req) {
+        resumeSessionId.set(req.resumeSessionId());
+        try {
+            PeerHandle inner = super.spawn(req);
+            return new SessionAwareHandle(inner, discovery, effectiveCwd(req));
+        } finally {
+            // Never let a paused/leftover resume id bleed into the next spawn on this thread.
+            resumeSessionId.remove();
+        }
+    }
+
+    /**
+     * A {@link PeerHandle} that delegates everything to the base's worker handle but resolves
+     * {@link #agentSessionId()} lazily through opencode session discovery. Delegate-only, so the
+     * base's id/terminalId/profile semantics (CB-519's host-unique routing key, herdr coordinates)
+     * are untouched — only the opencode-specific identity answer is added. {@code sessionName()}
+     * stays null: opencode has no display-name seam, so the logical name lives only in the bridge's
+     * roster (see the SESSION_NAME capability).
+     */
+    private static final class SessionAwareHandle implements PeerHandle {
+        private final PeerHandle delegate;
+        private final OpenCodeSessionDiscovery discovery;
+        private final String cwd;
+
+        SessionAwareHandle(PeerHandle delegate, OpenCodeSessionDiscovery discovery, String cwd) {
+            this.delegate = delegate;
+            this.discovery = discovery;
+            this.cwd = cwd;
+        }
+
+        @Override
+        public String id() {
+            return delegate.id();
+        }
+
+        @Override
+        public String terminalId() {
+            return delegate.terminalId();
+        }
+
+        @Override
+        public String profile() {
+            return delegate.profile();
+        }
+
+        @Override
+        public String sessionName() {
+            return delegate.sessionName();
+        }
+
+        @Override
+        public String agentSessionId() {
+            // Lazy + retried, never a spawn-time blocker: opencode writes the session record only
+            // when the session is first persisted, so null here is the correct interim answer and
+            // the caller re-calls later (each call re-scans, picking up a record that has since
+            // appeared).
+            return discovery.sessionIdForDirectory(cwd);
+        }
+    }
+
+    // --- Agent-returning convenience spawns (used by callers/tests that want the herdr Agent) ---
+
+    /** Spawn a worker for the default profile in the resolved default cwd. */
+    public Agent spawn() {
+        return spawnInternal(null, null, null);
+    }
+
+    /** Spawn a worker for a named profile (null → default) in the resolved default cwd. */
+    public Agent spawn(String profileName) {
+        return spawnInternal(profileName, null, null);
+    }
+
+    /** Spawn a worker for a named profile with an explicit requested/caller cwd (CB-112). */
+    public Agent spawn(String profileName, String requestedCwd, String callerCwd) {
+        return spawnInternal(profileName, requestedCwd, callerCwd);
+    }
+
+    // --- capabilities --------------------------------------------------------------------------
+
+    @Override
+    public Set<Capability> capabilities() {
+        Set<Capability> caps = EnumSet.of(Capability.MID_TURN_ASK, Capability.WORKTREE,
+                Capability.ORPHAN_REAP, Capability.SESSION_RESUME);
+        if (hasGitTokenProfile()) {
+            caps.add(Capability.SELF_PR);
+        }
+        // Deliberately NOT SESSION_NAME: opencode has no display-name flag, so the bridge's logical
+        // name can't surface in the peer's own UI — declaring the capability would hide that
+        // asymmetry rather than make it honest. For opencode the name lives only in the bridge's
+        // roster (see PeerHandle.sessionName() returning null).
+        return Set.copyOf(caps);
+    }
+
+    /** Whether any configured profile opts into a git-forge token (required for {@link Capability#SELF_PR}). */
+    private boolean hasGitTokenProfile() {
+        return profileConfigs().stream().anyMatch(BridgedConfig.Profile::hasGitToken);
+    }
+
+    // --- CB-117 reap predicate (opencode prefix), kept for direct unit testing -----------------
+
+    /**
+     * Whether {@code name} is an opencode bridge worker started by a <em>different</em> process than
+     * {@code currentNonce}. A thin {@code opencode}-prefix binding of
+     * {@link HerdrPeerLauncher#isForeignWorker(String, String, String)}.
+     */
+    static boolean isForeignWorker(String name, String currentNonce) {
+        return HerdrPeerLauncher.isForeignWorker(NAME_PREFIX, name, currentNonce);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/member/OpenCodeSessionDiscovery.java

@@ -0,0 +1,122 @@
+package dev.ltms.bridged.member;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.stream.Stream;
+
+/**
+ * Resolves the opencode session id for a bridged worker from opencode's on-disk storage — the
+ * only place this adapter touches opencode's private layout, and deliberately the <em>only</em>
+ * class that does.
+ *
+ * <p><strong>Why this is isolated behind one seam.</strong> The layout is version-coupled and not a
+ * stable contract: opencode writes one JSON file per session under
+ * {@code <storageRoot>/session/<projectID>/<ses_*.json>}, and each record carries a
+ * {@code "version"} field (e.g. {@code "1.1.31"}), so the exact directory shape, file naming, and
+ * field names can move between opencode releases. opencode also ships a headless HTTP server that
+ * may supersede file scanning entirely. Everything this adapter knows about that private storage —
+ * its shape, naming, and field names — lives here, so a layout change, or a switch to the HTTP
+ * server, changes exactly one class and nothing in {@link OpenCodeLauncher}.
+ *
+ * <p>The determinism that makes this useful is structural, not a guess: every bridged worker runs
+ * in its own unique git worktree, so the record's {@code directory} (its project root) equals the
+ * worker's cwd identifies <em>its</em> session unambiguously. We match on {@code directory} rather
+ * than diffing {@code opencode session list} before/after — that races under concurrent spawns, and
+ * the CLI listing does not even show the directory.
+ *
+ * <p>All reads are best-effort and never throw: a missing or unreadable storage root, a record that
+ * fails to parse, or a directory with no record yet all yield {@code null}, and the caller (the
+ * session handle) treats that as "identity not resolved yet" and retries later.
+ */
+final class OpenCodeSessionDiscovery {
+
+    private final Path storageRoot;   // e.g. ~/.local/share/opencode (injectable for tests)
+    private final ObjectMapper json;
+
+    OpenCodeSessionDiscovery(Path storageRoot) {
+        this.storageRoot = storageRoot;
+        this.json = new ObjectMapper();
+    }
+
+    /**
+     * The opencode session id whose record references {@code directory} (the worker's cwd), or
+     * {@code null} when no record matches yet. When several records share the directory — e.g.
+     * repeated spawns into the same worktree — the <em>most recently modified</em> one wins: it is
+     * the session the pane most likely corresponds to.
+     *
+     * <p>Never throws: a missing {@code storageRoot}, an unreadable/malformed record, or a
+     * directory that has not been persisted yet all resolve to {@code null} rather than failing a
+     * spawn. A bridged worker's session record is written lazily (when the session is first
+     * persisted), so {@code null} here is the normal answer right after the pane is ready, and the
+     * caller retries later.
+     *
+     * @param directory the worker's cwd, as resolved for this spawn
+     * @return the matching session id, or {@code null} if none is known yet
+     */
+    String sessionIdForDirectory(String directory) {
+        if (directory == null || directory.isBlank()) {
+            return null;
+        }
+        Path sessionRoot = storageRoot.resolve("session");
+        if (!Files.isDirectory(sessionRoot)) {
+            return null;
+        }
+        String best = null;
+        long bestMtime = Long.MIN_VALUE;
+        try (Stream<Path> projectDirs = Files.list(sessionRoot)) {
+            for (Path projectDir : projectDirs.filter(Files::isDirectory).toList()) {
+                try (Stream<Path> records = Files.list(projectDir)) {
+                    for (Path record : records.toList()) {
+                        String id = matchId(record, directory);
+                        if (id == null) {
+                            continue;
+                        }
+                        long mtime = lastModifiedEpochMillis(record);
+                        if (mtime > bestMtime) {
+                            bestMtime = mtime;
+                            best = id;
+                        }
+                    }
+                } catch (IOException ignored) {
+                    // one project dir unreadable — skip it; another may still match
+                }
+            }
+        } catch (IOException ignored) {
+            // storage root vanished or became unreadable — "no session known yet"
+            return null;
+        }
+        return best;
+    }
+
+    /**
+     * The record's session id when it references {@code directory}, else {@code null}. A record
+     * that is not JSON, lacks {@code id}/{@code directory}, or points at a different directory is
+     * simply not our session; a malformed one is skipped, never fatal.
+     */
+    private String matchId(Path record, String directory) {
+        try {
+            JsonNode node = json.readTree(record.toFile());
+            JsonNode id = node == null ? null : node.get("id");
+            JsonNode dir = node == null ? null : node.get("directory");
+            if (id == null || dir == null || !directory.equals(dir.asText())) {
+                return null;
+            }
+            return id.asText();
+        } catch (IOException e) {
+            return null;
+        }
+    }
+
+    /** The record's last-modified epoch ms, or {@code Long.MIN_VALUE} if unreadable (never wins). */
+    private static long lastModifiedEpochMillis(Path record) {
+        try {
+            return Files.getLastModifiedTime(record).toMillis();
+        } catch (IOException e) {
+            return Long.MIN_VALUE;
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/metrics/BridgedMetrics.java

@@ -0,0 +1,101 @@
+package dev.ltms.bridged.metrics;
+
+import dev.ltms.bridged.msg.ReplyInbox;
+import dev.ltms.bridged.session.SessionManager;
+import dev.ltms.bridged.session.MemberSession;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * The daemon's metric definitions (CB-502) — one place where every series is named, described, and
+ * (for gauges) bound to live state.
+ *
+ * <p>The set is deliberately small: each series maps to a failure mode this project has actually
+ * hit, not to whatever was easy to count. The two worth watching in practice are
+ * {@code bridged_sends_total{outcome="completion_fallback"}} — a rising share means turn detection
+ * is degrading, the CB-115/116/118 failure family — and
+ * {@code bridged_push_nudges_total{outcome="exhausted"}}, which means the primary stopped draining
+ * its inbox and CB-307's active push gave up.
+ */
+public final class BridgedMetrics {
+
+    /** Counter: delegated sends by terminal outcome. */
+    public static final String SENDS = "bridged_sends_total";
+    /** Counter: worker replies by the path that carried them (rendezvous vs stranded-to-inbox). */
+    public static final String REPLIES = "bridged_replies_total";
+    /** Counter: push-loop nudges to the primary, by outcome. */
+    public static final String PUSH_NUDGES = "bridged_push_nudges_total";
+    /** Counter: idle-lead heartbeat nudges to the lead, by outcome (CB-551). */
+    public static final String HEARTBEAT_NUDGES = "bridged_lead_heartbeat_nudges_total";
+    /** Counter: spawn attempts by peer kind and outcome. */
+    public static final String SPAWNS = "bridged_spawns_total";
+    /** Counter: herdr socket calls by method and outcome. */
+    public static final String HERDR_CALLS = "bridged_herdr_calls_total";
+    /** Counter: rejected requests by reason (CB-501). */
+    public static final String AUTH_FAILURES = "bridged_auth_failures_total";
+    /** Gauge: session census by lifecycle state. */
+    public static final String SESSIONS = "bridged_sessions";
+    /** Gauge: undrained replies held per target. */
+    public static final String INBOX_DEPTH = "bridged_inbox_depth";
+
+    private BridgedMetrics() {
+    }
+
+    /**
+     * Build the registry with its help text and live gauges bound.
+     *
+     * @param sessions the authoritative session registry (census gauge)
+     * @param inbox    the reply inbox; only used for a depth gauge when it can be inspected
+     */
+    public static Metrics create(SessionManager sessions, ReplyInbox inbox) {
+        Metrics m = new Metrics();
+
+        m.describe(SENDS, "counter",
+                "Delegated sends by terminal outcome (replied|completion_fallback|timeout|failed).");
+        m.describe(REPLIES, "counter",
+                "Worker replies by delivery path (rendezvous=resolved an open send, inbox=stranded and held).");
+        m.describe(PUSH_NUDGES, "counter",
+                "CB-307 push-loop nudges to the primary (delivered|exhausted).");
+        m.describe(HEARTBEAT_NUDGES, "counter",
+                "CB-551 idle-lead heartbeat nudges (delivered|failed|exhausted). Quiet-cap exhaustion "
+                        + "means the lead idled with nothing pending and was told to stand down.");
+        m.describe(SPAWNS, "counter",
+                "Worker spawn attempts by peer kind and outcome (ready|timeout|guard_rejected).");
+        m.describe(HERDR_CALLS, "counter",
+                "herdr socket calls by method and outcome — the dependency everything else rests on.");
+        m.describe(AUTH_FAILURES, "counter",
+                "Requests refused by CB-501/505 (unauthenticated|forbidden).");
+        m.describe(SESSIONS, "gauge",
+                "Registered worker sessions by lifecycle state.");
+        m.describe(INBOX_DEPTH, "gauge",
+                "Replies held for a target that the primary has not drained. Steady state is 0; "
+                        + "a target stuck above 0 means CB-307 delivery is not completing.");
+
+        // One gauge per state so a scrape shows the whole census even when a state is empty —
+        // an absent series and a zero series read very differently on a dashboard.
+        for (MemberSession.State state : MemberSession.State.values()) {
+            String label = state.name().toLowerCase();
+            m.gauge(SESSIONS, () -> countIn(sessions, state), "state", label);
+        }
+
+        // Depth is per live session, so the label set is only known at scrape time. peek() is the
+        // port's non-destructive read — scraping metrics must never ack a reply out of the inbox.
+        m.collector(INBOX_DEPTH, "target", () -> {
+            Map<String, Number> depths = new LinkedHashMap<>();
+            for (MemberSession s : sessions.roster()) {
+                String target = s.terminalId();
+                if (target == null) {
+                    continue;
+                }
+                depths.put(target, inbox.peek(target).size());
+            }
+            return depths;
+        });
+        return m;
+    }
+
+    private static long countIn(SessionManager sessions, MemberSession.State state) {
+        return sessions.roster().stream().filter(s -> s.state() == state).count();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/metrics/Metrics.java

@@ -0,0 +1,181 @@
+package dev.ltms.bridged.metrics;
+
+import java.util.Map;
+import java.util.NavigableMap;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentSkipListMap;
+import java.util.concurrent.atomic.LongAdder;
+import java.util.function.Supplier;
+
+/**
+ * The daemon's metric registry and Prometheus text renderer (CB-502).
+ *
+ * <p>Deliberately dependency-free. The roadmap's tech-stack table specified Micrometer, but this
+ * pom already carries an unusual reconciliation burden (a hand-pinned {@code jackson-annotations}
+ * to make the MCP SDK's Jackson 3 coexist with our Jackson 2, a Jetty BOM import to stop version
+ * skew, and four documented accepted-CVE advisories), and the dependency CVE gate this project
+ * mandates could not be run when this landed. The metric set is small and fully known, and
+ * Prometheus text exposition is a stable, well-specified format — so the registry is ~100 lines
+ * here instead of a new transitive tree. {@code GET /metrics} is the swap seam if Micrometer's
+ * ecosystem is ever wanted.
+ *
+ * <p>Thread-safe: counters are {@link LongAdder} (built for contended increment), gauges are
+ * supplier-backed so they read live state at scrape time rather than needing to be pushed.
+ */
+public final class Metrics {
+
+    /** Counter series, keyed by the fully-rendered {@code name{labels}} sample id. */
+    private final NavigableMap<String, LongAdder> counters = new ConcurrentSkipListMap<>();
+    /** Gauge series, evaluated at scrape time. */
+    private final NavigableMap<String, Supplier<Number>> gauges = new ConcurrentSkipListMap<>();
+    /** Gauge families whose label set is only known at scrape time, keyed by metric name. */
+    private final NavigableMap<String, Collector> collectors = new ConcurrentSkipListMap<>();
+    /** HELP/TYPE metadata, keyed by bare metric name. */
+    private final Map<String, String[]> meta = new ConcurrentHashMap<>();
+
+    /** A gauge family whose series are discovered per scrape (one label, many values). */
+    private record Collector(String labelName, Supplier<Map<String, Number>> samples) {
+    }
+
+    /** Declare a metric's help text and type once, so the exposition carries HELP/TYPE lines. */
+    public Metrics describe(String name, String type, String help) {
+        meta.put(name, new String[]{type, help});
+        return this;
+    }
+
+    /** Increment a counter by one. */
+    public void inc(String name, String... labelPairs) {
+        add(name, 1, labelPairs);
+    }
+
+    /** Increment a counter by {@code delta}. */
+    public void add(String name, long delta, String... labelPairs) {
+        counters.computeIfAbsent(sample(name, labelPairs), _ -> new LongAdder()).add(delta);
+    }
+
+    /**
+     * Register a live gauge. The supplier is called at scrape time, so it reflects current state
+     * (session census, inbox depth) without anything having to remember to update it.
+     */
+    public void gauge(String name, Supplier<Number> value, String... labelPairs) {
+        gauges.put(sample(name, labelPairs), value);
+    }
+
+    /**
+     * Register a gauge family whose label values are not known up front — inbox depth per target,
+     * for instance, where the set of targets changes as workers come and go. The supplier returns
+     * {@code labelValue → value} and is evaluated once per scrape.
+     */
+    public void collector(String name, String labelName, Supplier<Map<String, Number>> samples) {
+        collectors.put(name, new Collector(labelName, samples));
+    }
+
+    /** Current value of a counter series — for assertions in tests. */
+    public long count(String name, String... labelPairs) {
+        LongAdder a = counters.get(sample(name, labelPairs));
+        return a == null ? 0 : a.sum();
+    }
+
+    /**
+     * Render the Prometheus text exposition format (version 0.0.4): optional {@code # HELP} and
+     * {@code # TYPE} lines per metric family, then one line per sample.
+     */
+    public String render() {
+        StringBuilder out = new StringBuilder(1024);
+        String lastFamily = null;
+        for (Map.Entry<String, LongAdder> e : counters.entrySet()) {
+            lastFamily = emitHeader(out, e.getKey(), lastFamily);
+            out.append(e.getKey()).append(' ').append(e.getValue().sum()).append('\n');
+        }
+        for (Map.Entry<String, Supplier<Number>> e : gauges.entrySet()) {
+            lastFamily = emitHeader(out, e.getKey(), lastFamily);
+            Number v;
+            try {
+                v = e.getValue().get();
+            } catch (RuntimeException ex) {
+                continue; // a broken gauge must never break the whole scrape
+            }
+            if (v == null) {
+                continue;
+            }
+            out.append(e.getKey()).append(' ').append(format(v)).append('\n');
+        }
+        for (Map.Entry<String, Collector> e : collectors.entrySet()) {
+            Map<String, Number> samples;
+            try {
+                samples = e.getValue().samples().get();
+            } catch (RuntimeException ex) {
+                continue; // a broken collector must never break the whole scrape
+            }
+            if (samples == null || samples.isEmpty()) {
+                continue;
+            }
+            lastFamily = emitHeader(out, e.getKey(), lastFamily);
+            // Sort so repeated scrapes are byte-stable and diffable.
+            new java.util.TreeMap<>(samples).forEach((label, v) -> {
+                if (v != null) {
+                    out.append(sample(e.getKey(), e.getValue().labelName(), label))
+                            .append(' ').append(format(v)).append('\n');
+                }
+            });
+        }
+        return out.toString();
+    }
+
+    /** Emit HELP/TYPE when the sample starts a new metric family; returns the current family. */
+    private String emitHeader(StringBuilder out, String sampleId, String lastFamily) {
+        String family = familyOf(sampleId);
+        if (family.equals(lastFamily)) {
+            return lastFamily;
+        }
+        String[] m = meta.get(family);
+        if (m != null) {
+            out.append("# HELP ").append(family).append(' ').append(m[1]).append('\n');
+            out.append("# TYPE ").append(family).append(' ').append(m[0]).append('\n');
+        }
+        return family;
+    }
+
+    private static String familyOf(String sampleId) {
+        int brace = sampleId.indexOf('{');
+        return brace < 0 ? sampleId : sampleId.substring(0, brace);
+    }
+
+    /** Whole numbers render without a decimal point; everything else as-is. */
+    private static String format(Number v) {
+        double d = v.doubleValue();
+        return (d == Math.rint(d) && !Double.isInfinite(d))
+                ? Long.toString((long) d)
+                : Double.toString(d);
+    }
+
+    /** Build the {@code name{k="v",k2="v2"}} sample id; labels are sorted for stable output. */
+    private static String sample(String name, String... labelPairs) {
+        if (labelPairs == null || labelPairs.length == 0) {
+            return name;
+        }
+        if (labelPairs.length % 2 != 0) {
+            throw new IllegalArgumentException("labels must be key/value pairs, got " + labelPairs.length);
+        }
+        NavigableMap<String, String> sorted = new java.util.TreeMap<>();
+        for (int i = 0; i < labelPairs.length; i += 2) {
+            sorted.put(labelPairs[i], labelPairs[i + 1] == null ? "" : labelPairs[i + 1]);
+        }
+        StringBuilder sb = new StringBuilder(name.length() + 16 * sorted.size());
+        sb.append(name).append('{');
+        boolean first = true;
+        for (Map.Entry<String, String> e : sorted.entrySet()) {
+            if (!first) {
+                sb.append(',');
+            }
+            first = false;
+            sb.append(e.getKey()).append("=\"").append(escapeLabel(e.getValue())).append('"');
+        }
+        return sb.append('}').toString();
+    }
+
+    /** Label values are escaped per the exposition format: backslash, quote, newline. */
+    private static String escapeLabel(String v) {
+        return v.replace("\\", "\\\\").replace("\"", "\\\"").replace("\n", "\\n");
+    }
+}

bridged/src/main/java/dev/ltms/bridged/msg/AmqpReplyInbox.java

@@ -0,0 +1,242 @@
+package dev.ltms.bridged.msg;
+
+import com.rabbitmq.client.AMQP;
+import com.rabbitmq.client.Channel;
+import com.rabbitmq.client.Connection;
+import com.rabbitmq.client.ConnectionFactory;
+import com.rabbitmq.client.DeliverCallback;
+import com.rabbitmq.client.Recoverable;
+import com.rabbitmq.client.RecoveryListener;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * AMQP-backed {@link ReplyInbox} (CB-307 Stage 2): genuine cross-restart durability behind the same
+ * port {@link InMemoryReplyInbox} implements as soft state.
+ *
+ * <p><strong>Mapping — consume-and-hold with deferred manual ack.</strong> Each target has a durable
+ * queue {@code agent.<target>.inbox}. The gateway that owns the target starts a manual-ack consumer
+ * ({@link #own}) that pulls persistent messages off that queue into an in-memory <em>held</em> map
+ * (keyed by {@code msgId}) but does <em>not</em> ack them. {@link #peek} returns that snapshot;
+ * {@link #ack} acks the broker delivery-tag and drops the entry. Because messages stay unacked until
+ * the owning gateway actually drains them, a crash (or a {@code java -jar} bounce) before caller-ack
+ * leaves them on the broker — it redelivers on reconnect. That is the durability the in-memory
+ * adapter cannot give, with the port contract preserved.
+ *
+ * <p><strong>Ownership is explicit.</strong> {@link #own} declares the queue and starts the consumer;
+ * {@link #release} cancels it. {@link #publish} sends to the queue but does <em>not</em> imply ownership
+ * and does not attach a consumer. This split is required by CB-308 federation, where one gateway may
+ * publish to an agent owned by another gateway; in that case the publisher must not compete for
+ * deliveries.
+ *
+ * <p><strong>Dedup.</strong> The consumer keys the held map by {@code msgId}; a redelivered duplicate
+ * (at-least-once, or a producer double-publish) is acked-and-dropped on arrival, so it never
+ * double-queues.
+ *
+ * <p><strong>Visibility.</strong> Unlike the in-memory adapter, publish → broker → consumer is
+ * asynchronous, so a {@link #peek} immediately after {@link #publish} may not yet see the message
+ * (broker delivery latency). Callers that need the reply drained poll (as the primary already does);
+ * the contract test waits for visibility. This is inherent to broker-backed delivery, not a defect.
+ *
+ * <p>The default deploy targets LavinMQ; a stock RabbitMQ speaks the same AMQP 0-9-1 (URI-only swap),
+ * so the {@code @Tag("contract")} integration test runs against a RabbitMQ container.
+ */
+public final class AmqpReplyInbox implements ReplyInbox, AutoCloseable {
+
+    private static final Logger log = LoggerFactory.getLogger(AmqpReplyInbox.class);
+
+    private static final String QUEUE_PREFIX = "agent.";
+    private static final String QUEUE_SUFFIX = ".inbox";
+
+    private final Connection connection;
+    private final Channel channel;
+    /** All channel operations (publish/declare/ack/cancel) serialize on this — a Channel is not thread-safe. */
+    private final Object channelLock = new Object();
+    /** target → (msgId → held delivery). Per-target map is guarded by synchronizing on itself. */
+    private final ConcurrentHashMap<String, LinkedHashMap<String, Held>> held = new ConcurrentHashMap<>();
+    /** Targets whose queue is declared and consumer is running, mapped to their broker consumer tag. */
+    private final ConcurrentHashMap<String, String> consumerTags = new ConcurrentHashMap<>();
+
+    /** A message pulled off the broker but not yet acked: its delivery-tag plus the port payload. */
+    private record Held(long deliveryTag, InboxMessage message) {}
+
+    /** Connect to {@code uri} (e.g. {@code amqp://guest:guest@127.0.0.1:5672/}) and open the inbox. */
+    public static AmqpReplyInbox open(String uri) {
+        try {
+            ConnectionFactory factory = new ConnectionFactory();
+            factory.setUri(uri);
+            // Self-heal transient blips; topology recovery re-declares queues and re-attaches consumers.
+            factory.setAutomaticRecoveryEnabled(true);
+            factory.setTopologyRecoveryEnabled(true);
+            return new AmqpReplyInbox(factory.newConnection("bridged-reply-inbox"));
+        } catch (Exception e) {
+            throw new IllegalStateException("cannot connect to AMQP broker at " + uri, e);
+        }
+    }
+
+    /** Wrap an already-open connection (injection seam for the contract test). */
+    AmqpReplyInbox(Connection connection) {
+        this.connection = connection;
+        try {
+            this.channel = connection.createChannel();
+        } catch (IOException e) {
+            throw new IllegalStateException("cannot open AMQP channel", e);
+        }
+        // On automatic recovery the broker redelivers unacked messages with FRESH delivery-tags; the
+        // tags we were holding are now stale. Drop the held snapshot so the re-attached consumer
+        // repopulates it with valid tags (dedup by msgId still prevents any double-queue).
+        if (connection instanceof Recoverable recoverable) {
+            recoverable.addRecoveryListener(new RecoveryListener() {
+                @Override
+                public void handleRecovery(Recoverable recoverable) {
+                    held.clear();
+                    log.info("AMQP connection recovered; cleared held replies for fresh redelivery");
+                }
+
+                @Override
+                public void handleRecoveryStarted(Recoverable recoverable) {
+                    // no-op: we act once recovery completes
+                }
+            });
+        }
+    }
+
+    @Override
+    public void own(String target) {
+        synchronized (channelLock) {
+            if (consumerTags.containsKey(target)) {
+                return;                            // already owning this target
+            }
+            String queue = queueName(target);
+            try {
+                channel.queueDeclare(queue, true, false, false, null); // durable, non-exclusive, keep on idle
+                String tag = channel.basicConsume(queue, false, deliverCallback(target), _ -> { });
+                consumerTags.put(target, tag);
+                log.debug("AMQP inbox owns queue {} for target {}", queue, target);
+            } catch (IOException e) {
+                throw new IllegalStateException("cannot own queue " + queue, e);
+            }
+        }
+    }
+
+    @Override
+    public void release(String target) {
+        synchronized (channelLock) {
+            String tag = consumerTags.remove(target);
+            held.remove(target);                   // stale delivery tags must not survive release
+            if (tag == null) {
+                return;
+            }
+            try {
+                channel.basicCancel(tag);
+            } catch (IOException e) {
+                throw new IllegalStateException("cannot cancel consumer for " + target, e);
+            }
+        }
+    }
+
+    @Override
+    public void publish(String target, String msgId, String content) {
+        AMQP.BasicProperties props = new AMQP.BasicProperties.Builder()
+                .messageId(msgId)
+                .deliveryMode(2)                   // persistent — survives a broker restart
+                .contentType("text/plain")
+                .build();
+        try {
+            synchronized (channelLock) {
+                channel.basicPublish("", queueName(target), props, content.getBytes(StandardCharsets.UTF_8));
+            }
+        } catch (IOException e) {
+            throw new IllegalStateException("cannot publish reply to " + queueName(target), e);
+        }
+    }
+
+    @Override
+    public List<InboxMessage> peek(String target) {
+        var perTarget = held.get(target);
+        if (perTarget == null) {
+            return List.of();
+        }
+        synchronized (perTarget) {
+            return perTarget.values().stream().map(Held::message).toList();
+        }
+    }
+
+    @Override
+    public void ack(String target, String msgId) {
+        var perTarget = held.get(target);
+        if (perTarget == null) {
+            return;
+        }
+        Held h;
+        synchronized (perTarget) {
+            h = perTarget.remove(msgId);
+        }
+        if (h == null) {
+            return;                                // never held (or already acked) — no-op
+        }
+        try {
+            synchronized (channelLock) {
+                channel.basicAck(h.deliveryTag(), false);
+            }
+        } catch (IOException e) {
+            // Ack didn't reach the broker: restore the entry so a later ack (or a redelivery after
+            // reconnect) can retry. Keeps the at-least-once contract — a reply is never silently lost.
+            synchronized (perTarget) {
+                perTarget.putIfAbsent(msgId, h);
+            }
+            throw new IllegalStateException("cannot ack reply " + msgId + " on " + queueName(target), e);
+        }
+    }
+
+    private DeliverCallback deliverCallback(String target) {
+        return (_, delivery) -> {
+            String msgId = delivery.getProperties().getMessageId();
+            long tag = delivery.getEnvelope().getDeliveryTag();
+            if (msgId == null || msgId.isBlank()) {
+                msgId = Long.toHexString(tag);     // synthesize an id so dedup still has a key
+            }
+            String content = new String(delivery.getBody(), StandardCharsets.UTF_8);
+            var perTarget = held.computeIfAbsent(target, _ -> new LinkedHashMap<>());
+            boolean duplicate;
+            synchronized (perTarget) {
+                if (perTarget.containsKey(msgId)) {
+                    duplicate = true;
+                } else {
+                    perTarget.put(msgId, new Held(tag, new InboxMessage(msgId, target, content)));
+                    duplicate = false;
+                }
+            }
+            if (duplicate) {
+                // Redelivered duplicate: ack the new tag and drop it so the broker stops resending.
+                synchronized (channelLock) {
+                    channel.basicAck(tag, false);
+                }
+            }
+        };
+    }
+
+    private static String queueName(String target) {
+        return QUEUE_PREFIX + target + QUEUE_SUFFIX;
+    }
+
+    @Override
+    public void close() {
+        try {
+            channel.close();
+        } catch (Exception e) {
+            log.debug("AMQP channel close: {}", e.toString());
+        }
+        try {
+            connection.close();
+        } catch (Exception e) {
+            log.debug("AMQP connection close: {}", e.toString());
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/msg/InMemoryReplyInbox.java

@@ -0,0 +1,74 @@
+package dev.ltms.bridged.msg;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Soft-state {@link ReplyInbox} backed by a {@link ConcurrentHashMap} keyed by target session.
+ * Per-target FIFO ordering (insertion order via {@link LinkedHashMap}). Dedup by {@code msgId}
+ * within a target. Thread-safe for concurrent publish vs. drain.
+ *
+ * <p><strong>Ownership is explicit.</strong> {@link #own} marks a target as locally owned so that
+ * {@link #peek} and {@link #ack} operate on it; {@link #publish} works whether or not the target is
+ * owned. {@link #release} clears the local snapshot. This mirrors the AMQP adapter's contract so the
+ * non-broker path stays interchangeable.
+ *
+ * <p><strong>This is soft-state, NOT persistence.</strong> Lost on a {@code java -jar} bounce — that
+ * is correct and consistent with "bridged stays soft-state." The Stage-2 AMQP adapter replaces this.
+ */
+public final class InMemoryReplyInbox implements ReplyInbox {
+
+    private final ConcurrentHashMap<String, LinkedHashMap<String, InboxMessage>> store = new ConcurrentHashMap<>();
+    private final Set<String> owned = ConcurrentHashMap.newKeySet();
+
+    @Override
+    public void own(String target) {
+        owned.add(target);
+    }
+
+    @Override
+    public void release(String target) {
+        owned.remove(target);
+        store.remove(target);
+    }
+
+    @Override
+    public void publish(String target, String msgId, String content) {
+        var perTarget = store.computeIfAbsent(target, _ -> new LinkedHashMap<>());
+        //noinspection SynchronizationOnLocalVariableOrMethodParameter
+        synchronized (perTarget) {
+            perTarget.putIfAbsent(msgId, new InboxMessage(msgId, target, content));
+        }
+    }
+
+    @Override
+    public List<InboxMessage> peek(String target) {
+        if (!owned.contains(target)) {
+            return List.of();
+        }
+        var perTarget = store.get(target);
+        if (perTarget == null) {
+            return List.of();
+        }
+        //noinspection SynchronizationOnLocalVariableOrMethodParameter
+        synchronized (perTarget) {
+            return List.copyOf(perTarget.values());
+        }
+    }
+
+    @Override
+    public void ack(String target, String msgId) {
+        if (!owned.contains(target)) {
+            return;
+        }
+        var perTarget = store.get(target);
+        if (perTarget != null) {
+            //noinspection SynchronizationOnLocalVariableOrMethodParameter
+            synchronized (perTarget) {
+                perTarget.remove(msgId);
+            }
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/msg/LeadHeartbeatLoop.java

@@ -0,0 +1,351 @@
+package dev.ltms.bridged.msg;
+
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.AgentStatus;
+import dev.ltms.bridged.mcp.PrimaryRegistry;
+import dev.ltms.bridged.metrics.BridgedMetrics;
+import dev.ltms.bridged.metrics.Metrics;
+import dev.ltms.bridged.session.MemberSession;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.function.LongSupplier;
+import java.util.function.Supplier;
+
+/**
+ * CB-551: an opt-in heartbeat that nudges the single idle lead back to work once it has been
+ * continuously idle past a quiet period with no open {@code bridge_send} driving it.
+ *
+ * <p>Why this exists: the fleet is ONE lead + architects + workers, so an idle, stalled lead is a
+ * single point of failure for the fleet's progress. {@link ReplyPushLoop} nudges the lead only when
+ * a worker reply lands; this loop is the timer that catches the gap where nothing lands and the
+ * lead simply sits idle with nobody to prompt it onward.
+ *
+ * <p>Mechanism mirrors {@link ReplyPushLoop}: a pure, unit-testable decision function
+ * ({@link #decide(long, Long, int, AgentStatus, boolean, boolean, FleetState)}) plus a thin
+ * scheduler around it. The loop is <em>entirely opt-in</em> ({@code leadHeartbeat:} in config); with
+ * no such block it is never constructed, so upgrading the daemon cannot silently acquire a behaviour
+ * that spends the operator's model subscription on its own initiative (constraint 1).
+ *
+ * <p>Four invariants keep it from becoming a runaway subscription burner:
+ * <ol>
+ *   <li><b>Status-gated</b> — a {@code WORKING} lead is making progress and is never touched; only an
+ *       injectable (idle/done/blocked) lead is even considered (constraint 2).</li>
+ *   <li><b>Debounced</b> — a nudge only fires once the lead has been <em>continuously</em> idle past
+ *       {@code idleAfterSeconds}, so a lead that just finished a turn is not re-prompted into every
+ *       natural pause (constraint 3).</li>
+ *   <li><b>Bounded when quiet</b> — consecutive nudges that find no pending fleet state are capped at
+ *       {@code quietNudgeCap}, then the loop stops nudging until real state returns (constraint 4).</li>
+ *   <li><b>Never races {@link ReplyPushLoop}</b> — while that loop is actively nudging any target this
+ *       loop stands down, so two competing injections never start two turns in the same pane
+ *       (constraint 6).</li>
+ * </ol>
+ */
+public final class LeadHeartbeatLoop {
+
+    private static final Logger log = LoggerFactory.getLogger(LeadHeartbeatLoop.class);
+
+    /** Sentinel for {@link #idleSinceNanos}: the lead is not currently in an idle stretch. */
+    private static final long NOT_IDLE = Long.MIN_VALUE;
+
+    private final PrimaryRegistry primaryRegistry;
+    private final AgentControl agents;
+    private final ReplyInbox inbox;
+    private final Supplier<List<MemberSession>> roster;
+    private final ReplyPushLoop pushLoop;
+    private final ScheduledExecutorService scheduler;
+    private final LongSupplier clock;
+    private final long idleAfterNanos;
+    private final long backoffMs;
+    private final int quietNudgeCap;
+    private final Metrics metrics; // CB-512 pattern: nullable — no registry in unit tests
+
+    /** When the current idle stretch began (nanos), or {@link #NOT_IDLE}. Single scheduler thread only. */
+    private long idleSinceNanos = NOT_IDLE;
+    /** Consecutive nudges that found no pending fleet state. Single scheduler thread only. */
+    private int quietCount = 0;
+
+    /** Constructor with an injectable clock and no metric registry (unit tests, or wiring that opts out). */
+    public LeadHeartbeatLoop(PrimaryRegistry primaryRegistry, AgentControl agents, ReplyInbox inbox,
+                             Supplier<List<MemberSession>> roster, ReplyPushLoop pushLoop,
+                             ScheduledExecutorService scheduler, LongSupplier clock,
+                             long idleAfterNanos, long backoffMs, int quietNudgeCap) {
+        this(primaryRegistry, agents, inbox, roster, pushLoop, scheduler, clock,
+                idleAfterNanos, backoffMs, quietNudgeCap, null);
+    }
+
+    /** As above, with a metric registry (the CB-512 pattern) so nudge outcomes are counted. */
+    public LeadHeartbeatLoop(PrimaryRegistry primaryRegistry, AgentControl agents, ReplyInbox inbox,
+                             Supplier<List<MemberSession>> roster, ReplyPushLoop pushLoop,
+                             ScheduledExecutorService scheduler, LongSupplier clock,
+                             long idleAfterNanos, long backoffMs, int quietNudgeCap, Metrics metrics) {
+        this.primaryRegistry = primaryRegistry;
+        this.agents = agents;
+        this.inbox = inbox;
+        this.roster = roster;
+        this.pushLoop = pushLoop;
+        this.scheduler = scheduler;
+        this.clock = clock;
+        this.idleAfterNanos = idleAfterNanos;
+        this.backoffMs = backoffMs;
+        this.quietNudgeCap = quietNudgeCap;
+        this.metrics = metrics;
+    }
+
+    /** Count one nudge outcome when a registry is wired; a no-op in unit tests. */
+    private void countNudge(String outcome) {
+        if (metrics != null) {
+            metrics.inc(BridgedMetrics.HEARTBEAT_NUDGES, "outcome", outcome);
+        }
+    }
+
+    // --- decision logic (package-private for unit-testing) --------------------------------------
+
+    /** The action the loop should take on one tick. */
+    enum Action {
+        /** Send a heartbeat nudge to the lead now. */
+        INJECT,
+        /** Lead is idle but not yet past the quiet period — keep waiting, do nothing. */
+        WAIT_IDLE,
+        /** Lead is making progress (or its status cannot be read) — reset the idle window and re-arm. */
+        LEAD_BUSY,
+        /** Idle past the quiet period with nothing pending and the cap exhausted — stop until new state appears. */
+        QUIET_DONE,
+        /** {@link ReplyPushLoop} is actively nudging — stand aside rather than start a competing turn. */
+        STAND_DOWN
+    }
+
+    /** The outcome of one decision: the action plus the state to persist for the next tick. */
+    record Decision(Action action, Long idleSinceNanos, int quietCount) {}
+
+    /**
+     * Pure decision function: given the current loop state and fleet/lead facts, return what to do
+     * next and the exact state to carry forward. Pure means no I/O and no mutation — the caller
+     * ({@link #tick}) applies {@link Decision} to its fields. This is what makes the loop unit-testable
+     * with a fake clock and no sleeping.
+     *
+     * @param nowNanos        the current time (an injected clock in tests, {@link System#nanoTime()} live)
+     * @param idleSinceNanos  when the current idle stretch began, or {@code null} if the lead is not idle
+     * @param quietCount      consecutive nudges so far that found no pending fleet state
+     * @param status          the lead's herdr status
+     * @param pushLoopActive  whether {@link ReplyPushLoop} is currently nudging some target (constraint 6)
+     * @param leadKnown       whether a lead terminal is known to nudge at all
+     * @param fleet           a snapshot of the pending fleet state (constraint 5)
+     * @return the action to take and the state to persist
+     */
+    Decision decide(long nowNanos, Long idleSinceNanos, int quietCount, AgentStatus status,
+                    boolean pushLoopActive, boolean leadKnown, FleetState fleet) {
+        // Constraint 6: while ReplyPushLoop is actively nudging the lead, injecting a second,
+        // competing prompt into the same pane would start a second turn — racing loops multiply
+        // turns and context burn. Stand aside, and treat the active push as real state (re-arm the
+        // quiet counter), because the reply that drove it is exactly the kind of new state that
+        // should reset the cap.
+        if (pushLoopActive) {
+            return new Decision(Action.STAND_DOWN, idleSinceNanos, 0);
+        }
+        // Constraint 2: a WORKING lead is making progress and must NOT be touched; an unreadable
+        // status (read failure, or the agent is gone) is safest treated the same way — never inject
+        // into a state we cannot read. Either way, reset the idle window and the quiet counter: the
+        // lead was / may be active, so the next idle stretch must count its own quiet period fresh.
+        if (status == null || !status.injectable()) {
+            return new Decision(Action.LEAD_BUSY, null, 0);
+        }
+        if (idleSinceNanos == null) {
+            // The lead just became injectable — record the start of an idle stretch and wait out the
+            // debounce quiet period before ever nudging (constraint 3).
+            return new Decision(Action.WAIT_IDLE, nowNanos, quietCount);
+        }
+        if (nowNanos - idleSinceNanos < idleAfterNanos) {
+            // Still within the quiet period: the lead that just finished a turn sits momentarily idle
+            // and must not be re-prompted into every natural pause.
+            return new Decision(Action.WAIT_IDLE, idleSinceNanos, quietCount);
+        }
+        // Past the quiet period with an injectable lead: it is a genuine candidate for a nudge. Two
+        // gating facts decide whether and how:
+        if (!leadKnown) {
+            // No lead terminal is known yet (e.g. the registry has not learned one) — there is nobody
+            // to nudge. Keep waiting; the window stays open so discovery re-arms it without a fresh
+            // quiet period.
+            return new Decision(Action.WAIT_IDLE, idleSinceNanos, quietCount);
+        }
+        if (fleet.hasPending()) {
+            // Real fleet state is waiting — a worker reply or a DONE session. This is new state, so
+            // it resets the quiet counter (constraint 4) and the lead is nudged to go collect it.
+            return new Decision(Action.INJECT, idleSinceNanos, 0);
+        }
+        if (quietCount < quietNudgeCap) {
+            // Nothing is pending, but the cap is not exhausted: nudge anyway, telling the lead
+            // exactly that nothing is waiting so it can choose to stand down rather than hunt
+            // (constraint 5). Count it toward the consecutive-quiet cap.
+            return new Decision(Action.INJECT, idleSinceNanos, quietCount + 1);
+        }
+        // Nothing pending and the cap is exhausted: stop nudging until real state appears again
+        // (constraint 4). The loop still ticks on backoff so a genuinely new reply or session change
+        // re-arms it — QUIET_DONE stops injection, not observation.
+        return new Decision(Action.QUIET_DONE, idleSinceNanos, quietCount);
+    }
+
+    // --- loop ----------------------------------------------------------------------------------
+
+    /**
+     * Start the heartbeat. Schedules the first tick after one backoff so a freshly-booting daemon
+     * does not evaluate the lead's idle state before the fleet has settled.
+     */
+    public void start() {
+        log.info("idle-lead heartbeat: on — nudge lead after {}s idle (recheck {}ms, quiet cap {})",
+                TimeUnit.NANOSECONDS.toSeconds(idleAfterNanos), backoffMs, quietNudgeCap);
+        scheduler.schedule(this::tick, backoffMs, TimeUnit.MILLISECONDS);
+    }
+
+    /** One loop tick, every {@link #backoffMs} — the thin scheduler around {@link #decide}. */
+    private void tick() {
+        boolean leadKnown = primaryRegistry.primaryTerminal().isPresent();
+        FleetState fleet = snapshot(inbox, roster);
+        AgentStatus status = AgentStatus.UNKNOWN;
+        if (leadKnown) {
+            try {
+                status = agents.status(primaryRegistry.primaryTerminal().orElseThrow());
+            } catch (RuntimeException e) {
+                // A failed status read degrades to "unknown" — decide() treats that like a busy lead
+                // and never injects into a state it cannot read. Retry on the next backoff.
+                log.debug("idle-heartbeat: status check failed for lead, will retry: {}", e.toString());
+            }
+        }
+
+        Decision d = decide(clock.getAsLong(),
+                idleSinceNanos == NOT_IDLE ? null : idleSinceNanos,
+                quietCount, status, pushLoop.isActive(), leadKnown, fleet);
+        applyDecision(d);
+        switch (d.action()) {
+            case INJECT -> injectNudge(fleet);
+            case QUIET_DONE -> countNudge("exhausted");
+            case WAIT_IDLE, LEAD_BUSY, STAND_DOWN -> { /* nothing to inject, nothing to count */ }
+        }
+        scheduleNext();
+    }
+
+    /** Persist the state a decision returned, so the next tick starts from it. */
+    private void applyDecision(Decision d) {
+        idleSinceNanos = d.idleSinceNanos() == null ? NOT_IDLE : d.idleSinceNanos();
+        quietCount = d.quietCount();
+    }
+
+    /** Send the nudge to the known lead. */
+    private void injectNudge(FleetState fleet) {
+        var lead = primaryRegistry.primaryTerminal();
+        if (lead.isEmpty()) {
+            return; // the lead disappeared between the decision and the injection
+        }
+        String leadTerminal = lead.get();
+        try {
+            agents.send(leadTerminal, fleet.nudgeText());
+            log.debug("idle-heartbeat: nudge sent to lead {} (quiet nudges so far in this stretch: {})",
+                    leadTerminal, quietCount);
+            countNudge("delivered");
+        } catch (RuntimeException e) {
+            log.warn("idle-heartbeat: failed to nudge lead {}: {}", leadTerminal, e.toString());
+            countNudge("failed");
+        }
+    }
+
+    /** Schedule the next tick on the scheduler thread pool. */
+    private void scheduleNext() {
+        scheduler.schedule(this::tick, backoffMs, TimeUnit.MILLISECONDS);
+    }
+
+    // --- lifecycle -----------------------------------------------------------------------------
+
+    /** Shut down the scheduler; outstanding ticks are cancelled. */
+    public void stop() {
+        scheduler.shutdownNow();
+    }
+
+    /** @see #stop() */
+    public void close() {
+        stop();
+    }
+
+    /**
+     * A read-only snapshot of the fleet facts the heartbeat reports to an idle lead. Carries exact
+     * counts and names the targets that hold replies, so the nudge is actionable rather than a
+     * content-free "keep working" that would cost the lead a turn just to discover what there is to
+     * do (constraint 5).
+     *
+     * @param pendingReplies total undrained worker replies across owned targets
+     * @param doneSessions   session count in the DONE state — finished turns awaiting teardown
+     * @param liveWorkers    sessions still registered (acquired minus released)
+     * @param replyTargets   the terminals whose inboxes currently hold at least one reply
+     */
+    record FleetState(int pendingReplies, int doneSessions, int liveWorkers, List<String> replyTargets) {
+
+        /** True when the lead has something real to collect — a reply or a session awaiting teardown. */
+        boolean hasPending() {
+            return pendingReplies > 0 || doneSessions > 0;
+        }
+
+        /** The nudge body, phrased for the two cases the heartbeat distinguishes. */
+        String nudgeText() {
+            StringBuilder sb = new StringBuilder(
+                    "Heartbeat: you are idle and no bridge_send is waiting on you.");
+            if (hasPending()) {
+                sb.append(" The fleet has state to collect: ").append(pendingDetail());
+            } else {
+                sb.append(" Fleet is quiet — nothing pending to collect (")
+                        .append(pendingReplies).append(" worker replies, ")
+                        .append(doneSessions).append(" DONE sessions); ")
+                        .append(liveWorkers).append(" workers live. You may stand down until new state re-arms me.");
+            }
+            return sb.toString();
+        }
+
+        private String pendingDetail() {
+            StringBuilder sb = new StringBuilder();
+            sb.append(pendingReplies).append(" worker ")
+                    .append(pendingReplies == 1 ? "reply" : "replies")
+                    .append(" pending collection");
+            if (!replyTargets.isEmpty()) {
+                // Render each as the exact command so the lead can act without parsing: the nearest
+                // analogue to ReplyPushLoop's bridge_poll(target=...) nudge.
+                sb.append(" (")
+                        .append(String.join(", ",
+                                replyTargets.stream().map(t -> "bridge_poll(target=" + t + ")").toList()))
+                        .append(")");
+            }
+            sb.append(", ").append(doneSessions).append(" DONE session").append(doneSessions == 1 ? "" : "s")
+                    .append(" awaiting teardown")
+                    .append(", ").append(liveWorkers).append(" worker").append(liveWorkers == 1 ? "" : "s")
+                    .append(" live");
+            return sb.toString();
+        }
+    }
+
+    /**
+     * Build a {@link FleetState} snapshot over the live roster and the reply inbox — the same
+     * sources the metrics collector uses, so the heartbeat reports facts the operator can cross-check
+     * against {@code /metrics}. Package-private and pure (reads only) so it is unit-testable.
+     */
+    static FleetState snapshot(ReplyInbox inbox, Supplier<List<MemberSession>> roster) {
+        List<MemberSession> sessions = roster.get();
+        int replies = 0;
+        int done = 0;
+        List<String> replyTargets = new ArrayList<>();
+        for (MemberSession s : sessions) {
+            if (s.terminalId() == null) {
+                continue;
+            }
+            int depth = inbox.peek(s.terminalId()).size();
+            if (depth > 0) {
+                replies += depth;
+                replyTargets.add(s.terminalId());
+            }
+            if (s.state() == MemberSession.State.DONE) {
+                done++;
+            }
+        }
+        return new FleetState(replies, done, sessions.size(), List.copyOf(replyTargets));
+    }
+}

bridged/src/main/java/dev/ltms/bridged/msg/MessageService.java

@@ -0,0 +1,569 @@
+package dev.ltms.bridged.msg;
+
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.AgentStatus;
+import dev.ltms.bridged.inject.Injector;
+import dev.ltms.bridged.metrics.BridgedMetrics;
+import dev.ltms.bridged.metrics.Metrics;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * The blocking delegation feature (CB-104): deliver {@code content} into a worker and block until
+ * the worker returns a <em>structured reply</em> via {@code bridge_reply} (the {@link Rendezvous}),
+ * then hand that reply back. Delivery is the {@link Injector}'s job (the background poller sends it
+ * when the worker is injectable); this service never drives the injector or scrapes the terminal —
+ * completion is the worker's explicit reply, not a guess about {@code agent_status}.
+ *
+ * <p>Sends are serialized per session so exactly one reply can be outstanding per worker, which is
+ * what lets a reply map unambiguously to its send (no cross-talk between concurrent callers).
+ *
+ * <p>If the worker never replies within the timeout, the caller gets a typed "still working" /
+ * "queued" outcome — the message may still be mid-flight. A finished-but-unreplied turn is caught
+ * by the CB-106 completion fallback (see {@link Rendezvous#resolveCompletion}).
+ *
+ * <p><strong>Async fire-and-poll (CB-107).</strong> A caller's MCP client caps a blocking call at
+ * ~60s, but a real delegated task runs for minutes. {@link #sendAsync} therefore runs the same
+ * blocking {@link #send} on a background virtual thread and hands back a <em>ticket</em> the caller
+ * polls with {@link #poll}. The blocking and async paths share one code path (and the same per-target
+ * serialization), so async inherits the reply + completion resolution behaviour for free.
+ */
+public final class MessageService {
+
+    private static final Logger log = LoggerFactory.getLogger(MessageService.class);
+
+    /**
+     * The window a fire-and-poll send waits for resolution — generous, since no caller is blocked on
+     * it; a real delegated task resolves (reply or completion) well within this, and only a genuinely
+     * hung worker rides it out.
+     */
+    private static final long ASYNC_TIMEOUT_MS = 30 * 60 * 1_000L;
+
+    /** How long a finished (terminal) ticket is retained for polling before it is pruned. */
+    private static final long TICKET_TTL_NANOS = 10 * 60 * 1_000_000_000L;
+
+    /** Outcome of a blocking send. */
+    public enum Outcome {
+        /** The worker called {@code bridge_reply}; {@code text} holds the structured answer. */
+        REPLIED,
+        /**
+         * The worker's delegated turn finished without a {@code bridge_reply} (CB-106 fallback);
+         * {@code text} is the scraped transcript tail rather than a structured answer.
+         */
+        COMPLETED_UNREPLIED,
+        /**
+         * The worker ran the turn then wedged in an unrecoverable state (CB-109); {@code text} is the
+         * failure context (e.g. the error screen). Terminal, but not a successful completion.
+         */
+        WORKER_FAILED,
+        /**
+         * The worker paused mid-turn to ask the primary a question (CB-205); {@code text} is the
+         * question and {@code turnId} correlates the answer. Not terminal — the primary answers with
+         * {@link #answer(String, String, long)} and the turn resumes.
+         */
+        QUESTION,
+        /** Timed out after the message was delivered — the worker is still working. */
+        TIMED_OUT_WORKING,
+        /** Timed out before delivery — the message is still queued for the worker. */
+        TIMED_OUT_QUEUED,
+        /** Another send to this session was in flight for the whole window. */
+        BUSY,
+        /**
+         * An answer ({@link #answer(String, String, long)}) referenced a {@code turnId} that is no
+         * longer open — the worker's {@code bridge_ask} already timed out or was answered.
+         */
+        STALE_TURN
+    }
+
+    /**
+     * @param outcome how the send ended (or paused)
+     * @param text    the worker's answer when {@link #completed()} (a structured {@code bridge_reply}
+     *                for {@link Outcome#REPLIED}, a scraped transcript tail for
+     *                {@link Outcome#COMPLETED_UNREPLIED}), or the question for {@link Outcome#QUESTION},
+     *                else {@code null}
+     * @param turnId  correlation id for a {@link Outcome#QUESTION} (answered via
+     *                {@link #answer(String, String, long)}), else {@code null}
+     */
+    public record Reply(Outcome outcome, String text, String turnId) {
+        /** A reply with no correlation id (the common terminal outcomes). */
+        public Reply(Outcome outcome, String text) {
+            this(outcome, text, null);
+        }
+
+        /** Whether the worker's turn actually finished with an answer (replied or scraped). */
+        public boolean completed() {
+            return outcome == Outcome.REPLIED || outcome == Outcome.COMPLETED_UNREPLIED;
+        }
+    }
+
+    /** How a worker's {@code bridge_ask} (CB-205) resolved. */
+    public enum AskOutcome {
+        /** The primary answered; {@link AskResult#answer} carries it. */
+        ANSWERED,
+        /** No delegation was open to surface the question to — the worker has no one to ask. */
+        NO_WAITER,
+        /** The primary did not answer within the window. */
+        TIMED_OUT
+    }
+
+    /** The outcome of a worker's {@code bridge_ask}: how it resolved and (if answered) the answer. */
+    public record AskResult(AskOutcome outcome, String answer) {
+    }
+
+    /** Lifecycle phase of an async delegation ticket. */
+    public enum Phase {
+        /** Delegated and in flight — queued for the worker or being worked. */
+        PENDING,
+        /** The worker's turn finished; {@link TaskView#reply} holds the answer. */
+        DONE,
+        /** The delegation could not complete (timed out, worker gone, or busy). */
+        FAILED
+    }
+
+    /**
+     * A poll snapshot of an async delegation.
+     *
+     * @param reply       the answer when {@link #phase} is {@link Phase#DONE}, else {@code null}
+     * @param replySource {@code "reply"} (structured {@code bridge_reply}) or {@code "transcript"}
+     *                    (completion scrape) when {@link Phase#DONE}, else {@code null}
+     * @param detail      a human note (live worker status while pending, or the failure reason)
+     */
+    public record TaskView(String ticket, Phase phase, String reply, String replySource, String detail) {
+    }
+
+    /** An in-flight or finished async delegation, keyed by its ticket. */
+    private record Task(String target, CompletableFuture<Reply> future, long createdNanos) {
+    }
+
+    private final AgentControl agents;
+    private final Injector injector;
+    private final Rendezvous rendezvous;
+    private final ReplyInbox inbox;
+    private final ReplyPushLoop pushLoop;
+    private final Metrics metrics; // CB-502: nullable — no registry in unit tests
+    private final ConcurrentHashMap<String, ReentrantLock> sessionLocks = new ConcurrentHashMap<>();
+    private final ConcurrentHashMap<String, Task> tasks = new ConcurrentHashMap<>();
+    private final AtomicLong ticketSeq = new AtomicLong();
+    private final ExecutorService asyncExecutor = Executors.newThreadPerTaskExecutor(
+            Thread.ofVirtual().name("bridge-async-", 0).factory());
+
+    /**
+     * Create with an explicit {@link ReplyInbox} and optional {@link ReplyPushLoop}.
+     *
+     * @param pushLoop nullable — when non-null, the push loop is notified on the no-waiter reply
+     *                 branch ({@link #reply}) so it can nudge the primary to drain the inbox
+     */
+    public MessageService(AgentControl agents, Injector injector, Rendezvous rendezvous,
+                          ReplyInbox inbox, ReplyPushLoop pushLoop) {
+        this(agents, injector, rendezvous, inbox, pushLoop, null);
+    }
+
+    /**
+     * As above, with a metric registry (CB-502). Instrumenting here rather than at the REST and MCP
+     * edges means both surfaces are counted by one piece of code and cannot drift.
+     *
+     * @param metrics nullable — when null, nothing is recorded
+     */
+    public MessageService(AgentControl agents, Injector injector, Rendezvous rendezvous,
+                          ReplyInbox inbox, ReplyPushLoop pushLoop, Metrics metrics) {
+        this.agents = agents;
+        this.injector = injector;
+        this.rendezvous = rendezvous;
+        this.inbox = inbox;
+        this.pushLoop = pushLoop;
+        this.metrics = metrics;
+    }
+
+    /** Create with an explicit {@link ReplyInbox} and no push loop. */
+    public MessageService(AgentControl agents, Injector injector, Rendezvous rendezvous, ReplyInbox inbox) {
+        this(agents, injector, rendezvous, inbox, null);
+    }
+
+    /** Backward-compatible constructor that uses a default {@link InMemoryReplyInbox}. */
+    public MessageService(AgentControl agents, Injector injector, Rendezvous rendezvous) {
+        this(agents, injector, rendezvous, new InMemoryReplyInbox());
+    }
+
+    /** Current lifecycle status of a worker (the {@code GET /sessions/{id}/status} surface). */
+    public AgentStatus status(String target) {
+        return agents.status(target);
+    }
+
+    /**
+     * Route a worker's explicit {@code bridge_reply}: resolve an open send, or queue it in the
+     * inbox if no send is currently open. Unlike the bare {@link Rendezvous#resolve}, a no-waiter
+     * result is <em>not</em> a failure — the reply is held for later drain.
+     *
+     * <p><strong>Do NOT use this for mid-turn questions.</strong> {@code bridge_ask} /
+     * {@link Rendezvous#resolveQuestion} must keep today's {@code NO_WAITER} behaviour — questions
+     * are interactive and must never be queued.
+     *
+     * @return always {@code true} — the reply either resolved a live send or was queued
+     */
+    public boolean reply(String session, String content) {
+        if (rendezvous.resolve(session, content)) {
+            count(BridgedMetrics.REPLIES, "path", "rendezvous");
+            return true;                       // a live send took it — unchanged fast path
+        }
+        inbox.publish(session, UUID.randomUUID().toString(), content);
+        // A rising inbox share is the signal CB-307 exists to make visible: the worker finished but
+        // nobody was waiting, so delivery now depends on the push loop and a drain.
+        count(BridgedMetrics.REPLIES, "path", "inbox");
+        if (pushLoop != null) {
+            pushLoop.onReplyQueued(session);
+        }
+        return true;                           // held, not lost
+    }
+
+    /** Record a counter sample when a registry is wired; a no-op in unit tests. */
+    private void count(String name, String... labels) {
+        if (metrics != null) {
+            metrics.inc(name, labels);
+        }
+    }
+
+    /** Count a send's terminal outcome and pass the reply through unchanged. */
+    private Reply recorded(Reply r) {
+        String label = sendOutcomeLabel(r.outcome());
+        if (label != null) {
+            count(BridgedMetrics.SENDS, "outcome", label);
+        }
+        return r;
+    }
+
+    /** Map a terminal send outcome to its metric label, or {@code null} for non-terminal ones. */
+    private static String sendOutcomeLabel(Outcome o) {
+        return switch (o) {
+            case REPLIED -> "replied";
+            case COMPLETED_UNREPLIED -> "completion_fallback";
+            case TIMED_OUT_WORKING, TIMED_OUT_QUEUED, BUSY -> "timeout";
+            case WORKER_FAILED -> "failed";
+            case STALE_TURN, QUESTION -> null; // not a completed delegation
+        };
+    }
+
+    /**
+     * Abandon any send still waiting on {@code target} because its session has gone away (CB-516).
+     *
+     * <p>Without this, tearing a worker down left its rendezvous waiter open: a blocking
+     * {@code bridge_send} kept blocking, and an async one kept reporting {@code PENDING} until
+     * {@link #ASYNC_TIMEOUT_MS} — thirty minutes — even though the worker provably no longer
+     * existed and the delegation could never complete. Worse, {@code poll} already had the evidence
+     * (it calls {@code liveStatus} to build its detail string and gets back {@code "unknown"}) and
+     * reported {@code PENDING} anyway.
+     *
+     * <p>Resolving the waiter as a failure — rather than letting it time out — also means the
+     * outcome is counted, so a torn-down delegation stops being invisible to {@code /metrics}.
+     *
+     * @return true if a live waiter was failed
+     */
+    public boolean abandon(String target, String reason) {
+        CompletableFuture<Rendezvous.Resolution> waiter = rendezvous.currentWaiter(target);
+        if (waiter == null || waiter.isDone()) {
+            return false; // nobody is blocked on this worker — nothing to abandon
+        }
+        boolean failed = rendezvous.resolveFailure(waiter, reason);
+        if (failed) {
+            log.debug("abandoned send to {}: {}", target, reason);
+        }
+        return failed;
+    }
+
+    /**
+     * Acknowledge a specific reply by {@code msgId} for {@code target}. Removes it from the inbox
+     * so that a subsequent drain or peek no longer returns it.
+     */
+    public void ackReply(String target, String msgId) {
+        inbox.ack(target, msgId);
+    }
+
+    /**
+     * Drain (peek + ack) all pending inbox replies for {@code target}. At-least-once: returns the
+     * messages and acknowledges them; an in-flight failure between returning and the caller
+     * processing them re-surfaces them on a subsequent drain (the ack is local).
+     *
+     * @return the drained messages, newest last (FIFO); empty list if none
+     */
+    public List<ReplyInbox.InboxMessage> drainReplies(String target) {
+        var messages = inbox.peek(target);
+        for (var msg : messages) {
+            inbox.ack(target, msg.msgId());
+        }
+        return messages;
+    }
+
+    /**
+     * Deliver {@code content} to {@code target} (a herdr {@code terminal_id}) and block until the
+     * worker replies via {@link Rendezvous} or {@code timeoutMillis} elapses.
+     */
+    public Reply send(String target, String content, long timeoutMillis) {
+        return send(target, content, timeoutMillis, null);
+    }
+
+    /**
+     * As {@link #send(String, String, long)}, but with an accepted-delivery hook.
+     *
+     * <p>{@code onAccepted} is invoked exactly once, once this send has won {@code target}'s send
+     * lock and so become the <em>accepted target turn</em> — it runs <em>before</em> delivery is
+     * queued, so a throwing hook fails the send cleanly (the waiter it already opened is closed and
+     * nothing is left queued). It is <em>not</em> invoked when the send is {@link Outcome#BUSY}
+     * (lock never taken). A caller uses this to record that <em>it</em> now owns the delegation's
+     * reply routing (CB-548: {@code PrimaryRegistry} delegator ownership) — recording only on
+     * acceptance means a concurrent sender that times out {@code BUSY} can never steal ownership it
+     * never earned. {@code null} disables the hook.
+     */
+    public Reply send(String target, String content, long timeoutMillis, Runnable onAccepted) {
+        long deadlineNanos = System.nanoTime() + timeoutMillis * 1_000_000L;
+        ReentrantLock lock = sessionLocks.computeIfAbsent(target, _ -> new ReentrantLock());
+
+        if (!tryLock(lock, remainingMillis(deadlineNanos))) {
+            return new Reply(Outcome.BUSY, null); // another send held the session the whole window
+        }
+        try {
+            // Open the waiter BEFORE queueing delivery (CB-548). A fast reply — the worker already
+            // injectable the instant we enqueue — otherwise arrives before the waiter is registered
+            // and orphans into the inbox while this send blocks to the timeout (the enqueue-before-
+            // open race). Opening first also means a throwing onAccepted (fired before enqueue) or an
+            // enqueue failure is safely closed by the finally below: nothing is left queued, and the
+            // failed send leaves no stale waiter behind.
+            CompletableFuture<Rendezvous.Resolution> reply = rendezvous.open(target);
+            try {
+                // The send has won the lock; the accepted-delivery hook records delegator ownership
+                // here (CB-548). It runs BEFORE enqueue so a throwing hook — onAccepted is now a
+                // public callback — fails the send without queuing a message that would orphan.
+                if (onAccepted != null) {
+                    onAccepted.run();
+                }
+                CompletableFuture<Void> delivered = injector.enqueue(target, content);
+                try {
+                    Rendezvous.Resolution r = reply.get(remainingMillis(deadlineNanos), TimeUnit.MILLISECONDS);
+                    return recorded(new Reply(outcomeOf(r.kind()), r.text(), r.turnId()));
+                } catch (TimeoutException e) {
+                    boolean wasDelivered = delivered.isDone() && !delivered.isCompletedExceptionally();
+                    log.debug("send to {} timed out (delivered={})", target, wasDelivered);
+                    return recorded(new Reply(
+                            wasDelivered ? Outcome.TIMED_OUT_WORKING : Outcome.TIMED_OUT_QUEUED, null));
+                } catch (ExecutionException e) {
+                    Throwable cause = e.getCause();
+                    throw cause instanceof RuntimeException re ? re : new IllegalStateException(cause);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException("interrupted awaiting reply from " + target, e);
+                }
+            } finally {
+                rendezvous.close(target, reply);
+            }
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    /**
+     * A worker's mid-turn question (CB-205 reverse rendezvous): surface {@code question} to the
+     * primary by resolving its open blocking {@code bridge_send}, then block this (worker) call until
+     * the primary answers via {@link #answer} or {@code timeoutMillis} elapses. Identity is the
+     * worker's own session — it does not address the primary.
+     *
+     * <p>Returns {@link AskOutcome#NO_WAITER} when no delegation is open to surface the question to
+     * (nothing to answer it), {@link AskOutcome#ANSWERED} with the primary's answer, or
+     * {@link AskOutcome#TIMED_OUT} if the primary stayed silent. The worker resumes its turn either
+     * way — an answered ask hands back the answer; an unanswered one leaves it to proceed alone.
+     */
+    public AskResult ask(String workerSession, String question, long timeoutMillis) {
+        Rendezvous.AskTicket ticket = rendezvous.openAsk(workerSession);
+        // Only the freshly-opening caller surfaces the question; a coalesced duplicate simply blocks on
+        // the shared answer future that the fresh owner is already responsible for.
+        if (ticket.fresh()) {
+            // Register the reverse waiter first, then surface the question — so the answer, which can
+            // arrive the instant the primary reacts, always finds an open waiter to resolve.
+            if (!rendezvous.resolveQuestion(workerSession, question, ticket.turnId())) {
+                rendezvous.closeAsk(ticket.turnId());
+                return new AskResult(AskOutcome.NO_WAITER, null); // no primary is blocked on this worker
+            }
+        }
+        try {
+            String answer = ticket.answer().get(timeoutMillis, TimeUnit.MILLISECONDS);
+            return new AskResult(AskOutcome.ANSWERED, answer);
+        } catch (TimeoutException e) {
+            log.debug("bridge_ask from {} went unanswered in {}ms", workerSession, timeoutMillis);
+            return new AskResult(AskOutcome.TIMED_OUT, null);
+        } catch (ExecutionException e) {
+            Throwable cause = e.getCause();
+            throw cause instanceof RuntimeException re ? re : new IllegalStateException(cause);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("interrupted awaiting the primary's answer for " + workerSession, e);
+        } finally {
+            // Only the fresh owner tears down the shared turn; a duplicate must leave it open.
+            if (ticket.fresh()) {
+                rendezvous.closeAsk(ticket.turnId());
+            }
+        }
+    }
+
+    /**
+     * The primary's answer to a worker's {@code bridge_ask} (CB-205): resolve the worker's blocked
+     * question identified by {@code turnId}, then — like a fresh {@link #send} — block for the worker's
+     * eventual {@code bridge_reply} as it finishes the resumed turn. The worker session is derived from
+     * {@code turnId}, never a caller argument.
+     *
+     * <p>Unlike {@link #send} this does not re-inject through the {@link Injector}: the worker is
+     * mid-turn (already picked up), so the answer flows back through its own open {@code bridge_ask}
+     * call, not a new status-gated delivery. The forward waiter is opened <em>before</em> the worker
+     * is unblocked so a reply that lands the instant it resumes is not lost.
+     */
+    public Reply answer(String turnId, String content, long timeoutMillis) {
+        String workerSession = rendezvous.askSession(turnId);
+        if (workerSession == null) {
+            return new Reply(Outcome.STALE_TURN, null); // the ask lapsed (timed out or already answered)
+        }
+        long deadlineNanos = System.nanoTime() + timeoutMillis * 1_000_000L;
+        ReentrantLock lock = sessionLocks.computeIfAbsent(workerSession, _ -> new ReentrantLock());
+        if (!tryLock(lock, remainingMillis(deadlineNanos))) {
+            return new Reply(Outcome.BUSY, null);
+        }
+        try {
+            CompletableFuture<Rendezvous.Resolution> reply = rendezvous.open(workerSession);
+            if (!rendezvous.answerAsk(turnId, content)) {
+                rendezvous.close(workerSession, reply);
+                return new Reply(Outcome.STALE_TURN, null); // lapsed between the lookup and the unblock
+            }
+            try {
+                Rendezvous.Resolution r = reply.get(remainingMillis(deadlineNanos), TimeUnit.MILLISECONDS);
+                return new Reply(outcomeOf(r.kind()), r.text(), r.turnId());
+            } catch (TimeoutException e) {
+                // The worker resumed but hasn't replied yet — no completion fallback arms an answered
+                // turn (it never re-entered the injector), so a silent worker rides out the window.
+                return new Reply(Outcome.TIMED_OUT_WORKING, null);
+            } catch (ExecutionException e) {
+                Throwable cause = e.getCause();
+                throw cause instanceof RuntimeException re ? re : new IllegalStateException(cause);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                throw new IllegalStateException("interrupted awaiting reply from " + workerSession, e);
+            } finally {
+                rendezvous.close(workerSession, reply);
+            }
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    /**
+     * Fire-and-poll variant of {@link #send}: deliver {@code content} to {@code target} on a
+     * background virtual thread and return immediately with a ticket to {@link #poll}. This is how a
+     * long task is delegated without tripping the caller's MCP client call timeout.
+     *
+     * @return the ticket to poll for the eventual result
+     */
+    public String sendAsync(String target, String content) {
+        return sendAsync(target, content, null);
+    }
+
+    /**
+     * As {@link #sendAsync(String, String)}, with the accepted-delivery hook of
+     * {@link #send(String, String, long, Runnable)} — the running {@code send} invokes {@code onAccepted}
+     * the moment it becomes the accepted target turn, so async flooding records delegator ownership
+     * exactly as the blocking path does (CB-548).
+     *
+     * @return the ticket to poll for the eventual result
+     */
+    public String sendAsync(String target, String content, Runnable onAccepted) {
+        String ticket = "task-" + ticketSeq.incrementAndGet();
+        CompletableFuture<Reply> future = CompletableFuture.supplyAsync(
+                () -> send(target, content, ASYNC_TIMEOUT_MS, onAccepted), asyncExecutor);
+        tasks.put(ticket, new Task(target, future, System.nanoTime()));
+        pruneTerminalTickets();
+        log.debug("async send {} -> {}", ticket, target);
+        return ticket;
+    }
+
+    /**
+     * Snapshot the state of an async delegation. Returns {@code null} for an unknown/expired ticket;
+     * otherwise a {@link Phase#PENDING} view (with the live worker status as detail), a
+     * {@link Phase#DONE} view carrying the reply, or a {@link Phase#FAILED} view with the reason.
+     */
+    public TaskView poll(String ticket) {
+        Task task = tasks.get(ticket);
+        if (task == null) {
+            return null;
+        }
+        CompletableFuture<Reply> f = task.future();
+        if (!f.isDone()) {
+            return new TaskView(ticket, Phase.PENDING, null, null, "worker " + liveStatus(task.target()));
+        }
+        Reply r;
+        try {
+            r = f.getNow(null);
+        } catch (CompletionException | java.util.concurrent.CancellationException e) {
+            Throwable cause = (e instanceof CompletionException ce && ce.getCause() != null) ? ce.getCause() : e;
+            return new TaskView(ticket, Phase.FAILED, null, null, cause.getMessage());
+        }
+        if (r.completed()) {
+            String source = r.outcome() == Outcome.REPLIED ? "reply" : "transcript";
+            return new TaskView(ticket, Phase.DONE, r.text(), source, null);
+        }
+        // A wedged worker (CB-109) carries the error context as its reason; the timeout/busy
+        // outcomes carry none, so fall back to the outcome name.
+        String detail = r.outcome() == Outcome.WORKER_FAILED && r.text() != null
+                ? r.text()
+                : "no reply — " + r.outcome().name().toLowerCase();
+        return new TaskView(ticket, Phase.FAILED, null, null, detail);
+    }
+
+    /** Best-effort live worker status for a pending poll; never throws (a lookup error is just noise). */
+    private String liveStatus(String target) {
+        try {
+            return agents.status(target).name().toLowerCase();
+        } catch (RuntimeException e) {
+            return "unknown";
+        }
+    }
+
+    /** Drop finished tickets older than the TTL so the registry cannot grow without bound. */
+    private void pruneTerminalTickets() {
+        long cutoff = System.nanoTime() - TICKET_TTL_NANOS;
+        tasks.values().removeIf(t -> t.future().isDone() && t.createdNanos() < cutoff);
+    }
+
+    /** Release the async executor. */
+    public void close() {
+        asyncExecutor.shutdown();
+    }
+
+    /** Map a rendezvous {@link Rendezvous.Kind} onto its send {@link Outcome} (shared by send/answer). */
+    private static Outcome outcomeOf(Rendezvous.Kind kind) {
+        return switch (kind) {
+            case REPLY -> Outcome.REPLIED;
+            case COMPLETION -> Outcome.COMPLETED_UNREPLIED;
+            case FAILED -> Outcome.WORKER_FAILED;
+            case QUESTION -> Outcome.QUESTION;
+        };
+    }
+
+    private static boolean tryLock(ReentrantLock lock, long millis) {
+        try {
+            return lock.tryLock(Math.max(0, millis), TimeUnit.MILLISECONDS);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IllegalStateException("interrupted awaiting the session send lock", e);
+        }
+    }
+
+    private static long remainingMillis(long deadlineNanos) {
+        return (deadlineNanos - System.nanoTime()) / 1_000_000L;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/msg/Rendezvous.java

@@ -0,0 +1,231 @@
+package dev.ltms.bridged.msg;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+
+/**
+ * The reply rendezvous: where a blocking {@code bridge_send} awaits how the worker's delegated turn
+ * ends. The sending (primary) request thread {@link #open}s a waiter; it is resolved either by the
+ * worker's explicit {@code bridge_reply} ({@link #resolve}, arriving on a different thread via
+ * {@code POST /sessions/{id}/reply}) or — the CB-106 fallback — by the injector observing the
+ * worker's delegated turn return to idle without a reply ({@link #resolveCompletion}).
+ *
+ * <p>At most one waiter per session — {@link MessageService} serializes sends per session, so a
+ * resolution maps unambiguously to the one outstanding send and cannot be captured by another.
+ *
+ * <p><strong>Waiter identity (CB-116).</strong> The completion/failure fallbacks run asynchronously
+ * and can fire <em>after</em> the turn they belong to has already been resolved by an explicit reply
+ * and a <em>next</em> send has opened its own waiter on the same session. Resolving "whatever waiter
+ * is registered now" would then land turn N's stale scrape on turn N+1's send. So those fallbacks
+ * resolve a <em>specific</em> {@link CompletableFuture} captured when their turn was delivered
+ * ({@link #resolveCompletion(CompletableFuture, String)} /
+ * {@link #resolveFailure(CompletableFuture, String)}): a no-op if that waiter was already resolved,
+ * and it can never touch a later send's waiter.
+ */
+public final class Rendezvous {
+
+    /** How a delegated turn ended (or paused). */
+    public enum Kind {
+        /** The worker called {@code bridge_reply} with a structured answer. */
+        REPLY,
+        /** The worker's turn finished without a {@code bridge_reply}; {@code text} is a scrape. */
+        COMPLETION,
+        /** The worker ran the turn then wedged (CB-109); {@code text} is the failure context. */
+        FAILED,
+        /**
+         * The worker paused mid-turn to ask the primary a question (CB-205 reverse rendezvous);
+         * {@code text} is the question and {@code turnId} correlates the primary's answer back to
+         * the worker's blocked {@code bridge_ask}. Not terminal — the turn resumes after the answer.
+         */
+        QUESTION
+    }
+
+    /**
+     * The resolved outcome of a send: its {@link Kind}, the associated text, and — only for
+     * {@link Kind#QUESTION} — the {@code turnId} the primary answers with (else {@code null}).
+     */
+    public record Resolution(Kind kind, String text, String turnId) {
+        /** A terminal resolution (reply / completion / failure) with no correlation id. */
+        public Resolution(Kind kind, String text) {
+            this(kind, text, null);
+        }
+    }
+
+    /** A worker's open mid-turn question: the worker session it belongs to and the answer future. */
+    private record AskWaiter(String session, CompletableFuture<String> answer) {
+    }
+
+    /**
+     * Handle to a reverse-rendezvous turn: the {@code turnId}, its answer future, and whether this
+     * call freshly opened it (versus coalescing onto an already-open ask).
+     */
+    public record AskTicket(String turnId, CompletableFuture<String> answer, boolean fresh) {
+    }
+
+    private final ConcurrentHashMap<String, CompletableFuture<Resolution>> waiters = new ConcurrentHashMap<>();
+
+    /** Reverse rendezvous (CB-205): worker questions awaiting the primary's answer, keyed by {@code turnId}. */
+    private final ConcurrentHashMap<String, AskWaiter> asks = new ConcurrentHashMap<>();
+    private final AtomicLong askSeq = new AtomicLong();
+    /** Per-session index of the currently-open ask, so duplicate bridge_ask calls coalesce onto one turn. */
+    private final ConcurrentHashMap<String, String> openAsksBySession = new ConcurrentHashMap<>();
+
+    /**
+     * Register a waiter for {@code session} — the await side of the public {@code resolve*} methods.
+     * The caller must hold that session's send lock.
+     *
+     * <p>Atomic fail-if-present (CB-548): if a waiter is already registered for {@code session}, an
+     * {@link IllegalStateException} is thrown rather than replacing the first — so any future
+     * invariant violation fails loudly instead of silently swapping the waiter another send is
+     * blocked on. {@code MessageService} serializes sends per session (the send lock), so in correct
+     * code a double open is impossible; this is a tripwire for the day that no longer holds.
+     */
+    public CompletableFuture<Resolution> open(String session) {
+        CompletableFuture<Resolution> waiter = new CompletableFuture<>();
+        CompletableFuture<Resolution> existing = waiters.putIfAbsent(session, waiter);
+        if (existing != null) {
+            throw new IllegalStateException(
+                    "rendezvous double-open for session " + session + " — a waiter is already registered");
+        }
+        return waiter;
+    }
+
+    /**
+     * Remove {@code waiter} for {@code session}, only if it is still the registered one. The
+     * symmetric complement of {@link #open}: a terminal send deregisters its waiter so the next
+     * send on the session may {@link #open} a fresh one (CB-548 makes double-open an error, so a
+     * successful {@code open} after a finished turn requires this close to have happened first).
+     */
+    public void close(String session, CompletableFuture<Resolution> waiter) {
+        waiters.remove(session, waiter);
+    }
+
+    /** Whether a send is currently awaiting a resolution for {@code session}. */
+    public boolean isWaiting(String session) {
+        return waiters.containsKey(session);
+    }
+
+    /**
+     * The waiter currently registered for {@code session}, or {@code null} if none is waiting. The
+     * completion/failure fallbacks capture this at delivery time so they can later resolve that exact
+     * send (see the CB-116 note above) rather than whichever send happens to be waiting when they fire.
+     */
+    public CompletableFuture<Resolution> currentWaiter(String session) {
+        return waiters.get(session);
+    }
+
+    /**
+     * Resolve the send awaiting on {@code session} with the worker's explicit reply {@code content}.
+     *
+     * @return {@code true} if a waiter was resolved; {@code false} if none was waiting (a late or
+     *         spurious reply — e.g. the send already timed out)
+     */
+    public boolean resolve(String session, String content) {
+        return complete(session, new Resolution(Kind.REPLY, content));
+    }
+
+    // --- reverse rendezvous (CB-205 bridge_ask) ------------------------------------------------
+
+    /**
+     * Open a reverse-rendezvous waiter for a worker's mid-turn question. If {@code session} already has
+     * an open ask, coalesce onto it (same {@code turnId}, same answer future). Otherwise atomically mint
+     * a fresh {@code turnId}, register it in both the per-turn and per-session indexes, and hand it back
+     * marked fresh. The caller then {@link #resolveQuestion surfaces the question} to the primary and
+     * blocks on the returned future until the primary {@link #answerAsk answers}.
+     */
+    public AskTicket openAsk(String session) {
+        while (true) {
+            AskWaiter[] minted = { null };
+            String turnId = openAsksBySession.computeIfAbsent(session, _ -> {
+                String newTurnId = session + "#" + askSeq.incrementAndGet();
+                CompletableFuture<String> answer = new CompletableFuture<>();
+                AskWaiter waiter = new AskWaiter(session, answer);
+                asks.put(newTurnId, waiter);
+                minted[0] = waiter;
+                return newTurnId;
+            });
+            if (minted[0] != null) {
+                return new AskTicket(turnId, minted[0].answer(), true);
+            }
+            AskWaiter existing = asks.get(turnId);
+            if (existing != null) {
+                return new AskTicket(turnId, existing.answer(), false);
+            }
+            // A close raced and removed the waiter after we read the turnId; clear the stale index entry
+            // and retry so a fresh ask is always backed by a registered waiter.
+            openAsksBySession.remove(session, turnId);
+        }
+    }
+
+    /**
+     * Surface a worker's mid-turn {@code question} by resolving the primary's open {@code bridge_send}
+     * with a {@link Kind#QUESTION} carrying {@code turnId}. Same session-keyed semantics as
+     * {@link #resolve}: the one outstanding send for {@code session} unblocks with the question.
+     *
+     * @return {@code true} if a send was awaiting (the question reached the primary); {@code false}
+     *         if none was (no delegation is open to answer it)
+     */
+    public boolean resolveQuestion(String session, String question, String turnId) {
+        return complete(session, new Resolution(Kind.QUESTION, question, turnId));
+    }
+
+    /** The worker session an outstanding ask {@code turnId} belongs to, or {@code null} if unknown/lapsed. */
+    public String askSession(String turnId) {
+        AskWaiter w = asks.get(turnId);
+        return w == null ? null : w.session();
+    }
+
+    /**
+     * Resolve a worker's blocked {@code bridge_ask} with the primary's {@code answer}, unblocking it
+     * to resume its turn.
+     *
+     * @return {@code true} if the ask was still open and got the answer; {@code false} if the
+     *         {@code turnId} is unknown or the ask already lapsed (timed out / was answered)
+     */
+    public boolean answerAsk(String turnId, String answer) {
+        AskWaiter w = asks.get(turnId);
+        return w != null && w.answer().complete(answer);
+    }
+
+    /** Drop a reverse-rendezvous turn once its {@code bridge_ask} has resolved (answered or lapsed). */
+    public void closeAsk(String turnId) {
+        AskWaiter w = asks.get(turnId);
+        if (w == null) {
+            return;
+        }
+        // Remove the session index first and only if it still points to this turn, so a concurrent
+        // fresh ask cannot inherit a waiter we are about to drop.
+        openAsksBySession.remove(w.session(), turnId);
+        asks.remove(turnId);
+    }
+
+    /**
+     * Resolve a specific captured {@code waiter} as a completion (the delegated turn finished with no
+     * {@code bridge_reply}); {@code text} is the scraped transcript tail. The waiter is the one
+     * captured when this turn was delivered, so a late completion for turn N cannot land on turn N+1's
+     * send (CB-116). A no-op if that waiter was already resolved — a raced {@code bridge_reply} wins.
+     *
+     * @return {@code true} if this call resolved the waiter, {@code false} if it was null or already resolved
+     */
+    public boolean resolveCompletion(CompletableFuture<Resolution> waiter, String text) {
+        return waiter != null && waiter.complete(new Resolution(Kind.COMPLETION, text));
+    }
+
+    /**
+     * Resolve a specific captured {@code waiter} as a failure — the worker ran the turn but wedged in
+     * an unrecoverable state (CB-109); {@code reason} is the failure context (e.g. the error screen).
+     * Like {@link #resolveCompletion(CompletableFuture, String)} it targets the exact captured send
+     * (CB-116). A no-op if that waiter was already resolved — first resolution wins.
+     *
+     * @return {@code true} if this call resolved the waiter, {@code false} if it was null or already resolved
+     */
+    public boolean resolveFailure(CompletableFuture<Resolution> waiter, String reason) {
+        return waiter != null && waiter.complete(new Resolution(Kind.FAILED, reason));
+    }
+
+    private boolean complete(String session, Resolution resolution) {
+        CompletableFuture<Resolution> waiter = waiters.get(session);
+        return waiter != null && waiter.complete(resolution);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/msg/ReplyInbox.java

@@ -0,0 +1,51 @@
+package dev.ltms.bridged.msg;
+
+import java.util.List;
+
+/**
+ * Holds terminal worker→primary replies that arrive with no live send to resolve, keyed by worker
+ * session (target), until the primary drains them. Soft-state in Stage 1 (in-memory, lost on restart);
+ * the Stage 2 AMQP adapter implements the same contract with cross-restart durability.
+ *
+ * <p><strong>This interface is the port.</strong> {@link InMemoryReplyInbox} is the Stage-1 adapter;
+ * an AMQP-backed adapter (Stage 2) must implement the same contract (idempotent publish, FIFO peek,
+ * at-least-once ack).
+ *
+ * <p><strong>Ownership is explicit.</strong> A gateway {@link #own owns} the inbox for each agent it
+ * spawned; only the owner consumes and drains it. {@link #publish} sends a reply to the target's
+ * inbox but does <em>not</em> imply ownership or start a consumer. This separation is required by
+ * CB-308 federation, where one gateway may publish to an agent owned by another gateway.
+ */
+public interface ReplyInbox {
+
+    /** A queued reply: an idempotency id, the worker session it came from, and the reply text. */
+    record InboxMessage(String msgId, String target, String content) {}
+
+    /**
+     * Start owning (consuming) the inbox for {@code target}. Idempotent: multiple calls for the same
+     * target are no-ops. The owner is the only gateway that may {@link #peek} and {@link #ack} replies
+     * for this target.
+     */
+    void own(String target);
+
+    /**
+     * Stop owning (consuming) the inbox for {@code target}. Idempotent. Any replies held locally but
+     * not yet acked are dropped from the local snapshot; the underlying durable queue keeps
+     * unacked messages for redelivery when the target is re-owned.
+     */
+    void release(String target);
+
+    /**
+     * Queue {@code content} from worker {@code target} under {@code msgId}. Idempotent: publishing an
+     * already-present {@code msgId} for {@code target} is a no-op (dedup), so an at-least-once Stage-2
+     * redelivery cannot double-queue. Publishing does <em>not</em> imply ownership and must not start a
+     * consumer.
+     */
+    void publish(String target, String msgId, String content);
+
+    /** Non-destructive snapshot of pending replies for {@code target} (FIFO), empty list if none. */
+    List<InboxMessage> peek(String target);
+
+    /** Remove the reply {@code msgId} for {@code target} once the primary has taken it. No-op if absent. */
+    void ack(String target, String msgId);
+}

bridged/src/main/java/dev/ltms/bridged/msg/ReplyPushLoop.java

@@ -0,0 +1,199 @@
+package dev.ltms.bridged.msg;
+
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.AgentStatus;
+import dev.ltms.bridged.mcp.PrimaryRegistry;
+import dev.ltms.bridged.metrics.BridgedMetrics;
+import dev.ltms.bridged.metrics.Metrics;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Mechanism (b) of CB-307: a dedicated, status-gated push loop that nudges the primary's own
+ * herdr pane when a worker reply lands with no live {@code bridge_send} to resolve it.
+ *
+ * <p>The loop is triggered by {@link #onReplyQueued(String)} (called from
+ * {@link MessageService#reply} after the durable inbox publish). It checks four conditions
+ * at each tick via {@link #decide(String, int)}, then either injects a drain nudge,
+ * waits for the primary to become injectable, or stops reminding.
+ *
+ * <p>Bounded: at most {@link #maxReminders} nudges per target, with a configurable backoff
+ * between them. The reply is never lost — the durable inbox is the backstop.
+ */
+public final class ReplyPushLoop {
+
+    private static final Logger log = LoggerFactory.getLogger(ReplyPushLoop.class);
+    static final String NUDGE_FORMAT = "Worker %s returned a reply — run bridge_poll(target=%s) to collect it";
+
+    private final PrimaryRegistry primaryRegistry;
+    private final AgentControl agents;
+    private final ReplyInbox inbox;
+    private final ScheduledExecutorService scheduler;
+    private final int maxReminders;
+    private final long backoffMs;
+    private final Metrics metrics; // CB-512: nullable — no registry in unit tests
+
+    /** Track targets that have an active schedule. */
+    private final ConcurrentHashMap<String, Boolean> activeTargets = new ConcurrentHashMap<>();
+
+    public ReplyPushLoop(PrimaryRegistry primaryRegistry, AgentControl agents, ReplyInbox inbox,
+                         ScheduledExecutorService scheduler,
+                         int maxReminders, long backoffMs) {
+        this(primaryRegistry, agents, inbox, scheduler, maxReminders, backoffMs, null);
+    }
+
+    /** As above, with a metric registry (CB-512) so push outcomes are counted. */
+    public ReplyPushLoop(PrimaryRegistry primaryRegistry, AgentControl agents, ReplyInbox inbox,
+                         ScheduledExecutorService scheduler,
+                         int maxReminders, long backoffMs, Metrics metrics) {
+        this.primaryRegistry = primaryRegistry;
+        this.agents = agents;
+        this.inbox = inbox;
+        this.scheduler = scheduler;
+        this.maxReminders = maxReminders;
+        this.backoffMs = backoffMs;
+        this.metrics = metrics;
+    }
+
+    /** Count one nudge outcome when a registry is wired; a no-op in unit tests. */
+    private void countNudge(String outcome) {
+        if (metrics != null) {
+            metrics.inc(BridgedMetrics.PUSH_NUDGES, "outcome", outcome);
+        }
+    }
+
+    // --- decision logic (package-private for unit-testing) -------------------------------------
+
+    /** The action the loop should take for a target at the given reminder count. */
+    enum Action { INJECT, WAIT_BUSY, STOP }
+
+    /**
+     * Pure decision function: examine the current state and return what the loop should do.
+     *
+     * @param target        the worker session (target terminal id)
+     * @param reminderCount how many nudges have been sent so far for this target
+     * @return the action the caller should take
+     */
+    Action decide(String target, int reminderCount) {
+        // CB-532: the destination is per-delegation — the lead that sent this worker its work, not
+        // "the primary". With two leads orchestrating one fleet the singular question has no right
+        // answer, and answering it anyway interrupted whichever lead happened to call bridge_send
+        // first with results it never asked for.
+        var nudgeTarget = primaryRegistry.nudgeTargetFor(target);
+        if (nudgeTarget.isEmpty()) {
+            log.debug("push: no lead is known to be waiting on {}, stopping reminder", target);
+            return Action.STOP;
+        }
+        if (inbox.peek(target).isEmpty()) {
+            log.debug("push: inbox empty for {}, stopping reminder", target);
+            return Action.STOP;
+        }
+        if (reminderCount >= maxReminders) {
+            log.debug("push: reminder cap ({}) reached for {}, stopping", maxReminders, target);
+            countNudge("exhausted");
+            return Action.STOP;
+        }
+        String leadTerminal = nudgeTarget.get();
+        AgentStatus status;
+        try {
+            status = agents.status(leadTerminal);
+        } catch (RuntimeException e) {
+            log.debug("push: status check failed for lead {}, will retry", leadTerminal, e);
+            return Action.WAIT_BUSY;
+        }
+        if (status.injectable()) {
+            return Action.INJECT;
+        }
+        log.debug("push: lead {} is {} (not injectable), waiting", leadTerminal, status);
+        return Action.WAIT_BUSY;
+    }
+
+    // --- public entrypoint ---------------------------------------------------------------------
+
+    /**
+     * Called when a reply is queued for {@code target}. Idempotent per target: a second call while
+     * a schedule is active is a no-op. The schedule nudges the primary, then schedules a follow-up
+     * check (reminder on backoff, or re-check on WAIT_BUSY), until the inbox is empty or the cap
+     * is reached.
+     */
+    public void onReplyQueued(String target) {
+        if (activeTargets.putIfAbsent(target, Boolean.TRUE) != null) {
+            log.debug("push: already active for {}, ignoring duplicate trigger", target);
+            return; // already scheduled
+        }
+        log.debug("push: starting reminder loop for {}", target);
+        scheduleNext(target, 0);
+    }
+
+    /** Execute one loop tick — called on the scheduler thread. */
+    private void tick(String target, int reminderCount) {
+        var action = decide(target, reminderCount);
+        switch (action) {
+            case INJECT -> {
+                injectNudge(target, reminderCount);
+                scheduleNext(target, reminderCount + 1);
+            }
+            // Re-check after the configured backoff; the primary may become injectable soon.
+            case WAIT_BUSY -> scheduleNext(target, reminderCount);
+            case STOP -> {
+                activeTargets.remove(target);
+                log.debug("push: reminder loop ended for {}", target);
+            }
+        }
+    }
+
+    /** Send the nudge and log the event. */
+    private void injectNudge(String target, int reminderCount) {
+        // Re-read rather than threading it down from decide(): the delegating lead can change
+        // between the decision and the injection, and the nudge should follow the current one.
+        var lead = primaryRegistry.nudgeTargetFor(target);
+        if (lead.isEmpty()) {
+            log.debug("push: lead for {} disappeared before the nudge could be sent", target);
+            return;
+        }
+        String leadTerminal = lead.get();
+        String nudge = NUDGE_FORMAT.formatted(target, target);
+        try {
+            agents.send(leadTerminal, nudge);
+            log.debug("push: nudge {}/{} sent to lead {} for target {}",
+                    reminderCount + 1, maxReminders, leadTerminal, target);
+            countNudge("delivered");
+        } catch (RuntimeException e) {
+            log.warn("push: failed to nudge lead {} for target {} (reminder {}/{}): {}",
+                    leadTerminal, target, reminderCount + 1, maxReminders, e.toString());
+        }
+    }
+
+    /** Schedule the next tick on the scheduler thread pool. */
+    private void scheduleNext(String target, int nextReminderCount) {
+        scheduler.schedule(() -> tick(target, nextReminderCount), backoffMs, TimeUnit.MILLISECONDS);
+    }
+
+    // --- lifecycle -----------------------------------------------------------------------------
+
+    /**
+     * Whether any reminder loop is currently active for some target (CB-551). The idle-lead heartbeat
+     * uses this to stand aside: while the push loop is actively nudging the lead, a concurrent
+     * heartbeat injection would start a second competing turn in the same pane — racing loops multiply
+     * turns and context burn. "Active" means a schedule exists in {@link #activeTargets}; the set is
+     * bounded by what has been triggered, not by any persistent state.
+     */
+    public boolean isActive() {
+        return !activeTargets.isEmpty();
+    }
+
+    /** Shut down the scheduler. Outstanding reminders are cancelled. */
+    public void stop() {
+        scheduler.shutdownNow();
+        activeTargets.clear();
+    }
+
+    /** @see #stop() */
+    public void close() {
+        stop();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/peer/Capability.java

@@ -0,0 +1,58 @@
+package dev.ltms.bridged.peer;
+
+/**
+ * Declared capabilities of a {@link PeerLauncher}. The protocol is the union across all
+ * configured launchers; a verb invoked against a peer that lacks the capability returns a clean
+ * "unsupported for this peer" rather than a crash. Capabilities keep the protocol honest as peers
+ * diversify and prevent the core from assuming "every peer is a Claude in a worktree."
+ */
+public enum Capability {
+
+    /**
+     * The peer supports {@code bridge_ask} rendezvous — pausing its delegated turn to ask
+     * the primary a question, then resuming once answered. All Claude Code peers support this.
+     */
+    MID_TURN_ASK,
+
+    /**
+     * The peer can open its own PR at the end of an implementation turn (CB-302). Opt-in per
+     * profile: granted only when the profile carries a git-forge token ({@code gitTokenEnv}).
+     */
+    SELF_PR,
+
+    /**
+     * The peer can run inside a provisioned isolated git worktree. All CLI-based peers support
+     * this since their cwd is set at spawn time.
+     */
+    WORKTREE,
+
+    /**
+     * The peer can discard its current conversation context without starting a delegated bridge
+     * turn. The command or API used to do that is adapter-specific.
+     */
+    CONTEXT_RESET,
+
+    /**
+     * The spawner can reconcile orphaned peers on boot — workers that outlived a prior daemon
+     * process and whose pane ids died with it (CB-117). Claude Code over herdr supports this
+     * via name-based matching against the herdr agent list.
+     */
+    ORPHAN_REAP,
+
+    /**
+     * The peer surfaces the bridge's logical name ({@link SpawnRequest#sessionName()}) in its own
+     * UI at spawn — e.g. Claude Code's {@code -n} display name, which shows in the prompt box, the
+     * {@code /resume} picker, and the terminal title. This is what lets an operator tell the
+     * bridge's worker apart from a user's own session in the same terminal after a restart.
+     */
+    SESSION_NAME,
+
+    /**
+     * The peer can be relaunched onto a prior conversation via that conversation's own session id
+     * ({@link SpawnRequest#resumeSessionId()}) — e.g. Claude Code's {@code -r}, which adopts the id
+     * as the agent's own identity rather than starting a new conversation. A launcher that declares
+     * this mints/resolves that id at spawn and exposes it on the returned
+     * {@link PeerHandle#agentSessionId()}, so a later resume addresses the same conversation.
+     */
+    SESSION_RESUME
+}

bridged/src/main/java/dev/ltms/bridged/peer/MemberRole.java

@@ -0,0 +1,122 @@
+package dev.ltms.bridged.peer;
+
+import java.util.Locale;
+
+/**
+ * What a member is <em>for</em> — the contract it runs under.
+ *
+ * <p>A member is anything a lead spawns. Every member carries two independent attributes:
+ *
+ * <ul>
+ *   <li><b>role</b> (this enum) — <em>which contract</em>: the launch charter it is given, the role
+ *       file it reads, the playbook skill it loads, and its authorization row.</li>
+ *   <li><b>profile</b> (a {@code profiles:} key) — <em>which backend</em>: model, CLI adapter,
+ *       credentials, cost.</li>
+ * </ul>
+ *
+ * <p>These are separate axes on purpose. A {@code REVIEWER} may run on the same profile as the
+ * {@code DEV} whose diff it reviews — same backend, different contract. That case is what proves
+ * role and profile cannot be collapsed into one field.
+ *
+ * <p>A lead is deliberately <em>not</em> a role here. A lead is not spawned: it is a pre-existing,
+ * human-facing session that config recognises. Only spawned peers have a member role.
+ */
+public enum MemberRole {
+
+    /**
+     * Refines a ticket before anyone implements it: scope, acceptance criteria, risks, unit split.
+     *
+     * <p>Reads the repo and writes analysis. Never commits code and never opens a pull request —
+     * an architect that starts implementing has stopped doing the job that makes it useful.
+     *
+     * <p>Architects are the one member kind declared in config, because a lead addresses the same
+     * slots across many tickets and needs a stable name for them.
+     */
+    ARCHITECT,
+
+    /**
+     * Implements one unit of work: provisions a worktree, writes the code, commits, pushes, and
+     * opens its own pull request.
+     *
+     * <p>Never merges. The lead is the gate, and a member that merged its own work would remove the
+     * only independent check in the flow.
+     */
+    DEV,
+
+    /**
+     * Reviews a diff it did not write and reports one structured finding.
+     *
+     * <p>Never commits, never merges, and is never the member that wrote the scope under review.
+     * Briefed from the diff rather than from the implementer's rationale, because that rationale
+     * carries the same blind spot that produced the bug.
+     */
+    REVIEWER;
+
+    /** The lowercase spelling used in config and on the wire ({@code architect}, {@code dev}, …). */
+    public String wireName() {
+        return name().toLowerCase(Locale.ROOT);
+    }
+
+    /**
+     * The {@code fleet:} block that holds this role's pool — {@code architects},
+     * {@code developers}, {@code reviewers}.
+     *
+     * <p>Plural, and not always the wire name: the pool of things a {@code dev} may run on reads
+     * naturally as {@code developers:}. The wire name stays the singular {@code dev}, because that
+     * is what a tab label and a roster row say.
+     */
+    public String configKey() {
+        return switch (this) {
+            case ARCHITECT -> "architects";
+            case DEV -> "developers";
+            case REVIEWER -> "reviewers";
+        };
+    }
+
+    /**
+     * The role owning the {@code fleet:} pool named {@code key}, or {@code null} when the key is not
+     * a role pool ({@code leaders}, {@code tabLabel}, …). Null rather than a throw: callers use this
+     * to sort a fleet block's children, where a non-pool key is normal rather than an error.
+     */
+    public static MemberRole fromConfigKey(String key) {
+        if (key == null) {
+            return null;
+        }
+        String k = key.trim().toLowerCase(Locale.ROOT);
+        for (MemberRole r : values()) {
+            if (r.configKey().equals(k)) {
+                return r;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Parse a config/wire spelling, case-insensitively.
+     *
+     * @param s the spelling to parse
+     * @return the matching role
+     * @throws IllegalArgumentException when {@code s} is null, blank, or not a known role — the
+     *                                  message lists the valid spellings, because a typo'd role in
+     *                                  config should fail at startup with the fix in the error
+     */
+    public static MemberRole parse(String s) {
+        if (s != null && !s.isBlank()) {
+            String t = s.trim().toLowerCase(Locale.ROOT);
+            for (MemberRole r : values()) {
+                if (r.wireName().equals(t)) {
+                    return r;
+                }
+            }
+        }
+        StringBuilder valid = new StringBuilder();
+        for (MemberRole r : values()) {
+            if (!valid.isEmpty()) {
+                valid.append(", ");
+            }
+            valid.append(r.wireName());
+        }
+        throw new IllegalArgumentException(
+                "unknown member role '" + s + "'; valid roles are: " + valid);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/peer/PeerHandle.java

@@ -0,0 +1,70 @@
+package dev.ltms.bridged.peer;
+
+/**
+ * An opaque handle returned by {@link PeerLauncher#spawn(SpawnRequest)}. The core routes on
+ * {@link #id()} (the registry/routing key) and uses {@link #terminalId()} for session tracking;
+ * launcher-private coordinates beyond these are reachable through the concrete implementation.
+ *
+ * <p>A {@link PeerHandle} is returned <em>after</em> the peer process is live — the launcher
+ * has already completed subscription-guarded env/vfs setup, process start, and placement. The
+ * handle is a ticket the core exchanges for the running peer, not a lazy/delayed reference.
+ */
+public interface PeerHandle {
+
+    /**
+     * The registry/routing key — an opaque, launcher-assigned identifier (CB-519). Multiple
+     * daemon processes may run on one host, so the contract is <em>host-unique</em>, not merely
+     * process-unique: the herdr-backed launcher mints a fresh UUID per spawn, and a non-herdr
+     * launcher is likewise expected to return an identifier that cannot collide across processes
+     * on the same host. This id is the routing key and is deliberately decoupled from any launcher
+     * transport coordinate (e.g. a herdr pane id), which stays launcher-private. Guaranteed to be
+     * non-null and unique among live peers on the host.
+     */
+    String id();
+
+    /**
+     * The transport-level session identifier used for message routing and presence tracking.
+     * For the herdr launcher this is the herdr terminal UUID. A non-herdr launcher may return
+     * its own analogous identifier, or {@code null} if the concept does not apply.
+     */
+    default String terminalId() {
+        return null;
+    }
+
+    /**
+     * The worker profile that spawned this peer, if the launcher resolved one. A launcher that
+     * performs dynamic profile selection (e.g. CB-518 weighted placement) sets this so the
+     * session registry records the actual profile rather than the requested/default one.
+     *
+     * @return the profile name, or {@code null} when the launcher leaves it unspecified
+     */
+    default String profile() {
+        return null;
+    }
+
+    /**
+     * The bridge's logical name for this session, as assigned at spawn
+     * ({@link SpawnRequest#sessionName()}). Stable across restarts and meaningful to an operator,
+     * unlike the transport identifiers above; a launch with no name leaves the peer's display
+     * identity to the launcher to derive.
+     *
+     * @return the bridge-assigned logical session name, or {@code null} if none was assigned
+     */
+    default String sessionName() {
+        return null;
+    }
+
+    /**
+     * The peer's OWN session id — the handle that resumes this conversation later (the id a
+     * later {@link Capability#SESSION_RESUME resume} spawn would pass back). Null when the adapter
+     * cannot determine it — the contract for an adapter that declines
+     * {@link Capability#SESSION_RESUME}; an adapter that declares that capability returns this
+     * non-null for a spawn that requested session identity, because it knows the id before the
+     * peer has written anything.
+     *
+     * @return the peer's own session id, or {@code null} when not determinable
+     */
+    default String agentSessionId() {
+        return null;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/peer/PeerLauncher.java

@@ -0,0 +1,94 @@
+package dev.ltms.bridged.peer;
+
+import java.util.List;
+import java.util.Set;
+
+/**
+ * SPI for materializing a connected peer — the only way the bridge core creates or tears down
+ * a peer process. Every launcher is a first-party, in-tree adapter selected by (future) profile
+ * config; today's single adapter is the {@code ClaudeCodeLauncher} / Claude Code over herdr.
+ *
+ * <p>The core delegates spawn and teardown to this interface without knowing how the peer is set
+ * up. Environment variables, CLI flags, subscription guards, transport (herdr tab/pane) layout,
+ * and naming conventions are all adapter-private — the core sees only the returned
+ * {@link PeerHandle} whose {@code id()} is the registry/routing key.
+ *
+ * <p>The interface is a superset of what {@code SessionManager} and {@code Bridged.main} call
+ * on the concrete launcher today.
+ */
+public interface PeerLauncher {
+
+    /**
+     * The set of {@link Capability capabilities} this launcher declares. A peer whose profile
+     * opts into a git-forge token should include {@link Capability#SELF_PR}; the base set for
+     * the Claude Code herdr adapter is always {@code MID_TURN_ASK, WORKTREE, ORPHAN_REAP}.
+     */
+    Set<Capability> capabilities();
+
+    /**
+     * {@code profileName}/requestedCwd null/blank → default resolution. Returns after the peer
+     * process is live (env + argv + placement complete). Never returns {@code null}.
+     *
+     * @param req the spawn parameters (profile, requested cwd, caller cwd)
+     * @return a handle whose {@link PeerHandle#id()} is the registry/routing key
+     * @throws IllegalArgumentException if the profile is unknown and no default is configured
+     */
+    PeerHandle spawn(SpawnRequest req);
+
+    /**
+     * The configured worker profile names — the set of names {@code spawn(profileName)} accepts.
+     */
+    Set<String> profiles();
+
+    /**
+     * The profile a no-argument {@link #spawn(SpawnRequest)} uses, or {@code null} if none is configured.
+     */
+    String defaultProfile();
+
+    /**
+     * Resolve the effective working directory for a spawn {@code req} without actually spawning.
+     * Resolution order: requestedCwd → profile cwd → callerCwd → daemon cwd.
+     *
+     * @return the resolved absolute path, never null/blank
+     */
+    String effectiveCwd(SpawnRequest req);
+
+    /**
+     * The parity-overlay file list for {@code profileName} (default list when unset). Used by
+     * worktree provisioning to copy config files into the isolated checkout before spawning.
+     */
+    List<String> parityOverlay(String profileName);
+
+    /**
+     * The set of all agents this launcher currently tracks, transport-specific. Each element
+     * exposes at minimum a pane-like {@code id()} matching this launcher's {@link PeerHandle}
+     * scheme, plus transport-level status. Callers merge this set with the session registry to
+     * build a live roster view.
+     */
+    List<?> list();
+
+    /**
+     * Reap orphaned peers left behind by a prior daemon process. Only peers whose naming scheme
+     * matches this launcher's and whose nonce differs from the current process are eligible.
+     * Best-effort: a failure to list or to stop any one peer is logged and never aborts startup.
+     *
+     * @return the number of orphaned peers reaped
+     */
+    int reapOrphanWorkers();
+
+    /**
+     * Tear a peer down by its registry/routing key ({@link PeerHandle#id()}). Tolerates an
+     * already-gone peer. Also cleans up launcher-private resources (e.g. empty dedicated tabs)
+     * when safe to do so.
+     */
+    void stop(String id);
+
+    /**
+     * Discard the context of the peer identified by {@code id}. Implementations must bypass normal
+     * bridge delivery/turn accounting. Unsupported peer kinds return {@code false} without sending
+     * a guessed command.
+     *
+     * @return {@code true} when a reset was sent and its status transition must settle before reuse
+     */
+    boolean clearContext(String id);
+}

bridged/src/main/java/dev/ltms/bridged/peer/PeerUnreachableException.java

@@ -0,0 +1,18 @@
+package dev.ltms.bridged.peer;
+
+/**
+ * Thrown when a {@link PeerLauncher} starts a peer process but the peer
+ * does not reach an injectable (ready-to-receive) state within the configured
+ * timeout. The launcher MUST clean up any resources it created (pane, tab)
+ * before throwing — no orphaned peer or pane is left behind.
+ *
+ * <p>This is a spawn-time failure, distinct from a post-spawn disconnect.
+ * Callers treat this as a clean spawn error (the peer never materialized
+ * into a usable session), not a mid-life session fault.
+ */
+public final class PeerUnreachableException extends RuntimeException {
+
+    public PeerUnreachableException(String message) {
+        super(message);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/peer/SpawnRequest.java

@@ -0,0 +1,32 @@
+package dev.ltms.bridged.peer;
+
+/**
+ * What a caller asks for when spawning a peer.
+ *
+ * @param profileName     the {@code profiles:} entry to spawn on; {@code null}/blank ⇒ the caller
+ *                        did not choose, and the role's pool supplies the candidates
+ * @param requestedCwd    working directory asked for by the caller ({@code null} ⇒ unset)
+ * @param callerCwd       the caller's own working directory, used when nothing else pins one
+ * @param sessionName     agent session name (CB-547a); {@code null} ⇒ the launcher mints one
+ * @param resumeSessionId prior agent session to resume; {@code null} ⇒ a fresh session
+ * @param role            the contract this member runs under (CB-557). Picks the tab label and,
+ *                        with the profile, the counter its tab number comes from. {@code null} is
+ *                        read as {@link MemberRole#DEV} — an unqualified spawn is a unit of work
+ */
+public record SpawnRequest(String profileName, String requestedCwd, String callerCwd,
+                           String sessionName, String resumeSessionId, MemberRole role) {
+
+    public SpawnRequest {
+        role = (role == null) ? MemberRole.DEV : role;
+    }
+
+    public SpawnRequest(String profileName, String requestedCwd, String callerCwd) {
+        this(profileName, requestedCwd, callerCwd, null, null, null);
+    }
+
+    /** Pre-CB-557 shape: session identity without an explicit role (defaults to {@code dev}). */
+    public SpawnRequest(String profileName, String requestedCwd, String callerCwd,
+                        String sessionName, String resumeSessionId) {
+        this(profileName, requestedCwd, callerCwd, sessionName, resumeSessionId, null);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/FixedPlacementPolicy.java

@@ -0,0 +1,22 @@
+package dev.ltms.bridged.placement;
+
+/**
+ * Backward-compatible placement: an unqualified spawn always resolves to the configured default
+ * profile, exactly as {@code CompositePeerLauncher} did before CB-518. This ignores caps and
+ * reachability so that a pre-existing config behaves identically after upgrade.
+ */
+final class FixedPlacementPolicy implements PlacementPolicy {
+
+    @Override
+    public PlacementCandidate select(PlacementContext ctx) {
+        String d = ctx.defaultProfile();
+        if (d != null && !d.isBlank()) {
+            return new PlacementCandidate(d, null, 1.0f, null);
+        }
+        if (!ctx.candidates().isEmpty()) {
+            PlacementCandidate first = ctx.candidates().getFirst();
+            return new PlacementCandidate(first.profile(), null, first.weight(), first.maxLoad());
+        }
+        throw new PlacementException("no worker profiles configured");
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/PlacementCandidate.java

@@ -0,0 +1,20 @@
+package dev.ltms.bridged.placement;
+
+/**
+ * A profile (and, in CB-308, a host) that can be chosen by a {@link PlacementPolicy}.
+ *
+ * <p>Keeping this as a small descriptor rather than a bare profile name lets CB-308 widen
+ * selection to {@code (host, profile)} pairs without changing the policy interface.
+ */
+public record PlacementCandidate(String profile, String host, float weight, Integer maxLoad) {
+
+    /** A candidate with no explicit host (the single-host default) and the given weight/cap. */
+    public static PlacementCandidate profile(String profile, float weight, Integer maxLoad) {
+        return new PlacementCandidate(profile, null, weight, maxLoad);
+    }
+
+    /** A candidate with no explicit host, unit weight, and no cap. */
+    public static PlacementCandidate profile(String profile) {
+        return new PlacementCandidate(profile, null, 1.0f, null);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/PlacementContext.java

@@ -0,0 +1,19 @@
+package dev.ltms.bridged.placement;
+
+import java.util.List;
+import java.util.Set;
+import java.util.function.Function;
+
+/**
+ * Everything a {@link PlacementPolicy} needs to make one selection.
+ *
+ * @param defaultProfile profile a {@code fixed} policy should return (may be {@code null})
+ * @param candidates     every configured candidate; the policy filters out those at cap or unreachable
+ * @param liveCount      current live worker count per profile (from the session registry)
+ * @param unreachable    profiles already known to have failed in this spawn attempt
+ */
+public record PlacementContext(String defaultProfile,
+                               List<PlacementCandidate> candidates,
+                               Function<String, Integer> liveCount,
+                               Set<String> unreachable) {
+}

bridged/src/main/java/dev/ltms/bridged/placement/PlacementException.java

@@ -0,0 +1,12 @@
+package dev.ltms.bridged.placement;
+
+/**
+ * Thrown when a {@link PlacementPolicy} has no candidate available. Kept as a distinct type so
+ * callers can distinguish "no capacity" from a spawn-time transport failure.
+ */
+public final class PlacementException extends IllegalStateException {
+
+    public PlacementException(String message) {
+        super(message);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/PlacementPolicies.java

@@ -0,0 +1,41 @@
+package dev.ltms.bridged.placement;
+
+/**
+ * Factory for the built-in placement policies.
+ */
+public final class PlacementPolicies {
+
+    private PlacementPolicies() {
+    }
+
+    /**
+     * Resolve a policy name from config. Absent/blank values and {@code "fixed"} return the
+     * backward-compatible fixed policy; unknown names throw.
+     */
+    public static PlacementPolicy fromName(String name) {
+        String n = (name == null) ? "" : name.toLowerCase();
+        if (n.isBlank() || "fixed".equals(n)) {
+            return fixed();
+        }
+        if ("weighted".equals(n)) {
+            return weighted();
+        }
+        if ("round-robin".equals(n)) {
+            return roundRobin();
+        }
+        throw new IllegalArgumentException("unknown placement policy '" + name
+                + "' — must be one of: fixed, round-robin, weighted");
+    }
+
+    public static PlacementPolicy fixed() {
+        return new FixedPlacementPolicy();
+    }
+
+    public static PlacementPolicy weighted() {
+        return new WeightedRoundRobinPolicy();
+    }
+
+    public static PlacementPolicy roundRobin() {
+        return new RoundRobinPlacementPolicy();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/PlacementPolicy.java

@@ -0,0 +1,16 @@
+package dev.ltms.bridged.placement;
+
+/**
+ * How {@code bridged} chooses a worker profile when a spawn names none. Implementations are
+ * deterministic and unit-testable; the caller (the composite launcher) handles failover retries.
+ */
+public interface PlacementPolicy {
+
+    /**
+     * Pick one candidate from the configured set.
+     *
+     * @throws java.lang.IllegalStateException when no candidate is available, with a message naming
+     *                                       whether every profile is at capacity or unreachable
+     */
+    PlacementCandidate select(PlacementContext ctx);
+}

bridged/src/main/java/dev/ltms/bridged/placement/PlacementPolicyUtil.java

@@ -0,0 +1,65 @@
+package dev.ltms.bridged.placement;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Shared filtering and empty-set reporting used by the built-in placement policies.
+ */
+final class PlacementPolicyUtil {
+
+    private PlacementPolicyUtil() {
+    }
+
+    /**
+     * Candidates that are not known-unreachable and have not reached their maxLoad.
+     * A {@code null} maxLoad means unlimited.
+     */
+    static List<PlacementCandidate> available(PlacementContext ctx) {
+        List<PlacementCandidate> out = new ArrayList<>();
+        for (PlacementCandidate c : ctx.candidates()) {
+            if (ctx.unreachable().contains(c.profile())) {
+                continue;
+            }
+            Integer cap = c.maxLoad();
+            if (cap != null) {
+                int live = ctx.liveCount().apply(c.profile());
+                if (live >= cap) {
+                    continue;
+                }
+            }
+            out.add(c);
+        }
+        return out;
+    }
+
+    /**
+     * Build a clear exception describing why every candidate was dropped: all at capacity,
+     * all unreachable, or a mix.
+     */
+    static PlacementException emptyException(PlacementContext ctx) {
+        int atCap = 0;
+        int unreachable = 0;
+        for (PlacementCandidate c : ctx.candidates()) {
+            Integer cap = c.maxLoad();
+            if (ctx.unreachable().contains(c.profile())) {
+                unreachable++;
+            } else if (cap != null && ctx.liveCount().apply(c.profile()) >= cap) {
+                atCap++;
+            }
+        }
+
+        int total = ctx.candidates().size();
+        if (total == 0) {
+            return new PlacementException("no worker profiles configured");
+        }
+        if (atCap == total) {
+            return new PlacementException("all worker profiles are at maxLoad");
+        }
+        if (unreachable == total) {
+            return new PlacementException("all worker profiles are unreachable");
+        }
+        return new PlacementException("no worker profile available: " + atCap + " at maxLoad, "
+                + unreachable + " unreachable, " + (total - atCap - unreachable) + " remaining");
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/RoundRobinPlacementPolicy.java

@@ -0,0 +1,23 @@
+package dev.ltms.bridged.placement;
+
+import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * Deterministic round-robin over the profiles that still have capacity and are not known to be
+ * unreachable. The index advances only on successful selections so the distribution stays even
+ * across spawns.
+ */
+final class RoundRobinPlacementPolicy implements PlacementPolicy {
+
+    private final AtomicInteger index = new AtomicInteger(0);
+
+    @Override
+    public synchronized PlacementCandidate select(PlacementContext ctx) {
+        List<PlacementCandidate> available = PlacementPolicyUtil.available(ctx);
+        if (available.isEmpty()) {
+            throw PlacementPolicyUtil.emptyException(ctx);
+        }
+        return available.get(index.getAndIncrement() % available.size());
+    }
+}

bridged/src/main/java/dev/ltms/bridged/placement/WeightedRoundRobinPolicy.java

@@ -0,0 +1,50 @@
+package dev.ltms.bridged.placement;
+
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Smooth weighted round-robin (nginx-style): for each selection, add the candidate's weight to
+ * its current score, pick the highest score, then subtract the total weight of all available
+ * candidates from the winner. Weights are not required to sum to 1.0; only their ratios matter.
+ *
+ * <p>The state is per-policy instance and protected by {@code synchronized} so concurrent spawns
+ * see a consistent, deterministic sequence rather than interleaving updates.
+ */
+final class WeightedRoundRobinPolicy implements PlacementPolicy {
+
+    private final Map<String, Double> current = new ConcurrentHashMap<>();
+
+    @Override
+    public synchronized PlacementCandidate select(PlacementContext ctx) {
+        List<PlacementCandidate> available = PlacementPolicyUtil.available(ctx);
+        if (available.isEmpty()) {
+            throw PlacementPolicyUtil.emptyException(ctx);
+        }
+
+        double total = 0.0;
+        for (PlacementCandidate c : available) {
+            total += c.weight();
+        }
+        if (total <= 0.0) {
+            throw new PlacementException("all available profiles have non-positive weight");
+        }
+
+        PlacementCandidate best = null;
+        double bestScore = Double.NEGATIVE_INFINITY;
+        for (PlacementCandidate c : available) {
+            double score = current.merge(c.profile(), (double) c.weight(), (old, add) -> old + add);
+            if (score > bestScore) {
+                bestScore = score;
+                best = c;
+            }
+        }
+        if (best == null) {
+            throw new PlacementException("no placement candidate could be selected");
+        }
+
+        current.put(best.profile(), current.get(best.profile()) - total);
+        return best;
+    }
+}

bridged/src/main/java/dev/ltms/bridged/rest/BridgedApp.java

@@ -1,18 +1,35 @@
 package dev.ltms.bridged.rest;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.ltms.bridged.auth.AuditLog;
+import dev.ltms.bridged.auth.Authz;
+import dev.ltms.bridged.auth.CallerResolver;
+import dev.ltms.bridged.auth.Principal;
 import dev.ltms.bridged.guard.GuardException;
+import dev.ltms.bridged.metrics.Metrics;
 import dev.ltms.bridged.herdr.Agent;
 import dev.ltms.bridged.herdr.HerdrClient;
 import dev.ltms.bridged.herdr.HerdrException;
-import dev.ltms.bridged.worker.WorkerService;
+import dev.ltms.bridged.inject.MemberPresence;
+import dev.ltms.bridged.peer.PeerUnreachableException;
+import dev.ltms.bridged.msg.MessageService;
+import dev.ltms.bridged.session.SessionManager;
+import dev.ltms.bridged.peer.MemberRole;
+import dev.ltms.bridged.session.MemberSession;
+import dev.ltms.bridged.session.WorktreeRequest;
+import dev.ltms.bridged.peer.PeerLauncher;
 import io.javalin.Javalin;
 import io.javalin.http.Context;
+import jakarta.servlet.http.HttpServlet;
+import org.eclipse.jetty.servlet.ServletHolder;
 
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
 
 /**
  * The REST surface — {@code bridged}'s contract and its testability seam. Every
@@ -25,25 +42,141 @@ import java.util.Map;
  */
 public final class BridgedApp {
 
-    private final HerdrClient herdr;
-    private final WorkerService workers;
+    /** Default blocking window for a message; kept under typical HTTP idle timeouts. */
+    private static final long DEFAULT_MESSAGE_TIMEOUT_MS = 25_000;
+    private static final long MAX_MESSAGE_TIMEOUT_MS = 120_000;
+    /** Blocking window for a worker's bridge_ask (CB-205); the worker's MCP client caps its own call. */
+    private static final long DEFAULT_ASK_TIMEOUT_MS = 55_000;
+    private static final long MAX_ASK_TIMEOUT_MS = 115_000;
 
-    public BridgedApp(HerdrClient herdr, WorkerService workers) {
+    /** Context attribute under which the resolved caller is stashed by the auth filter. */
+    private static final String CALLER = "bridged.caller";
+
+    private final HerdrClient herdr;
+    private final PeerLauncher workers;
+    private final SessionManager sessions; // CB-301: authoritative session registry
+    private final MessageService messages;
+    private final MemberPresence presence; // CB-113: which workers are MCP-connected (available)
+    private final HttpServlet mcpServlet; // MCP Streamable-HTTP endpoint, mounted at /mcp (nullable)
+    private final CallerResolver auth;    // CB-501: null → authz not enforced (legacy behaviour)
+    private final Metrics metrics;        // CB-502: null → /metrics not exposed
+    private final ObjectMapper mapper = new ObjectMapper();
+
+    /**
+     * Legacy constructor — no identity resolution and no authorization, exactly as the REST surface
+     * behaved before CB-501. Retained so existing acceptance tests keep exercising handler
+     * behaviour without each needing an auth fixture.
+     */
+    public BridgedApp(HerdrClient herdr, PeerLauncher workers, SessionManager sessions,
+                      MessageService messages, MemberPresence presence,
+                      HttpServlet mcpServlet) {
+        this(herdr, workers, sessions, messages, presence, mcpServlet, null, null);
+    }
+
+    /**
+     * @param auth    resolves each request's {@link Principal}; {@code null} disables authorization
+     *                entirely (legacy). {@code main} always supplies one.
+     * @param metrics registry to instrument and expose at {@code GET /metrics}; {@code null} omits
+     *                the endpoint
+     */
+    public BridgedApp(HerdrClient herdr, PeerLauncher workers, SessionManager sessions,
+                      MessageService messages, MemberPresence presence,
+                      HttpServlet mcpServlet, CallerResolver auth, Metrics metrics) {
         this.herdr = herdr;
         this.workers = workers;
+        this.sessions = sessions;
+        this.messages = messages;
+        this.presence = presence;
+        this.mcpServlet = mcpServlet;
+        this.auth = auth;
+        this.metrics = metrics;
     }
 
     /** Wire routes onto a fresh, unstarted Javalin instance. Caller starts it. */
     public Javalin build() {
-        Javalin app = Javalin.create(cfg -> cfg.showJavalinBanner = false);
+        Javalin app = Javalin.create(cfg -> {
+            cfg.showJavalinBanner = false;
+            if (mcpServlet != null) {
+                // The MCP server shares the daemon's port; Jetty routes /mcp to its servlet.
+                cfg.jetty.modifyServletContextHandler(h ->
+                        h.addServlet(new ServletHolder(mcpServlet), "/mcp"));
+            }
+        });
+        // CB-501: resolve identity once per request, before any handler. /mcp does NOT pass through
+        // here — it is a raw servlet on Jetty's context handler — so BridgeMcp enforces separately
+        // against the same CallerResolver. Any check that lives in only one place is not a control.
+        if (auth != null) {
+            app.before(ctx -> ctx.attribute(CALLER,
+                    auth.resolve(ctx.req().getRemoteAddr(), ctx.req().getRemotePort(),
+                            ctx.header("Authorization"))));
+        }
         app.get("/healthz", this::healthz);
+        if (metrics != null) {
+            app.get("/metrics", this::metrics);
+        }
         app.get("/sessions", this::sessions);
         app.get("/agents", this::agents);
-        app.post("/workers", this::spawnWorker);
-        app.delete("/workers/{paneId}", this::stopWorker);
+        app.get("/members", this::listMembers);                  // CB-304: registry roster + live herdr status
+        app.get("/profiles", this::profiles);                    // configured backend profiles
+        app.post("/members", this::spawnMember);                 // optional ?role=&profile= or {"role":…,"profile":…}
+        app.delete("/members/{paneId}", this::stopMember);
+        app.post("/sessions/{id}/message", this::sendMessage);   // bridge_send (primary; blocking, wait:false, or answer via turnId)
+        app.post("/sessions/{id}/reply", this::replyMessage);    // bridge_reply (worker)
+        app.get("/sessions/{id}/replies", this::drainReplies);   // drain reply inbox (CB-307)
+        app.post("/sessions/{id}/ask", this::askMessage);        // bridge_ask (worker → primary, CB-205)
+        app.get("/sessions/{id}/status", this::sessionStatus);   // bridge_status
+        app.get("/tasks/{ticket}", this::taskStatus);            // poll an async (wait:false) send
         return app;
     }
 
+    /**
+     * Gate a handler on the CB-505 authorization table. Returns {@code true} when the request may
+     * proceed; otherwise writes the error response and returns {@code false}.
+     *
+     * <p>401 vs 403 is a real distinction here: 401 means "you presented no usable identity" (a
+     * credential problem the caller can fix), 403 means "you are authenticated, but this is not
+     * yours" (a worker reaching for another worker's session, or for orchestration).
+     */
+    private boolean allow(Context ctx, Authz.Action action, String target) {
+        if (auth == null) {
+            return true; // legacy: authorization not enforced
+        }
+        Principal caller = ctx.attribute(CALLER);
+        if (Authz.permits(caller, action, target)) {
+            if (action != Authz.Action.READ && action != Authz.Action.METRICS) {
+                AuditLog.allowed(caller, action, target); // reads would drown the trail
+            }
+            return true;
+        }
+        if (Authz.isUnauthenticated(caller)) {
+            AuditLog.denied(caller, action, target, "unauthenticated");
+            countAuthFailure("unauthenticated");
+            ctx.status(401).json(Map.of("error", "unauthenticated",
+                    "detail", "present Authorization: Bearer <token>"));
+        } else {
+            AuditLog.denied(caller, action, target, "forbidden");
+            countAuthFailure("forbidden");
+            ctx.status(403).json(Map.of("error", "forbidden",
+                    "detail", caller.describe() + " may not " + action + " on "
+                            + (target == null ? "this resource" : target)));
+        }
+        return false;
+    }
+
+    private void countAuthFailure(String reason) {
+        if (metrics != null) {
+            metrics.inc("bridged_auth_failures_total", "reason", reason);
+        }
+    }
+
+    /** Prometheus scrape endpoint (CB-502). */
+    private void metrics(Context ctx) {
+        if (!allow(ctx, Authz.Action.METRICS, null)) {
+            return;
+        }
+        ctx.status(200).contentType("text/plain; version=0.0.4; charset=utf-8").result(metrics.render());
+    }
+
     /** Liveness + herdr reachability. 200 when herdr answers ping, 503 otherwise. */
     private void healthz(Context ctx) {
         try {
@@ -63,6 +196,9 @@ public final class BridgedApp {
 
     /** Sessions view derived from herdr {@code workspace.list} (one workspace → one row). */
     private void sessions(Context ctx) {
+        if (!allow(ctx, Authz.Action.READ, null)) {
+            return;
+        }
         JsonNode result = herdr.call("workspace.list");
         List<Map<String, Object>> out = new ArrayList<>();
         for (JsonNode w : result.path("workspaces")) {
@@ -78,25 +214,333 @@ public final class BridgedApp {
 
     /** Discovery: every agent herdr tracks, keyed by its Claude session UUID. */
     private void agents(Context ctx) {
-        ctx.status(200).json(Map.of("agents", workers.list().stream().map(BridgedApp::view).toList()));
+        if (!allow(ctx, Authz.Action.READ, null)) {
+            return;
+        }
+        ctx.status(200).json(Map.of("agents",
+                workers.list().stream().map(Agent.class::cast).map(BridgedApp::view).toList()));
     }
 
-    /** Spawn a guard-checked worker. 403 if the base_url would breach the subscription boundary. */
-    private void spawnWorker(Context ctx) {
+    /** CB-304: bridge-owned roster merged with live herdr status by paneId. */
+    private void listMembers(Context ctx) {
+        if (!allow(ctx, Authz.Action.READ, null)) {
+            return;
+        }
+        // CB-519: the registry key is a host-unique id, not the pane coordinate — join on terminal.
+        Map<String, Agent> live = workers.list().stream()
+                .map(Agent.class::cast)
+                .filter(a -> a.terminalId() != null)
+                .collect(Collectors.toMap(Agent::terminalId, Function.identity(), (_, b) -> b));
+        List<Map<String, Object>> out = sessions.roster().stream()
+                .map(s -> SessionManager.rosterView(s, live.get(s.terminalId())))
+                .toList();
+        ctx.status(200).json(Map.of("workers", out));
+    }
+
+    /** The configured worker profiles and which one a no-argument spawn uses. */
+    private void profiles(Context ctx) {
+        if (!allow(ctx, Authz.Action.READ, null)) {
+            return;
+        }
+        ctx.status(200).json(Map.of(
+                "profiles", workers.profiles(),
+                "default", workers.defaultProfile() == null ? "" : workers.defaultProfile()));
+    }
+
+    /**
+     * Spawn a guard-checked worker. An optional {@code profile} (query param or {@code {"profile":…}}
+     * body) picks which configured profile; omitted → the default. 403 if the base_url would breach
+     * the subscription boundary, 400 for an unknown profile.
+     */
+    private void spawnMember(Context ctx) {
+        if (!allow(ctx, Authz.Action.SPAWN, null)) {
+            return;
+        }
+        String role = ctx.queryParam("role");
+        String profile = ctx.queryParam("profile");
+        String cwd = ctx.queryParam("cwd");
+        String worktree = ctx.queryParam("worktree");
+        String ticket = ctx.queryParam("ticket");
+        if (profile == null || profile.isBlank() || cwd == null || cwd.isBlank()
+                || worktree == null || worktree.isBlank()) {
+            try {
+                String body = ctx.body();
+                if (!body.isBlank()) {
+                    JsonNode b = mapper.readTree(body);
+                    if (role == null || role.isBlank()) role = b.path("role").asText(null);
+                    if (profile == null || profile.isBlank()) profile = b.path("profile").asText(null);
+                    if (cwd == null || cwd.isBlank()) cwd = b.path("cwd").asText(null);
+                    if (worktree == null || worktree.isBlank()) worktree = b.path("worktree").asText(null);
+                    if (ticket == null || ticket.isBlank()) ticket = b.path("ticket").asText(null);
+                }
+            } catch (Exception ignored) {
+                // A malformed/empty body just means "no overrides" → fall through to defaults.
+            }
+        }
+        WorktreeRequest wt = worktreeRequest(worktree, ticket);
+        MemberRole memberRole;
         try {
-            Agent worker = workers.spawn();
-            ctx.status(201).json(view(worker));
+            memberRole = (role == null || role.isBlank()) ? MemberRole.DEV : MemberRole.parse(role);
+        } catch (IllegalArgumentException e) {
+            ctx.status(400).json(Map.of("error", "unknown_role", "detail", e.getMessage()));
+            return;
+        }
+        try {
+            // No MCP caller over REST, so callerCwd and ownerTerminal are null.
+            MemberSession member = sessions.acquire(blankToNull(profile), memberRole,
+                    blankToNull(cwd), null, null, wt);
+            ctx.status(201).json(view(member));
         } catch (GuardException e) {
             ctx.status(403).json(Map.of("error", "subscription_boundary", "detail", e.getMessage()));
+        } catch (IllegalArgumentException e) {
+            ctx.status(400).json(Map.of("error", "unknown_profile", "detail", e.getMessage()));
+        } catch (PeerUnreachableException e) {
+            ctx.status(502).json(Map.of("error", "spawn_timeout", "detail", e.getMessage()));
         }
     }
 
+    private static WorktreeRequest worktreeRequest(String worktree, String ticket) {
+        if (worktree == null || worktree.isBlank() || "false".equalsIgnoreCase(worktree)) {
+            return null;
+        }
+        if ("true".equalsIgnoreCase(worktree)) {
+            if (ticket == null || ticket.isBlank()) {
+                throw new IllegalArgumentException("worktree=true requires a ticket slug");
+            }
+            return new WorktreeRequest(ticket, null);
+        }
+        return new WorktreeRequest(worktree, null);
+    }
+
+    private static String blankToNull(String s) {
+        return (s == null || s.isBlank()) ? null : s;
+    }
+
     /** Tear a worker down by pane id. */
-    private void stopWorker(Context ctx) {
-        workers.stop(ctx.pathParam("paneId"));
+    private void stopMember(Context ctx) {
+        String paneId = ctx.pathParam("paneId");
+        if (!allow(ctx, Authz.Action.STOP, paneId)) {
+            return;
+        }
+        sessions.release(paneId);
         ctx.status(204);
     }
 
+    /**
+     * The blocking delegation call (CB-104): inject {@code content} into the worker via the
+     * status-gated injector and block until the worker returns a structured {@code bridge_reply}.
+     * Times out with a typed 202 (working / queued / busy) rather than an error — the message may
+     * still land.
+     */
+    private void sendMessage(Context ctx) {
+        String id = ctx.pathParam("id");
+        if (!allow(ctx, Authz.Action.SEND, id)) {
+            return;
+        }
+        String content;
+        String turnId;
+        long timeout;
+        boolean wait;
+        try {
+            JsonNode body = mapper.readTree(ctx.body());
+            content = body.path("content").asText("");
+            turnId = body.path("turnId").asText(null);
+            timeout = body.path("timeoutMs").asLong(DEFAULT_MESSAGE_TIMEOUT_MS);
+            wait = body.path("wait").asBoolean(true); // default: block for the reply (CB-104)
+        } catch (Exception e) {
+            ctx.status(400).json(Map.of("error", "bad_request", "detail", "body must be JSON"));
+            return;
+        }
+        if (content.isBlank()) {
+            ctx.status(400).json(Map.of("error", "bad_request", "detail", "content is required"));
+            return;
+        }
+        timeout = Math.clamp(timeout, 1, MAX_MESSAGE_TIMEOUT_MS);
+
+        // Answering a worker's bridge_ask (CB-205): always blocks, and derives the worker from turnId.
+        if (turnId != null && !turnId.isBlank()) {
+            writeReply(ctx, id, messages.answer(turnId, content, timeout), timeout);
+            return;
+        }
+
+        if (!wait) {
+            // Fire-and-poll (CB-107): return a ticket immediately; the caller polls GET /tasks/{ticket}.
+            String ticket = messages.sendAsync(id, content);
+            ctx.status(202).json(Map.of("sessionId", id, "ticket", ticket, "status", "accepted"));
+            return;
+        }
+
+        try {
+            writeReply(ctx, id, messages.send(id, content, timeout), timeout);
+        } catch (HerdrException e) {
+            herdrError(ctx, e);
+        }
+    }
+
+    /**
+     * Render a {@link MessageService.Reply} onto the response — shared by a normal send and a
+     * bridge_ask answer. A structured/scraped completion is 200; a worker's mid-turn question a 202
+     * (with its {@code turnId}); a stale answer a 409; every other non-terminal outcome a typed 202.
+     */
+    private void writeReply(Context ctx, String id, MessageService.Reply reply, long timeout) {
+        switch (reply.outcome()) {
+            case QUESTION -> ctx.status(202).json(Map.of(
+                    "sessionId", id, "status", "question",
+                    "question", reply.text(), "turnId", reply.turnId()));
+            case STALE_TURN -> ctx.status(409).json(Map.of(
+                    "sessionId", id, "error", "stale_turn",
+                    "detail", "that question is no longer open (timed out or already answered)"));
+            case REPLIED, COMPLETED_UNREPLIED -> {
+                // replySource distinguishes a structured bridge_reply from the CB-106 completion
+                // fallback (a scrape of the worker's transcript when it finished without replying).
+                String source = reply.outcome() == MessageService.Outcome.REPLIED ? "reply" : "transcript";
+                ctx.status(200).json(Map.of("sessionId", id, "reply", reply.text(), "replySource", source));
+            }
+            default -> ctx.status(202).json(Map.of(
+                    "sessionId", id,
+                    "status", switch (reply.outcome()) {
+                        case TIMED_OUT_WORKING -> "working";
+                        case TIMED_OUT_QUEUED -> "queued";
+                        case BUSY -> "busy";
+                        case WORKER_FAILED -> "failed";
+                        default -> "done"; // unreachable (terminal outcomes handled above)
+                    },
+                    "detail", reply.outcome() == MessageService.Outcome.WORKER_FAILED && reply.text() != null
+                            ? reply.text()
+                            : "no reply within " + timeout + "ms; poll status or retry"));
+        }
+    }
+
+    /**
+     * A worker's mid-turn question ({@code bridge_ask}, CB-205) — surfaces to the primary's open
+     * blocking send and blocks until it answers. 200 with the answer, 409 if no delegation is open,
+     * 202 if the primary stayed silent.
+     */
+    private void askMessage(Context ctx) {
+        String id = ctx.pathParam("id");
+        if (!allow(ctx, Authz.Action.ASK, id)) {
+            return;
+        }
+        String question;
+        long timeout;
+        try {
+            JsonNode body = mapper.readTree(ctx.body());
+            question = body.path("question").asText("");
+            timeout = body.path("timeoutMs").asLong(DEFAULT_ASK_TIMEOUT_MS);
+        } catch (Exception e) {
+            ctx.status(400).json(Map.of("error", "bad_request", "detail", "body must be JSON"));
+            return;
+        }
+        if (question.isBlank()) {
+            ctx.status(400).json(Map.of("error", "bad_request", "detail", "question is required"));
+            return;
+        }
+        timeout = Math.clamp(timeout, 1, MAX_ASK_TIMEOUT_MS);
+        MessageService.AskResult r = messages.ask(id, question, timeout);
+        switch (r.outcome()) {
+            case ANSWERED -> ctx.status(200).json(Map.of("sessionId", id, "answered", true, "answer", r.answer()));
+            case NO_WAITER -> ctx.status(409).json(Map.of(
+                    "sessionId", id, "error", "no_pending_send",
+                    "detail", "no primary is awaiting this turn to answer a question"));
+            case TIMED_OUT -> ctx.status(202).json(Map.of(
+                    "sessionId", id, "status", "no_answer",
+                    "detail", "the primary did not answer within " + timeout + "ms"));
+        }
+    }
+
+    /**
+     * The worker's structured reply ({@code bridge_reply}) — resolves the blocking send awaiting
+     * on this session, or queues the reply in the inbox when no send is open (CB-307).
+     */
+    private void replyMessage(Context ctx) {
+        String id = ctx.pathParam("id");
+        // The rule that matters: a worker may reply only as itself. Over MCP this was already true
+        // structurally (identity comes from the connection, never an argument); over REST the path
+        // id was simply trusted, so this is where the invariant actually gets enforced.
+        if (!allow(ctx, Authz.Action.REPLY, id)) {
+            return;
+        }
+        String content;
+        try {
+            content = mapper.readTree(ctx.body()).path("content").asText("");
+        } catch (Exception e) {
+            ctx.status(400).json(Map.of("error", "bad_request", "detail", "body must be JSON"));
+            return;
+        }
+        messages.reply(id, content);
+        ctx.status(200).json(Map.of("sessionId", id, "delivered", true));
+    }
+
+    /**
+     * Drain the reply inbox for a worker session — peek + ack any replies that arrived when no send
+     * was open. At-least-once: draining removes them from the inbox so a subsequent read returns
+     * nothing; an in-flight failure between the drain and the caller's processing re-surfaces them.
+     */
+    private void drainReplies(Context ctx) {
+        String id = ctx.pathParam("id");
+        if (!allow(ctx, Authz.Action.DRAIN, id)) {
+            return;
+        }
+        var replies = messages.drainReplies(id);
+        ctx.status(200).json(Map.of("sessionId", id, "replies",
+                replies.stream().map(m -> Map.of(
+                        "msgId", m.msgId(),
+                        "content", m.content())).toList()));
+    }
+
+    /**
+     * Live lifecycle status of a worker (MCP `bridge_status` wraps this in CB-105), plus its
+     * <em>readiness</em> (CB-113): {@code ready} is true once the worker's Claude has connected the
+     * bridge MCP — the reliable "available to receive a task" signal, unlike bare {@code idle}, which
+     * is also true during boot.
+     */
+    private void sessionStatus(Context ctx) {
+        String id = ctx.pathParam("id");
+        if (!allow(ctx, Authz.Action.READ, id)) {
+            return;
+        }
+        try {
+            ctx.status(200).json(Map.of(
+                    "sessionId", id,
+                    "status", messages.status(id).name().toLowerCase(),
+                    "ready", presence.isPresent(id)));
+        } catch (HerdrException e) {
+            herdrError(ctx, e);
+        }
+    }
+
+    /** Poll an async (wait:false) delegation by ticket. 404 for an unknown/expired ticket. */
+    private void taskStatus(Context ctx) {
+        if (!allow(ctx, Authz.Action.READ, null)) {
+            return;
+        }
+        MessageService.TaskView v = messages.poll(ctx.pathParam("ticket"));
+        if (v == null) {
+            ctx.status(404).json(Map.of("error", "unknown_ticket", "detail", "no such task (or it has expired)"));
+            return;
+        }
+        Map<String, Object> body = new LinkedHashMap<>();
+        body.put("ticket", v.ticket());
+        body.put("phase", v.phase().name().toLowerCase());
+        if (v.reply() != null) {
+            body.put("reply", v.reply());
+            body.put("replySource", v.replySource());
+        }
+        if (v.detail() != null) {
+            body.put("detail", v.detail());
+        }
+        ctx.status(200).json(body);
+    }
+
+    /** Map a herdr failure: unknown target → 404, anything else → 502 (herdr is upstream). */
+    private static void herdrError(Context ctx, HerdrException e) {
+        if (e.code() != null && e.code().endsWith("_not_found")) {
+            ctx.status(404).json(Map.of("error", "session_not_found", "detail", e.getMessage()));
+        } else {
+            ctx.status(502).json(Map.of("error", "herdr_error", "detail", e.getMessage()));
+        }
+    }
+
     /** Stable JSON projection of an agent (null-safe for the start-time shape). */
     private static Map<String, Object> view(Agent a) {
         Map<String, Object> m = new LinkedHashMap<>();
@@ -109,4 +553,22 @@ public final class BridgedApp {
         m.put("status", a.status().name().toLowerCase());
         return m;
     }
+
+    /** CB-301 projection of an authoritative bridge-owned session. */
+    private static Map<String, Object> view(MemberSession s) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("terminalId", s.terminalId());
+        m.put("paneId", s.paneId());
+        m.put("profile", s.profile());
+        m.put("cwd", s.cwd());
+        m.put("ownerTerminal", s.ownerTerminal());
+        m.put("state", s.state().name().toLowerCase());
+        if (s.worktree() != null) {
+            m.put("worktree", s.worktree());
+        }
+        if (s.branch() != null) {
+            m.put("branch", s.branch());
+        }
+        return m;
+    }
 }

bridged/src/main/java/dev/ltms/bridged/session/GitWorktrees.java

@@ -0,0 +1,270 @@
+package dev.ltms.bridged.session;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.security.SecureRandom;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.stream.Collectors;
+
+/**
+ * Production {@link Worktrees} implementation that shells {@code git} via {@link ProcessBuilder}.
+ * Non-zero exits become {@link WorktreeException}. Worktree directories live under a configurable
+ * root (default: a sibling {@code .bridged-worktrees} of the repo root) so they are never nested
+ * inside the primary working tree.
+ */
+public final class GitWorktrees implements Worktrees {
+
+    private static final Logger log = LoggerFactory.getLogger(GitWorktrees.class);
+
+    /** Project-level MCP config. Present in the repo, so every worktree would otherwise inherit the
+     *  primary's IDE server mounts (a CB-523 worker edited the primary checkout; see the isolation
+     *  javadoc). Neutralized unconditionally. */
+    private static final String MCP_CONFIG = ".mcp.json";
+
+    /** What {@link #isolateToolSurface} writes for {@code .mcp.json}: a valid, explicitly empty server map. */
+    private static final String NEUTRAL_MCP_CONFIG = "{\n  \"mcpServers\": {}\n}\n";
+
+    /** OpenCode's repo-level config. Tracked here, so it lands in every worktree; it carries
+     *  {@code {file:.secrets/...}} references to gitignored secrets that never reach a worktree, and
+     *  opencode refuses to start on a dangling reference — so it is neutralized and the worker gets
+     *  only the config its launcher writes via {@code OPENCODE_CONFIG}. */
+    private static final String OPENCODE_CONFIG = "opencode.json";
+
+    /** What {@link #isolateToolSurface} writes for {@code opencode.json}: a valid, empty JSON object. */
+    private static final String NEUTRAL_OPENCODE_CONFIG = "{}\n";
+
+    /** Autoenv's repo-level config. Not tracked today, but re-landing it must stay safe: autoenv
+     *  authorizes by path, so a fresh worktree path is always unauthorized and its interactive prompt
+     *  would block every spawn — neutralize it so it can never be committed. */
+    private static final String AUTOENV_CONFIG = ".autoenv";
+
+    /** What {@link #isolateToolSurface} writes for {@code .autoenv}: a valid, empty env file. */
+    private static final String NEUTRAL_AUTOENV_CONFIG = "";
+
+    /**
+     * A tracked project config that is hostile in a provisioned worktree, and what to replace it
+     * with. {@link #file} is the repo-relative path; {@link #stub} is a neutral but VALID payload for
+     * that file's format — a malformed stub would only trade one crash for another;
+     * {@link #createIfAbsent} keeps {@code .mcp.json}'s long-standing behaviour of writing its stub
+     * even when the repo carries no such file, whereas the others are only touched when present.
+     */
+    private record WorktreeHostileConfig(String file, String stub, boolean createIfAbsent) {}
+
+    /** The worktree-hostile configs neutralized in every provisioned worktree, in order. */
+    private static final List<WorktreeHostileConfig> WORKTREE_HOSTILE_CONFIGS = List.of(
+            new WorktreeHostileConfig(MCP_CONFIG, NEUTRAL_MCP_CONFIG, true),
+            new WorktreeHostileConfig(OPENCODE_CONFIG, NEUTRAL_OPENCODE_CONFIG, false),
+            new WorktreeHostileConfig(AUTOENV_CONFIG, NEUTRAL_AUTOENV_CONFIG, false)
+    );
+
+    private final String configuredRoot;
+    private final SecureRandom random = new SecureRandom();
+    private final AtomicLong seq = new AtomicLong();
+
+    /** Default constructor: worktree root is derived per-repo as {@code <repoRoot>/../.bridged-worktrees}. */
+    public GitWorktrees() {
+        this(null);
+    }
+
+    /** @param configuredRoot nullable absolute or relative path; null/blank derives a sibling of the repo root. */
+    public GitWorktrees(String configuredRoot) {
+        this.configuredRoot = configuredRoot;
+    }
+
+    @Override
+    public String add(String repoRoot, String branch, String baseRef) {
+        String base = (baseRef == null || baseRef.isBlank()) ? "HEAD" : baseRef;
+        String nonce = nonce();
+        Path root = resolveRoot(repoRoot);
+        Path path = root.resolve(nonce);
+        try {
+            Files.createDirectories(root);
+        } catch (IOException e) {
+            throw new WorktreeException("cannot create worktree root " + root + ": " + e.getMessage(), e);
+        }
+        String wt = path.toAbsolutePath().toString();
+        log.info("adding worktree branch={} path={} base={}", branch, wt, base);
+        exec("git", "-C", repoRoot, "worktree", "add", wt, "-b", branch, base);
+        isolateToolSurface(wt);
+        return wt;
+    }
+
+    /**
+     * Neutralize the worktree's worktree-hostile project configs so a worker inherits only the tools
+     * and environment its launcher mounts (the bridge via {@code --mcp-config}, the opencode config
+     * via {@code OPENCODE_CONFIG}) — never the primary's.
+     *
+     * <p>This is unconditional, and it is not the same job as the parity overlay. The repo's own
+     * committed {@code .mcp.json} declares the primary's IDE servers, so a fresh checkout mounts them
+     * whether or not the overlay copies anything; a worker that inherits them navigates and edits
+     * through tools bound to the <em>primary's</em> IntelliJ project, which silently hands it absolute
+     * paths outside its own worktree. That is not hypothetical: a CB-523 worker made all 59 of its
+     * edits in the primary checkout while compiling its worktree, so every build it ran was of code
+     * that did not contain its changes. {@code opencode.json} is the same trap one tool over — tracked,
+     * so it lands in every worktree, referencing gitignored {@code .secrets/} files that never do, and
+     * opencode refuses to start on the dangling reference. {@code .autoenv} extends the principle to a
+     * config that is not tracked today: autoenv authorizes by path, so a fresh worktree path is always
+     * unauthorized and its interactive prompt would block every spawn, so re-landing one must be safe.
+     *
+     * <p>Where a config exists it is replaced by a valid neutral stub (an explicitly empty
+     * map/object, or an empty env file — never a deletion, which would still let a later
+     * {@code git checkout} restore the hostile copy). The {@code --skip-worktree} bit keeps the
+     * neutralized copy from ever showing up as a local modification the worker might commit. A config
+     * the repo does not carry is skipped silently — no stub is invented for a file the repo does not
+     * have, and one missing file must never fail provisioning.
+     */
+    private void isolateToolSurface(String worktreePath) {
+        Path root = Path.of(worktreePath).toAbsolutePath().normalize();
+        for (WorktreeHostileConfig cfg : WORKTREE_HOSTILE_CONFIGS) {
+            neutralize(root, worktreePath, cfg);
+        }
+    }
+
+    private void neutralize(Path root, String worktreePath, WorktreeHostileConfig cfg) {
+        Path target = root.resolve(cfg.file());
+        if (!Files.exists(target) && !cfg.createIfAbsent()) {
+            log.debug("{} absent in the worktree — skipping (repo does not carry it)", cfg.file());
+            return;
+        }
+        try {
+            Files.writeString(target, cfg.stub());
+        } catch (IOException e) {
+            throw new WorktreeException("cannot neutralize " + cfg.file() + " in the worktree: "
+                    + e.getMessage(), e);
+        }
+        if (isTracked(root, cfg.file())) {
+            exec("git", "-C", worktreePath, "update-index", "--skip-worktree", cfg.file());
+        }
+        log.debug("neutralized {} — worker tool surface is launcher-mounted only", cfg.file());
+    }
+
+    @Override
+    public void remove(String repoRoot, String worktreePath) {
+        Path p = Path.of(worktreePath);
+        if (!Files.exists(p)) {
+            log.debug("worktree {} already gone — nothing to remove", worktreePath);
+            return;
+        }
+        log.info("removing worktree {}", worktreePath);
+        exec("git", "-C", repoRoot, "worktree", "remove", "--force", worktreePath);
+    }
+
+    @Override
+    public void overlayParity(String repoRoot, String worktreePath, List<String> overlay) {
+        if (overlay == null || overlay.isEmpty()) {
+            return;
+        }
+        Path srcRoot = Path.of(repoRoot).toAbsolutePath().normalize();
+        Path dstRoot = Path.of(worktreePath).toAbsolutePath().normalize();
+        for (String rel : overlay) {
+            Path src = srcRoot.resolve(rel).normalize();
+            if (!Files.exists(src)) {
+                log.debug("parity overlay source missing — skipping {}", rel);
+                continue;
+            }
+            Path dst = dstRoot.resolve(rel).normalize();
+            try {
+                Files.createDirectories(dst.getParent());
+                Files.copy(src, dst, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.COPY_ATTRIBUTES);
+                log.debug("copied parity overlay {}", rel);
+            } catch (IOException e) {
+                throw new WorktreeException("cannot copy overlay " + rel + ": " + e.getMessage(), e);
+            }
+            if (isTracked(dstRoot, rel)) {
+                exec("git", "-C", worktreePath, "update-index", "--skip-worktree", rel);
+                log.debug("marked overlay --skip-worktree {}", rel);
+            }
+        }
+    }
+
+    @Override
+    public String repoRoot(String cwd) {
+        String out = exec("git", "-C", cwd, "rev-parse", "--show-toplevel");
+        return Path.of(out.trim()).toAbsolutePath().normalize().toString();
+    }
+
+    /** Resolve the directory that will hold per-session worktree checkouts. */
+    private Path resolveRoot(String repoRoot) {
+        if (configuredRoot != null && !configuredRoot.isBlank()) {
+            return Path.of(configuredRoot).toAbsolutePath().normalize();
+        }
+        Path repo = Path.of(repoRoot).toAbsolutePath().normalize();
+        return repo.resolveSibling(".bridged-worktrees");
+    }
+
+    private String nonce() {
+        return String.format("%06x", random.nextInt(1 << 24)) + "-" + seq.incrementAndGet();
+    }
+
+    private boolean isTracked(Path worktreeRoot, String rel) {
+        return exitCode("git", "-C", worktreeRoot.toString(), "ls-files", "--error-unmatch", rel) == 0;
+    }
+
+    /**
+     * Run a command and return its stdout. Non-zero exit → {@link WorktreeException} with both
+     * stdout and stderr (merged by redirectErrorStream).
+     */
+    private String exec(String... command) {
+        String out;
+        int code;
+        Process p;
+        try {
+            p = new ProcessBuilder(command).redirectErrorStream(true).start();
+        } catch (IOException e) {
+            throw new WorktreeException("failed to start " + command[0] + ": " + e.getMessage(), e);
+        }
+        try (BufferedReader r = new BufferedReader(new InputStreamReader(p.getInputStream(), StandardCharsets.UTF_8))) {
+            out = r.lines().collect(Collectors.joining("\n"));
+        } catch (IOException e) {
+            p.destroyForcibly();
+            throw new UncheckedIOException(e);
+        }
+        try {
+            if (!p.waitFor(30, TimeUnit.SECONDS)) {
+                p.destroyForcibly();
+                throw new WorktreeException("command timed out: " + String.join(" ", command) + "\n" + out);
+            }
+            code = p.exitValue();
+        } catch (InterruptedException e) {
+            p.destroyForcibly();
+            Thread.currentThread().interrupt();
+            throw new WorktreeException("interrupted waiting for command: " + String.join(" ", command), e);
+        }
+        if (code != 0) {
+            throw new WorktreeException("exit " + code + " for: " + String.join(" ", command)
+                    + (out.isBlank() ? "" : "\n" + out));
+        }
+        return out;
+    }
+
+    private int exitCode(String... command) {
+        Process p;
+        try {
+            p = new ProcessBuilder(command).redirectErrorStream(true).start();
+        } catch (IOException e) {
+            throw new WorktreeException("failed to start " + command[0] + ": " + e.getMessage(), e);
+        }
+        try {
+            if (!p.waitFor(30, TimeUnit.SECONDS)) {
+                p.destroyForcibly();
+                throw new WorktreeException("command timed out: " + String.join(" ", command));
+            }
+            return p.exitValue();
+        } catch (InterruptedException e) {
+            p.destroyForcibly();
+            Thread.currentThread().interrupt();
+            throw new WorktreeException("interrupted waiting for command: " + String.join(" ", command), e);
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/session/MemberSession.java

@@ -0,0 +1,68 @@
+package dev.ltms.bridged.session;
+
+import dev.ltms.bridged.peer.MemberRole;
+
+/**
+ * A bridge-owned worker session — the authoritative in-daemon record of a worker this
+ * process spawned. Immutable; state transitions are performed by replacing the record in
+ * {@link SessionManager}'s registry.
+ *
+ * @param paneId         the host-unique opaque id (CB-519) — the registry key and the argument to
+ *                       teardown. Despite the historical name this is the {@link
+ *                       dev.ltms.bridged.peer.PeerHandle#id()}, a UUID, and is distinct from the
+ *                       launcher-private herdr pane coordinate.
+ * @param terminalId     herdr terminal handle — the {@code target} for send/read/status
+ * @param profile        the profile name that spawned this session — WHICH BACKEND
+ * @param role           the contract this member runs under — WHAT IT IS FOR. Independent of
+ *                       {@code profile}: a reviewer may run on the same profile as the dev
+ *                       whose diff it reads. {@code null} only for a session recorded before
+ *                       the role was known
+ * @param cwd            the resolved working directory the worker started in
+ * @param ownerTerminal  the caller that requested this worker ({@code null} = daemon/anon)
+ * @param spawnedAtNanos     {@link System#nanoTime()} when the session was registered
+ * @param lastActivityAtNanos {@link System#nanoTime()} of the most recent lifecycle event
+ * @param turnCount          number of delegated turns that have been delivered to this session
+ * @param state              current lifecycle state in the one-shot FSM
+ */
+public record MemberSession(
+        String paneId,
+        String terminalId,
+        String profile,
+        MemberRole role,
+        String cwd,
+        String ownerTerminal,
+        long spawnedAtNanos,
+        long lastActivityAtNanos,
+        int turnCount,
+        State state,
+        String worktree,
+        String branch) {
+
+    /** One-shot worker lifecycle states. */
+    public enum State {
+        SPAWNING,
+        READY,
+        BUSY,
+        DONE,
+        FAILED,
+        RELEASED
+    }
+
+    /** Return a copy of this session in {@code state}. */
+    public MemberSession withState(State state) {
+        return new MemberSession(paneId, terminalId, profile, role, cwd, ownerTerminal, spawnedAtNanos,
+                lastActivityAtNanos, turnCount, state, worktree, branch);
+    }
+
+    /** Return a copy with {@code lastActivityAtNanos} updated to {@code nowNanos}. */
+    public MemberSession withActivity(long nowNanos) {
+        return new MemberSession(paneId, terminalId, profile, role, cwd, ownerTerminal, spawnedAtNanos,
+                nowNanos, turnCount, state, worktree, branch);
+    }
+
+    /** Return a copy with the turn count incremented and activity timestamped at {@code nowNanos}. */
+    public MemberSession bumpTurn(long nowNanos) {
+        return new MemberSession(paneId, terminalId, profile, role, cwd, ownerTerminal, spawnedAtNanos,
+                nowNanos, turnCount + 1, state, worktree, branch);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/session/SessionManager.java

@@ -0,0 +1,619 @@
+package dev.ltms.bridged.session;
+
+import dev.ltms.bridged.herdr.Agent;
+import dev.ltms.bridged.inject.TurnListener;
+import dev.ltms.bridged.inject.MemberPresence;
+import dev.ltms.bridged.peer.MemberRole;
+import dev.ltms.bridged.peer.PeerHandle;
+import dev.ltms.bridged.peer.PeerLauncher;
+import dev.ltms.bridged.peer.SpawnRequest;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.security.SecureRandom;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.function.Consumer;
+import java.util.function.LongSupplier;
+
+/**
+ * Authoritative in-daemon registry of the worker sessions this {@code bridged} process spawned.
+ * Delegates spawn/teardown to a {@link PeerLauncher} (which performs subscription-guarded env
+ * setup and process/materialization) and adds lifecycle tracking, ownership, and deterministic
+ * teardown on top.
+ *
+ * <p>The state machine is intentionally one-shot / no-reuse: every acquired worker is fresh,
+ * and a finished or released worker is torn down, never pooled. {@link #recycle} is a convenience
+ * for {@code release + acquire} with a new distinct pane id.
+ *
+ * <p>The manager implements {@link TurnListener} so the injector's turn boundaries drive
+ * {@code READY → BUSY → DONE} (or {@code FAILED}). It exposes a {@link MemberPresence} view via
+ * {@link #asPresence()}: any MCP contact from a worker marks it present and simultaneously
+ * transitions the session {@code SPAWNING → READY}.
+ */
+public final class SessionManager implements TurnListener {
+
+    private static final Logger log = LoggerFactory.getLogger(SessionManager.class);
+
+    private final PeerLauncher launcher;
+    private final Worktrees worktrees;
+    private final ConcurrentHashMap<String /*paneId*/, MemberSession> registry = new ConcurrentHashMap<>();
+    private final MemberPresence presence;
+    private final SecureRandom nonceRandom = new SecureRandom();
+    private final AtomicLong nonceSeq = new AtomicLong();
+    private final LongSupplier nowNanos;
+    private final int contextCap;
+    private final boolean clearAfterTurn;
+
+    /** CB-520: notified with a terminalId on every acquire; no-op until wired. */
+    private final List<Consumer<String>> acquireListeners = new java.util.concurrent.CopyOnWriteArrayList<>();
+    /** CB-516: notified with a terminalId on every release; no-op until wired. */
+    private final List<Consumer<String>> releaseListeners = new java.util.concurrent.CopyOnWriteArrayList<>();
+
+    /** Backward-compatible constructor: shared-tree sessions, production git seam. */
+    public SessionManager(PeerLauncher launcher) {
+        this(launcher, new GitWorktrees(), System::nanoTime, 0, false);
+    }
+
+    /** Backward-compatible constructor with an injectable worktree seam. */
+    public SessionManager(PeerLauncher launcher, Worktrees worktrees) {
+        this(launcher, worktrees, System::nanoTime, 0, false);
+    }
+
+    /** Test constructor with an injectable clock. */
+    public SessionManager(PeerLauncher launcher, Worktrees worktrees, LongSupplier nowNanos) {
+        this(launcher, worktrees, nowNanos, 0, false);
+    }
+
+    /** Production constructor with a configured context turn cap. */
+    public SessionManager(PeerLauncher launcher, Worktrees worktrees, int contextCap) {
+        this(launcher, worktrees, System::nanoTime, contextCap, false);
+    }
+
+    public SessionManager(PeerLauncher launcher, Worktrees worktrees, LongSupplier nowNanos,
+                           int contextCap) {
+        this(launcher, worktrees, nowNanos, contextCap, false);
+    }
+
+    public SessionManager(PeerLauncher launcher, Worktrees worktrees, LongSupplier nowNanos,
+                          int contextCap, boolean clearAfterTurn) {
+        this.launcher = launcher;
+        this.worktrees = worktrees;
+        this.presence = new PresenceBridge(this);
+        this.nowNanos = nowNanos;
+        this.contextCap = contextCap;
+        this.clearAfterTurn = clearAfterTurn;
+    }
+
+    /**
+     * The single {@link MemberPresence} view of this manager: it records availability and forwards
+     * the signal to the {@code SPAWNING → READY} transition. Pass this to the {@code Injector} and
+     * {@code BridgeMcp} where they previously accepted a plain {@link MemberPresence}. The same
+     * instance is returned every call — presence is shared state, so a fresh bridge per call would
+     * fragment the {@code present} set and lose signals across callers.
+     */
+    public MemberPresence asPresence() {
+        return presence;
+    }
+
+    /**
+     * Spawn a worker and register it as {@link MemberSession.State#SPAWNING}. The caller's
+     * identity is recorded as {@code ownerTerminal} ({@code null} for daemon/anon callers).
+     */
+    public MemberSession acquire(String profile, String requestedCwd, String callerCwd,
+                                 String ownerTerminal) {
+        return acquire(profile, requestedCwd, callerCwd, ownerTerminal, null);
+    }
+
+    /**
+     * Spawn a member, optionally inside a fresh git worktree, defaulting the role to
+     * {@link MemberRole#DEV}.
+     *
+     * <p>{@code DEV} is the right default because it is exactly what the old "worker" meant: an
+     * unqualified spawn is a unit of implementation work. An architect or a reviewer is always
+     * asked for on purpose, so neither is ever what a caller silently gets.
+     */
+    public MemberSession acquire(String profile, String requestedCwd, String callerCwd,
+                                 String ownerTerminal, WorktreeRequest wt) {
+        return acquire(profile, MemberRole.DEV, requestedCwd, callerCwd, ownerTerminal, wt);
+    }
+
+    /**
+     * Spawn a member, optionally inside a fresh git worktree. When {@code wt} is non-null the
+     * worktree is provisioned, parity-overlaid, and its path becomes the member's cwd. On any
+     * failure before registration the worktree is removed so no dangling checkout is left.
+     *
+     * @param profile which backend to run on — a {@code profiles:} key
+     * @param role    which contract the member runs under; never {@code null}
+     */
+    public MemberSession acquire(String profile, MemberRole role, String requestedCwd, String callerCwd,
+                                 String ownerTerminal, WorktreeRequest wt) {
+        MemberRole memberRole = (role == null) ? MemberRole.DEV : role;
+        if (wt == null) {
+            // CB-557: the role must ride on the SpawnRequest, not stay a local. The launcher needs it
+            // to pick the profile out of that role's pool and to label the tab; a role kept only on
+            // the MemberSession is recorded after the spawn it was supposed to steer.
+            SpawnRequest req = new SpawnRequest(profile, requestedCwd, callerCwd, null, null, memberRole);
+            PeerHandle handle = launcher.spawn(req);
+            String resolvedProfile = resolveProfile(handle, profile);
+            String cwd = launcher.effectiveCwd(new SpawnRequest(resolvedProfile, requestedCwd, callerCwd));
+            long now = nowNanos.getAsLong();
+            MemberSession session = new MemberSession(
+                    handle.id(),
+                    handle.terminalId(),
+                    resolvedProfile,
+                    memberRole,
+                    cwd,
+                    ownerTerminal,
+                    now,
+                    now,
+                    0,
+                    MemberSession.State.SPAWNING,
+                    null,
+                    null);
+            registry.put(handle.id(), session);
+            log.debug("acquired session id={} terminal={} profile={} owner={}",
+                    handle.id(), handle.terminalId(), session.profile(), session.ownerTerminal());
+            notifyAcquired(session.terminalId());
+            return session;
+        }
+        return acquireWithWorktree(profile, memberRole, requestedCwd, callerCwd, ownerTerminal, wt);
+    }
+
+    /** Tear a worker down by pane id and remove it from the registry. Idempotent. */
+    public void release(String paneId) {
+        release(paneId, ReleaseCause.COMPLETED);
+    }
+
+    /**
+     * Core teardown: always stops the worker pane and deregisters the session; whether the worker's
+     * git worktree is also removed depends on {@code cause}.
+     *
+     * <p>CB-544: these are two concerns that used to be fused. Stopping the pane is correct on every
+     * teardown — the worker process must end. Removing the worktree is a destructive act that is only
+     * correct for a deliberately-finished teardown (an explicit stop of a completed session, the
+     * reaper releasing a genuinely idle one, a context-capped or recycled session). A shutdown drain
+     * must stop panes but preserve worktrees: a worker's uncommitted work exists in exactly one
+     * place — its worktree — so deleting it while the daemon simply goes down is silent data loss,
+     * with no copy and no error. Do NOT fuse these back together; the cost of an orphaned worktree
+     * is a logged path an operator can reclaim, the cost of a deleted one is unrecoverable work.
+     */
+    private void release(String paneId, ReleaseCause cause) {
+        MemberSession removed = registry.remove(paneId);
+        boolean preserveWorktree = cause == ReleaseCause.SHUTDOWN;
+        if (removed != null) {
+            log.debug("releasing session pane={} terminal={} state={} cause={}",
+                    removed.paneId(), removed.terminalId(), removed.state(), cause);
+            if (preserveWorktree && removed.worktree() != null) {
+                logPreservedForShutdown(removed);
+            }
+            // CB-516: a send still waiting on this worker can never be answered now. Tell the
+            // listener BEFORE the pane is torn down, so a blocked caller fails fast with a real
+            // reason instead of sitting on a rendezvous nothing will ever resolve.
+            notifyReleased(removed.terminalId());
+        }
+        launcher.stop(paneId);
+        if (removed != null && !preserveWorktree && removed.worktree() != null) {
+            worktrees.remove(worktrees.repoRoot(removed.cwd()), removed.worktree());
+        }
+    }
+
+    /**
+     * Why a session is being released — governs whether its worktree is preserved or removed.
+     * Worktree removal is reserved for the one case that is genuinely finished; everything else
+     * must keep the worker's only copy of its work.
+     */
+    public enum ReleaseCause {
+        /** Deliberate teardown of a finished session. Stops the pane and removes the worktree. */
+        COMPLETED,
+        /** Daemon shutdown drain. Stops the pane but PRESERVES the worktree. */
+        SHUTDOWN
+    }
+
+    /**
+     * CB-544 shutdown drain log for a worktree we deliberately kept. A session still {@code BUSY}
+     * when the drain timeout expired was abandoned mid-turn — that work may be uncommitted and is
+     * the only copy — so the message is loud and points at the path an operator needs to reclaim.
+     */
+    private void logPreservedForShutdown(MemberSession session) {
+        if (session.state() == MemberSession.State.BUSY) {
+            log.warn("shutdown drain abandoned BUSY session pane={} terminal={} mid-turn; "
+                    + "worktree preserved at {}", session.paneId(), session.terminalId(),
+                    session.worktree());
+        } else {
+            log.info("shutdown drain preserved worktree at {} for pane={}",
+                    session.worktree(), session.paneId());
+        }
+    }
+
+    /**
+     * Register a callback invoked with a session's {@code terminalId} whenever it is acquired
+     * (CB-520). This is the hook that lets the reply inbox {@code own} a target's queue.
+     */
+    public void onAcquire(Consumer<String> listener) {
+        if (listener != null) {
+            acquireListeners.add(listener);
+        }
+    }
+
+    /**
+     * Register a callback invoked with a session's {@code terminalId} whenever it is released
+     * (CB-516). Every teardown path funnels through {@link #release}, so one hook covers the REST
+     * and MCP stop tools, the idle-TTL reaper, {@code recycle}, and shutdown drain alike.
+     *
+     * <p>Added rather than injected because {@code MessageService} — one intended listener — is
+     * constructed after this manager (it needs the injector and rendezvous, which need the session
+     * presence view this manager exposes). Wiring it at construction would require breaking that
+     * cycle for one callback.
+     */
+    public void onRelease(Consumer<String> listener) {
+        if (listener != null) {
+            releaseListeners.add(listener);
+        }
+    }
+
+    /** A listener failure must never prevent the acquisition it is reacting to. */
+    private void notifyAcquired(String terminalId) {
+        if (terminalId == null) {
+            return;
+        }
+        for (Consumer<String> listener : acquireListeners) {
+            try {
+                listener.accept(terminalId);
+            } catch (RuntimeException e) {
+                log.warn("acquire listener failed for terminal {}: {}", terminalId, e.toString());
+            }
+        }
+    }
+
+    /** A listener failure must never prevent the teardown it is reacting to. */
+    private void notifyReleased(String terminalId) {
+        if (terminalId == null) {
+            return;
+        }
+        for (Consumer<String> listener : releaseListeners) {
+            try {
+                listener.accept(terminalId);
+            } catch (RuntimeException e) {
+                log.warn("release listener failed for terminal {}: {}", terminalId, e.toString());
+            }
+        }
+    }
+
+    private MemberSession acquireWithWorktree(String profile, MemberRole memberRole, String requestedCwd, String callerCwd,
+                                              String ownerTerminal, WorktreeRequest wt) {
+        String preResolvedProfile = (profile == null || profile.isBlank())
+                ? launcher.defaultProfile() : profile;
+        // CB-507: resolve through the launcher's CB-112 chain (requested → profile cwd → caller →
+        // daemon cwd → "."), never the raw args. A plain REST spawn supplies neither a requested
+        // nor a caller cwd, so taking the first non-blank of those two yielded null and put
+        // `git -C null` on the command line — an NPE out of ProcessBuilder, surfacing as HTTP 500.
+        // The non-worktree path always used this chain; only this branch was missed.
+        String repoRoot = worktrees.repoRoot(
+                launcher.effectiveCwd(new SpawnRequest(preResolvedProfile, requestedCwd, callerCwd)));
+        String branch = "worker/" + slug(wt.ticketSlug()) + "-" + nonce();
+        String path = null;
+        PeerHandle handle;
+        try {
+            path = worktrees.add(repoRoot, branch, wt.baseRef());
+            worktrees.overlayParity(repoRoot, path, launcher.parityOverlay(preResolvedProfile));
+            handle = launcher.spawn(new SpawnRequest(profile, path, callerCwd, null, null, memberRole));
+        } catch (RuntimeException e) {
+            if (path != null) {
+                try {
+                    worktrees.remove(repoRoot, path);
+                } catch (RuntimeException cleanup) {
+                    log.warn("failed to clean up worktree {} after spawn error: {}", path, cleanup.getMessage());
+                }
+            }
+            throw e;
+        }
+        String resolvedProfile = resolveProfile(handle, profile);
+        String cwd = launcher.effectiveCwd(new SpawnRequest(resolvedProfile, path, callerCwd));
+        long now = nowNanos.getAsLong();
+        MemberSession session = new MemberSession(
+                handle.id(),
+                handle.terminalId(),
+                resolvedProfile,
+                memberRole,
+                cwd,
+                ownerTerminal,
+                now,
+                now,
+                0,
+                MemberSession.State.SPAWNING,
+                path,
+                branch);
+        registry.put(handle.id(), session);
+        log.debug("acquired worktree session id={} terminal={} profile={} branch={} path={}",
+                handle.id(), handle.terminalId(), session.profile(), session.branch(), session.worktree());
+        notifyAcquired(session.terminalId());
+        return session;
+    }
+
+    private String slug(String raw) {
+        return raw == null ? "ticket" : raw.toLowerCase().replaceAll("[^a-z0-9]+", "-").replaceAll("^-+|-+$", "");
+    }
+
+    private String nonce() {
+        return String.format("%06x", nonceRandom.nextInt(1 << 24)) + "-" + nonceSeq.incrementAndGet();
+    }
+
+    /**
+     * The profile to record for a session. A launcher that performed dynamic selection tells us
+     * the actual profile via {@link PeerHandle#profile()}; otherwise fall back to what the caller
+     * requested (or the launcher's default for a no-profile spawn).
+     */
+    private String resolveProfile(PeerHandle handle, String requestedProfile) {
+        String fromHandle = handle.profile();
+        if (fromHandle != null && !fromHandle.isBlank()) {
+            return fromHandle;
+        }
+        if (requestedProfile != null && !requestedProfile.isBlank()) {
+            return requestedProfile;
+        }
+        return launcher.defaultProfile();
+    }
+
+    /**
+     * Release the old session and acquire a fresh one with the same profile and working directory.
+     * The new session is guaranteed to have a pane id distinct from the old one (no-reuse invariant).
+     */
+    public MemberSession recycle(String paneId) {
+        MemberSession old = registry.get(paneId);
+        if (old == null) {
+            throw new IllegalArgumentException("no session for paneId " + paneId);
+        }
+        release(paneId);
+        return acquire(old.profile(), old.cwd(), old.cwd(), old.ownerTerminal());
+    }
+
+    /** The session for {@code paneId}, if it is still registered and not released. */
+    public Optional<MemberSession> get(String paneId) {
+        return Optional.ofNullable(registry.get(paneId));
+    }
+
+    /** Bridge-owned roster: all registered sessions (acquired minus released). */
+    public List<MemberSession> roster() {
+        return List.copyOf(registry.values());
+    }
+
+    /**
+     * CB-304 merged roster+live view. The registry is authoritative for worktree, branch,
+     * profile, owner, and state; the optional live agent supplies the herdr-reported status.
+     */
+    public static Map<String, Object> rosterView(MemberSession session, Agent live) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("sessionId", session.terminalId());
+        m.put("paneId", session.paneId());
+        // Both axes, always: profile says which backend this member runs on, role says what it is
+        // for. A lead reading the roster needs both — two rows may share a profile and still be
+        // allowed to do entirely different things.
+        m.put("profile", session.profile());
+        m.put("role", session.role() == null ? "dev" : session.role().wireName());
+        m.put("state", session.state().name().toLowerCase());
+        if (session.worktree() != null) {
+            m.put("worktree", session.worktree());
+        }
+        if (session.branch() != null) {
+            m.put("branch", session.branch());
+        }
+        if (session.ownerTerminal() != null) {
+            m.put("owner", session.ownerTerminal());
+        }
+        m.put("liveStatus", live == null ? "unknown" : live.status().name().toLowerCase());
+        return m;
+    }
+
+    /** Lifecycle hook: worker became available on the bridge MCP. */
+    void onReady(String terminalId) {
+        transitionByTerminal(terminalId, MemberSession.State.SPAWNING, MemberSession.State.READY);
+    }
+
+    /**
+     * Lifecycle hook: a message was delivered into the worker — it is now busy on a turn.
+     * The turn count is bumped and the activity timestamp is refreshed. A {@code DONE} session
+     * can be re-delivered for multi-turn reuse until it is released.
+     */
+    @Override
+    public void onDelivered(String target) {
+        MemberSession current = findByTerminal(target);
+        if (current == null) return;
+        if (current.state() != MemberSession.State.READY && current.state() != MemberSession.State.DONE) {
+            return;
+        }
+        long now = nowNanos.getAsLong();
+        MemberSession updated = current.withState(MemberSession.State.BUSY).bumpTurn(now);
+        if (replace(current, updated)) {
+            log.debug("session transitioned terminal={} pane={} {} -> BUSY turn={}",
+                    target, current.paneId(), current.state(), updated.turnCount());
+        }
+    }
+
+    /** Lifecycle hook: the worker's delegated turn completed successfully. */
+    @Override
+    public void onTurnComplete(String target) {
+        completeTurn(target, false);
+    }
+
+    @Override
+    public boolean hasPostTurnAction(String target) {
+        if (!clearAfterTurn) return false;
+        MemberSession current = findByTerminal(target);
+        return current != null && current.state() == MemberSession.State.BUSY
+                && (contextCap <= 0 || current.turnCount() < contextCap);
+    }
+
+    @Override
+    public boolean onTurnCompleteWithPostAction(String target) {
+        return completeTurn(target, true);
+    }
+
+    private boolean completeTurn(String target, boolean startContextReset) {
+        MemberSession current = findByTerminal(target);
+        if (current == null || current.state() != MemberSession.State.BUSY) return false;
+        long now = nowNanos.getAsLong();
+        MemberSession updated = current.withState(MemberSession.State.DONE).withActivity(now);
+        if (replace(current, updated)) {
+            log.debug("session transitioned terminal={} pane={} BUSY -> DONE turn={}",
+                    target, current.paneId(), updated.turnCount());
+        }
+        if (contextCap > 0 && updated.turnCount() >= contextCap) {
+            release(current.paneId());
+            return false;
+        }
+        if (!startContextReset || !clearAfterTurn) return false;
+        try {
+            return launcher.clearContext(current.paneId());
+        } catch (RuntimeException e) {
+            log.warn("context reset failed for terminal={} pane={}; continuing without reset: {}",
+                    target, current.paneId(), e.getMessage());
+            return false;
+        }
+    }
+
+    /** Lifecycle hook: the worker's delegated turn failed. */
+    @Override
+    public void onTurnFailed(String target) {
+        onFailed(target);
+    }
+
+    /** Lifecycle hook: the worker vanished or was dropped mid-life. */
+    void onFailed(String target) {
+        MemberSession current = findByTerminal(target);
+        if (current == null) return;
+        if (current.state() == MemberSession.State.RELEASED) return;
+        if (replace(current, current.withState(MemberSession.State.FAILED))) {
+            log.debug("session marked failed terminal={} pane={}", target, current.paneId());
+        }
+    }
+
+    /**
+     * Best-effort reap of sessions that have been idle longer than {@code idleTtlNanos}. Only
+     * {@code READY} and {@code DONE} sessions are eligible — never a {@code SPAWNING} or
+     * {@code BUSY} worker. Returns the number of sessions released.
+     */
+    int reapIdle(long idleTtlNanos) {
+        long now = nowNanos.getAsLong();
+        int reaped = 0;
+        for (MemberSession s : roster()) {
+            if (s.state() != MemberSession.State.READY && s.state() != MemberSession.State.DONE) {
+                continue;
+            }
+            if (now - s.lastActivityAtNanos() > idleTtlNanos) {
+                release(s.paneId());
+                reaped++;
+            }
+        }
+        return reaped;
+    }
+
+    /**
+     * Gracefully drain all registered sessions on daemon shutdown. For each session that is
+     * {@code BUSY}, poll up to {@code timeoutNanos} for it to leave {@code BUSY}, then release it
+     * regardless. Non-busy sessions are released immediately. A failure releasing one session is
+     * logged and does not abort the rest.
+     *
+     * <p>CB-544: this is a {@link ReleaseCause#SHUTDOWN} release — the worker's pane is stopped
+     * (the process must end) but its worktree is preserved and its path logged. Shutdown is never
+     * a reason to delete a worker's only copy of its uncommitted work. A session still {@code BUSY}
+     * when the timeout expired is abandoned mid-turn and logged loudly so an operator can find its
+     * kept worktree.
+     */
+    void drainAll(long timeoutNanos) {
+        long deadline = System.nanoTime() + timeoutNanos;
+        for (MemberSession s : roster()) {
+            try {
+                if (s.state() == MemberSession.State.BUSY) {
+                    while (System.nanoTime() < deadline) {
+                        MemberSession current = registry.get(s.paneId());
+                        if (current == null || current.state() != MemberSession.State.BUSY) {
+                            break;
+                        }
+                        try {
+                            long remaining = deadline - System.nanoTime();
+                            Thread.sleep(Math.min(TimeUnit.NANOSECONDS.toMillis(remaining), 50));
+                        } catch (InterruptedException e) {
+                            Thread.currentThread().interrupt();
+                            break;
+                        }
+                    }
+                }
+                release(s.paneId(), ReleaseCause.SHUTDOWN);
+            } catch (RuntimeException e) {
+                log.warn("drain failed for pane={}; continuing with remaining sessions", s.paneId(), e);
+            }
+        }
+    }
+
+    /**
+     * Close this manager by draining all sessions. The timeout comes from configuration when set,
+     * otherwise a sensible default.
+     */
+    public void close(Integer drainTimeoutSeconds) {
+        int seconds = (drainTimeoutSeconds != null && drainTimeoutSeconds > 0) ? drainTimeoutSeconds : 5;
+        drainAll(TimeUnit.SECONDS.toNanos(seconds));
+    }
+
+    /** Number of sessions currently registered. */
+    public int size() {
+        return registry.size();
+    }
+
+    /**
+     * The registered session owning {@code terminalId}, or {@code null} if none does.
+     *
+     * <p>A null {@code terminalId} is a normal input, not a caller bug: every lifecycle hook here is
+     * fed from the MCP transport, where the <em>primary</em> resolves to a {@link
+     * dev.ltms.bridged.auth.Principal} with no terminal. {@code BridgeMcp} documents that contact as
+     * a no-op, and {@link dev.ltms.bridged.inject.MemberPresence#markPresent} honours it — but
+     * {@code PresenceBridge} then forwards the same null here. Matching on a null id can never
+     * succeed anyway (a registered session always has a terminal), so answer "no match" rather than
+     * throwing: an NPE on this path takes down an unrelated tool call for the primary.
+     */
+    private MemberSession findByTerminal(String terminalId) {
+        if (terminalId == null) return null;
+        for (MemberSession s : registry.values()) {
+            if (terminalId.equals(s.terminalId())) return s;
+        }
+        return null;
+    }
+
+    private void transitionByTerminal(String terminalId, MemberSession.State from,
+                                      MemberSession.State to) {
+        MemberSession current = findByTerminal(terminalId);
+        if (current == null || current.state() != from) return;
+        long now = nowNanos.getAsLong();
+        if (replace(current, current.withState(to).withActivity(now))) {
+            log.debug("session transitioned terminal={} pane={} {} -> {}",
+                    terminalId, current.paneId(), from, to);
+        }
+    }
+
+    private boolean replace(MemberSession expected, MemberSession updated) {
+        return registry.replace(expected.paneId(), expected, updated);
+    }
+
+    /** MemberPresence bridge that also drives the manager's READY transition. */
+    private static final class PresenceBridge extends MemberPresence {
+        private final SessionManager sessions;
+
+        PresenceBridge(SessionManager sessions) {
+            this.sessions = sessions;
+        }
+
+        @Override
+        public void markPresent(String terminal) {
+            if (terminal == null || terminal.isBlank()) {
+                return; // the primary's contact carries no worker terminal — not a readiness signal
+            }
+            super.markPresent(terminal);
+            sessions.onReady(terminal);
+        }
+    }
+}

bridged/src/main/java/dev/ltms/bridged/session/SessionReaper.java

@@ -0,0 +1,70 @@
+package dev.ltms.bridged.session;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Periodic virtual-thread reaper that tears down {@code READY}/{@code DONE} sessions which have
+ * exceeded their idle TTL. Modeled on {@link dev.ltms.bridged.inject.StatusPoller}: a single
+ * virtual-thread loop, idempotent start/stop, and no {@code ScheduledExecutorService}.
+ */
+public final class SessionReaper {
+
+    private static final Logger log = LoggerFactory.getLogger(SessionReaper.class);
+    private static final long DEFAULT_INTERVAL_MILLIS = 5000;
+
+    private final SessionManager sessions;
+    private final long idleTtlNanos;
+    private final long intervalMillis;
+    private volatile boolean running;
+    private Thread thread;
+
+    /** Construct a reaper with the default 5-second polling interval. */
+    public SessionReaper(SessionManager sessions, long idleTtlSeconds) {
+        this(sessions, idleTtlSeconds, DEFAULT_INTERVAL_MILLIS);
+    }
+
+    /** Construct a reaper with an explicit polling interval (useful for tests). */
+    public SessionReaper(SessionManager sessions, long idleTtlSeconds, long intervalMillis) {
+        this.sessions = sessions;
+        this.idleTtlNanos = TimeUnit.SECONDS.toNanos(idleTtlSeconds);
+        this.intervalMillis = intervalMillis;
+    }
+
+    /** Start the reaper loop on a virtual thread. Idempotent. */
+    public synchronized void start() {
+        if (running) return;
+        running = true;
+        thread = Thread.ofVirtual().name("session-reaper").start(this::loop);
+        log.info("session reaper started (idle ttl {}s, interval {}ms)",
+                TimeUnit.NANOSECONDS.toSeconds(idleTtlNanos), intervalMillis);
+    }
+
+    private void loop() {
+        while (running) {
+            try {
+                sessions.reapIdle(idleTtlNanos);
+            } catch (RuntimeException e) {
+                log.warn("session reaper iteration failed; continuing", e);
+            }
+            sleep();
+        }
+    }
+
+    private void sleep() {
+        try {
+            Thread.sleep(intervalMillis);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            running = false;
+        }
+    }
+
+    /** Stop the reaper loop. Idempotent. */
+    public synchronized void stop() {
+        running = false;
+        if (thread != null) thread.interrupt();
+    }
+}

bridged/src/main/java/dev/ltms/bridged/session/WorktreeException.java

@@ -0,0 +1,12 @@
+package dev.ltms.bridged.session;
+
+/** Non-zero exit or I/O failure from a git worktree operation. */
+public final class WorktreeException extends RuntimeException {
+    public WorktreeException(String message) {
+        super(message);
+    }
+
+    public WorktreeException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

bridged/src/main/java/dev/ltms/bridged/session/WorktreeRequest.java

@@ -0,0 +1,6 @@
+package dev.ltms.bridged.session;
+
+/** Ask {@link SessionManager#acquire} to provision an isolated worktree. null ⇒ run in the shared primary tree. */
+public record WorktreeRequest(String ticketSlug, String baseRef) {
+    // ticketSlug seeds the branch name; baseRef null/blank ⇒ current HEAD of the repo.
+}

bridged/src/main/java/dev/ltms/bridged/session/Worktrees.java

@@ -0,0 +1,18 @@
+package dev.ltms.bridged.session;
+
+import java.util.List;
+
+/** Seam between {@link SessionManager} and git worktree operations. Tests use a recording fake. */
+public interface Worktrees {
+    /** git -C <repoRoot> worktree add <path> -b <branch> <baseRef|HEAD>. Returns the worktree path. */
+    String add(String repoRoot, String branch, String baseRef);
+
+    /** git -C <repoRoot> worktree remove --force <path>. Idempotent (already-gone tolerated). */
+    void remove(String repoRoot, String worktreePath);
+
+    /** Copy each existing overlay path repoRoot→worktree; mark tracked ones --skip-worktree. */
+    void overlayParity(String repoRoot, String worktreePath, List<String> overlay);
+
+    /** git -C <cwd> rev-parse --show-toplevel — the repo root that owns cwd. */
+    String repoRoot(String cwd);
+}

bridged/src/main/java/dev/ltms/bridged/worker/WorkerService.java

@@ -1,206 +0,0 @@
-package dev.ltms.bridged.worker;
-
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.Agent;
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.HerdrException;
-import dev.ltms.bridged.herdr.Tab;
-import dev.ltms.bridged.herdr.Workspace;
-import dev.ltms.bridged.herdr.WorkspaceControl;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import java.security.SecureRandom;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.atomic.AtomicLong;
-import java.util.function.Function;
-
-/**
- * Spawns and lists worker sessions — the safe path from a delegation request to a
- * running off-subscription Claude.
- *
- * <p>The spawn sequence encodes the subscription boundary: build the worker env with
- * {@code ANTHROPIC_BASE_URL}, assert that host is on the allowlist <em>before</em>
- * touching herdr, and only then {@code agent.start}. A worker's base_url lives in the
- * env map handed to herdr and nowhere else; {@code bridged}'s own environment is never
- * mutated.
- *
- * <p>Placement: in the default {@code tab} policy a worker lands in its own tab inside a
- * dedicated worker space (found-or-created once, then shared), so workers never split or
- * clutter the user's real work spaces. Teardown removes the worker's pane <em>and</em> its
- * now-empty tab, tolerating an already-gone worker so a repeated DELETE is harmless.
- */
-public final class WorkerService {
-
-    private static final Logger log = LoggerFactory.getLogger(WorkerService.class);
-
-    /** herdr rejects a duplicate agent {@code name}; we retry a bumped name this many times. */
-    private static final int NAME_RETRIES = 8;
-
-    private final AgentControl agents;
-    private final WorkspaceControl spaces;
-    private final SubscriptionGuard guard;
-    private final BridgedConfig.Worker cfg;
-    private final Function<String, String> env; // host env lookup (injectable for tests)
-    private final AtomicLong nameSeq = new AtomicLong(); // per-worker counter (also the tab #)
-    // Per-process token mixed into each worker name so a fresh process (nameSeq back at 0)
-    // cannot collide with same-profile workers that outlived a restart. See startUniquelyNamed.
-    private final String nameNonce = String.format("%06x", new SecureRandom().nextInt(1 << 24));
-
-    public WorkerService(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
-                         BridgedConfig.Worker cfg, Function<String, String> env) {
-        this.agents = agents;
-        this.spaces = spaces;
-        this.guard = guard;
-        this.cfg = cfg;
-        this.env = env;
-    }
-
-    /** Spawn a worker for the configured profile. Guard runs before any herdr call. */
-    public Agent spawn() {
-        String baseUrl = cfg.baseUrl();
-        guard.assertWorker(baseUrl); // hard stop before we spawn anything
-
-        Map<String, String> workerEnv = new LinkedHashMap<>();
-        workerEnv.put("ANTHROPIC_BASE_URL", baseUrl);
-        putIfPresent(workerEnv, "ANTHROPIC_MODEL", cfg.model());
-        putIfPresent(workerEnv, "CLAUDE_CONFIG_DIR", cfg.configDir());
-        String token = env.apply(cfg.tokenEnv());
-        putIfPresent(workerEnv, "ANTHROPIC_AUTH_TOKEN", token);
-
-        return cfg.tabPlacement() ? spawnInTab(workerEnv) : spawnAsPane(workerEnv);
-    }
-
-    /** Dedicated worker space → own tab → drop the placeholder shell so only the worker remains. */
-    private Agent spawnInTab(Map<String, String> workerEnv) {
-        Workspace space = spaces.ensureWorkspace(cfg.workspace());
-        Tab.Created tab = spaces.createTab(space.workspaceId());
-        log.info("spawning worker profile={} base_url={} space={} tab={}",
-                cfg.profile(), cfg.baseUrl(), space.workspaceId(), tab.tab().tabId());
-
-        Started started;
-        try {
-            started = startUniquelyNamed(workerEnv, tab.tab().tabId());
-        } catch (RuntimeException e) {
-            // The worker never started — don't leave the tab we just created orphaned.
-            // Best-effort cleanup; never let it mask the real spawn failure.
-            try {
-                spaces.closeTab(tab.tab().tabId());
-            } catch (RuntimeException cleanup) {
-                log.warn("failed to close orphaned tab {} after spawn error: {}",
-                        tab.tab().tabId(), cleanup.getMessage());
-            }
-            throw e;
-        }
-
-        // The worker is LIVE now. The remaining steps are cosmetic (drop herdr's seed shell
-        // so the tab holds only the worker; label the tab). They must not fail the spawn or
-        // orphan the running worker — on error we log and still return it so the caller gets
-        // its paneId and can tear it down.
-        if (tab.rootPaneId() != null) {
-            tidy("close seed pane " + tab.rootPaneId(), () -> agents.close(tab.rootPaneId()));
-        } else {
-            log.warn("tab {} had no seed pane in the create response; worker tab may hold an extra pane",
-                    tab.tab().tabId());
-        }
-        tidy("label tab " + tab.tab().tabId(),
-                () -> spaces.renameTab(tab.tab().tabId(), cfg.renderTabLabel(started.seq())));
-        log.info("worker started pane={} tab={} terminal={}",
-                started.agent().paneId(), started.agent().tabId(), started.agent().terminalId());
-        return started.agent();
-    }
-
-    /** Run a best-effort post-start cleanup step, logging (not throwing) on failure. */
-    private void tidy(String what, Runnable step) {
-        try {
-            step.run();
-        } catch (RuntimeException e) {
-            log.warn("post-start step failed ({}) — worker is running regardless: {}", what, e.getMessage());
-        }
-    }
-
-    /** Legacy placement: herdr splits the currently-focused tab. */
-    private Agent spawnAsPane(Map<String, String> workerEnv) {
-        log.info("spawning worker (pane placement) profile={} base_url={} argv={}",
-                cfg.profile(), cfg.baseUrl(), cfg.argv());
-        Agent worker = startUniquelyNamed(workerEnv, null).agent();
-        log.info("worker started pane={} terminal={}", worker.paneId(), worker.terminalId());
-        return worker;
-    }
-
-    /** A started worker together with the sequence its unique name/label used. */
-    private record Started(Agent agent, long seq) {
-    }
-
-    /**
-     * Start the worker under a unique herdr agent name. herdr requires each running
-     * agent's {@code name} to be distinct (a 2nd {@code name:"claude"} fails
-     * {@code agent_name_taken}) — the exact case that makes multiple workers useful. The name
-     * is {@code claude-<profile>-<nonce>-<seq>}: {@code seq} distinguishes workers within this
-     * process, and the per-process {@code nonce} keeps a fresh process (whose {@code seq}
-     * restarts at 0) from colliding with same-profile workers that outlived a restart. The
-     * retry is a belt-and-braces backstop for the astronomically unlikely nonce+seq clash;
-     * the name is a label only — herdr detects kind and status from terminal output, not it.
-     */
-    private Started startUniquelyNamed(Map<String, String> workerEnv, String tabId) {
-        HerdrException last = null;
-        for (int attempt = 0; attempt < NAME_RETRIES; attempt++) {
-            long seq = nameSeq.incrementAndGet();
-            String name = "claude-" + cfg.profile() + "-" + nameNonce + "-" + seq;
-            try {
-                return new Started(agents.start(name, cfg.argv(), workerEnv, tabId), seq);
-            } catch (HerdrException e) {
-                if (!"agent_name_taken".equals(e.code())) throw e;
-                log.debug("worker name '{}' taken, retrying", name);
-                last = e;
-            }
-        }
-        throw last;
-    }
-
-    /** All herdr-tracked agents — discovery for "what workers exist". */
-    public List<Agent> list() {
-        return agents.list();
-    }
-
-    /**
-     * Tear a worker down by pane id: close the pane, and close its tab <em>only</em> when the
-     * worker is that tab's sole occupant. The single-pane check is what makes this safe
-     * regardless of how the worker was placed (or a placement-config change across a restart):
-     * a pane-placement worker sitting in one of the user's shared tabs has siblings, so its
-     * tab is never closed — we only ever remove a tab we created to hold one worker.
-     *
-     * <p>Resolves the tab from the pane <em>before</em> closing it. An already-gone pane/tab
-     * (repeated DELETE, crashed worker) is treated as success; any other failure propagates so
-     * a genuinely failed teardown is not reported as done.
-     */
-    public void stop(String paneId) {
-        WorkspaceControl.PaneLocation loc = cfg.tabPlacement() ? spaces.locatePane(paneId) : null;
-        try {
-            agents.close(paneId);
-        } catch (HerdrException e) {
-            if (!isAlreadyGone(e)) throw e;
-            log.debug("pane.close({}) ignored — already gone: {}", paneId, e.getMessage());
-        }
-        if (loc != null && loc.tabPaneCount() == 1) {
-            spaces.closeTab(loc.tabId());
-        } else if (loc != null) {
-            log.debug("not closing tab {} — it holds {} panes (not a dedicated worker tab)",
-                    loc.tabId(), loc.tabPaneCount());
-        }
-    }
-
-    /** True when a herdr error means the target is already gone (safe to treat as done). */
-    private static boolean isAlreadyGone(HerdrException e) {
-        return e.code() != null && e.code().endsWith("_not_found");
-    }
-
-    private static void putIfPresent(Map<String, String> m, String k, String v) {
-        if (v != null && !v.isBlank()) {
-            m.put(k, v);
-        }
-    }
-}

bridged/src/main/resources/logback.xml

@@ -5,10 +5,39 @@
         </encoder>
     </appender>
 
+    <!--
+      CB-505 audit trail. Its own file, deliberately not the app log: privileged actions
+      (spawn/stop/send/reply/drain) must stay greppable and shippable without dragging DEBUG noise
+      along. AuditLog emits a complete JSON object including its own ISO-8601 "ts" field, so the
+      pattern is a bare %msg — a pattern that spliced literal braces around the message would
+      collide with logback's own variable substitution. Rolls daily, 30 days retained, 100MB cap.
+
+      NOTE: records carry who/what/target/outcome only. Message CONTENT is never written here —
+      this bridge carries source code and prompts, and an audit log that accumulated them would be
+      a transcript archive rather than a control.
+    -->
+    <appender name="AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
+        <file>logs/audit.log</file>
+        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
+            <fileNamePattern>logs/audit.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
+            <maxFileSize>10MB</maxFileSize>
+            <maxHistory>30</maxHistory>
+            <totalSizeCap>100MB</totalSizeCap>
+        </rollingPolicy>
+        <encoder>
+            <pattern>%msg%n</pattern>
+        </encoder>
+    </appender>
+
     <logger name="dev.ltms.bridged" level="DEBUG"/>
     <logger name="io.javalin" level="INFO"/>
     <logger name="org.eclipse.jetty" level="WARN"/>
 
+    <!-- additivity=false keeps the audit stream out of stdout; it is its own record. -->
+    <logger name="audit" level="INFO" additivity="false">
+        <appender-ref ref="AUDIT"/>
+    </logger>
+
     <root level="INFO">
         <appender-ref ref="STDOUT"/>
     </root>

bridged/src/test/java/dev/ltms/bridged/BridgedDeliverabilityTest.java

@@ -0,0 +1,86 @@
+package dev.ltms.bridged;
+
+import dev.ltms.bridged.inject.MemberPresence;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.function.Predicate;
+import java.util.function.Supplier;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * CB-534: the injector's readiness gate must open for a lead as well as for a present worker.
+ *
+ * <p>The bug these cover was silent and slow: a lead was never marked present (only workers are), so
+ * every lead→lead delivery sat on the gate for the full readiness grace and failed ~60s later without
+ * a keystroke ever reaching the pane.
+ */
+class BridgedDeliverabilityTest {
+
+    private static Supplier<Map<String, String>> leads(Map<String, String> m) {
+        return () -> m;
+    }
+
+    @Test
+    @DisplayName("a worker that has connected its MCP is deliverable")
+    void presentWorkerIsDeliverable() {
+        MemberPresence presence = new MemberPresence();
+        presence.markPresent("term_worker");
+
+        assertTrue(Bridged.deliverableTo(presence, leads(Map.of())).test("term_worker"));
+    }
+
+    @Test
+    @DisplayName("a worker still in its boot window is held back")
+    void absentWorkerIsNotDeliverable() {
+        assertFalse(Bridged.deliverableTo(new MemberPresence(), leads(Map.of())).test("term_booting"));
+    }
+
+    @Test
+    @DisplayName("a lead is deliverable without ever being marked present")
+    void leadIsDeliverableWithoutPresence() {
+        MemberPresence presence = new MemberPresence();
+        Predicate<String> deliverable =
+                Bridged.deliverableTo(presence, leads(Map.of("term_lead", "opus-5.0")));
+
+        assertFalse(presence.isPresent("term_lead"), "a lead is never enrolled in worker presence");
+        assertTrue(deliverable.test("term_lead"), "…and must be deliverable anyway");
+    }
+
+    @Test
+    @DisplayName("an unknown terminal is deliverable to neither")
+    void strangerIsNotDeliverable() {
+        MemberPresence presence = new MemberPresence();
+        presence.markPresent("term_worker");
+
+        assertFalse(Bridged.deliverableTo(presence, leads(Map.of("term_lead", "opus-5.0")))
+                .test("term_stranger"));
+    }
+
+    @Test
+    @DisplayName("a lead discovered after startup becomes deliverable with no restart")
+    void leadSetIsReadThroughOnEveryCall() {
+        Map<String, String> discovered = new HashMap<>();
+        Predicate<String> deliverable = Bridged.deliverableTo(new MemberPresence(), leads(discovered));
+
+        assertFalse(deliverable.test("term_late"));
+        discovered.put("term_late", "gpt-sol-5.6"); // leadScan picks up a newly labelled tab
+        assertTrue(deliverable.test("term_late"), "the supplier must be re-read, not snapshotted");
+    }
+
+    @Test
+    @DisplayName("forgetting a torn-down worker does not strip a lead of its deliverability")
+    void forgetDoesNotDisarmALead() {
+        MemberPresence presence = new MemberPresence();
+        Predicate<String> deliverable =
+                Bridged.deliverableTo(presence, leads(Map.of("term_lead", "opus-5.0")));
+
+        presence.forget("term_lead"); // the injector's cleanup path runs against every target
+
+        assertTrue(deliverable.test("term_lead"));
+    }
+}

bridged/src/test/java/dev/ltms/bridged/auth/AuditLogTest.java

@@ -0,0 +1,100 @@
+package dev.ltms.bridged.auth;
+
+import ch.qos.logback.classic.Level;
+import ch.qos.logback.classic.LoggerContext;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.LoggerFactory;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * CB-505 — the audit record's shape.
+ *
+ * <p>These exist because the first cut of this feature emitted lines that were <em>not</em> valid
+ * JSON: the timestamp was spliced on by a logback pattern whose literal braces collided with
+ * logback's variable substitution. The appender failed to parse, and nothing in the build noticed.
+ * An audit trail that silently stops being machine-readable is worse than none.
+ */
+class AuditLogTest {
+
+    private final ObjectMapper mapper = new ObjectMapper();
+    private ListAppender<ILoggingEvent> appender;
+    private ch.qos.logback.classic.Logger auditLogger;
+
+    @BeforeEach
+    void attach() {
+        LoggerContext ctx = (LoggerContext) LoggerFactory.getILoggerFactory();
+        auditLogger = ctx.getLogger("audit");
+        appender = new ListAppender<>();
+        appender.setContext(ctx);
+        appender.start();
+        auditLogger.addAppender(appender);
+        auditLogger.setLevel(Level.INFO);
+    }
+
+    @AfterEach
+    void detach() {
+        auditLogger.detachAppender(appender);
+    }
+
+    private JsonNode onlyRecord() throws Exception {
+        assertEquals(1, appender.list.size(), "exactly one audit line expected");
+        String line = appender.list.getFirst().getFormattedMessage();
+        return mapper.readTree(line); // throws if the line is not valid JSON
+    }
+
+    @Test
+    void anAllowedActionIsRecordedAsValidJson() throws Exception {
+        AuditLog.allowed(Principal.primary(4242), Authz.Action.SPAWN, "term_a");
+
+        JsonNode r = onlyRecord();
+        assertEquals("PRIMARY", r.path("role").asText());
+        assertEquals("primary", r.path("actor").asText());
+        assertEquals(4242, r.path("pid").asLong());
+        assertEquals("SPAWN", r.path("action").asText());
+        assertEquals("term_a", r.path("target").asText());
+        assertEquals("allowed", r.path("outcome").asText());
+        assertFalse(r.path("ts").asText().isBlank(), "every record carries its own timestamp");
+    }
+
+    @Test
+    void aDenialRecordsTheReason() throws Exception {
+        AuditLog.denied(Principal.worker("term_b", 7), Authz.Action.REPLY, "term_a", "forbidden");
+
+        JsonNode r = onlyRecord();
+        assertEquals("WORKER", r.path("role").asText());
+        assertEquals("worker:term_b", r.path("actor").asText());
+        assertEquals("denied", r.path("outcome").asText());
+        assertEquals("forbidden", r.path("reason").asText());
+    }
+
+    @Test
+    void aNullCallerIsRecordedAsAnonymousRatherThanCrashing() throws Exception {
+        AuditLog.failed(null, Authz.Action.SEND, null, "herdr unreachable");
+
+        JsonNode r = onlyRecord();
+        assertEquals("ANONYMOUS", r.path("role").asText());
+        assertTrue(r.path("target").isNull(), "an absent target is JSON null, not the string \"null\"");
+        assertEquals("failed", r.path("outcome").asText());
+    }
+
+    @Test
+    void hostileValuesAreEscapedAndCannotForgeAnExtraRecord() throws Exception {
+        // A target id containing a quote and a newline must not be able to terminate the JSON
+        // object early and inject a second, attacker-shaped audit line.
+        AuditLog.denied(Principal.worker("term_a", 1), Authz.Action.REPLY,
+                "evil\",\"outcome\":\"allowed\"}\n{\"forged\":true", "forbidden");
+
+        JsonNode r = onlyRecord();
+        assertEquals("denied", r.path("outcome").asText(),
+                "the injected outcome must not override the real one");
+        assertTrue(r.path("target").asText().contains("forged"),
+                "the hostile text survives as inert data inside the target field");
+    }
+}

bridged/src/test/java/dev/ltms/bridged/auth/AuthzTest.java

@@ -0,0 +1,124 @@
+package dev.ltms.bridged.auth;
+
+import org.junit.jupiter.api.Test;
+
+import static dev.ltms.bridged.auth.Authz.Action.*;
+import static org.junit.jupiter.api.Assertions.*;
+
+/** CB-505 — the authorization table, pinned so it cannot drift silently. */
+class AuthzTest {
+
+    private static final Principal PRIMARY = Principal.primary(100);
+    private static final Principal WORKER_A = Principal.worker("term_a", 200);
+    private static final Principal WORKER_B = Principal.worker("term_b", 300);
+    private static final Principal ANON = Principal.anonymous();
+    private static final Principal ARCH_DESIGN = Principal.architect("lead-designer", "term_design", 400);
+    private static final Principal ARCH_OTHER = Principal.architect("reviewer", "term_review", 500);
+
+    @Test
+    void anonymousIsAuthorizedForNothing() {
+        for (Authz.Action a : Authz.Action.values()) {
+            assertFalse(Authz.permits(ANON, a, "term_a"),
+                    a + " must be refused to an unauthenticated caller");
+        }
+    }
+
+    @Test
+    void aNullCallerIsTreatedAsAnonymous() {
+        assertFalse(Authz.permits(null, READ, null));
+        assertTrue(Authz.isUnauthenticated(null));
+    }
+
+    @Test
+    void orchestrationBelongsToThePrimaryAlone() {
+        for (Authz.Action a : new Authz.Action[]{SPAWN, STOP, SEND, DRAIN}) {
+            assertTrue(Authz.permits(PRIMARY, a, "term_a"), "the primary orchestrates: " + a);
+            assertFalse(Authz.permits(WORKER_A, a, "term_a"),
+                    "a worker performing " + a + " would be escalating into the orchestrator role");
+        }
+    }
+
+    @Test
+    void aWorkerMayReplyAndAskOnlyAsItself() {
+        assertTrue(Authz.permits(WORKER_A, REPLY, "term_a"));
+        assertTrue(Authz.permits(WORKER_A, ASK, "term_a"));
+
+        assertFalse(Authz.permits(WORKER_A, REPLY, "term_b"),
+                "worker A must not be able to reply on worker B's session");
+        assertFalse(Authz.permits(WORKER_B, ASK, "term_a"),
+                "worker B must not be able to ask as worker A");
+    }
+
+    @Test
+    void thePrimaryMayNotForgeAWorkersReply() {
+        // Not a hypothetical nicety: a forged reply would resolve the rendezvous the primary is
+        // itself blocked on, corrupting the correlation between a turn and its answer.
+        assertFalse(Authz.permits(PRIMARY, REPLY, "term_a"));
+        assertFalse(Authz.permits(PRIMARY, ASK, "term_a"));
+    }
+
+    @Test
+    void aWorkerWithNoTargetCannotReply() {
+        assertFalse(Authz.permits(WORKER_A, REPLY, null),
+                "an absent session id must not satisfy the own-session rule");
+    }
+
+    // ── CB-548: the architect matrix ───────────────────────────────────────────────────────────
+
+    @Test
+    void anArchitectMaySendButNotSpawnStopOrDrain() {
+        assertTrue(Authz.permits(ARCH_DESIGN, SEND, "term_worker"),
+                "delegating a turn to a worker IS the architect's job");
+        assertTrue(Authz.permits(ARCH_DESIGN, SEND, null));
+
+        for (Authz.Action a : new Authz.Action[]{SPAWN, STOP, DRAIN}) {
+            assertFalse(Authz.permits(ARCH_DESIGN, a, null),
+                    "an architect must not " + a + " — fleet lifecycle is the primary's alone, so "
+                            + "a coordinator cannot also stand up or tear down the fleet");
+        }
+    }
+
+    @Test
+    void anArchitectMayReplyAndAskOnlyAsItsOwnPane() {
+        assertTrue(Authz.permits(ARCH_DESIGN, REPLY, "term_design"), "its own pane is its own");
+        assertTrue(Authz.permits(ARCH_DESIGN, ASK, "term_design"));
+
+        assertFalse(Authz.permits(ARCH_DESIGN, REPLY, "term_review"),
+                "architect 'lead-designer' must not reply on reviewer's pane");
+        assertFalse(Authz.permits(ARCH_OTHER, ASK, "term_design"),
+                "reviewer must not ask as lead-designer — no terminal is another's");
+        assertFalse(Authz.permits(ARCH_DESIGN, REPLY, null),
+                "an absent target must not pass the own-session rule");
+    }
+
+    @Test
+    void anArchitectMayReadAndScrapeMetrics() {
+        assertTrue(Authz.permits(ARCH_DESIGN, READ, null));
+        assertTrue(Authz.permits(ARCH_DESIGN, METRICS, null));
+    }
+
+    @Test
+    void anArchitectIsNotCountedAsPrimaryOrWorker() {
+        assertFalse(Authz.permits(ARCH_DESIGN, SPAWN, null), "not a primary — no lifecycle");
+        assertFalse(ARCH_DESIGN.isPrimary());
+        assertFalse(ARCH_DESIGN.isWorker(), "an architect is its own role, not a widened worker");
+        assertTrue(ARCH_DESIGN.isArchitect());
+    }
+
+    @Test
+    void observationIsOpenToBothAuthenticatedRoles() {
+        assertTrue(Authz.permits(PRIMARY, READ, null));
+        assertTrue(Authz.permits(WORKER_A, READ, null));
+        assertTrue(Authz.permits(PRIMARY, METRICS, null));
+        assertTrue(Authz.permits(WORKER_A, METRICS, null));
+    }
+
+    @Test
+    void unauthenticatedIsDistinguishedFromMerelyForbidden() {
+        // Drives the 401-vs-403 split: a missing credential is fixable by the caller, a wrong role
+        // is not.
+        assertTrue(Authz.isUnauthenticated(ANON));
+        assertFalse(Authz.isUnauthenticated(WORKER_A));
+        assertFalse(Authz.isUnauthenticated(PRIMARY));
+    }
+}

bridged/src/test/java/dev/ltms/bridged/auth/CallerResolverTest.java

@@ -0,0 +1,399 @@
+package dev.ltms.bridged.auth;
+
+import dev.ltms.bridged.herdr.FakeHerdr;
+import dev.ltms.bridged.herdr.PaneLocator;
+import dev.ltms.bridged.mcp.ConnectionIdentity;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * CB-501. The behaviour under test is the inversion of the pre-CB-501 default: failing every
+ * identity check must yield {@link Role#ANONYMOUS}, not {@code PRIMARY}.
+ */
+class CallerResolverTest {
+
+    private final FakeHerdr herdr = new FakeHerdr();
+
+    /** Identity resolving the canned worker pane, keyed off a faked peer-PID lookup. */
+    private ConnectionIdentity identity(long pid) {
+        return new ConnectionIdentity(new PaneLocator(herdr), _ -> pid);
+    }
+
+    /** A PID that owns a worker pane in the fake. */
+    private ConnectionIdentity workerIdentity() {
+        return identity(FakeHerdr.WORKER_PID);
+    }
+
+    /** A PID that owns no pane — i.e. the primary, or any other local process. */
+    private ConnectionIdentity nonWorkerIdentity() {
+        return identity(999_999);
+    }
+
+    @Test
+    void aLoopbackWorkerPaneResolvesToWorkerRegardlessOfAuthMode() {
+        Principal underTrust = new CallerResolver(workerIdentity()).resolve("127.0.0.1", 42, null);
+        Principal underToken = new CallerResolver(workerIdentity(), true, "s3cret")
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.WORKER, underTrust.role());
+        assertEquals("term_a", underTrust.terminal());
+        assertEquals(Role.WORKER, underToken.role(),
+                "worker identity is unforgeable and must never be token-gated — otherwise enabling "
+                        + "auth would lock the whole fleet out of bridge_reply");
+        assertEquals("term_a", underToken.terminal());
+    }
+
+    @Test
+    void aPinnedPrimaryTerminalResolvesToPrimaryNotWorker() {
+        // The primary's own session lives in a herdr pane (term_a here). Without the pin the pane
+        // match wins and the primary is locked out of spawn/send/stop as a misread worker.
+        Principal p = CallerResolver.pinnedTo(workerIdentity(), false, null, "term_a")
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role());
+    }
+
+    @Test
+    void aPinnedPrimaryTerminalNeedsNoTokenEvenInTokenMode() {
+        Principal p = CallerResolver.pinnedTo(workerIdentity(), true, "s3cret", "term_a")
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role(),
+                "the pane mapping is as unforgeable as a worker's — the pin outranks the token path");
+    }
+
+    @Test
+    void otherPanesRemainWorkersWhenAPinIsSet() {
+        Principal p = CallerResolver.pinnedTo(workerIdentity(), false, null, "term_someone_else")
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.WORKER, p.role());
+        assertEquals("term_a", p.terminal());
+    }
+
+    /** The pin is optional config, so an absent or whitespace one must change nothing at all. */
+    @Test
+    void aBlankPinLeavesWorkerResolutionUntouched() {
+        assertEquals(Role.WORKER,
+                CallerResolver.pinnedTo(workerIdentity(), false, null, "  ").resolve("127.0.0.1", 42, null).role());
+        assertEquals(Role.WORKER,
+                CallerResolver.pinnedTo(workerIdentity(), false, null, null).resolve("127.0.0.1", 42, null).role());
+    }
+
+    @Test
+    void loopbackTrustTreatsANonWorkerLoopbackCallerAsThePrimary() {
+        Principal p = new CallerResolver(nonWorkerIdentity()).resolve("127.0.0.1", 99, null);
+
+        assertEquals(Role.PRIMARY, p.role(), "the historical behaviour, now an explicit choice");
+    }
+
+    @Test
+    void tokenModeRefusesANonWorkerCallerThatPresentsNoToken() {
+        Principal p = new CallerResolver(nonWorkerIdentity(), true, "s3cret")
+                .resolve("127.0.0.1", 99, null);
+
+        assertEquals(Role.ANONYMOUS, p.role(),
+                "no credential must mean NOTHING, not the most privileged role on the bus");
+    }
+
+    @Test
+    void tokenModeAcceptsAValidBearerTokenAsThePrimary() {
+        Principal p = new CallerResolver(nonWorkerIdentity(), true, "s3cret")
+                .resolve("127.0.0.1", 99, "Bearer s3cret");
+
+        assertEquals(Role.PRIMARY, p.role());
+    }
+
+    @Test
+    void tokenModeRejectsAWrongOrMalformedCredential() {
+        CallerResolver r = new CallerResolver(nonWorkerIdentity(), true, "s3cret");
+
+        assertEquals(Role.ANONYMOUS, r.resolve("127.0.0.1", 99, "Bearer wrong").role());
+        assertEquals(Role.ANONYMOUS, r.resolve("127.0.0.1", 99, "s3cret").role(), "scheme required");
+        assertEquals(Role.ANONYMOUS, r.resolve("127.0.0.1", 99, "Bearer ").role(), "empty credential");
+        assertEquals(Role.ANONYMOUS, r.resolve("127.0.0.1", 99, "Basic s3cret").role(), "wrong scheme");
+    }
+
+    @Test
+    void theBearerSchemeIsCaseInsensitivePerRfc7235() {
+        CallerResolver r = new CallerResolver(nonWorkerIdentity(), true, "s3cret");
+
+        assertEquals(Role.PRIMARY, r.resolve("127.0.0.1", 99, "bearer s3cret").role());
+        assertEquals(Role.PRIMARY, r.resolve("127.0.0.1", 99, "BEARER s3cret").role());
+    }
+
+    @Test
+    void aNonLoopbackCallerIsNeverThePrimaryUnderLoopbackTrust() {
+        // Defence in depth: startup already refuses this pairing (validateAuthExposure), but if a
+        // proxy ever forwards a remote peer onto the loopback listener, the resolver must not
+        // hand it the primary role.
+        Principal p = new CallerResolver(nonWorkerIdentity()).resolve("10.0.0.7", 99, null);
+
+        assertEquals(Role.ANONYMOUS, p.role());
+    }
+
+    // ── CB-530: the leaders registry ────────────────────────────────────────────────────────────
+    // The fake resolves exactly one pane (term_a) from a PID, so "two leads both resolve" is
+    // asserted at the config layer (BridgedConfigTest#leaderTerminals…). What matters here is that
+    // resolution is a REGISTRY LOOKUP rather than a single equality test against one pin.
+
+    @Test
+    void aRegisteredLeadPaneResolvesToPrimaryCarryingItsName() {
+        Principal p = new CallerResolver(workerIdentity(), false, null, Map.of("term_a", "opus-5.0"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role());
+        assertEquals("opus-5.0", p.name(), "whoami must be able to say WHICH lead is asking");
+        assertEquals("term_a", p.terminal(),
+                "CB-532: a lead carries the pane it was matched by. Without it ownsSession() can "
+                        + "never be true for a lead, so it can send to a peer but never answer one");
+    }
+
+    @Test
+    void aSecondLeadIsRecognisedRatherThanSilentlyDemoted() {
+        // The regression this feature exists for: with a singular pin, whichever lead was not the
+        // pin resolved as a worker and was refused every orchestration call.
+        Principal p = new CallerResolver(workerIdentity(), false, null,
+                Map.of("term_elsewhere", "gpt-sol-5.6", "term_a", "opus-5.0"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role());
+        assertEquals("opus-5.0", p.name());
+    }
+
+    @Test
+    void aPaneAbsentFromTheRegistryIsStillAWorker() {
+        Principal p = new CallerResolver(workerIdentity(), false, null,
+                Map.of("term_elsewhere", "gpt-sol-5.6"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.WORKER, p.role());
+        assertEquals("term_a", p.terminal());
+        assertNull(p.name());
+    }
+
+    @Test
+    void aRegisteredLeadNeedsNoTokenEvenInTokenMode() {
+        Principal p = new CallerResolver(workerIdentity(), true, "s3cret", Map.of("term_a", "opus"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role(),
+                "the pane mapping is as unforgeable as a worker's — it outranks the token path");
+        assertEquals("opus", p.name());
+    }
+
+    /** The pre-CB-530 spelling must keep working, exactly, including for configs that never migrate. */
+    @Test
+    void theLegacySinglePinBehavesAsALeadNamedPrimary() {
+        Principal p = CallerResolver.pinnedTo(workerIdentity(), false, null, "term_a")
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role());
+        assertEquals("primary", p.name());
+    }
+
+    @Test
+    void anEmptyRegistryLeavesEveryPaneAWorker() {
+        Map<String, String> noLeads = null;
+        assertEquals(Role.WORKER,
+                new CallerResolver(workerIdentity(), false, null, Map.of())
+                        .resolve("127.0.0.1", 42, null).role());
+        assertEquals(Role.WORKER,
+                new CallerResolver(workerIdentity(), false, null, noLeads)
+                        .resolve("127.0.0.1", 42, null).role());
+        // CB-531: and the same for the live-registry form, whose supplier may also be absent.
+        assertEquals(Role.WORKER,
+                CallerResolver.withLeads(workerIdentity(), false, null, null)
+                        .resolve("127.0.0.1", 42, null).role());
+    }
+
+    /** The audit line must distinguish leads once several exist, or a log says nothing useful. */
+    @Test
+    void describeNamesTheLeadButStillReadsPrimaryWhenUnnamed() {
+        assertEquals("leader:opus-5.0", Principal.leader("opus-5.0", "term_a", 1).describe());
+        assertEquals("primary", Principal.primary(1).describe());
+        assertEquals("worker:term_a", Principal.worker("term_a", 1).describe());
+    }
+
+    // ── CB-532: a lead is an addressable peer, not only a sender ────────────────────────────────
+
+    /**
+     * The regression this ticket exists for: two leads could both be recognised (CB-530/531) and
+     * still not converse, because REPLY is gated on ownsSession() and a lead owned nothing.
+     */
+    @Test
+    void aLeadOwnsItsOwnPaneSoItMayAnswerAPeer() {
+        Principal lead = new CallerResolver(workerIdentity(), false, null, Map.of("term_a", "opus-5.0"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertTrue(lead.ownsSession("term_a"));
+        assertTrue(Authz.permits(lead, Authz.Action.REPLY, "term_a"),
+                "a lead answering a peer replies for its OWN terminal — the rendezvous the sender "
+                        + "opened is keyed on exactly that");
+        assertTrue(Authz.permits(lead, Authz.Action.ASK, "term_a"));
+    }
+
+    @Test
+    void aLeadStillCannotActAsAnyoneElse() {
+        Principal lead = new CallerResolver(workerIdentity(), false, null, Map.of("term_a", "opus-5.0"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertFalse(lead.ownsSession("term_someone_else"));
+        assertFalse(Authz.permits(lead, Authz.Action.REPLY, "term_someone_else"),
+                "widening WHO may reply must not widen WHAT they may reply as");
+    }
+
+    /** A primary with no pane — token mode, or off-host — owns nothing and must stay a sender only. */
+    @Test
+    void anUnnamedPrimaryWithNoPaneOwnsNothing() {
+        Principal p = new CallerResolver(nonWorkerIdentity(), true, "s3cret")
+                .resolve("127.0.0.1", 99, "Bearer s3cret");
+
+        assertEquals(Role.PRIMARY, p.role());
+        assertNull(p.terminal());
+        assertFalse(p.ownsSession(null), "a null terminal must never match a null session id");
+        assertFalse(Authz.permits(p, Authz.Action.REPLY, null));
+    }
+
+    @Test
+    void aLeadKeepsEveryOrchestrationRightItAlreadyHad() {
+        Principal lead = new CallerResolver(workerIdentity(), false, null, Map.of("term_a", "opus-5.0"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertTrue(Authz.permits(lead, Authz.Action.SPAWN, null));
+        assertTrue(Authz.permits(lead, Authz.Action.SEND, "term_worker"));
+        assertTrue(Authz.permits(lead, Authz.Action.STOP, null));
+        assertTrue(Authz.permits(lead, Authz.Action.DRAIN, null));
+    }
+
+    /**
+     * CB-531: the registry is read per resolve, not snapshotted at construction — a lead that
+     * labels its tab after the daemon booted is recognised without a restart.
+     */
+    @Test
+    void aLeadRegisteredAfterConstructionIsHonouredWithoutRebuildingTheResolver() {
+        Map<String, String> live = new java.util.HashMap<>();
+        CallerResolver r = CallerResolver.withLeads(workerIdentity(), false, null, () -> live);
+
+        assertEquals(Role.WORKER, r.resolve("127.0.0.1", 42, null).role());
+
+        live.put("term_a", "gpt-sol-5.6"); // the scanner sees a newly-labelled tab
+
+        Principal p = r.resolve("127.0.0.1", 42, null);
+        assertEquals(Role.PRIMARY, p.role());
+        assertEquals("gpt-sol-5.6", p.name());
+    }
+
+    /** The map form must stay a snapshot: a caller handing over a map is not offering live state. */
+    @Test
+    void theMapFormIsCopiedSoLaterMutationCannotGrantLeadership() {
+        Map<String, String> mutable = new java.util.HashMap<>();
+        CallerResolver r = new CallerResolver(workerIdentity(), false, null, mutable);
+
+        mutable.put("term_a", "sneaky");
+
+        assertEquals(Role.WORKER, r.resolve("127.0.0.1", 42, null).role());
+    }
+
+    // ── CB-548: architect slots ─────────────────────────────────────────────────────────────────
+
+    @Test
+    void aBoundArchitectPaneResolvesToArchitectBeforeTheWorkerFallback() {
+        Principal p = CallerResolver.withLeadsAndMembers(workerIdentity(), false, null,
+                Map::of, () -> Map.of("term_a", "lead-designer"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.ARCHITECT, p.role(),
+                "a terminal bound to an architect slot is an architect, NOT the generic worker it "
+                        + "would otherwise resolve to");
+        assertEquals("lead-designer", p.name(), "whoami must say WHICH slot is asking");
+        assertEquals("term_a", p.terminal(), "the pane identity is carried so ownsSession works");
+    }
+
+    @Test
+    void anArchitectNeedsNoTokenEvenInTokenMode() {
+        Principal p = CallerResolver.withLeadsAndMembers(workerIdentity(), true, "s3cret",
+                Map::of, () -> Map.of("term_a", "lead-designer"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.ARCHITECT, p.role(),
+                "the pane mapping is as unforgeable as a worker's — it outranks the token path");
+    }
+
+    @Test
+    void anUnboundPaneStillResolvesAsAWorker() {
+        Map<String, String> arch = Map.of("term_elsewhere", "reviewer");
+        Principal p = CallerResolver.withLeadsAndMembers(workerIdentity(), false, null,
+                Map::of, () -> arch).resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.WORKER, p.role());
+        assertNull(p.name());
+    }
+
+    /** CB-548 precedence: lead > architect > worker, so a pane named in BOTH is still a lead. */
+    @Test
+    void aLeadWinsOverAnArchitectBindingForTheSamePane() {
+        Principal p = CallerResolver.withLeadsAndMembers(workerIdentity(), false, null,
+                () -> Map.of("term_a", "opus-5.0"), () -> Map.of("term_a", "lead-designer"))
+                .resolve("127.0.0.1", 42, null);
+
+        assertEquals(Role.PRIMARY, p.role(),
+                "a pane the config calls a lead must keep resolving as a lead — no behaviour change "
+                        + "when an architect binding is added to an existing fleet");
+        assertEquals("opus-5.0", p.name());
+    }
+
+    /** The registry is live, like leads: a binding injected after construction is honoured. */
+    @Test
+    void anArchitectBoundAfterConstructionIsHonouredWithoutRebuildingTheResolver() {
+        Map<String, String> live = new java.util.HashMap<>();
+        CallerResolver r = CallerResolver.withLeadsAndMembers(workerIdentity(), false, null,
+                Map::of, () -> live);
+
+        assertEquals(Role.WORKER, r.resolve("127.0.0.1", 42, null).role());
+
+        live.put("term_a", "lead-designer"); // the later lifecycle binds the slot
+
+        assertEquals(Role.ARCHITECT, r.resolve("127.0.0.1", 42, null).role());
+        assertEquals("lead-designer", r.members().get("term_a"));
+    }
+
+    @Test
+    void theArchitectMapFormIsCopiedSoLaterMutationCannotGrantArchitect() {
+        Map<String, String> mutable = new java.util.LinkedHashMap<>();
+        CallerResolver r = new CallerResolver(workerIdentity(), false, null, Map.of(), mutable);
+
+        mutable.put("term_a", "sneaky");
+
+        assertEquals(Role.WORKER, r.resolve("127.0.0.1", 42, null).role());
+    }
+
+    @Test
+    void describeNamesTheArchitectSlot() {
+        assertEquals("architect:lead-designer",
+                Principal.architect("lead-designer", "term_a", 1).describe());
+    }
+
+    /** An architect acts only as its own pane — the same ownsSession rule as a worker or lead. */
+    @Test
+    void anArchitectOwnsItsOwnPaneAndNoOther() {
+        Principal arch = CallerResolver.withLeadsAndMembers(workerIdentity(), false, null,
+                Map::of, () -> Map.of("term_a", "lead-designer")).resolve("127.0.0.1", 42, null);
+
+        assertTrue(arch.ownsSession("term_a"));
+        assertTrue(Authz.permits(arch, Authz.Action.REPLY, "term_a"));
+        assertFalse(arch.ownsSession("term_b"));
+        assertFalse(Authz.permits(arch, Authz.Action.REPLY, "term_b"));
+    }
+
+    @Test
+    void tokenModeRequiresANonEmptyConfiguredToken() {
+        ConnectionIdentity id = nonWorkerIdentity();
+
+        assertThrows(IllegalArgumentException.class, () -> new CallerResolver(id, true, null));
+        assertThrows(IllegalArgumentException.class, () -> new CallerResolver(id, true, "  "));
+    }
+}

bridged/src/test/java/dev/ltms/bridged/auth/MemberRegistryTest.java

@@ -0,0 +1,269 @@
+package dev.ltms.bridged.auth;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import dev.ltms.bridged.peer.MemberRole;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * CB-548 — the architect-slot registry: the config snapshot of slot → profile, and the live
+ * terminal → slot bindings it owns. The role a binding produces is asserted in
+ * {@link CallerResolverTest}; this pins the registry object itself — its invariants and their
+ * thread-safety.
+ */
+class MemberRegistryTest {
+
+    /**
+     * Slot keys are qualified by role (CB-557): a bare name is unique only within its pool, so
+     * {@code sonnet} can be both a developer and a reviewer, while a terminal binds to exactly one.
+     */
+    private static final String DESIGNER = "architect:lead-designer";
+    private static final String REVIEWER = "architect:code-reviewer";
+
+    private static BridgedConfig.Fleet fleetWith(Map<String, BridgedConfig.Slot> architects) {
+        return new BridgedConfig.Fleet(Map.of(), architects, Map.of(), Map.of(), null);
+    }
+
+    private static Map<String, BridgedConfig.Slot> architects() {
+        Map<String, BridgedConfig.Slot> pool = new LinkedHashMap<>();
+        pool.put("lead-designer", new BridgedConfig.Slot("sonnet"));
+        pool.put("code-reviewer", new BridgedConfig.Slot("gx10"));
+        return pool;
+    }
+
+    private final MemberRegistry registry = new MemberRegistry(fleetWith(architects()));
+
+    @Test
+    void exposesTheConfiguredSlotsQualifiedByRole() {
+        assertEquals(Set.of(DESIGNER, REVIEWER), registry.slots().keySet());
+        assertTrue(registry.isSlot(REVIEWER));
+        assertFalse(registry.isSlot("nope"));
+        assertFalse(registry.isSlot("lead-designer"),
+                "the bare name is not the key — it is unique only inside its pool");
+    }
+
+    /** The case the pool shape exists for: one profile serving two roles is not a duplicate. */
+    @Test
+    void oneProfileMayServeTwoRolesUnderTheSameSlotName() {
+        Map<String, BridgedConfig.Slot> devs = Map.of("sonnet", new BridgedConfig.Slot("sonnet"));
+        Map<String, BridgedConfig.Slot> revs = Map.of("sonnet", new BridgedConfig.Slot("sonnet"));
+        MemberRegistry r = new MemberRegistry(
+                new BridgedConfig.Fleet(Map.of(), Map.of(), devs, revs, null));
+
+        assertEquals(Set.of("dev:sonnet", "reviewer:sonnet"), r.slots().keySet());
+        assertEquals(MemberRole.DEV, r.roleForSlot("dev:sonnet"));
+        assertEquals(MemberRole.REVIEWER, r.roleForSlot("reviewer:sonnet"));
+    }
+
+    @Test
+    void theSpawnLifecycleReadsTheProfileBackFromASlot() {
+        assertEquals("sonnet", registry.profileForSlot(DESIGNER));
+        assertEquals("gx10", registry.profileForSlot(REVIEWER));
+        assertNull(registry.profileForSlot("unknown"), "an unknown slot has no profile");
+    }
+
+    @Test
+    void startsEmptySoNoTerminalResolvesToAnArchitect() {
+        assertTrue(registry.snapshot().isEmpty());
+        assertNull(registry.slotForTerminal("term_design"),
+                "config declares no architect terminal — nothing is recognised until a bind");
+        assertNull(registry.slotForTerminal(null), "no terminal ⇒ no slot");
+    }
+
+    // ── bind ──────────────────────────────────────────────────────────────────────────────────
+
+    @Test
+    void bindResolvesTheTerminalToTheSlot() {
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        assertEquals(DESIGNER, registry.slotForTerminal("term_design"));
+        assertEquals(Map.of("term_design", DESIGNER), registry.snapshot());
+    }
+
+    @Test
+    void bindRefusesAnUnknownSlot() {
+        assertFalse(registry.bind("nope", "term_x"),
+                "a slot that is not configured must be refused — bind is not a way to invent one");
+        assertNull(registry.slotForTerminal("term_x"));
+    }
+
+    @Test
+    void bindRefusesATerminalInTwoSlots() {
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        assertFalse(registry.bind(REVIEWER, "term_design"),
+                "a terminal may occupy at most one slot");
+        assertEquals(DESIGNER, registry.slotForTerminal("term_design"),
+                "the first binding survives the refused second");
+    }
+
+    @Test
+    void bindRefusesASlotWithTwoTerminals() {
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        assertFalse(registry.bind(DESIGNER, "term_other"),
+                "a slot may host at most one terminal");
+        assertEquals(DESIGNER, registry.slotForTerminal("term_design"),
+                "the first binding survives the refused second");
+        assertNull(registry.slotForTerminal("term_other"));
+    }
+
+    @Test
+    void rebindingTheSamePairIsAnIdempotentNoOp() {
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        assertTrue(registry.bind(DESIGNER, "term_design"),
+                "the same terminal → slot is harmless to repeat");
+        assertEquals(1, registry.snapshot().size());
+    }
+
+    // ── unbind ────────────────────────────────────────────────────────────────────────────────
+
+    @Test
+    void unbindRemovesTheExactBinding() {
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        assertTrue(registry.unbind(DESIGNER, "term_design"));
+        assertNull(registry.slotForTerminal("term_design"));
+        assertTrue(registry.snapshot().isEmpty());
+    }
+
+    @Test
+    void aStaleUnbindDoesNotRemoveAReplacement() {
+        // Bind, tear down, and stand the slot back up with a NEW terminal.
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        registry.unbind(DESIGNER, "term_design");
+        assertTrue(registry.bind(DESIGNER, "term_new"));
+
+        // A late unbind naming the OLD terminal must not remove the replacement binding.
+        assertFalse(registry.unbind(DESIGNER, "term_design"));
+        assertEquals(DESIGNER, registry.slotForTerminal("term_new"),
+                "the replacement terminal stays bound");
+    }
+
+    @Test
+    void aStaleUnbindForATerminalThatMovedSlotsDoesNothing() {
+        // term_design starts in lead-designer, is torn down, and stands back up in a FREE slot.
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        registry.unbind(DESIGNER, "term_design");
+        assertTrue(registry.bind(REVIEWER, "term_design"));
+
+        // Unbinding against the slot it no longer occupies is refused; the new binding is intact.
+        assertFalse(registry.unbind(DESIGNER, "term_design"),
+                "the old slot must not unbind a terminal that moved elsewhere");
+        assertEquals(REVIEWER, registry.slotForTerminal("term_design"));
+    }
+
+    @Test
+    void unbindOfNothingIsAFalseNoOp() {
+        assertFalse(registry.unbind(DESIGNER, "term_design"),
+                "nothing was bound, so nothing is removed");
+    }
+
+    // ── snapshot ─────────────────────────────────────────────────────────────────────────────
+
+    @Test
+    void theSnapshotIsAnImmutableCopyNotAliveState() {
+        assertTrue(registry.bind(DESIGNER, "term_design"));
+        Map<String, String> snap = registry.snapshot();
+
+        assertThrows(UnsupportedOperationException.class, () -> snap.put("x", "y"),
+                "a handed-out snapshot cannot be mutated in place");
+
+        // Later binds must not leak into an earlier snapshot.
+        assertTrue(registry.bind(REVIEWER, "term_review"));
+        assertFalse(snap.containsKey("term_review"),
+                "a snapshot is a point-in-time copy, not a live view");
+    }
+
+    // ── concurrency (CB-548 invariants hold under contention) ─────────────────────────────────
+
+    @Test
+    void concurrentBindsNeverGiveASlotTwoTerminals() throws Exception {
+        int n = 16;
+        ExecutorService pool = Executors.newFixedThreadPool(n);
+        try {
+            CountDownLatch go = new CountDownLatch(1);
+            List<Future<Boolean>> results = new ArrayList<>();
+            for (int i = 0; i < n; i++) {
+                final String term = "term_" + i; // every thread races for the SAME slot
+                results.add(pool.submit(() -> {
+                    go.await();
+                    return registry.bind(DESIGNER, term);
+                }));
+            }
+            go.countDown();
+
+            int won = 0;
+            for (Future<Boolean> r : results) {
+                if (r.get()) {
+                    won++;
+                }
+            }
+            assertEquals(1, won, "exactly one terminal may win the sole slot, got " + won);
+            assertEquals(1, registry.snapshot().size(),
+                    "the slot hosts at most one terminal after the race");
+        } finally {
+            pool.shutdownNow();
+        }
+    }
+
+    @Test
+    void concurrentBindsNeverPutOneTerminalInTwoSlots() throws Exception {
+        int n = 16;
+        ExecutorService pool = Executors.newFixedThreadPool(n);
+        try {
+            CountDownLatch go = new CountDownLatch(1);
+            List<Future<String>> results = new ArrayList<>();
+            for (int i = 0; i < n; i++) {
+                final String slot = (i % 2 == 0) ? DESIGNER : REVIEWER; // all race for ONE terminal
+                results.add(pool.submit(() -> {
+                    go.await();
+                    return registry.bind(slot, "shared_term")
+                            ? registry.slotForTerminal("shared_term") : null;
+                }));
+            }
+            go.countDown();
+
+            // Rebinding the same terminal to the same slot is a harmless idempotent true, so count
+            // winners is not the assertion — agreement is: every thread that reported success must
+            // have seen the terminal in the SAME slot, never in two at once.
+            String bound = null;
+            boolean conflict = false;
+            for (Future<String> r : results) {
+                String s = r.get();
+                if (s != null) {
+                    if (bound == null) {
+                        bound = s;
+                    } else if (!bound.equals(s)) {
+                        conflict = true;
+                    }
+                }
+            }
+            assertFalse(conflict, "a terminal was observed in two slots at once");
+            assertNotNull(bound, "at least one thread bound the terminal");
+            assertEquals(1, registry.snapshot().size(),
+                    "the terminal occupies exactly one slot in the final snapshot");
+            assertEquals(bound, registry.slotForTerminal("shared_term"));
+        } finally {
+            pool.shutdownNow();
+        }
+    }
+
+    /** A handed-over slot map is snapshotted at construction, not offered as live state. */
+    @Test
+    void theSlotSnapshotIsFixedByConstruction() {
+        Map<String, BridgedConfig.Slot> mutable = architects();
+        MemberRegistry r = new MemberRegistry(fleetWith(mutable));
+
+        mutable.put("hijack", new BridgedConfig.Slot("gx10"));
+
+        assertFalse(r.isSlot("architect:hijack"), "a handed-over map is not offered as live state");
+    }
+}

bridged/src/test/java/dev/ltms/bridged/config/ConfigRefTest.java

@@ -0,0 +1,295 @@
+package dev.ltms.bridged.config;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * CB-559: re-reading {@code bridged.yaml} under a running daemon.
+ *
+ * <p>The tests that matter here are the refusals. A reload that applies a good file is the easy
+ * half; the half that protects an operator is the one that keeps the running config when the new
+ * file is bad, and the one that refuses a change the running daemon cannot honour.
+ */
+class ConfigRefTest {
+
+    /** A minimal file that loads and passes every startup validator. */
+    private static String yaml(String extra) {
+        return """
+                bind:
+                  host: 127.0.0.1
+                  port: 8765
+                herdrSocket: ~/.config/herdr/herdr.sock
+                profiles:
+                  sonnet:
+                    baseUrl: http://gx00.gw:8000
+                    model: sonnet
+                guard:
+                  offSubscriptionHosts:
+                    - gx00.gw
+                """ + extra;
+    }
+
+    private static ConfigRef refFor(Path f) {
+        return new ConfigRef(f, BridgedConfig.load(f));
+    }
+
+    @Test
+    void aHotChangeIsAppliedAndReadThroughGet(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml("""
+                fleet:
+                  tabLabel: "{role}: {profile} #{n}"
+                  developers:
+                    a:
+                      profile: sonnet
+                """));
+        ConfigRef ref = refFor(f);
+        assertEquals("{role}: {profile} #{n}", ref.get().fleet().tabLabel());
+
+        Files.writeString(f, yaml("""
+                fleet:
+                  tabLabel: "[{profile}] {role}"
+                  developers:
+                    a:
+                      profile: sonnet
+                """));
+        ConfigRef.Outcome out = ref.reload();
+
+        assertTrue(out.applied());
+        assertTrue(out.deferred().isEmpty());
+        assertEquals("config reloaded", out.summary());
+        assertEquals("[{profile}] {role}", ref.get().fleet().tabLabel());
+    }
+
+    /**
+     * The point of the whole class: a consumer holding the ref sees the new value without being
+     * rebuilt. A component that captured {@code get()} into a field would still show the old one.
+     */
+    @Test
+    void aConsumerHoldingTheRefSeesTheNewValue(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml("placement: weighted\n"));
+        ConfigRef ref = refFor(f);
+        java.util.function.Supplier<String> reader = () -> ref.get().placement();
+        assertEquals("weighted", reader.get());
+
+        Files.writeString(f, yaml("placement: fixed\n"));
+        assertTrue(ref.reload().applied());
+
+        assertEquals("fixed", reader.get());
+    }
+
+    @Test
+    void aChangedColdKeyRefusesTheWholeReload(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml("placement: weighted\n"));
+        ConfigRef ref = refFor(f);
+
+        // Two changes in one file: a cold one (the port) and a hot one (placement).
+        Files.writeString(f, yaml("placement: fixed\n").replace("port: 8765", "port: 9999"));
+        ConfigRef.Outcome out = ref.reload();
+
+        assertFalse(out.applied());
+        assertEquals(java.util.List.of("bind"), out.coldKeys());
+        assertTrue(out.summary().contains("Restart bridged"), out.summary());
+        // The hot half must NOT have leaked in. A half-applied reload leaves the daemon matching no
+        // file on disk, which is worse for an operator than no reload at all.
+        assertEquals("weighted", ref.get().placement());
+        assertEquals(8765, ref.get().bind().port());
+    }
+
+    @Test
+    void aFileThatNoLongerParsesKeepsTheRunningConfig(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml("placement: weighted\n"));
+        ConfigRef ref = refFor(f);
+        BridgedConfig before = ref.get();
+
+        Files.writeString(f, "profiles:\n  sonnet:\n   baseUrl: \"unclosed\n");
+        ConfigRef.Outcome out = ref.reload();
+
+        assertFalse(out.applied());
+        assertNotNull(out.error());
+        assertTrue(out.summary().startsWith("config reload refused"), out.summary());
+        assertSame(before, ref.get());
+    }
+
+    /** A file that would have refused to boot must not be able to slip in through a reload. */
+    @Test
+    void aFileThatFailsAValidatorKeepsTheRunningConfig(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml("placement: weighted\n"));
+        ConfigRef ref = refFor(f);
+        BridgedConfig before = ref.get();
+
+        // A member slot naming a profile that does not exist — validateMembers refuses this at
+        // startup, so it must refuse it here too.
+        Files.writeString(f, yaml("""
+                fleet:
+                  developers:
+                    a:
+                      profile: no-such-profile
+                """));
+        ConfigRef.Outcome out = ref.reload();
+
+        assertFalse(out.applied());
+        assertNotNull(out.error());
+        assertSame(before, ref.get());
+    }
+
+    @Test
+    void aDeletedFileIsRefusedRatherThanCrashing(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml(""));
+        ConfigRef ref = refFor(f);
+        BridgedConfig before = ref.get();
+
+        Files.delete(f);
+        ConfigRef.Outcome out = ref.reload();
+
+        assertFalse(out.applied());
+        assertNotNull(out.error());
+        assertSame(before, ref.get());
+    }
+
+    /** A deferred change applies to the snapshot but the operator is told it needs a restart. */
+    @Test
+    void aDeferredChangeIsAppliedAndReported(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml("""
+                lifecycle:
+                  drainTimeoutSeconds: 30
+                """));
+        ConfigRef ref = refFor(f);
+
+        Files.writeString(f, yaml("""
+                lifecycle:
+                  drainTimeoutSeconds: 60
+                """));
+        ConfigRef.Outcome out = ref.reload();
+
+        assertTrue(out.applied());
+        assertEquals(java.util.List.of("lifecycle"), out.deferred());
+        assertTrue(out.summary().contains("needs a restart") || out.summary().contains("need a restart"),
+                out.summary());
+        assertEquals(60, ref.get().lifecycle().drainTimeoutSeconds());
+    }
+
+    /**
+     * Adding a profile is deferred, not hot: a new backend needs its own launcher, and launchers are
+     * built once at startup. The snapshot carries it so a restart picks it up.
+     */
+    @Test
+    void addingAProfileIsReportedAsDeferred(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml(""));
+        ConfigRef ref = refFor(f);
+
+        Files.writeString(f, """
+                bind:
+                  host: 127.0.0.1
+                  port: 8765
+                herdrSocket: ~/.config/herdr/herdr.sock
+                profiles:
+                  sonnet:
+                    baseUrl: http://gx00.gw:8000
+                    model: sonnet
+                  haiku:
+                    baseUrl: http://gx00.gw:8000
+                    model: haiku
+                guard:
+                  offSubscriptionHosts:
+                    - gx00.gw
+                """);
+        ConfigRef.Outcome out = ref.reload();
+
+        assertTrue(out.applied());
+        assertEquals(1, out.deferred().size());
+        assertTrue(out.deferred().getFirst().contains("haiku"), out.deferred().toString());
+    }
+
+    /**
+     * Changing an existing profile's weight or maxLoad IS hot: placement reads those live through
+     * the supplier on the composite, so the next spawn already sees them.
+     */
+    @Test
+    void changingAProfilesWeightOrMaxLoadIsHot(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml(""));
+        ConfigRef ref = refFor(f);
+
+        Files.writeString(f, """
+                bind:
+                  host: 127.0.0.1
+                  port: 8765
+                herdrSocket: ~/.config/herdr/herdr.sock
+                profiles:
+                  sonnet:
+                    baseUrl: http://gx00.gw:8000
+                    model: sonnet
+                    maxLoad: 7
+                    weight: 3.0
+                guard:
+                  offSubscriptionHosts:
+                    - gx00.gw
+                """);
+        ConfigRef.Outcome out = ref.reload();
+
+        assertTrue(out.applied());
+        assertTrue(out.deferred().isEmpty(), out.deferred().toString());
+        assertEquals(7, ref.get().profiles().get("sonnet").maxLoad());
+    }
+
+    /**
+     * Changing an existing profile's MODEL is deferred, not hot — and saying so is the whole point.
+     * HerdrPeerLauncher takes Map.copyOf(profiles) at construction and resolves every spawn out of
+     * that copy, so a reloaded model never reaches a launch. Reporting it as applied would be the
+     * worst outcome a reload can produce: the operator has no reason to doubt a clean "reloaded".
+     */
+    @Test
+    void changingAProfilesLaunchSettingsIsReportedAsDeferred(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml(""));
+        ConfigRef ref = refFor(f);
+
+        Files.writeString(f, """
+                bind:
+                  host: 127.0.0.1
+                  port: 8765
+                herdrSocket: ~/.config/herdr/herdr.sock
+                profiles:
+                  sonnet:
+                    baseUrl: http://gx00.gw:8000
+                    model: deepseek-v4-flash
+                guard:
+                  offSubscriptionHosts:
+                    - gx00.gw
+                """);
+        ConfigRef.Outcome out = ref.reload();
+
+        assertTrue(out.applied());
+        assertEquals(1, out.deferred().size(), out.deferred().toString());
+        assertTrue(out.deferred().getFirst().contains("sonnet"), out.deferred().toString());
+        assertTrue(out.deferred().getFirst().contains("launch settings"), out.deferred().toString());
+        // The snapshot still carries the new value — a restart is what makes it take effect.
+        assertEquals("deepseek-v4-flash", ref.get().profiles().get("sonnet").model());
+    }
+
+    @Test
+    void aFixedRefHasNoFileAndRefusesToReload() {
+        BridgedConfig cfg = new BridgedConfig(null, null, null, null, null, null,
+                null, null, null, null, null, null, null, null, null).withDefaults();
+        ConfigRef ref = ConfigRef.fixed(cfg);
+
+        assertNull(ref.path());
+        assertSame(cfg, ref.get());
+        ConfigRef.Outcome out = ref.reload();
+        assertFalse(out.applied());
+        assertNotNull(out.error());
+    }
+}

bridged/src/test/java/dev/ltms/bridged/config/ConfigWatcherTest.java

@@ -0,0 +1,162 @@
+package dev.ltms.bridged.config;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.FileTime;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * CB-559: the mtime poller behind {@code configReload:}. The tests drive {@link
+ * ConfigWatcher#tick()} directly rather than the scheduler, so nothing here sleeps.
+ */
+class ConfigWatcherTest {
+
+    private static String yaml(String placement) {
+        return """
+                bind:
+                  host: 127.0.0.1
+                  port: 8765
+                herdrSocket: ~/.config/herdr/herdr.sock
+                profiles:
+                  sonnet:
+                    baseUrl: http://gx00.gw:8000
+                    model: sonnet
+                guard:
+                  offSubscriptionHosts:
+                    - gx00.gw
+                """ + "placement: " + placement + "\n";
+    }
+
+    /** Write and stamp an mtime, so a test never depends on the filesystem's clock resolution. */
+    private static void write(Path f, String content, long millis) throws Exception {
+        Files.writeString(f, content);
+        Files.setLastModifiedTime(f, FileTime.fromMillis(millis));
+    }
+
+    @Test
+    void aChangedMtimeTriggersAReload(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        write(f, yaml("weighted"), 1_000L);
+        ConfigRef ref = new ConfigRef(f, BridgedConfig.load(f));
+
+        ConfigWatcher watcher = new ConfigWatcher(ref, 10);
+        try {
+            write(f, yaml("fixed"), 2_000L);
+            watcher.tick();
+
+            assertEquals("fixed", ref.get().placement());
+        } finally {
+            watcher.stop();
+        }
+    }
+
+    @Test
+    void anUnchangedFileIsNotReloaded(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        write(f, yaml("weighted"), 1_000L);
+        ConfigRef ref = new ConfigRef(f, BridgedConfig.load(f));
+        BridgedConfig before = ref.get();
+
+        ConfigWatcher watcher = new ConfigWatcher(ref, 10);
+        try {
+            watcher.tick();
+            watcher.tick();
+
+            // Same instance, so no reload happened — a reload always swaps in a fresh object.
+            assertSame(before, ref.get());
+        } finally {
+            watcher.stop();
+        }
+    }
+
+    /**
+     * A refused reload must not be retried every tick. Without the stamp-before-reload order the
+     * same refusal would be logged forever, which buries the log an operator needs.
+     */
+    @Test
+    void aRefusedReloadIsNotRetriedUntilTheFileChangesAgain(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        write(f, yaml("weighted"), 1_000L);
+        ConfigRef ref = new ConfigRef(f, BridgedConfig.load(f));
+        BridgedConfig before = ref.get();
+
+        ConfigWatcher watcher = new ConfigWatcher(ref, 10);
+        try {
+            // A cold change: refused, and the running config stays.
+            write(f, yaml("fixed").replace("port: 8765", "port: 9999"), 2_000L);
+            watcher.tick();
+            assertSame(before, ref.get());
+
+            // The next tick sees the same mtime, so it does nothing at all.
+            watcher.tick();
+            assertSame(before, ref.get());
+
+            // A fresh save earns a fresh attempt — and this one is hot, so it applies.
+            write(f, yaml("fixed"), 3_000L);
+            watcher.tick();
+            assertEquals("fixed", ref.get().placement());
+        } finally {
+            watcher.stop();
+        }
+    }
+
+    /**
+     * Editors briefly unlink the file mid-save. A missing file is skipped, not an error and not a
+     * reload — the running config stays live, which is right either way.
+     */
+    @Test
+    void aMissingFileIsSkippedAndTheNextTickTriesAgain(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        write(f, yaml("weighted"), 1_000L);
+        ConfigRef ref = new ConfigRef(f, BridgedConfig.load(f));
+        BridgedConfig before = ref.get();
+
+        ConfigWatcher watcher = new ConfigWatcher(ref, 10);
+        try {
+            Files.delete(f);
+            assertDoesNotThrow(watcher::tick);
+            assertSame(before, ref.get());
+
+            write(f, yaml("fixed"), 2_000L);
+            watcher.tick();
+            assertEquals("fixed", ref.get().placement());
+        } finally {
+            watcher.stop();
+        }
+    }
+
+    /** A ref with no file behind it must not start a scheduler that could never do anything. */
+    @Test
+    void aFixedRefStartsNoWatch() {
+        BridgedConfig cfg = new BridgedConfig(null, null, null, null, null, null,
+                null, null, null, null, null, null, null, null, null).withDefaults();
+        ConfigWatcher watcher = new ConfigWatcher(ConfigRef.fixed(cfg), 10);
+        try {
+            assertDoesNotThrow(watcher::start);
+            assertDoesNotThrow(watcher::tick);
+        } finally {
+            watcher.stop();
+        }
+    }
+
+    @Test
+    void configReloadIsOffUnlessTheBlockSaysOtherwise(@TempDir Path dir) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        write(f, yaml("weighted"), 1_000L);
+        assertNull(BridgedConfig.load(f).configReload());
+
+        write(f, yaml("weighted") + "configReload:\n  enabled: true\n", 2_000L);
+        BridgedConfig.ConfigReload on = BridgedConfig.load(f).configReload();
+        assertTrue(on.isEnabled());
+        assertEquals(10, on.intervalSeconds(), "an absent interval defaults to 10s");
+
+        write(f, yaml("weighted") + "configReload:\n  intervalSeconds: 30\n", 3_000L);
+        BridgedConfig.ConfigReload off = BridgedConfig.load(f).configReload();
+        assertFalse(off.isEnabled(), "a block that only sets the interval does not enable the watch");
+        assertEquals(30, off.intervalSeconds());
+    }
+}

bridged/src/test/java/dev/ltms/bridged/herdr/AgentControlContractTest.java

@@ -11,10 +11,11 @@ import static org.junit.jupiter.api.Assertions.*;
 import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
 /**
- * Contract test for the {@code agent.*} south side against a REAL herdr, locking in
- * the CB-102 spike findings. It spawns a HARMLESS probe command (never {@code claude},
- * so no subscription/token involvement), proves the {@code env} map reaches the process
- * environment, exercises status/read, and always tears the pane down.
+ * Contract test for the worker env seam against a REAL herdr. Under protocol 19 (CB-521) the
+ * env map is injected at PANE CREATION ({@code tab.create}), not {@code agent.start} — and
+ * {@code agent.start} now only launches supported agent kinds, so this probes the seed pane's
+ * SHELL directly (never {@code claude}, so no subscription/token involvement) and always tears
+ * the throwaway space down.
  *
  * <p>Tagged {@code contract}; run with {@code mvn test -Pcontract}.
  */
@@ -26,38 +27,30 @@ class AgentControlContractTest {
     }
 
     @Test
-    void startInjectsEnvThenReadAndClose() throws Exception {
+    void tabCreateInjectsEnvIntoTheSeedShell() throws Exception {
         assumeTrue(!noSocket(), "no herdr socket — skipping");
         try (UnixSocketHerdrClient herdr = UnixSocketHerdrClient.connect()) {
-            AgentControl agents = new AgentControl(herdr);
-
-            Agent probe = agents.start(
-                    "__contract__",
-                    List.of("bash", "-c", "printf 'PROBE_BASE=[%s]\\n' \"$ANTHROPIC_BASE_URL\"; sleep 20"),
+            WorkspaceControl spaces = new WorkspaceControl(herdr);
+            Workspace space = spaces.ensureWorkspace("__bridged_env_contract__");
+            Tab.Created tab = spaces.createTab(space.workspaceId(), null,
                     Map.of("ANTHROPIC_BASE_URL", "http://gx00.gw:8000"));
-
-            assertNotNull(probe.terminalId());
-            assertNotNull(probe.paneId());
             try {
-                // Give the shell a moment to print, then confirm env reached the process.
+                assertNotNull(tab.rootPaneId(), "tab.create must return the seed pane");
+                Thread.sleep(1000); // let the seed shell reach its prompt
+                herdr.call("pane.send_input", Map.of(
+                        "pane_id", tab.rootPaneId(),
+                        "text", "printf 'PROBE_BASE=[%s]\\n' \"$ANTHROPIC_BASE_URL\"",
+                        "keys", List.of("enter")));
                 Thread.sleep(800);
-                String visible = agents.read(probe.terminalId(), "visible");
+                String visible = herdr.call("pane.read",
+                                Map.of("pane_id", tab.rootPaneId(), "source", "visible"))
+                        .path("read").path("text").asText("");
                 assertTrue(visible.contains("PROBE_BASE=[http://gx00.gw:8000]"),
-                        "env map must reach the process; saw: " + visible);
-
-                // Status is queryable; the probe appears in the agent list.
-                assertNotNull(agents.status(probe.terminalId()));
-                assertTrue(agents.list().stream()
-                                .anyMatch(a -> probe.terminalId().equals(a.terminalId())),
-                        "spawned probe should appear in agent.list");
+                        "env map must reach the seed shell; saw: " + visible);
             } finally {
-                agents.close(probe.paneId());
+                spaces.closeTab(tab.tab().tabId());
+                herdr.call("workspace.close", Map.of("workspace_id", space.workspaceId()));
             }
-
-            // After close the pane is gone.
-            assertFalse(agents.list().stream()
-                            .anyMatch(a -> probe.terminalId().equals(a.terminalId())),
-                    "closed probe should no longer be listed");
         }
     }
 }

bridged/src/test/java/dev/ltms/bridged/herdr/AgentControlTest.java

@@ -0,0 +1,74 @@
+package dev.ltms.bridged.herdr;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/** Unit-level behaviour of {@link AgentControl} over a fake herdr (protocol 19). */
+class AgentControlTest {
+
+    /** The {@code text} of every agent.prompt, in call order. */
+    @SuppressWarnings("unchecked")
+    private static List<String> promptTexts(FakeHerdr herdr) {
+        return herdr.calls.stream()
+                .filter(c -> c.method().equals("agent.prompt"))
+                .map(c -> ((Map<String, Object>) c.params()).get("text").toString())
+                .toList();
+    }
+
+    @Test
+    void sendDeliversThePayloadAsOnePromptThatSubmitsItself() {
+        FakeHerdr herdr = new FakeHerdr();
+        new AgentControl(herdr).send("term_x", "do the thing");
+
+        // agent.prompt pastes AND submits in one call — no separate Enter event to assert.
+        assertEquals(List.of("do the thing"), promptTexts(herdr),
+                "exactly one agent.prompt carrying the payload");
+    }
+
+    @Test
+    void sendPreservesEmbeddedNewlinesVerbatim() {
+        FakeHerdr herdr = new FakeHerdr();
+        new AgentControl(herdr).send("term_x", "line1\nline2");
+
+        assertEquals(List.of("line1\nline2"), promptTexts(herdr),
+                "multiline content is delivered verbatim in the single prompt");
+    }
+
+    @Test
+    void submitNudgesWithAStandaloneEnterKeystroke() {
+        FakeHerdr herdr = new FakeHerdr();
+        new AgentControl(herdr).submit("term_x");
+
+        FakeHerdr.Call keys = herdr.lastCall("agent.send_keys");
+        assertEquals(Map.of("target", "term_x", "keys", List.of("enter")), keys.params(),
+                "the raced-Enter nudge is a raw send_keys, not a second prompt");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void aTerminalIdTargetIsTranslatedToItsPaneId() {
+        // Protocol 19 rejects terminal_id as an agent.* target; the fake's agent.list maps
+        // term_a to pane w2:p7, and the control layer must address herdr by that pane.
+        FakeHerdr herdr = new FakeHerdr();
+        new AgentControl(herdr).send("term_a", "hello");
+
+        Map<String, Object> prompt = (Map<String, Object>) herdr.lastCall("agent.prompt").params();
+        assertEquals("w2:p7", prompt.get("target"), "terminal target resolved to the agent's pane id");
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void theTerminalToPaneMappingIsCachedAcrossCalls() {
+        FakeHerdr herdr = new FakeHerdr();
+        AgentControl agents = new AgentControl(herdr);
+        agents.send("term_a", "one");
+        agents.send("term_a", "two");
+
+        long lists = herdr.calls.stream().filter(c -> c.method().equals("agent.list")).count();
+        assertEquals(1, lists, "one agent.list resolution serves every later call to the same terminal");
+    }
+}

bridged/src/test/java/dev/ltms/bridged/herdr/AgentStatusTest.java

@@ -0,0 +1,43 @@
+package dev.ltms.bridged.herdr;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/** Wire mapping and injectability of {@link AgentStatus}, including the CB-115 {@code done} state. */
+class AgentStatusTest {
+
+    @Test
+    void mapsTheKnownWireStrings() {
+        assertEquals(AgentStatus.IDLE, AgentStatus.fromWire("idle"));
+        assertEquals(AgentStatus.WORKING, AgentStatus.fromWire("working"));
+        assertEquals(AgentStatus.BLOCKED, AgentStatus.fromWire("blocked"));
+        assertEquals(AgentStatus.DONE, AgentStatus.fromWire("done"));
+    }
+
+    @Test
+    void mapsDoneCaseInsensitively() {
+        assertEquals(AgentStatus.DONE, AgentStatus.fromWire("DONE"));
+        assertEquals(AgentStatus.DONE, AgentStatus.fromWire("Done"));
+    }
+
+    @Test
+    void unknownAndNullFallToUnknown() {
+        assertEquals(AgentStatus.UNKNOWN, AgentStatus.fromWire("unknown"));
+        assertEquals(AgentStatus.UNKNOWN, AgentStatus.fromWire("something-else"));
+        assertEquals(AgentStatus.UNKNOWN, AgentStatus.fromWire(null));
+    }
+
+    @Test
+    void doneIsInjectableLikeIdle() {
+        // The whole point of CB-115: a finished worker herdr reports as `done` must be deliverable,
+        // not treated as UNKNOWN (which wedged delivery and mis-fired the stall failure).
+        assertTrue(AgentStatus.DONE.injectable());
+        assertTrue(AgentStatus.IDLE.injectable());
+        assertTrue(AgentStatus.BLOCKED.injectable());
+        assertFalse(AgentStatus.WORKING.injectable());
+        assertFalse(AgentStatus.UNKNOWN.injectable());
+    }
+}

bridged/src/test/java/dev/ltms/bridged/herdr/FakeHerdr.java

@@ -4,27 +4,40 @@ import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 
 import java.util.ArrayList;
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Recording fake {@link HerdrClient} for unit/acceptance tests. Returns canned frames
- * captured from the real herdr 0.7.0 daemon and records every call so tests can assert
- * both behaviour and that guard-blocked paths never reached herdr.
+ * matching the real herdr 0.8.0 daemon (protocol 19) and records every call so tests can
+ * assert both behaviour and that guard-blocked paths never reached herdr.
  */
 public final class FakeHerdr implements HerdrClient {
 
     public record Call(String method, Object params) {
     }
 
+    /** The foreground PID of the one agent pane (term_a) in the canned {@code pane.process_info}. */
+    public static final long WORKER_PID = 4242;
+
     private final ObjectMapper mapper = new ObjectMapper();
     public final List<Call> calls = new ArrayList<>();
     private boolean healthy = true;
     private final List<String> extraWorkspaces = new ArrayList<>();
+    private final List<String> extraAgents = new ArrayList<>();
+    /** workspaceId → extra tabs that {@code tab.list} reports for it (CB-558 lead scans). */
+    private final Map<String, List<String>> extraTabs = new LinkedHashMap<>();
     private int agentNameTakenFor = 0;
+    private int agentPaneBusyFor = 0;
     private int workerTabPaneCount = 1;
     private String paneCloseErrorCode = null;
     private String agentSendErrorCode = null;
-    private volatile String agentStatus = "idle"; // what agent.get reports
+    private volatile String agentStatus = "idle"; // steady-state agent.get status
+    private volatile String readText = "worker transcript tail"; // canned agent.read output
+    private int pinnedStarts = 0;   // how many upcoming agent.start calls report a fixed pane
+    private String pinnedStartTerminal;
+    private String pinnedStartPane;
 
     public FakeHerdr healthy(boolean h) {
         this.healthy = h;
@@ -37,6 +50,12 @@ public final class FakeHerdr implements HerdrClient {
         return this;
     }
 
+    /** Reject the first {@code n} {@code agent.start} calls with {@code agent_pane_busy}. */
+    public FakeHerdr agentPaneBusyTimes(int n) {
+        this.agentPaneBusyFor = n;
+        return this;
+    }
+
     /** Make the worker tab (w9:t2) report this many panes in {@code tab.list} (default 1). */
     public FakeHerdr withWorkerTabPaneCount(int n) {
         this.workerTabPaneCount = n;
@@ -55,12 +74,57 @@ public final class FakeHerdr implements HerdrClient {
         return this;
     }
 
-    /** Make {@code agent.send} fail with this herdr error code. */
+    /** The text {@code agent.read} returns (the CB-106 completion scrape). */
+    public FakeHerdr readText(String text) {
+        this.readText = text;
+        return this;
+    }
+
+    /** Make delivery ({@code agent.prompt} / {@code agent.send_keys}) fail with this error code. */
     public FakeHerdr agentSendFailsWith(String code) {
         this.agentSendErrorCode = code;
         return this;
     }
 
+    /**
+     * Force the next {@code n} {@code agent.start} calls to report this terminal/pane coordinate,
+     * instead of the fake's usual incrementing {@code term_new_n}/{@code w9:pRoot_n}. Lets a test make
+     * two spawns report the <em>same</em> herdr pane, to prove the host-unique id (CB-519) never
+     * collides on that coordinate.
+     */
+    public FakeHerdr pinNextStarts(int n, String terminalId, String paneId) {
+        this.pinnedStarts = n;
+        this.pinnedStartTerminal = terminalId;
+        this.pinnedStartPane = paneId;
+        return this;
+    }
+
+
+    /**
+     * Seed a named agent into {@code agent.list} (e.g. an orphaned worker for CB-117 reaper tests).
+     * The {@code name} carries the worker label the reaper keys on; {@code paneId}/{@code tabId}
+     * locate its pane for teardown.
+     */
+    public FakeHerdr withAgent(String name, String terminalId, String paneId, String tabId) {
+        extraAgents.add(("{\"terminal_id\":\"%s\",\"agent\":\"claude\",\"agent_status\":\"idle\","
+                + "\"name\":\"%s\",\"agent_session\":{\"kind\":\"id\",\"value\":\"sess-%s\"},"
+                + "\"workspace_id\":\"wQ\",\"tab_id\":\"%s\",\"pane_id\":\"%s\"}")
+                .formatted(terminalId, name, terminalId, tabId, paneId));
+        return this;
+    }
+
+    /**
+     * Seed a labelled tab into {@code tab.list} for one workspace (e.g. an existing {@code lead: x}
+     * tab). Pair it with {@link #withAgent} on the same {@code tabId} to make the lead <em>live</em>;
+     * seeding the tab alone models the stale-label case.
+     */
+    public FakeHerdr withTab(String workspaceId, String tabId, String label) {
+        extraTabs.computeIfAbsent(workspaceId, _ -> new ArrayList<>())
+                .add(("{\"tab_id\":\"%s\",\"workspace_id\":\"%s\",\"label\":\"%s\",\"pane_count\":1}")
+                        .formatted(tabId, workspaceId, label));
+        return this;
+    }
+
     /** Seed an additional workspace into {@code workspace.list} (e.g. a pre-existing worker space). */
     public FakeHerdr withWorkspace(String id, String label) {
         extraWorkspaces.add(("{\"workspace_id\":\"%s\",\"label\":\"%s\",\"focused\":false,"
@@ -85,20 +149,31 @@ public final class FakeHerdr implements HerdrClient {
         try {
             return switch (method) {
                 case "ping" -> mapper.readTree(
-                        "{\"type\":\"pong\",\"version\":\"0.7.0\",\"protocol\":14}");
+                        "{\"type\":\"pong\",\"version\":\"0.8.0\",\"protocol\":19}");
                 case "workspace.list" -> mapper.readTree(("""
                         {"type":"workspace_list","workspaces":[
                           {"workspace_id":"w1","label":"dev-mgnl","focused":true,"pane_count":7,"agent_status":"unknown"},
                           {"workspace_id":"w2","label":"ltms","focused":false,"pane_count":5,"agent_status":"done"}%s]}""")
                         .formatted(extraWorkspaces.isEmpty() ? "" : "," + String.join(",", extraWorkspaces)));
-                case "agent.list" -> mapper.readTree("""
+                case "agent.list" -> mapper.readTree(("""
                         {"type":"agent_list","agents":[
                           {"terminal_id":"term_a","agent":"claude","agent_status":"idle",
                            "agent_session":{"kind":"id","value":"sess-1111"},
-                           "workspace_id":"w2","tab_id":"w2:t7","pane_id":"w2:p7"}]}""");
-                case "agent.send" -> {
+                           "workspace_id":"w2","tab_id":"w2:t7","pane_id":"w2:p7"}%s]}""")
+                        .formatted(extraAgents.isEmpty() ? "" : "," + String.join(",", extraAgents)));
+                case "agent.prompt" -> {
                     if (agentSendErrorCode != null) {
-                        throw new HerdrException("herdr error [" + agentSendErrorCode + "]: agent.send failed",
+                        throw new HerdrException("herdr error [" + agentSendErrorCode + "]: agent.prompt failed",
+                                agentSendErrorCode, null);
+                    }
+                    yield mapper.readTree(("""
+                        {"type":"agent_prompted","agent":{"terminal_id":"term_a","agent":"claude",
+                          "agent_status":"%s","workspace_id":"w2","tab_id":"w2:t7","pane_id":"w2:p7"}}""")
+                            .formatted(agentStatus));
+                }
+                case "agent.send_keys" -> {
+                    if (agentSendErrorCode != null) {
+                        throw new HerdrException("herdr error [" + agentSendErrorCode + "]: agent.send_keys failed",
                                 agentSendErrorCode, null);
                     }
                     yield mapper.readTree("{\"type\":\"ok\"}");
@@ -107,40 +182,100 @@ public final class FakeHerdr implements HerdrClient {
                         {"type":"agent_info","agent":{"terminal_id":"term_a","agent":"claude",
                           "agent_status":"%s","workspace_id":"w2","tab_id":"w2:t7","pane_id":"w2:p7"}}""")
                         .formatted(agentStatus));
+                case "agent.read" -> mapper.readTree(mapper.writeValueAsString(
+                        java.util.Map.of("type", "agent_read", "read", java.util.Map.of("text", readText))));
                 case "agent.start" -> {
+                    // Protocol 19: kind and pane_id are required — reject like the real daemon.
+                    java.util.Map<?, ?> p = params instanceof java.util.Map<?, ?> m ? m : java.util.Map.of();
+                    for (String required : new String[]{"kind", "pane_id"}) {
+                        if (p.get(required) == null) {
+                            throw new HerdrException(
+                                    "herdr error [invalid_request]: invalid request: missing field `"
+                                            + required + "`", "invalid_request", null);
+                        }
+                    }
                     long starts = calls.stream().filter(c -> c.method().equals("agent.start")).count();
-                    if (starts <= agentNameTakenFor) {
+                    if (starts <= agentPaneBusyFor) {
+                        throw new HerdrException(
+                                "herdr error [agent_pane_busy]: agent target pane is not an available shell",
+                                "agent_pane_busy", null);
+                    }
+                    long busyAdjusted = starts - agentPaneBusyFor;
+                    if (busyAdjusted <= agentNameTakenFor) {
                         throw new HerdrException(
                                 "herdr error [agent_name_taken]: agent name already used",
                                 "agent_name_taken", null);
                     }
-                    yield mapper.readTree("""
+                    long n = busyAdjusted - agentNameTakenFor;
+                    boolean pinned = pinnedStarts > 0;
+                    if (pinned) {
+                        pinnedStarts--;
+                    }
+                    // Protocol 19: the agent starts INTO the requested pane, so its pane_id normally
+                    // echoes the param. A pin overrides both coordinates, which is the only way to
+                    // make two spawns report one pane — what CB-519's collision test needs.
+                    String terminal = pinned ? pinnedStartTerminal : ("term_new_" + n);
+                    Object pane = pinned ? pinnedStartPane : p.get("pane_id");
+                    yield mapper.readTree(("""
                         {"type":"agent_started","agent":{
-                          "terminal_id":"term_new","name":"claude","agent_status":"unknown",
-                          "workspace_id":"w9","tab_id":"w9:t2","pane_id":"w9:pW"}}""");
+                          "terminal_id":"%s","name":"claude","agent_status":"unknown",
+                          "workspace_id":"w9","tab_id":"w9:t2","pane_id":"%s"}}""")
+                            .formatted(terminal, pane));
                 }
+                case "pane.split" -> mapper.readTree("""
+                        {"type":"pane_info","pane":{"pane_id":"w1:pSplit","workspace_id":"w1",
+                          "tab_id":"w1:t1"}}""");
                 case "workspace.create" -> mapper.readTree("""
                         {"type":"workspace_created",
                          "workspace":{"workspace_id":"w9","label":"bridged-workers","focused":false,
                            "pane_count":1,"tab_count":1,"active_tab_id":"w9:t1","agent_status":"unknown"},
                          "tab":{"tab_id":"w9:t1","workspace_id":"w9","label":"1","pane_count":1},
                          "root_pane":{"pane_id":"w9:p1","workspace_id":"w9","tab_id":"w9:t1"}}""");
-                case "tab.create" -> mapper.readTree("""
+                case "tab.create" -> {
+                    // Each tab gets its own seed pane — under protocol 19 that pane becomes the
+                    // worker pane, so distinct spawns must yield distinct pane ids.
+                    long tabs = calls.stream().filter(c -> c.method().equals("tab.create")).count();
+                    yield mapper.readTree(("""
                         {"type":"tab_created",
                          "tab":{"tab_id":"w9:t2","workspace_id":"w9","label":"2","pane_count":1},
-                         "root_pane":{"pane_id":"w9:pRoot","workspace_id":"w9","tab_id":"w9:t2"}}""");
+                         "root_pane":{"pane_id":"w9:pRoot_%d","workspace_id":"w9","tab_id":"w9:t2"}}""")
+                            .formatted(tabs));
+                }
                 case "tab.rename" -> mapper.readTree("""
                         {"type":"tab_info","tab":{"tab_id":"w9:t2","workspace_id":"w9",
                           "label":"worker: ltms-local","pane_count":1}}""");
-                case "tab.list" -> mapper.readTree(("""
+                case "tab.list" -> {
+                    // The base pair is returned for every workspace, exactly as before. Seeded tabs
+                    // are appended only for the workspace they were registered against, so a test
+                    // that seeds none sees the historical response byte for byte.
+                    Object wsId = params instanceof java.util.Map<?, ?> m ? m.get("workspace_id") : null;
+                    List<String> seeded = extraTabs.getOrDefault(String.valueOf(wsId), List.of());
+                    yield mapper.readTree(("""
                         {"type":"tab_list","tabs":[
                           {"tab_id":"w9:t1","workspace_id":"w9","label":"1","pane_count":1},
-                          {"tab_id":"w9:t2","workspace_id":"w9","label":"worker: ltms-local","pane_count":%d}]}""")
-                        .formatted(workerTabPaneCount));
+                          {"tab_id":"w9:t2","workspace_id":"w9","label":"worker: ltms-local","pane_count":%d}%s]}""")
+                            .formatted(workerTabPaneCount,
+                                    seeded.isEmpty() ? "" : "," + String.join(",", seeded)));
+                }
                 case "tab.close" -> mapper.readTree("{\"type\":\"ok\"}");
                 case "pane.get" -> mapper.readTree("""
                         {"type":"pane_info","pane":{"pane_id":"w9:pW","workspace_id":"w9",
                           "tab_id":"w9:t2","agent_status":"idle"}}""");
+                case "pane.list" -> mapper.readTree("""
+                        {"type":"pane_list","panes":[
+                          {"pane_id":"w2:p7","terminal_id":"term_a","workspace_id":"w2","tab_id":"w2:t7","agent":"claude"},
+                          {"pane_id":"w2:p9","terminal_id":"term_shell","workspace_id":"w2","tab_id":"w2:t8"}]}""");
+                case "pane.process_info" -> {
+                    Object paneId = params instanceof java.util.Map<?, ?> m ? m.get("pane_id") : null;
+                    yield "w2:p7".equals(paneId)
+                            ? mapper.readTree(("""
+                                {"type":"pane_process_info","process_info":{"pane_id":"w2:p7","shell_pid":%d,
+                                  "foreground_processes":[{"pid":%d,"name":"node","argv0":"claude"}]}}""")
+                                    .formatted(WORKER_PID, WORKER_PID))
+                            : mapper.readTree("""
+                                {"type":"pane_process_info","process_info":{"pane_id":"w2:p9","shell_pid":9001,
+                                  "foreground_processes":[]}}""");
+                }
                 case "pane.close" -> {
                     if (paneCloseErrorCode != null) {
                         throw new HerdrException("herdr error [" + paneCloseErrorCode + "]: pane.close failed",

bridged/src/test/java/dev/ltms/bridged/herdr/LeadTabScannerTest.java

@@ -0,0 +1,262 @@
+package dev.ltms.bridged.herdr;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * CB-531. A lead is never spawned, so the daemon has to <em>find</em> it: these assert that an
+ * operator-labelled tab is what makes a pane a lead, and — just as importantly — what does not.
+ */
+class LeadTabScannerTest {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final long TTL = TimeUnit.SECONDS.toNanos(10);
+
+    /**
+     * A herdr whose workspace/tab/pane topology is declared per test. Counts calls so the caching
+     * contract can be asserted, and can be made to fail on demand.
+     */
+    private static final class TopologyHerdr implements HerdrClient {
+        /** workspace_id → label. */
+        final Map<String, String> workspaces = new LinkedHashMap<>();
+        /** tab_id → [workspace_id, label]. */
+        final Map<String, String[]> tabs = new LinkedHashMap<>();
+        /** pane_id → [tab_id, terminal_id]. */
+        final Map<String, String[]> panes = new LinkedHashMap<>();
+        int calls;
+        boolean failing;
+
+        TopologyHerdr workspace(String id, String label) {
+            workspaces.put(id, label);
+            return this;
+        }
+
+        TopologyHerdr tab(String tabId, String workspaceId, String label) {
+            tabs.put(tabId, new String[]{workspaceId, label});
+            return this;
+        }
+
+        TopologyHerdr pane(String paneId, String tabId, String terminalId) {
+            panes.put(paneId, new String[]{tabId, terminalId});
+            return this;
+        }
+
+        @Override
+        public JsonNode call(String method, Object params) {
+            calls++;
+            if (failing) {
+                throw new HerdrException("socket closed");
+            }
+            List<String> items = new ArrayList<>();
+            switch (method) {
+                case "workspace.list" -> {
+                    workspaces.forEach((id, label) -> items.add(
+                            "{\"workspace_id\":\"%s\",\"label\":\"%s\"}".formatted(id, label)));
+                    return read("{\"workspaces\":[%s]}".formatted(String.join(",", items)));
+                }
+                case "tab.list" -> {
+                    String ws = String.valueOf(((Map<?, ?>) params).get("workspace_id"));
+                    tabs.forEach((id, t) -> {
+                        if (ws.equals(t[0])) {
+                            items.add(("{\"tab_id\":\"%s\",\"workspace_id\":\"%s\",\"label\":%s,"
+                                    + "\"pane_count\":1}").formatted(id, t[0],
+                                    t[1] == null ? "null" : "\"" + t[1] + "\""));
+                        }
+                    });
+                    return read("{\"tabs\":[%s]}".formatted(String.join(",", items)));
+                }
+                case "pane.list" -> {
+                    panes.forEach((id, p) -> items.add(
+                            "{\"pane_id\":\"%s\",\"tab_id\":\"%s\",\"terminal_id\":\"%s\"}"
+                                    .formatted(id, p[0], p[1])));
+                    return read("{\"panes\":[%s]}".formatted(String.join(",", items)));
+                }
+                default -> throw new AssertionError("unexpected herdr call: " + method);
+            }
+        }
+
+        private static JsonNode read(String json) {
+            try {
+                return MAPPER.readTree(json);
+            } catch (Exception e) {
+                throw new AssertionError(e);
+            }
+        }
+
+        @Override
+        public void close() {
+        }
+    }
+
+    /**
+     * The usual shape: one user space with lead tabs, one worker space bridged owns.
+     *
+     * <p>Not closed: {@code close()} is a no-op on this fake, and every test needs the handle after
+     * the scanner is built (to mutate the topology or read {@code calls}).
+     */
+    @SuppressWarnings("resource")
+    private TopologyHerdr twoLeads() {
+        return new TopologyHerdr()
+                .workspace("w1", "main")
+                .workspace("w9", "bridged-workers")
+                .tab("w1:t1", "w1", "lead: opus-5.0")
+                .tab("w1:t2", "w1", "lead: gpt-sol-5.6")
+                .tab("w1:t3", "w1", "notes")
+                .tab("w9:t1", "w9", "worker: gx10 #1")
+                .pane("w1:p1", "w1:t1", "term_opus")
+                .pane("w1:p2", "w1:t2", "term_gpt")
+                .pane("w1:p3", "w1:t3", "term_notes")
+                .pane("w9:p1", "w9:t1", "term_worker");
+    }
+
+    private LeadTabScanner scanner(TopologyHerdr herdr, Map<String, String> configured,
+                                   AtomicLong clock) {
+        return new LeadTabScanner(herdr, "lead:", Set.of("bridged-workers"), configured, TTL,
+                clock::get);
+    }
+
+    @Test
+    void everyLabelledTabBecomesALeadNamedByItsLabel() {
+        Map<String, String> leads = scanner(twoLeads(), Map.of(), new AtomicLong()).get();
+
+        assertEquals(Map.of("term_opus", "opus-5.0", "term_gpt", "gpt-sol-5.6"), leads,
+                "two leads discovered from labels alone — no terminal_id was ever configured");
+    }
+
+    @Test
+    void anUnlabelledTabContributesNothing() {
+        assertFalse(scanner(twoLeads(), Map.of(), new AtomicLong()).get().containsKey("term_notes"));
+    }
+
+    /**
+     * The guard that matters: bridged labels its own worker tabs, so if a worker space were scanned
+     * a naming accident would promote the fleet. The exclusion is by workspace, not by hoping the
+     * worker template never collides.
+     */
+    @Test
+    void aTabInAWorkerSpaceIsNeverALeadEvenWhenItsLabelMatches() {
+        TopologyHerdr herdr = twoLeads().tab("w9:t2", "w9", "lead: impostor")
+                .pane("w9:p2", "w9:t2", "term_impostor");
+
+        assertFalse(scanner(herdr, Map.of(), new AtomicLong()).get().containsKey("term_impostor"));
+    }
+
+    @Test
+    void aBarePrefixNamesNobodyAndIsRejected() {
+        TopologyHerdr herdr = new TopologyHerdr().workspace("w1", "main")
+                .tab("w1:t1", "w1", "lead:").pane("w1:p1", "w1:t1", "term_a");
+
+        assertEquals(Map.of(), scanner(herdr, Map.of(), new AtomicLong()).get(),
+                "a lead with no name would resolve as PRIMARY with nothing to attribute it to");
+    }
+
+    @Test
+    void thePrefixMatchesCaseInsensitivelyAndTheNameIsTrimmed() {
+        TopologyHerdr herdr = new TopologyHerdr().workspace("w1", "main")
+                .tab("w1:t1", "w1", "  LEAD:   opus-5.0  ").pane("w1:p1", "w1:t1", "term_a");
+
+        assertEquals(Map.of("term_a", "opus-5.0"), scanner(herdr, Map.of(), new AtomicLong()).get());
+    }
+
+    @Test
+    void everyPaneInALeadTabResolvesAsThatLead() {
+        // A human may split their own lead tab. Both panes are theirs, so both are that lead —
+        // nothing bridged placed can land here (see the worker-space test above).
+        TopologyHerdr herdr = twoLeads().pane("w1:p1b", "w1:t1", "term_opus_split");
+
+        assertEquals("opus-5.0", scanner(herdr, Map.of(), new AtomicLong()).get().get("term_opus_split"));
+    }
+
+    @Test
+    void anExplicitlyConfiguredLeadIsMergedInAndOutranksALabel() {
+        Map<String, String> configured = Map.of("term_opus", "pinned-name", "term_extra", "from-config");
+
+        Map<String, String> leads = scanner(twoLeads(), configured, new AtomicLong()).get();
+
+        assertEquals("pinned-name", leads.get("term_opus"), "an explicit pin is the operator's last word");
+        assertEquals("from-config", leads.get("term_extra"), "a configured lead needs no tab at all");
+        assertEquals("gpt-sol-5.6", leads.get("term_gpt"));
+    }
+
+    // ── caching ─────────────────────────────────────────────────────────────────────────────────
+
+    @Test
+    void aSecondLookupWithinTheTtlDoesNotTouchHerdr() {
+        TopologyHerdr herdr = twoLeads();
+        AtomicLong clock = new AtomicLong();
+        LeadTabScanner s = scanner(herdr, Map.of(), clock);
+
+        s.get();
+        int afterFirst = herdr.calls;
+        clock.addAndGet(TTL - 1);
+        s.get();
+
+        assertEquals(afterFirst, herdr.calls,
+                "resolve() runs on every request — an un-cached scan would put herdr on that path");
+    }
+
+    @Test
+    void aTabLabelledAfterStartupIsPickedUpOnceTheTtlExpires() {
+        TopologyHerdr herdr = twoLeads();
+        AtomicLong clock = new AtomicLong();
+        LeadTabScanner s = scanner(herdr, Map.of(), clock);
+        assertFalse(s.get().containsKey("term_notes"));
+
+        herdr.tab("w1:t3", "w1", "lead: late-arrival"); // the operator renames their tab
+        clock.addAndGet(TTL);
+
+        assertEquals("late-arrival", s.get().get("term_notes"),
+                "the whole point over `leaders:`: no config edit, no restart");
+    }
+
+    @Test
+    void aFailedScanKeepsTheLeadsAlreadyKnownRatherThanDemotingThem() {
+        TopologyHerdr herdr = twoLeads();
+        AtomicLong clock = new AtomicLong();
+        LeadTabScanner s = scanner(herdr, Map.of(), clock);
+        Map<String, String> before = s.get();
+
+        herdr.failing = true;
+        clock.addAndGet(TTL);
+
+        assertEquals(before, s.get(),
+                "a herdr hiccup must not silently demote a live lead to a worker mid-session");
+    }
+
+    @Test
+    void aFailedFirstScanStillHonoursTheConfiguredLeads() {
+        TopologyHerdr herdr = twoLeads();
+        herdr.failing = true;
+
+        Map<String, String> leads = scanner(herdr, Map.of("term_x", "opus-5.0"), new AtomicLong()).get();
+
+        assertEquals(Map.of("term_x", "opus-5.0"), leads,
+                "config-named leads must not depend on herdr answering at all");
+    }
+
+    @Test
+    void aDownHerdrIsRetriedOncePerTtlNotOncePerRequest() {
+        TopologyHerdr herdr = twoLeads();
+        herdr.failing = true;
+        AtomicLong clock = new AtomicLong();
+        LeadTabScanner s = scanner(herdr, Map.of(), clock);
+
+        s.get();
+        int afterFirst = herdr.calls;
+        s.get();
+        s.get();
+
+        assertEquals(afterFirst, herdr.calls, "the failure path must be rate-limited too");
+    }
+}

bridged/src/test/java/dev/ltms/bridged/herdr/PaneLocatorContractTest.java

@@ -0,0 +1,48 @@
+package dev.ltms.bridged.herdr;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Files;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+
+/**
+ * Contract test for {@link PaneLocator} against a REAL herdr: the PID→pane mapping that
+ * connection identity rests on. Uses a throwaway tab's seed shell as the probe process
+ * (protocol 19 removed arbitrary-command agents), and always tears the space down.
+ *
+ * <p>Tagged {@code contract}; run with {@code mvn test -Pcontract}.
+ */
+@Tag("contract")
+class PaneLocatorContractTest {
+
+    @Test
+    void resolvesTheTerminalOwningARealProcessPid() throws Exception {
+        assumeTrue(Files.exists(UnixSocketHerdrClient.defaultSocketPath()), "no herdr socket — skipping");
+        try (UnixSocketHerdrClient herdr = UnixSocketHerdrClient.connect()) {
+            WorkspaceControl spaces = new WorkspaceControl(herdr);
+            Workspace space = spaces.ensureWorkspace("__bridged_pid_contract__");
+            Tab.Created tab = spaces.createTab(space.workspaceId(), null, Map.of());
+            try {
+                JsonNode info = herdr.call("pane.process_info", Map.of("pane_id", tab.rootPaneId()))
+                        .path("process_info");
+                long shellPid = info.path("shell_pid").asLong(-1);
+                assertTrue(shellPid > 0, "seed pane should report a shell pid");
+
+                String terminalId = herdr.call("pane.get", Map.of("pane_id", tab.rootPaneId()))
+                        .path("pane").path("terminal_id").asText(null);
+                assertNotNull(terminalId, "seed pane should carry a terminal_id");
+
+                assertEquals(terminalId, new PaneLocator(herdr).terminalForPid(shellPid),
+                        "a real PID must resolve back to its own pane's terminal_id");
+            } finally {
+                spaces.closeTab(tab.tab().tabId());
+                herdr.call("workspace.close", Map.of("workspace_id", space.workspaceId()));
+            }
+        }
+    }
+}

bridged/src/test/java/dev/ltms/bridged/herdr/PaneLocatorTest.java

@@ -0,0 +1,27 @@
+package dev.ltms.bridged.herdr;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/** Unit tests for PID → pane resolution (the herdr half of connection-based MCP identity). */
+class PaneLocatorTest {
+
+    private final PaneLocator loc = new PaneLocator(new FakeHerdr());
+
+    @Test
+    void resolvesTerminalForAForegroundPid() {
+        assertEquals("term_a", loc.terminalForPid(FakeHerdr.WORKER_PID));
+    }
+
+    @Test
+    void nullForAPidInNoPane() {
+        assertNull(loc.terminalForPid(999_999));
+    }
+
+    @Test
+    void nullForNonPositivePid() {
+        assertNull(loc.terminalForPid(0));
+        assertNull(loc.terminalForPid(-1));
+    }
+}

bridged/src/test/java/dev/ltms/bridged/herdr/WorkspacePlacementContractTest.java

@@ -5,7 +5,6 @@ import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 
 import java.nio.file.Files;
-import java.util.List;
 import java.util.Map;
 
 import static org.junit.jupiter.api.Assertions.*;
@@ -13,9 +12,9 @@ import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
 /**
  * Contract test for the placement layer ({@code workspace.*}/{@code tab.*}) against a
- * REAL herdr, locking in the "one clean tab per worker" recipe: find-or-create a worker
- * space, give the worker its own tab, drop herdr's seed shell so the tab holds only the
- * worker, and tear it all down. Uses a HARMLESS probe (never {@code claude}) in a
+ * REAL herdr, locking in the "one clean tab per worker" recipe under protocol 19: find-or-create
+ * a worker space, give the worker its own tab, and the SEED pane is where the worker starts —
+ * the tab holds exactly that one pane from creation. Uses no agent (never {@code claude}) in a
  * throwaway space that is fully removed at the end.
  *
  * <p>Tagged {@code contract}; run with {@code mvn test -Pcontract}.
@@ -41,7 +40,6 @@ class WorkspacePlacementContractTest {
     void workerGetsOwnCleanTabAndTearsDownCompletely() throws Exception {
         assumeTrue(!noSocket(), "no herdr socket — skipping");
         try (UnixSocketHerdrClient herdr = UnixSocketHerdrClient.connect()) {
-            AgentControl agents = new AgentControl(herdr);
             WorkspaceControl spaces = new WorkspaceControl(herdr);
 
             Workspace space = spaces.ensureWorkspace(LABEL);
@@ -49,36 +47,27 @@ class WorkspacePlacementContractTest {
             // Idempotent: a second ensure finds the same space, never creates a duplicate.
             assertEquals(space.workspaceId(), spaces.ensureWorkspace(LABEL).workspaceId());
 
-            Tab.Created tab = spaces.createTab(space.workspaceId());
-            Agent worker = agents.start(
-                    "__contract__",
-                    List.of("bash", "-c", "sleep 20"),
-                    Map.of(),
-                    tab.tab().tabId());
+            Tab.Created tab = spaces.createTab(space.workspaceId(), null, Map.of());
             try {
-                // The worker landed in its dedicated tab in the worker space.
-                assertEquals(tab.tab().tabId(), worker.tabId());
-                assertEquals(space.workspaceId(), worker.workspaceId());
+                assertNotNull(tab.rootPaneId(), "tab.create must return the seed pane");
 
-                // Drop the seed shell; the tab now holds exactly the worker pane.
-                agents.close(tab.rootPaneId());
+                // Protocol 19: the seed pane IS the worker pane — the tab holds exactly it.
                 spaces.renameTab(tab.tab().tabId(), "worker: contract");
                 assertEquals(1, paneCount(herdr, space.workspaceId(), tab.tab().tabId()),
-                        "worker tab must hold only the worker pane after the seed shell is dropped");
+                        "worker tab must hold exactly the seed/worker pane");
 
                 // Teardown resolves the tab from the pane, and sees it holds exactly one pane.
-                WorkspaceControl.PaneLocation loc = spaces.locatePane(worker.paneId());
+                WorkspaceControl.PaneLocation loc = spaces.locatePane(tab.rootPaneId());
                 assertNotNull(loc);
                 assertEquals(tab.tab().tabId(), loc.tabId());
-                assertEquals(1, loc.tabPaneCount(), "worker is the tab's sole occupant");
+                assertEquals(1, loc.tabPaneCount(), "worker pane is the tab's sole occupant");
             } finally {
-                agents.close(worker.paneId());
                 spaces.closeTab(tab.tab().tabId());
             }
 
             // Tolerant teardown: closing an already-gone tab / reading a gone pane is a no-op.
             spaces.closeTab(tab.tab().tabId());
-            assertNull(spaces.locatePane(worker.paneId()), "closed worker pane must be gone");
+            assertNull(spaces.locatePane(tab.rootPaneId()), "closed worker pane must be gone");
 
             // Remove the throwaway space entirely so the test leaves no residue.
             herdr.call("workspace.close", Map.of("workspace_id", space.workspaceId()));

bridged/src/test/java/dev/ltms/bridged/inject/CompletionResolverTest.java

@@ -0,0 +1,304 @@
+package dev.ltms.bridged.inject;
+
+import dev.ltms.bridged.herdr.AgentControl;
+import dev.ltms.bridged.herdr.FakeHerdr;
+import dev.ltms.bridged.msg.Rendezvous;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/** Unit behaviour of the CB-106 completion resolver in isolation from the injector. */
+class CompletionResolverTest {
+
+    @Test
+    void skipsTheScrapeWhenNoSendIsWaiting() {
+        FakeHerdr herdr = new FakeHerdr();
+        Rendezvous rendezvous = new Rendezvous(); // no waiter opened
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        resolver.resolve("term_a", null); // no in-flight turn captured for this target
+
+        assertFalse(herdr.called("agent.read"),
+                "a turn nobody is blocked on must not cost a transcript scrape");
+    }
+
+    @Test
+    void failSkipsTheScrapeWhenNoSendIsWaiting() {
+        FakeHerdr herdr = new FakeHerdr();
+        Rendezvous rendezvous = new Rendezvous(); // no waiter opened
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        resolver.fail("term_a", null); // no in-flight turn, and no registered waiter to fall back to
+
+        assertFalse(herdr.called("agent.read"),
+                "a wedge nobody is blocked on must not cost a transcript scrape");
+    }
+
+    @Test
+    void captureBaselineSkipsTheReadWhenNoSendIsWaiting() {
+        FakeHerdr herdr = new FakeHerdr().readText("⏺ X\n❯ ");
+        Rendezvous rendezvous = new Rendezvous(); // no waiter opened
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        resolver.captureBaseline("term_a"); // no send to attribute a later completion to
+
+        assertFalse(herdr.called("agent.read"),
+                "with no waiting send there is no turn to baseline — skip the scrape");
+    }
+
+    // --- CB-115 clean scrape: extract the last assistant block ----------------
+
+    @Test
+    void extractsTheLastAssistantBlockStrippingChrome() {
+        String raw = """
+                ⏺ Reading the file…
+
+                ⏺ Done. The bug was an off-by-one in the loop bound.
+
+                ╭──────────────────────────────────────╮
+                │ >                                    │
+                ╰──────────────────────────────────────╯
+                  ⏵⏵ auto mode on · ? for shortcuts
+                """;
+        assertEquals("Done. The bug was an off-by-one in the loop bound.",
+                CompletionResolver.lastAssistantBlock(raw));
+    }
+
+    @Test
+    void keepsMultiLineAssistantContent() {
+        String raw = "⏺ Line one.\nLine two.\n❯ ";
+        assertEquals("Line one.\nLine two.", CompletionResolver.lastAssistantBlock(raw));
+    }
+
+    @Test
+    void fallsBackToRawTextWhenThereIsNoMarker() {
+        String raw = "plain worker output with no glyph";
+        assertEquals("plain worker output with no glyph", CompletionResolver.lastAssistantBlock(raw));
+    }
+
+    @Test
+    void blankScrapeYieldsEmpty() {
+        assertTrue(CompletionResolver.lastAssistantBlock("").isEmpty());
+        assertTrue(CompletionResolver.lastAssistantBlock(null).isEmpty());
+    }
+
+    @Test
+    void stripsSpinnerAndRuleChrome() {
+        String raw = """
+                ⏺ Channel check confirmed — your message got through.
+
+                ✻ Brewed for 11s
+
+                ─────────────────────────────────────
+                """;
+        assertEquals("Channel check confirmed — your message got through.",
+                CompletionResolver.lastAssistantBlock(raw));
+    }
+
+    @Test
+    void cutsANextTurnPromptEchoAndTrailingTipsFromTheBlock() {
+        // The exact turn-2 leak: the scrape captured the settled answer, then a "✻ Cooked" spinner,
+        // then the NEXT turn's echoed prompt, then a "✶ Forming…" spinner and trailing tips/warnings
+        // whose lines (⎿, ⚠) are not themselves chrome-terminated. Stopping at the first boundary
+        // (the ✻ spinner) is what keeps every one of those interface lines out of the reply.
+        String raw = """
+                ⏺ Channel confirmed — the bridge reply delivered successfully.
+
+                ✻ Cooked for 9s
+
+                ❯ Thanks. Now a small task: what is 17 * 23? Show just the number.
+
+
+
+                ✶ Forming…
+                  ⎿  Tip: Name your conversations with /rename
+                  ⚠ claude.ai connectors are disabled because ANTHROPIC_API_KEY is set
+                """;
+        assertEquals("Channel confirmed — the bridge reply delivered successfully.",
+                CompletionResolver.lastAssistantBlock(raw));
+    }
+
+    // --- CB-115 misattribution guard: suppress a stale (unchanged) completion -------
+
+    @Test
+    void suppressesACompletionWhoseScrapeIsUnchangedFromDelivery() {
+        // Rapid back-to-back turn: the pane still shows the PREVIOUS turn's answer when this turn's
+        // (misattributed) completion boundary fires. The scrape == the delivery baseline, so the
+        // send must NOT be resolved with the stale answer.
+        FakeHerdr herdr = new FakeHerdr().readText("⏺ 391\n❯ ");
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a");   // a send is blocked on this turn
+        // The turn as captured at delivery: its waiter, and the previous turn's answer still on screen.
+        var turn = new CompletionResolver.InFlight(waiter, "391");
+        resolver.resolve("term_a", turn);          // scrape still "391" == baseline → suppress
+
+        assertFalse(waiter.isDone(), "a completion with no output change must not resolve the send");
+        assertTrue(rendezvous.isWaiting("term_a"), "the send stays waiting for a real reply");
+    }
+
+    @Test
+    void resolvesACompletionWhoseScrapeChangedSinceDelivery() {
+        FakeHerdr herdr = new FakeHerdr().readText("⏺ No, 391 = 17 × 23.\n❯ "); // the worker's real answer
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a");
+        // Delivery baseline was the previous turn's "391"; the scrape now differs → resolve.
+        var turn = new CompletionResolver.InFlight(waiter, "391");
+        resolver.resolve("term_a", turn);
+
+        assertTrue(waiter.isDone(), "a completion with new output must resolve the send");
+        assertEquals(Rendezvous.Kind.COMPLETION, waiter.getNow(null).kind());
+        assertEquals("No, 391 = 17 × 23.", waiter.getNow(null).text());
+    }
+
+    @Test
+    void resolvesSynchronouslyBeforePostTurnContextClearing() {
+        FakeHerdr herdr = new FakeHerdr().readText("⏺ previous answer\n❯ ");
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+        var waiter = rendezvous.open("term_a");
+        resolver.captureBaseline("term_a");
+        herdr.readText("⏺ answer that /clear would erase\n❯ ");
+
+        resolver.resolveBeforePostAction("term_a");
+
+        assertTrue(waiter.isDone(), "the answer is captured before the adapter sends /clear");
+        assertEquals("answer that /clear would erase", waiter.getNow(null).text());
+    }
+
+    @Test
+    void suppressesAnUnchangedCompletionEvenWhenTheBlockExceedsTheScrapeCap() {
+        // The fan-out issue-hunt finding: captureBaseline once stored the RAW (unclipped) assistant
+        // block while resolve compares against a clip()'d tail. For a block longer than MAX_SCRAPE_CHARS
+        // the two capped representations differ even when the pane never changed, so the CB-115
+        // byte-identical guard failed to fire and a stale completion could resolve the send. Both sides
+        // must clip identically; here an unchanged >cap block on rapid back-to-back turns stays suppressed.
+        String longBlock = "⏺ " + "x".repeat(CompletionResolver.MAX_SCRAPE_CHARS + 500) + "\n❯ ";
+        FakeHerdr herdr = new FakeHerdr().readText(longBlock);
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a");        // a send is blocked on this turn
+        resolver.captureBaseline("term_a");            // baseline is the clipped >cap block
+        var turn = resolver.inFlight("term_a");
+        assertEquals(CompletionResolver.MAX_SCRAPE_CHARS, turn.baseline().length(),
+                "the delivery baseline is clipped to the same cap resolve() applies to the tail");
+
+        resolver.resolve("term_a", turn);              // scrape unchanged → clipped tail == baseline → suppress
+
+        assertFalse(waiter.isDone(),
+                "an unchanged >cap block must still be recognised as stale and suppressed");
+        assertTrue(rendezvous.isWaiting("term_a"), "the send stays waiting for a real reply");
+    }
+
+    @Test
+    void resolvesWhenThereIsNoBaseline() {
+        // No delivery baseline (e.g. the pre-turn read failed) ⇒ never suppress; the completion resolves.
+        FakeHerdr herdr = new FakeHerdr().readText("⏺ hello\n❯ ");
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a");
+        resolver.resolve("term_a", new CompletionResolver.InFlight(waiter, null));
+
+        assertTrue(waiter.isDone(), "with no baseline a completion resolves as before");
+        assertEquals("hello", waiter.getNow(null).text());
+    }
+
+    @Test
+    void resolvesWhenTheScrapeItselfFailsEvenWithABaselinePresent() {
+        // The most important branch of the CB-115 guard: a failed read means the resolver could not
+        // SEE the screen — "couldn't see", not "no change". It must still resolve the send (an empty
+        // tail beats hanging until the caller's timeout), even though a baseline was captured. The
+        // baseline here is "" (an empty pane at delivery), so without the !scrapeFailed clause the
+        // byte-identical guard would wrongly match the empty tail and suppress.
+        FakeHerdr herdr = new FakeHerdr().healthy(false); // agent.read throws HerdrException
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a");
+        var turn = new CompletionResolver.InFlight(waiter, ""); // empty pane baselined at delivery
+        resolver.resolve("term_a", turn);
+
+        assertTrue(waiter.isDone(),
+                "a failed scrape must still resolve the send, not hang until the caller's timeout");
+        assertEquals(Rendezvous.Kind.COMPLETION, waiter.getNow(null).kind());
+        assertEquals("", waiter.getNow(null).text(), "the tail is empty because the screen was unreadable");
+    }
+
+    // --- CB-115/CB-116 fail guard: an already-done or absent waiter is left alone ---------
+
+    @Test
+    void failLeavesAnAlreadyResolvedWaiterUntouchedAndSkipsTheScrape() {
+        // The send was already resolved (e.g. by the worker's explicit reply) before fail fired.
+        // fail must not overwrite that value, and must not even scrape the worker — nobody needs it.
+        FakeHerdr herdr = new FakeHerdr().readText("an error screen");
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a");
+        var turn = new CompletionResolver.InFlight(waiter, null);
+        assertTrue(rendezvous.resolveCompletion(waiter, "already replied"));
+
+        resolver.fail("term_a", turn);
+
+        assertFalse(herdr.called("agent.read"),
+                "fail must not scrape a waiter that is already done");
+        assertEquals(Rendezvous.Kind.COMPLETION, waiter.getNow(null).kind(),
+                "fail must not overwrite the existing resolution");
+        assertEquals("already replied", waiter.getNow(null).text());
+    }
+
+    @Test
+    void failFallsBackToTheRegisteredWaiterWhenThereIsNoInFlightTurn() {
+        // A never-delivered readiness failure has no in-flight record but still has a blocked send;
+        // fail falls back to the waiter currently registered on the Rendezvous and fails it.
+        FakeHerdr herdr = new FakeHerdr().readText("stuck on an error screen");
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiter = rendezvous.open("term_a"); // send registered, but no captureBaseline ever ran
+        resolver.fail("term_a", null);          // no in-flight turn → fall back to the registered waiter
+
+        assertTrue(waiter.isDone(), "fail falls back to the registered waiter when no turn is in flight");
+        assertEquals(Rendezvous.Kind.FAILED, waiter.getNow(null).kind());
+        assertEquals("stuck on an error screen", waiter.getNow(null).text());
+    }
+
+    // --- CB-116 waiter identity: a late completion never crosses into the next turn ---------
+
+    @Test
+    void aLateCompletionForOneTurnNeverResolvesTheNextTurnsWaiter() {
+        // The cross-turn stale reply the conversation test surfaced: turn N's completion fallback
+        // fires AFTER turn N was resolved by an explicit bridge_reply and turn N+1 has opened its own
+        // waiter on the same session. Resolving "whatever is waiting now" would hand turn N's stale
+        // scrape to turn N+1; targeting turn N's captured waiter makes the late completion a no-op.
+        FakeHerdr herdr = new FakeHerdr().readText("⏺ turn N answer\n❯ ");
+        Rendezvous rendezvous = new Rendezvous();
+        CompletionResolver resolver = new CompletionResolver(new AgentControl(herdr), rendezvous);
+
+        var waiterN = rendezvous.open("term_a"); // turn N's send
+        // The turn as the injector captured it at delivery (waiter + pre-turn baseline).
+        var turnN = new CompletionResolver.InFlight(waiterN, "an earlier answer");
+
+        // Turn N is resolved by the worker's explicit reply, and its send deregisters the waiter.
+        assertTrue(rendezvous.resolve("term_a", "N replied"));
+        rendezvous.close("term_a", waiterN); // the sender's finally, before the next turn opens
+
+        // Turn N+1's send opens its own waiter on the same session (CB-548: open fails if the
+        // previous waiter is still registered, so a clean turn deregisters it first as above).
+        var waiterN1 = rendezvous.open("term_a");
+
+        resolver.resolve("term_a", turnN); // turn N's completion fallback finally fires
+
+        assertFalse(waiterN1.isDone(), "turn N's late completion must not resolve turn N+1's waiter");
+        assertEquals(Rendezvous.Kind.REPLY, waiterN.getNow(null).kind(),
+                "turn N stays resolved by its own reply");
+        assertTrue(rendezvous.isWaiting("term_a"), "turn N+1 is still awaiting its own resolution");
+    }
+}

bridged/src/test/java/dev/ltms/bridged/inject/InjectorTest.java

@@ -6,8 +6,10 @@ import dev.ltms.bridged.herdr.FakeHerdr;
 import dev.ltms.bridged.herdr.HerdrException;
 import org.junit.jupiter.api.Test;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeUnit;
@@ -25,11 +27,15 @@ class InjectorTest {
     private final FakeHerdr herdr = new FakeHerdr();
     private final Injector injector = new Injector(new AgentControl(herdr));
 
-    /** Text of every agent.send, in order. */
+    /**
+     * The logical messages delivered, in order. Under protocol 19 each delivery is one
+     * {@code agent.prompt} carrying the payload (it submits itself); the Enter nudge is a
+     * separate {@code agent.send_keys} and never appears here.
+     */
     @SuppressWarnings("unchecked")
     private List<String> sent() {
         return herdr.calls.stream()
-                .filter(c -> c.method().equals("agent.send"))
+                .filter(c -> c.method().equals("agent.prompt"))
                 .map(c -> ((Map<String, Object>) c.params()).get("text").toString())
                 .toList();
     }
@@ -43,6 +49,45 @@ class InjectorTest {
         assertEquals(List.of("hello"), sent());
     }
 
+    @Test
+    void holdsDeliveryUntilTheWorkerIsAvailable() {
+        // CB-113: idle alone is not enough — hold until the worker's MCP is connected (ready).
+        java.util.Set<String> ready = new java.util.HashSet<>();
+        Injector inj = new Injector(new AgentControl(herdr), TurnListener.NOOP, ready::contains);
+        inj.enqueue(T, "task");
+
+        inj.onStatus(T, AgentStatus.IDLE); // idle but not yet available → held out of the boot window
+        assertEquals(List.of(), sent(), "must not deliver into a not-yet-available worker");
+
+        ready.add(T);                      // the worker's Claude connects the bridge MCP
+        inj.onStatus(T, AgentStatus.IDLE);
+        assertEquals(List.of("task"), sent(), "delivers once the worker is available");
+    }
+
+    private long enterKeystrokes() {
+        return herdr.calls.stream()
+                .filter(c -> c.method().equals("agent.send_keys"))
+                .count();
+    }
+
+    @Test
+    void resubmitsEnterWhenADeliveredMessageIsNotPickedUp() {
+        // CB-113: the Enter at delivery can race the paste; while the worker stays idle (not picked
+        // up), the injector re-nudges Enter so the pending paste submits.
+        injector.enqueue(T, "task");
+        injector.onStatus(T, AgentStatus.IDLE); // deliver: paste + one Enter
+        long afterDeliver = enterKeystrokes();
+
+        injector.onStatus(T, AgentStatus.IDLE); // still idle → re-nudge Enter
+        injector.onStatus(T, AgentStatus.IDLE); // and again
+        assertTrue(enterKeystrokes() > afterDeliver, "an unpicked-up delivery re-nudges Enter");
+
+        injector.onStatus(T, AgentStatus.WORKING); // worker finally starts
+        long atPickup = enterKeystrokes();
+        injector.onStatus(T, AgentStatus.WORKING);
+        assertEquals(atPickup, enterKeystrokes(), "no more nudges once the worker has picked up");
+    }
+
     @Test
     void holdsWhileWorkingThenDeliversOnIdle() {
         injector.enqueue(T, "later");
@@ -120,17 +165,138 @@ class InjectorTest {
     }
 
     @Test
-    void activeWhileQueuedOrInFlightThenQuietAfterPickup() {
+    void activeWhileQueuedOrInFlightThenQuietAfterTurnCompletes() {
         assertTrue(injector.activeTargets().isEmpty());
         injector.enqueue(T, "x");
-        assertEquals(java.util.Set.of(T), injector.activeTargets(), "active while a message is queued");
+        assertEquals(Set.of(T), injector.activeTargets(), "active while a message is queued");
 
-        injector.onStatus(T, AgentStatus.IDLE); // delivers; still in-flight (awaiting pickup)
-        assertEquals(java.util.Set.of(T), injector.activeTargets(),
+        injector.onStatus(T, AgentStatus.IDLE); // delivers; awaiting pickup
+        assertEquals(Set.of(T), injector.activeTargets(),
                 "stays active so the poller can observe the worker pick the message up");
 
-        injector.onStatus(T, AgentStatus.WORKING); // pickup observed → in-flight cleared
-        assertTrue(injector.activeTargets().isEmpty(), "quiet once queue is empty and pickup is seen");
+        injector.onStatus(T, AgentStatus.WORKING); // pickup observed; now awaiting turn completion
+        assertEquals(Set.of(T), injector.activeTargets(),
+                "stays active after pickup so the working→idle completion boundary is observed");
+
+        injector.onStatus(T, AgentStatus.IDLE); // working → idle: turn complete
+        assertTrue(injector.activeTargets().isEmpty(), "quiet once the delegated turn has completed");
+    }
+
+    @Test
+    void firesTurnCompleteOnAConfirmedWorkingThenIdle() {
+        List<String> completed = new ArrayList<>();
+        Injector inj = new Injector(new AgentControl(herdr), completed::add);
+        inj.enqueue(T, "task");
+
+        inj.onStatus(T, AgentStatus.IDLE);    // deliver
+        inj.onStatus(T, AgentStatus.WORKING); // pickup + turn running
+        assertEquals(List.of(), completed, "no completion until the turn returns to idle");
+
+        inj.onStatus(T, AgentStatus.IDLE);    // working → idle: turn complete
+        assertEquals(List.of(T), completed, "a confirmed working→idle fires exactly one completion");
+    }
+
+    @Test
+    void postTurnResetSettlesBeforeNextDelegationWithoutBecomingATurn() {
+        AgentControl agents = new AgentControl(herdr);
+        class ResetListener implements TurnListener {
+            int completed;
+
+            @Override
+            public void onTurnComplete(String target) {
+                completed++;
+            }
+
+            @Override
+            public boolean hasPostTurnAction(String target) {
+                return true;
+            }
+
+            @Override
+            public boolean onTurnCompleteWithPostAction(String target) {
+                completed++;
+                agents.send(target, "/clear"); // direct housekeeping, never Injector.enqueue
+                return true;
+            }
+        }
+        ResetListener listener = new ResetListener();
+        Injector inj = new Injector(agents, listener);
+        inj.enqueue(T, "first");
+        inj.enqueue(T, "second");
+
+        inj.onStatus(T, AgentStatus.IDLE);    // first delegation
+        inj.onStatus(T, AgentStatus.WORKING);
+        inj.onStatus(T, AgentStatus.IDLE);    // first complete; reset dispatched
+        assertEquals(List.of("first", "/clear"), sent(),
+                "same-tick completion must not let the queued delegation overtake reset");
+
+        inj.onStatus(T, AgentStatus.WORKING); // reset picked up, but this is not a bridge turn
+        inj.onStatus(T, AgentStatus.IDLE);    // reset settled; second may now deliver
+        assertEquals(List.of("first", "/clear", "second"), sent());
+        assertEquals(1, listener.completed,
+                "reset settlement must not recursively emit another turn completion");
+    }
+
+    @Test
+    void doesNotSynthesizeCompletionFromAnUnconfirmedTurn() {
+        List<String> completed = new ArrayList<>();
+        Injector inj = new Injector(new AgentControl(herdr), completed::add);
+        inj.enqueue(T, "task");
+
+        // Deliver, then only ever idle — a `working` sample is never seen. The pickup grace unwedges
+        // the queue but must NOT invent a completion: without a sampled turn there is no trustworthy
+        // "the worker finished the task" signal, so the send should fall through to its timeout.
+        for (int i = 0; i < 15; i++) inj.onStatus(T, AgentStatus.IDLE);
+        assertEquals(List.of(), completed, "no completion is synthesized from an unconfirmed turn");
+    }
+
+    /** Captures both turn-lifecycle callbacks so the CB-109 stall path can be asserted. */
+    private static final class Captor implements TurnListener {
+        final List<String> completed = new ArrayList<>();
+        final List<String> failed = new ArrayList<>();
+
+        @Override
+        public void onTurnComplete(String target) {
+            completed.add(target);
+        }
+
+        @Override
+        public void onTurnFailed(String target) {
+            failed.add(target);
+        }
+    }
+
+    // ~30s of unknown at the 250ms prod poll interval; enough onStatus samples to trip the stall.
+    private static final int STALL_SAMPLES = 130;
+
+    @Test
+    void failsAnOutstandingDelegationWhoseWorkerWedgesInUnknown() {
+        Captor cap = new Captor();
+        Injector inj = new Injector(new AgentControl(herdr), cap);
+        inj.enqueue(T, "task");
+
+        inj.onStatus(T, AgentStatus.IDLE);    // deliver
+        inj.onStatus(T, AgentStatus.WORKING); // worker starts the turn
+        for (int i = 0; i < STALL_SAMPLES; i++) inj.onStatus(T, AgentStatus.UNKNOWN); // then wedges
+
+        assertEquals(List.of(T), cap.failed, "a sustained unknown streak fails the outstanding send");
+        assertEquals(List.of(), cap.completed, "a wedge is a failure, not a completion");
+        assertTrue(inj.activeTargets().isEmpty(), "the wedged target is reclaimed, not polled forever");
+    }
+
+    @Test
+    void aTransientUnknownGlitchNeitherFailsNorBlocksCompletion() {
+        Captor cap = new Captor();
+        Injector inj = new Injector(new AgentControl(herdr), cap);
+        inj.enqueue(T, "task");
+
+        inj.onStatus(T, AgentStatus.IDLE);    // deliver
+        inj.onStatus(T, AgentStatus.WORKING); // confirmed turn
+        for (int i = 0; i < 10; i++) inj.onStatus(T, AgentStatus.UNKNOWN); // brief glitch, well under grace
+        inj.onStatus(T, AgentStatus.IDLE);    // working → idle: the real completion
+
+        assertEquals(List.of(), cap.failed, "a short unknown blip must not fail the turn");
+        assertEquals(List.of(T), cap.completed, "the streak reset, so the turn still completes");
     }
 
     @Test
@@ -151,6 +317,86 @@ class InjectorTest {
         assertTrue(f.isCompletedExceptionally(), "queued waiters unblock when the worker vanishes");
     }
 
+    @Test
+    void dropFailsTheTurnOfADeliveredMessageWhenTheWorkerVanishes() {
+        // CB-110: the message was delivered (no longer queued), so failing queued waiters alone would
+        // leave its send hanging. A vanished worker must fail that in-flight turn too.
+        Captor cap = new Captor();
+        Injector inj = new Injector(new AgentControl(herdr), cap);
+        inj.enqueue(T, "task");
+        inj.onStatus(T, AgentStatus.IDLE);    // deliver
+        inj.onStatus(T, AgentStatus.WORKING); // turn running
+
+        inj.drop(T, new HerdrException("worker gone", "pane_not_found", null));
+        assertEquals(List.of(T), cap.failed, "a worker that vanishes mid-turn fails its in-flight send");
+    }
+
+    @Test
+    void dropFailsADeliveredTurnThatVanishesBeforePickupIsConfirmed() {
+        // Delivered but no WORKING sampled yet (awaitingCompletion=true, awaitingPickup still true,
+        // turnObserved=false) — a distinct state the other two drop tests don't cover. (Gap surfaced
+        // by an off-sub worker's review of CB-110, delegated through the bridge.)
+        Captor cap = new Captor();
+        Injector inj = new Injector(new AgentControl(herdr), cap);
+        inj.enqueue(T, "task");
+        inj.onStatus(T, AgentStatus.IDLE); // deliver; pickup never confirmed
+
+        inj.drop(T, new HerdrException("worker gone", "pane_not_found", null));
+        assertEquals(List.of(T), cap.failed, "a delivery that vanishes before pickup still fails its send");
+    }
+
+    // ~60s of idle-but-not-ready at the 250ms prod poll interval; enough to trip the readiness grace.
+    private static final int READINESS_SAMPLES = 245;
+
+    @Test
+    void failsAQueuedMessageWhoseWorkerNeverBecomesReady() {
+        // CB-114: herdr keeps reporting the worker idle, but its Claude never connects the bridge MCP,
+        // so the readiness gate never opens. The message must not be held (and the target polled)
+        // forever — after the grace it fails, the caller unblocks via the worker-failure path, the
+        // target is reclaimed, and the never-set presence is cleared.
+        Captor cap = new Captor();
+        List<String> forgotten = new ArrayList<>();
+        Injector inj = new Injector(new AgentControl(herdr), cap, _ -> false, forgotten::add);
+        CompletableFuture<Void> f = inj.enqueue(T, "task");
+
+        for (int i = 0; i < READINESS_SAMPLES; i++) inj.onStatus(T, AgentStatus.IDLE);
+
+        assertEquals(List.of(), sent(), "a never-ready worker is never delivered to");
+        assertTrue(f.isCompletedExceptionally(), "the caller's future fails instead of hanging forever");
+        assertEquals(List.of(T), cap.failed, "the awaiting send resolves through the worker-failure path");
+        assertEquals(List.of(), cap.completed, "a never-ready worker is a failure, not a completion");
+        assertEquals(List.of(T), forgotten, "the never-ready worker's presence is cleared");
+        assertTrue(inj.activeTargets().isEmpty(), "the target is reclaimed, not polled forever");
+    }
+
+    @Test
+    void aWorkerThatBecomesReadyWithinTheGraceIsDeliveredNormally() {
+        // The readiness grace must not fail a worker that is merely slow to boot: once it becomes
+        // available before the grace elapses, delivery proceeds as usual (the counter resets).
+        Set<String> ready = new java.util.HashSet<>();
+        Injector inj = new Injector(new AgentControl(herdr), TurnListener.NOOP, ready::contains, _ -> {
+        });
+        inj.enqueue(T, "task");
+
+        for (int i = 0; i < 100; i++) inj.onStatus(T, AgentStatus.IDLE); // still booting, well under grace
+        assertEquals(List.of(), sent());
+
+        ready.add(T); // MCP connects before the grace elapses
+        inj.onStatus(T, AgentStatus.IDLE);
+        assertEquals(List.of("task"), sent(), "a worker that connects within the grace is delivered to");
+    }
+
+    @Test
+    void dropClearsWorkerPresence() {
+        // CB-114 (finding #1): a vanished worker's readiness must be forgotten so a stale entry cannot
+        // linger past the worker's life (MemberPresence.forget had no caller before this).
+        List<String> forgotten = new ArrayList<>();
+        Injector inj = new Injector(new AgentControl(herdr), TurnListener.NOOP, _ -> true, forgotten::add);
+        inj.enqueue(T, "orphan");
+        inj.drop(T, new HerdrException("worker gone", "pane_not_found", null));
+        assertEquals(List.of(T), forgotten, "drop clears the gone worker's presence");
+    }
+
     @Test
     void pollerDeliversToAnIdleWorker() throws Exception {
         // End-to-end through the poller: idle worker → message delivered without manual onStatus.
@@ -165,12 +411,13 @@ class InjectorTest {
             poller.stop();
         }
         assertEquals(List.of("via-poller"), idle.calls.stream()
-                .filter(c -> c.method().equals("agent.send"))
+                .filter(c -> c.method().equals("agent.prompt"))
                 .map(c -> {
                     @SuppressWarnings("unchecked")
                     Map<String, Object> p = (Map<String, Object>) c.params();
                     return p.get("text").toString();
-                }).toList());
+                })
+                .toList());
     }
 
     @Test