Classify named AMQP recovery errors

Both connections were already named at newConnection() -- 'fleetd-reply-inbox' and
'fleetd-lead-mailbox' -- and neither name ever reached the log: 0 occurrences in
fleetd.out, and both connections logged under the same thread name
'[AMQP Connection 10.10.20.13:5672]'. So when one of the two died and never came
back, the log could not say which.

AmqpConnectionFailureLogger extends DefaultExceptionHandler and overrides only the
protected log(String, Throwable) sink that every handle* method calls virtually, so
the identity is added without changing any handler action.

My brief caused a defect here and the correction is the interesting part. I told the
worker the client 'currently uses ForgivingExceptionHandler', read off the log line
c.r.c.i.ForgivingExceptionHandler -- which names where the LOGGER FIELD is declared,
not the instance's class. javap on the jar shows ConnectionFactory's constructor does
'new DefaultExceptionHandler', and DefaultExceptionHandler extends StrictExceptionHandler
extends ForgivingExceptionHandler. The first version therefore extended the base and
silently dropped strict channel-closing on four listener/consumer paths. Now pinned by
a type assertion on both factories plus a behavioural test that handleConsumerException
still closes the channel once.

Verified on merge with a mutation the worker did not run: it mutated the parent class,
so I mutated the copied private-static isSocketClosedOrConnectionReset in the DANGEROUS
direction (always true => every failure logs at WARN and vanishes from the redeploy
gate's ERROR count). Caught: 'inbox failure line ==> expected: <ERROR> but was: <WARN>'.

Merged main in first; the auto-merge compiled. 1379 green, unpiped.

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "claude-bridge",
+  "description": "Tooling for orchestrating a fleet of delegated coding agents through the fleetd MCP gateway.",
+  "owner": {
+    "name": "LTMS"
+  },
+  "plugins": [
+    {
+      "name": "claude-bridge",
+      "source": "./plugin",
+      "description": "Make a project bridge-ready: mount the fleetd 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/agents/architect.md

@@ -0,0 +1,24 @@
+---
+name: architect
+description: Refine work into clear, independent units before implementation.
+---
+
+<!-- CB-617: The model comes from fleetd.yaml because the launch flag overrides model here on both backends. -->
+
+You are an architect in this fleet. You refine work before anyone builds it: scope,
+acceptance criteria, risks, and a unit split. You read the repo and write analysis.
+You never commit production code and never open a pull request.
+
+A design task is worked by two architects. Design alone first, then exchange and
+say plainly where you disagree. Do not concede just to agree.
+
+Do only the assigned scope. Note anything outside that scope in one line and do not
+investigate it further. Use `fleet_ask{question}` only when a decision belongs to
+the lead, such as an unclear requirement or two defensible fixes. Do not ask about
+something you can decide by reading more code.
+
+Report only work you actually did and the real output of checks you ran. Do not
+claim a result from a tool you could not use. The primary's IDE tools are not yours.
+A mounted forge tool may use a blocked credential and fail by design.
+
+The launcher provides the required bridge reply instructions for every member.

.claude/agents/dev.md

@@ -0,0 +1,29 @@
+---
+name: dev
+description: Implement one assigned unit, test it, and open a pull request.
+---
+
+<!-- CB-617: The model comes from fleetd.yaml because the launch flag overrides model here on both backends. -->
+
+You implement the one unit you were given and nothing else. Work in your assigned
+git worktree and branch. Never check out, rebase onto, or push to `main`. Confirm
+the worktree root and branch before you edit. Use only paths under that root.
+
+Do only the assigned scope. Note anything outside that scope in one line and do not
+investigate it further. Use `fleet_ask{question}` only when a decision belongs to
+the lead, such as an unclear requirement or two defensible fixes. Do not ask about
+something you can decide by reading more code.
+
+Implement the change and run the full required build in your worktree. Read the
+complete output and report its real result. Do not hide failures with a pipe. State
+only checks you actually ran. The primary's IDE tools are not yours. A mounted forge
+tool may use a blocked credential and fail by design.
+
+Stage only files you changed. Never use `git add -A` or `git add .`. Never commit
+`.mcp.json` or `wiki/`. Commit with a clear message, push your branch, and open your
+own pull request against `main`. Never merge.
+
+Your handoff must name the pull request or why it was not created, the branch, the
+files changed, the build result, and any caveat for review.
+
+The launcher provides the required bridge reply instructions for every member.

.claude/agents/reviewer.md

@@ -0,0 +1,34 @@
+---
+name: reviewer
+description: Review one assigned scope and report the most important real issue.
+---
+
+<!-- CB-617: The model comes from fleetd.yaml because the launch flag overrides model here on both backends. -->
+
+You review the diff you were given. Report bugs, risks, and missing tests. You do
+not change code.
+
+Read the whole assigned scope before judging it. Review only that scope. If you see
+something outside it, note it in one line and do not investigate it further. Do not
+run the build. The owner makes changes and runs checks.
+
+Use `fleet_ask{question}` only when a decision belongs to the lead, such as an
+unclear requirement or two defensible fixes. Do not ask about something you can
+decide by reading more code.
+
+Report the single most important real issue in this form:
+
+```
+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
+```
+
+If there is no real issue, report `NO ISSUE` and one line saying why. A clean review
+is valid. Do not invent an issue. Use high for a wrong result, data loss, security,
+or a hang or crash on a real path. Use medium for an edge-path bug or a correctness
+risk under load or concurrency. Use low for clarity, a latent foot-gun, or a smell
+with no current failure.
+
+The launcher provides the required bridge reply instructions for every member.

.claude/skills/fleets-status/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: fleets-status
+description: Report the status of every fleet that shares one LavinMQ instance. Use for local daemon health, broker-wide fleet presence, and cross-host lead coordination checks.
+---
+
+# Status of every fleet on the shared LavinMQ instance
+
+**The headline: always report what is missing.** This skill starts with the local fleet, then adds
+broker-wide facts when its read-only credential exists. A missing fleet must appear as `unknown` or
+`not reachable`, with the reason and the fix. Never leave it out.
+
+The known topology has one LavinMQ instance on `10.10.20.13` (`fleet01`). AMQP uses port `5672`,
+and the management API uses port `15672`. The Mac fleet owns vhost `/mac`. The fleet01 fleet owns
+vhost `/fleet01`.
+
+## 1. Protect credentials before any probe
+
+**Hard rule — never print `LAVINMQ_URI`.** It is an AMQP URI with its password inline. It only
+resolves in a login shell because `${SHARED_ENV}/tools/secrets.sh` supplies it. A non-login shell
+can make every broker probe look empty.
+
+- Never run `echo "$LAVINMQ_URI"`.
+- Never put `${LAVINMQ_URI:-something}` in output. That form expands to the secret value when set.
+- Parse the user, host, and password into shell or Python variables. Use them without printing them.
+- Prefer `resolves` or `does not resolve` over any part of the value.
+- Every command that can read `LAVINMQ_URI` must send all output through this redaction before it
+  reaches the report:
+
+```bash
+sed -E 's#://[^@]*@#://<redacted>@#g'
+```
+
+**The `g` flag is not optional.** Without it `sed` replaces only the first match on each line, so a
+line carrying two URIs leaks the second one. `scripts/redeploy-fleetd.sh --check` prints lines like
+that. Checked on 2026-08-27: without `g`, `amqp://u1:p1@h1/mac and http://u2:p2@h2:15672/api`
+redacts the first pair and prints `u2:p2` in the clear.
+
+Keep `pipefail` on when applying that filter. Otherwise the filter can hide a failed probe. Apply
+the same no-print rule to the management password below, even though it is not in an AMQP URI.
+
+## 2. Tier 1 — this fleet (always run)
+
+Start here even when the broker tier is blocked. Work from the local fleetd checkout.
+
+First run the read-only deployment check. It already checks the daemon process, deployed jar versus
+the checkout `HEAD`, launchd state, and whether each configured token resolves in a login shell.
+Do not copy those checks into new shell code. The script reads `LAVINMQ_URI`, so redact all output:
+
+```bash
+set -o pipefail
+scripts/redeploy-fleetd.sh --check 2>&1 \
+  | sed -E 's#://[^@]*@#://<redacted>@#g'
+git rev-parse HEAD
+```
+
+Treat jar drift as a top-level warning. A merge is not a deployment. State the running jar result
+as `matches HEAD`, `drift`, or `unknown`; do not turn an unclear timestamp into a match.
+
+Report the process identifier (PID) and uptime too:
+
+```bash
+PIDS="$(pgrep -f 'target/fleetd.jar' || true)"
+if [ -z "$PIDS" ]; then
+  printf '%s\n' 'fleetd: not running'
+else
+  for PID in $PIDS; do
+    ps -p "$PID" -o pid=,etime=,lstart=,command=
+  done
+fi
+```
+
+Read the full health response. Keep the HTTP status because `503` means fleetd is running but herdr
+is not reachable. Report both `herdr.version` and `herdr.protocol` when present:
+
+```bash
+curl -sS --max-time 5 -w '\nHTTP %{http_code}\n' http://127.0.0.1:8765/healthz
+```
+
+Call `fleet_whoami`, then call `fleet_list`. Preserve its sections in the report:
+
+- `leads`, including which row is this lead;
+- `members`, including state, role, profile, branch, and worktree when present;
+- every per-profile `capacity` row, including `maxLoad`, `live`, `free`, and quarantine facts;
+- the exact `healthCoverage` value.
+
+Do not describe an empty `members` list as an empty fleet. It says only that no members are spawned.
+Also do not hide a profile with `free: 0`; say whether load or credential quarantine caused it.
+
+Show only WARN, ERROR, and SEVERE lines after the last `fleetd listening` line. This anchor stops an
+old incident from looking current:
+
+```bash
+python3 - <<'PY'
+from pathlib import Path
+import re
+
+path = Path("fleetd/fleetd.out")
+if not path.exists():
+    print("cannot check current WARN/ERROR: fleetd/fleetd.out does not exist")
+else:
+    lines = path.read_text(errors="replace").splitlines()
+    starts = [i for i, line in enumerate(lines) if "fleetd listening" in line]
+    if not starts:
+        print("cannot anchor WARN/ERROR: no 'fleetd listening' line exists")
+    else:
+        current = lines[starts[-1]:]
+        alerts = [line for line in current if re.search(r"\b(?:WARN|ERROR|SEVERE)\b", line)]
+        print(f"current WARN/ERROR/SEVERE count: {len(alerts)}")
+        for line in alerts[-50:]:
+            print(line)
+PY
+```
+
+**What this tier cannot see:** it proves facts only about the Mac daemon at `127.0.0.1:8765`.
+It cannot show the fleet01 daemon, broker queue depth, or broker consumers. The fleet01 REST service
+at `10.10.20.13:8765` is not reachable from the Mac. Say this in the report rather than omitting
+fleet01.
+
+**But fleet01 IS reachable over SSH — checked 2026-08-28.** An older version of this line said SSH
+was denied. That is true only for the user `dai.ha`. The host alias `fleet01` maps to user `ltms`,
+and `ssh fleet01` works with key auth:
+
+```bash
+ssh -o BatchMode=yes -o ConnectTimeout=6 fleet01 'echo $(id -un)@$(hostname)'
+```
+
+So fleet01's daemon PID, uptime, jar and `/healthz` **can** be reported — over SSH, not over REST.
+Do that rather than writing `not reachable`. `ltms` also has passwordless sudo there.
+
+## 3. Tier 2 — the shared broker (run when management access exists)
+
+**This tier is blocked today.** The AMQP user in `LAVINMQ_URI` can connect on port `5672`, but gets
+HTTP `401` from the management API on port `15672`. An AMQP connection does not grant monitoring
+access.
+
+The operator must create a separate, read-only LavinMQ management user with the `monitoring` tag.
+It needs access to inspect both `/mac` and `/fleet01`. Store its values as
+`LAVINMQ_MANAGEMENT_USER` and `LAVINMQ_MANAGEMENT_PASSWORD` in
+`${SHARED_ENV}/tools/secrets.sh`. Do not reuse or print the AMQP URI. Full multi-fleet status stays
+blocked until this user exists.
+
+When both variables resolve, run this from a login shell. It calls `GET /api/overview`,
+`GET /api/vhosts`, `GET /api/queues`, and `GET /api/connections`. It prints selected status fields,
+but never the user, password, Authorization header, or AMQP URI:
+
+```bash
+zsh -lc 'python3 - "$@"' -- <<'PY'
+import base64
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+base = "http://10.10.20.13:15672"
+user = os.environ.get("LAVINMQ_MANAGEMENT_USER", "")
+password = os.environ.get("LAVINMQ_MANAGEMENT_PASSWORD", "")
+if not user or not password:
+    print("broker tier: BLOCKED — management credential does not resolve in a login shell")
+    sys.exit(0)
+
+token = base64.b64encode(f"{user}:{password}".encode()).decode()
+
+def get(path):
+    request = urllib.request.Request(
+        base + path,
+        headers={"Authorization": "Basic " + token, "Accept": "application/json"},
+    )
+    with urllib.request.urlopen(request, timeout=5) as response:
+        return json.load(response)
+
+try:
+    overview = get("/api/overview")
+    vhosts = get("/api/vhosts")
+    queues = get("/api/queues")
+    connections = get("/api/connections")
+except urllib.error.HTTPError as error:
+    print(f"broker tier: BLOCKED — management API returned HTTP {error.code}")
+    sys.exit(0)
+except Exception as error:
+    print(f"broker tier: BLOCKED — management API is not reachable: {type(error).__name__}")
+    sys.exit(0)
+
+fleet_names = {"/mac": "Mac fleet", "/fleet01": "fleet01 fleet"}
+print(json.dumps({
+    "overview": {
+        "lavinmq_version": overview.get("lavinmq_version"),
+        "rabbitmq_version": overview.get("rabbitmq_version"),
+        "queue_totals": overview.get("queue_totals", {}),
+        "object_totals": overview.get("object_totals", {}),
+    },
+    "fleets": [
+        {
+            "fleet": fleet_names.get(vhost.get("name"), "UNKNOWN FLEET"),
+            "vhost": vhost.get("name"),
+            "queues": [
+                {
+                    "name": queue.get("name"),
+                    "messages": queue.get("messages", 0),
+                    "messages_ready": queue.get("messages_ready", 0),
+                    "messages_unacknowledged": queue.get("messages_unacknowledged", 0),
+                    "consumers": queue.get("consumers", 0),
+                }
+                for queue in queues if queue.get("vhost") == vhost.get("name")
+            ],
+            "connections": [
+                {
+                    "name": connection.get("name"),
+                    "peer_host": connection.get("peer_host"),
+                    "state": connection.get("state"),
+                }
+                for connection in connections if connection.get("vhost") == vhost.get("name")
+            ],
+        }
+        for vhost in vhosts
+    ],
+}, indent=2, sort_keys=True))
+PY
+```
+
+Map `/mac` to the Mac fleet and `/fleet01` to the fleet01 fleet. Keep any other vhost in the
+report as `UNKNOWN FLEET`; do not drop it. For each vhost, total the ready, unacknowledged, and all
+messages. Report every queue's consumer count and each live connection.
+
+**A vhost with queues but zero consumers means that fleet's daemon is down while its durable state
+survives. Call this out as a top-level warning.** This is the main reason to use the management API
+instead of calling each remote daemon.
+
+**What this tier cannot see:** without the new `monitoring` credential it cannot enumerate any
+vhost, queue, depth, consumer, or connection. With the credential it still cannot report fleet01's
+daemon PID, uptime, jar revision, `/healthz`, herdr version, or member capacity. Those need reachable
+fleet01 REST or SSH access, which the Mac does not have today.
+
+## 4. Tier 3 — cross-fleet lead coordination
+
+Use the queue data from Tier 2. Select queues whose names match `lead.<coordId>.inbox`. Report each
+queue's vhost, depth, consumer count, and the `coordId` between the prefix and suffix.
+
+- A lead inbox with a consumer shows that a lead mailbox is live on that vhost.
+- A durable lead inbox with zero consumers shows saved coordination state, but no live receiver.
+- No lead inbox is not proof that coordination is disabled. The daemon may be down before declaring
+  its queue, or this account may not be allowed to see the vhost.
+
+This Mac fleet currently sets both `broker.uriEnv` and `coordinator.uriEnv` to the same variable,
+`LAVINMQ_URI`. Therefore its coordinator connects to `/mac`. Cross-host `fleet_send{coordId}` routes
+only when both leads share the same coordinator vhost. If the fleet01 lead uses `/fleet01` for its
+coordinator, the leads cannot see each other and the send will not route.
+
+**Open question:** the fleet01 coordinator vhost has not been checked. Surface this question in
+every report until a live `lead.<coordId>.inbox` consumer or fleet01's config proves the answer. Do
+not claim that fleet01 uses `/fleet01` just because its member queues do.
+
+Also compare these broker facts with the `leads` rows from local `fleet_list`. A missing remote lead
+is `not visible from this coordinator`, not `down`, unless the broker consumer facts prove it.
+
+**What this tier cannot see:** without Tier 2 management access it cannot list lead inboxes or their
+consumers. Even with that access, a stopped fleet01 daemon leaves only durable queue history. That
+history cannot prove which coordinator URI its current config would use after restart.
+
+## 5. Report all fleets
+
+Use one row per known or discovered fleet. Include blocked rows.
+
+| Fleet | Daemon | Deployment | Herdr | Members/capacity | Queues/consumers | Lead coordination | Cannot check |
+|---|---|---|---|---|---|---|---|
+| Mac (`/mac`) | PID + uptime | jar vs `HEAD` | health + version + protocol | `fleet_list` + `healthCoverage` | facts or blocked reason | inbox facts or open question | exact missing facts |
+| fleet01 (`/fleet01`) | reachable/down/unknown | value or `not reachable` | value or `not reachable` | value or `not reachable` | facts or blocked reason | inbox facts plus coordinator-vhost question | exact missing facts and fix |
+
+Add rows for unknown vhosts. End with three short sections: `Current warnings`, `Checks that were
+blocked`, and `Operator action`. Until the management user exists, `Operator action` must say:
+
+> Create a read-only LavinMQ management user with the `monitoring` tag and access to `/mac` and
+> `/fleet01`. Put its user and password in `${SHARED_ENV}/tools/secrets.sh` as
+> `LAVINMQ_MANAGEMENT_USER` and `LAVINMQ_MANAGEMENT_PASSWORD`.

.claude/skills/hunter/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: hunter
+description: Defect-hunt procedure for a fleetd worker — sweep an assigned package for real bugs and report several ranked findings without fixing anything. Load this when the lead asks you to hunt or audit a scope rather than review one diff. Do NOT load `reviewer` for this; the two want different output.
+---
+
+# Hunter worker — procedure
+
+The turn contract (one `fleet_reply`, `fleet_ask` for the lead's decisions, honest reporting,
+never merge) is in **`CLAUDE.md` → Bridge communication → Worker** and already applies.
+
+**This skill is not `reviewer`.** `reviewer` judges one diff and reports the *single* most
+important issue in about 90 words. A hunt sweeps a whole package and reports *several* findings
+in a long structured form. Loading both gives you two contradictory output contracts, and the
+usual result is a worker that writes a good report into its terminal and ends the turn without
+sending it. Load exactly one.
+
+## 0. Read this before you read code: how the report gets home
+
+Your terminal reaches nobody. The lead sees **only** the text inside your `fleet_reply` call.
+
+A long report is exactly the case where this goes wrong, so plan for it:
+
+- **Write the report into the `fleet_reply` argument itself.** Do not compose it in your terminal
+  and then summarise it into the call.
+- If the report is long, **send it anyway** — one `fleet_reply` with everything.
+- If you end the turn without replying, the bridge scrapes your pane instead. That scrape carries
+  at most the last 4000 characters, and on a hunt it usually captures the tail of the lead's own
+  brief rather than your findings. The lead then has nothing and has to ask you again.
+
+## 1. Change nothing
+
+A hunt is read-only. Do not edit a production file, do not "quickly fix" what you find, and do
+not run a formatter. You may run the build and tests to *check* a claim, and you should say so
+when you did.
+
+## 2. Read the whole scope first
+
+Read every file in the assigned package before you judge any of it. A defect that a caller
+elsewhere in the same package makes unreachable is not a defect, and you cannot know that from
+one file.
+
+Stay inside the scope. If a defect there depends on a class outside it, read that class to
+confirm — but the defect itself must live in the scope you were given.
+
+## 3. The bar — this matters more than the count
+
+**Name the path into the bad state.** Say which caller, in which state, reaches it. A defect on
+paper is not a reachable defect. If you cannot name that path, keep the finding but mark it
+`unproven` and say exactly what you could not check. Do not drop it, and do not dress it up.
+
+**Say which direction the harm goes.** Data loss, privilege escalation and silent wrong answers
+are worth reporting even when the window is narrow. A finding whose worst outcome is a worse log
+line is not worth a block.
+
+Two workers once ran the same scope: the one that applied the direction-of-harm filter found ten
+real defects, the one that did not found none. Fewer findings the lead can act on beat many the
+lead has to triage.
+
+## 4. Shapes that have produced real merged fixes here
+
+Read for these first:
+
+1. **A one-way gate.** A guard added after an incident closes only the direction that incident
+   came from. Do not only ask what closes the gate — ask **which states still open it**.
+2. **A value read once, then used later to authorise something destructive**, after something
+   else has had a chance to change it.
+3. **A failure downgraded to a value that looks like a legitimate result** — `-1`, `null`, an
+   empty list, `false` — which a caller then trusts.
+4. **A lock held for one half of a read-modify-write and not the other**, or two collections
+   updated under different locks.
+5. **A comment or javadoc stating an invariant the code no longer keeps.** Comments are
+   load-bearing in this repo; a stale one has already caused a bug.
+
+## 5. What you cannot check, and must not claim you did
+
+- `fleetd/fleetd.yaml` is gitignored and **absent from your worktree**. You cannot read it. If a
+  finding depends on live configuration, name the key and say you could not check it.
+- `.mcp.json`, `opencode.json` and `.autoenv` in your worktree are neutralised stubs, not the
+  repo's real files.
+- The `wiki/` submodule pointer is months old. Do not cite it.
+
+Reporting a fact you took from the lead's brief as something you measured yourself is a false
+report, even when the fact is correct. Say where each fact came from.
+
+## 6. The report — what goes in `fleet_reply`
+
+One block per finding, most severe first:
+
+```
+FINDING N — <one line>
+file:line
+Path in:        <which caller, in which state, reaches this>
+Direction:      <data loss | escalation | silent wrong answer | outage | ...>
+Window/trigger: <when it actually happens>
+Confidence:     <confirmed by reading | unproven — say what you could not check>
+Why nothing else catches it: <the guard or test you checked, and why it misses>
+```
+
+End with one line naming every file you read, so the lead knows the denominator.
+
+**Nothing clears the bar?** Reply `NO FINDINGS`, name the files you read, and say what you ruled
+out. A clean sweep is a valid result; an invented defect is worse than none.

.claude/skills/implementer/SKILL.md

@@ -1,24 +1,23 @@
 ---
 name: implementer
-description: Implementer-role playbook for a bridged worker — you are in an isolated git worktree on a dedicated branch; implement the assigned task, commit, push, open your own PR to main, and hand off the PR URL via bridge_reply. You never merge. Load this when you have been delegated an implementation task over bridged.
+description: Implementer-role procedure for a fleetd 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 fleetd.
 ---
 
-# Implementer worker
+# Implementer worker — procedure
 
-You are an **implementer** in the claude-bridge fleet. The lead delegated you one scoped task,
-and you are running in an **isolated git worktree on your own branch** — a full peer of the
-primary (same `CLAUDE.md`, skills, memory, MCP), differing only in the model behind you and the
-branch you sit on. Your job for this turn: **implement the task, then hand off a PR the lead can
-review and merge.** You do the work; the lead (or human) is the merge gate — you never merge.
+The turn contract (one `fleet_reply`, `fleet_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*.
 
-Delivery mechanics (how the task reached you, how your reply resolves the lead's blocked send)
-are in [`docs/MCP-Contract.md`](../../../docs/MCP-Contract.md); the worktree/PR model is in
-[`docs/Worker-Git-Workflow.md`](../../../docs/Worker-Git-Workflow.md). You only need the steps
-below.
+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 — a worktree on a dedicated branch
+## 1. Confirm where you are — then never leave
 
-Before touching anything, verify your ground truth:
+Before touching anything:
 
 ```bash
 git rev-parse --show-toplevel   # your worktree root — NOT the primary's main tree
@@ -26,49 +25,80 @@ 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** switch to `main`, never `git checkout main`,
-never rebase onto or push to `main` directly. The branch is your isolation — respect it.
+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.
 
-## 2. Implement the task
-
-- Implement exactly the scope the lead named. Keep changes focused; if you notice something out
-  of scope, note it in your reply rather than expanding the diff.
-- Match the surrounding code's style, naming, and idioms. Follow project `CLAUDE.md`.
-- **You cannot run the IDE MCP tools** (intellij-index / jetbrains are the primary's, not yours).
-  So **never claim a file is "IDE-clean" or "diagnostics-clean"** — you cannot verify that. State
-  only what you actually ran (e.g. `mvn`, a test) and its real output. A fabricated clean claim is
-  worse than an honest "I could not verify inspections here."
-- Run whatever build/test you can and **report the true result** — including failures.
-
-## 3. Commit — focused, and never the excluded files
+**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
-git add <the files you changed>
+test "$(git rev-parse --show-toplevel)" = "$PWD" || cd "$(git rev-parse --show-toplevel)"
+```
+
+**Never run `git stash` (or `git stash pop`/`apply`/`drop`).** Your worktree is isolated, but the
+stash is **not**: `refs/stash` is one stack shared by the primary's checkout and every other
+worker's worktree of this repo. Measured on 2026-09-04 — `git stash list` from a worker's worktree
+and from the primary's tree returned byte-identical output. So a `git stash` you run can be popped
+into someone else's tree, and a `git stash pop` you run can drop **another worker's** uncommitted
+edits on top of yours. This has already happened here: two workers were running in parallel and one
+of them had its in-progress edit silently overwritten by the other's stash.
+
+The branch is your isolation, so use it instead. To set work aside, commit it on your own branch
+(`git commit -m "wip: ..."`) and carry on; to try something and back out, use
+`git diff > /tmp/<your-branch>.patch` then `git checkout -- <file>`. Both stay inside your worktree.
+If you find a stash entry you did not create, leave it alone and say so in your report.
+
+## 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)/fleetd" && 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>"
 ```
 
-**Excluded from every commit, always:** `.mcp.json` (the primary's local, session-modified copy —
-present only for parity) and `wiki/` (a separate submodule). Stage files explicitly; do **not**
-`git add -A` / `git add .` blindly, or you risk staging them. If `.mcp.json` shows as modified,
-leave it — it is flagged `--skip-worktree` and is not yours to commit.
+`.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 your branch
+## 4. Push
 
 ```bash
 git push -u origin HEAD
 ```
 
-Push is over SSH as the same user — no extra credential needed. Push the branch as-is; do not
-force-push over anything you did not create.
+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`
 
-Open the PR 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** (that stays the lead/human gate).
+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"
+API="${GITEA_HOST%/}/api/v1/repos/fleet/fleetd/pulls"
 BRANCH="$(git branch --show-current)"
 curl -sS -X POST "$API" \
   -H "Authorization: token ${GITEA_TOKEN}" \
@@ -81,46 +111,40 @@ JSON
 )"
 ```
 
-The response JSON includes `"html_url"` — that is your PR URL. If the call fails (non-2xx), read
-the error body, fix the cause if it is yours (e.g. branch not pushed yet), and report the failure
-honestly in your reply rather than inventing a URL. If `GITEA_TOKEN` is unset, your profile was
-not granted PR-create — push the branch (step 4) and report the branch name so the lead opens the
-PR.
+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. Reply via `bridge_reply` — the PR is the handoff
+## 6. Hand off — what goes in `fleet_reply`
 
-End your turn with **exactly one** `bridge_reply`. That reply is the entire handoff — the lead
-cannot see your terminal. Include:
+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>
-files:   <the files you changed>
-tests:   <what you ran and its REAL result — or "not run: <why>">
+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>
 ```
 
-Then stop. **Do not merge. Do not touch `.mcp.json` or `wiki/`.** One reply closes the turn.
-
 ```mermaid
 sequenceDiagram
     autonumber
     participant L as Lead
-    participant B as bridged
     participant I as Implementer (you)
     participant G as git / gitea
 
-    L->>B: bridge_send(task) — blocks
-    B-->>I: your assignment (in a worktree on your branch)
-    I->>I: implement + build/test here
+    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->>B: bridge_reply(PR url, branch, files, tests)
-    B-->>L: { outcome:"reply", text }
-    Note over L,G: lead reviews the PR, merges on green — you never merge
+    I->>L: fleet_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. The
-lead is the merge gate.*
+*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,180 @@
+---
+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": {
+    "fleetd":  { "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 | one central store, sourced by the login shell |
+| a spawner (bridge, CI, IDE) | `{env:…}`, with the spawner injecting the variable |
+
+**For the human case, keep every credential in one file the login shell sources.** Here that file
+is `${SHARED_ENV}/tools/secrets.sh`, sourced from `${SHARED_ENV}/.ltms`, kept at mode 600 and never
+committed. `opencode.json` then names variables and holds no values:
+
+```json
+"headers": { "Authorization": "Bearer {env:CONTEXT7_TOKEN}" }
+```
+
+Both routes end at the same syntax, and that is the point. The file does not change when a human
+launches opencode instead of the bridge.
+
+**`{file:…}` also works, and this project moved away from it.** Opencode resolves a relative
+`{file:}` path against the project root, so a gitignored `.secrets/` beside `opencode.json` needs no
+shell setup at all. It did not fail; the problem is that it makes a second copy of the token. The
+same secret then lives in two places, and the copy you forget is the one that leaks or goes stale.
+One store with many references is easier to rotate and to audit.
+
+**One catch survives either choice, so state it out loud:** what a human's shell exports does not
+reach a spawned peer, and neither does a gitignored `.secrets/` — a git worktree receives tracked
+files only. Spawned peers must 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. In this repo the bridge goes further: it neutralizes a worktree's
+`opencode.json`, so a member cannot inherit the primary's credentials by accident.
+
+## 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

@@ -1,69 +1,44 @@
 ---
 name: reviewer
-description: Reviewer-role playbook for a bridged worker — read the assigned scope, find the real issues, ask the lead via bridge_ask when a decision is genuinely theirs, and report the finding via bridge_reply. Load this when you have been delegated a code review over bridged.
+description: Reviewer-role procedure for a fleetd 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 fleetd.
 ---
 
-# Reviewer worker
+# Reviewer worker — procedure
 
-You are a **reviewer** in the claude-bridge fleet. The lead delegated you one scoped review
-over `bridged`, and your whole job is **this single turn**: examine the scope it named, and
-report back. You are not the owner of the code and you do not merge anything — you surface
-what the owner needs to know, then hand the turn back.
+The turn contract (one `fleet_reply`, `fleet_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.
 
-Delivery mechanics (how the task reached you, how your reply resolves the lead's blocked
-send) are in [`docs/MCP-Contract.md`](../../../docs/MCP-Contract.md); you only need the three
-rules below.
+**Wrong skill for a sweep.** This one reviews *one* diff or scope and reports the *single* most
+important issue. If the lead asked you to hunt or audit a whole package for several defects, load
+`hunter` instead and ignore this file — the two want different output, and following both is how a
+worker ends its turn with a good report that never gets sent.
 
 ## 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 only part of the scope and guessing the rest is the most common way a
-reviewer worker is wrong.
+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 your lane
+## 2. Stay in the scope
 
-- Review **only** the assigned scope. If you notice something elsewhere, mention it in one
-  line — do **not** go hunt it. Wandering is how two workers end up reporting the same thing
-  and neither covers what it was given.
-- Do **not** edit files, run the build, or spawn other workers. You review; the owner acts.
-- You never set `ANTHROPIC_BASE_URL` and never touch herdr — you are a Claude Code process,
-  not part of the transport.
+- 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. When the decision is the lead's — ask, don't guess
+## 3. Reach for `fleet_ask` only for a genuine fork
 
-Some things you cannot resolve from the code: an ambiguous requirement, a missing acceptance
-criterion, "is this behavior intended or a bug?", or a choice between two defensible fixes.
-Guessing there produces a confident-but-wrong finding. Instead **pause and ask the lead** with
-`bridge_ask` — a single crisp question. The call blocks; when the lead answers you **resume
-the same turn** with the answer and finish. Ask only when the answer changes your finding;
-don't narrate options you could decide yourself.
+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.
 
-```mermaid
-sequenceDiagram
-    participant L as Lead
-    participant B as bridged
-    participant R as Reviewer (you)
+## 4. The finding — what goes in `fleet_reply`
 
-    L->>B: bridge_send(review scope) — blocks
-    B-->>R: your assignment
-    R->>R: read the full scope
-    opt a decision only the lead can make
-        R->>B: bridge_ask("intended, or a bug?") — you block
-        B-->>L: { outcome:"question", turn_id }
-        L->>B: bridge_send(answer, turn_id)
-        B-->>R: { answer } — you resume the SAME turn
-    end
-    R->>B: bridge_reply(structured finding) — ends your turn
-    B-->>L: { outcome:"reply", text }
-```
-
-*The review turn, with the optional `bridge_ask` detour when the call is the lead's to make.*
-
-## 4. Report with `bridge_reply` — one structured finding
-
-End your turn with **exactly one** `bridge_reply`. Report the **single most important** real
-issue in the scope, in these four lines, under ~90 words:
+Report the **single most important** real issue in the scope, in these four lines, under
+~90 words:
 
 ```
 1. <path>:<line>
@@ -72,13 +47,10 @@ issue in the scope, in these four lines, under ~90 words:
 4. severity: high | medium | low
 ```
 
-- Found nothing real after reading? Reply `NO ISSUE` and one line saying why — a clean review
-  is a valid result, and a fabricated issue is worse than none.
+- **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 to where it goes wrong, you haven't found it yet.
-
-One reply closes the turn. If you asked mid-turn, the answer you got is already folded into
-this finding — you do not ask again after replying.
+- 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,105 @@
+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; fleetd 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: fleetd
+        # 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: fleetd
+        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 fleetd/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
+    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: fleetd
+        run: mvn -B -Pcontract test -Dtest=AmqpReplyInboxContractTest
+
+      - name: Failing test output
+        if: failure()
+        working-directory: fleetd
+        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,21 @@
+# No secret belongs in this repo any more: every credential lives in one shell-level store
+# (${SHARED_ENV}/tools/secrets.sh), and opencode.json reads it as {env:...}. This line stays as a
+# backstop, so a workspace-scoped copy that someone re-creates by habit still cannot be committed.
+.secrets/
+
+# Settings backups inherit the env block — and secrets with it.
+.claude/settings.local.json.bak*
+
+# The default profile parityOverlay copies these primary→worktree, so they appear in EVERY worker
+# worktree. Two reasons they must be ignored. They hold environment values, which is reason enough.
+# And since CB-576 a release preserves any worktree that `git status --porcelain` calls dirty —
+# untracked files included, deliberately. An untracked overlay file would therefore make every
+# COMPLETED release preserve its worktree, and worktrees would pile up with no error to notice.
+.env
+.envrc
+
+# Daemon runtime artefacts. fleetd appends its log wherever it is launched from, so both the
+# repo root and fleetd/ collect one; neither belongs in git.
+fleetd.out
+fleetd/fleetd.out
+logs/

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "wiki"]
 	path = wiki
-	url = ssh://git@git.ltms.dev:2224/lms/claude-bridge.wiki.git
+	url = ssh://git@git.ltms.dev:2224/fleet/fleetd.wiki.git

.opencode/agent/architect.md

@@ -0,0 +1,24 @@
+---
+description: Refine work into clear, independent units before implementation.
+mode: primary
+---
+
+<!-- CB-617: The model comes from fleetd.yaml because the launch flag overrides model here on both backends. -->
+
+You are an architect in this fleet. You refine work before anyone builds it: scope,
+acceptance criteria, risks, and a unit split. You read the repo and write analysis.
+You never commit production code and never open a pull request.
+
+A design task is worked by two architects. Design alone first, then exchange and
+say plainly where you disagree. Do not concede just to agree.
+
+Do only the assigned scope. Note anything outside that scope in one line and do not
+investigate it further. Use `fleet_ask{question}` only when a decision belongs to
+the lead, such as an unclear requirement or two defensible fixes. Do not ask about
+something you can decide by reading more code.
+
+Report only work you actually did and the real output of checks you ran. Do not
+claim a result from a tool you could not use. The primary's IDE tools are not yours.
+A mounted forge tool may use a blocked credential and fail by design.
+
+The launcher provides the required bridge reply instructions for every member.

.opencode/agent/dev.md

@@ -0,0 +1,29 @@
+---
+description: Implement one assigned unit, test it, and open a pull request.
+mode: primary
+---
+
+<!-- CB-617: The model comes from fleetd.yaml because the launch flag overrides model here on both backends. -->
+
+You implement the one unit you were given and nothing else. Work in your assigned
+git worktree and branch. Never check out, rebase onto, or push to `main`. Confirm
+the worktree root and branch before you edit. Use only paths under that root.
+
+Do only the assigned scope. Note anything outside that scope in one line and do not
+investigate it further. Use `fleet_ask{question}` only when a decision belongs to
+the lead, such as an unclear requirement or two defensible fixes. Do not ask about
+something you can decide by reading more code.
+
+Implement the change and run the full required build in your worktree. Read the
+complete output and report its real result. Do not hide failures with a pipe. State
+only checks you actually ran. The primary's IDE tools are not yours. A mounted forge
+tool may use a blocked credential and fail by design.
+
+Stage only files you changed. Never use `git add -A` or `git add .`. Never commit
+`.mcp.json` or `wiki/`. Commit with a clear message, push your branch, and open your
+own pull request against `main`. Never merge.
+
+Your handoff must name the pull request or why it was not created, the branch, the
+files changed, the build result, and any caveat for review.
+
+The launcher provides the required bridge reply instructions for every member.

.opencode/agent/reviewer.md

@@ -0,0 +1,34 @@
+---
+description: Review one assigned scope and report the most important real issue.
+mode: primary
+---
+
+<!-- CB-617: The model comes from fleetd.yaml because the launch flag overrides model here on both backends. -->
+
+You review the diff you were given. Report bugs, risks, and missing tests. You do
+not change code.
+
+Read the whole assigned scope before judging it. Review only that scope. If you see
+something outside it, note it in one line and do not investigate it further. Do not
+run the build. The owner makes changes and runs checks.
+
+Use `fleet_ask{question}` only when a decision belongs to the lead, such as an
+unclear requirement or two defensible fixes. Do not ask about something you can
+decide by reading more code.
+
+Report the single most important real issue in this form:
+
+```
+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
+```
+
+If there is no real issue, report `NO ISSUE` and one line saying why. A clean review
+is valid. Do not invent an issue. Use high for a wrong result, data loss, security,
+or a hang or crash on a real path. Use medium for an edge-path bug or a correctness
+risk under load or concurrency. Use low for clarity, a latent foot-gun, or a smell
+with no current failure.
+
+The launcher provides the required bridge reply instructions for every member.

CLAUDE.md

@@ -1,13 +1,349 @@
 # 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/fleet/fleetd/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 `fleet_*` MCP tools are mounted in this session, this section does not apply — skip it.
+
+`fleetd` is the **sole communication gateway** between agents here. The orchestrating session (the
+**primary**) and every delegated peer (a **member**) mount the *same* MCP server and talk only
+through its `fleet_*` tools. No session addresses a peer, a broker, or the network directly.
+
+### Which role am I? — settle this before acting
+
+**Every role reads this file.** A member runs in a git worktree of this same repo, so it inherits
+this `CLAUDE.md` verbatim, and every rule below is role-conditional.
+
+**Call `fleet_whoami`.** It returns `primary`, `worker`, or `architect`, resolved by the daemon from
+your connection — unforgeable, and the same resolution its authorization gate uses. A worker also
+carries its `sessionId`, `profile`, `worktree` and `branch`; an architect carries the slot name it
+was bound to. 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 a spawned member in the
+claude-bridge fleet"*) ⇒ **spawned member**; fleet tools prefixed `mcp__fleet__*` ⇒ **spawned
+member** (the launcher fixes that mount name; a primary's mount is named by whoever wrote its
+`.mcp.json`, so it varies — and a member spawned before CB-632 still says `mcp__bridge__*`); `ANTHROPIC_BASE_URL` set ⇒ **spawned member** (Claude-model members run
+on a clean env, so its *absence* proves nothing). None of these separate a worker from an architect —
+only `fleet_whoami` does. **Still unsure ⇒ act as a worker**, the most restricted member role. The
+two mistakes are not symmetric: a primary acting as a worker is refused by the authorization gate —
+loud and self-correcting — while a member acting as the primary ends its turn with no `fleet_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 member 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 `fleet_*` 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/drain are lead-only; **send is lead or architect**;
+   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` or
+   `done`. A spawned member must **also** have mounted the bridge MCP: until it has, it is not
+   deliverable, and a send waits on that gate for ~60s and then fails without ever reaching its pane.
+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 `fleet_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** — `fleet_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** — `fleet_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** — `fleet_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** — `fleet_poll{ticket}` → `fleet_ack{target, msgId}`. Answer a worker's `fleet_ask`
+   with `fleet_send{turnId, content}` — **not** `sessionId`. A worker gone quiet is diagnosed with
+   `fleet_status`, never by reading its terminal; it also reports an open question and the `turnId`
+   that answers it. **A worker's ask waits ~55 seconds, and no nudge makes that longer** — so never
+   brief a worker to "ask me". Decide before you delegate, or give it an explicit default.
+6. **Verify yourself.** Re-run the build and the checks. A worker cannot run your IDE tooling, any
+   forge tools it appears to have hold a blocked credential and fail, 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 `fleet_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` + `fleet_poll` for anything non-trivial: a blocking `fleet_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 | `fleet_whoami` |
+| See backends available | `fleet_profiles` |
+| Start a member | `fleet_spawn{role?, profile?, cwd?, worktree?, ticket?, sessionName?, resumeSessionId?}` → `sessionId` + `paneId` |
+| See the fleet | `fleet_list` → `leads` (your peers) + `members` (each carries `agentSessionId` when its backend knows one) · one peer's state: `fleet_status{sessionId}` |
+| Delegate (blocking) | `fleet_send{sessionId, content}` |
+| Delegate (long task) | `fleet_send{sessionId, content, wait:false}` → ticket → `fleet_poll{ticket}` |
+| Answer a member's `fleet_ask` | `fleet_send{turnId, content}` — **not** `sessionId` |
+| Message a **peer lead** on this host | `fleet_send{sessionId: <their terminal>, content}` — `fleet_list` → `leads` reports it. Coordination only, **never** a task |
+| Message a **peer lead** on another daemon or host | `fleet_send{coordId: <their coord-id>, content}` — needs a `coordinator:` block; your own coord-id is in `fleet_list`. Coordination only, **never** a task |
+| Answer a peer lead that messaged you | `fleet_reply{content}` — the one case a lead replies |
+| Collect a held reply | `fleet_poll{target}` · then `fleet_ack{target, msgId}` |
+| Tear down a member | `fleet_stop{paneId}` |
+
+### Lead ↔ lead — coordinate, never delegate
+
+`fleet_list` returns `leads` alongside `members`; your own row carries `self: true`. Every other row
+is a peer — an orchestrator with its own context, its own members, and its own judgment. An empty
+`members` array means no members are spawned; it says nothing about peers.
+
+**A lead never assigns a task to another lead.** Work goes to members — only ever downward, never
+sideways. Sending a peer a brief with acceptance criteria is a category error: a brief is a member's
+artefact, and a peer is not yours to task. If a unit needs doing and it falls in your area, spawn a
+member 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 `fleet_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.
+
+### Member (worker or architect) — 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. **`fleet_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 `fleet_reply{content}`**, carrying your complete answer. This is
+   the whole handoff. No `fleet_reply` ⇒ the sender gets nothing and the exchange stalls.
+   Do **not** lean on the completion fallback to carry your answer for you: when you end a turn
+   without replying, the bridge scrapes your pane, and it can return only the last 4000 characters.
+   A clipped scrape is marked as partial, but the missing text is gone — your report reaches the
+   lead with its end cut off.
+5. **Report honestly.** State only what you actually ran and its real output, including failures,
+   and never claim the result of a check you had no way to run. **Measure your own tools; do not
+   assume them.** What you mount depends on your backend: an opencode member gets the bridge and
+   nothing else, while a Claude Code member also inherits the operator's user-scope MCP servers,
+   which the bridge never chose for you. Two rules follow. The primary's IDE tooling is still not
+   yours, whatever you see. And **a mounted tool is not a working tool** — the forge server you may
+   find there holds a deliberately blocked credential and fails every call, by design.
+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 `fleet_reply`* | every spawned member, at launch, every peer kind — never a lead |
+| **this section** | protocol + orchestration policy | primary **and** every member that reads the repo — tracked in git, so worktrees inherit it |
+| role agent definition files | role contract and per-job procedure | a member whose launcher binds its role to the matching file in its worktree |
+| role playbook skills | per-job procedure (commit/PR recipe, finding format) | a member 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. A member without a
+repo checkout still gets the launcher's reply charter, which is why that one rule stays there.
+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 `fleetd`, its MCP mount is `http://127.0.0.1:8765/mcp`,
+  and the code behind the rules above is `mcp/FleetMcp` (tools), `auth/Authz` (the role table),
+  `mcp/ConnectionIdentity` (connection→role), and `worker/*Launcher` (`REPLY_CHARTER`).
+- **`fleet_profiles`/`fleet_list` report two separate outage states, and they are not the same
+  thing.** *Quarantined* (CB-578) means the backend told us it is out of capacity — a long,
+  1800s-default cooldown. *Cooling off* (fleetd #201/#227) means a profile's credential threw two
+  distinct backend errors (a non-exhaustion failure such as an HTTP 5xx) within 60 seconds — a
+  short, fixed 60s cooldown, not configurable per profile. Each check runs independently, so a
+  profile can show both at once. In the JSON: a cooling profile carries `credentialId` and
+  `coolingOffForSeconds`; a quarantined profile carries `quarantinedForSeconds`; a profile hit by
+  both carries all three fields, and either state alone already sets that profile's `free` to `0`.
+  A `fleet_spawn` naming a cooling-off profile is refused before it ever reaches the backend
+  adapter, with a message naming the credential and the remaining seconds ("cooling off after
+  repeated backend errors") — distinct wording from a quarantine refusal, so don't conflate the
+  two when reading a spawn failure.
+- **Skills available to delegate:** `implementer` (worktree → commit → push → own PR),
+  `reviewer` (one diff → one structured finding) and `hunter` (sweep a package → several ranked
+  findings, change nothing). Name exactly one in every delegation. **`reviewer` and `hunter` are
+  not interchangeable** — `reviewer` caps the answer at one finding in about 90 words, so naming
+  it for a multi-finding sweep hands the worker two contradictory output contracts. That has
+  already cost three workers' turns: each wrote a good report to its terminal and ended the turn
+  with no `fleet_reply`, and the scrape returned the tail of the brief instead.
+- **Primary-side skills** (not delegation playbooks — a worker cannot use them):
+  `port-to-opencode` (make an OpenCode session a participant in this workspace) and
+  `fleets-status` (report every fleet that shares one LavinMQ instance).
+- **Never commit** `.mcp.json` (the primary's local copy, flagged `--skip-worktree`) or `wiki/`
+  (a submodule with its own remote).
+- **A provisioned worktree neutralizes `.mcp.json`, `opencode.json` and `.autoenv`** — the repo's
+  committed copies would otherwise mount the primary's IDE and forge servers (fleetd #134). The
+  worktree's copy of each is a stub, **not** the repo's real file, so a worker that reads one and
+  reports what it found is reporting on the stub. The daemon logs a per-spawn summary, but the
+  worker cannot see that log. From inside its own worktree a worker — or a lead debugging one —
+  reads the list with `git config --worktree --get-all fleet.neutralizedConfig`, and the
+  consequence with `git config --worktree --get fleet.neutralizedConfigNote`. Never brief a worker
+  to edit one of these files: the edit cannot be committed, and it will not tell you so.
+- **Flows and the error model** — rendezvous, `fleet_ask`, detached delivery, the turn-done
+  fallback and status gating — are diagrammed in `docs/MCP-Contract.md`. That page is now flows
+  only: its pre-build tool catalogue, parameter tables and REST paths were deleted rather than
+  corrected, because a hand-maintained second copy of the tool surface is what drifted for a month
+  while this line pointed every session at it (CB-609 / #114). **The live MCP schema is the tool
+  reference**, with the intent→tool table above as the short form. `McpContractDocTest` fails if
+  that page names a `fleet_*` tool the server does not register. The flows are kept out of this
+  file because this file loads into every session's context.
+
+### Redeploying the daemon — the lead may do this (primary only)
+
+**A merge is not a deployment.** The running `fleetd` holds the jar it was started with, so a
+feature merged to `main` does nothing until the daemon is rebuilt and restarted. Saying "shipped"
+about code the live daemon has never loaded is a false report. The lead **may and should** redeploy
+rather than hand the job back to the operator.
+
+Workers must never do this. A worker has no business restarting the daemon it is talking through,
+and stopping it kills the worker's own channel mid-turn.
+
+**Use the script — do not hand-roll the steps.**
+
+```bash
+scripts/redeploy-fleetd.sh --check   # report state, change nothing
+scripts/redeploy-fleetd.sh           # build, confirm drain, restart, verify
+scripts/redeploy-fleetd.sh --yes     # skip the drain prompt (fleet already checked)
+```
+
+It builds before it stops anything, so a failed build never leaves the fleet down; it waits for the
+old process to exit rather than assuming; it polls `/healthz`; and it anchors its log checks to a
+line marker taken before the restart, so old errors cannot be misread as new ones. Run `--check`
+first — it is read-only and reports whether the forge token resolves, which nothing else tells you.
+
+The script encodes the five things below, each of which has gone wrong here before. Read them anyway:
+if the script is unavailable or a step fails, this is what it was protecting you from.
+
+1. **Login shell, or workers silently lose their forge token.** The daemon inherits
+   `WORKER_GITEA_TOKEN` from the shell that starts it, and that comes from
+   `${SHARED_ENV}/tools/secrets.sh`. Start it from a non-login shell and the variable is empty, the
+   daemon starts fine, and the failure appears much later as workers that cannot open a PR. Nothing
+   logs this at startup — the script's `--check` is the only thing that reports it, and it checks
+   whether the name resolves without ever printing the value.
+2. **Drain live members first.** `fleet_list`, then `fleet_stop` each member, and collect anything
+   you still want with `fleet_poll` before you kill anything. A restart drops in-flight tickets and
+   rendezvous, and a member's report is not recoverable once its ticket is gone.
+3. **A restart is the only way deferred config keys take effect.** That is usually the reason to do
+   it. The startup log names which keys it accepted and which it deferred — read those lines rather
+   than assuming.
+4. **Re-check identity afterwards.** Call `fleet_whoami` and confirm it still answers `primary`. The
+   lead is found by its tab label (`fleet.leaders.*.tab`), and a lead whose tab no longer matches is
+   demoted to worker, which refuses every orchestration call.
+5. **Prove the new jar is the one running.** Confirm a *fresh* `fleetd listening` line at the end of
+   `fleetd/fleetd.out`, dated after the restart. An old daemon that never died looks identical from
+   the outside.
+
+**Permission.** A `CLAUDE.md` rule grants intent, not tool permission — the command classifier
+refuses a bare `kill` on the daemon whatever this file says. The script is the seam that fixes that:
+it is one auditable command, so the operator allow-lists it once instead of approving a stop and a
+start every time. The rule lives in the operator's Claude Code settings:
+
+```json
+{ "permissions": { "allow": ["Bash(scripts/redeploy-fleetd.sh:*)"] } }
+```
+
+Granted by the operator on 2026-08-15. If a call is still refused, do **not** route around it by
+running the stop and start as separate commands — that is exactly the approval the script replaced.
+Say what you were going to run and why, and let the operator decide.
+
+### 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 `fleet_*` 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 `fleet_whoami` paragraph and the fallback ladder |
+| `REPLY_CHARTER`, or a launcher's mount/flags | the fallback ladder (`mcp__fleet__*`), 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 `fleetd.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/fleet/fleetd/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:
+module is **`fleetd`**. Always pass these to IDE MCP tools:
 
-- `project_path` = `/Users/dai.ha/LTMS/claude-bridge/bridged`
-- IDE paths are relative to `bridged/` (e.g. `src/main/java/dev/ltms/bridged/...`)
+- `project_path` = `/Users/dai.ha/LTMS/claude-bridge/fleetd`
+- IDE paths are relative to `fleetd/` (e.g. `src/main/java/dev/ltms/fleet/...`)
 
 ### After editing any file — mandatory
 
@@ -21,7 +357,7 @@ module is **`bridged`**. Always pass these to IDE MCP tools:
    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
+`jetbrains get_file_problems{filePath: "fleetd/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

README.md

@@ -9,32 +9,33 @@ Sibling of [`crush-bridge`](https://git.ltms.dev/systems/vms) (which drives a he
 process*, so it inherits `CLAUDE.md`, hooks, skills, and MCP — just pointed at a
 cheaper/local model.
 
-## Leading approach — herdr-centric message server (`bridged`)
+## Leading approach — herdr-centric message server (`fleetd`)
 
-A small always-on message server, **`bridged`**, controls
+A small always-on message server, **`fleetd`**, controls
 [herdr](https://herdr.dev) (an agent multiplexer) over its Unix-socket API and exposes a
 clean 2-way messaging API as an **MCP server that both the primary and the workers mount** —
 one unified Claude setup and the **sole communication gateway** (REST/SSE stays for non-Claude
-clients; any broker is `bridged`-internal, below the gateway).
-herdr owns the PTYs, multiplexing, persistence, and **agent-status events**; `bridged` owns
+clients; any broker is `fleetd`-internal, below the gateway).
+herdr owns the PTYs, multiplexing, persistence, and **agent-status events**; `fleetd` owns
 policy (subscription boundary, session lifecycle, status-gated delivery) and the client
-contract. The worker `claude` launches with `ANTHROPIC_BASE_URL=https://ollama.ltms.dev` + a
-bearer token; the primary Opus stays env-clean and calls `bridged`'s MCP tools.
+contract. A Claude member launches with `ANTHROPIC_BASE_URL` pointed at the gateway,
+`https://llm.ltms.dev/anthropic`, plus a bearer token; the lead stays env-clean and calls
+`fleetd`'s MCP tools. See the wiki's **[13 User Guide](wiki/13-User-Guide.md)** to run it.
 
 ```mermaid
 flowchart LR
     OPUS["Opus — primary<br/>(Claude Code, env CLEAN)<br/>MCP client"]
-    subgraph BD["bridged — standalone daemon (not a claude process)"]
+    subgraph BD["fleetd — standalone daemon (not a claude process)"]
         SRV["SERVER face<br/>MCP · REST/SSE · policy"]
         CLI["CLIENT face<br/>status-gated injector · herdr socket"]
         SRV --> CLI
     end
     HERDR["herdr<br/>panes · agent-status"]
     W["worker claude pane<br/>ANTHROPIC_BASE_URL set<br/>MCP client"]
-    M["ollama.ltms.dev<br/>(worker model)"]
+    M["llm.ltms.dev<br/>(the one gateway)"]
 
-    OPUS -->|"MCP bridge_send (blocks)"| SRV
-    W -.->|"MCP bridge_reply"| SRV
+    OPUS -->|"MCP fleet_send (blocks)"| SRV
+    W -.->|"MCP fleet_reply"| SRV
     CLI -->|"Unix socket<br/>send_text · events.subscribe"| HERDR
     HERDR -->|"drives PTY"| W
     W -->|"inference"| M
@@ -46,24 +47,26 @@ flowchart LR
 ```
 
 - **Subscription boundary:** the *primary* never sets `ANTHROPIC_BASE_URL` (stays on
-  Pro/Max). Only the *secondary* process is off-subscription — and `bridged` itself is a
+  Pro/Max). Only the *secondary* process is off-subscription — and `fleetd` itself is a
   plain daemon (no Anthropic quota), so it may poll/subscribe freely.
-- **One gateway (unified MCP setup):** `bridged` is the **sole communication path** for every
+- **One gateway (unified MCP setup):** `fleetd` 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_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`);
-  `bridged` holds it open until the worker calls `bridge_reply` or its turn hits
+   line, same on both) and talk over MCP tools — `fleet_send` / `fleet_reply` /
+   `fleet_status` (with `fleet_ask` planned for the blocked-worker path). **No Claude session
+   ever addresses a broker, a peer, or the network
+   directly**; any queue is `fleetd`-internal. MCP tool I/O never sets `ANTHROPIC_BASE_URL`, so
+   mounting the bridge is subscription-safe by construction.
+   **Tool naming:** the tools are `fleet_*` (renamed from `bridge_*` in CB-622). The old
+   `bridge_*` names were removed in CB-634 — only `fleet_*` answers now.
+- **How the primary consumes a reply:** a single **blocking MCP call** (`fleet_send`);
+  `fleetd` holds it open until the worker calls `fleet_reply` or its turn hits
   `agent_status=done`, then returns the reply as the tool result. No cross-turn busy-poll, so
   no quota burn. SSE is an optional side-channel for humans/dashboards watching status.
-- **Worker → primary** rides `bridged`'s **MCP rendezvous** — the reply resolves the primary's
-  blocking call (or, for detached work, `bridged` **injects the primary's idle pane** when it's
+- **Worker → primary** rides `fleetd`'s **MCP rendezvous** — the reply resolves the primary's
+  blocking call (or, for detached work, `fleetd` **injects the primary's idle pane** when it's
   ready), so *no keystroke-into-primary and no broker are involved, even single-host*. The one
   exception: a split-host primary that isn't a herdr pane wakes via its own `Stop`-hook, which
-  polls **`bridged`** (never a broker). See the wiki for the two topologies.
+  polls **`fleetd`** (never a broker). See the wiki for the two topologies.
 - **Different model per process** sidesteps Claude Code's lack of per-subagent provider
   routing — the worker isn't a subagent, it's its own configured process.
 - **AgentAPI** ([`coder/agentapi`](https://github.com/coder/agentapi)) is retained only as a
@@ -72,11 +75,11 @@ flowchart LR
 
 ## Docs
 
-Full design, setup, and operations live in the **[wiki](https://git.ltms.dev/lms/claude-bridge/wiki)**,
+Full design, setup, and operations live in the **[wiki](https://git.ltms.dev/fleet/fleetd/wiki)**,
 vendored here as a submodule under [`wiki/`](./wiki):
 
 ```bash
-git clone --recurse-submodules ssh://git@git.ltms.dev:2224/lms/claude-bridge.git
+git clone --recurse-submodules ssh://git@git.ltms.dev:2224/fleet/fleetd.git
 # or, after a plain clone:
 git submodule update --init
 ```
@@ -86,19 +89,20 @@ Gitea wiki.
 
 ## Status
 
-🟢 **Implemented & dogfooded** — the herdr-centric **`bridged`** message server is built and in
+🟢 **Implemented & dogfooded** — the herdr-centric **`fleetd`** 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 · 105 tests green — unit/acceptance + live-herdr contract tests):
+**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
+  blocking `fleet_send` with reply rendezvous; MCP server as a thin adapter over the REST core.
+- **MCP tools** — `fleet_send` / `fleet_reply` / `fleet_status` (messaging) and `fleet_spawn`
+  / `fleet_list` / `fleet_stop` / `fleet_profiles` / `fleet_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
@@ -106,7 +110,17 @@ fallback injector.
 - **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** — `fleet_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)) — structured envelope schema, `bridge_ask`
-(blocked-worker path), session lifecycle / recycle / `idle_ttl`, split-host, and hardening
-(auth/TLS, `/metrics`, CI, systemd).
+**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

@@ -1,11 +0,0 @@
-# Build output
-target/
-dependency-reduced-pom.xml
-
-# Local runtime config (copy from bridged.example.yaml)
-bridged.yaml
-
-# Editor / OS
-*.iml
-.idea/
-.DS_Store

bridged/bridged.example.yaml

@@ -1,65 +0,0 @@
-# bridged configuration (example). Copy to bridged.yaml and adjust.
-#
-# 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.
-bind:
-  host: 127.0.0.1
-  port: 8765
-
-# herdr Unix socket. Omit to use the client default
-# (${HERDR_SOCKET_PATH:-~/.config/herdr/herdr.sock}).
-herdrSocket: ~/.config/herdr/herdr.sock
-
-# How worker sessions are spawned. Define one or more named profiles (backends) under
-# `workers`; each key is the profile name (also the ccs profile). `defaultWorker` picks
-# which one a no-argument spawn uses (bridge_spawn with no profile / POST /workers).
-#
-# Shared knobs (placement/workspace/tabLabel) 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.
-# Put `defaultMode: "auto"` in each ccs profile so the worker runs autonomously.
-workers:
-  gx10:                              # ccs profile name (NOT a hostname)
-    baseUrl: http://gx01.gw:8000     # the vLLM host this profile targets (gx00.gw / gx01.gw)
-    model: coder
-    placement: tab
-    workspace: bridged-workers
-    tabLabel: "worker: {profile} #{n}"  # {profile}/{model}/{n} substituted; {n} keeps sibling tabs distinct
-    mcpUrl: http://127.0.0.1:8765/mcp
-    tokenEnv: BRIDGED_WORKER_TOKEN
-    argv: ["ccs", "gx10"]
-  ollama:
-    baseUrl: http://ollama.ltms.dev  # local/self-hosted; usually no token
-    placement: tab
-    workspace: bridged-workers
-    tabLabel: "worker: {profile} #{n}"
-    mcpUrl: http://127.0.0.1:8765/mcp
-    argv: ["ccs", "ollama"]
-defaultWorker: gx10
-
-# Subscription boundary. A worker's base_url host MUST be one of these; the primary
-# must carry none. Every profile above must have its host listed here.
-guard:
-  offSubscriptionHosts:
-    - gx00.gw
-    - gx01.gw
-    - ollama.ltms.dev
-
-# 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

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

@@ -1,147 +0,0 @@
-package dev.ltms.bridged;
-
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.AgentControl;
-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.WorkerPresence;
-import dev.ltms.bridged.mcp.BridgeMcp;
-import dev.ltms.bridged.mcp.ConnectionIdentity;
-import dev.ltms.bridged.mcp.LsofPeerPidLookup;
-import dev.ltms.bridged.mcp.LsofProcessCwdLookup;
-import dev.ltms.bridged.msg.MessageService;
-import dev.ltms.bridged.msg.Rendezvous;
-import dev.ltms.bridged.rest.BridgedApp;
-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.worker.ClaudeCodeLauncher;
-import io.javalin.Javalin;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import java.nio.file.Path;
-
-/**
- * {@code bridged} entry point. Wires the real herdr socket client to the REST app and
- * starts listening. Before anything else it asserts its own environment is clean —
- * {@code bridged} is not a Claude process and must never carry a base_url.
- */
-public final class Bridged {
-
-    private static final Logger log = LoggerFactory.getLogger(Bridged.class);
-
-    /** How often the injector samples a busy worker's status while it has queued work. */
-    private static final long INJECT_POLL_MILLIS = 250;
-
-    static void main(String[] args) {
-        Path configPath = Path.of(args.length > 0 ? args[0] : "bridged.yaml");
-        BridgedConfig cfg = BridgedConfig.load(configPath);
-
-        // The primary/host env that launched bridged must not be tainted.
-        SubscriptionGuard guard = new SubscriptionGuard(cfg.guard().hostSet());
-        guard.assertPrimaryClean(System.getenv());
-
-        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());
-
-        AgentControl agents = new AgentControl(herdr);
-        WorkspaceControl spaces = new WorkspaceControl(herdr);
-        PeerLauncher workers = new ClaudeCodeLauncher(agents, spaces, guard,
-                cfg.workerProfiles(), cfg.defaultProfile(), System::getenv);
-        // 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();
-
-        // 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();
-        }
-        SessionManager sessions = new SessionManager(workers, new GitWorktrees(cfg.worktreeRoot()), contextCap);
-
-        // 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;
-        }
-
-        // 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.
-        // 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.
-        WorkerPresence presence = sessions.asPresence();
-        TurnListener turnListener = new TurnListener() {
-            @Override
-            public void onTurnComplete(String target) {
-                completion.onTurnComplete(target);
-                sessions.onTurnComplete(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, presence::isPresent, presence::forget);
-        StatusPoller poller = new StatusPoller(agents, injector, INJECT_POLL_MILLIS);
-        poller.start();
-
-        MessageService messages = new MessageService(agents, injector, rendezvous);
-
-        // 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());
-        // Cast to ClaudeCodeLauncher: BridgeMcp is not yet migrated to PeerLauncher (Stage A scope).
-        BridgeMcp mcp = new BridgeMcp(messages, rendezvous, (ClaudeCodeLauncher) workers, sessions, identity, presence);
-
-        // 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();
-            mcp.close();
-            if (reaper != null) reaper.stop();
-            herdr.close();
-        }));
-
-        Javalin app = new BridgedApp(herdr, (ClaudeCodeLauncher) workers, sessions, messages, rendezvous, presence, mcp.servlet()).build();
-        app.start(cfg.bind().host(), cfg.bind().port());
-        log.info("bridged listening on {}:{}, herdr socket {}",
-                cfg.bind().host(), cfg.bind().port(), socket);
-    }
-
-    private Bridged() {
-    }
-}

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

@@ -1,234 +0,0 @@
-package dev.ltms.bridged.config;
-
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
-
-import java.io.IOException;
-import java.io.UncheckedIOException;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
-/**
- * {@code bridged} configuration, loaded from a YAML file (see
- * {@code bridged.example.yaml}). Unknown keys are ignored so config can grow ahead
- * of the code.
- *
- * @param bind          REST/MCP listen host:port
- * @param herdrSocket   path to herdr's Unix socket ({@code null} → client default)
- * @param worker        single worker profile (legacy; superseded by {@code workers})
- * @param workers       named worker profiles, keyed by profile name (multi-backend fleet)
- * @param defaultWorker which {@code workers} key a no-argument spawn uses ({@code null} → the
- *                      single {@code worker}, or the sole/first profile)
- * @param guard         subscription-boundary allowlist
- * @param worktreeRoot  nullable root directory for provisioned worktrees; defaults to a sibling
- *                      of the repo root
- * @param lifecycle     session lifecycle limits ({@code null} = all disabled)
- */
-@JsonIgnoreProperties(ignoreUnknown = true)
-public record BridgedConfig(
-        Bind bind,
-        String herdrSocket,
-        Worker worker,
-        Map<String, Worker> workers,
-        String defaultWorker,
-        Guard guard,
-        String worktreeRoot,
-        Lifecycle lifecycle) {
-
-    @JsonIgnoreProperties(ignoreUnknown = true)
-    public record Bind(String host, int port) {
-        public Bind {
-            if (host == null || host.isBlank()) host = "127.0.0.1";
-            if (port <= 0) port = 8765;
-        }
-    }
-
-    /**
-     * @param profile   ccs profile a worker is spawned under (Stage-1: {@code ltms-local})
-     * @param baseUrl   the off-subscription endpoint injected as {@code ANTHROPIC_BASE_URL}
-     * @param model     model alias, injected as {@code ANTHROPIC_MODEL} (may be {@code null})
-     * @param configDir {@code CLAUDE_CONFIG_DIR} so the worker inherits the profile's
-     *                  skills/MCP/hooks (may be {@code null})
-     * @param tokenEnv  name of the host env var holding the worker's auth token; its value
-     *                  is injected as {@code ANTHROPIC_AUTH_TOKEN} (never stored in config)
-     * @param argv      launch command; defaults to {@code ["claude"]}
-     * @param placement where a worker lands: {@code "tab"} (default — its own tab in the
-     *                  worker space) or {@code "pane"} (legacy — split the focused tab)
-     * @param workspace label of the dedicated worker space; found-or-created on first
-     *                  spawn (default {@code "bridged-workers"}). A future per-session
-     *                  layout is just a distinct label here — the shared space is default.
-     * @param tabLabel  template for a worker tab's label; {@code {profile}}/{@code {model}}
-     *                  and {@code {n}} (per-worker number, to keep sibling tabs distinct)
-     *                  are substituted (default {@code "worker: {profile} #{n}"})
-     * @param mcpUrl         bridge MCP URL to provision into the worker's {@code configDir} so it
-     *                       can call {@code bridge_reply} ({@code null}/blank → no provisioning; the
-     *                       worker won't reply, only the fallback/timeout resolves the send)
-     * @param cwd            fixed working directory for this profile's workers (CB-112 "told otherwise");
-     *                       {@code null}/blank → inherit the primary's cwd, else the daemon's
-     * @param parityOverlay  repo-relative paths copied primary→worktree for config parity; null/empty
-     *                       defaults to a sensible set of local config files
-     * @param gitTokenEnv    name of the host env var holding the git-forge API token; when set, its
-     *                       value is injected as {@code GITEA_TOKEN} so the worker can open its own PR
-     *                       at checkpoint (CB-302). {@code null}/blank ⇒ no token is injected
-     *                       (minimal-grant default — push over SSH stays free, PR-create is opt-in)
-     * @param gitHostEnv     name of the host env var holding the forge host (default {@code GITEA_HOST});
-     *                       injected as {@code GITEA_HOST} <em>only</em> when {@code gitTokenEnv} is set
-     */
-    @JsonIgnoreProperties(ignoreUnknown = true)
-    public record Worker(String profile, String baseUrl, String model,
-                         String configDir, String tokenEnv, List<String> argv,
-                         String placement, String workspace, String tabLabel, String mcpUrl,
-                         String cwd,
-                         List<String> parityOverlay,
-                         String gitTokenEnv, String gitHostEnv) {
-        public Worker {
-            argv = (argv == null || argv.isEmpty()) ? List.of("claude") : List.copyOf(argv);
-            tokenEnv = (tokenEnv == null || tokenEnv.isBlank()) ? "BRIDGED_WORKER_TOKEN" : tokenEnv;
-            placement = (placement == null || placement.isBlank()) ? "tab" : placement.toLowerCase();
-            workspace = (workspace == null || workspace.isBlank()) ? "bridged-workers" : workspace;
-            tabLabel = (tabLabel == null || tabLabel.isBlank()) ? "worker: {profile} #{n}" : tabLabel;
-            parityOverlay = (parityOverlay == null || parityOverlay.isEmpty())
-                    ? List.of(".mcp.json", ".claude/settings.local.json", ".env", ".envrc")
-                    : List.copyOf(parityOverlay);
-            // gitTokenEnv stays null when unset (opt-in). gitHostEnv defaults so operators enabling
-            // checkpoints need only set gitTokenEnv; it is injected only alongside a resolved token.
-            gitHostEnv = (gitHostEnv == null || gitHostEnv.isBlank()) ? "GITEA_HOST" : gitHostEnv;
-        }
-
-        /**
-         * Backward-compatible constructor without the CB-302 git-forge fields — the worker is
-         * granted no PR-create token (push over SSH is unaffected). Keeps pre-CB-302 call sites
-         * (and any {@code workers:} YAML that omits the git keys) working unchanged.
-         */
-        public Worker(String profile, String baseUrl, String model,
-                      String configDir, String tokenEnv, List<String> argv,
-                      String placement, String workspace, String tabLabel, String mcpUrl,
-                      String cwd, List<String> parityOverlay) {
-            this(profile, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, null, null);
-        }
-
-        /** A copy with {@code profile} set — used to default a profile to its {@code workers} key. */
-        public Worker withProfile(String p) {
-            return new Worker(p, baseUrl, model, configDir, tokenEnv, argv, placement, workspace, tabLabel,
-                    mcpUrl, cwd, parityOverlay, gitTokenEnv, gitHostEnv);
-        }
-
-        /** True when this profile's workers are granted a forge token to open their own PR (CB-302). */
-        public boolean hasGitToken() {
-            return gitTokenEnv != null && !gitTokenEnv.isBlank();
-        }
-
-        /** True when workers should land in their own tab in the worker space. */
-        public boolean tabPlacement() {
-            return "tab".equals(placement);
-        }
-
-        /** True when the bridge MCP should be mounted into a spawned worker (via launch flags). */
-        public boolean hasMcp() {
-            return mcpUrl != null && !mcpUrl.isBlank();
-        }
-
-        /**
-         * Render {@link #tabLabel} for the {@code n}-th worker (substitutes
-         * {@code {profile}}/{@code {model}}/{@code {n}}), so sibling worker tabs are distinct.
-         */
-        public String renderTabLabel(long n) {
-            return tabLabel
-                    .replace("{profile}", profile == null ? "" : profile)
-                    .replace("{model}", model == null ? "" : model)
-                    .replace("{n}", Long.toString(n));
-        }
-    }
-
-    /**
-     * Session lifecycle limits. All knobs are opt-in: {@code null} or {@code 0} disables the
-     * feature so existing configs keep the previous behaviour.
-     *
-     * @param idleTtlSeconds     max seconds a {@code READY}/{@code DONE} session may sit idle
-     *                           before it is reaped ({@code null} → disabled)
-     * @param contextCap          max delegated turns a session serves before force-release
-     *                           ({@code null} → disabled)
-     * @param drainTimeoutSeconds seconds to wait for {@code BUSY} sessions to finish before
-     *                           forced teardown on shutdown (default 5 when unset)
-     */
-    @JsonIgnoreProperties(ignoreUnknown = true)
-    public record Lifecycle(Integer idleTtlSeconds, Integer contextCap, Integer drainTimeoutSeconds) {
-    }
-
-    /**
-     * Subscription boundary. Only these hosts may back a worker's
-     * {@code ANTHROPIC_BASE_URL}; the primary must carry none.
-     *
-     * @param offSubscriptionHosts hostnames allowed for worker base_urls
-     */
-    @JsonIgnoreProperties(ignoreUnknown = true)
-    public record Guard(List<String> offSubscriptionHosts) {
-        public Guard {
-            offSubscriptionHosts = offSubscriptionHosts == null ? List.of() : List.copyOf(offSubscriptionHosts);
-        }
-
-        public Set<String> hostSet() {
-            return Set.copyOf(offSubscriptionHosts);
-        }
-    }
-
-    /**
-     * The effective worker profiles, keyed by profile name. Prefers the {@code workers} map (each
-     * value's {@code profile} defaulted to its key); falls back to the legacy singular {@code worker}
-     * (keyed by its own profile). Empty if neither is configured.
-     */
-    public Map<String, Worker> workerProfiles() {
-        if (workers != null && !workers.isEmpty()) {
-            Map<String, Worker> out = new LinkedHashMap<>();
-            workers.forEach((name, w) -> out.put(name,
-                    (w.profile() == null || w.profile().isBlank()) ? w.withProfile(name) : w));
-            return Map.copyOf(out);
-        }
-        if (worker != null) {
-            String name = (worker.profile() == null || worker.profile().isBlank()) ? "default" : worker.profile();
-            return Map.of(name, worker);
-        }
-        return Map.of();
-    }
-
-    /**
-     * The profile a no-argument spawn uses: {@code defaultWorker} if set, else the legacy single
-     * {@code worker}'s profile, else the sole/first configured profile, else {@code null}.
-     */
-    public String defaultProfile() {
-        if (defaultWorker != null && !defaultWorker.isBlank()) {
-            return defaultWorker;
-        }
-        if (worker != null && worker.profile() != null && !worker.profile().isBlank()) {
-            return worker.profile();
-        }
-        Map<String, Worker> p = workerProfiles();
-        return p.isEmpty() ? null : p.keySet().iterator().next();
-    }
-
-    private static final ObjectMapper YAML = new ObjectMapper(new YAMLFactory());
-
-    /** Load and validate config from {@code path}. */
-    public static BridgedConfig load(Path path) {
-        try {
-            BridgedConfig cfg = YAML.readValue(Files.readString(path), BridgedConfig.class);
-            return cfg.withDefaults();
-        } catch (IOException e) {
-            throw new UncheckedIOException("cannot read bridged config at " + path, e);
-        }
-    }
-
-    /** Fill in nested defaults so callers never see nulls for structural fields. */
-    public BridgedConfig withDefaults() {
-        Bind b = bind != null ? bind : new Bind(null, 0);
-        Guard g = guard != null ? guard : new Guard(List.of());
-        Lifecycle l = lifecycle != null ? lifecycle : new Lifecycle(null, null, null);
-        return new BridgedConfig(b, herdrSocket, worker, workers, defaultWorker, g, worktreeRoot, l);
-    }
-}

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

@@ -1,132 +0,0 @@
-package dev.ltms.bridged.herdr;
-
-import com.fasterxml.jackson.databind.JsonNode;
-
-import java.util.ArrayList;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-
-/**
- * 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.
- *
- * <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.
- */
-public final class AgentControl {
-
-    /**
-     * The keystroke that submits a prompt in the Claude Code TUI: a carriage return (Enter).
-     * It must be delivered as its <em>own</em> {@code agent.send} call — herdr delivers a message's
-     * text as a bracketed paste, and a {@code "\r"} appended to that same text is swallowed as
-     * literal newline content, not a submit. Sent as a separate keystroke event it lands outside
-     * the paste and submits. (A bare {@code "\n"} inserts a newline either way.) Verified live
-     * against Claude Code v2.1.210: an injected task stayed unsubmitted with {@code "text\r"} in
-     * one call, and submitted the instant a standalone {@code "\r"} was sent.
-     */
-    static final String SUBMIT_KEY = "\r";
-
-    private final HerdrClient herdr;
-
-    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);
-    }
-
-    /** Spawn an agent into {@code tabId} at herdr's default cwd. */
-    public Agent start(String name, List<String> argv, Map<String, String> env, String tabId) {
-        return start(name, argv, env, tabId, null);
-    }
-
-    /**
-     * Spawn an agent. 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). A non-blank {@code cwd} sets the worker process's working directory —
-     * {@code agent.start} honours {@code cwd} directly (an agent pane does <em>not</em> inherit the
-     * tab's or workspace's cwd, so this is the only way to root a worker in the primary's directory;
-     * CB-112).
-     */
-    public Agent start(String name, List<String> argv, Map<String, String> env, String tabId, String cwd) {
-        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);
-        }
-        if (cwd != null && !cwd.isBlank()) {
-            params.put("cwd", cwd);
-        }
-        JsonNode result = herdr.call("agent.start", params);
-        return Agent.from(result.get("agent"));
-    }
-
-    /**
-     * Deliver {@code text} to an agent as its next prompt <em>and submit it</em> — two keystroke
-     * events: the message (a bracketed paste, so any embedded newlines are preserved verbatim),
-     * then a standalone {@link #SUBMIT_KEY} (Enter) that actually submits it. Without the second
-     * event the text just sits in the worker's input box, never processed (see {@link #SUBMIT_KEY}).
-     */
-    public void send(String target, String text) {
-        herdr.call("agent.send", Map.of("target", target, "text", text));
-        herdr.call("agent.send", Map.of("target", target, "text", SUBMIT_KEY));
-    }
-
-    /**
-     * Re-send the submit keystroke (Enter) to {@code target}. The Enter 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) {
-        herdr.call("agent.send", Map.of("target", target, "text", SUBMIT_KEY));
-    }
-
-    /**
-     * Read an agent's terminal.
-     *
-     * @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));
-        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"));
-    }
-
-    /** Just the lifecycle status — what the status-gated injector checks before send. */
-    public AgentStatus status(String target) {
-        return get(target).status();
-    }
-
-    /** All agents herdr tracks — the discovery surface ("what workers exist"). */
-    public List<Agent> list() {
-        JsonNode result = herdr.call("agent.list");
-        List<Agent> out = new ArrayList<>();
-        for (JsonNode a : result.path("agents")) {
-            out.add(Agent.from(a));
-        }
-        return out;
-    }
-
-    /** Tear a worker down (there is no agent.stop — close its pane). */
-    public void close(String paneId) {
-        herdr.call("pane.close", Map.of("pane_id", paneId));
-    }
-}

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

@@ -1,59 +0,0 @@
-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/inject/CompletionResolver.java

@@ -1,256 +0,0 @@
-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));
-    }
-
-    @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/mcp/BridgeMcp.java

@@ -1,539 +0,0 @@
-package dev.ltms.bridged.mcp;
-
-import dev.ltms.bridged.guard.GuardException;
-import dev.ltms.bridged.herdr.Agent;
-import dev.ltms.bridged.inject.WorkerPresence;
-import dev.ltms.bridged.herdr.HerdrException;
-import dev.ltms.bridged.msg.MessageService;
-import dev.ltms.bridged.msg.Rendezvous;
-import dev.ltms.bridged.session.SessionManager;
-import dev.ltms.bridged.session.WorkerSession;
-import dev.ltms.bridged.session.WorktreeRequest;
-import dev.ltms.bridged.worker.ClaudeCodeLauncher;
-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} adapt {@link ClaudeCodeLauncher} so a worker's whole lifecycle
- * is driven through MCP, with the subscription boundary still enforced inside {@code ClaudeCodeLauncher}.
- *
- * <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";
-
-    private final HttpServletStreamableServerTransportProvider transport;
-    private final McpSyncServer server;
-
-    public BridgeMcp(MessageService messages, Rendezvous rendezvous, ClaudeCodeLauncher workers,
-                     SessionManager sessions, ConnectionIdentity identity, WorkerPresence presence) {
-        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 -> {
-                    ConnectionIdentity.Caller c = identity.resolve(req.getRemoteAddr(), req.getRemotePort());
-                    presence.markPresent(c.terminal()); // no-op for the primary (null terminal)
-                    return McpTransportContext.create(Map.of(
-                            CALLER_TERMINAL, orEmpty(c.terminal()),
-                            CALLER_PID, Long.toString(c.pid())));
-                })
-                .build();
-        this.server = McpServer.sync(transport)
-                .serverInfo("bridge", "0.1.0")
-                .capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
-                .toolCall(sendTool(), (_, req) -> {
-                    Map<String, Object> a = req.arguments();
-                    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.
-                        return answer(messages, turnId, str(a, "content"), timeoutMs(a));
-                    }
-                    // wait defaults to true (block for the reply); wait:false is fire-and-poll.
-                    return Boolean.FALSE.equals(a.get("wait"))
-                            ? sendAsync(messages, str(a, "sessionId"), str(a, "content"))
-                            : send(messages, str(a, "sessionId"), str(a, "content"), timeoutMs(a));
-                })
-                // bridge_reply's identity is the CONNECTION, never an argument.
-                .toolCall(replyTool(), (exchange, req) ->
-                        reply(rendezvous, callerTerminal(exchange), str(req.arguments(), "content")))
-                // bridge_ask (CB-205): a worker's mid-turn question — identity from the CONNECTION.
-                .toolCall(askTool(), (exchange, req) ->
-                        ask(messages, callerTerminal(exchange), str(req.arguments(), "question"), timeoutMs(req.arguments())))
-                .toolCall(statusTool(), (_, req) ->
-                        status(messages, str(req.arguments(), "sessionId")))
-                .toolCall(pollTool(), (_, req) ->
-                        poll(messages, str(req.arguments(), "ticket")))
-                // Fleet management (CB-108): spawn/list/stop over ClaudeCodeLauncher.
-                .toolCall(spawnTool(), (exchange, req) -> {
-                    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, "cwd"), callerCwd,
-                            callerTerminal(exchange), worktreeRequest(a));
-                })
-                .toolCall(listTool(), (_, _) -> listWorkers(workers, sessions))
-                .toolCall(stopTool(), (_, req) -> stop(sessions, str(req.arguments(), "paneId")))
-                .toolCall(profilesTool(), (_, _) -> profiles(workers))
-                .build();
-    }
-
-    /** 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 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) {
-        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), 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) {
-        if (isBlank(sessionId) || isBlank(content)) {
-            return error("sessionId and content are required");
-        }
-        String ticket = messages.sendAsync(sessionId, content);
-        return text("accepted — task delegated. Poll bridge_poll with ticket=" + ticket);
-    }
-
-    /** {@code bridge_poll}: check an async delegation by ticket (pending / done+reply / failed). */
-    static McpSchema.CallToolResult poll(MessageService messages, String ticket) {
-        if (isBlank(ticket)) {
-            return error("ticket 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.
-     * {@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(Rendezvous rendezvous, 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");
-        }
-        return rendezvous.resolve(callerTerminal, content)
-                ? text("delivered")
-                : error("no send is awaiting a reply for this worker");
-    }
-
-    /** {@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());
-        }
-    }
-
-    // --- 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);
-    }
-
-    /**
-     * {@code bridge_spawn}: launch a guard-checked worker for {@code profile} (blank → the default
-     * profile) and return its session id + pane id. The worker'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.
-     */
-    static McpSchema.CallToolResult spawn(SessionManager sessions, String profile,
-                                          String requestedCwd, String callerCwd,
-                                          String ownerTerminal, WorktreeRequest worktreeRequest) {
-        try {
-            WorkerSession worker = sessions.acquire(isBlank(profile) ? null : profile,
-                    requestedCwd, callerCwd, ownerTerminal, worktreeRequest);
-            return text(json(workerView(worker)));
-        } catch (GuardException e) {
-            return error("subscription boundary: " + e.getMessage());
-        } catch (IllegalArgumentException e) {
-            return error(e.getMessage()); // unknown / no-default profile
-        } 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(ClaudeCodeLauncher workers) {
-        return text(json(Map.of(
-                "profiles", workers.profiles(),
-                "default", workers.defaultProfile() == null ? "" : workers.defaultProfile())));
-    }
-
-    /** {@code bridge_list}: bridge-owned roster merged with live herdr status by paneId. */
-    static McpSchema.CallToolResult listWorkers(ClaudeCodeLauncher workers, SessionManager sessions) {
-        try {
-            Map<String, Agent> live = workers.list().stream()
-                    .filter(a -> a.paneId() != null)
-                    .collect(Collectors.toMap(Agent::paneId, Function.identity(), (_, b) -> b));
-            List<Map<String, Object>> out = sessions.roster().stream()
-                    .map(s -> SessionManager.rosterView(s, live.get(s.paneId())))
-                    .toList();
-            return text(json(Map.of("workers", out)));
-        } catch (HerdrException e) {
-            return error("herdr error listing workers: " + e.getMessage());
-        }
-    }
-
-    /** {@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> workerView(WorkerSession s) {
-        Map<String, Object> m = new LinkedHashMap<>();
-        m.put("sessionId", s.terminalId());
-        m.put("paneId", s.paneId());
-        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.",
-                objectSchema(Map.of(
-                        "ticket", stringProp("The ticket returned by bridge_send wait:false")),
-                        List.of("ticket")));
-    }
-
-    private static McpSchema.Tool spawnTool() {
-        return tool("bridge_spawn",
-                "Spawn a new off-subscription worker session. Pass a profile (from bridge_profiles) to "
-                        + "pick the backend, or omit it for the default. The worker 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 worker's sessionId (use with bridge_send) and paneId (use with bridge_stop).",
-                objectSchema(Map.of(
-                        "profile", stringProp("Worker profile to spawn (omit for the default profile)"),
-                        "cwd", stringProp("Working directory for the worker (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 worker sessions the bridge tracks — each with its sessionId, paneId, profile, "
-                        + "state, optional worktree/branch/owner, and live herdr status.",
-                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 worker's identity is resolved from the connection.
-        return tool("bridge_reply",
-                "Return your structured answer for the task you were delegated, "
-                        + "resolving the caller's blocked bridge_send.",
-                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")));
-    }
-
-    // --- 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

@@ -1,66 +0,0 @@
-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/msg/MessageService.java

@@ -1,385 +0,0 @@
-package dev.ltms.bridged.msg;
-
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.AgentStatus;
-import dev.ltms.bridged.inject.Injector;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-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 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());
-
-    public MessageService(AgentControl agents, Injector injector, Rendezvous rendezvous) {
-        this.agents = agents;
-        this.injector = injector;
-        this.rendezvous = rendezvous;
-    }
-
-    /** Current lifecycle status of a worker (the {@code GET /sessions/{id}/status} surface). */
-    public AgentStatus status(String target) {
-        return agents.status(target);
-    }
-
-    /**
-     * 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) {
-        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 {
-            CompletableFuture<Void> delivered = injector.enqueue(target, content);
-            CompletableFuture<Rendezvous.Resolution> reply = rendezvous.open(target);
-            try {
-                Rendezvous.Resolution r = reply.get(remainingMillis(deadlineNanos), TimeUnit.MILLISECONDS);
-                return 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 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) {
-        String ticket = "task-" + ticketSeq.incrementAndGet();
-        CompletableFuture<Reply> future =
-                CompletableFuture.supplyAsync(() -> send(target, content, ASYNC_TIMEOUT_MS), 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/peer/Capability.java

@@ -1,35 +0,0 @@
-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 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
-}

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

@@ -1,29 +0,0 @@
-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. For the herdr-backed
-     * launcher this is the herdr pane id; for other launchers it is whatever their transport
-     * uses. Guaranteed to be non-null and unique among live peers within a single daemon process.
-     */
-    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;
-    }
-}

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

@@ -1,85 +0,0 @@
-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);
-}

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

@@ -1,13 +0,0 @@
-package dev.ltms.bridged.peer;
-
-/**
- * Parameters for a {@link PeerLauncher#spawn(SpawnRequest)} call — the peer-neutral
- * aggregation of what the core knows at delegation time: which profile to use, the caller's
- * requested working directory, and the caller's own cwd (to inherit when no other cwd is set).
- *
- * <p>A null or blank {@code profileName} means "use the launcher's default profile."
- * A null or blank {@code requestedCwd} means "inherit from config or caller."
- * A null {@code callerCwd} means "the request came from the daemon itself (not a primary)."
- */
-public record SpawnRequest(String profileName, String requestedCwd, String callerCwd) {
-}

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

@@ -1,422 +0,0 @@
-package dev.ltms.bridged.rest;
-
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import dev.ltms.bridged.guard.GuardException;
-import dev.ltms.bridged.herdr.Agent;
-import dev.ltms.bridged.herdr.HerdrClient;
-import dev.ltms.bridged.herdr.HerdrException;
-import dev.ltms.bridged.inject.WorkerPresence;
-import dev.ltms.bridged.msg.MessageService;
-import dev.ltms.bridged.msg.Rendezvous;
-import dev.ltms.bridged.session.SessionManager;
-import dev.ltms.bridged.session.WorkerSession;
-import dev.ltms.bridged.session.WorktreeRequest;
-import dev.ltms.bridged.worker.ClaudeCodeLauncher;
-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
- * feature is reachable here without Claude or MCP in the loop, so each is an
- * acceptance test against plain HTTP. MCP tools (later) are thin adapters over these
- * same endpoints and are validated by parity, not by re-implementing behaviour.
- *
- * <p>Built from injected collaborators so tests supply fakes and run on an ephemeral
- * port; {@code main} supplies the real Unix-socket client and worker service.
- */
-public final class BridgedApp {
-
-    /** 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;
-
-    private final HerdrClient herdr;
-    private final ClaudeCodeLauncher workers;
-    private final SessionManager sessions; // CB-301: authoritative session registry
-    private final MessageService messages;
-    private final Rendezvous rendezvous;
-    private final WorkerPresence presence; // CB-113: which workers are MCP-connected (available)
-    private final HttpServlet mcpServlet; // MCP Streamable-HTTP endpoint, mounted at /mcp (nullable)
-    private final ObjectMapper mapper = new ObjectMapper();
-
-    public BridgedApp(HerdrClient herdr, ClaudeCodeLauncher workers, SessionManager sessions,
-                      MessageService messages, Rendezvous rendezvous, WorkerPresence presence,
-                      HttpServlet mcpServlet) {
-        this.herdr = herdr;
-        this.workers = workers;
-        this.sessions = sessions;
-        this.messages = messages;
-        this.rendezvous = rendezvous;
-        this.presence = presence;
-        this.mcpServlet = mcpServlet;
-    }
-
-    /** Wire routes onto a fresh, unstarted Javalin instance. Caller starts it. */
-    public Javalin build() {
-        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"));
-            }
-        });
-        app.get("/healthz", this::healthz);
-        app.get("/sessions", this::sessions);
-        app.get("/agents", this::agents);
-        app.get("/workers", this::listWorkers);                 // CB-304: registry roster + live herdr status
-        app.get("/profiles", this::profiles);                    // configured worker profiles
-        app.post("/workers", this::spawnWorker);                 // optional ?profile= or {"profile":…}
-        app.delete("/workers/{paneId}", this::stopWorker);
-        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.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;
-    }
-
-    /** Liveness + herdr reachability. 200 when herdr answers ping, 503 otherwise. */
-    private void healthz(Context ctx) {
-        try {
-            JsonNode pong = herdr.call("ping");
-            ctx.status(200).json(Map.of(
-                    "status", "ok",
-                    "herdr", Map.of(
-                            "version", pong.path("version").asText(""),
-                            "protocol", pong.path("protocol").asInt())));
-        } catch (HerdrException e) {
-            ctx.status(503).json(Map.of(
-                    "status", "degraded",
-                    "herdr", "unreachable",
-                    "detail", e.getMessage()));
-        }
-    }
-
-    /** Sessions view derived from herdr {@code workspace.list} (one workspace → one row). */
-    private void sessions(Context ctx) {
-        JsonNode result = herdr.call("workspace.list");
-        List<Map<String, Object>> out = new ArrayList<>();
-        for (JsonNode w : result.path("workspaces")) {
-            out.add(Map.of(
-                    "id", w.path("workspace_id").asText(""),
-                    "label", w.path("label").asText(""),
-                    "focused", w.path("focused").asBoolean(false),
-                    "paneCount", w.path("pane_count").asInt(),
-                    "agentStatus", w.path("agent_status").asText("unknown")));
-        }
-        ctx.status(200).json(Map.of("sessions", out));
-    }
-
-    /** 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()));
-    }
-
-    /** CB-304: bridge-owned roster merged with live herdr status by paneId. */
-    private void listWorkers(Context ctx) {
-        Map<String, Agent> live = workers.list().stream()
-                .filter(a -> a.paneId() != null)
-                .collect(Collectors.toMap(Agent::paneId, Function.identity(), (_, b) -> b));
-        List<Map<String, Object>> out = sessions.roster().stream()
-                .map(s -> SessionManager.rosterView(s, live.get(s.paneId())))
-                .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) {
-        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 spawnWorker(Context ctx) {
-        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 (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);
-        try {
-            // No MCP caller over REST, so callerCwd and ownerTerminal are null.
-            WorkerSession worker = sessions.acquire(blankToNull(profile), blankToNull(cwd), null, null, wt);
-            ctx.status(201).json(view(worker));
-        } 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()));
-        }
-    }
-
-    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) {
-        sessions.release(ctx.pathParam("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");
-        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");
-        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. 200 if a send was waiting, 409 if none was (late or spurious reply).
-     */
-    private void replyMessage(Context ctx) {
-        String id = ctx.pathParam("id");
-        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;
-        }
-        if (rendezvous.resolve(id, content)) {
-            ctx.status(200).json(Map.of("sessionId", id, "delivered", true));
-        } else {
-            ctx.status(409).json(Map.of(
-                    "sessionId", id, "error", "no_pending_send",
-                    "detail", "no send is awaiting a reply for this session"));
-        }
-    }
-
-    /**
-     * 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");
-        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) {
-        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<>();
-        m.put("terminalId", a.terminalId());
-        m.put("paneId", a.paneId());
-        m.put("workspaceId", a.workspaceId());
-        m.put("tabId", a.tabId());
-        m.put("sessionId", a.sessionId());
-        m.put("agentType", a.agentType());
-        m.put("status", a.status().name().toLowerCase());
-        return m;
-    }
-
-    /** CB-301 projection of an authoritative bridge-owned session. */
-    private static Map<String, Object> view(WorkerSession 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

@@ -1,179 +0,0 @@
-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);
-
-    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);
-        return wt;
-    }
-
-    @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/SessionManager.java

@@ -1,411 +0,0 @@
-package dev.ltms.bridged.session;
-
-import dev.ltms.bridged.herdr.Agent;
-import dev.ltms.bridged.inject.TurnListener;
-import dev.ltms.bridged.inject.WorkerPresence;
-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.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 WorkerPresence} 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*/, WorkerSession> registry = new ConcurrentHashMap<>();
-    private final WorkerPresence presence;
-    private final SecureRandom nonceRandom = new SecureRandom();
-    private final AtomicLong nonceSeq = new AtomicLong();
-    private final LongSupplier nowNanos;
-    private final int contextCap;
-
-    /** Backward-compatible constructor: shared-tree sessions, production git seam. */
-    public SessionManager(PeerLauncher launcher) {
-        this(launcher, new GitWorktrees(), System::nanoTime, 0);
-    }
-
-    /** Backward-compatible constructor with an injectable worktree seam. */
-    public SessionManager(PeerLauncher launcher, Worktrees worktrees) {
-        this(launcher, worktrees, System::nanoTime, 0);
-    }
-
-    /** Test constructor with an injectable clock. */
-    public SessionManager(PeerLauncher launcher, Worktrees worktrees, LongSupplier nowNanos) {
-        this(launcher, worktrees, nowNanos, 0);
-    }
-
-    /** Production constructor with a configured context turn cap. */
-    public SessionManager(PeerLauncher launcher, Worktrees worktrees, int contextCap) {
-        this(launcher, worktrees, System::nanoTime, contextCap);
-    }
-
-    public SessionManager(PeerLauncher launcher, Worktrees worktrees, LongSupplier nowNanos,
-                          int contextCap) {
-        this.launcher = launcher;
-        this.worktrees = worktrees;
-        this.presence = new PresenceBridge(this);
-        this.nowNanos = nowNanos;
-        this.contextCap = contextCap;
-    }
-
-    /**
-     * The single {@link WorkerPresence} 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 WorkerPresence}. 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 WorkerPresence asPresence() {
-        return presence;
-    }
-
-    /**
-     * Spawn a worker and register it as {@link WorkerSession.State#SPAWNING}. The caller's
-     * identity is recorded as {@code ownerTerminal} ({@code null} for daemon/anon callers).
-     */
-    public WorkerSession acquire(String profile, String requestedCwd, String callerCwd,
-                                 String ownerTerminal) {
-        return acquire(profile, requestedCwd, callerCwd, ownerTerminal, null);
-    }
-
-    /**
-     * Spawn a worker, optionally inside a fresh git worktree. When {@code wt} is non-null the
-     * worktree is provisioned, parity-overlaid, and its path becomes the worker's cwd. On any
-     * failure before registration the worktree is removed so no dangling checkout is left.
-     */
-    public WorkerSession acquire(String profile, String requestedCwd, String callerCwd,
-                                 String ownerTerminal, WorktreeRequest wt) {
-        if (wt == null) {
-            SpawnRequest req = new SpawnRequest(profile, requestedCwd, callerCwd);
-            PeerHandle handle = launcher.spawn(req);
-            String resolvedProfile = (profile == null || profile.isBlank())
-                    ? launcher.defaultProfile() : profile;
-            String cwd = launcher.effectiveCwd(req);
-            long now = nowNanos.getAsLong();
-            WorkerSession session = new WorkerSession(
-                    handle.id(),
-                    handle.terminalId(),
-                    resolvedProfile,
-                    cwd,
-                    ownerTerminal,
-                    now,
-                    now,
-                    0,
-                    WorkerSession.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());
-            return session;
-        }
-        return acquireWithWorktree(profile, requestedCwd, callerCwd, ownerTerminal, wt);
-    }
-
-    /** Tear a worker down by pane id and remove it from the registry. Idempotent. */
-    public void release(String paneId) {
-        WorkerSession removed = registry.remove(paneId);
-        if (removed != null) {
-            log.debug("releasing session pane={} terminal={} state={}",
-                    removed.paneId(), removed.terminalId(), removed.state());
-        }
-        launcher.stop(paneId);
-        if (removed != null && removed.worktree() != null) {
-            worktrees.remove(worktrees.repoRoot(removed.cwd()), removed.worktree());
-        }
-    }
-
-    private WorkerSession acquireWithWorktree(String profile, String requestedCwd, String callerCwd,
-                                              String ownerTerminal, WorktreeRequest wt) {
-        String resolvedProfile = (profile == null || profile.isBlank())
-                ? launcher.defaultProfile() : profile;
-        String repoRoot = worktrees.repoRoot(firstNonBlank(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(resolvedProfile));
-            handle = launcher.spawn(new SpawnRequest(profile, path, callerCwd));
-        } 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;
-        }
-        long now = nowNanos.getAsLong();
-        WorkerSession session = new WorkerSession(
-                handle.id(),
-                handle.terminalId(),
-                resolvedProfile,
-                resolveCwd(path, profile, callerCwd),
-                ownerTerminal,
-                now,
-                now,
-                0,
-                WorkerSession.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());
-        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();
-    }
-
-    private static String firstNonBlank(String... values) {
-        for (String v : values) {
-            if (v != null && !v.isBlank()) return v;
-        }
-        return null;
-    }
-
-    /**
-     * 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 WorkerSession recycle(String paneId) {
-        WorkerSession 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<WorkerSession> get(String paneId) {
-        return Optional.ofNullable(registry.get(paneId));
-    }
-
-    /** Bridge-owned roster: all registered sessions (acquired minus released). */
-    public List<WorkerSession> 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(WorkerSession session, Agent live) {
-        Map<String, Object> m = new LinkedHashMap<>();
-        m.put("sessionId", session.terminalId());
-        m.put("paneId", session.paneId());
-        m.put("profile", session.profile());
-        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, WorkerSession.State.SPAWNING, WorkerSession.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) {
-        WorkerSession current = findByTerminal(target);
-        if (current == null) return;
-        if (current.state() != WorkerSession.State.READY && current.state() != WorkerSession.State.DONE) {
-            return;
-        }
-        long now = nowNanos.getAsLong();
-        WorkerSession updated = current.withState(WorkerSession.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) {
-        WorkerSession current = findByTerminal(target);
-        if (current == null || current.state() != WorkerSession.State.BUSY) return;
-        long now = nowNanos.getAsLong();
-        WorkerSession updated = current.withState(WorkerSession.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());
-        }
-    }
-
-    /** 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) {
-        WorkerSession current = findByTerminal(target);
-        if (current == null) return;
-        if (current.state() == WorkerSession.State.RELEASED) return;
-        if (replace(current, current.withState(WorkerSession.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 (WorkerSession s : roster()) {
-            if (s.state() != WorkerSession.State.READY && s.state() != WorkerSession.State.DONE) {
-                continue;
-            }
-            if (now - s.lastActivityAtNanos() > idleTtlNanos) {
-                release(s.paneId());
-                reaped++;
-            }
-        }
-        return reaped;
-    }
-
-    /**
-     * Gracefully drain all registered sessions. 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.
-     */
-    void drainAll(long timeoutNanos) {
-        long deadline = System.nanoTime() + timeoutNanos;
-        for (WorkerSession s : roster()) {
-            try {
-                if (s.state() == WorkerSession.State.BUSY) {
-                    while (System.nanoTime() < deadline) {
-                        WorkerSession current = registry.get(s.paneId());
-                        if (current == null || current.state() != WorkerSession.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());
-            } 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();
-    }
-
-    private WorkerSession findByTerminal(String terminalId) {
-        for (WorkerSession s : registry.values()) {
-            if (terminalId.equals(s.terminalId())) return s;
-        }
-        return null;
-    }
-
-    private void transitionByTerminal(String terminalId, WorkerSession.State from,
-                                      WorkerSession.State to) {
-        WorkerSession 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(WorkerSession expected, WorkerSession updated) {
-        return registry.replace(expected.paneId(), expected, updated);
-    }
-
-    private String resolveCwd(String requestedCwd, String profileName, String callerCwd) {
-        return launcher.effectiveCwd(new SpawnRequest(profileName, requestedCwd, callerCwd));
-    }
-
-    /** WorkerPresence bridge that also drives the manager's READY transition. */
-    private static final class PresenceBridge extends WorkerPresence {
-        private final SessionManager sessions;
-
-        PresenceBridge(SessionManager sessions) {
-            this.sessions = sessions;
-        }
-
-        @Override
-        public void markPresent(String terminal) {
-            super.markPresent(terminal);
-            sessions.onReady(terminal);
-        }
-    }
-}

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

@@ -1,70 +0,0 @@
-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/WorkerSession.java

@@ -1,58 +0,0 @@
-package dev.ltms.bridged.session;
-
-/**
- * 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         herdr pane handle — the registry key and the argument to teardown
- * @param terminalId     herdr terminal handle — the {@code target} for send/read/status
- * @param profile        the worker profile name that spawned this session
- * @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 WorkerSession(
-        String paneId,
-        String terminalId,
-        String profile,
-        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 WorkerSession withState(State state) {
-        return new WorkerSession(paneId, terminalId, profile, cwd, ownerTerminal, spawnedAtNanos,
-                lastActivityAtNanos, turnCount, state, worktree, branch);
-    }
-
-    /** Return a copy with {@code lastActivityAtNanos} updated to {@code nowNanos}. */
-    public WorkerSession withActivity(long nowNanos) {
-        return new WorkerSession(paneId, terminalId, profile, cwd, ownerTerminal, spawnedAtNanos,
-                nowNanos, turnCount, state, worktree, branch);
-    }
-
-    /** Return a copy with the turn count incremented and activity timestamped at {@code nowNanos}. */
-    public WorkerSession bumpTurn(long nowNanos) {
-        return new WorkerSession(paneId, terminalId, profile, cwd, ownerTerminal, spawnedAtNanos,
-                nowNanos, turnCount + 1, state, worktree, branch);
-    }
-}

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

@@ -1,18 +0,0 @@
-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/ClaudeCodeLauncher.java

@@ -1,488 +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 dev.ltms.bridged.peer.Capability;
-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.ArrayList;
-import java.util.EnumSet;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-import java.util.concurrent.atomic.AtomicLong;
-import java.util.function.Function;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-
-/**
- * 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 ClaudeCodeLauncher implements PeerLauncher {
-
-    private static final Logger log = LoggerFactory.getLogger(ClaudeCodeLauncher.class);
-
-    /** herdr rejects a duplicate agent {@code name}; we retry a bumped name this many times. */
-    private static final int NAME_RETRIES = 8;
-
-    /**
-     * A bridge-spawned worker label {@code claude-<profile>-<nonce>-<seq>} (see
-     * {@link #startUniquelyNamed}); group 1 captures the 6-hex per-process {@code nonce}. The
-     * profile segment may itself contain {@code -}, so the nonce/seq are anchored at the tail.
-     * Names not matching this shape are not workers we started and are never reaped (CB-117).
-     */
-    private static final Pattern WORKER_NAME = Pattern.compile("claude-.*-([0-9a-f]{6})-\\d+");
-
-    private final AgentControl agents;
-    private final WorkspaceControl spaces;
-    private final SubscriptionGuard guard;
-    private final Map<String, BridgedConfig.Worker> profiles; // profile name → spawn settings
-    private final String defaultProfile;                      // profile a no-arg spawn uses (nullable)
-    private final Function<String, String> env; // host env lookup (injectable for tests)
-    private final AtomicLong nameSeq = new AtomicLong(); // per-worker counter (also the tab #)
-
-    /**
-     * 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.";
-
-    // 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 ClaudeCodeLauncher(AgentControl agents, WorkspaceControl spaces, SubscriptionGuard guard,
-                              Map<String, BridgedConfig.Worker> profiles, String defaultProfile,
-                              Function<String, String> env) {
-        this.agents = agents;
-        this.spaces = spaces;
-        this.guard = guard;
-        this.profiles = Map.copyOf(profiles);
-        this.defaultProfile = defaultProfile;
-        this.env = env;
-    }
-
-    /** The configured worker 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.Worker cfg = profiles.get(name);
-        return cfg == null ? List.of() : cfg.parityOverlay();
-    }
-
-    /** The profile a no-argument {@link #spawn()} uses, or {@code null} if none is configured. */
-    @Override
-    public String defaultProfile() {
-        return defaultProfile;
-    }
-
-    /** Spawn a worker for the default profile in the resolved default cwd. */
-    public Agent spawn() {
-        return spawn(null, null, null);
-    }
-
-    /** Spawn a worker for a named profile (null → default) in the resolved default cwd. */
-    public Agent spawn(String profileName) {
-        return spawn(profileName, null, null);
-    }
-
-    /**
-     * Spawn a worker. {@code profileName} null/blank → the default profile. The worker's working
-     * directory (CB-112) is resolved by {@link #resolveCwd}: an explicit {@code requestedCwd} (a
-     * spawn argument), 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}. Guard runs before any herdr call.
-     */
-    public Agent spawn(String profileName, String requestedCwd, String callerCwd) {
-        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.Worker cfg = profiles.get(name);
-        if (cfg == null) {
-            throw new IllegalArgumentException("unknown worker profile '" + name
-                    + "' — configured: " + profiles.keySet());
-        }
-        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);
-
-        // CB-302: the worker checkpoint (commit → push → open its own PR). Push is free over SSH;
-        // the only incremental grant is PR-create, a repo-scoped forge token injected here — opt-in
-        // per profile via gitTokenEnv, and never mutating bridged's own env. The paired forge host
-        // rides along only when a token is actually granted, so non-implementer profiles get neither.
-        if (cfg.hasGitToken()) {
-            String gitToken = resolveEnv(cfg.gitTokenEnv());
-            if (gitToken != null) {
-                workerEnv.put("GITEA_TOKEN", gitToken);
-                putIfPresent(workerEnv, "GITEA_HOST", resolveEnv(cfg.gitHostEnv()));
-            }
-        }
-
-        // Mount the bridge MCP + reply charter as launch FLAGS (non-invasive: nothing written to
-        // the worker's profile/config dir). Identity is connection-based, so the mount is shared.
-        List<String> argv = argvWithBridge(cfg);
-        String cwd = resolveCwd(requestedCwd, cfg, callerCwd);
-
-        return cfg.tabPlacement()
-                ? spawnInTab(cfg, workerEnv, argv, cwd)
-                : spawnAsPane(cfg, workerEnv, argv, cwd);
-    }
-
-    /**
-     * 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.Worker cfg, String callerCwd) {
-        return firstNonBlank(requestedCwd, cfg.cwd(), callerCwd, System.getProperty("user.dir"), ".");
-    }
-
-    /**
-     * CB-301: the effective working directory a spawn for {@code profileName} would use, without
-     * actually spawning. Used by {@link dev.ltms.bridged.session.SessionManager} to record the
-     * resolved cwd in the session registry.
-     */
-    public String effectiveCwd(String profileName, String requestedCwd, String callerCwd) {
-        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.Worker cfg = profiles.get(name);
-        if (cfg == null) {
-            throw new IllegalArgumentException("unknown worker profile '" + name
-                    + "' — configured: " + profiles.keySet());
-        }
-        return resolveCwd(requestedCwd, cfg, callerCwd);
-    }
-
-    private static String firstNonBlank(String... values) {
-        for (String v : values) {
-            if (v != null && !v.isBlank()) return v;
-        }
-        return null;
-    }
-
-    /**
-     * 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.
-     */
-    private List<String> argvWithBridge(BridgedConfig.Worker cfg) {
-        if (!cfg.hasMcp()) {
-            return cfg.argv();
-        }
-        String mcpJson = "{\"mcpServers\":{\"bridge\":{\"type\":\"http\",\"url\":\""
-                + cfg.mcpUrl() + "\"}}}";
-        List<String> argv = new ArrayList<>(cfg.argv());
-        argv.add("--mcp-config");
-        argv.add(mcpJson);
-        argv.add("--append-system-prompt");
-        argv.add(REPLY_CHARTER);
-        return argv;
-    }
-
-    /** Dedicated worker space → own tab → start the worker (rooted at {@code cwd}) → drop the shell. */
-    private Agent spawnInTab(BridgedConfig.Worker cfg, Map<String, String> workerEnv,
-                             List<String> argv, String cwd) {
-        Workspace space = spaces.ensureWorkspace(cfg.workspace());
-        Tab.Created tab = spaces.createTab(space.workspaceId());
-        log.info("spawning worker profile={} base_url={} space={} tab={} cwd={}",
-                cfg.profile(), cfg.baseUrl(), space.workspaceId(), tab.tab().tabId(), cwd);
-
-        Started started;
-        try {
-            started = startUniquelyNamed(cfg, workerEnv, argv, tab.tab().tabId(), cwd);
-        } 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; the worker still starts in {@code cwd}. */
-    private Agent spawnAsPane(BridgedConfig.Worker cfg, Map<String, String> workerEnv,
-                             List<String> argv, String cwd) {
-        log.info("spawning worker (pane placement) profile={} base_url={} cwd={} argv={}",
-                cfg.profile(), cfg.baseUrl(), cwd, argv);
-        Agent worker = startUniquelyNamed(cfg, workerEnv, argv, null, cwd).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(BridgedConfig.Worker cfg, Map<String, String> workerEnv,
-                                       List<String> argv, String tabId, String cwd) {
-        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, argv, workerEnv, tabId, cwd), 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". */
-    @Override
-    public List<Agent> list() {
-        return agents.list();
-    }
-
-    /**
-     * Reap worker panes left behind by an earlier daemon process (CB-117). herdr keeps a worker's
-     * pane alive across a daemon restart <em>by design</em>, and that pane's id is held only by its
-     * spawner — so a worker whose owning process exited before issuing the matching teardown leaks
-     * with nothing tracking it (there is no registry; {@link #list()} only asks herdr). On boot we
-     * scan herdr for agents whose name matches our {@code claude-<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 worker is ours and live,
-     * so it is left running; a user's own {@code claude} session carries no such name and is never
-     * touched. Best-effort: a failed listing, or a failure to stop any one worker, is logged and
-     * never aborts startup.
-     *
-     * @return the number of orphaned workers reaped
-     */
-    @Override
-    public int reapOrphanWorkers() {
-        List<Agent> all;
-        try {
-            all = agents.list();
-        } catch (RuntimeException e) {
-            log.warn("orphan-worker reap skipped — agent.list failed: {}", e.getMessage());
-            return 0;
-        }
-        int reaped = 0;
-        for (Agent a : all) {
-            if (!isForeignWorker(a.name(), nameNonce)) continue;
-            try {
-                stop(a.paneId());
-                reaped++;
-                log.info("reaped orphan worker {} (pane={} tab={}) left by a prior daemon",
-                        a.name(), a.paneId(), a.tabId());
-            } catch (RuntimeException e) {
-                log.warn("could not reap orphan worker {} (pane={}): {}",
-                        a.name(), a.paneId(), e.getMessage());
-            }
-        }
-        if (reaped > 0) {
-            log.info("orphan-worker reap complete — {} stale worker(s) removed at startup", reaped);
-        }
-        return reaped;
-    }
-
-    /**
-     * Whether {@code name} is a bridge worker started by a <em>different</em> process than
-     * {@code currentNonce} — the reap predicate (CB-117). True only for our naming scheme with a
-     * foreign nonce: a non-worker name (no match, e.g. a user session) or our own live nonce is
-     * excluded. Pure and package-private so the decision is unit-testable without herdr.
-     */
-    static boolean isForeignWorker(String name, String currentNonce) {
-        String nonce = workerNonce(name);
-        return nonce != null && !nonce.equals(currentNonce);
-    }
-
-    /** The 6-hex nonce embedded in a bridge worker name, or {@code null} if {@code name} isn't one. */
-    static String workerNonce(String name) {
-        if (name == null) return null;
-        Matcher m = WORKER_NAME.matcher(name);
-        return m.matches() ? m.group(1) : null;
-    }
-
-    /** This process's worker-name nonce (a label component only; exposed for reaper tests). */
-    String nameNonce() {
-        return nameNonce;
-    }
-
-    /**
-     * 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.
-     */
-    @Override
-    public void stop(String paneId) {
-        // Teardown knows only the paneId, not which profile spawned it. Attempt tab cleanup when any
-        // profile uses tab placement (so the bridge may have created a dedicated worker tab); the
-        // single-occupant check below is what actually protects the user's shared tabs.
-        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 worker tab)",
-                    loc.tabId(), loc.tabPaneCount());
-        }
-    }
-
-    /** Whether any configured profile places workers in their own tab (so tabs may need cleanup). */
-    private boolean usesTabPlacement() {
-        return profiles.values().stream().anyMatch(BridgedConfig.Worker::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");
-    }
-
-    // --- PeerLauncher SPI -------------------------------------------------------------------
-
-    @Override
-    public Set<Capability> capabilities() {
-        Set<Capability> caps = EnumSet.of(Capability.MID_TURN_ASK, Capability.WORKTREE, Capability.ORPHAN_REAP);
-        if (hasGitTokenProfile()) {
-            caps.add(Capability.SELF_PR);
-        }
-        return Set.copyOf(caps);
-    }
-
-    /** Whether any configured profile opts into a git-forge token (required for {@link Capability#SELF_PR}). */
-    private boolean hasGitTokenProfile() {
-        return profiles.values().stream().anyMatch(BridgedConfig.Worker::hasGitToken);
-    }
-
-    /**
-     * {@inheritDoc}
-     *
-     * <p>Delegates to the three-arg {@link #spawn(String, String, String)} and wraps the
-     * resulting herdr {@link Agent} in a {@link WorkerHandle} whose {@link PeerHandle#id()}
-     * equals the agent's paneId.
-     */
-    @Override
-    public PeerHandle spawn(SpawnRequest req) {
-        Agent agent = spawn(req.profileName(), req.requestedCwd(), req.callerCwd());
-        return new WorkerHandle(agent.paneId(), agent.terminalId());
-    }
-
-    /** A concrete {@link PeerHandle} wrapping herdr agent coordinates. */
-    private record WorkerHandle(String id, String terminalId) implements PeerHandle {
-    }
-
-    @Override
-    public String effectiveCwd(SpawnRequest req) {
-        return effectiveCwd(req.profileName(), req.requestedCwd(), req.callerCwd());
-    }
-
-    private 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. */
-    private String resolveEnv(String name) {
-        return (name == null || name.isBlank()) ? null : env.apply(name);
-    }
-}

bridged/src/main/resources/logback.xml

@@ -1,15 +0,0 @@
-<configuration>
-    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
-        <encoder>
-            <pattern>%d{HH:mm:ss.SSS} %-5level [%thread] %logger{28} - %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"/>
-
-    <root level="INFO">
-        <appender-ref ref="STDOUT"/>
-    </root>
-</configuration>

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

@@ -1,93 +0,0 @@
-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.util.Set;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-class BridgedConfigTest {
-
-    @Test
-    void loadsFullConfig(@TempDir Path dir) throws Exception {
-        Path f = dir.resolve("bridged.yaml");
-        Files.writeString(f, """
-                bind:
-                  host: 127.0.0.1
-                  port: 8080
-                herdrSocket: ~/.config/herdr/herdr.sock
-                worker:
-                  profile: ltms-local
-                  baseUrl: http://gx00.gw:8000
-                  model: coder
-                guard:
-                  offSubscriptionHosts:
-                    - gx00.gw
-                    - ollama.ltms.dev
-                """);
-
-        BridgedConfig cfg = BridgedConfig.load(f);
-        assertEquals(8080, cfg.bind().port());
-        assertEquals("ltms-local", cfg.worker().profile());
-        assertTrue(cfg.guard().hostSet().contains("gx00.gw"));
-        assertTrue(cfg.guard().hostSet().contains("ollama.ltms.dev"));
-    }
-
-    @Test
-    void appliesDefaultsForMissingSections(@TempDir Path dir) throws Exception {
-        Path f = dir.resolve("minimal.yaml");
-        Files.writeString(f, "bind:\n  host: 0.0.0.0\n  port: 9000\n");
-
-        BridgedConfig cfg = BridgedConfig.load(f);
-        assertEquals(9000, cfg.bind().port());
-        assertNotNull(cfg.guard(), "guard must default to empty, never null");
-        assertTrue(cfg.guard().offSubscriptionHosts().isEmpty());
-    }
-
-    @Test
-    void singleWorkerBecomesAOneEntryProfileMapWithItselfAsDefault(@TempDir Path dir) throws Exception {
-        Path f = dir.resolve("single.yaml");
-        Files.writeString(f, """
-                worker:
-                  profile: ltms-local
-                  baseUrl: http://gx00.gw:8000
-                """);
-
-        BridgedConfig cfg = BridgedConfig.load(f);
-        assertEquals(Set.of("ltms-local"), cfg.workerProfiles().keySet(), "legacy worker → one profile");
-        assertEquals("ltms-local", cfg.defaultProfile());
-    }
-
-    @Test
-    void loadsMultipleWorkerProfilesWithADefault(@TempDir Path dir) throws Exception {
-        Path f = dir.resolve("multi.yaml");
-        Files.writeString(f, """
-                workers:
-                  gx10:
-                    baseUrl: http://gx10.gw:8000
-                    argv: ["ccs", "gx10"]
-                  ollama:
-                    baseUrl: http://ollama.ltms.dev
-                    argv: ["ccs", "ollama"]
-                defaultWorker: gx10
-                guard:
-                  offSubscriptionHosts: [gx10.gw, ollama.ltms.dev]
-                """);
-
-        BridgedConfig cfg = BridgedConfig.load(f);
-        assertEquals(Set.of("gx10", "ollama"), cfg.workerProfiles().keySet());
-        assertEquals("gx10", cfg.defaultProfile());
-        assertEquals("ollama", cfg.workerProfiles().get("ollama").profile(), "profile defaults to its map key");
-        assertEquals("http://gx10.gw:8000", cfg.workerProfiles().get("gx10").baseUrl());
-    }
-
-    @Test
-    void ignoresUnknownKeys(@TempDir Path dir) throws Exception {
-        Path f = dir.resolve("future.yaml");
-        Files.writeString(f, "bind:\n  port: 8080\nfutureFeature:\n  enabled: true\n");
-        assertDoesNotThrow(() -> BridgedConfig.load(f));
-    }
-}

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

@@ -1,63 +0,0 @@
-package dev.ltms.bridged.herdr;
-
-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.*;
-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.
- *
- * <p>Tagged {@code contract}; run with {@code mvn test -Pcontract}.
- */
-@Tag("contract")
-class AgentControlContractTest {
-
-    private boolean noSocket() {
-        return !Files.exists(UnixSocketHerdrClient.defaultSocketPath());
-    }
-
-    @Test
-    void startInjectsEnvThenReadAndClose() 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"),
-                    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.
-                Thread.sleep(800);
-                String visible = agents.read(probe.terminalId(), "visible");
-                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");
-            } finally {
-                agents.close(probe.paneId());
-            }
-
-            // 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

@@ -1,40 +0,0 @@
-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. */
-class AgentControlTest {
-
-    /** The {@code text} of every agent.send, in call order. */
-    @SuppressWarnings("unchecked")
-    private static List<String> sendTexts(FakeHerdr herdr) {
-        return herdr.calls.stream()
-                .filter(c -> c.method().equals("agent.send"))
-                .map(c -> ((Map<String, Object>) c.params()).get("text").toString())
-                .toList();
-    }
-
-    @Test
-    void sendDeliversThePayloadThenAStandaloneSubmitKey() {
-        FakeHerdr herdr = new FakeHerdr();
-        new AgentControl(herdr).send("term_x", "do the thing");
-
-        // The Enter must be its own event — appended to the paste it would be swallowed as text.
-        assertEquals(List.of("do the thing", "\r"), sendTexts(herdr),
-                "payload paste first, then a separate carriage-return keystroke to submit it");
-    }
-
-    @Test
-    void sendPreservesEmbeddedNewlinesAndSubmitsOnlyOnce() {
-        FakeHerdr herdr = new FakeHerdr();
-        new AgentControl(herdr).send("term_x", "line1\nline2");
-
-        assertEquals(List.of("line1\nline2", "\r"), sendTexts(herdr),
-                "multiline content is delivered verbatim; a single trailing Enter submits it");
-    }
-}

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

@@ -1,208 +0,0 @@
-package dev.ltms.bridged.herdr;
-
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-
-import java.util.ArrayList;
-import java.util.List;
-
-/**
- * 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.
- */
-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<>();
-    private int agentNameTakenFor = 0;
-    private int workerTabPaneCount = 1;
-    private String paneCloseErrorCode = null;
-    private String agentSendErrorCode = null;
-    private volatile String agentStatus = "idle"; // steady-state agent.get status
-    private volatile String readText = "worker transcript tail"; // canned agent.read output
-
-    public FakeHerdr healthy(boolean h) {
-        this.healthy = h;
-        return this;
-    }
-
-    /** Reject the first {@code n} {@code agent.start} calls with {@code agent_name_taken}. */
-    public FakeHerdr agentNameTakenTimes(int n) {
-        this.agentNameTakenFor = 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;
-        return this;
-    }
-
-    /** Make {@code pane.close} fail with this herdr error code. */
-    public FakeHerdr paneCloseFailsWith(String code) {
-        this.paneCloseErrorCode = code;
-        return this;
-    }
-
-    /** Set the {@code agent_status} that {@code agent.get} reports (drives the injector). */
-    public FakeHerdr agentStatus(String status) {
-        this.agentStatus = status;
-        return this;
-    }
-
-    /** The text {@code agent.read} returns (the CB-106 completion scrape). */
-    public FakeHerdr readText(String text) {
-        this.readText = text;
-        return this;
-    }
-
-    /** Make {@code agent.send} fail with this herdr error code. */
-    public FakeHerdr agentSendFailsWith(String code) {
-        this.agentSendErrorCode = code;
-        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 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,"
-                + "\"pane_count\":1,\"active_tab_id\":\"%s:t1\",\"agent_status\":\"unknown\"}")
-                .formatted(id, label, id));
-        return this;
-    }
-
-    public boolean called(String method) {
-        return calls.stream().anyMatch(c -> c.method().equals(method));
-    }
-
-    public Call lastCall(String method) {
-        return calls.stream().filter(c -> c.method().equals(method))
-                .reduce((_, b) -> b).orElseThrow();
-    }
-
-    @Override
-    public JsonNode call(String method, Object params) {
-        calls.add(new Call(method, params));
-        if (!healthy) throw new HerdrException("herdr unreachable (fake)");
-        try {
-            return switch (method) {
-                case "ping" -> mapper.readTree(
-                        "{\"type\":\"pong\",\"version\":\"0.7.0\",\"protocol\":14}");
-                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(("""
-                        {"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"}%s]}""")
-                        .formatted(extraAgents.isEmpty() ? "" : "," + String.join(",", extraAgents)));
-                case "agent.send" -> {
-                    if (agentSendErrorCode != null) {
-                        throw new HerdrException("herdr error [" + agentSendErrorCode + "]: agent.send failed",
-                                agentSendErrorCode, null);
-                    }
-                    yield mapper.readTree("{\"type\":\"ok\"}");
-                }
-                case "agent.get" -> mapper.readTree(("""
-                        {"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" -> {
-                    long starts = calls.stream().filter(c -> c.method().equals("agent.start")).count();
-                    if (starts <= agentNameTakenFor) {
-                        throw new HerdrException(
-                                "herdr error [agent_name_taken]: agent name already used",
-                                "agent_name_taken", null);
-                    }
-                    long n = starts - agentNameTakenFor;
-                    yield mapper.readTree(("""
-                        {"type":"agent_started","agent":{
-                          "terminal_id":"term_new_%d","name":"claude","agent_status":"unknown",
-                          "workspace_id":"w9","tab_id":"w9:t2","pane_id":"w9:pW_%d"}}""")
-                            .formatted(n, n));
-                }
-                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("""
-                        {"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"}}""");
-                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(("""
-                        {"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));
-                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",
-                                paneCloseErrorCode, null);
-                    }
-                    yield mapper.readTree("{\"type\":\"ok\"}");
-                }
-                default -> throw new HerdrException("fake has no canned response for " + method);
-            };
-        } catch (HerdrException e) {
-            throw e; // intentional protocol errors (e.g. agent_name_taken) propagate with their code
-        } catch (Exception e) {
-            throw new HerdrException("fake decode failed for " + method, e);
-        }
-    }
-
-    @Override
-    public void close() {
-    }
-}

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

@@ -1,43 +0,0 @@
-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.List;
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.*;
-import static org.junit.jupiter.api.Assumptions.assumeTrue;
-
-/**
- * Contract test for the herdr half of connection-based identity against a REAL herdr: spawn a
- * harmless probe, read its actual {@code shell_pid} from {@code pane.process_info}, and confirm
- * {@link PaneLocator} resolves that PID back to the probe's own {@code terminal_id}.
- *
- * <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()) {
-            AgentControl agents = new AgentControl(herdr);
-            Agent probe = agents.start("__pidprobe__", List.of("bash", "-c", "sleep 20"), Map.of());
-            try {
-                JsonNode info = herdr.call("pane.process_info", Map.of("pane_id", probe.paneId()))
-                        .path("process_info");
-                long shellPid = info.path("shell_pid").asLong(-1);
-                assertTrue(shellPid > 0, "probe pane should report a shell pid");
-
-                assertEquals(probe.terminalId(), new PaneLocator(herdr).terminalForPid(shellPid),
-                        "a real PID must resolve back to its own pane's terminal_id");
-            } finally {
-                agents.close(probe.paneId());
-            }
-        }
-    }
-}

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

@@ -1,27 +0,0 @@
-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/inject/CompletionResolverTest.java

@@ -1,227 +0,0 @@
-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 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());
-    }
-
-    // --- 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.
-        assertTrue(rendezvous.resolve("term_a", "N replied"));
-
-        // Turn N+1's send opens its own waiter on the same session (replacing the registered one).
-        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/mcp/BridgeMcpTest.java

@@ -1,288 +0,0 @@
-package dev.ltms.bridged.mcp;
-
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.FakeHerdr;
-import dev.ltms.bridged.herdr.WorkspaceControl;
-import dev.ltms.bridged.inject.Injector;
-import dev.ltms.bridged.msg.MessageService;
-import dev.ltms.bridged.msg.Rendezvous;
-import dev.ltms.bridged.session.FakeWorktrees;
-import dev.ltms.bridged.session.SessionManager;
-import dev.ltms.bridged.session.WorkerSession;
-import dev.ltms.bridged.session.WorktreeRequest;
-import dev.ltms.bridged.worker.ClaudeCodeLauncher;
-import io.modelcontextprotocol.spec.McpSchema;
-import org.junit.jupiter.api.Test;
-
-import java.util.Map;
-import java.util.Set;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.TimeUnit;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-/**
- * Parity tests for the MCP tool adapters — they must produce the same outcomes as the REST routes,
- * since both drive the same {@link MessageService}/{@link Rendezvous}. The MCP wire protocol itself
- * is the SDK's concern; here we test the thin adapter logic directly.
- */
-class BridgeMcpTest {
-
-    private final FakeHerdr herdr = new FakeHerdr();
-    private final AgentControl agents = new AgentControl(herdr);
-    private final Rendezvous rendezvous = new Rendezvous();
-    private final MessageService messages = new MessageService(agents, new Injector(agents), rendezvous);
-
-    private static String textOf(McpSchema.CallToolResult r) {
-        return ((McpSchema.TextContent) r.content().getFirst()).text();
-    }
-
-    private static ClaudeCodeLauncher workerService(FakeHerdr h, String baseUrl, Set<String> allow) {
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "ltms-local", baseUrl, "coder", null, "BRIDGED_WORKER_TOKEN", null,
-                "tab", "bridged-workers", "worker: {profile} #{n}", null, null, null);
-        return new ClaudeCodeLauncher(new AgentControl(h), new WorkspaceControl(h),
-                new SubscriptionGuard(allow), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> "tok");
-    }
-
-    private static SessionManager sessionManager(FakeHerdr h, String baseUrl, Set<String> allow) {
-        return new SessionManager(workerService(h, baseUrl, allow));
-    }
-
-    @Test
-    void sendThenReplyRoundTrips() throws Exception {
-        // bridge_send blocks; bridge_reply resolves it with the worker's structured answer.
-        CompletableFuture<McpSchema.CallToolResult> send = CompletableFuture.supplyAsync(
-                () -> BridgeMcp.send(messages, "term_a", "review this", 4000L));
-
-        McpSchema.CallToolResult reply = BridgeMcp.reply(rendezvous, "term_a", "LGTM");
-        long deadline = System.currentTimeMillis() + 3000;
-        while (Boolean.TRUE.equals(reply.isError()) && System.currentTimeMillis() < deadline) {
-            //noinspection BusyWait
-            Thread.sleep(10);
-            reply = BridgeMcp.reply(rendezvous, "term_a", "LGTM");
-        }
-        assertEquals("delivered", textOf(reply));
-
-        McpSchema.CallToolResult res = send.get(6, TimeUnit.SECONDS);
-        assertNotEquals(Boolean.TRUE, res.isError());
-        assertEquals("LGTM", textOf(res));
-    }
-
-    @Test
-    void asyncSendReturnsATicketThenPollReportsTheReply() throws Exception {
-        // wait:false parity — a ticket is issued, resolved by a reply, and surfaced by bridge_poll.
-        McpSchema.CallToolResult accepted = BridgeMcp.sendAsync(messages, "term_a", "do it");
-        assertNotEquals(Boolean.TRUE, accepted.isError());
-        String out = textOf(accepted);
-        assertTrue(out.contains("ticket="), out);
-        String ticket = out.substring(out.indexOf("ticket=") + "ticket=".length()).trim();
-
-        // Resolve the awaiting send once it has opened (retry past the async-open race).
-        long deadline = System.currentTimeMillis() + 3000;
-        McpSchema.CallToolResult reply = BridgeMcp.reply(rendezvous, "term_a", "async LGTM");
-        while (Boolean.TRUE.equals(reply.isError()) && System.currentTimeMillis() < deadline) {
-            //noinspection BusyWait
-            Thread.sleep(10);
-            reply = BridgeMcp.reply(rendezvous, "term_a", "async LGTM");
-        }
-        assertEquals("delivered", textOf(reply));
-
-        // Poll until the async send completes and reports the reply.
-        McpSchema.CallToolResult polled = BridgeMcp.poll(messages, ticket);
-        deadline = System.currentTimeMillis() + 3000;
-        while (!textOf(polled).contains("async LGTM") && System.currentTimeMillis() < deadline) {
-            //noinspection BusyWait
-            Thread.sleep(10);
-            polled = BridgeMcp.poll(messages, ticket);
-        }
-        assertEquals("async LGTM", textOf(polled));
-    }
-
-    @Test
-    void pollUnknownTicketIsAnError() {
-        McpSchema.CallToolResult res = BridgeMcp.poll(messages, "task-999");
-        assertTrue(res.isError());
-        assertTrue(textOf(res).contains("unknown ticket"));
-    }
-
-    @Test
-    void sendTimesOutWithAWorkingNote() {
-        McpSchema.CallToolResult res = BridgeMcp.send(messages, "term_a", "hi", 120L);
-        assertNotEquals(Boolean.TRUE, res.isError(), "a timeout is informational, not a tool error");
-        assertTrue(textOf(res).contains("no reply"), "got: " + textOf(res));
-    }
-
-    @Test
-    void sendRejectsMissingArgs() {
-        assertTrue(BridgeMcp.send(messages, null, "hi", null).isError());
-        assertTrue(BridgeMcp.send(messages, "term_a", "  ", null).isError());
-    }
-
-    @Test
-    void replyWithNoPendingSendIsAnError() {
-        McpSchema.CallToolResult res = BridgeMcp.reply(rendezvous, "term_a", "orphan");
-        assertTrue(res.isError());
-        assertTrue(textOf(res).contains("no send is awaiting"));
-    }
-
-    @Test
-    void askThenAnswerRoundTrips() throws Exception {
-        // The primary delegates and blocks; wait until its waiter is open before the worker asks.
-        CompletableFuture<McpSchema.CallToolResult> send = CompletableFuture.supplyAsync(
-                () -> BridgeMcp.send(messages, "term_a", "do X", 5000L));
-        long deadline = System.currentTimeMillis() + 3000;
-        while (!rendezvous.isWaiting("term_a") && System.currentTimeMillis() < deadline) {
-            //noinspection BusyWait
-            Thread.sleep(5);
-        }
-        assertTrue(rendezvous.isWaiting("term_a"), "the send must be waiting for the ask to surface to");
-
-        // The worker asks mid-turn; the call blocks for the primary's answer.
-        CompletableFuture<McpSchema.CallToolResult> ask = CompletableFuture.supplyAsync(
-                () -> BridgeMcp.ask(messages, "term_a", "which config?", 5000L));
-
-        // The primary's send unblocks with the question and a turnId to answer on.
-        McpSchema.CallToolResult q = send.get(6, TimeUnit.SECONDS);
-        assertNotEquals(Boolean.TRUE, q.isError());
-        String qt = textOf(q);
-        assertTrue(qt.contains("[question]"), qt);
-        String afterMarker = qt.substring(qt.indexOf("turnId=\"") + "turnId=\"".length());
-        String turnId = afterMarker.substring(0, afterMarker.indexOf('"'));
-
-        // The primary answers via bridge_send(turnId); this blocks again for the worker's reply.
-        CompletableFuture<McpSchema.CallToolResult> answer = CompletableFuture.supplyAsync(
-                () -> BridgeMcp.answer(messages, turnId, "config.yaml", 5000L));
-
-        // The worker's ask returns the answer — it resumes the same turn.
-        assertEquals("config.yaml", textOf(ask.get(6, TimeUnit.SECONDS)));
-
-        // The resumed worker replies, resolving the answering send (retry past the reopen race).
-        McpSchema.CallToolResult reply = BridgeMcp.reply(rendezvous, "term_a", "done");
-        deadline = System.currentTimeMillis() + 3000;
-        while (Boolean.TRUE.equals(reply.isError()) && System.currentTimeMillis() < deadline) {
-            //noinspection BusyWait
-            Thread.sleep(10);
-            reply = BridgeMcp.reply(rendezvous, "term_a", "done");
-        }
-        assertEquals("delivered", textOf(reply));
-        assertEquals("done", textOf(answer.get(6, TimeUnit.SECONDS)));
-    }
-
-    @Test
-    void askFromANonWorkerConnectionIsAnError() {
-        McpSchema.CallToolResult res = BridgeMcp.ask(messages, null, "which config?", 500L);
-        assertTrue(res.isError());
-        assertTrue(textOf(res).contains("workers only"), textOf(res));
-    }
-
-    @Test
-    void answerToAStaleTurnIsAnError() {
-        McpSchema.CallToolResult res = BridgeMcp.answer(messages, "term_a#999", "too late", 500L);
-        assertTrue(res.isError());
-        assertTrue(textOf(res).contains("no longer open"), textOf(res));
-    }
-
-    @Test
-    void spawnReturnsTheNewWorkersSessionAndPane() {
-        FakeHerdr h = new FakeHerdr();
-        McpSchema.CallToolResult res = BridgeMcp.spawn(
-                sessionManager(h, "http://gx00.gw:8000", Set.of("gx00.gw")), null);
-        assertNotEquals(Boolean.TRUE, res.isError());
-        String out = textOf(res);
-        assertTrue(out.contains("\"sessionId\":\"term_new_1\""), out);
-        assertTrue(out.contains("\"paneId\":\"w9:pW_1\""), out);
-        assertTrue(out.contains("\"status\":\"spawning\""), out);
-    }
-
-    @Test
-    void spawnRejectsAnOffAllowlistProfileWithoutTouchingHerdr() {
-        FakeHerdr h = new FakeHerdr();
-        McpSchema.CallToolResult res =
-                BridgeMcp.spawn(sessionManager(h, "https://api.anthropic.com", Set.of("gx00.gw")), null);
-        assertTrue(res.isError());
-        assertTrue(textOf(res).contains("subscription boundary"));
-        assertFalse(h.called("agent.start"), "the guard must block before any spawn");
-    }
-
-    @Test
-    void spawnRejectsAnUnknownProfileAsAnError() {
-        FakeHerdr h = new FakeHerdr();
-        McpSchema.CallToolResult res =
-                BridgeMcp.spawn(sessionManager(h, "http://gx00.gw:8000", Set.of("gx00.gw")), "nope");
-        assertTrue(res.isError());
-        assertTrue(textOf(res).contains("unknown worker profile"), textOf(res));
-    }
-
-    @Test
-    void spawnPassesTheRequestedCwdToTheWorker() {
-        FakeHerdr h = new FakeHerdr();
-        McpSchema.CallToolResult res = BridgeMcp.spawn(
-                sessionManager(h, "http://gx00.gw:8000", Set.of("gx00.gw")), null, "/req/dir", null, null, null);
-        assertNotEquals(Boolean.TRUE, res.isError());
-        @SuppressWarnings("unchecked")
-        Map<String, Object> start = (Map<String, Object>) h.lastCall("agent.start").params();
-        assertEquals("/req/dir", start.get("cwd"));
-    }
-
-    @Test
-    void profilesListsConfiguredProfilesAndDefault() {
-        FakeHerdr h = new FakeHerdr();
-        McpSchema.CallToolResult res = BridgeMcp.profiles(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")));
-        assertNotEquals(Boolean.TRUE, res.isError());
-        String out = textOf(res);
-        assertTrue(out.contains("ltms-local"), out);
-        assertTrue(out.contains("\"default\":\"ltms-local\""), out);
-    }
-
-    @Test
-    void listReportsTrackedWorkers() {
-        FakeHerdr h = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt");
-        SessionManager sessions = new SessionManager(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")), worktrees);
-        WorkerSession s = sessions.acquire("ltms-local", null, "/caller/proj", "term_primary",
-                new WorktreeRequest("cb-304", null));
-
-        McpSchema.CallToolResult res = BridgeMcp.listWorkers(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")), sessions);
-
-        assertNotEquals(Boolean.TRUE, res.isError());
-        String out = textOf(res);
-        assertTrue(out.contains("\"sessionId\":\"" + s.terminalId() + "\""), out);
-        assertTrue(out.contains("\"paneId\":\"" + s.paneId() + "\""), out);
-        assertTrue(out.contains("\"profile\":\"ltms-local\""), out);
-        assertTrue(out.contains("\"state\":\"spawning\""), out);
-        assertTrue(out.contains("\"worktree\":\"" + s.worktree() + "\""), out);
-        assertTrue(out.contains("\"branch\":\"" + s.branch() + "\""), out);
-        assertTrue(out.contains("\"owner\":\"term_primary\""), out);
-        assertTrue(out.contains("\"liveStatus\":\"unknown\""), out);
-    }
-
-    @Test
-    void stopTearsDownAWorkerByPane() {
-        FakeHerdr h = new FakeHerdr();
-        McpSchema.CallToolResult res = BridgeMcp.stop(
-                sessionManager(h, "http://gx00.gw:8000", Set.of("gx00.gw")), "w9:pW");
-        assertNotEquals(Boolean.TRUE, res.isError());
-        assertEquals("stopped w9:pW", textOf(res));
-        assertTrue(h.called("pane.close"));
-    }
-
-    @Test
-    void stopRequiresAPaneId() {
-        FakeHerdr h = new FakeHerdr();
-        assertTrue(BridgeMcp.stop(
-                sessionManager(h, "http://gx00.gw:8000", Set.of("gx00.gw")), "  ").isError());
-    }
-
-    @Test
-    void statusReportsLiveAgentStatus() {
-        FakeHerdr blocked = new FakeHerdr().agentStatus("blocked");
-        AgentControl blockedAgents = new AgentControl(blocked);
-        McpSchema.CallToolResult res = BridgeMcp.status(
-                new MessageService(blockedAgents, new Injector(blockedAgents), rendezvous), "term_a");
-        assertNotEquals(Boolean.TRUE, res.isError());
-        assertEquals("blocked", textOf(res));
-    }
-}

bridged/src/test/java/dev/ltms/bridged/mcp/ConnectionIdentityTest.java

@@ -1,46 +0,0 @@
-package dev.ltms.bridged.mcp;
-
-import dev.ltms.bridged.herdr.FakeHerdr;
-import dev.ltms.bridged.herdr.PaneLocator;
-import org.junit.jupiter.api.Test;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-/** Connection → caller-identity resolution, with the OS peer-PID lookup faked. */
-class ConnectionIdentityTest {
-
-    private final FakeHerdr herdr = new FakeHerdr();
-
-    private ConnectionIdentity with(PeerPidLookup pids) {
-        return new ConnectionIdentity(new PaneLocator(herdr), pids);
-    }
-
-    @Test
-    void resolvesWorkerFromLoopbackPeerPid() {
-        assertEquals("term_a", with(_ -> FakeHerdr.WORKER_PID).callerTerminal("127.0.0.1", 55555));
-    }
-
-    @Test
-    void nullForOffHostCaller() {
-        // A non-loopback peer can't be an on-host worker → treat as primary/unknown.
-        assertNull(with(_ -> FakeHerdr.WORKER_PID).callerTerminal("10.0.0.9", 55555));
-    }
-
-    @Test
-    void nullWhenPidOwnsNoPane() {
-        // e.g. the primary — its PID maps to no worker pane.
-        assertNull(with(_ -> 999_999).callerTerminal("127.0.0.1", 55555));
-    }
-
-    @Test
-    void resolvesTheCallersPidAndCwd() {
-        // CB-112: the primary maps to no pane, but its PID and cwd are still readable.
-        ConnectionIdentity id = new ConnectionIdentity(
-                new PaneLocator(herdr), _ -> 999_999, pid -> pid == 999_999 ? "/main/project" : null);
-        ConnectionIdentity.Caller c = id.resolve("127.0.0.1", 55555);
-        assertNull(c.terminal(), "the primary owns no worker pane");
-        assertEquals(999_999, c.pid());
-        assertEquals("/main/project", id.cwdForPid(c.pid()), "the primary's cwd is resolvable from its PID");
-        assertNull(id.cwdForPid(-1), "no cwd for an unresolved PID");
-    }
-}

bridged/src/test/java/dev/ltms/bridged/msg/MessageServiceTest.java

@@ -1,214 +0,0 @@
-package dev.ltms.bridged.msg;
-
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.AgentStatus;
-import dev.ltms.bridged.herdr.FakeHerdr;
-import dev.ltms.bridged.herdr.HerdrException;
-import dev.ltms.bridged.inject.CompletionResolver;
-import dev.ltms.bridged.inject.Injector;
-import org.junit.jupiter.api.Test;
-
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.TimeUnit;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertNotNull;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-/**
- * The message layer's resolution paths (CB-104 reply + CB-106 completion fallback). The turn is
- * driven deterministically by feeding {@code onStatus} rather than running a real poller.
- */
-class MessageServiceTest {
-
-    private static final String T = "term_a";
-
-    private final FakeHerdr herdr = new FakeHerdr().readText("BUILD GREEN: 391 files");
-    private final AgentControl agents = new AgentControl(herdr);
-    private final Rendezvous rendezvous = new Rendezvous();
-    private final CompletionResolver completion = new CompletionResolver(agents, rendezvous);
-    private final Injector injector = new Injector(agents, completion);
-    private final MessageService messages = new MessageService(agents, injector, rendezvous);
-
-    /** Run {@code send} on a background thread; the current thread drives the worker's turn. */
-    private CompletableFuture<MessageService.Reply> sendAsync() {
-        return CompletableFuture.supplyAsync(() -> messages.send(T, "do the task", 5000));
-    }
-
-    private void awaitWaiting() throws InterruptedException {
-        long deadline = System.currentTimeMillis() + 2000;
-        while (!rendezvous.isWaiting(T) && System.currentTimeMillis() < deadline) {
-            //noinspection BusyWait
-            Thread.sleep(5);
-        }
-        assertTrue(rendezvous.isWaiting(T), "send should have opened its rendezvous waiter");
-    }
-
-    @Test
-    void completionFallbackResolvesATurnThatNeverCalledBridgeReply() throws Exception {
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-
-        herdr.readText("$ prompt");                // pre-turn pane: no answer yet (baseline reference)
-        injector.onStatus(T, AgentStatus.IDLE);    // deliver the task (baselines the pre-turn content)
-        injector.onStatus(T, AgentStatus.WORKING); // worker picks it up and works
-        herdr.readText("BUILD GREEN: 391 files");  // the worker's turn produced new output
-        injector.onStatus(T, AgentStatus.IDLE);    // working → idle: turn complete, no bridge_reply
-
-        MessageService.Reply reply = send.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.COMPLETED_UNREPLIED, reply.outcome(),
-                "an unreplied but finished turn resolves via the completion fallback");
-        assertEquals("BUILD GREEN: 391 files", reply.text(), "the scraped transcript tail is returned");
-        assertTrue(reply.completed(), "a scraped completion still counts as completed");
-    }
-
-    @Test
-    void explicitBridgeReplyResolvesAsReplied() throws Exception {
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-
-        injector.onStatus(T, AgentStatus.IDLE);    // deliver
-        injector.onStatus(T, AgentStatus.WORKING); // worker working
-        assertTrue(rendezvous.resolve(T, "LGTM ship it"), "an explicit reply resolves the send");
-
-        MessageService.Reply reply = send.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.REPLIED, reply.outcome());
-        assertEquals("LGTM ship it", reply.text());
-    }
-
-    @Test
-    void aWedgedWorkerResolvesTheSendAsFailedWithTheErrorContext() throws Exception {
-        herdr.readText("API Error: Unable to connect to API (ENOTFOUND)");
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-
-        injector.onStatus(T, AgentStatus.IDLE);    // deliver
-        injector.onStatus(T, AgentStatus.WORKING); // worker starts the turn
-        for (int i = 0; i < 130; i++) injector.onStatus(T, AgentStatus.UNKNOWN); // then wedges (CB-109)
-
-        MessageService.Reply reply = send.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.WORKER_FAILED, reply.outcome());
-        assertFalse(reply.completed(), "a wedge is terminal but not a successful completion");
-        assertTrue(reply.text().contains("ENOTFOUND"), "the error screen is carried as the failure reason");
-    }
-
-    @Test
-    void aWorkerThatVanishesMidTurnResolvesTheSendAsFailed() throws Exception {
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-
-        injector.onStatus(T, AgentStatus.IDLE);    // deliver
-        injector.onStatus(T, AgentStatus.WORKING); // worker starts the turn
-        // The worker's pane crashes — the poller sees a *_not_found and drops it (CB-110).
-        injector.drop(T, new HerdrException("worker gone", "pane_not_found", null));
-
-        MessageService.Reply reply = send.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.WORKER_FAILED, reply.outcome(),
-                "a delivered send whose worker vanishes fails instead of hanging to the timeout");
-        assertFalse(reply.completed());
-    }
-
-    // --- bridge_ask reverse rendezvous (CB-205) ------------------------------------------------
-
-    @Test
-    void askSurfacesAsAQuestionAndTheAnswerResumesTheSameTurn() throws Exception {
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-        injector.onStatus(T, AgentStatus.IDLE);    // deliver
-        injector.onStatus(T, AgentStatus.WORKING); // worker picks it up, then pauses to ask
-
-        // The worker asks mid-turn on its own thread; the call blocks for the primary's answer.
-        CompletableFuture<MessageService.AskResult> ask =
-                CompletableFuture.supplyAsync(() -> messages.ask(T, "which config file?", 5000));
-
-        // The primary's blocking send unblocks with the question and a turnId to answer on.
-        MessageService.Reply q = send.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.QUESTION, q.outcome());
-        assertEquals("which config file?", q.text());
-        assertNotNull(q.turnId(), "a question carries a turnId to answer on");
-
-        // The primary answers via bridge_send(turnId); this blocks again for the worker's reply.
-        CompletableFuture<MessageService.Reply> answer =
-                CompletableFuture.supplyAsync(() -> messages.answer(q.turnId(), "config.yaml", 5000));
-
-        // The worker's ask returns the answer — it resumes the same turn.
-        MessageService.AskResult a = ask.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.AskOutcome.ANSWERED, a.outcome());
-        assertEquals("config.yaml", a.answer());
-
-        // The resumed worker finishes with a structured reply, resolving the answering send.
-        awaitWaiting(); // the answering send has (re)opened its forward waiter
-        assertTrue(rendezvous.resolve(T, "done"), "the worker's final reply resolves the answering send");
-        MessageService.Reply done = answer.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.REPLIED, done.outcome());
-        assertEquals("done", done.text());
-    }
-
-    @Test
-    void duplicateAsksFromTheSameSessionCoalesceToOneTurn() throws Exception {
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-        injector.onStatus(T, AgentStatus.IDLE);    // deliver
-        injector.onStatus(T, AgentStatus.WORKING); // worker picks it up, then pauses to ask
-
-        // A transport retry: two concurrent bridge_ask calls from the same worker session.
-        CompletableFuture<MessageService.AskResult> ask1 =
-                CompletableFuture.supplyAsync(() -> messages.ask(T, "which config file?", 5000));
-        CompletableFuture<MessageService.AskResult> ask2 =
-                CompletableFuture.supplyAsync(() -> messages.ask(T, "which config file?", 5000));
-
-        // The primary's single blocked send surfaces exactly ONE question (one turnId).
-        MessageService.Reply q = send.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.QUESTION, q.outcome());
-        assertEquals("which config file?", q.text());
-        assertNotNull(q.turnId(), "only one turnId should be minted");
-
-        // The primary answers that one turnId; both asks unblock with the same answer.
-        CompletableFuture<MessageService.Reply> answer =
-                CompletableFuture.supplyAsync(() -> messages.answer(q.turnId(), "config.yaml", 5000));
-
-        MessageService.AskResult a1 = ask1.get(5, TimeUnit.SECONDS);
-        MessageService.AskResult a2 = ask2.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.AskOutcome.ANSWERED, a1.outcome());
-        assertEquals("config.yaml", a1.answer());
-        assertEquals(MessageService.AskOutcome.ANSWERED, a2.outcome());
-        assertEquals("config.yaml", a2.answer());
-
-        // The resumed worker finishes with a structured reply, resolving the answering send.
-        awaitWaiting();
-        assertTrue(rendezvous.resolve(T, "done"), "the worker's final reply resolves the answering send");
-        MessageService.Reply done = answer.get(5, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.REPLIED, done.outcome());
-        assertEquals("done", done.text());
-    }
-
-    @Test
-    void askWithNoOpenDelegationReturnsNoWaiter() {
-        MessageService.AskResult r = messages.ask(T, "anyone listening?", 500);
-        assertEquals(MessageService.AskOutcome.NO_WAITER, r.outcome(),
-                "a question with no blocked send has no primary to answer it");
-    }
-
-    @Test
-    void askTimesOutWhenThePrimaryNeverAnswers() throws Exception {
-        CompletableFuture<MessageService.Reply> send = sendAsync();
-        awaitWaiting();
-        injector.onStatus(T, AgentStatus.IDLE);
-        injector.onStatus(T, AgentStatus.WORKING);
-
-        MessageService.AskResult r = messages.ask(T, "still there?", 200); // primary never answers
-        assertEquals(MessageService.AskOutcome.TIMED_OUT, r.outcome());
-
-        // The send itself already unblocked with the question the instant the ask surfaced.
-        MessageService.Reply q = send.get(2, TimeUnit.SECONDS);
-        assertEquals(MessageService.Outcome.QUESTION, q.outcome());
-    }
-
-    @Test
-    void answeringAnUnknownTurnIsStale() {
-        MessageService.Reply r = messages.answer(T + "#999", "too late", 500);
-        assertEquals(MessageService.Outcome.STALE_TURN, r.outcome(),
-                "an answer to a turn that never existed (or already lapsed) is stale, not a hang");
-    }
-}

bridged/src/test/java/dev/ltms/bridged/rest/BridgedAppTest.java

@@ -1,473 +0,0 @@
-package dev.ltms.bridged.rest;
-
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.FakeHerdr;
-import dev.ltms.bridged.herdr.WorkspaceControl;
-import dev.ltms.bridged.inject.Injector;
-import dev.ltms.bridged.inject.StatusPoller;
-import dev.ltms.bridged.inject.WorkerPresence;
-import dev.ltms.bridged.msg.MessageService;
-import dev.ltms.bridged.msg.Rendezvous;
-import dev.ltms.bridged.session.FakeWorktrees;
-import dev.ltms.bridged.session.GitWorktrees;
-import dev.ltms.bridged.session.SessionManager;
-import dev.ltms.bridged.session.Worktrees;
-import dev.ltms.bridged.worker.ClaudeCodeLauncher;
-import io.javalin.Javalin;
-import org.junit.jupiter.api.AfterEach;
-import org.junit.jupiter.api.Test;
-
-import java.net.URI;
-import java.net.http.HttpClient;
-import java.net.http.HttpRequest;
-import java.net.http.HttpResponse;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-/**
- * REST acceptance tests — the feature contract over plain HTTP with a fake herdr, no
- * live daemon and no Claude in the loop. This is the surface later MCP tools match by
- * parity, and where the subscription boundary and worker placement are proven at the
- * API edge.
- */
-class BridgedAppTest {
-
-    private final ObjectMapper mapper = new ObjectMapper();
-    private final HttpClient http = HttpClient.newHttpClient();
-    private WorkerPresence presence;
-    private Javalin app;
-    private StatusPoller poller;
-
-    @AfterEach
-    void stop() {
-        if (poller != null) poller.stop();
-        if (app != null) app.stop();
-    }
-
-    private int start(FakeHerdr herdr, String workerBaseUrl, Set<String> allow) {
-        return start(herdr, workerBaseUrl, allow, "tab");
-    }
-
-    private int start(FakeHerdr herdr, String workerBaseUrl, Set<String> allow, String placement) {
-        return start(herdr, workerBaseUrl, allow, placement, new GitWorktrees());
-    }
-
-    private int start(FakeHerdr herdr, String workerBaseUrl, Set<String> allow, String placement, Worktrees worktrees) {
-        BridgedConfig.Worker wcfg = new BridgedConfig.Worker(
-                "ltms-local", workerBaseUrl, "coder", null, "BRIDGED_WORKER_TOKEN", null,
-                placement, "bridged-workers", "worker: {profile} #{n}", null, null, null);
-        AgentControl agents = new AgentControl(herdr);
-        ClaudeCodeLauncher workers = new ClaudeCodeLauncher(
-                agents, new WorkspaceControl(herdr), new SubscriptionGuard(allow),
-                Map.of(wcfg.profile(), wcfg), wcfg.profile(),
-                k -> "BRIDGED_WORKER_TOKEN".equals(k) ? "tok-abc" : null);
-        SessionManager sessions = new SessionManager(workers, worktrees);
-        this.presence = sessions.asPresence();
-        Injector injector = new Injector(agents);
-        poller = new StatusPoller(agents, injector, 5); // delivers when the fake reports idle
-        poller.start();
-        Rendezvous rendezvous = new Rendezvous();
-        MessageService messages = new MessageService(agents, injector, rendezvous);
-        app = new BridgedApp(herdr, workers, sessions, messages, rendezvous, this.presence, null)
-                .build().start("127.0.0.1", 0);
-        return app.port();
-    }
-
-    private int startHealthy() {
-        return start(new FakeHerdr(), "http://gx00.gw:8000", Set.of("gx00.gw"));
-    }
-
-    private HttpResponse<String> postMessage(int port, String json) throws Exception {
-        return postJson(port, "/sessions/term_a/message", json);
-    }
-
-    private HttpResponse<String> postJson(int port, String path, String json) throws Exception {
-        HttpRequest r = HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + path))
-                .header("Content-Type", "application/json")
-                .POST(HttpRequest.BodyPublishers.ofString(json)).build();
-        return http.send(r, HttpResponse.BodyHandlers.ofString());
-    }
-
-
-    private HttpResponse<String> req(int port, String method, String path) throws Exception {
-        HttpRequest.Builder b = HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + path));
-        b = switch (method) {
-            case "POST" -> b.POST(HttpRequest.BodyPublishers.noBody());
-            case "DELETE" -> b.DELETE();
-            default -> b.GET();
-        };
-        return http.send(b.build(), HttpResponse.BodyHandlers.ofString());
-    }
-
-    @SuppressWarnings("unchecked")
-    private Map<String, Object> params(FakeHerdr herdr, String method) {
-        return (Map<String, Object>) herdr.lastCall(method).params();
-    }
-
-    @Test
-    void healthzOkWhenHerdrAnswers() throws Exception {
-        int port = startHealthy();
-        HttpResponse<String> res = req(port, "GET", "/healthz");
-        assertEquals(200, res.statusCode());
-        JsonNode body = mapper.readTree(res.body());
-        assertEquals("ok", body.get("status").asText());
-        assertEquals(14, body.get("herdr").get("protocol").asInt());
-    }
-
-    @Test
-    void healthzDegradedWhenHerdrDown() throws Exception {
-        FakeHerdr down = new FakeHerdr().healthy(false);
-        int port = start(down, "http://gx00.gw:8000", Set.of("gx00.gw"));
-        HttpResponse<String> res = req(port, "GET", "/healthz");
-        assertEquals(503, res.statusCode());
-        assertEquals("degraded", mapper.readTree(res.body()).get("status").asText());
-    }
-
-    @Test
-    void sessionsMapsWorkspaceList() throws Exception {
-        int port = startHealthy();
-        JsonNode sessions = mapper.readTree(req(port, "GET", "/sessions").body()).get("sessions");
-        assertEquals(2, sessions.size());
-        assertEquals("w1", sessions.get(0).get("id").asText());
-        assertEquals("done", sessions.get(1).get("agentStatus").asText());
-    }
-
-    @Test
-    void agentsExposesSessionUuid() throws Exception {
-        int port = startHealthy();
-        JsonNode agents = mapper.readTree(req(port, "GET", "/agents").body()).get("agents");
-        assertEquals(1, agents.size());
-        assertEquals("sess-1111", agents.get(0).get("sessionId").asText());
-        assertEquals("idle", agents.get(0).get("status").asText());
-    }
-
-    @Test
-    void spawnWorkerLandsInOwnTabInWorkerSpaceAndInjectsBaseUrl() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        HttpResponse<String> res = req(port, "POST", "/workers");
-        assertEquals(201, res.statusCode());
-        JsonNode body = mapper.readTree(res.body());
-        assertEquals("w9:pW_1", body.get("paneId").asText());
-        assertEquals("spawning", body.get("state").asText());
-
-        // Subscription boundary: agent.start carried base_url + token in its env map.
-        Map<String, Object> start = params(herdr, "agent.start");
-        @SuppressWarnings("unchecked")
-        Map<String, String> env = (Map<String, String>) start.get("env");
-        assertEquals("http://gx00.gw:8000", env.get("ANTHROPIC_BASE_URL"));
-        assertEquals("tok-abc", env.get("ANTHROPIC_AUTH_TOKEN"));
-        assertEquals(List.of("claude"), start.get("argv"));
-
-        // Placement: worker space ensured, worker started INTO its own tab, seed shell
-        // dropped, and the tab given a friendly label.
-        assertTrue(herdr.called("workspace.create"), "worker space must be found-or-created");
-        assertEquals("w9:t2", start.get("tab_id"), "worker must start into its dedicated tab");
-        assertEquals("w9:pRoot", params(herdr, "pane.close").get("pane_id"), "seed shell pane dropped");
-        assertEquals("worker: ltms-local #1", params(herdr, "tab.rename").get("label"),
-                "tab label carries the worker number so siblings stay distinct");
-    }
-
-    @Test
-    void profilesEndpointListsConfiguredProfilesAndDefault() throws Exception {
-        int port = startHealthy();
-        JsonNode body = mapper.readTree(req(port, "GET", "/profiles").body());
-        assertEquals("ltms-local", body.get("default").asText());
-        assertEquals("ltms-local", body.get("profiles").get(0).asText());
-    }
-
-    @Test
-    void workersEndpointReturnsRegistryRosterWithLiveStatus() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"), "tab",
-                new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt"));
-
-        HttpResponse<String> spawn = req(port, "POST", "/workers?worktree=true&ticket=cb-304");
-        assertEquals(201, spawn.statusCode());
-        JsonNode spawned = mapper.readTree(spawn.body());
-        String paneId = spawned.get("paneId").asText();
-
-        HttpResponse<String> res = req(port, "GET", "/workers");
-        assertEquals(200, res.statusCode());
-        JsonNode workers = mapper.readTree(res.body()).get("workers");
-        assertEquals(1, workers.size());
-        JsonNode w = workers.get(0);
-        assertEquals(spawned.get("terminalId").asText(), w.get("sessionId").asText());
-        assertEquals(paneId, w.get("paneId").asText());
-        assertEquals("ltms-local", w.get("profile").asText());
-        assertEquals("spawning", w.get("state").asText());
-        assertTrue(w.has("worktree"), "worktree-backed session exposes worktree");
-        assertTrue(w.has("branch"), "worktree-backed session exposes branch");
-        assertEquals("unknown", w.get("liveStatus").asText(),
-                "liveStatus is unknown when herdr has no matching pane");
-    }
-
-    @Test
-    void spawnWithACwdParamRootsTheWorkerThere() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-        assertEquals(201, req(port, "POST", "/workers?cwd=/tmp/proj").statusCode());
-        assertEquals("/tmp/proj", params(herdr, "agent.start").get("cwd"), "the worker starts in cwd");
-    }
-
-    @Test
-    void spawnWithAnUnknownProfileIs400() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-        HttpResponse<String> res = req(port, "POST", "/workers?profile=nope");
-        assertEquals(400, res.statusCode());
-        assertEquals("unknown_profile", mapper.readTree(res.body()).get("error").asText());
-        assertFalse(herdr.called("agent.start"), "an unknown profile must not spawn anything");
-    }
-
-    @Test
-    void spawnWorkerReusesExistingWorkerSpace() throws Exception {
-        // A space labelled "bridged-workers" already exists → no second workspace.create.
-        FakeHerdr herdr = new FakeHerdr().withWorkspace("w9", "bridged-workers");
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        assertEquals(201, req(port, "POST", "/workers").statusCode());
-        assertFalse(herdr.called("workspace.create"), "existing worker space must be reused, not recreated");
-        assertTrue(herdr.called("tab.create"), "a fresh tab is still created for the worker");
-    }
-
-    @Test
-    @SuppressWarnings("unchecked")
-    void spawnRetriesUnderAFreshNameWhenAgentNameTaken() throws Exception {
-        // herdr rejects a duplicate agent name; the service must bump and retry.
-        FakeHerdr herdr = new FakeHerdr().agentNameTakenTimes(2);
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        assertEquals(201, req(port, "POST", "/workers").statusCode());
-        List<String> names = herdr.calls.stream()
-                .filter(c -> c.method().equals("agent.start"))
-                .map(c -> ((Map<String, Object>) c.params()).get("name").toString())
-                .toList();
-        assertEquals(3, names.size(), "2 rejected + 1 success");
-        assertEquals(3, Set.copyOf(names).size(), "each attempt must use a distinct name");
-    }
-
-    @Test
-    void spawnClosesTheCreatedTabWhenTheWorkerNeverStarts() throws Exception {
-        // Every agent.start attempt is rejected → spawn fails; the tab we created must not leak.
-        FakeHerdr herdr = new FakeHerdr().agentNameTakenTimes(99);
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        assertEquals(500, req(port, "POST", "/workers").statusCode());
-        assertTrue(herdr.called("tab.create"), "a tab was created before the failed start");
-        assertEquals("w9:t2", params(herdr, "tab.close").get("tab_id"), "orphaned tab must be closed");
-    }
-
-    @Test
-    void spawnWorkerRejectsOffAllowlistBaseUrlAndNeverTouchesHerdr() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        // base_url points at the subscription — guard must block before any herdr call.
-        int port = start(herdr, "https://api.anthropic.com", Set.of("gx00.gw"));
-
-        HttpResponse<String> res = req(port, "POST", "/workers");
-        assertEquals(403, res.statusCode());
-        assertEquals("subscription_boundary", mapper.readTree(res.body()).get("error").asText());
-        assertFalse(herdr.called("agent.start"), "guard must stop the spawn before herdr");
-        assertFalse(herdr.called("workspace.create"), "guard must stop before provisioning a space");
-    }
-
-    @Test
-    void panePlacementSplitsFocusedTabWithoutADedicatedSpace() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"), "pane");
-
-        assertEquals(201, req(port, "POST", "/workers").statusCode());
-        Map<String, Object> start = params(herdr, "agent.start");
-        assertFalse(start.containsKey("tab_id"), "pane placement must not target a tab");
-        assertFalse(herdr.called("workspace.create"), "pane placement uses no dedicated space");
-        assertFalse(herdr.called("tab.create"));
-    }
-
-    @Test
-    void stopWorkerClosesPaneAndItsTab() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
-        assertTrue(herdr.called("pane.close"));
-        // Tab resolved from the pane (pane.get), then closed.
-        assertEquals("w9:t2", params(herdr, "tab.close").get("tab_id"));
-    }
-
-    @Test
-    void messageReturnsTheWorkersStructuredReply() throws Exception {
-        // CB-104 (option C): the blocking send resolves on the worker's bridge_reply, not a scrape.
-        FakeHerdr herdr = new FakeHerdr().agentStatus("idle"); // poller delivers the injection
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        var send = java.util.concurrent.CompletableFuture.supplyAsync(() -> {
-            try { return postMessage(port, "{\"content\":\"review this\",\"timeoutMs\":4000}"); }
-            catch (Exception e) { throw new RuntimeException(e); }
-        });
-
-        // The worker replies once a send is actually awaiting (retry past the startup race).
-        HttpResponse<String> reply;
-        long deadline = System.currentTimeMillis() + 3000;
-        do {
-            reply = postJson(port, "/sessions/term_a/reply", "{\"content\":\"LGTM ship it\"}");
-            if (reply.statusCode() != 409) break;
-            //noinspection BusyWait
-            Thread.sleep(10);
-        } while (System.currentTimeMillis() < deadline);
-        assertEquals(200, reply.statusCode());
-
-        HttpResponse<String> res = send.get(6, java.util.concurrent.TimeUnit.SECONDS);
-        assertEquals(200, res.statusCode());
-        assertEquals("LGTM ship it", mapper.readTree(res.body()).get("reply").asText());
-        // (injection via agent.send is covered deterministically by the timeout-working test)
-    }
-
-    @Test
-    void asyncSendReturnsATicketThenPollReportsTheReply() throws Exception {
-        // CB-107 fire-and-poll: wait:false returns a ticket immediately; the result is polled.
-        FakeHerdr herdr = new FakeHerdr().agentStatus("idle"); // poller delivers the injection
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        HttpResponse<String> accepted = postMessage(port, "{\"content\":\"do it\",\"wait\":false}");
-        assertEquals(202, accepted.statusCode());
-        String ticket = mapper.readTree(accepted.body()).get("ticket").asText();
-        assertFalse(ticket.isBlank(), "an async send must return a ticket");
-
-        // The worker replies once the async send is actually awaiting (retry past the startup race).
-        HttpResponse<String> reply;
-        long deadline = System.currentTimeMillis() + 3000;
-        do {
-            reply = postJson(port, "/sessions/term_a/reply", "{\"content\":\"async LGTM\"}");
-            if (reply.statusCode() != 409) break;
-            //noinspection BusyWait
-            Thread.sleep(10);
-        } while (System.currentTimeMillis() < deadline);
-        assertEquals(200, reply.statusCode());
-
-        // Polling the ticket now reports the finished delegation and its reply.
-        JsonNode task;
-        deadline = System.currentTimeMillis() + 3000;
-        do {
-            task = mapper.readTree(req(port, "GET", "/tasks/" + ticket).body());
-            if ("done".equals(task.path("phase").asText())) break;
-            //noinspection BusyWait
-            Thread.sleep(10);
-        } while (System.currentTimeMillis() < deadline);
-        assertEquals("done", task.get("phase").asText());
-        assertEquals("async LGTM", task.get("reply").asText());
-        assertEquals("reply", task.get("replySource").asText());
-    }
-
-    @Test
-    void pollUnknownTicketIs404() throws Exception {
-        int port = startHealthy();
-        HttpResponse<String> res = req(port, "GET", "/tasks/task-999");
-        assertEquals(404, res.statusCode());
-        assertEquals("unknown_ticket", mapper.readTree(res.body()).get("error").asText());
-    }
-
-    @Test
-    void replyWithNoPendingSendIsConflict() throws Exception {
-        int port = startHealthy();
-        HttpResponse<String> res = postJson(port, "/sessions/term_a/reply", "{\"content\":\"orphan\"}");
-        assertEquals(409, res.statusCode());
-        assertEquals("no_pending_send", mapper.readTree(res.body()).get("error").asText());
-    }
-
-    @Test
-    void messageTimesOutQueuedWhenWorkerNeverInjectable() throws Exception {
-        FakeHerdr herdr = new FakeHerdr().agentStatus("working"); // never injectable → never delivered
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        HttpResponse<String> res = postMessage(port, "{\"content\":\"hi\",\"timeoutMs\":150}");
-        assertEquals(202, res.statusCode());
-        assertEquals("queued", mapper.readTree(res.body()).get("status").asText());
-        assertFalse(herdr.called("agent.send"), "no injection while the worker is mid-turn");
-    }
-
-    @Test
-    void messageTimesOutWorkingWhenDeliveredButNoReply() throws Exception {
-        FakeHerdr herdr = new FakeHerdr().agentStatus("idle"); // delivered, but nobody replies
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        HttpResponse<String> res = postMessage(port, "{\"content\":\"hi\",\"timeoutMs\":250}");
-        assertEquals(202, res.statusCode());
-        assertEquals("working", mapper.readTree(res.body()).get("status").asText());
-        assertTrue(herdr.called("agent.send"), "message was injected");
-    }
-
-    @Test
-    void messageRejectsBlankContent() throws Exception {
-        int port = startHealthy();
-        assertEquals(400, postMessage(port, "{}").statusCode());
-    }
-
-    @Test
-    void sessionStatusReportsLiveAgentStatus() throws Exception {
-        FakeHerdr herdr = new FakeHerdr().agentStatus("blocked");
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-        HttpResponse<String> res = req(port, "GET", "/sessions/term_a/status");
-        assertEquals(200, res.statusCode());
-        assertEquals("blocked", mapper.readTree(res.body()).get("status").asText());
-    }
-
-    @Test
-    void sessionStatusReportsReadinessFromMcpPresence() throws Exception {
-        int port = start(new FakeHerdr(), "http://gx00.gw:8000", Set.of("gx00.gw"));
-        // Not yet seen on the bridge MCP → not ready.
-        assertFalse(mapper.readTree(req(port, "GET", "/sessions/term_a/status").body()).get("ready").asBoolean());
-        // Worker connects its MCP client → available.
-        presence.markPresent("term_a");
-        assertTrue(mapper.readTree(req(port, "GET", "/sessions/term_a/status").body()).get("ready").asBoolean());
-    }
-
-    @Test
-    void stopWorkerInPanePlacementClosesOnlyThePane() throws Exception {
-        FakeHerdr herdr = new FakeHerdr();
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"), "pane");
-
-        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
-        assertTrue(herdr.called("pane.close"));
-        assertFalse(herdr.called("tab.close"), "pane placement owns no tab to close");
-        assertFalse(herdr.called("pane.get"), "no tab resolution in pane placement");
-    }
-
-    @Test
-    void stopNeverClosesATabThatHoldsOtherPanes() throws Exception {
-        // The worker's tab has 2 panes (e.g. a pane-placement worker sharing a user tab).
-        FakeHerdr herdr = new FakeHerdr().withWorkerTabPaneCount(2);
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
-        assertTrue(herdr.called("pane.close"), "the worker's own pane is still closed");
-        assertFalse(herdr.called("tab.close"), "must not close a tab that holds the user's other panes");
-    }
-
-    @Test
-    void stopReportsFailureWhenPaneCloseFailsForARealReason() throws Exception {
-        FakeHerdr herdr = new FakeHerdr().paneCloseFailsWith("herdr_busy");
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        // A genuine teardown failure must surface, not be reported as a successful 204.
-        assertEquals(500, req(port, "DELETE", "/workers/w9:pW").statusCode());
-        assertFalse(herdr.called("tab.close"), "tab is not removed when the pane close failed");
-    }
-
-    @Test
-    void stopToleratesAnAlreadyGonePane() throws Exception {
-        FakeHerdr herdr = new FakeHerdr().paneCloseFailsWith("pane_not_found");
-        int port = start(herdr, "http://gx00.gw:8000", Set.of("gx00.gw"));
-
-        // Already-gone is success; the (now-empty) tab is still cleaned up.
-        assertEquals(204, req(port, "DELETE", "/workers/w9:pW").statusCode());
-        assertTrue(herdr.called("tab.close"));
-    }
-}

bridged/src/test/java/dev/ltms/bridged/session/FakeWorktrees.java

@@ -1,130 +0,0 @@
-package dev.ltms.bridged.session;
-
-import java.util.Collections;
-import java.util.List;
-import java.util.Set;
-import java.util.concurrent.ConcurrentHashMap;
-import java.util.concurrent.CopyOnWriteArrayList;
-
-/** Recording fake {@link Worktrees} for CB-301-ext acceptance tests (no live git). */
-public final class FakeWorktrees implements Worktrees {
-
-    public record AddCall(String repoRoot, String branch, String baseRef) {
-    }
-
-    public record RemoveCall(String repoRoot, String worktreePath) {
-    }
-
-    public record OverlayCall(String repoRoot, String worktreePath,
-                               List<String> requested, List<String> copied, List<String> skipWorktree) {
-    }
-
-    public record RepoRootCall(String cwd) {
-    }
-
-    private final List<AddCall> addCalls = new CopyOnWriteArrayList<>();
-    private final List<RemoveCall> removeCalls = new CopyOnWriteArrayList<>();
-    private final List<OverlayCall> overlayCalls = new CopyOnWriteArrayList<>();
-    private final List<RepoRootCall> repoRootCalls = new CopyOnWriteArrayList<>();
-    private final Set<String> existingPaths = ConcurrentHashMap.newKeySet();
-    private final Set<String> trackedPaths = ConcurrentHashMap.newKeySet();
-    private volatile RuntimeException addFailure;
-    private volatile String repoRoot = "/repo";
-    private volatile String prefix = "/worktrees";
-
-    public FakeWorktrees withRepoRoot(String root) {
-        this.repoRoot = root;
-        return this;
-    }
-
-    public FakeWorktrees withPrefix(String prefix) {
-        this.prefix = prefix;
-        return this;
-    }
-
-    /** Paths that exist in the primary repo and will be copied to the worktree. */
-    public FakeWorktrees exists(String... paths) {
-        Collections.addAll(existingPaths, paths);
-        return this;
-    }
-
-    /** Paths that exist AND are tracked, so overlayParity should --skip-worktree them. */
-    public FakeWorktrees track(String... paths) {
-        exists(paths);
-        Collections.addAll(trackedPaths, paths);
-        return this;
-    }
-
-    /** Make subsequent {@link #add} calls throw (simulates git worktree add failure). */
-    public FakeWorktrees failAdd(String message) {
-        this.addFailure = new WorktreeException(message);
-        return this;
-    }
-
-    @Override
-    public String add(String repoRoot, String branch, String baseRef) {
-        addCalls.add(new AddCall(repoRoot, branch, baseRef));
-        if (addFailure != null) {
-            throw addFailure;
-        }
-        // The branch already carries a unique nonce, so the derived path is distinct per acquire
-        // without an extra counter — keep it a pure function of the branch the test can predict.
-        return prefix + "/" + branch.replace('/', '_');
-    }
-
-    @Override
-    public void remove(String repoRoot, String worktreePath) {
-        removeCalls.add(new RemoveCall(repoRoot, worktreePath));
-    }
-
-    @Override
-    public void overlayParity(String repoRoot, String worktreePath, List<String> overlay) {
-        List<String> copied = new java.util.ArrayList<>();
-        List<String> skipped = new java.util.ArrayList<>();
-        for (String rel : overlay) {
-            if (!existingPaths.contains(rel)) {
-                continue; // missing source is silently skipped
-            }
-            copied.add(rel);
-            if (trackedPaths.contains(rel)) {
-                skipped.add(rel);
-            }
-        }
-        overlayCalls.add(new OverlayCall(repoRoot, worktreePath, List.copyOf(overlay),
-                List.copyOf(copied), List.copyOf(skipped)));
-    }
-
-    @Override
-    public String repoRoot(String cwd) {
-        repoRootCalls.add(new RepoRootCall(cwd));
-        return repoRoot;
-    }
-
-    public List<AddCall> addCalls() {
-        return List.copyOf(addCalls);
-    }
-
-    public List<RemoveCall> removeCalls() {
-        return List.copyOf(removeCalls);
-    }
-
-    public List<OverlayCall> overlayCalls() {
-        return List.copyOf(overlayCalls);
-    }
-
-    public List<RepoRootCall> repoRootCalls() {
-        return List.copyOf(repoRootCalls);
-    }
-
-    public AddCall lastAdd() {
-        return addCalls.isEmpty() ? null : addCalls.getLast();
-    }
-
-    public RemoveCall lastRemove() {
-        return removeCalls.isEmpty() ? null : removeCalls.getLast();
-    }
-
-    public OverlayCall lastOverlay() {
-        return overlayCalls.isEmpty() ? null : overlayCalls.getLast();
-    }
-}

bridged/src/test/java/dev/ltms/bridged/session/SessionManagerTest.java

@@ -1,335 +0,0 @@
-package dev.ltms.bridged.session;
-
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.FakeHerdr;
-import dev.ltms.bridged.herdr.WorkspaceControl;
-import dev.ltms.bridged.worker.ClaudeCodeLauncher;
-import org.junit.jupiter.api.Test;
-
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-import java.util.concurrent.TimeUnit;
-import java.util.function.LongSupplier;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-/**
- * CB-301 / CB-303 acceptance tests for the authoritative session registry, one-shot lifecycle FSM,
- * and configurable lifecycle limits (idle TTL, context cap, drain).
- * No live herdr — everything runs against the same {@link FakeHerdr} the rest of the project uses.
- */
-class SessionManagerTest {
-
-    private SessionManager sessionManager(FakeHerdr herdr) {
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
-                List.of("ccs", "ltms-local"), "tab", "bridged-workers",
-                "worker: {profile} #{n}", null, null, null);
-        ClaudeCodeLauncher workers = new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null);
-        return new SessionManager(workers);
-    }
-
-    private SessionManager sessionManager(FakeHerdr herdr, LongSupplier clock) {
-        return sessionManager(herdr, clock, 0);
-    }
-
-    private SessionManager sessionManager(FakeHerdr herdr, LongSupplier clock, int contextCap) {
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
-                List.of("ccs", "ltms-local"), "tab", "bridged-workers",
-                "worker: {profile} #{n}", null, null, null);
-        ClaudeCodeLauncher workers = new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null);
-        return new SessionManager(workers, new GitWorktrees(), clock, contextCap);
-    }
-
-    @Test
-    void acquireRegistersSpawningSessionWithDistinctPaneId() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr);
-
-        WorkerSession a = sessions.acquire("ltms-local", "/work/a", "/caller/a", "term_primary");
-        WorkerSession b = sessions.acquire("ltms-local", "/work/b", "/caller/b", "term_primary");
-
-        assertEquals(WorkerSession.State.SPAWNING, a.state(), "fresh session starts spawning");
-        assertEquals("ltms-local", a.profile());
-        assertEquals("/work/a", a.cwd(), "explicit requested cwd is recorded");
-        assertEquals("term_primary", a.ownerTerminal());
-        assertTrue(a.spawnedAtNanos() > 0);
-        assertNotNull(a.paneId());
-        assertNotNull(a.terminalId());
-
-        assertNotEquals(a.paneId(), b.paneId(), "no pane reuse");
-        assertNotEquals(a.terminalId(), b.terminalId(), "no terminal reuse");
-        assertEquals(2, sessions.roster().size(), "both sessions are registered");
-    }
-
-    @Test
-    void presenceMovesSpawningToReadyAndDeliveredTurnMovesToDone() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-
-        sessions.asPresence().markPresent(terminal);
-        assertEquals(WorkerSession.State.READY, sessions.get(session.paneId()).orElseThrow().state(),
-                "MCP presence moves SPAWNING → READY");
-        assertTrue(sessions.asPresence().isPresent(terminal), "presence is also recorded");
-
-        sessions.onDelivered(terminal);
-        assertEquals(WorkerSession.State.BUSY, sessions.get(session.paneId()).orElseThrow().state(),
-                "delivery moves READY → BUSY");
-
-        sessions.onTurnComplete(terminal);
-        assertEquals(WorkerSession.State.DONE, sessions.get(session.paneId()).orElseThrow().state(),
-                "turn completion moves BUSY → DONE");
-    }
-
-    @Test
-    void releaseTearsDownWorkerAndRemovesFromRosterAndIsIdempotent() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", null);
-        String paneId = session.paneId();
-
-        sessions.release(paneId);
-
-        assertTrue(herdr.called("pane.close"), "release tears the worker pane down");
-        assertTrue(sessions.get(paneId).isEmpty(), "released session is no longer retrievable");
-        assertTrue(sessions.roster().isEmpty(), "released session is no longer in the roster");
-
-        assertDoesNotThrow(() -> sessions.release(paneId), "a second release is harmless");
-    }
-
-    @Test
-    void onTurnFailedMovesSessionToFailed() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-        sessions.onDelivered(terminal);
-
-        sessions.onTurnFailed(terminal);
-
-        WorkerSession updated = sessions.get(session.paneId()).orElseThrow();
-        assertEquals(WorkerSession.State.FAILED, updated.state(), "turn failure moves to FAILED");
-        assertTrue(sessions.roster().contains(updated), "FAILED is still in acquired-minus-released roster");
-    }
-
-    @Test
-    void recycleProducesNewPaneIdAndOldOneIsGone() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr);
-        WorkerSession oldSession = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String oldPane = oldSession.paneId();
-        String oldTerminal = oldSession.terminalId();
-
-        WorkerSession fresh = sessions.recycle(oldPane);
-
-        assertNotEquals(oldPane, fresh.paneId(), "recycle yields a new pane id");
-        assertNotEquals(oldTerminal, fresh.terminalId(), "recycle yields a new terminal id");
-        assertEquals(oldSession.profile(), fresh.profile(), "profile is preserved");
-        assertEquals(oldSession.cwd(), fresh.cwd(), "cwd is preserved");
-        assertEquals(oldSession.ownerTerminal(), fresh.ownerTerminal(), "owner is preserved");
-
-        assertTrue(sessions.get(oldPane).isEmpty(), "old pane is deregistered");
-        assertEquals(1, sessions.roster().size(), "only the fresh session remains");
-        assertEquals(fresh.paneId(), sessions.roster().getFirst().paneId());
-
-        long paneCloseCount = herdr.calls.stream()
-                .filter(c -> "pane.close".equals(c.method()))
-                .filter(c -> oldPane.equals(((Map<?, ?>) c.params()).get("pane_id")))
-                .count();
-        assertEquals(1, paneCloseCount, "the old worker was torn down");
-    }
-
-    @Test
-    void rosterReflectsAcquiredMinusReleased() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr);
-        WorkerSession a = sessions.acquire("ltms-local", "/a", "/caller", "ownerA");
-        WorkerSession b = sessions.acquire("ltms-local", "/b", "/caller", "ownerB");
-
-        assertEquals(2, sessions.roster().size());
-        assertTrue(sessions.roster().stream().anyMatch(s -> s.paneId().equals(a.paneId())));
-        assertTrue(sessions.roster().stream().anyMatch(s -> s.paneId().equals(b.paneId())));
-
-        sessions.release(a.paneId());
-
-        assertEquals(1, sessions.roster().size());
-        assertEquals(b.paneId(), sessions.roster().getFirst().paneId());
-    }
-
-    // --- CB-303 lifecycle limits ----------------------------------------------------
-
-    @Test
-    void reapIdleDoesNothingWhenNoSessions() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> 0L);
-
-        assertEquals(0, sessions.reapIdle(10));
-        assertTrue(sessions.roster().isEmpty());
-    }
-
-    @Test
-    void readySessionPastIdleTtlIsReaped() {
-        long[] clock = {0};
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> clock[0]);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-
-        clock[0] = 11;
-        assertEquals(1, sessions.reapIdle(10), "READY session past TTL is reaped");
-        assertTrue(sessions.get(session.paneId()).isEmpty(), "reaped session is removed from registry");
-        assertTrue(herdr.called("pane.close"), "reaped session tears the pane down");
-    }
-
-    @Test
-    void readySessionWithinIdleTtlSurvives() {
-        long[] clock = {0};
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> clock[0]);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-
-        clock[0] = 5;
-        assertEquals(0, sessions.reapIdle(10), "READY session within TTL is not reaped");
-        assertEquals(WorkerSession.State.READY,
-                sessions.get(session.paneId()).orElseThrow().state(),
-                "READY session survives");
-    }
-
-    @Test
-    void busySessionPastIdleTtlIsNotReaped() {
-        long[] clock = {0};
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> clock[0]);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-        sessions.onDelivered(terminal);
-
-        clock[0] = 100;
-        assertEquals(0, sessions.reapIdle(10), "BUSY session past TTL is never reaped");
-        assertEquals(WorkerSession.State.BUSY,
-                sessions.get(session.paneId()).orElseThrow().state(),
-                "BUSY session remains");
-    }
-
-    @Test
-    void doneSessionPastIdleTtlIsReaped() {
-        long[] clock = {0};
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> clock[0]);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-        sessions.onDelivered(terminal);
-        sessions.onTurnComplete(terminal);
-
-        clock[0] = 21;
-        assertEquals(1, sessions.reapIdle(20), "DONE session past TTL is reaped");
-        assertTrue(sessions.get(session.paneId()).isEmpty(), "DONE session is removed");
-    }
-
-    @Test
-    void reapIdleReturnsCorrectCountAndSkipsBusy() {
-        long[] clock = {0};
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> clock[0]);
-
-        WorkerSession ready = sessions.acquire("ltms-local", "/ready", "/caller", "owner1");
-        WorkerSession busy = sessions.acquire("ltms-local", "/busy", "/caller", "owner2");
-        sessions.asPresence().markPresent(ready.terminalId());
-        sessions.asPresence().markPresent(busy.terminalId());
-        sessions.onDelivered(busy.terminalId());
-
-        clock[0] = 50;
-        assertEquals(1, sessions.reapIdle(30), "only READY past TTL is reaped");
-        assertTrue(sessions.get(ready.paneId()).isEmpty(), "READY session is gone");
-        assertEquals(WorkerSession.State.BUSY,
-                sessions.get(busy.paneId()).orElseThrow().state(),
-                "BUSY session is still registered");
-    }
-
-    @Test
-    void contextCapDisabledSessionSurvivesMultipleTurns() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> 0L, 0);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-
-        sessions.onDelivered(terminal);
-        sessions.onTurnComplete(terminal);
-        sessions.onDelivered(terminal);
-        sessions.onTurnComplete(terminal);
-
-        WorkerSession updated = sessions.get(session.paneId()).orElseThrow();
-        assertEquals(WorkerSession.State.DONE, updated.state(), "session finishes second turn");
-        assertEquals(2, updated.turnCount(), "turn count tracks both deliveries");
-        long releaseCloseCount = paneCloseCallsFor(herdr, session.paneId());
-        assertEquals(0, releaseCloseCount, "cap disabled — no forced release of the worker pane");
-    }
-
-    @Test
-    void contextCapTwoReleasesAfterSecondComplete() {
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> 0L, 2);
-        WorkerSession session = sessions.acquire("ltms-local", null, "/caller", "term_primary");
-        String terminal = session.terminalId();
-        sessions.asPresence().markPresent(terminal);
-
-        sessions.onDelivered(terminal);
-        sessions.onTurnComplete(terminal);
-        assertEquals(WorkerSession.State.DONE,
-                sessions.get(session.paneId()).orElseThrow().state(),
-                "first turn completes without release");
-
-        sessions.onDelivered(terminal);
-        sessions.onTurnComplete(terminal);
-
-        assertTrue(sessions.get(session.paneId()).isEmpty(), "session released after cap reached");
-        assertTrue(sessions.roster().isEmpty(), "released session leaves roster");
-        assertEquals(1, paneCloseCallsFor(herdr, session.paneId()),
-                "forced release tears the worker pane down exactly once");
-    }
-
-    @Test
-    void drainAllReleasesBusyAndReadySessionsAndWaitsForBusy() {
-        long[] clock = {0};
-        FakeHerdr herdr = new FakeHerdr();
-        SessionManager sessions = sessionManager(herdr, () -> clock[0]);
-
-        WorkerSession ready = sessions.acquire("ltms-local", "/ready", "/caller", "ownerR");
-        WorkerSession busy = sessions.acquire("ltms-local", "/busy", "/caller", "ownerB");
-        sessions.asPresence().markPresent(ready.terminalId());
-        sessions.asPresence().markPresent(busy.terminalId());
-        sessions.onDelivered(busy.terminalId());
-
-        sessions.drainAll(TimeUnit.MILLISECONDS.toNanos(100));
-
-        assertTrue(sessions.roster().isEmpty(), "drain clears the roster");
-        assertTrue(sessions.get(ready.paneId()).isEmpty(), "ready session is released");
-        assertTrue(sessions.get(busy.paneId()).isEmpty(), "busy session is released after timeout");
-        assertEquals(1, paneCloseCallsFor(herdr, ready.paneId()),
-                "ready worker pane is torn down");
-        assertEquals(1, paneCloseCallsFor(herdr, busy.paneId()),
-                "busy worker pane is torn down");
-    }
-
-    private static long paneCloseCallsFor(FakeHerdr herdr, String paneId) {
-        return herdr.calls.stream()
-                .filter(c -> "pane.close".equals(c.method()))
-                .filter(c -> paneId.equals(((Map<?, ?>) c.params()).get("pane_id")))
-                .count();
-    }
-}

bridged/src/test/java/dev/ltms/bridged/session/WorktreeSessionManagerTest.java

@@ -1,169 +0,0 @@
-package dev.ltms.bridged.session;
-
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.FakeHerdr;
-import dev.ltms.bridged.herdr.WorkspaceControl;
-import dev.ltms.bridged.worker.ClaudeCodeLauncher;
-import org.junit.jupiter.api.Test;
-
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-/**
- * CB-301-ext acceptance tests for worktree provisioning and config-parity overlay.
- * No live git — every Worktrees call is handled by {@link FakeWorktrees} and every herdr
- * call by {@link FakeHerdr}, matching the project's fake-based test style.
- */
-class WorktreeSessionManagerTest {
-
-    private static ClaudeCodeLauncher workerService(FakeHerdr herdr) {
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
-                List.of("ccs", "ltms-local"), "tab", "bridged-workers",
-                "worker: {profile} #{n}", null, null, null);
-        return new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null);
-    }
-
-    private static String startCwd(FakeHerdr herdr) {
-        @SuppressWarnings("unchecked")
-        Map<String, Object> start = (Map<String, Object>) herdr.lastCall("agent.start").params();
-        Object cwd = start.get("cwd");
-        return cwd == null ? null : cwd.toString();
-    }
-
-    @Test
-    void sharedTreeAcquireMakesNoWorktreesCallsAndRecordsNullWorktree() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees();
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-
-        WorkerSession s = sessions.acquire("ltms-local", null, "/caller/proj", "term_primary");
-
-        assertTrue(worktrees.addCalls().isEmpty(), "shared-tree acquire never adds a worktree");
-        assertTrue(worktrees.repoRootCalls().isEmpty(), "shared-tree acquire never resolves a repo root");
-        assertTrue(worktrees.overlayCalls().isEmpty(), "shared-tree acquire never overlays parity");
-        assertNull(s.worktree(), "shared-tree session has no worktree");
-        assertNull(s.branch(), "shared-tree session has no branch");
-        assertEquals("/caller/proj", s.cwd(), "shared-tree cwd is the caller's cwd");
-        assertEquals("/caller/proj", startCwd(herdr), "spawn receives the caller's cwd");
-    }
-
-    @Test
-    void worktreeAcquireProvisionsAndRecordsPathAndBranch() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt");
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-
-        WorkerSession s = sessions.acquire("ltms-local", null, "/caller/proj", "term_primary",
-                new WorktreeRequest("cb-999", null));
-
-        assertEquals(1, worktrees.addCalls().size(), "one worktree was added");
-        FakeWorktrees.AddCall add = worktrees.lastAdd();
-        assertNotNull(add);
-        assertEquals("/repo", add.repoRoot());
-        assertTrue(add.branch().startsWith("worker/cb-999-"), "branch is worker/<slug>-<nonce>: " + add.branch());
-        assertNull(add.baseRef(), "null baseRef is passed through (HEAD default)");
-
-        String expectedPath = "/wt/" + add.branch().replace('/', '_');
-        assertEquals(expectedPath, s.worktree(), "session records the returned worktree path");
-        assertEquals(add.branch(), s.branch(), "session records the branch");
-        assertEquals(expectedPath, startCwd(herdr), "spawn receives the worktree path as cwd");
-        assertEquals(expectedPath, s.cwd(), "session cwd is the worktree path");
-    }
-
-    @Test
-    void worktreeAcquireRunsParityOverlayWithProfileDefaults() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt")
-                .track(".mcp.json")
-                .exists(".claude/settings.local.json");
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-
-        sessions.acquire("ltms-local", null, "/caller/proj", null,
-                new WorktreeRequest("cb-888", null));
-
-        assertEquals(1, worktrees.overlayCalls().size());
-        FakeWorktrees.OverlayCall overlay = worktrees.lastOverlay();
-        assertNotNull(overlay);
-        assertEquals("/repo", overlay.repoRoot());
-        assertEquals(List.of(".mcp.json", ".claude/settings.local.json", ".env", ".envrc"),
-                overlay.requested(), "default parity overlay is used when unset");
-        assertEquals(List.of(".mcp.json", ".claude/settings.local.json"), overlay.copied(),
-                "existing paths are copied; missing paths are skipped");
-        assertEquals(List.of(".mcp.json"), overlay.skipWorktree(),
-                "tracked copied paths are --skip-worktree'd");
-    }
-
-    @Test
-    void releaseRemovesWorktreeButDoesNotDeleteBranch() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt");
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-        WorkerSession s = sessions.acquire("ltms-local", null, "/caller/proj", null,
-                new WorktreeRequest("cb-666", null));
-        String paneId = s.paneId();
-
-        sessions.release(paneId);
-
-        assertTrue(herdr.called("pane.close"), "release still tears the worker pane down");
-        assertEquals(1, worktrees.removeCalls().size(), "worktree session triggers one remove");
-        FakeWorktrees.RemoveCall remove = worktrees.lastRemove();
-        assertNotNull(remove);
-        assertEquals("/repo", remove.repoRoot());
-        assertEquals(s.worktree(), remove.worktreePath());
-        // The fake records no branch-delete calls because Worktrees.remove only removes the checkout.
-        assertTrue(sessions.get(paneId).isEmpty(), "released session is no longer retrievable");
-    }
-
-    @Test
-    void sharedTreeReleaseMakesNoWorktreesCalls() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees();
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-        WorkerSession s = sessions.acquire("ltms-local", null, "/caller/proj", null);
-
-        sessions.release(s.paneId());
-
-        assertTrue(herdr.called("pane.close"), "release tears the worker pane down");
-        assertTrue(worktrees.removeCalls().isEmpty(), "shared-tree release never removes a worktree");
-    }
-
-    @Test
-    void failedWorktreeAddUnwindsWithoutRegisteringSessionOrSpawning() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees().failAdd("worktree add failed");
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-
-        assertThrows(WorktreeException.class, () ->
-                sessions.acquire("ltms-local", null, "/caller/proj", null,
-                        new WorktreeRequest("cb-555", null)));
-
-        assertEquals(0, sessions.size(), "failed acquire leaves no registry entry");
-        assertFalse(herdr.called("agent.start"), "spawn is never reached when add fails");
-        assertTrue(worktrees.removeCalls().isEmpty(), "no worktree was added, so none is removed");
-    }
-
-    @Test
-    void twoWorktreeAcquiresYieldDistinctBranchesAndPaths() {
-        FakeHerdr herdr = new FakeHerdr();
-        FakeWorktrees worktrees = new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt");
-        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
-
-        WorkerSession a = sessions.acquire("ltms-local", null, "/caller/proj", null,
-                new WorktreeRequest("cb-444", null));
-        WorkerSession b = sessions.acquire("ltms-local", null, "/caller/proj", null,
-                new WorktreeRequest("cb-444", null));
-
-        assertNotEquals(a.branch(), b.branch(), "branches are distinct");
-        assertNotEquals(a.worktree(), b.worktree(), "paths are distinct");
-        assertEquals(2, worktrees.addCalls().size());
-        assertEquals(2, sessions.roster().size());
-    }
-
-}

bridged/src/test/java/dev/ltms/bridged/worker/ClaudeCodeLauncherTest.java

@@ -1,321 +0,0 @@
-package dev.ltms.bridged.worker;
-
-import dev.ltms.bridged.config.BridgedConfig;
-import dev.ltms.bridged.guard.SubscriptionGuard;
-import dev.ltms.bridged.herdr.AgentControl;
-import dev.ltms.bridged.herdr.FakeHerdr;
-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 org.junit.jupiter.api.Test;
-
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-import java.util.function.Function;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-/** The step-4 launch-flag injection: the bridge MCP + reply charter are appended to the argv. */
-class ClaudeCodeLauncherTest {
-
-    private ClaudeCodeLauncher service(FakeHerdr herdr, List<String> argv, String mcpUrl) {
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
-                argv, "tab", "bridged-workers", "worker: {profile} #{n}", mcpUrl, null, null);
-        return new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null);
-    }
-
-    @SuppressWarnings("unchecked")
-    private List<String> spawnedArgv(FakeHerdr herdr) {
-        return (List<String>) ((Map<String, Object>) herdr.lastCall("agent.start").params()).get("argv");
-    }
-
-    @Test
-    void appendsBridgeMcpAndReplyCharterWhenMcpUrlSet() {
-        FakeHerdr herdr = new FakeHerdr();
-        service(herdr, List.of("ccs", "ltms-local"), "http://127.0.0.1:8765/mcp").spawn();
-
-        List<String> argv = spawnedArgv(herdr);
-        assertEquals(List.of("ccs", "ltms-local"), argv.subList(0, 2), "base command preserved first");
-        assertTrue(argv.contains("--mcp-config"));
-        assertTrue(argv.stream().anyMatch(a -> a.contains("\"bridge\"") && a.contains("http://127.0.0.1:8765/mcp")),
-                "inline bridge MCP config present");
-        assertTrue(argv.contains("--append-system-prompt"));
-        assertTrue(argv.stream().anyMatch(a -> a.contains("bridge_reply")), "reply charter present");
-    }
-
-    @Test
-    void noBridgeFlagsWhenMcpUrlAbsent() {
-        FakeHerdr herdr = new FakeHerdr();
-        service(herdr, List.of("bash", "-c", "sleep 1"), null).spawn();
-        assertEquals(List.of("bash", "-c", "sleep 1"), spawnedArgv(herdr), "argv untouched without mcpUrl");
-    }
-
-    private ClaudeCodeLauncher multiProfile(FakeHerdr herdr) {
-        BridgedConfig.Worker gx10 = new BridgedConfig.Worker("gx10", "http://gx10.gw:8000", "coder",
-                null, "BRIDGED_WORKER_TOKEN", List.of("ccs", "gx10"), "tab", "bridged-workers", "w #{n}", null, null, null);
-        BridgedConfig.Worker ollama = new BridgedConfig.Worker("ollama", "http://ollama.ltms.dev", null,
-                null, "BRIDGED_WORKER_TOKEN", List.of("ccs", "ollama"), "tab", "bridged-workers", "w #{n}", null, null, null);
-        return new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx10.gw", "ollama.ltms.dev")),
-                Map.of("gx10", gx10, "ollama", ollama), "gx10", _ -> "tok");
-    }
-
-    @Test
-    @SuppressWarnings("unchecked")
-    void spawnPicksTheNamedProfilesBaseUrlAndArgv() {
-        FakeHerdr herdr = new FakeHerdr();
-        multiProfile(herdr).spawn("ollama");
-
-        Map<String, Object> start = (Map<String, Object>) herdr.lastCall("agent.start").params();
-        Map<String, String> env = (Map<String, String>) start.get("env");
-        assertEquals("http://ollama.ltms.dev", env.get("ANTHROPIC_BASE_URL"), "the named profile's base_url");
-        assertEquals(List.of("ccs", "ollama"), start.get("argv"), "the named profile's launch command");
-    }
-
-    @Test
-    void spawnRejectsAnUnknownProfile() {
-        try (FakeHerdr herdr = new FakeHerdr()) {
-            assertThrows(IllegalArgumentException.class, () -> multiProfile(herdr).spawn("nope"));
-        }
-    }
-
-    @SuppressWarnings("unchecked")
-    private static String startCwd(FakeHerdr herdr) {
-        // The worker's cwd is set on agent.start (an agent pane does not inherit the tab's cwd).
-        Object v = ((Map<String, Object>) herdr.lastCall("agent.start").params()).get("cwd");
-        return v == null ? null : v.toString();
-    }
-
-    @Test
-    void requestedCwdRootsTheWorker() {
-        FakeHerdr herdr = new FakeHerdr();
-        service(herdr, List.of("ccs", "ltms-local"), null).spawn("ltms-local", "/work/proj", "/caller/home");
-        assertEquals("/work/proj", startCwd(herdr), "an explicit spawn cwd wins over everything");
-    }
-
-    @Test
-    void profileConfigCwdBeatsTheCallerCwd() {
-        FakeHerdr herdr = new FakeHerdr();
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker("ltms-local", "http://gx00.gw:8000", "coder",
-                null, "BRIDGED_WORKER_TOKEN", List.of("ccs", "ltms-local"), "tab", "bridged-workers",
-                "w #{n}", null, "/pinned/dir", null);
-        ClaudeCodeLauncher svc = new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of("ltms-local", cfg), "ltms-local", _ -> null);
-        svc.spawn("ltms-local", null, "/caller/home");
-        assertEquals("/pinned/dir", startCwd(herdr), "a profile-pinned cwd overrides the caller's");
-    }
-
-    @Test
-    void inheritsTheCallerCwdWhenNothingElseIsSet() {
-        FakeHerdr herdr = new FakeHerdr();
-        service(herdr, List.of("ccs", "ltms-local"), null).spawn("ltms-local", null, "/primary/project");
-        assertEquals("/primary/project", startCwd(herdr), "no explicit/config cwd → inherit the primary's");
-    }
-
-    // --- CB-302 git-forge token injection (worker checkpoint grant) ------------
-
-    @SuppressWarnings("unchecked")
-    private static Map<String, String> startEnv(FakeHerdr herdr) {
-        return (Map<String, String>) ((Map<String, Object>) herdr.lastCall("agent.start").params()).get("env");
-    }
-
-    @Test
-    void injectsForgeTokenAndHostWhenProfileGrantsIt() {
-        FakeHerdr herdr = new FakeHerdr();
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "impl", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
-                List.of("ccs", "impl"), "tab", "bridged-workers", "w #{n}", null, null, null,
-                "GITEA_ACCESS_TOKEN", null); // parityOverlay null; gitHostEnv null → defaults to GITEA_HOST
-        Function<String, String> host = name -> switch (name) {
-            case "GITEA_ACCESS_TOKEN" -> "gt-secret";
-            case "GITEA_HOST" -> "git.ltms.dev";
-            default -> null;
-        };
-        new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of("impl", cfg), "impl", host).spawn();
-
-        Map<String, String> env = startEnv(herdr);
-        assertEquals("gt-secret", env.get("GITEA_TOKEN"), "the forge token is injected for a granting profile");
-        assertEquals("git.ltms.dev", env.get("GITEA_HOST"), "the paired forge host rides along with the token");
-    }
-
-    @Test
-    void noForgeTokenWhenProfileDoesNotGrantIt() {
-        FakeHerdr herdr = new FakeHerdr();
-        // gitTokenEnv unset (12-arg ctor); the env would resolve a token if asked, proving the gate
-        // is the profile config, not a missing env var.
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker("ltms-local", "http://gx00.gw:8000", "coder",
-                null, "BRIDGED_WORKER_TOKEN", List.of("ccs"), "tab", "bridged-workers", "w #{n}",
-                null, null, null);
-        new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of("ltms-local", cfg), "ltms-local",
-                _ -> "would-be-secret").spawn();
-
-        Map<String, String> env = startEnv(herdr);
-        assertNull(env.get("GITEA_TOKEN"), "no forge token when the profile does not opt in");
-        assertNull(env.get("GITEA_HOST"), "no forge host without a granted token");
-    }
-
-    // --- CB-117 orphan reap: the pure predicate --------------------------------
-
-    @Test
-    void isForeignWorkerMatchesOurSchemeWithANonSelfNonce() {
-        assertTrue(ClaudeCodeLauncher.isForeignWorker("claude-ollama-be09c2-2", "aaaaaa"),
-                "a bridge worker name with a different nonce is a prior daemon's orphan");
-        assertTrue(ClaudeCodeLauncher.isForeignWorker("claude-gx10-4127af-11", "aaaaaa"),
-                "profile and multi-digit seq are still parsed; foreign nonce ⇒ reap");
-    }
-
-    @Test
-    void isForeignWorkerSparesOurOwnLiveWorkersAndNonWorkers() {
-        assertFalse(ClaudeCodeLauncher.isForeignWorker("claude-ollama-abcdef-3", "abcdef"),
-                "a worker with THIS process's nonce is ours and live — never reap it");
-        assertFalse(ClaudeCodeLauncher.isForeignWorker(null, "abcdef"), "an unnamed agent is not a worker");
-        assertFalse(ClaudeCodeLauncher.isForeignWorker("claude", "abcdef"), "a bare kind name is not a worker");
-        assertFalse(ClaudeCodeLauncher.isForeignWorker("my-repl", "abcdef"), "a user's own label is not a worker");
-        assertFalse(ClaudeCodeLauncher.isForeignWorker("claude-ollama-XYZ123-2", "abcdef"),
-                "a non-hex nonce does not match our scheme");
-    }
-
-    // --- CB-117 orphan reap: the wiring through stop() -------------------------
-
-    private static long paneCloseCount(FakeHerdr herdr, String paneId) {
-        return herdr.calls.stream()
-                .filter(c -> c.method().equals("pane.close"))
-                .filter(c -> paneId.equals(((Map<?, ?>) c.params()).get("pane_id")))
-                .count();
-    }
-
-    @Test
-    void reapsAForeignOrphanButSparesOurOwnWorkerAndUserSessions() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = multiProfile(herdr);
-        herdr.withAgent("claude-ollama-be09c2-2", "term_orphan", "wQ:pF", "wQ:t8") // prior daemon's leak
-             .withAgent("claude-gx10-" + svc.nameNonce() + "-1", "term_mine", "wQ:pMine", "wQ:tMine"); // ours, live
-        // (the fake's default unnamed term_a stands in for a user's own Claude session)
-
-        int reaped = svc.reapOrphanWorkers();
-
-        assertEquals(1, reaped, "exactly the one foreign-nonce orphan is reaped");
-        assertEquals(1, paneCloseCount(herdr, "wQ:pF"), "the orphan's pane is closed");
-        assertEquals(0, paneCloseCount(herdr, "wQ:pMine"), "our own live worker's pane is left running");
-        assertEquals(0, paneCloseCount(herdr, "w2:p7"), "a user's own session is never touched");
-        assertTrue(herdr.called("tab.close"), "the orphan's now-empty dedicated tab is closed too");
-    }
-
-    @Test
-    void reapCountsAnAlreadyGoneOrphanAsReaped() {
-        FakeHerdr herdr = new FakeHerdr().paneCloseFailsWith("pane_not_found");
-        ClaudeCodeLauncher svc = multiProfile(herdr);
-        herdr.withAgent("claude-ollama-0d856d-3", "term_gone", "wQ:pS", "wQ:tD");
-
-        assertEquals(1, svc.reapOrphanWorkers(),
-                "a pane that vanished between list and close is a successful reap, not a failure");
-    }
-
-    @Test
-    void reapIsSkippedWhenHerdrCannotBeListed() {
-        FakeHerdr herdr = new FakeHerdr().healthy(false); // agent.list throws
-        assertEquals(0, multiProfile(herdr).reapOrphanWorkers(), "a listing failure reaps nothing and does not throw");
-    }
-
-    // --- PeerHandle indirection ----------------------------------------------------------------
-
-    @Test
-    void spawnReturnsPeerHandleWithIdEqualToPaneId() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
-
-        PeerHandle handle = svc.spawn(new SpawnRequest(null, null, null));
-
-        assertNotNull(handle, "spawn must return a non-null handle");
-        assertEquals("w9:pW_1", handle.id(), "handle.id() must equal the agent's paneId");
-    }
-
-    @Test
-    void spawnReturnsPeerHandleWithCorrectTerminalId() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
-
-        PeerHandle handle = svc.spawn(new SpawnRequest("ltms-local", null, "/caller"));
-
-        assertEquals("term_new_1", handle.terminalId(), "handle.terminalId() must equal the agent's terminalId");
-    }
-
-    @Test
-    void capabilitiesIncludeMidTurnAskWorktreeOrphanReap() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
-
-        Set<Capability> caps = svc.capabilities();
-
-        assertTrue(caps.contains(Capability.MID_TURN_ASK), "every Claude Code peer supports mid-turn ask");
-        assertTrue(caps.contains(Capability.WORKTREE), "every CLI peer supports worktree cwd");
-        assertTrue(caps.contains(Capability.ORPHAN_REAP), "every herdr launcher supports orphan reap");
-    }
-
-    @Test
-    void capabilitiesIncludeSelfPrWhenProfileHasGitToken() {
-        FakeHerdr herdr = new FakeHerdr();
-        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
-                "impl", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
-                List.of("ccs", "impl"), "tab", "bridged-workers", "w #{n}", null, null, null,
-                "GITEA_ACCESS_TOKEN", null);
-        ClaudeCodeLauncher svc = new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
-                new SubscriptionGuard(Set.of("gx00.gw")), Map.of("impl", cfg), "impl",
-                _ -> "tok");
-
-        assertTrue(svc.capabilities().contains(Capability.SELF_PR),
-                "a profile with a git token grants SELF_PR");
-    }
-
-    @Test
-    void capabilitiesExcludeSelfPrWhenNoGitToken() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
-
-        assertFalse(svc.capabilities().contains(Capability.SELF_PR),
-                "no git token profile → no SELF_PR capability");
-    }
-
-    @Test
-    void effectiveCwdViaSpawnRequestMatchesExistingResolution() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
-
-        String cwd = svc.effectiveCwd(new SpawnRequest("ltms-local", "/work/proj", "/caller/home"));
-
-        assertEquals("/work/proj", cwd, "effectiveCwd via SpawnRequest must match the three-arg resolution");
-    }
-
-    @Test
-    void profilesViaPeerLauncherMatchesExistingApi() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = multiProfile(herdr);
-
-        assertEquals(Set.of("gx10", "ollama"), svc.profiles(), "profiles() via PeerLauncher must match");
-    }
-
-    @Test
-    void defaultProfileViaPeerLauncherMatches() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = multiProfile(herdr);
-
-        assertEquals("gx10", svc.defaultProfile(), "defaultProfile() via PeerLauncher must match");
-    }
-
-    @Test
-    void stopViaPeerLauncherTearsDownByHandleId() {
-        FakeHerdr herdr = new FakeHerdr();
-        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
-        PeerHandle handle = svc.spawn(new SpawnRequest(null, null, null));
-
-        svc.stop(handle.id());
-
-        assertTrue(herdr.called("pane.close"), "stop via handle.id() must close the pane");
-    }
-}

deploy/dev.ltms.fleetd.plist

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  CB-504 / CB-594 — launchd agent for fleetd (macOS).
+
+  This is the real supervision target today: the dogfooded daemon runs on macOS, where there is
+  no systemd. A systemd unit ships alongside (deploy/fleetd.service) for the Linux gateways
+  CB-308 introduces.
+
+  Install:
+    cp deploy/dev.ltms.fleetd.plist ~/Library/LaunchAgents/
+    launchctl load -w ~/Library/LaunchAgents/dev.ltms.fleetd.plist
+    launchctl list | grep fleetd
+
+  The paths below are already filled in for this host (resolved 2026-08-16 from
+  `/usr/libexec/java_home`... except that reported the system Applet-plugin JVM, not the jenv-
+  managed JDK 25 actually used to build/run fleetd, so JAVA_HOME here is the real one:
+  `JENV_VERSION=25.0.3 java -XshowSettings:properties -version 2>&1 | grep java.home`; `which mvn`;
+  `echo $HOME`). If this file is copied to a different host, re-resolve all three paths and check
+  no placeholder path is left behind; scripts/redeploy-fleetd.sh's check mode does not (and
+  cannot) check this file for you.
+
+  CB-594 — launchd cannot run a login shell (see the PATH comment on EnvironmentVariables below,
+  and scripts/fleetd-launchd-wrapper.sh for the fix): ProgramArguments below execs THAT wrapper,
+  not java directly, so WORKER_GITEA_TOKEN and AI_GATEWAY_TOKEN still get sourced from
+  ${SHARED_ENV}/tools/secrets.sh even though launchd itself never sources anything.
+
+  Note on ordering: launchd has no "start after herdr" primitive for user agents, and neither
+  does systemd in a way that survives a socket appearing late. fleetd retries the herdr socket
+  on startup instead, so an agent that comes up before herdr converges rather than dying — that
+  retry is the actual fix; KeepAlive below is the backstop.
+
+  CB-594 — KeepAlive vs. scripts/redeploy-fleetd.sh: a bare SIGTERM makes this JVM exit 143 even
+  with its shutdown hook running to completion (measured, see the CB-594 report), which
+  SuccessfulExit:false below reads as a crash and races to restart the OLD jar. The redeploy
+  script now detects a loaded agent and uses `launchctl unload`/`load` instead of a raw kill, so
+  only one supervisor ever touches the process at a time — read that script's own output on a
+  redeploy for the confirmation.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>dev.ltms.fleetd</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Users/dai.ha/LTMS/claude-bridge/scripts/fleetd-launchd-wrapper.sh</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home/bin/java</string>
+        <string>-jar</string>
+        <string>/Users/dai.ha/LTMS/claude-bridge/fleetd/target/fleetd.jar</string>
+        <string>fleetd.yaml</string>
+    </array>
+
+    <!-- Config path in ProgramArguments is relative, so the working directory must be the module. -->
+    <key>WorkingDirectory</key>
+    <string>/Users/dai.ha/LTMS/claude-bridge/fleetd</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>JAVA_HOME</key>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home</string>
+        <key>HERDR_SOCKET_PATH</key>
+        <string>/Users/dai.ha/.config/herdr/herdr.sock</string>
+        <!--
+          PATH matters more than it looks (CB-511): fleetd propagates its own PATH to every worker
+          it spawns, so this line decides whether the fleet can run a build at all. launchd does NOT
+          source .zprofile/.zshrc, so without this the daemon (and therefore every worker) gets a
+          bare /usr/bin:/bin and no JDK or Maven. Keep the toolchain entries first.
+        -->
+        <key>PATH</key>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home/bin:/Users/dai.ha/Softwares/apache-maven/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <!--
+          Worker/API tokens are NOT set here: this file is committed. CB-594 —
+          scripts/fleetd-launchd-wrapper.sh (named in ProgramArguments above) is what supplies
+          them, by execing a login shell that sources ${SHARED_ENV}/tools/secrets.sh before the
+          daemon itself starts. fleetd also reads the API token from the env var named by
+          auth.tokenEnv (default FLEETD_API_TOKEN) and only in auth.mode: token — the wrapper
+          covers that one too, since it is the same login shell.
+        -->
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <!--
+      CB-600 — read this before assuming ThrottleInterval bounds anything. It paces restarts to at
+      most one per 10s; it does NOT cap how many times launchd retries. If fleetd fails fast on
+      every start — a bad fleetd.yaml, for example auth.mode: token with the token env var unset,
+      which throws in main() before the daemon ever binds a port — launchd restarts it forever,
+      once every 10s, until a human intervenes. LaunchAgents have no "give up after N attempts"
+      primitive, so this is not something a config change here can fix.
+
+      That loop stops only two ways: (1) `launchctl unload -w ~/Library/LaunchAgents/dev.ltms.fleetd.plist`,
+      or (2) the underlying cause gets fixed, so the process starts successfully and stays up (no
+      more exits to restart). scripts/redeploy-fleetd.sh does not add a third way — it does not
+      make fleetd self-disable on a config error, on purpose: a fail-fast exit path that
+      sometimes decides "this is unrecoverable, stop trying" is one more thing that can misfire,
+      and a wrongly self-disabled daemon needs the exact same manual `launchctl load -w` recovery
+      this comment already names — so it buys nothing an operator watching for the crash loop
+      doesn't already have, at the cost of a new way to be silently down. Watch for it with
+      `launchctl list dev.ltms.fleetd` (a high restart count) or by tailing fleetd.out for the
+      same startup error repeating every ~10s.
+    -->
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <!--
+      CB-594 — same file scripts/redeploy-fleetd.sh already tails ($BRIDGED/fleetd.out), and both
+      streams point at it, not two separate log files: the script's fresh-line / ERROR-count checks
+      after a restart read this one path regardless of whether launchd or the script started the
+      process, and a stdout/stderr split would make half of what happens during a launchd-driven
+      restart invisible to it.
+    -->
+    <key>StandardOutPath</key>
+    <string>/Users/dai.ha/LTMS/claude-bridge/fleetd/fleetd.out</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/dai.ha/LTMS/claude-bridge/fleetd/fleetd.out</string>
+
+    <key>ProcessType</key>
+    <string>Background</string>
+</dict>
+</plist>

deploy/fleetd.service

@@ -0,0 +1,77 @@
+# CB-504 — systemd unit for fleetd (Linux).
+#
+# The macOS launchd agent (deploy/dev.ltms.fleetd.plist) is the supervision target for the
+# current single-host deployment. This unit exists for the per-host gateways CB-308 introduces,
+# which will run on Linux.
+#
+# Install (user service — fleetd drives the user's herdr, not a system daemon):
+#   mkdir -p ~/.config/systemd/user
+#   cp deploy/fleetd.service ~/.config/systemd/user/
+#   # edit ExecStart / WorkingDirectory / Environment below, then:
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now fleetd
+#   journalctl --user -u fleetd -f
+
+[Unit]
+Description=fleetd — claude-bridge message server
+Documentation=https://git.ltms.dev/fleet/fleetd/wiki
+# Ordering only: herdr is a user process and its socket may appear after us. This is advisory —
+# fleetd retries the herdr socket rather than exiting, which is what actually makes a late
+# socket survivable. Do NOT add Requires=: a herdr restart must not take fleetd down with it.
+After=herdr.service
+Wants=herdr.service
+
+[Service]
+Type=simple
+WorkingDirectory=%h/src/claude-bridge/fleetd
+ExecStart=/usr/lib/jvm/temurin-25-jdk/bin/java -jar target/fleetd.jar fleetd.yaml
+
+Environment=HERDR_SOCKET_PATH=%h/.config/herdr/herdr.sock
+# PATH matters more than it looks (CB-511): fleetd propagates its own PATH to every worker it
+# spawns, so this line decides whether the fleet can run a build at all. systemd does not source a
+# login shell, so without it the daemon — and every worker — gets a bare default with no JDK/Maven.
+Environment=PATH=/usr/lib/jvm/temurin-25-jdk/bin:/usr/share/maven/bin:/usr/local/bin:/usr/bin:/bin
+# Secrets are NOT set here — this file is committed. Put ALL three tokens in a private drop-in
+# that systemd reads with restrictive permissions. In `systemctl --user edit fleetd`, add:
+#   [Service]
+#   Environment=FLEETD_API_TOKEN=...
+#   Environment=WORKER_GITEA_TOKEN=...
+#   Environment=AI_GATEWAY_TOKEN=...
+# FLEETD_API_TOKEN protects fleetd's API. WORKER_GITEA_TOKEN lets members open pull requests; if
+# it is missing, fleetd still starts, but a member fails when it later tries to open a pull request.
+# AI_GATEWAY_TOKEN authenticates gateway profiles; if it is missing, fleetd still starts, but a
+# gateway profile later returns HTTP 401. Or, put the same three variables in a 0600 file and add:
+# EnvironmentFile=%h/.config/fleetd/env
+# After starting, check which of them actually resolved. The daemon reports every secret a
+# configured profile references, by name, never by value:
+#   journalctl --user -u fleetd | grep 'startup secret'
+# A resolved one logs "startup secret NAME: set (profile 'x' tokenEnv)". A missing one logs
+# "startup secret NAME: MISSING" at WARN — and the daemon starts anyway, which is the whole
+# problem: without this grep the first sign is a member that cannot open a pull request, hours
+# later and in a different component.
+# Note what the report can and cannot tell you. It lists only names some profile actually
+# references (tokenEnv, gitTokenEnv, and the broker uriEnv). A secret nothing references is never
+# reported, because nothing needs it.
+
+Restart=on-failure
+RestartSec=10s
+# A bad config (e.g. a non-loopback bind without token auth) makes fleetd fail fast by design.
+# Give up rather than restart-loop on a permanent error.
+StartLimitBurst=5
+StartLimitIntervalSec=120
+
+# The daemon reads the repo, writes worktrees, and talks to a Unix socket — it needs no more.
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-write
+ProtectKernelTunables=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=fleetd
+
+[Install]
+WantedBy=default.target

deploy/lavinmq/compose.yaml

@@ -0,0 +1,60 @@
+# LavinMQ — the AMQP broker behind fleetd's durable ReplyInbox (CB-307 Stage 2).
+#
+# Why this file exists: the broker was previously run ad hoc and simply vanished from the host,
+# which takes fleetd down with it — AmqpReplyInbox.open throws on an unreachable broker and
+# Fleetd.java:187 does not guard it, so a missing broker is a hard startup failure, not a
+# degraded mode. This pins the version, keeps the data, and brings itself back after a reboot.
+#
+# Usage:
+#   docker compose -f deploy/lavinmq/compose.yaml up -d
+#   docker compose -f deploy/lavinmq/compose.yaml ps
+#   docker compose -f deploy/lavinmq/compose.yaml logs -f
+#   docker compose -f deploy/lavinmq/compose.yaml down          # keeps the volume
+#   docker compose -f deploy/lavinmq/compose.yaml down -v       # DESTROYS held replies
+#
+# Management UI: http://127.0.0.1:15672  (guest / guest)
+#
+# This is fleetd's OWN broker. Do not point fleetd at any other AMQP server on this host —
+# notably not the `local-rabbitmq` container, which belongs to a different project and would end
+# up carrying this project's queues.
+
+name: fleetd-broker
+
+services:
+  lavinmq:
+    # Pinned deliberately: :latest silently moves the broker under a running daemon.
+    image: cloudamqp/lavinmq:2.9.1
+    container_name: fleetd-lavinmq
+
+    # The failure this deployment exists to prevent — survive reboots and Docker restarts, but
+    # stay down if it was stopped on purpose.
+    restart: unless-stopped
+
+    # Loopback-bound on purpose. LavinMQ ships a default guest/guest account, which is only
+    # acceptable because nothing off-host can reach it. fleetd connects over 127.0.0.1, and
+    # binding 0.0.0.0 here would expose a broker with default credentials to the network.
+    ports:
+      - "127.0.0.1:5672:5672"      # AMQP — fleetd.yaml broker.uri points here
+      - "127.0.0.1:15672:15672"    # HTTP management API + UI
+
+    # The whole point of Stage 2. Held-but-unacked replies live here; without a named volume a
+    # `docker compose down` would discard exactly what the durable inbox exists to protect.
+    volumes:
+      - lavinmq-data:/var/lib/lavinmq
+
+    healthcheck:
+      test: ["CMD", "lavinmqctl", "status"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+volumes:
+  lavinmq-data:
+    name: fleetd-lavinmq-data

docs/CB-201-227-Refinement.md

@@ -0,0 +1,531 @@
+# CB-201 and CB-227 refinement
+
+Date: 2026-09-03
+
+## Decision
+
+#201 and #227 are one delivery program, but they are not one implementation unit.
+
+#201 has a real seam: `CompletionResolver` can publish a typed backend-error event only after its
+waiter resolution wins. #227 can consume that event without knowing any pane text. The classifier
+must land before the final #227 wiring. However, the policy engine, roster state, and lead nudge can
+be built in parallel with the classifier.
+
+I propose five units. Units 1 to 4 own separate files and can run in parallel. Unit 5 owns all
+composition files and lands after them. It also depends on the #234 defect 2 fix named in the task.
+
+```mermaid
+flowchart LR
+    U1["Unit 1: typed backend-error classification"] --> U5["Unit 5: wire policy, spawn gate, and fleet views"]
+    U2["Unit 2: credential outage policy"] --> U5
+    U3["Unit 3: lead outage nudge"] --> U5
+    U4["Unit 4: durable member outcome"] --> U5
+    D234["#234 defect 2: fail-loud target resolution"] --> U5
+```
+
+*Figure 1. Four file-disjoint foundations feed one composition unit.*
+
+This split keeps `Fleetd.java` under one owner. It also keeps every other production file under one
+unit in this plan.
+
+## Evidence checked in the current branch
+
+I read both issue pages in full. Each page reports zero comments.
+
+| Evidence | What the code says now |
+|---|---|
+| `inject/CompletionResolver.java:229-237` | A turn below two seconds fails before normal scrape classification. A matching fast backend error is therefore only a generic failure today. |
+| `inject/CompletionResolver.java:260-276` and `:332-367` | #211 already added raw-screen classification when `lastAssistantBlock` is empty. The “dead-code question” in #201 is stale on this branch. |
+| `inject/CompletionResolver.java:288-317` | Exhaustion wins before the hard-coded `API Error:` match. A backend error then goes through generic `fail(...)`. |
+| `inject/CompletionResolver.java:311-316` | The code admits that the pattern is a heuristic. A member report which quotes an API error may match it. |
+| `inject/CompletionResolver.java:449-467` | Startup coverage exists only for `exhaustedPattern`. |
+| `inject/ExhaustedPatternLookup.java:13-25` | The current lookup and explicit `none()` value are a good shape for the new classifier seam. |
+| `Fleetd.java:196-207` | One `BackendQuarantine` is shared by placement and the exhaustion sink. Its cooldown comes from `quarantineCooldownSeconds`. |
+| `Fleetd.java:322-363` | Pattern compilation, target-to-profile lookup, and the live `ExhaustionSink` are composed in `Fleetd.main`. The sink on this branch still ends in `.ifPresent(...)`. This plan assumes #234 replaces that silent path. |
+| `placement/BackendQuarantine.java:60-87` | A repeated exhaustion restarts one long quarantine. The store is credential-keyed and uses an injected monotonic clock. |
+| `member/CompositePeerLauncher.java:260-317` | Explicit and policy-selected spawns have separate gates. Both paths must learn about outage cool-off. |
+| `member/CompositePeerLauncher.java:347-379` | Exhaustion refusal already checks a credential for explicit spawns and filters policy candidates. Its error text says “exhausted”. |
+| `placement/PlacementContext.java:10-22` and `PlacementPolicyUtil.java:14-83` | Automatic placement has only one transient exclusion set named `quarantined`. Reusing it would make outage errors say “backend exhausted”. |
+| `mcp/FleetMcp.java:913-1025` | `fleet_list` sets `free: 0` and adds `credentialId` plus `quarantinedForSeconds` when quarantine is active. |
+| `session/MemberSession.java:51-59` | The roster has `DONE` and generic `FAILED`, but no backend-error state or stored reason. |
+| `session/SessionManager.java:695-773` | A normal boundary moves `BUSY` to `DONE`. A failure moves any non-released session to `FAILED`. The async completion resolver can race the `DONE` update. |
+| `session/SessionManager.java:648-687` | `rosterView` reports the session state, but it reports no terminal reason. |
+| `msg/MessageService.java:922-940` | CB-588 already nudges for every terminal async ticket, including failures. Current code would report failed tickets, but it would not report one correlated outage. |
+| `msg/ReplyPushLoop.java:20-48` | Replies, terminal tickets, and questions share one per-lead schedule. This prevents two push sources from injecting competing turns. |
+| `msg/ReplyPushLoop.java:305-395` | Each push entry point resolves the owning lead through `PrimaryRegistry`. Missing ownership is logged and the durable or pending item remains the backstop. |
+| `msg/ReplyPushLoop.java:496-547` | One tick builds one combined nudge. Pending items have separate reminder counts. |
+| `health/FleetHealthMonitor.java:91-143` | Health is a slow periodic observer of members and message-layer facts. It does not receive completion classifications. |
+| `health/FleetHealthMonitor.java:206-208` | `healthCoverage` means health enabled plus webhook configured. It does not describe lead-pane alerts. |
+| `Fleetd.java:465-486` | Health stays `detection-only` without the webhook notification setting. |
+
+I also read the related unit tests for `CompletionResolver`, `ReplyPushLoop`, `BackendQuarantine`,
+`CompositePeerLauncher`, `PlacementPolicyUtil`, `SessionManager`, `MessageService`, and `FleetMcp`.
+
+I did not inspect the in-progress #234 branch. I only used the two measured facts in the task. No
+peer architect was named, so I did not exchange a design with one.
+
+## Required behaviour
+
+The policy should use these first values:
+
+- Threshold: **2** classified backend errors.
+- Window: **60 seconds**, measured from the first error to the second.
+- Cool-off: **60 seconds**, starting when the threshold is reached.
+- Correlation key: `credentialId`, never profile name and never error text.
+- Incident rule: one active incident per credential. Errors during its cool-off do not extend it and
+  do not create more lead notices.
+- Rearm rule: after cool-off ends, two fresh errors are needed for another incident.
+
+Two errors are the smallest threshold which protects the honest one-turn failure. A 60-second window
+fits the measured two-member outage. A 60-second cool-off blocks immediate repeat spawns without
+turning a short backend fault into the default 1,800-second exhaustion quarantine.
+
+A single classified error still fails its send and marks its member `backend_error`. It does not
+cool a credential and does not send an outage notice. This is what “a single error changes nothing”
+must mean at the credential level. It cannot mean that the failed member still looks successful.
+
+```mermaid
+sequenceDiagram
+    participant R1 as Resolver for member A
+    participant R2 as Resolver for member B
+    participant P as Outage policy
+    participant S as Spawn gate
+    participant N as Lead push loop
+    participant L as Lead pane
+
+    R1->>P: backend error for credential C
+    Note over P: Count 1, no cool-off
+    R2->>P: backend error for credential C within 60s
+    P->>P: Start one 60s incident
+    P->>S: Credential C is cooling off
+    P->>N: Queue one incident notice
+    N->>L: Inject when lead is idle, blocked, or done
+    L->>S: Request another spawn on credential C
+    S-->>L: Refuse and report remaining cool-off
+```
+
+*Figure 2. The second independent classification creates the fleet-level event.*
+
+Against the 2026-09-01 case, the second failed member would start cool-off. `fleet_list` would show
+zero free capacity and both members as `backend_error`. The push loop would inject one outage notice
+even if the lead had not polled either ticket yet. The design reports the outage. It does not recover
+uncommitted work from the members.
+
+## Unit 1 — Typed backend-error classification
+
+### Scope
+
+Replace the direct hard-coded check inside `CompletionResolver` with a lookup and a sink. Keep the
+public send result as a failed send. The typed internal event is the seam #227 consumes.
+
+The lookup returns the pattern for a target. The sink receives the target, matched line, and full
+failure reason. It fires only after `Rendezvous.resolveFailure(...)` wins for that exact captured
+waiter. This copies the race rule already used by `ExhaustionSink`.
+
+The classifier must run in all three current paths:
+
+1. a normal non-empty assistant block;
+2. the #211 raw scrape fallback;
+3. a turn inside `MIN_TURN_NANOS`, before it becomes a generic too-fast failure.
+
+In every path, the order stays: stale-baseline guard, exhaustion, backend error, then generic
+failure or completion. A fast turn still fails when no configured pattern matches.
+
+Keep `(?i)\bAPI Error\s*:` as a compatibility pattern for profiles without `errorPattern` until the
+operator config is updated. Do not call this full coverage. Startup reporting in Unit 5 must name
+profiles using this weaker legacy default.
+
+### Files owned
+
+- Add `fleetd/src/main/java/dev/ltms/fleet/inject/BackendErrorPatternLookup.java`.
+- Add `fleetd/src/main/java/dev/ltms/fleet/inject/BackendErrorSink.java`.
+- Change `fleetd/src/main/java/dev/ltms/fleet/inject/CompletionResolver.java`.
+- Change `fleetd/src/test/java/dev/ltms/fleet/inject/CompletionResolverTest.java`.
+
+No other unit may edit these files.
+
+### Acceptance criteria
+
+1. A target-specific error pattern matches a normal assistant block and resolves the send as failed.
+2. The same match calls `BackendErrorSink` exactly once after the waiter resolution wins.
+3. A late classification which loses to `fleet_reply` does not call the sink.
+4. An exhausted line that also matches the generic error pattern stays `BACKEND_EXHAUSTED`. It calls
+   only `ExhaustionSink`.
+5. A raw pane with leading Terminal User Interface (TUI) chrome and no assistant marker still uses
+   the #211 fallback and calls the backend-error sink.
+6. A matching error inside the two-second floor is typed and sent to the sink. A non-matching fast
+   turn stays a generic failure.
+7. An unchanged delivery baseline which contains old backend-error text is suppressed. It never
+   increments outage evidence.
+8. A non-match keeps the existing completion result and text.
+9. Constructors used by current callers keep compiling. They use the legacy default lookup and an
+   explicit inert sink until Unit 5 supplies the production objects.
+10. Unit tests pass. The developer runs the focused test first, then `mvn clean install` from
+    `fleetd/`.
+
+### Dependencies
+
+None. Unit 1 can run with Units 2, 3, and 4.
+
+Unit 5 depends on its new lookup, sink, and constructor.
+
+### What to report back
+
+- The exact classifier order in all three paths.
+- The focused test command and result.
+- The test which proves a losing waiter race does not publish an event.
+- The test which proves a fast matching failure is typed.
+- The final `mvn clean install` result.
+- Any constructor kept only for transition and where Unit 5 replaces it.
+
+## Unit 2 — Credential outage policy
+
+### Scope
+
+Build a small credential-keyed state machine. It accepts already-classified backend-error events.
+It does not read pane text, profiles, sessions, or lead state.
+
+Use an injected monotonic clock. A call records `credentialId`, target, and reason. It returns a new
+incident only on the threshold crossing. The incident contains a stable event id, credential id,
+the distinct affected targets, evidence count, window, and remaining cool-off.
+
+This class owns both correlation and short cool-off. Keeping them together makes threshold crossing
+and the cool-off deadline one atomic state change.
+
+### Files owned
+
+- Add `fleetd/src/main/java/dev/ltms/fleet/placement/BackendOutagePolicy.java`.
+- Add `fleetd/src/test/java/dev/ltms/fleet/placement/BackendOutagePolicyTest.java`.
+
+No other unit may edit these files.
+
+### Acceptance criteria
+
+1. One error creates no incident and no cool-off.
+2. Two errors for one credential within 60 seconds create exactly one incident and a 60-second
+   cool-off.
+3. Two errors more than 60 seconds apart do not create an incident.
+4. The exact 60-second boundary has a pinned result. Use inclusive `<= 60s` so scheduler delay does
+   not discard evidence at the boundary.
+5. Different credentials never share evidence.
+6. Different profiles which supply the same credential id do share evidence. The policy itself only
+   sees the credential id.
+7. More errors during active cool-off do not extend its deadline and do not return another incident.
+8. After expiry, old evidence is cleared. Two fresh errors are needed to create the next incident.
+9. Remaining seconds round up, matching `BackendQuarantine` reporting.
+10. Concurrent second and third errors cannot return two incidents.
+11. The focused tests and `mvn clean install` pass.
+
+### Dependencies
+
+None. Unit 2 can run with Units 1, 3, and 4.
+
+Unit 5 depends on the policy API.
+
+### What to report back
+
+- The state transition table and locking method.
+- The exact threshold, window, cool-off, and boundary rule.
+- The test which proves one incident under concurrent calls.
+- The focused test and `mvn clean install` results.
+
+## Unit 3 — Lead outage nudge
+
+### Scope
+
+Add backend incidents as a fourth pending source in `ReplyPushLoop`. Do not create another scheduler
+or call `AgentControl.send` from `Fleetd`. The existing combined per-lead schedule is the control
+which prevents competing injected turns.
+
+The entry point takes an incident id, affected worker targets, credential id, affected profile
+names, and remaining cool-off. It resolves distinct owning leads through `PrimaryRegistry`.
+
+Each `(incidentId, lead)` item is one-shot. It waits while the lead is not injectable. After one
+successful `agents.send`, remove it. A send exception keeps it pending for a bounded retry. It never
+uses the repeated reminder behaviour of an uncollected ticket.
+
+Also add a fail-loud entry point for a classified target that Unit 5 cannot map to a credential. It
+uses `PrimaryRegistry.nudgeTargetFor(target)` and says that correlation could not run. If no lead is
+known, log at `WARN`, not `DEBUG`.
+
+### Files owned
+
+- Change `fleetd/src/main/java/dev/ltms/fleet/msg/ReplyPushLoop.java`.
+- Change `fleetd/src/test/java/dev/ltms/fleet/msg/ReplyPushLoopTest.java`.
+
+No other unit may edit these files.
+
+### Acceptance criteria
+
+1. One incident affecting two workers owned by one lead causes one successful pane injection.
+2. Two affected workers owned by two leads cause one successful injection per affected lead. This
+   is one notice per event per lead, not one notice per member.
+3. Repeating the same incident id is idempotent.
+4. A busy or unknown lead is not injected. The item stays pending until the lead becomes injectable
+   or its attempt cap is reached.
+5. After one successful injection, later ticks do not mention that incident again.
+6. A failed `agents.send` is retried within the existing bound. A successful retry still gives only
+   one successful send.
+7. A pending ticket and an outage incident for one lead appear in one combined nudge, not two
+   competing turns.
+8. The text names the credential, profiles, affected workers, and remaining cool-off. It tells the
+   lead to run `fleet_list`.
+9. An unmapped target produces a direct warning notice when a lead is known. If no lead is known,
+   the code logs a `WARN` naming the target and reason.
+10. `stop()` clears incident state as it clears other push state.
+11. Existing reply, ticket, and question tests stay green. The focused tests and
+    `mvn clean install` pass.
+
+### Dependencies
+
+None. The API uses plain values, not the Unit 2 incident class. This lets Unit 3 run in parallel.
+
+Unit 5 adapts the Unit 2 incident into this entry point.
+
+### What to report back
+
+- The exact one-shot and retry rules.
+- The test showing one combined nudge with a failed ticket.
+- The test showing one successful send for two affected workers.
+- The focused test and `mvn clean install` results.
+
+## Unit 4 — Durable member backend-error outcome
+
+### Scope
+
+Make a classified backend failure remain visible after its ticket is collected or expires.
+
+Add `BACKEND_ERROR` to `MemberSession.State`. Add a nullable failure detail to `MemberSession` and
+render it as `failureReason` in `SessionManager.rosterView`. Add
+`SessionManager.onBackendError(target, reason)`.
+
+The transition must handle both completion orderings:
+
+- `BUSY -> BACKEND_ERROR` when classification wins before the normal completion state update;
+- `DONE -> BACKEND_ERROR` when the async resolver runs after `SessionManager.onTurnComplete`.
+
+It must use a compare-and-set retry or another atomic update. `RELEASED` must never return to the
+roster. A backend-error member is terminal and cannot accept another delivery.
+
+### Files owned
+
+- Change `fleetd/src/main/java/dev/ltms/fleet/session/MemberSession.java`.
+- Change `fleetd/src/main/java/dev/ltms/fleet/session/SessionManager.java`.
+- Change `fleetd/src/test/java/dev/ltms/fleet/session/SessionManagerTest.java`.
+
+No other unit may edit these files.
+
+### Acceptance criteria
+
+1. `onBackendError` moves a `BUSY` member to `BACKEND_ERROR` and stores the reason.
+2. It also moves `DONE` to `BACKEND_ERROR`, covering the resolver race.
+3. A later normal `onTurnComplete` cannot change `BACKEND_ERROR` back to `DONE`.
+4. A released or unknown member is not recreated. The unknown case logs at `WARN` and returns an
+   explicit false result to its caller.
+5. `onDelivered` refuses a `BACKEND_ERROR` member, just as it refuses generic `FAILED`.
+6. `rosterView` reports `state: backend_error` and `failureReason` after the send ticket is gone.
+7. Ordinary members do not gain a blank or invented `failureReason` field.
+8. Existing constructors keep source compatibility for tests and adapters.
+9. The focused tests and `mvn clean install` pass.
+
+### Dependencies
+
+None. Unit 4 can run with Units 1, 2, and 3.
+
+Unit 5 calls the new session method from the production sink.
+
+### What to report back
+
+- The two race orderings and the tests for both.
+- The exact roster JSON shape.
+- The unknown-target result and log level.
+- The focused test and `mvn clean install` results.
+
+## Unit 5 — Production wiring, spawn gate, and fleet views
+
+### Scope
+
+Compose Units 1 to 4 in production. This is the only unit which edits `Fleetd.java`.
+
+Add per-profile `errorPattern` config beside `exhaustedPattern`. Compile both once at startup. A
+configured pattern wins over the legacy default. Report configured profiles and legacy-default
+profiles separately at startup. A bad regex must stop startup with the profile and key in the
+message.
+
+Wire one production `BackendErrorSink` with this order:
+
+1. mark the member `backend_error` with its reason;
+2. resolve the profile and its current `effectiveCredentialId()` through the fail-loud #234 seam;
+3. record the error in `BackendOutagePolicy`;
+4. on a new incident, submit one event to `ReplyPushLoop`.
+
+If target metadata cannot be resolved, do not end in `Optional.ifPresent`. Log an error and call the
+Unit 3 unmapped-target notice. The failed send still reaches its ticket through CB-588.
+
+Teach both spawn paths about a separate cool-off source. Exhaustion quarantine has priority when
+both states are active. Automatic placement needs a distinct `coolingOff` set so its refusal does
+not say “exhausted”.
+
+Extend the MCP (Model Context Protocol) views:
+
+- A cooling profile has `free: 0`, `credentialId`, and `coolingOffForSeconds` in `fleet_list`.
+- It does not have `quarantinedForSeconds` unless exhaustion quarantine is also active.
+- `fleet_profiles` has a separate `coolingOff` map, not an entry in `quarantined`.
+- A direct spawn refusal says the credential is cooling off after repeated backend errors and gives
+  the remaining seconds.
+
+Do not change `FleetHealthMonitor.coverage`. It still describes the periodic health webhook path.
+Lead-pane outage delivery is a separate capability.
+
+### Files owned
+
+- `fleetd/src/main/java/dev/ltms/fleet/Fleetd.java`
+- `fleetd/src/main/java/dev/ltms/fleet/config/FleetConfig.java`
+- `fleetd/src/main/java/dev/ltms/fleet/config/ConfigRef.java`
+- `fleetd/src/main/java/dev/ltms/fleet/member/CompositePeerLauncher.java`
+- `fleetd/src/main/java/dev/ltms/fleet/placement/PlacementContext.java`
+- `fleetd/src/main/java/dev/ltms/fleet/placement/PlacementPolicyUtil.java`
+- `fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java`
+- `fleetd/src/test/java/dev/ltms/fleet/config/FleetConfigTest.java`
+- `fleetd/src/test/java/dev/ltms/fleet/config/ConfigRefTest.java`
+- `fleetd/src/test/java/dev/ltms/fleet/member/CompositePeerLauncherTest.java`
+- `fleetd/src/test/java/dev/ltms/fleet/placement/PlacementPolicyTest.java`
+- `fleetd/src/test/java/dev/ltms/fleet/mcp/FleetMcpTest.java`
+- Add `fleetd/src/test/java/dev/ltms/fleet/BackendOutageFlowTest.java`.
+- `fleetd/fleetd.example.yaml`
+- `CLAUDE.md`
+
+No earlier unit edits these files.
+
+The lead, not a worker, must update `wiki/7-Use-Cases.md`, `wiki/9-Implementation.md`, and
+`wiki/11-Features.md`. Project rules forbid workers from committing `wiki/`. The portable block in
+`CLAUDE.md` and `wiki/7-Use-Cases.md` must remain byte-identical.
+
+### Acceptance criteria
+
+1. `errorPattern` binds per profile. Blank uses the legacy default and is reported as degraded
+   coverage. A config reload which changes it is reported as deferred because patterns are compiled
+   at startup.
+2. A malformed `errorPattern` stops startup and names `profiles.<name>.errorPattern`.
+3. The real production sink never silently drops an unknown target. A test captures its error log
+   and the fallback notice call.
+4. One real backend-error classification through `CompletionResolver` marks only its member. It does
+   not cool the credential and does not send an outage notice.
+5. Two real classifications for one credential within 60 seconds start one incident.
+6. The integration test then calls the real explicit-profile spawn gate. It is refused before any
+   adapter spawn call, with “cooling off” and remaining seconds in the message.
+7. The same test calls an automatic placement path. A cooling candidate is skipped. If every
+   candidate is cooling, the error names cool-off rather than exhaustion.
+8. Profiles sharing the credential are all blocked. A profile on another credential stays usable.
+9. `fleet_list` from the same fixture shows both members as `backend_error`, preserves each failure
+   reason, and reports `free: 0`, the credential, and `coolingOffForSeconds`.
+10. `fleet_profiles` reports cool-off separately from quarantine.
+11. The real `ReplyPushLoop` receives one incident and makes one successful lead-pane send. Existing
+    failed-ticket notice content may share that same combined send.
+12. Exhaustion still wins when a line matches both patterns. A simultaneous exhaustion quarantine
+    also wins in spawn errors and fleet views.
+13. After the 60-second cool-off, spawn is allowed again. A new incident needs two fresh errors.
+14. `healthCoverage` has the same value before and after this change for the same health config.
+15. `fleetd.example.yaml` explains `errorPattern`, the legacy fallback, 2/60/60 policy, and the
+    difference between cool-off and exhaustion quarantine.
+16. `CLAUDE.md` tells leads how `fleet_profiles` and `fleet_list` report cool-off. The lead later
+    applies the matching wiki updates and runs the documented byte-sync check.
+17. The developer records the new end-to-end test failing before implementation, then passing. The
+    focused suites and `mvn clean install` pass.
+
+### Dependencies
+
+Unit 5 starts only after Units 1 to 4 are merged or rebased into its branch. It also starts after the
+#234 defect 2 fix lands, because both areas touch the same target-resolution control path.
+
+### What to report back
+
+- The exact commits used for Units 1 to 4 and #234.
+- The startup coverage line with one configured and one legacy-default profile.
+- The red test output before the implementation and its green result after.
+- The explicit and automatic spawn refusal text.
+- Sample `fleet_list` and `fleet_profiles` JSON for cool-off and exhaustion.
+- The number and text of lead-pane sends in the real-path test.
+- The focused test commands and final `mvn clean install` result.
+- The exact `CLAUDE.md` change and the wiki edits the lead must apply.
+
+## File ownership summary
+
+| Area | Unit | Shared edit risk |
+|---|---:|---|
+| Completion classification | 1 | Only Unit 1 edits `CompletionResolver` and its test. |
+| Correlation and cool-off state | 2 | New files only. |
+| Lead push scheduling | 3 | Only Unit 3 edits `ReplyPushLoop` and its test. |
+| Member terminal state | 4 | Only Unit 4 edits `MemberSession`, `SessionManager`, and their test. |
+| Main composition, config, placement, MCP views, shipped prompt | 5 | Only Unit 5 edits `Fleetd`, `FleetConfig`, `CompositePeerLauncher`, placement context, `FleetMcp`, and `CLAUDE.md`. |
+| Wiki propagation | Lead after Unit 5 | Workers do not commit the wiki submodule. |
+
+## What I would not build
+
+1. **Do not reuse `BackendQuarantine` for outages.** Its repeat call restarts a long credential
+   quarantine. Its fields and errors say “exhausted”. That is wrong for a short outage.
+2. **Do not merge the exhaustion and generic error patterns.** Exhaustion must win because it has a
+   different policy and duration.
+3. **Do not group by error string.** One outage can produce different text. The shared operational
+   limit is the credential.
+4. **Do not mark a profile unusable until config changes.** The current classifier cannot safely
+   tell a permanent malformed request from a transient service fault. A permanent state would need
+   a stronger error taxonomy first.
+5. **Do not quarantine on the first generic backend error.** That would turn one bad request or one
+   false pattern match into a fleet-wide capacity loss.
+6. **Do not add this to `FleetHealthMonitor`.** The monitor samples slow member health. The exact
+   backend event already exists at completion resolution, and moving it to polling would lose type
+   and time.
+7. **Do not add another direct lead injector.** `ReplyPushLoop` already owns status gating,
+   per-lead coalescing, retry bounds, and heartbeat stand-down.
+8. **Do not change `healthCoverage` to `full`.** That field still means a webhook notification sink
+   exists for periodic health. A backend outage nudge does not make every health event visible.
+9. **Do not persist incident history across daemon restart in this work.** Existing exhaustion
+   quarantine is also in memory. A 60-second state does not justify a new durable store.
+10. **Do not build work recovery.** The PR-body survival story proves why checkpoint-first work is
+    useful, but these tickets are about detection, capacity, and signalling.
+11. **Do not remove the legacy `API Error:` fallback in the first release.** Doing so would turn an
+    unedited config back into a false successful completion. Report it as degraded coverage instead.
+12. **Do not reorder or add the old `visibleTurn` fallback from #201.** #211 already implemented the
+    narrow raw-scrape fallback at `CompletionResolver.classifyRawScrapeFallback`.
+
+## Riskiest assumption and cheapest experiment
+
+The riskiest assumption is that a configured error regex means “the backend failed this turn”. The
+current code and test already show the counterexample: a worker may quote `API Error:` while writing
+a valid report. Two such false matches on one credential would now remove capacity for 60 seconds.
+
+The cheapest experiment is a replay corpus before Unit 5 ships:
+
+1. Save the full pane text from the measured 2026-09-01 outage.
+2. Produce one safe failure per backend with a disposable invalid endpoint or request.
+3. Save one valid member report which quotes each error line.
+4. Replay all samples through the real `CompletionResolver` test fixture.
+5. Require outage samples to match and quoted-report samples not to match after assistant-block
+   extraction and baseline checks.
+
+This costs no outage deployment and no real sleep. If quoted reports still match, narrow the profile
+patterns before enabling correlation. Do not raise the threshold to hide a bad classifier.
+
+## Sequencing with three developers
+
+First wave:
+
+1. Developer A: Unit 1, typed classification.
+2. Developer B: Unit 2, credential outage policy.
+3. Developer C: Unit 3, lead outage nudge.
+
+As soon as one slot is free, start Unit 4. It is file-disjoint from every first-wave unit. Merge and
+review Units 1 to 4 independently.
+
+Start Unit 5 only after all four foundations and #234 are available. Unit 5 is the only high-conflict
+integration branch, so no other active unit should touch its file list.
+
+## Checks performed for this refinement
+
+- Read issue #201 and issue #227 through their Gitea pages. Both showed zero comments.
+- Read the source and tests named in the evidence section.
+- Ran `git status --short --branch`; the branch was clean before this document was added.
+- Ran `git log --oneline -12` to identify the branch base.
+- I did not run Maven because this change adds only a design document.
+- Rendered both Mermaid blocks with `npx @mermaid-js/mermaid-cli`; both commands succeeded.

docs/CB-301-Session-Manager.md

@@ -2,7 +2,7 @@
 
 **Status:** design spec for review → delegate implementation.
 **Grounded in:** `WorkerService`, `Injector`/`StatusPoller`/`TurnListener`, `MessageService`,
-`BridgeMcp`, `BridgedApp` (see [wiki 9. Implementation](../wiki/9-Implementation.md)).
+`FleetMcp`, `FleetApp` (see [wiki 9. Implementation](../wiki/9-Implementation.md)).
 
 ## Problem
 
@@ -15,7 +15,7 @@ Consequences today:
   since when?" without shelling to herdr for a raw agent list (no state, no ownership, no age).
 - Cleanup of a worker that outlived its owning process depends entirely on the boot-time
   name-nonce **reaper** (CB-117) — there is no live, authoritative roster during a run.
-- `bridge_list` (CB-304) can only surface herdr's view, not a bridge-owned roster.
+- `fleet_list` (CB-304) can only surface herdr's view, not a bridge-owned roster.
 - There is no seam for per-session policy (checkpoint on teardown → CB-302; idle_ttl /
   context_cap / drain → CB-303).
 
@@ -35,7 +35,7 @@ build on.
 - **No checkpoint content.** Writing `STATE.md` + commit on teardown is CB-302; CB-301 only exposes
   the release hook it will attach to.
 
-"Recycle" under no-reuse is simply **release + fresh acquire** — a helper, not a pool operation.
+Under no-reuse, a released session is terminal. A new `acquire` always creates a fresh session.
 
 ## Design
 
@@ -43,14 +43,9 @@ build on.
 subscription-guarded spawn/teardown mechanics; `SessionManager` adds the registry, lifecycle, and
 ownership on top.
 
-**Package:** new `dev.ltms.bridged.session` — keeps the registry/lifecycle concern separate from
+**Package:** new `dev.ltms.fleet.session` — keeps the registry/lifecycle concern separate from
 the `worker` spawn mechanics. Holds `SessionManager` + `WorkerSession`.
 
-**`recycle` is IN SCOPE for CB-301** (decided): implement `recycle(paneId, …)` = `release` the old
-session then `acquire` a fresh one, asserting a new distinct paneId (the no-reuse invariant). It is
-a thin convenience over the two primitives, shipped now so the no-reuse teardown+respawn path is
-covered by a test from day one.
-
 ### `WorkerSession` (record or small mutable holder)
 
 | Field | Source | Notes |
@@ -88,7 +83,6 @@ SPAWNING|READY|BUSY|DONE --vanished/drop--> FAILED
 final class SessionManager {
     WorkerSession acquire(String profile, String requestedCwd, String callerCwd, String ownerTerminal);
     void          release(String paneId);          // deterministic teardown + deregister
-    WorkerSession recycle(String paneId, ...);      // release + acquire (no-reuse convenience)
     Optional<WorkerSession> get(String paneId);
     List<WorkerSession> roster();                   // bridge-owned view (CB-304 consumes this)
     // lifecycle hooks (package-private): onReady/onDelivered/onComplete/onFailed(target)
@@ -102,13 +96,13 @@ final class SessionManager {
 
 ### Integration points
 
-- **`Bridged.main`** — construct `SessionManager(workerService, ...)`; wire it as/decorating the
+- **`Fleetd.main`** — construct `SessionManager(workerService, ...)`; wire it as/decorating the
   `TurnListener` alongside `CompletionResolver` so it sees turn boundaries, and give it the
   `WorkerPresence` signal for `READY`.
-- **`BridgeMcp.spawn` / `BridgedApp.spawnWorker`** — route spawn through `SessionManager.acquire`
-  (carry `callerTerminal` as `ownerTerminal`). **`bridge_stop` / `DELETE /workers/{paneId}`** →
+- **`FleetMcp.spawn` / `FleetApp.spawnWorker`** — route spawn through `SessionManager.acquire`
+  (carry `callerTerminal` as `ownerTerminal`). **`fleet_stop` / `DELETE /workers/{paneId}`** →
   `SessionManager.release`.
-- **`bridge_list` / `GET /sessions` (CB-304 later)** — read `SessionManager.roster()`.
+- **`fleet_list` / `GET /sessions` (CB-304 later)** — read `SessionManager.roster()`.
 - **`MessageService`** — no change required for one-shot; a later CB-303 auto-release hook can call
   `release` from `onTurnComplete` under policy.
 
@@ -120,12 +114,11 @@ final class SessionManager {
 3. `release` tears the worker down via `WorkerService.stop` and removes it from `roster()`;
    a second `release` on the same paneId is a harmless no-op.
 4. `onTurnFailed` / drop moves the session to `FAILED` and it is absent from the live roster.
-5. `recycle` produces a new paneId and the old one is gone (no-reuse invariant).
-6. `roster()` reflects exactly the sessions acquired-minus-released, joined with live status.
+5. `roster()` reflects exactly the sessions acquired-minus-released, joined with live status.
 
 ## Seams left open (deliberately)
 
 - **CB-302** — attach a checkpoint step (`STATE.md` + commit) to the `release` path.
 - **CB-303** — a policy loop over `roster()` using `spawnedAtNanos`/state to auto-`release` on
   `idle_ttl`, or drain on `context_cap`.
-- **CB-304** — `bridge_list` reads `roster()` for a bridge-owned roster + live join.
+- **CB-304** — `fleet_list` reads `roster()` for a bridge-owned roster + live join.

docs/CB-301-ext-Worktree-Provisioning.md

@@ -1,9 +1,13 @@
 # CB-301-ext — Worktree provisioning + config-parity overlay
 
-**Status:** design spec for review → delegate implementation.
+**Status:** ✅ shipped — implemented at commit `97ecc71` (per-worker git worktree + config-parity
+overlay). As-built: `session/GitWorktrees.java` behind the `Worktrees` port, wired in
+`Fleetd.main` and configurable via `worktreeRoot` / per-profile `parityOverlay`
+(see `fleetd.example.yaml`). Branch/worktree surface in `fleet_list` landed with CB-304
+(`9fe04bf`); the worker-opened-PR checkpoint landed as CB-302 (`64e70ef`).
 **Extends:** [CB-301 Session Manager](CB-301-Session-Manager.md) (shipped, commit `54d907c`).
 **Realizes:** the config-parity requirement in [Worker Git Workflow](Worker-Git-Workflow.md).
-**Grounded in:** `SessionManager`, `WorkerService.spawn/effectiveCwd`, `BridgedConfig.Worker`,
+**Grounded in:** `SessionManager`, `WorkerService.spawn/effectiveCwd`, `FleetConfig.Worker`,
 `inject/…LsofPeerPidLookup` (the `ProcessBuilder` exec pattern).
 
 ## Problem
@@ -39,7 +43,7 @@ provider.
 ### `WorktreeRequest` (new, nullable = "no worktree")
 
 ```java
-package dev.ltms.bridged.session;
+package dev.ltms.fleet.session;
 /** Ask 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.
@@ -59,7 +63,7 @@ untouched.
 ### `Worktrees` seam (new)
 
 ```java
-package dev.ltms.bridged.session;
+package dev.ltms.fleet.session;
 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);
@@ -108,7 +112,7 @@ public void release(String paneId) {
 }
 ```
 
-### Config — `BridgedConfig.Worker.parityOverlay` + a `worktreeRoot`
+### Config — `FleetConfig.Worker.parityOverlay` + a `worktreeRoot`
 
 - Add `List<String> parityOverlay` to the `Worker` record (12th field). Compact-constructor default
   when null/empty: `[".mcp.json", ".claude/settings.local.json", ".env", ".envrc"]` (missing paths are
@@ -118,7 +122,7 @@ public void release(String paneId) {
 
 ### Surface: MCP + REST
 
-- `bridge_spawn` gains an optional `worktree` arg: `true`, or a ticket slug string. Truthy ⇒ build a
+- `fleet_spawn` gains an optional `worktree` arg: `true`, or a ticket slug string. Truthy ⇒ build a
   `WorktreeRequest(slug, null)` and call the 5-arg `acquire`.
 - `POST /workers` gains `worktree` (+ optional `ticket`) in the body/query, same mapping.
 - `workerView`/`view(WorkerSession)` include `worktree` and `branch` **when non-null** (omit for

docs/CB-306-Spawn-Readiness-Gate.md

@@ -0,0 +1,143 @@
+# CB-306 — Spawn-Readiness Gate (launcher-owned terminal readiness)
+
+**Status:** design note / delegation spec (branch `worker/cb-306-readiness`)
+**Issue:** gitea `fleet/fleetd` #4
+**Owner of the behaviour:** `ClaudeCodeLauncher` (the `PeerLauncher` adapter) — NOT core.
+
+## 1. Problem
+
+`fleet_spawn` today returns a session the instant the herdr pane is started. The pane is not
+yet a usable Claude REPL — it may still be sitting at the folder-trust prompt, or the CLI may
+never come up at all. Nothing blocks or times out on that. Consequences:
+
+- A `fleet_send` to a not-yet-ready worker surfaces as a **~60 s MCP-client timeout** (the send
+  blocks waiting for a turn that can't start) instead of a fast, explicit spawn failure.
+- A worker stuck at the folder-trust prompt lingers in `SPAWNING` forever; nothing fails it.
+
+We want **fail-fast spawn**: `spawn()` returns only once the peer is genuinely up and usable in
+its terminal, or throws a clean error (and leaves no orphan pane) within a bounded timeout.
+
+## 2. What already exists (do NOT rebuild)
+
+`SessionManager` + `PresenceBridge.markPresent()` already flip a session `SPAWNING → READY` on
+**any MCP contact from the worker** (`onReady(terminal)` → `transitionByTerminal(SPAWNING, READY)`,
+SessionManager ~line 249, "worker became available on the bridge MCP"). That is the **delivery
+lifecycle** and it stays exactly as-is. CB-306 does **not** touch it and does **not** replace it.
+
+CB-306 adds a *complementary, launcher-side* gate: the launcher guarantees the **terminal** is a
+live, interactive REPL before it hands a handle back. The two signals are layered:
+
+| Signal | Owner | Means | CB-306 |
+|---|---|---|---|
+| terminal reaches interactive REPL (herdr `IDLE`) | `ClaudeCodeLauncher` (this ticket) | pane is past folder-trust, CLI is up | **NEW — the spawn gate** |
+| first MCP contact → `SPAWNING→READY` | core (`SessionManager`/`PresenceBridge`) | worker spoke to the bridge | unchanged |
+
+## 3. The readiness predicate (herdr status)
+
+`AgentStatus.fromWire` maps herdr's wire strings to `IDLE | WORKING | BLOCKED | DONE | UNKNOWN`.
+A freshly started pane that has **not** reached an interactive Claude — including one stalled at
+the folder-trust prompt — reports **`UNKNOWN`** (herdr has not detected a Claude REPL yet). Once
+the CLI is up and settled at its prompt it reports **`IDLE`**.
+
+**Predicate:** the pane is *ready* when `AgentControl.status(target)` first returns an
+**injectable** state (`IDLE`, `BLOCKED`, or `DONE` — reuse `AgentStatus.injectable()`). `UNKNOWN`
+= not ready. `WORKING` alone is ambiguous this early and should not by itself satisfy readiness;
+wait for an injectable state. (We do not need to know *why* a pane isn't ready — a trust stall,
+a crash, and a slow start all present as "never becomes injectable" and all correctly time out.)
+
+## 4. Contract change on `spawn(SpawnRequest)`
+
+`ClaudeCodeLauncher.spawn(SpawnRequest)` becomes **block-until-ready-or-throw**:
+
+1. Start the pane exactly as today (`spawn(profile, cwd, callerCwd) → Agent`, build env + guard +
+   argv, `spawnInTab`/`spawnAsPane`, unique-named).
+2. **Poll** `agentControl.status(paneId)` every `pollIntervalMs` (~300 ms) until it is `injectable()`
+   or `spawnReadyTimeoutMs` elapses.
+3. **Ready** → return the `WorkerHandle(paneId, terminalId)` as today.
+4. **Timeout** → the launcher **closes the pane it started** (and its tab, via the same path
+   `release`/`stop` uses) and throws **`PeerUnreachableException`** (new, in `dev.ltms.fleet.peer`).
+   No orphan pane is left behind — the launcher cleans up its own failed birth.
+
+`spawnReadyTimeoutMs == 0` (or unset) **disables** the gate = legacy non-blocking behaviour, so the
+change is opt-in per deployment and existing tests that don't configure it keep their old semantics.
+
+### Testability seam (required)
+
+Do **not** call `Thread.sleep` directly in the poll loop against a real clock — unit tests must not
+real-sleep. Introduce a small injectable seam, mirroring the existing `StatusPoller` style:
+
+- a `LongSupplier nowMillis` (monotonic clock) **and** a sleep/wait hook (e.g. a
+  `Sleeper`/`Waiter` functional interface, or reuse whatever `StatusPoller` already uses), both
+  defaulting to the real implementations in the production constructor and overridable in tests.
+
+Unit tests (add to the existing `ClaudeCodeLauncher` test):
+- fake `AgentControl` returns `UNKNOWN` a few times then `IDLE` → `spawn` returns the handle; assert
+  no `close` was called.
+- fake `AgentControl` always `UNKNOWN` → `spawn` throws `PeerUnreachableException`; assert the pane
+  **was closed** (verify `close(paneId)` invoked) and the fake clock advanced past the timeout.
+- `spawnReadyTimeoutMs == 0` → `spawn` returns immediately without polling (legacy path).
+
+## 5. Config
+
+Add to the launcher-level config (a fleetd-level knob, not per-profile) in `fleetd.yaml` +
+`FleetConfig`:
+
+```yaml
+spawn_ready_timeout_ms: 20000   # 0 disables the gate (legacy non-blocking spawn)
+spawn_ready_poll_ms: 300
+```
+
+Jackson ignores unknown keys, so omitting them in existing YAML is safe; pick sane defaults in code
+(`20000` / `300`). Keep the names consistent with existing config field style in `FleetConfig`.
+
+## 6. Core / MCP propagation
+
+`SessionManager.acquire(...)` already calls `launcher.spawn(req)`. A thrown
+`PeerUnreachableException` must propagate out as a **clean spawn failure**:
+
+- The **worktree** acquire path already has a try/catch that cleans up a provisioned worktree when
+  `spawn` throws — verify the new exception flows through it (worktree removed, nothing registered).
+- The **non-worktree** path registers the session only *after* `spawn` returns, so a throw means no
+  half-live `SPAWNING` session is ever registered — confirm this and add a test.
+- `fleet_spawn` (MCP verb) must return an **error result** carrying the exception message, not a
+  success with a dead session. Trace `FleetMcp`/`FleetApp` spawn handlers and make sure the
+  exception becomes a clean tool error, not an uncaught 500 with a stack trace.
+
+**Out of scope (do NOT do here):** gating `fleet_send` on session `READY` (existing status-gate +
+this spawn gate already close the window), MCP-handshake-as-readiness signal, the CB-307 broker,
+any config `kind:` discriminator, any second adapter.
+
+## 7. Definition of done
+
+- `ClaudeCodeLauncher.spawn` blocks until injectable or throws `PeerUnreachableException` +
+  self-reaps the pane; gate disabled when timeout is 0.
+- New `PeerUnreachableException` in `dev.ltms.fleet.peer`.
+- Config knobs wired (`spawn_ready_timeout_ms`, `spawn_ready_poll_ms`) with safe defaults.
+- Existing `SPAWNING→READY` MCP-contact transition untouched.
+- New unit tests (ready / timeout+reap / disabled) green; **all existing tests still pass unchanged**.
+- Build clean via the worker's own `mvn` (primary re-runs the authoritative IDE + `mvn clean install`
+  gate — self-reports are not verified facts).
+
+## 8. Sequence
+
+```mermaid
+sequenceDiagram
+    participant SM as SessionManager.acquire
+    participant L as ClaudeCodeLauncher.spawn
+    participant T as herdr (AgentControl)
+    SM->>L: spawn(SpawnRequest)
+    L->>T: start pane (env+guard+argv)
+    loop until injectable or timeout
+        L->>T: status(paneId)
+        T-->>L: UNKNOWN / IDLE
+    end
+    alt reached injectable
+        L-->>SM: PeerHandle(id, terminalId)
+    else timed out
+        L->>T: close(paneId) + tab
+        L-->>SM: throw PeerUnreachableException
+        SM-->>SM: no session registered / worktree cleaned
+    end
+```
+
+*Figure — the launcher blocks in `spawn` until the pane is a usable REPL, else self-reaps and throws.*

docs/CB-307-Reliable-Delivery.md

@@ -0,0 +1,201 @@
+# CB-307 Stage 1 — Reply-Inbox Port + In-Memory Adapter (delegation spec)
+
+**Ticket:** gitea #5 (CB-307). **Stage:** 1 of 2 (see the issue's "Implementation staging" comment).
+**Scope of THIS delegation:** the `ReplyInbox` port + the in-memory (soft-state) adapter, wired at the
+exact drop seam so a worker's terminal reply is **held instead of silently discarded** when no primary
+send is open. **No broker, no new dependency, no infra** — fully unit-testable and primary-gate-verifiable.
+Stage 2 (the AMQP/LavinMQ adapter behind the same port) is explicitly **out of scope** here.
+
+> **Read this whole spec before starting.** The port and the publish seam are prescriptive
+> (non-negotiable). Where a choice is genuinely open it says "DECISION" with the required default —
+> follow the default and flag it in your completion message for the primary's review.
+
+## 1. The bug this fixes (grounded in current code)
+
+The reverse (worker→primary) path is `Rendezvous` — a `ConcurrentHashMap<session, CompletableFuture<Resolution>>`
+of **live blocking waiters only**. No queue, no store. When a worker calls `fleet_reply` and **no send
+is currently open** for that worker:
+
+- `Rendezvous.resolve(session, content)` → `complete(...)` → `waiters.get(session) == null` →
+  returns `false` (`msg/Rendezvous.java:212-215`).
+- The `content` string is **never retained** — it is dropped. The worker is told it failed:
+  `FleetMcp.reply` returns `error("no send is awaiting a reply for this worker")` (`mcp/FleetMcp.java:270-272`);
+  REST returns `409 no_pending_send` (`rest/FleetApp.java:339-345`).
+
+This is the observed "communication break": a worker that finishes just after its `fleet_send` timed
+out (the ~60s sync window) replies into the void. There is **no message-id, dedup, or ack** anywhere in
+the message path today.
+
+## 2. What to build
+
+### 2.1 The port — `dev.ltms.fleet.msg.ReplyInbox`
+
+A thin interface owned by the `msg` layer. The in-memory adapter is Stage 1; the AMQP adapter (Stage 2)
+implements the **same** interface, so keep it broker-agnostic.
+
+```java
+package dev.ltms.fleet.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.
+ */
+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) {}
+
+    /**
+     * 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.
+     */
+    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);
+}
+```
+
+### 2.2 The default adapter — `InMemoryReplyInbox`
+
+- Backed by a `ConcurrentHashMap<String, ...>` keyed by target session; per-target FIFO ordering.
+- Dedup by `msgId` within a target (a `LinkedHashMap<msgId, InboxMessage>` per target, or a deque + a
+  seen-set — your call; preserve insertion order).
+- `peek` returns an immutable copy; `ack` removes by `msgId`. Thread-safe (concurrent publish vs. drain).
+- **This is soft-state, NOT persistence.** Lost on a `java -jar` bounce — that is correct and consistent
+  with "fleetd stays soft-state." Do **not** add any file/DB backing.
+
+### 2.3 Publish seam — route reply through the service layer
+
+Keep `Rendezvous` a pure synchronization primitive (do **not** give it an inbox field). Instead centralize
+in `MessageService`, which already owns the `Rendezvous` and will own the `ReplyInbox`:
+
+- Add `MessageService.reply(String session, String content)`:
+  ```java
+  /** Route a worker's explicit fleet_reply: resolve an open send, or queue it in the inbox if none. */
+  public boolean reply(String session, String content) {
+      if (rendezvous.resolve(session, content)) {
+          return true;                       // a live send took it — unchanged fast path
+      }
+      inbox.publish(session, UUID.randomUUID().toString(), content);  // was a silent drop
+      return true;                           // held, not lost
+  }
+  ```
+- Repoint the two callers off the bare `rendezvous.resolve(...)` onto `messages.reply(...)`:
+  - `FleetMcp.reply` (`mcp/FleetMcp.java:262-273`) — on success return a normal ack; **remove** the
+    `error("no send is awaiting a reply…")` branch (that case is now a successful queue).
+  - `FleetApp.replyMessage` (`rest/FleetApp.java:330-346`) — return `200` (queued) instead of
+    `409 no_pending_send`.
+
+**DO NOT touch the QUESTION path.** `fleet_ask` / `rendezvous.resolveQuestion` must keep today's
+`NO_WAITER` behaviour — a mid-turn question is **interactive** (the worker blocks synchronously and cannot
+consume a late answer), so it must **never** be queued. Only terminal `REPLY`s go to the inbox.
+
+**DO NOT queue the completion/failure fallbacks** (`resolveCompletion` / `resolveFailure`,
+`Rendezvous.java:196-210`). They target a *captured* waiter (CB-116); a `false` there means the turn was
+already resolved or the scrape is a stale late duplicate — queueing it risks double-delivery. Leave them
+exactly as they are. (Extending durability to completions is a deliberate Stage-2 consideration, not this.)
+
+### 2.4 Drain seam — how the primary collects a stranded reply
+
+The primary re-checks a worker it delegated to. Expose a drain keyed by **worker session (target)**:
+
+- Add `MessageService.drainReplies(String target)`: `peek` the inbox, `ack` each returned `msgId`, hand
+  back the `List<InboxMessage>` (or just the contents). At-least-once: peek→deliver→ack (ack only after
+  the caller has them, so an in-flight failure re-surfaces them).
+- **DECISION (required default): expose via the existing poll verb, keyed by target.** Extend `fleet_poll`
+  to accept an optional `target` (worker session) and, when present, return that worker's drained replies —
+  alongside a matching REST route `GET /sessions/{id}/replies`. Do **not** change `send`/`answer` semantics
+  (do not drain inside `send` — that conflates "deliver to worker" with "collect its mail"). Keep the
+  existing ticket-based `fleet_poll(ticket)` path working unchanged. If you see a cleaner surface, still
+  ship this default and note the alternative for review.
+
+## 3. Config
+
+**None for Stage 1.** The in-memory adapter is the unconditional default — wire `new InMemoryReplyInbox()`
+into `MessageService` in `Fleetd.main`. Do **not** add a `broker:` config block (that arrives with the
+Stage-2 AMQP adapter: absent → in-memory, present → AMQP).
+
+## 4. Acceptance criteria (what the primary will verify)
+
+1. New `ReplyInbox` + `InboxMessage` + `InMemoryReplyInbox` in `dev.ltms.fleet.msg`.
+2. `fleet_reply` with **no open send** now **succeeds and queues** (no more `error` / `409`); the reply is
+   later retrievable and identical.
+3. The queued reply is drainable by the primary keyed by target; draining **acks** it (a second drain
+   returns nothing); dedup by `msgId` (re-publishing the same id does not double-queue).
+4. **QUESTION path unchanged** — `fleet_ask` with no open send still returns `NO_WAITER` (add/keep a test
+   proving a question is never queued).
+5. Completion/failure fallbacks unchanged.
+6. Unit tests covering: `InMemoryReplyInbox` publish/peek/ack/dedup/FIFO/concurrency; `MessageService.reply`
+   queues on no-waiter and resolves-not-queues when a send is open; `drainReplies` returns+acks;
+   the QUESTION-not-queued guard.
+7. **All pre-existing tests still green** (baseline is **188**; your total must be ≥ 188 + your new tests).
+
+## 5. Build & verification (worker side)
+
+- Build with Maven from the worktree's `fleetd/` dir. **Capture the exit code without a masking pipe**
+  (`mvn clean install; echo "MVN_EXIT=$?"` — never `mvn … | tail`, which hides failures).
+- Read the real test totals from `target/surefire-reports/TEST-*.xml`, not from stdout scroll.
+- You do **not** have IDE MCP access — do not claim `ide_diagnostics` results. The **primary** runs the
+  authoritative gate (IDE sync + diagnostics 0/0 + `mvn clean install`) before integrating. Your
+  self-reported counts are inputs to that gate, not final facts.
+
+## 6. Hard constraints (non-negotiable)
+
+- **`.mcp.json` is `--skip-worktree` in your worktree — never edit, `git add`, or commit it.**
+- **`wiki/` is a submodule — never run git in it; never touch it.**
+- Commit only your feature changes (the new port/adapter, the `msg`/`mcp`/`rest` wiring, tests, and if
+  you add config wiring in `Fleetd.java`). Nothing else.
+- Work only inside your assigned worktree on your feature branch. The primary fast-forwards `main` after
+  re-gating — do not touch `main`.
+- Java 25 idioms are welcome (unnamed `_` params, records). Keep the diff minimal and match surrounding style.
+
+## 7. Definition of done (report back over the bridge)
+
+Commit on your feature branch and reply with: the commit SHA, the surefire total (run/failures/errors), a
+one-line note on the drain-surface decision (§2.4) you shipped, and confirmation that `.mcp.json`/`wiki/`
+were untouched. The primary re-gates and integrates.
+
+## 8. Running the contract tests (CB-521)
+
+`AmqpReplyInboxContractTest` is the real-broker proof of the `ReplyInbox` port (eventual visibility, ack
+removal, msgId dedup, cross-restart redelivery). It is `@Tag("contract")`, so the default
+`mvn test` / `mvn clean install` **skip it** — that hermetic, Docker-free default is deliberate and
+untouched. Run it explicitly when Docker (or a broker) is available:
+
+```bash
+cd fleetd
+mvn -Pcontract test -Dtest=AmqpReplyInboxContractTest   # local: spins a RabbitMQ Testcontainers fixture
+```
+
+### Two broker modes
+
+| Mode | Trigger | Broker | Needs Docker? |
+|---|---|---|---|
+| Local | `AMQP_URI` unset | Testcontainers starts `rabbitmq:3.13-management` | Yes |
+| CI / external | `AMQP_URI` set | the broker at that URI (CI RabbitMQ service container) | **No** — binds straight to the URI, never touches Testcontainers |
+
+In CI the broker is provided as a RabbitMQ **service container** and `AMQP_URI` points at it, so the
+contract job runs the same assertions with no Docker on the runner and no skipped test
+(see `.gitea/workflows/ci.yml` → `contract`). The `build` job stays hermetic and Docker-free — keep
+that separation.
+
+### Docker-engine discovery (why the contract profile pins `api.version`)
+
+Out of the box, Testcontainers 1.20.4's docker-java client defaults to Docker API **1.32** when no
+version is requested. Modern engines reject that as too old — on this host's OrbStack (`min API 1.40`)
+testcontainers fails with *"Could not find a valid Docker environment … client version 1.32 is too
+old"* even though the `docker` CLI works (the CLI negotiates a newer API).
+
+The `contract` Maven profile sets `api.version=1.43` in surefire, which works on OrbStack and Docker
+24+, and is overridable per host: `mvn -Pcontract -Dapi.version=1.54 test …`. It only applies under
+`-Pcontract`, so the default build is unaffected. If your engine differs, set `-Dapi.version` to a
+version ≥ your engine's minimum API (e.g. `docker version` shows `API version`).
+

docs/CB-308-Multi-Host-Federation.md

@@ -0,0 +1,303 @@
+# CB-308 — Multi-Host Federation (Stage 5)
+
+**Status:** design note (proposal) — core design decisions resolved 2026-08-10 (§7)
+**Depends on:** CB-307 (broker-based reliable delivery) — CB-308 is the multi-host layer built *on*
+CB-307's broker fabric.
+**Relates to:** CB-401 (`PeerHandle` opaque id), CB-304 (`rosterView`), CB-306 (spawn-readiness),
+CB-303 (lifecycle limits), CB-117 (orphan reap).
+
+## 1. Goal
+
+Let `claude-bridge` coordinate agents that live on **more than one host** — a primary on host A
+delegating to workers on hosts B, C, … — without any host learning another host's terminals. The
+bus stays a **provider-neutral communication fabric**; multi-host is an addressing + routing
+concern, not a new kind of peer.
+
+The design rests on three pieces (the shape this ticket proposes):
+
+1. **Dedicated per-agent channels** — every agent has its own addressable inbox on the broker.
+2. **A federated agent directory** — a global "who/where/status" lookup, assembled from per-host
+   presence, not a central database.
+3. **A per-host gateway** — each host runs a `fleetd` that owns its local herdr, registers/manages
+   its own sessions, and proxies messages to/from other hosts over the broker.
+
+## 2. What is single-host today (the assumptions to break)
+
+```mermaid
+flowchart TB
+    subgraph host["Single host (today)"]
+        primary["primary<br/>(MCP client)"]
+        daemon["fleetd daemon<br/>127.0.0.1:8765"]
+        reg["in-process registry<br/>keyed by PeerHandle.id() == paneId"]
+        herdr["herdr<br/>(local unix-socket PTY mux)"]
+        w1["worker pane wQ:p1"]
+        w2["worker pane wQ:p2"]
+        primary --> daemon
+        daemon --> reg
+        daemon --> herdr
+        herdr --> w1
+        herdr --> w2
+    end
+```
+
+*Figure 1 — everything is co-located and loopback.*
+
+Three concrete bake-ins assume one host:
+
+| Assumption | Where | Why it blocks multi-host |
+|---|---|---|
+| **herdr is local** | `herdr/` unix socket `~/.config/herdr/herdr.sock` | You cannot drive another host's PTYs → each host **must** own its herdr. This is why a per-host gateway is mandatory. |
+| **registry is in-process, keyed by `paneId`** | `session/SessionManager` | `paneId` (e.g. `wQ:p2B`) is a herdr-local coordinate — meaningless off-host. Routing needs a host-unique id. |
+| **loopback, no authn** | `rest/FleetApp` binds `127.0.0.1:8765` | Fine on one host; the moment a second host can talk to a gateway, that link is a trust boundary. |
+
+## 3. Target architecture
+
+```mermaid
+flowchart TB
+    subgraph hostA["HOST A"]
+        gA["gateway = fleetd A"]
+        regA["local registry + herdr"]
+        primary["primary (MCP client)"]
+        gA --- regA
+        primary --- gA
+    end
+    subgraph hostB["HOST B"]
+        gB["gateway = fleetd B"]
+        regB["local registry + herdr"]
+        wb["worker panes"]
+        gB --- regB
+        gB --- wb
+    end
+    subgraph broker["BROKER (LavinMQ / AMQP) — CB-307 fabric"]
+        inbox["agent.&lt;id&gt;.inbox queues"]
+        roster["roster.* presence topic"]
+        dlq["DLQ · delayed-retry (remind)"]
+    end
+    gA -->|"publish to agent.&lt;id&gt;.inbox"| inbox
+    gB -->|"publish to agent.&lt;id&gt;.inbox"| inbox
+    inbox -->|"owning gateway consumes"| gA
+    inbox -->|"owning gateway consumes"| gB
+    gA -->|"announce local agents"| roster
+    gB -->|"announce local agents"| roster
+    roster -->|"union view"| gA
+    roster -->|"union view"| gB
+```
+
+*Figure 2 — each gateway owns its local herdr + registry, consumes only its own agents' inboxes,
+and announces its agents onto a shared presence topic. The broker routes; no host sees another
+host's terminals.*
+
+### 3.1 Component mapping (the three pieces)
+
+- **Dedicated per-agent channels** = a per-agent AMQP routing key / queue, e.g.
+  `agent.<globalId>.inbox`. The agent's **owning gateway is the only consumer** of its inbox.
+  Senders publish to `agent.<id>.inbox` and never need to know the agent's host — the broker
+  routes to whichever gateway holds it. LavinMQ additionally gives durability, DLX, and a native
+  delayed-message exchange (the remind/backoff loop for free) — the same reasons CB-307 picked it.
+
+- **Federated agent directory** = a **soft-state, bridge-owned** roster, *not* a broker-stored
+  database. Per the persistence-boundary decision (fleetd is soft-state; the broker owns *message*
+  durability, not *who/where/status*), each gateway announces its local agents `(globalId, host,
+  status, capabilities)` on a `roster.*` presence topic with periodic heartbeats. Every gateway
+  builds an eventually-consistent **union view** — literally CB-304's `rosterView`, federated. A
+  stale entry expires by missed heartbeat (reuses CB-303's idle/TTL thinking).
+
+- **Per-host gateway** = today's `fleetd` daemon, evolved. It already registers/manages sessions
+  and controls its local herdr; multi-host adds exactly two responsibilities: (a) a broker client
+  that consumes its agents' inboxes and injects into local herdr, and (b) presence announce +
+  union-roster assembly. Evolution, not rewrite.
+
+### 3.2 Routing rule
+
+```mermaid
+flowchart LR
+    send["fleet_send(globalId, msg)"] --> lookup{"directory:<br/>is globalId local?"}
+    lookup -->|"yes"| local["inject via local herdr<br/>(today's Injector path)"]
+    lookup -->|"no"| pub["publish agent.&lt;id&gt;.inbox<br/>(broker routes to owning gateway)"]
+    pub --> consume["owning gateway consumes<br/>→ injects into its local herdr"]
+```
+
+*Figure 3 — one fork: local agents keep today's in-process inject path; remote agents go over the
+broker. A sender is oblivious to which branch it took.*
+
+## 4. What CB-307 already provides vs. what is net-new
+
+**CB-307 delivers the transport half** and is independently valuable on a single host: the AMQP
+broker fabric, the `fleetd → broker` client/adapter, at-least-once + idempotent (dedup-by-id)
+delivery, DLQ, and delayed-retry (remind). That *is* the "proxy cross-host message" backbone;
+extending the same broker from "worker→primary reliability" to "gateway↔gateway" is incremental.
+
+**Net-new for CB-308 (multi-host), five items:**
+
+1. **Global agent id** — decouple the routing key from `paneId`. CB-401's `PeerHandle` already
+   abstracts the routing id; make it host-unique (e.g. `<host>/<paneId>` or a UUID minted at spawn).
+   The registry and all verbs route on the global id.
+2. **Federated directory** — presence announce + heartbeat + union roster over `roster.*`
+   (§3.1).
+3. **Gateway routing** — the `local ? inject : publish` fork (§3.2), plus each gateway consuming
+   its own agents' inbox queues and injecting into local herdr.
+4. **Cross-host spawn** — `spawn on host B` = publish a control request to B's control channel →
+   gateway B runs `ClaudeCodeLauncher.spawn` **locally** (CB-306's readiness gate becomes *more*
+   valuable here: the far side wants a positive "agent ready" before anyone sends) → announces the
+   new agent into the federated roster.
+5. **Trust** — the broker connection is now the security boundary. A gateway injects env/tokens at
+   daemon privilege (the CB-401 Stage-C concern), so a **remote-triggered spawn/send** needs
+   authn/authz: who may act on which host, and which control channels a gateway will honour.
+   *Authenticity* is resolved — signed messages, §7.1; *authorization* (who may do what) remains
+   open — §8.
+
+## 5. The one thing the broker does NOT dissolve
+
+The MCP asymmetry survives the network. The primary is an MCP **client** to its **local** gateway;
+it cannot be called into. A worker on B replying to a primary on A flows:
+
+```mermaid
+sequenceDiagram
+    participant W as worker (host B)
+    participant GB as gateway B
+    participant BR as broker
+    participant GA as gateway A
+    participant P as primary (host A, MCP client)
+    W->>GB: fleet_reply
+    GB->>BR: publish primary-bound (durable, msg id)
+    BR->>GA: route to A's primary inbox
+    Note over GA: held durably until the primary pulls
+    P->>GA: blocking fleet_send resolves / fleet_poll
+    GA-->>P: reply (then ACK to broker)
+```
+
+*Figure 4 — the broker makes the middle hop lossless, ordered, and idempotent; the **final** hop
+into the primary is still a **pull** (gateway A holds the message until the primary's blocking
+`fleet_send` or `fleet_poll`). Cross-host neither improves nor worsens this — it just spans hosts.
+This is precisely the gap CB-307 closes on one host and CB-308 stretches across hosts.*
+
+## 6. Staging & dependencies
+
+```mermaid
+flowchart LR
+    cb307["CB-307<br/>broker-based reliable delivery<br/>(single host first)"] --> cb308["CB-308<br/>multi-host federation<br/>(this note)"]
+    cb308 --> a["global agent id"]
+    cb308 --> b["federated directory"]
+    cb308 --> c["gateway routing"]
+    cb308 --> d["cross-host spawn"]
+    cb308 --> e["cross-host trust model"]
+    classDef gate fill:#b7791f,stroke:#7b341e,color:#ffffff;
+    class e gate
+```
+
+*Figure 5 — CB-307 is the foundation; CB-308's five items build on it. The trust model (e) is the
+gating concern before any host accepts remote control.*
+
+**Recommendation:** keep CB-307 scoped to single-host broker reliability (foundation, independently
+useful), and build CB-308's items on top once the broker fabric exists. Choose CB-307's broker /
+channel naming **multi-host-ready** now (per-agent routing keys, a `roster.*` topic namespace) so
+CB-308 doesn't have to repaint the topology.
+
+## 7. Resolved design decisions (2026-08-10)
+
+Settled in a design review of this note + wiki chapter 10. The broker-level operational rules
+(inbox caps, TLS + private broker, schema versioning, trace id, exclusive consumers, U8 broadcast)
+are recorded in wiki 10 §10; the CB-308-side decisions are below. Entries 1–6 are the first-pass
+decisions; 7–10 came out of the adversarial second-pass review (same day) and supersede 1–6 where
+they overlap (notably: the envelope is no longer optional, and dedup is split by path).
+
+1. **Sender authenticity — sign every message.** Each gateway holds its own signing key and signs
+   what it publishes (sender gid, `msgId`, timestamp). The receiving gateway verifies the
+   signature **and** checks against the roster that the claimed sender lives on the signing
+   gateway's host. This extends the single-host invariant — *identity comes from the connection,
+   never an argument* — across the broker: cross-host, identity comes from the key. Complements
+   (not replaces) per-gateway broker logins over TLS.
+2. **Profiles are owned by the worker's host.** `fleet_spawn(profile, host)` resolves the name in
+   the *target* gateway's `fleetd.yaml`. Gateways advertise their profile names in presence
+   heartbeats, so a leader sees what each host offers before spawning; an unknown name is a clear
+   error from the target. Secrets (base URLs, tokens) never leave the host that uses them.
+3. **Repo provisioning — clone from the forge, pinned.** A cross-host spawn names the repo URL and
+   the exact commit. The target gateway clones from the forge into a local cache (first spawn
+   only), then cuts a per-worker worktree — the CB-301-ext flow with a clone step in front,
+   covered by the same repo-scoped forge token (CB-302). Git stays the only channel code moves
+   through.
+4. **Asks are live-only, with expiry.** `ASK`/`ANSWER` (U2) traverse the broker as short-lived
+   (TTL'd) messages carrying the `turn_id`, and are never held durably — the single-host rule
+   kept. An answer arriving after its turn ended is **not** injected; it is dropped and the leader
+   gets a `TOO_LATE` notice, so the one failure case is loud rather than weird. Only terminal
+   replies are durable. Walkthrough: wiki 10 §7.4.
+5. **Spawn dedup — a spawn id, remembered on the target.** The control queue redelivers like any
+   queue; a replayed `SpawnRequest` must not double-spawn. Requests carry a unique spawn id; the
+   target gateway keeps a short memory of handled ids and answers a redelivery with the existing
+   `PeerHandle`. CB-117's orphan reap stays as the backstop.
+6. **Broker down — local unaffected, remote fails fast.** The routing fork (§3.2) means same-host
+   traffic never touches the broker; that is now a written promise. A send to a remote agent while
+   the broker is unreachable **fails immediately** with a clear error — the gateway never buffers
+   on the broker's behalf (it stays soft-state, so a crash cannot lose messages it claimed to
+   deliver). Gateways auto-reconnect; remote hosts read as unknown in the roster meanwhile. Broker
+   HA is a later ops choice, not a design requirement.
+
+7. **Turn state — split by where the signals are.** The *worker's* gateway owns the turn record
+   (turnId minting, ask coalescing, STALE_TURN, the completion/failure fallbacks, CB-516 abandon):
+   every input to those decisions — pane status, injection, teardown — is local to it. The
+   *sender's* gateway owns only the waiter. The two are stitched by terminal-outcome envelope
+   kinds (`REPLY` / `FAILED` / `ABANDONED`) published to the sender's inbox: a worker dying on B
+   fails A's waiter fast because gateway B sees the death synchronously and says so.
+   **`ABANDONED` is belt-and-braces over the waiter's own timeout and roster expiry, never a
+   replacement** — the case where the waiter hangs longest is gateway B itself dying, which is
+   exactly when B can publish nothing.
+8. **Dual ack model + spawn idempotence by construction.** Forward path (a brief into a worker):
+   ack **before** the inject — at-most-once, duplicates structurally impossible; the loss window
+   is closed by an `INJECTED` confirmation published after the inject lands (no `INJECTED` within
+   a bound = loud fast failure at the sender, not a silent send-timeout). Reply/pull path keeps
+   ack-after-drain — a duplicate reply is benign, deduped by `msgId`. Spawn: the requester mints
+   **spawn id = the new worker's gid**; the target checks it against the **live pane registry**,
+   and the gid is **stored in the herdr pane itself** (label/env, readable back), so a restarted
+   gateway rebuilds gid↔pane from herdr and the check survives restarts with *no persisted
+   ledger* — this storage point is the load-bearing detail of the no-ledger position. An
+   **in-flight reservation set**, entered before the launcher call, absorbs a redelivery arriving
+   while the first spawn is still inside CB-306's readiness gate; a crash mid-spawn leaves a
+   half-built pane, which is exactly what CB-117 reaps.
+9. **Publish is enforced, not fire-and-forget.** Publisher confirms + the `mandatory` flag + a
+   return listener, on a **publish channel separate from the consume/ack channel** — synchronous
+   confirms on the single shared channel would hold its lock across a broker round trip and
+   serialize acks fleet-wide. Ordering caveat: a *return* (unroutable) arrives **before** the
+   confirm, so "confirmed" ≠ "routed"; the sender checks the returned-set at confirm time.
+   `mandatory` is false only for `BROADCAST`, where an empty group is legal silence.
+10. **Queue lifecycle is session lifecycle.** `fleet_stop`/reap deletes the worker's inbox queue
+    (its `broadcast.*` bindings die with it — no broadcasts to the dead); `x-expires` collects
+    queues orphaned by a crashed gateway (long for main/orchestrator inboxes, short for workers).
+    Queue names carry a version suffix (`.v2`): AMQP refuses to redeclare an existing durable
+    queue with new arguments (`PRECONDITION_FAILED` — a crash loop on an in-place upgrade from
+    v1.0.0), and the suffix keeps old sender-keyed and new recipient-keyed queues apart during
+    the keying migration (wiki 10 §3 footnote).
+
+## 8. Still open
+
+- **Directory ground-truth:** pure soft-state presence (heartbeats) vs. also treating broker queue
+  existence as authoritative. Lean soft-state to preserve the persistence boundary; revisit if
+  split-brain roster views cause mis-routing.
+- **Gateway discovery:** how gateways find the broker and each other (static config vs. discovery).
+- **Control authorization — THE GATE ON U4.** Signing (§7.1) settles *who sent it*; authorization
+  is *who may do what*. **Cross-host spawn must not land before the minimal version exists**: a
+  per-host allowlist in `fleetd.yaml` — beside the peer public keys — of gateway ids permitted to
+  publish control to this host, checked against the verified signature. A few lines of config and
+  check; without them, any principal holding broker credentials can start processes on every host
+  in the fleet.
+- **Key distribution & rotation:** static config (host → public key in each `fleetd.yaml`) is
+  fine at the current 2–3 host scale; rotation is manual. A refinement, not a blocker.
+- **Gateway death mid-turn:** the roster reaps it by missed heartbeat, and in-flight primary-bound
+  messages survive by broker durability; still open is reconciling *worker* state when the dead
+  gateway's host comes back (orphaned panes vs. still-valid sessions).
+
+*(Resolved and moved up: the global id scheme — an opaque UUID minted by the spawn requester as
+the spawn id, host carried as roster metadata; §7.8.)*
+
+## 9. Implementation order (each step verifiable single-host)
+
+1. **As-built fixes, independent of CB-308** (v1.0.x tickets): `basicQos` prefetch on the AMQP
+   consumer (today the queue drains into gateway heap, so any cap would guard an empty queue);
+   publisher confirms + `mandatory` (§7.9); the `drainReplies` javadoc that claims "the ack is
+   local" — false for the AMQP adapter.
+2. Envelope + signing (wiki 10 §2.1) — testable against the single-host broker.
+3. Recipient-keyed queue migration (`.v2` names, drain-by-`from`, `ReplyPushLoop` rekeyed).
+4. Global id + queue lifecycle (§7.8, §7.10).
+5. Roster: host-level heartbeat + signed presence; then the routing fork (§3.2).
+6. U2 cross-host with the terminal-outcome kinds (§7.4, §7.7).
+7. U4 cross-host spawn — **gated on the control allowlist (§8)**.
+8. U8 broadcast **last** — it is the feature that punishes an unfinished queue lifecycle.

docs/CB-401-Peer-Launcher-SPI.md

@@ -7,7 +7,7 @@ the core learning any one peer's environment.
 ## 1. Why
 
 `claude-bridge` is a **communication bus between heterogeneous AI agents** — its stable surface is
-the protocol (`bridge_spawn / send / poll / reply / ask / list / stop / status`), and that surface
+the protocol (`fleet_spawn / send / poll / reply / ask / list / stop / status`), and that surface
 should stay provider-neutral. Today the daemon can only materialize one kind of peer: an
 off-subscription Claude Code CLI over herdr. Everything specific to *how that peer is set up*
 (`ANTHROPIC_BASE_URL`, the subscription guard, `--mcp-config`/system-prompt flags, `claude-*`
@@ -60,7 +60,7 @@ Where Claude/herdr specifics actually live today:
 | `claude-<profile>-<nonce>-<seq>` naming, `WORKER_NAME` regex, orphan reap (CB-117) | `WorkerService` | **→ adapter** (naming is a herdr-label detail) |
 | `GITEA_TOKEN` / `GITEA_HOST` injection (CB-302 checkpoint) | `WorkerService.spawn` | **→ adapter** + a **capability** (§6) |
 | tab/pane placement, worker space, tab labels | `WorkerService.spawnInTab/spawnAsPane` via herdr `WorkspaceControl` | **→ adapter** (herdr transport detail) |
-| `BridgedConfig.Worker` profile shape (`baseUrl`, `model`, `configDir`, …) | `config` | **mostly adapter-shaped** — see §5 |
+| `FleetConfig.Worker` profile shape (`baseUrl`, `model`, `configDir`, …) | `config` | **mostly adapter-shaped** — see §5 |
 | FSM, registry, roster, `reapIdle`/`drainAll`/`contextCap`, `rosterView` | `SessionManager` | **stays core** |
 | turn/completion detection (`TurnListener`, `CompletionResolver`, `StatusPoller`, `WorkerPresence`) | `inject/` | **stays core**, but reads herdr terminal output → transport-coupled (§4b) |
 | message store & routing | `msg/` | **stays core** |
@@ -118,7 +118,7 @@ hard-wire "turns come from herdr".
 
 ## 5. Config shape
 
-`BridgedConfig.Worker` is Claude-shaped (`baseUrl`, `model`, `configDir`, `tokenEnv`). Rather than
+`FleetConfig.Worker` is Claude-shaped (`baseUrl`, `model`, `configDir`, `tokenEnv`). Rather than
 break existing YAML, CB-401 keeps `workers:` exactly as-is and treats those fields as the
 **ClaudeCodeLauncher's** profile schema. A future peer kind adds a `kind:` discriminator
 (default `"claude-code"`) selecting the launcher; unknown-kind → clear config error. No migration of
@@ -126,7 +126,7 @@ existing configs. (Jackson already ignores unknown keys, so adding `kind` is bac
 
 ```mermaid
 sequenceDiagram
-    participant MCP as bridge_spawn (MCP/REST)
+    participant MCP as fleet_spawn (MCP/REST)
     participant SM as SessionManager
     participant L as PeerLauncher (by profile.kind)
     participant T as transport (herdr)
@@ -150,7 +150,7 @@ degrades gracefully when a launcher lacks one:
 
 | Capability | Meaning | Claude Code | Codex (likely) | Human |
 |---|---|---|---|---|
-| `MID_TURN_ASK` | supports `bridge_ask` rendezvous | ✓ | ? | ✗ |
+| `MID_TURN_ASK` | supports `fleet_ask` rendezvous | ✓ | ? | ✗ |
 | `SELF_PR` | can open its own PR at checkpoint (CB-302) | ✓ (opt-in token) | ? | ✗ |
 | `WORKTREE` | can run in a provisioned git worktree | ✓ | ✓ | ✗ |
 | `ORPHAN_REAP` | spawner can reconcile orphaned peers on boot | ✓ | ? | ✗ |
@@ -185,13 +185,13 @@ messages, not verified facts.
 Deliverable for CB-401 Stage A — mechanical, behaviour-preserving:
 
 1. `PeerLauncher` interface + `PeerHandle` (opaque id) + `SpawnRequest` (profile, requestedCwd,
-   callerCwd) + `Capability` enum, new package `dev.ltms.bridged.peer`.
+   callerCwd) + `Capability` enum, new package `dev.ltms.fleet.peer`.
 2. `ClaudeCodeLauncher implements PeerLauncher` = today's `WorkerService`, adapted: `spawn(...)`
    returns a `PeerHandle` (id = paneId), `capabilities()` declares
    `MID_TURN_ASK, SELF_PR(when token), WORKTREE, ORPHAN_REAP`.
 3. `SessionManager` depends on `PeerLauncher`, not `WorkerService` concretely; routing keys on
    `PeerHandle.id()` (== paneId today, so zero value change).
-4. `Bridged.main` wires the concrete `ClaudeCodeLauncher` behind the interface.
+4. `Fleetd.main` wires the concrete `ClaudeCodeLauncher` behind the interface.
 5. **No behaviour change, no config change.** Full green gate: `ide_sync` → `ide_diagnostics`
    (0 errors/0 warnings) → `mvn clean install` with `MVN_EXIT` captured (no masking pipe). All
    existing tests pass unchanged; add tests only for the new `PeerHandle` indirection.

docs/CB-402-OpenCode-Adapter.md

@@ -0,0 +1,305 @@
+# CB-402 — Second peer adapter: opencode (Stage B of the Peer Launcher SPI)
+
+**Status:** ✅ **complete — implemented, merged (`ded226a`), and live-dogfooded 2026-07-29.**
+All five increments of §4 are done, including increment 5 (the §5 live checklist). See
+[§8 As-built](#8-as-built--live-dogfood-2026-07-29) for the run. Gitea issue #7 closed.
+**Depends on:** CB-401 Stage A (`PeerLauncher` SPI, merged `3aa69a9`)
+**Stage:** 4 (Pluggable peers) · Stage B
+**Owner action:** design-note → file issue → delegate → primary-verify (per CB-401/306/307)
+
+---
+
+## 1. Goal
+
+Prove the [`PeerLauncher`](../fleetd/src/main/java/dev/ltms/fleet/peer/PeerLauncher.java) SPI
+actually holds for a **non-Claude** coding agent by shipping a second, first-class in-tree
+adapter: **opencode** (`opencode` 1.1.31, a provider-agnostic terminal coding agent).
+
+The product direction is *heterogeneous coding agents, Claude Code first-class* — not a
+human/mock peer. opencode is the right proof precisely because it differs from Claude Code on
+every seam the SPI is meant to hide:
+
+| Seam | Claude Code | opencode | ⇒ SPI proof |
+|------|-------------|----------|-------------|
+| Subscription boundary | `ANTHROPIC_BASE_URL` + `SubscriptionGuard.assertWorker()` before any herdr call | none — provider-agnostic, off-subscription by nature | the guard is **Claude-private**, not core |
+| MCP mount | inline `--mcp-config '{…}'` launch flag | `opencode mcp add` / config file (`OPENCODE_CONFIG`) — **no inline flag** | "mount the bridge MCP" is adapter-private |
+| Instruction injection | `--append-system-prompt "<REPLY_CHARTER>"` | config `instructions` / `AGENTS.md` / `--agent` — **no append flag** | the reply-charter mount is adapter-private |
+| Model selection | `ANTHROPIC_MODEL` env | `-m provider/model` flag | env-vs-flag is adapter-private |
+| Name / reap scheme | `claude-<profile>-<nonce>-<seq>` | `opencode-<profile>-<nonce>-<seq>` | each adapter reaps only its own kind |
+
+Everything *else* — herdr tab/pane placement, the CB-306 spawn-readiness gate, CB-301-ext
+worktree provisioning, CB-117 orphan reap, teardown, `list()`, cwd resolution — is transport
+machinery that is **identical** for both. That split is the whole design.
+
+> Out of scope (deferred to Stage C / later): dynamic external plugin loading behind a
+> trust/capability model, capability *enforcement* at the verb layer (Stage A only *declares*
+> caps), and a `human`/mock peer.
+
+---
+
+## 2. Current state — one launcher, two concerns mixed
+
+`ClaudeCodeLauncher` (584 LOC) is the sole `PeerLauncher`. It interleaves two concerns:
+
+```mermaid
+flowchart TB
+    subgraph CCL["ClaudeCodeLauncher (584 LOC) — today"]
+        direction TB
+        T["herdr transport (GENERIC / reusable)<br/>tab-pane placement · spawn-ready gate · worktree<br/>orphan reap · teardown · list · cwd resolution · unique naming"]
+        C["Claude-specific (per-agent)<br/>ANTHROPIC_BASE_URL + SubscriptionGuard · ANTHROPIC_MODEL<br/>argv --mcp-config · --append-system-prompt REPLY_CHARTER · 'claude-' name prefix"]
+    end
+    classDef generic fill:#2f855a,stroke:#22543d,color:#ffffff;
+    classDef specific fill:#b7791f,stroke:#7b341e,color:#ffffff;
+    class T generic
+    class C specific
+```
+
+*Figure 1 — the two concerns tangled inside today's single launcher; CB-402 splits them.*
+
+There is also a **Stage-A deferral** to finish: `Fleetd.main` still casts
+`(ClaudeCodeLauncher) workers` at the `FleetMcp` and `FleetApp` constructors. Those two
+callers only invoke `profiles()`, `defaultProfile()`, and `list()` — **all already on the
+`PeerLauncher` interface**. The cast survives for one reason only: `PeerLauncher.list()`
+returns `List<?>` (element type erased) while the callers use `Agent` element methods in their
+roster join. Finishing the migration is therefore small and contained (§4.D).
+
+---
+
+## 3. Target design
+
+Template-Method base + two thin adapters + a routing composite that keeps the Stage-A seam
+(one `PeerLauncher` reference held by `SessionManager` / `FleetMcp` / `FleetApp`) intact.
+
+```mermaid
+flowchart TB
+    IFACE["«interface»<br/>PeerLauncher"]
+    COMP["CompositePeerLauncher<br/>routes by profile kind; fans out list/reap/caps"]
+    BASE["«abstract»<br/>HerdrPeerLauncher<br/>transport: placement · ready-gate · reap · stop · cwd · naming"]
+    CCL2["ClaudeCodeLauncher<br/>hooks: guard+ANTHROPIC_* env · --mcp-config · charter flag · prefix 'claude'"]
+    OCL["OpenCodeLauncher<br/>hooks: provider env · OPENCODE_CONFIG file · AGENTS charter · prefix 'opencode'"]
+
+    IFACE -.implemented by.-> COMP
+    IFACE -.implemented by.-> BASE
+    BASE --> CCL2
+    BASE --> OCL
+    COMP -->|"kind=claude-code"| CCL2
+    COMP -->|"kind=opencode"| OCL
+
+    classDef iface fill:#2b6cb0,stroke:#1a365d,color:#ffffff;
+    classDef base fill:#2f855a,stroke:#22543d,color:#ffffff;
+    classDef leaf fill:#6b46c1,stroke:#44337a,color:#ffffff;
+    class IFACE,COMP iface
+    class BASE base
+    class CCL2,OCL leaf
+```
+
+*Figure 2 — extracted base, two adapters, and a routing composite behind the unchanged SPI.*
+
+### A. Extract `HerdrPeerLauncher` (abstract base)
+
+Move all transport machinery down from `ClaudeCodeLauncher`. What stays generic:
+
+- fields `agents`, `spaces`, `profiles`, `defaultProfile`, `env`, `nameSeq`, the CB-306 gate
+  knobs (`spawnReadyTimeoutMs`/`spawnReadyPollMs`/`nowMillis`/`sleeper`), and `nameNonce`;
+- `profiles()`, `defaultProfile()`, `parityOverlay()`, `effectiveCwd(…)`, `resolveCwd`;
+- the `spawn(SpawnRequest)` **skeleton**: resolve profile → cfg → *hook* → placement → gate → `WorkerHandle`;
+- `spawnInTab` / `spawnAsPane` / `tidy` / `startUniquelyNamed` (name built from a *hook* prefix);
+- `list()`, `reapOrphanWorkers()` / `isForeignWorker` / `workerNonce` (pattern built from the prefix hook), `stop()` / `usesTabPlacement` / `isAlreadyGone`;
+- `waitUntilInjectableOrThrow`, the `WorkerHandle` record, `putIfPresent`, `resolveEnv`, `sleepUninterruptibly`.
+
+Two adapter **hooks** (abstract):
+
+```java
+/** Label prefix for this peer kind; drives unique naming AND the orphan-reap pattern. */
+protected abstract String namePrefix();               // "claude" | "opencode"
+
+/** Build the peer-specific launch: env map + argv. Runs any pre-spawn guard here. */
+protected abstract Launch buildLaunch(FleetConfig.Worker cfg, SpawnRequest req);
+record Launch(Map<String,String> env, List<String> argv) {}
+```
+
+`capabilities()` stays abstract/per-adapter (it already is). The subscription guard is **not**
+a base field — it is a constructor dependency of `ClaudeCodeLauncher` alone.
+
+**Reap isolation:** the reap pattern becomes `Pattern.compile(namePrefix() + "-.*-([0-9a-f]{6})-\\d+")`,
+so the opencode adapter never reaps a `claude-*` pane and vice-versa. The composite sums both.
+
+### B. `kind:` config discriminator
+
+Add one field to `FleetConfig.Worker`:
+
+```java
+String kind          // "claude-code" (default) | "opencode"
+```
+
+- Compact-ctor default: `kind = blank ? "claude-code" : kind.toLowerCase()`.
+- `argv` default is currently `List.of("claude")`; when `kind=opencode` and the operator left
+  `argv` unset, default it to `List.of("opencode")`. (Handle in normalization, keyed off `kind`,
+  so the record stays declarative.)
+- Keep the existing back-compat constructors; `kind` is additive and optional.
+
+`fleetd.example.yaml` documents a two-kind `workers:` block.
+
+### C. `OpenCodeLauncher` — the adapter hooks for opencode
+
+`namePrefix()` → `"opencode"`. `buildLaunch(cfg, req)`:
+
+- **Env:** *no* `ANTHROPIC_BASE_URL`, *no* `SubscriptionGuard` call. Pass through provider
+  credentials the operator names (reuse the existing `tokenEnv` indirection; opencode reads
+  provider keys from env / `opencode auth`). CB-302 git-token injection is reused unchanged
+  (it is peer-neutral: `GITEA_TOKEN`/`GITEA_HOST`).
+- **MCP mount (non-invasive):** opencode has no inline `--mcp-config`. The adapter writes a
+  throwaway config file and points `OPENCODE_CONFIG=<tempfile>` in the worker env, containing
+  the bridge MCP server block (opencode HTTP MCP schema, `type: "remote"`) — the opencode analog
+  of Claude Code's inline flag. Nothing is written into the worker's real project or profile.
+- **Reply-charter:** carry `REPLY_CHARTER` as an `instructions` entry in that same generated
+  config (or an `AGENTS.md` written into the per-worker worktree, which is already a throwaway
+  isolated checkout under CB-301-ext). Recommend the config-file route to keep the "touch
+  nothing the user owns" invariant.
+- **argv:** `opencode <project-or-cwd>` (interactive TUI, the mode a herdr pane drives), plus
+  `-m <provider/model>` when the profile sets a model.
+
+> `REPLY_CHARTER` is peer-neutral text — hoist it to a shared constant (base or a small
+> `PeerCharter`), consumed by each adapter through its own injection mechanism.
+
+### D. `CompositePeerLauncher` + finish the Stage-A migration
+
+- `Fleetd.main` groups configured profiles by `kind`, instantiates one launcher per kind
+  present, and wraps them in `CompositePeerLauncher implements PeerLauncher`.
+- Routing methods (`spawn(req)`, `effectiveCwd(req)`, `parityOverlay(name)`) dispatch by the
+  profile's kind. Fan-out methods (`list()`, `reapOrphanWorkers()`, `capabilities()`,
+  `profiles()`, `defaultProfile()`) merge across sub-launchers. `stop(id)` tries each (teardown
+  only knows the pane id) — already best-effort/idempotent.
+- **Migrate `FleetMcp` + `FleetApp` to the `PeerLauncher` interface**, dropping both
+  `(ClaudeCodeLauncher)` casts. Only friction is `list()`'s `List<?>`; resolve by giving the SPI
+  a typed roster element (small neutral `PeerAgent` view exposing `id()`/`name()`/status) that
+  the CB-304 roster join consumes — or, minimally, narrow at the callsite. Prefer the typed view.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant P as Primary
+    participant M as FleetMcp / REST
+    participant C as CompositePeerLauncher
+    participant O as OpenCodeLauncher
+    participant B as HerdrPeerLauncher (base)
+    participant H as herdr
+    P->>M: fleet_spawn(profile="oc-impl")
+    M->>C: spawn(SpawnRequest)
+    C->>C: kind(profile)=="opencode"
+    C->>O: spawn(req)
+    O->>O: buildLaunch → provider env + OPENCODE_CONFIG file + argv
+    O->>B: placement + startUniquelyNamed("opencode-…")
+    B->>H: agent.start(name, argv, env, tab, cwd)
+    B->>H: poll status until injectable (CB-306 gate)
+    B-->>O: Agent
+    O-->>C: PeerHandle(paneId, terminalId)
+    C-->>M: PeerHandle
+    M-->>P: session id
+```
+
+*Figure 3 — an opencode spawn: composite routes by kind, adapter builds the peer-specific launch, shared base drives herdr + the readiness gate.*
+
+---
+
+## 4. Increment plan (delegate-then-verify friendly)
+
+1. **Extract base, no behaviour change.** Introduce `HerdrPeerLauncher`; make
+   `ClaudeCodeLauncher` extend it with `namePrefix()="claude"` and `buildLaunch()` wrapping
+   today's guard+env+argv logic. Green build, identical tests — pure refactor. *(IDE
+   `refactor` where possible; the primary re-runs the gate workers can't.)*
+2. **`kind:` discriminator.** Add the field + normalization + `fleetd.example.yaml`. Default
+   path unchanged (`kind=claude-code`).
+3. **`OpenCodeLauncher`.** Implement the three hooks; unit-test `buildLaunch` (env has no
+   `ANTHROPIC_BASE_URL`; `OPENCODE_CONFIG` points at a file carrying the bridge MCP block +
+   charter; argv shape).
+4. **`CompositePeerLauncher` + wiring + finish Stage-A migration** (drop the two casts).
+5. **Live dogfood** (§5) + wiki as-built (primary-gated submodule commit).
+
+Each increment is independently buildable/mergeable; the feature branch stays **unmerged**
+until it is "major" (Stage-B whole), per the CB-401 bar.
+
+---
+
+## 5. Risks & validation (live dogfood, not assumed)
+
+- **opencode TUI ⇄ herdr injection.** herdr drives a pane by typing into a TUI. Must confirm
+  opencode's TUI accepts injected keystrokes/submit the way `claude` does, and reaches an
+  `injectable` status the CB-306 gate recognizes. *Validation:* spawn one opencode worker,
+  watch the readiness gate pass, `fleet_send` a trivial task.
+- **Bridge MCP visibility in opencode.** Confirm `OPENCODE_CONFIG` (or `opencode mcp add`)
+   actually surfaces the `fleet_*` tools inside the opencode session, and that `fleet_reply`
+  is callable — the reply-charter is worthless if the tool isn't mounted. *Validation:* the
+  worker completes a task by calling `fleet_reply`; the reply lands via the CB-307 path.
+- **opencode MCP/config schema drift.** opencode is fast-moving (1.1.31 today). Pin the config
+  schema we generate against the installed version; treat the exact keys (`type: "remote"` vs
+  `"http"`, `instructions` shape) as a dogfood-verified fact, not an assumption.
+- **Provider credentials.** opencode needs a configured provider (env key or `opencode auth`).
+  The dogfood profile must name a provider the host actually has, distinct from the primary's
+  subscription.
+
+---
+
+## 6. Test plan
+
+- **Unit (hermetic):** base-extraction regression (existing `ClaudeCodeLauncher` tests pass
+  unchanged); `OpenCodeLauncher.buildLaunch` env/argv/config assertions; `kind` normalization
+  in `FleetConfigTest`; `CompositePeerLauncher` routing + fan-out (merge of `profiles()`,
+  summed `reapOrphanWorkers()`, per-kind reap isolation) with fake sub-launchers.
+- **Live (dogfood, manual):** the §5 checklist on the running daemon.
+- **Gate (primary):** IDE diagnostics 0/0 on every changed file, `mvn clean install` green with
+  the surefire summary captured (not `| tail`), manual diff review — the authoritative checks a
+  worker cannot self-run.
+
+---
+
+## 7. Open questions for the lead
+
+1. ✅ **Provider — resolved 2026-07-29.** None was needed. opencode's own gateway serves
+   **free-tier models with zero credentials** (`opencode auth list` → *0 credentials*, yet
+   `opencode run -m opencode/north-mini-code-free` answers). The dogfood profile uses
+   `opencode/north-mini-code-free`. It is distinct from the primary's Anthropic subscription by
+   construction, and needs no `guard` entry — opencode carries no `ANTHROPIC_BASE_URL`, so the
+   `SubscriptionGuard` does not apply to it at all.
+2. ✅ **Charter carrier — confirmed as designed:** generated `OPENCODE_CONFIG` `instructions`.
+   Verified working against the installed version.
+3. ✅ **Merge cadence — resolved as it happened:** Stage B landed as one unit (`ded226a`).
+
+---
+
+## 8. As-built — live dogfood (2026-07-29)
+
+Run against `fleetd` on `127.0.0.1:8766` at main `19cdf8d`, with opencode **1.18.5** installed
+via Homebrew. Every §5 risk is now a verified fact rather than an assumption.
+
+**The version-drift risk was the real one, and it did not bite.** This adapter was designed against
+opencode **1.1.31**; the installed version is **1.18.5**. The generated config schema still
+validates unchanged — `mcp.<name>.type: "remote"`, `url`, `enabled`, and `instructions: [path]` are
+all accepted, and `OPENCODE_CONFIG=… opencode mcp list` reports `✓ bridge connected`. Pinned here
+as a dogfood-verified fact for 1.18.5.
+
+| §5 risk | Result |
+|---|---|
+| opencode TUI ⇄ herdr injection; CB-306 gate | ✅ `peer pane=wD:p3 reached injectable state` ~0.6s after `agent.start` |
+| Bridge MCP visible + `fleet_reply` callable | ✅ MCP `initialize` from `Implementation[name=opencode, version=1.18.5]`; worker replied through the tool |
+| Config schema drift (1.1.31 → 1.18.5) | ✅ unchanged, see above |
+| Provider credentials | ✅ free tier, zero credentials |
+
+Full lifecycle exercised through the REST surface:
+
+1. `POST /workers?profile=opencode-free` → `201`, routed by `kind:` through `CompositePeerLauncher`
+   to `OpenCodeLauncher` (`spawning opencode profile=opencode-free`), pane `wD:p3`.
+2. Readiness: `{"ready":true,"status":"idle"}`, roster state `ready`.
+3. `POST /sessions/{id}/message` → **`{"replySource":"reply","reply":"391"}`** — a *structured*
+   `fleet_reply`, not the CB-115 completion-fallback transcript scrape. The clean path.
+4. `DELETE /workers/wD:p3` → `204`, roster empty, tolerant teardown (`tab_not_found` ignored —
+   opencode had already closed its own tab).
+
+**Unplanned cross-validation with CB-501.** The audit trail recorded the worker's reply as
+`role: WORKER, actor: worker:term_657c1dad2b9731e, action: REPLY, outcome: allowed`. Connection-based
+identity (loopback peer PID → herdr pane) classified an **opencode** process as a worker with no
+opencode-specific handling — confirming the identity model is peer-kind-agnostic, which is exactly
+what CB-308 needs when it stretches the roster across hosts.
+
+CB-502 counters for the same run: `fleet_sends_total{outcome="replied"} 1`,
+`fleet_replies_total{path="rendezvous"} 1`, `fleet_inbox_depth{...} 0`.

docs/CB-500-Multi-Tier-Coordination.md

@@ -0,0 +1,482 @@
+# CB-500 — Multi-Tier Coordination (Stage 6)
+
+**Status:** design note. Developments A/B remain proposals; Development C (§6 and Figures 7–8) is
+**SUPERSEDED** by the advisory-architect design in Gitea issue #16 and the `architects:` configuration
+block (CB-548).
+**Depends on:** CB-401/402 (Peer Launcher SPI + composite router — placement-neutral spawn),
+CB-308 (per-agent broker channels + global id + federated roster — the addressing substrate),
+CB-307 (durable inbox + push loop), CB-301/303 (session FSM + context-cap/idle-ttl), CB-304
+(`rosterView`).
+**Relates to:** the bus-identity boundary — see §7. This note stays a **proposal**; no code until the
+staging in §6 is reviewed and the arc is split into tickets.
+
+## 1. Goal
+
+Grow `claude-bridge` from a **single-tier** coordinator (one human-driven primary → a flat pool of
+workers) into a **multi-tier** one, along three axes the lead has asked for:
+
+1. **Sandboxed workers** — each worker runs in a **separated, peer-owned sandbox** carrying its own
+   toolchain (Claude routed via `ANTHROPIC_BASE_URL`, a headless IDE, git, MCP, dev-tools), with
+   **per-role** sandboxes (a backend-agent image, a frontend-agent image).
+2. **Main-agent pairs** — **SUPERSEDED.** The considered model made the "main" tier a pair
+   (on-subscription Opus + one cloud module). The actual fleet is one human-driven lead plus two
+   short-lived advisory architects on different model families.
+3. **An orchestrator tier** — a supervisor **above** the mains that owns their **session identity**
+   (naming, resume) and **curates context**, so every main→worker delegation carries the *exact*
+   slice of context it needs and nothing else.
+
+The through-line: **this is not a new pillar.** It is the existing `PeerLauncher` and
+`SessionManager` patterns extended one tier up, riding the **same CB-308 substrate** that multi-host
+already needs. Sandbox = a placement-neutral spawn target (CB-402 pattern). Pair + orchestrator =
+per-agent channels + a recursive session manager (CB-308 pattern). The bus stays a
+**provider-neutral communication fabric**; every addition is addressing, launch, or session scoping —
+never toolchain ownership (§7).
+
+## 2. Single-tier today (the assumptions to break)
+
+```mermaid
+flowchart TB
+    human["human (types)"]
+    primary["PRIMARY (Opus)<br/>MCP client — pull-only"]
+    daemon["fleetd daemon<br/>127.0.0.1:8765 (single host)"]
+    comp["CompositePeerLauncher<br/>routes by kind"]
+    cc["ClaudeCodeLauncher"]
+    oc["OpenCodeLauncher"]
+    w1["worker pane (gx00 vLLM)"]
+    w2["worker pane (ollama)"]
+    human --> primary
+    primary -->|"fleet_send / spawn / ask"| daemon
+    daemon --> comp
+    comp --> cc
+    comp --> oc
+    cc --> w1
+    oc --> w2
+```
+
+*Figure 1 — one human-driven primary, one daemon, a flat pool of bare herdr-pane workers.*
+
+Four concrete bake-ins assume a single tier:
+
+| Assumption | Where (verified) | Why it blocks the direction |
+|---|---|---|
+| **Exactly one primary** | `mcp/PrimaryRegistry` — an `AtomicReference<String>`, "single-slot registry for the primary's terminal" | A *pair* needs N addressable mains, each with its own pull inbox. |
+| **Workers are bare panes** | `worker/*Launcher` spawn a herdr pane via `argv:["ccs", …]` into a pre-existing env | A *sandbox* is a richer launch target (container/devcontainer) — a new placement, not a new provider. |
+| **`SpawnRequest` is flat** | `peer/SpawnRequest(profileName, requestedCwd, callerCwd)` | A sandbox/role selection needs a spawn-target dimension the record does not carry. |
+| **No tier above the primary** | there is no manager of the *primary's own* session — `SessionManager` manages *workers* only | An orchestrator that names/resumes/scopes the mains is a wholly new (but pattern-reusable) tier. |
+
+## 3. Target multi-tier architecture
+
+> **SUPERSEDED fleet sketch.** Figure 2 records the former two-main model. The actual fleet is one
+> lead, two independent advisory architects, and N workers; architects are sideways peers, not leads
+> and not a tier above the lead. See Gitea issue #16 and the `architects:` block.
+
+```mermaid
+flowchart TB
+    human["human"]
+    subgraph orch["TIER 0 — orchestrator"]
+        osm["OrchestratorSessionManager<br/>(SessionManager, recursed up)<br/>names · resumes · scopes context"]
+    end
+    subgraph mains["TIER 1 — main pair"]
+        m1["main A: Opus<br/>MCP client"]
+        m2["main B: cloud module<br/>MCP client"]
+    end
+    subgraph bus["fleetd fabric (CB-307/308 substrate)"]
+        chan["per-agent inbox channels<br/>agent.&lt;globalId&gt;.inbox"]
+        roster["federated roster (union view)"]
+    end
+    subgraph workers["TIER 2 — sandboxed workers"]
+        sbBE["backend sandbox<br/>Claude via ANTHROPIC_BASE_URL<br/>+ headless IDE · git · MCP · dev-tools"]
+        sbFE["frontend sandbox<br/>(role-specific image)"]
+    end
+    human --> osm
+    osm -->|"spawn / name / resume"| m1
+    osm -->|"spawn / name / resume"| m2
+    m1 <-->|"pull inbox"| chan
+    m2 <-->|"pull inbox"| chan
+    m1 -->|"scoped delegation"| bus
+    m2 -->|"scoped delegation"| bus
+    bus --> sbBE
+    bus --> sbFE
+    chan --- roster
+```
+
+*Figure 2 — **SUPERSEDED historical fleet sketch.** It proposed a collaborating pair of managed mains.
+The actual fleet keeps one human-driven lead and uses two independent, short-lived advisory architects
+on different model families, so agreement is evidence rather than correlated echo.*
+
+The recursion is the key idea: **`orchestrator : mains :: main : workers`** — the same
+spawn/name/resume/scope verbs at two levels.
+
+## 4. Development A — Sandboxed, role-specific workers
+
+A "sandbox" is a **placement**, not a provider — so it slots into the CB-401 SPI exactly the way
+CB-402's opencode adapter slotted in as a new *provider*. CB-402 proved the SPI is
+provider-neutral; a `SandboxLauncher` proves it is **placement-neutral**.
+
+```mermaid
+flowchart TB
+    req["SpawnRequest<br/>(profileName, cwd, + sandbox/role)"]
+    comp["CompositePeerLauncher<br/>routes by kind"]
+    cc["ClaudeCodeLauncher<br/>kind: claude-code"]
+    oc["OpenCodeLauncher<br/>kind: opencode"]
+    sb["SandboxLauncher (NEW)<br/>kind: sandbox"]
+    subgraph owned["bridge OWNS (launch + inject boundary)"]
+        launch["run sandbox entrypoint<br/>(docker/devcontainer up → agent)"]
+        inject["inject + guard baseUrl,<br/>mount bridge MCP + charter"]
+    end
+    subgraph peer["peer OWNS (inside the sandbox)"]
+        img["image = backend|frontend role<br/>headless IDE · git · dev-tools · MCP"]
+    end
+    req --> comp
+    comp --> cc
+    comp --> oc
+    comp --> sb
+    sb --> launch --> inject
+    inject -.->|"launches into, never builds"| img
+    classDef line fill:#b7791f,stroke:#7b341e,color:#ffffff;
+    class inject line
+```
+
+*Figure 3 — the ownership line (amber). The bridge runs the sandbox entrypoint and injects the same
+boundary it owns today (guarded `baseUrl`, mounted MCP + reply charter). Everything inside the image
+— the IDE, git, dev-tools — is the peer's. The bridge references the image/role; it never provisions
+tools. This is what keeps "give the worker a headless IDE" on the right side of the "bus, not
+env-manager" rule (§7).*
+
+```mermaid
+sequenceDiagram
+    participant M as main (delegator)
+    participant D as fleetd
+    participant SL as SandboxLauncher
+    participant SB as sandbox (peer-owned)
+    participant A as agent in sandbox
+    M->>D: fleet_spawn(profile=backend, role=backend)
+    D->>SL: spawn(SpawnRequest)
+    SL->>SB: start entrypoint (image = backend role)
+    Note over SL,SB: bridge injects guarded ANTHROPIC_BASE_URL,<br/>mounts bridge MCP url + reply charter
+    SB->>A: launch Claude (headless IDE, git, MCP ready — peer's own)
+    A-->>SL: MCP connects → readiness gate (CB-306) passes
+    SL-->>D: PeerHandle(globalId)
+    D-->>M: spawned, injectable
+```
+
+*Figure 4 — spawn into a peer-owned sandbox. Identical control flow to today's pane spawn (incl. the
+CB-306 readiness gate); only the launcher's `buildLaunch` differs — exactly the CB-402 seam.*
+
+**Deltas:** a new `kind: sandbox` adapter (extends the same `HerdrPeerLauncher`/`PeerLauncher` base);
+a spawn-target/role dimension on `SpawnRequest` and the `Worker` profile; optionally a `SANDBOX`
+`Capability`. Per-role = two profiles → two images; `CompositePeerLauncher` already routes them. If a
+sandbox is a *separate host/container*, it reuses CB-308's global id + per-host gateway wholesale —
+**the distributed case is resolved in §11: a sandbox on another host is one spawned by that host's
+gateway, because herdr keystroke-injection needs a locally-owned PTY.**
+
+## 5. Development B — Main-agent pairs
+
+> **SUPERSEDED — do not implement this model.** The two-main fleet was replaced by one human-driven
+> lead and two independent advisory architects. They are deliberately different model families (Claude
+> Sonnet 5 and GPT-5.6 through opencode), receive the same brief, and work independently so agreement
+> is evidence rather than correlated echo. See Gitea issue #16 and `architects:`.
+
+Both mains are MCP **clients**, so **neither can be called into** — each needs a **pull-based
+per-agent inbox**, which is precisely CB-308 item #1 (per-agent AMQP channels). The primary machinery
+that is singular today (single-slot `PrimaryRegistry`, a push-loop aimed at one terminal, "these
+tools only the primary calls") generalizes from a singleton to a **set**.
+
+```mermaid
+flowchart TB
+    subgraph pair["TIER 1 — collaborating pair"]
+        m1["main A: Opus<br/>MCP client (pull-only)"]
+        m2["main B: cloud module<br/>MCP client (pull-only)"]
+    end
+    reg["PrimaryRegistry → multi-slot<br/>(terminal per main)"]
+    subgraph fabric["fleetd"]
+        ca["agent.A.inbox"]
+        cb["agent.B.inbox"]
+        push["ReplyPushLoop → N terminals"]
+    end
+    m1 <-->|"peer-to-peer message"| m2
+    m1 -->|"register terminal"| reg
+    m2 -->|"register terminal"| reg
+    ca -->|"pull / nudge"| m1
+    cb -->|"pull / nudge"| m2
+    reg --> push
+    push --> ca
+    push --> cb
+```
+
+*Figure 5 — the pair. Each main owns an addressable inbox; `PrimaryRegistry` becomes multi-slot; the
+push loop nudges each main's terminal. Mains message each other as equals over the same bus (the
+transport is already peer-neutral — what was missing is N pull endpoints).*
+
+```mermaid
+sequenceDiagram
+    participant MA as main A (Opus)
+    participant BR as fleetd / broker
+    participant MB as main B (cloud)
+    MA->>BR: fleet_send(to = main B, msg)
+    BR->>BR: publish agent.B.inbox (durable, msg id)
+    Note over BR: held until B pulls (B is a client too)
+    MB->>BR: blocking fleet_send / poll resolves
+    BR-->>MB: msg (then ACK)
+    MB->>BR: fleet_reply(to = main A)
+    BR->>BR: publish agent.A.inbox
+    MA->>BR: poll resolves
+    BR-->>MA: reply
+```
+
+*Figure 6 — main↔main is the CB-307 asymmetry applied on both ends: two clients, so both hops are
+pull. This is why Part B **depends on** the per-agent-channel substrate, not just a config flag.*
+
+**Deltas:** `PrimaryRegistry` single-slot → keyed-by-main; per-main inbox routing (CB-308 #1);
+push-loop fan-out; relax "orchestration tools only the primary calls" to "any registered main."
+
+## 6. Development C — Orchestrator tier
+
+> **SUPERSEDED — do not implement this model.** The operator rejected a supervisor above the lead.
+> The human continues to drive the pre-existing lead directly; fleetd neither spawns nor resumes that
+> lead. What replaced this proposal is **one lead, two short-lived advisory architects, and N workers**:
+> the lead engages architects sideways for a strong-model assessment, then discards them. Architect
+> slots are declared in `architects:` (see Gitea issue #16), rather than making leads managed sessions.
+> The two architects deliberately use different model families — Claude Sonnet 5 and GPT-5.6 through
+> opencode — and receive the same brief independently. Agreement is evidence, not correlated echo
+> from one provider or one conversation.
+
+> **Historical alternative retained.** The text and figures below record the considered model and why it
+> was rejected: it re-rooted the human-facing session above the lead, violating the still-true premise
+> that configured leaders pre-exist, are recognised, and cannot be resumed by fleetd.
+
+The orchestrator is **`SessionManager` recursed one tier up**: today it spawns/names/reaps *worker*
+sessions; the orchestrator does the same for *main* sessions, and adds **context scoping**.
+
+```mermaid
+flowchart TB
+    human["human"]
+    subgraph t0["TIER 0 — orchestrator (new top MCP client)"]
+        osm["OrchestratorSessionManager<br/>= SessionManager pattern"]
+        idm["session identity<br/>name · resume · idle-ttl (CB-303)"]
+        ctx["context scoper<br/>(CB-303 context-cap + turn_id)"]
+    end
+    subgraph t1["TIER 1 — mains (now MANAGED sessions)"]
+        m1["main A"]
+        m2["main B"]
+    end
+    subgraph t2["TIER 2 — workers"]
+        w["sandboxed workers"]
+    end
+    human --> osm
+    osm --> idm
+    osm --> ctx
+    idm -->|"spawn / name / resume"| m1
+    idm -->|"spawn / name / resume"| m2
+    ctx -->|"inject exact context slice"| m1
+    m1 -->|"scoped delegation"| w
+    m2 -->|"scoped delegation"| w
+```
+
+*Figure 7 — **SUPERSEDED historical alternative.** The recursion re-rooted the human-facing session:
+the human drove an orchestrator and the mains became managed, resumable sessions. The operator rejected
+that re-root. The replacement keeps the human-driven, pre-existing lead and engages architects sideways
+as short-lived advisory peers; see Gitea issue #16 and `architects:`.*
+
+```mermaid
+sequenceDiagram
+    participant H as human
+    participant O as orchestrator
+    participant MA as main A
+    participant W as worker
+    H->>O: high-level goal (large context)
+    O->>O: name/resume main A session
+    O->>MA: task + SCOPED context slice (not the whole history)
+    MA->>W: fleet_send(delegation, carrying only the relevant slice)
+    W-->>MA: result
+    MA-->>O: rollup
+    O->>O: fold into orchestrator context, pick next main/turn
+```
+
+*Figure 8 — **SUPERSEDED historical alternative.** This proposed an orchestrator holding global context
+and slicing it for managed mains. The replacement has the human-driven lead send the same advisory brief
+issue #16 and `architects:`.*
+
+**Deltas:** a second, higher `SessionManager` instance whose "peers" are mains; the orchestrator
+becomes the top MCP client; context-slice selection (new) layered on CB-303's `context_cap` +
+`turn_id` scoping; mains gain a resumable session id in the federated roster.
+
+## 7. The identity boundary — the one clause to hold
+
+The bus is a **communication fabric, not an env/toolchain manager**. This direction is compatible
+**only** with the ownership split below; the amber line in Figure 3 is where it must hold.
+
+```mermaid
+flowchart LR
+    subgraph ok["STAYS A BUS (owned)"]
+        a["launch INTO a sandbox<br/>(opaque image/role reference)"]
+        b["inject + guard baseUrl,<br/>mount MCP + charter"]
+        c["session identity + context scope<br/>(name/resume/turn_id)"]
+        d["per-agent addressing + roster"]
+    end
+    subgraph drift["BECOMES ENV-MANAGER (forbidden)"]
+        e["build images / install IDE<br/>or dev-tools"]
+        f["wire the bridge's OWN IDE MCP<br/>into a worker"]
+        g["enumerate 'what a frontend<br/>agent needs'"]
+    end
+    ok -.->|"red flag: any feature that only<br/>makes sense for ONE kind of peer"| drift
+    classDef bad fill:#9b2c2c,stroke:#742a2a,color:#ffffff;
+    class e,f,g bad
+```
+
+*Figure 9 — the guardrail. A worker having a headless IDE **inside its own sandbox** is the peer
+owning its toolchain (left) — the opposite of the bridge reaching into the peer (right). Sandbox
+specs are peer-owned references (like `argv`/image id); the instant the bridge builds or installs
+them, it has drifted. This resolves the apparent contradiction between "do NOT give workers IDE MCP
+access" and "give workers a sandboxed IDE" — different owners.*
+
+## 8. Staging & dependencies
+
+```mermaid
+flowchart LR
+    cb402["CB-401/402<br/>Peer Launcher SPI + composite<br/>(DONE / in-flight)"]
+    A["A · SandboxLauncher<br/>(placement-neutral, independent)"]
+    cb308["CB-308 substrate<br/>per-agent channels + global id<br/>+ federated roster"]
+    B["B · main-agent pair (SUPERSEDED)<br/>(multi-slot PrimaryRegistry)"]
+    C["C · orchestrator tier<br/>(SessionManager recursed up)"]
+    cb402 --> A
+    cb402 --> cb308
+    cb308 --> B
+    cb308 --> C
+    B --> C
+    A -.->|"if sandbox = separate host/container,<br/>reuses CB-308 global id"| cb308
+    classDef gate fill:#b7791f,stroke:#7b341e,color:#ffffff;
+    class cb308 gate
+```
+
+*Figure 10 — the substrate (amber) is the shared enabler for B and C. Recommended order:*
+
+1. **Finish CB-402** (merge the opencode adapter branch).
+2. **A · SandboxLauncher** — independent; a second proof of the SPI (placement-neutral). Ships anytime.
+3. **CB-308 substrate** — per-agent channels + global id + federated roster (the multi-host work,
+   promoted from host-to-host to tier-to-tier).
+4. **B · main-agent pair** — **SUPERSEDED** by lead + two advisory architects.
+5. **C · orchestrator tier** — the capstone; the recursive session manager + context scoping.
+
+## 9. Open questions (to resolve at ticket-split)
+
+- **Sandbox mechanism:** container (`docker exec`) vs devcontainer — how the role→image mapping is
+  expressed on the profile. *(Topology **resolved** in §11: distributed = gateway-per-host × local
+  sandboxes; the remaining choice is only the local launch mechanism, not the shape.)*
+- **Pair semantics:** **SUPERSEDED.** The two-main question is replaced by the architect role's
+  least-privilege boundary: advisory architects can send/reply/ask/read but cannot spawn/stop/drain.
+- **Orchestrator drivenness:** the mains become programmatically spawned/resumed — does the human
+  still ever type directly into a main, or only into the orchestrator? (The re-root caveat, Fig 7.)
+- **Context-slice selection:** who decides the slice — orchestrator heuristics, explicit tool args,
+  or the main pulling on demand? This is the genuinely new responsibility; keep it *scoping*, not
+  content authorship, to stay inside the boundary.
+- **Trust:** every new tier boundary that accepts spawn/send is a trust edge (the CB-308 item #5 /
+  CB-401 Stage-C concern) — orchestrator→main and main→sandbox both need authz.
+
+## 10. Ticket-split guidance (deferred)
+
+This note is deliberately one arc; when split, the natural tickets are **A** (SandboxLauncher +
+role/spawn-target), **the CB-308 substrate** (likely already its own ticket), **B** (multi-primary
+pair), and **C** (orchestrator tier + context scoping) — with the identity clause (§7) as an
+acceptance criterion on **A** specifically. Sequence per §8; nothing here is a new pillar, so each
+ticket is an extension of an existing pattern (CB-402 for A, CB-308 for B/C).
+
+## 11. Distributed sandboxes — the resolved topology
+
+The follow-up question — *"clarify the architecture when we have distributed agents in sandboxes"* —
+resolves the fork left open in §4 and §9. **Decision: Development A (sandbox launcher) and CB-308
+(per-host federation) *compose*, not compete — each host runs a `fleetd` gateway whose launcher
+spawns agents into that host's *local* sandboxes.** A sandbox is never reached across the network; it
+is reached by the gateway sitting next to it.
+
+### 11.1 The one fact that fixes the shape
+
+The bus delivers a turn by **herdr keystroke-injection** — `Injector → AgentControl.send` writes into
+a PTY that its **local** herdr owns. The broker moves *messages and presence*, **never keystrokes**.
+So an agent's PTY must live in a herdr that *some* `fleetd` instance drives locally: a remote
+container with no local herdr **cannot be injected into**. That rules out a central daemon reaching
+remote PTYs, and collapses the design to a single identity:
+
+> **"a sandboxed agent on another host" ≡ "a sandbox spawned by that host's gateway."**
+
+```mermaid
+flowchart TB
+    subgraph hostA["HOST A — gateway"]
+        mA["main / orchestrator<br/>MCP client → LOCAL gateway"]
+        gA["fleetd A<br/>herdr + CompositePeerLauncher<br/>(incl. SandboxLauncher)"]
+        cBEa["sandbox: backend<br/>(local container)"]
+        cFEa["sandbox: frontend<br/>(local container)"]
+        mA --- gA
+        gA -->|"spawn (docker/devcontainer)<br/>→ PTY in A's herdr"| cBEa
+        gA --> cFEa
+    end
+    subgraph broker["BROKER (AMQP) — CB-307/308 fabric"]
+        inbox["agent.ID.inbox queues"]
+        roster["roster.* (federated presence)"]
+    end
+    subgraph hostB["HOST B — gateway"]
+        gB["fleetd B<br/>herdr + SandboxLauncher"]
+        cBEb["sandbox: backend<br/>(local container)"]
+        gB -->|"spawn → PTY in B's herdr"| cBEb
+    end
+    gA <-->|"messages + presence<br/>(NOT keystrokes)"| inbox
+    gB <-->|"messages + presence"| inbox
+    gA --- roster
+    gB --- roster
+    classDef line fill:#2b6cb0,stroke:#1a365d,color:#ffffff;
+    class inbox,roster line
+```
+
+*Figure 11 — the composed topology. Each gateway owns its local herdr and runs a `SandboxLauncher`
+(the §4 adapter) that spawns role-specific containers **on its own host**; the broker (blue) carries
+only messages + roster between gateways. Keystroke-injection stays strictly local to each gateway.*
+
+### 11.2 How a delegation reaches a sandboxed agent on another host
+
+```mermaid
+sequenceDiagram
+    participant MA as main (host A)
+    participant GA as gateway A
+    participant BR as broker
+    participant GB as gateway B
+    participant SB as sandbox agent (host B, container)
+    MA->>GA: fleet_send(globalId on B, msg)
+    GA->>GA: directory lookup - is globalId local? NO
+    GA->>BR: publish agent.ID.inbox (durable)
+    BR->>GB: route to the owning gateway
+    GB->>SB: inject via B's LOCAL herdr (keystrokes)
+    Note over GB,SB: SandboxLauncher already spawned the container -<br/>its PTY is in B's herdr, CB-306 readiness passed
+    SB-->>GB: fleet_reply (to B's LOCAL MCP endpoint)
+    GB->>BR: publish primary-bound (durable, msg id)
+    BR->>GA: route back to A
+    Note over GA: held until the main pulls (the main is a client)
+    MA->>GA: poll / blocking send resolves
+    GA-->>MA: reply
+```
+
+*Figure 12 — the `local ? inject : publish` fork (CB-308 §3.2) with a sandboxed far side. Only the
+**middle** hop crosses the network via the broker; **both** injection points (into the sandbox on B,
+and the drain-nudge back into the main on A) are local herdr writes. This is CB-308's routing rule
+unchanged — the sandbox is transparent to it.*
+
+### 11.3 Two reachability changes any sandbox forces
+
+| Change | Today | Under sandboxes |
+|---|---|---|
+| **`mcpUrl`** | `http://127.0.0.1:8765/mcp` (loopback) | must be **host-routable from inside the container** (e.g. `host.docker.internal` or the gateway's LAN IP) — the worker connects to **its own gateway's** MCP, never a remote one. |
+| **PTY ownership** | pane in the daemon's herdr | pane is the **container's** attached PTY, in the **local** gateway's herdr (via `docker exec`/devcontainer) — non-negotiable per §11.1. |
+
+### 11.4 Everything maps to an existing seam (nothing new invented)
+
+| Concern | Provided by |
+|---|---|
+| Per-host gateway (owns local herdr + sessions) | **CB-308** (today's `fleetd`, evolved) |
+| Spawn into a local sandbox / role→image | **Development A** `SandboxLauncher` (§4), routed by `CompositePeerLauncher` |
+| Addressing a remote sandboxed agent | **CB-308** global id + federated roster (host + role as metadata) |
+| Orphan reap after a gateway restart | **CB-117** per-gateway, summed by the composite — each reaps only its **local** herdr |
+| Container up/down | tied to **CB-303** session lifecycle — `SandboxLauncher.stop` tears the container down with the pane |
+| Cross-gateway spawn/send trust | **CB-308 item #5** / CB-401 Stage-C — each gateway edge is a trust boundary |
+
+*The net: distributed sandboxes add **zero** new pillars — they are `CB-308 gateway × Development-A
+launcher` at every host, with the §7 ownership line (peer owns the image; the bridge only launches
+into it) holding at each gateway.*

docs/CB-591-Gateway-Migration.md

@@ -0,0 +1,467 @@
+# CB-591 — move the fleet onto the LLM and MCP gateway
+
+**Status: DONE — the fleet is on the gateway as of 2026-08-15.** `local` runs on `/anthropic` and
+`gx` on `/v1`, both at `weight: 100`; `local-direct` stays at `weight: 0` as the escape hatch. Getting
+here took a revert and two upstream fixes — see §7.1, which is the useful part of this document. One
+risk is **accepted rather than solved**: a stream cut by any mid-response timer arrives as HTTP 200
+with no terminator, and our third-party members cannot detect it (§7.2).
+· **Upstream:** [systems/vms wiki → LLM and MCP Gateway](https://git.ltms.dev/systems/vms/wiki/LLM-and-MCP-Gateway)
+· **Upstream issue:** [systems/vms#31](https://git.ltms.dev/systems/vms/issues/31)
+
+The gateway went live on 2026-08-15 and replaced Bifrost. This plan says what that means for a
+**member definition** in `fleetd.yaml`, because that is the part of this repo the change actually
+touches.
+
+---
+
+## 1. What changed upstream
+
+One front door for every LLM and MCP client: `https://llm.ltms.dev`, one token per consumer.
+
+| Surface | URL |
+|---|---|
+| OpenAI chat | `https://llm.ltms.dev/v1/chat/completions` |
+| OpenAI models | `https://llm.ltms.dev/v1/models` |
+| **Anthropic messages** | `https://llm.ltms.dev/anthropic/v1/messages` |
+| MCP, all servers multiplexed | `https://llm.ltms.dev/mcp` |
+
+Anything outside that list returns **404 before any token is checked**, on purpose — the gateway must
+never become a blanket proxy.
+
+The model backend is unchanged: GX10 vLLM at `10.10.10.26:8000` (`gx00.gw`), model name exactly
+`deepseek-v4-flash`. The direct LAN path stays open on purpose as an escape hatch.
+
+---
+
+## 2. Where claude-bridge sits today
+
+We do **not** use the gateway. The `local` profile talks straight to the vLLM:
+
+```yaml
+local:
+  kind: claude-code
+  baseUrl: http://gx00.gw:8000     # direct vLLM — no auth, LAN only
+  model: deepseek-v4-flash
+  configDir: /Users/dai.ha/.ccs/instances/gx10
+```
+
+Three facts about our side that decide the shape of this work:
+
+1. **`baseUrl` becomes `ANTHROPIC_BASE_URL`** in the member's environment, and `tokenEnv` becomes
+   `ANTHROPIC_AUTH_TOKEN` (the value is read from a host env var and never stored in config).
+   `local` sets no `tokenEnv` today, because a direct vLLM needs no token.
+2. **`SubscriptionGuard` refuses any host not on an allowlist**, and that allowlist is
+   `guard.offSubscriptionHosts: [gx00.gw]`. It is built once in `Fleetd.java:93` and handed to the
+   launcher, so **it is a restart-required key**, not a hot one. Changing `baseUrl` without changing
+   this makes every `local` spawn throw.
+3. **The wiki names us as a blocker.** Under *Not done yet*: retiring the shared `legacy` token is
+   blocked because "kb, brain, **claude-bridge** and the workstation still share it. Each needs its
+   own consumer first."
+
+Context7 is mounted twice today, both times straight at `https://ct7.ltms.dev/mcp` — once in
+`.mcp.json` (the primary) and once in `opencode.json` (the `sol` and `terra` members).
+
+```mermaid
+flowchart LR
+    subgraph now["Today"]
+        M1["local member<br/>claude-code"] -->|"ANTHROPIC_BASE_URL"| V1["vLLM gx00.gw:8000<br/>no auth, LAN only"]
+        M2["sol / terra<br/>opencode"] --> CT1["ct7.ltms.dev/mcp"]
+        P1["primary"] --> CT1
+    end
+    subgraph after["Proposed"]
+        M3["local member"] -->|"ANTHROPIC_BASE_URL<br/>+ ANTHROPIC_AUTH_TOKEN"| G["llm.ltms.dev/anthropic<br/>consumer: claude-bridge"]
+        G --> V2["vLLM gx00.gw:8000"]
+        M4["local-direct<br/>weight 0, escape hatch"] --> V2
+    end
+```
+
+*The member definition is the only thing that moves. The model behind it does not.*
+
+---
+
+## 3. The member definition change
+
+The gateway serves an Anthropic surface *and* an OpenAI surface, so **both member kinds can point at
+it**. That is the main opportunity here, and it is bigger than the `local` profile alone.
+
+### 3a. `local` — claude-code, on `/anthropic`
+
+| Key | Today | After | Note |
+|---|---|---|---|
+| `baseUrl` | `http://gx00.gw:8000` | `https://llm.ltms.dev/anthropic` | see the schema warning below |
+| `tokenEnv` | *(unset)* | `AI_GATEWAY_TOKEN` | new consumer token, `llmk-claude-bridge-<32 hex>` |
+| `model` | `deepseek-v4-flash` | unchanged | must stay **exact**; a regex match returns an empty `/v1/models` while completions keep working |
+| `guard.offSubscriptionHosts` | `[gx00.gw]` | `[gx00.gw, llm.ltms.dev]` | **restart required** |
+
+### 3b. A new opencode profile on `/v1` — no code needed
+
+`OpenCodeLauncher` already supports a pinned OpenAI-compatible endpoint (CB-508). Given `baseUrl` it
+writes a custom provider block into the worker's opencode config:
+
+- `baseUrl` → `options.baseURL`. `openAiBaseUrl` appends `/v1` to a bare host, and takes a URL that
+  already has a path **as-is** — so `https://llm.ltms.dev/v1` works unchanged.
+- `tokenEnv` → `options.apiKey` (falls back to a placeholder when unset, since a local vLLM ignores it).
+- `model:` **must** be `<provider>/<model>` when `baseUrl` is set — a bare name is rejected loudly
+  rather than silently falling back to opencode's default gateway.
+
+So the profile is pure config:
+
+```yaml
+gx:
+  kind: opencode
+  baseUrl: https://llm.ltms.dev/v1
+  tokenEnv: AI_GATEWAY_TOKEN
+  model: gx/deepseek-v4-flash        # provider id is ours to choose; the half after / is the model
+  argv: ["opencode"]
+  mcpUrl: http://127.0.0.1:8765/mcp
+  gitTokenEnv: WORKER_GITEA_TOKEN
+  weight: 100                        # same tier as `local` — free
+  maxLoad: 2
+  # deliberately NO credentialId — this is our own box, not the shared OpenAI account
+```
+
+**Why this matters more than it looks.** Today every opencode member is `sol` or `terra`, and those
+are two models on **one** OpenAI account sharing `credentialId: openai-shared` — so an exhaustion on
+either locks out both, and half the fleet's opencode capacity dies at once. A gateway-backed opencode
+profile is free, is not on that credential, and therefore is not in that quarantine pair. It removes
+a single point of failure rather than just adding capacity.
+
+**Note the asymmetry, it is deliberate:** `SubscriptionGuard` does not apply to opencode at all — the
+guard exists to stop a *Claude* worker borrowing the operator's subscription, and opencode reads its
+own provider credentials. So 3b needs **no allowlist change**; only 3a does.
+
+**Both still need a restart, for a different reason.** `tokenEnv` is resolved by
+`HerdrPeerLauncher.resolveEnv` → `env.apply(name)`, which reads the **daemon's own process
+environment**. The running `fleetd` inherited its environment when it started, so a variable added to
+`secrets.sh` afterwards is simply not there — the launcher would inject an empty token and the
+gateway would answer 401. This is the same failure as trap 1 in `scripts/redeploy-fleetd.sh`
+(`WORKER_GITEA_TOKEN`), and it has the same fix: **restart from a login shell**, and use
+`scripts/redeploy-fleetd.sh --check` to confirm the name resolves before restarting anything.
+
+### 3c. What this does to `ccs`
+
+Once a profile carries `baseUrl`, `tokenEnv` and `model` itself, the ccs instance stops being what
+routes a member. Be precise about what is left, though: `configDir` still supplies **folder trust**
+and `settings.json`, and dropping it is what produced the trust dialog and the wrong-model error
+recorded in `fleetd.yaml`. So ccs goes from *deciding where the tokens go* to *holding client-side
+state*. Less load-bearing, not removable.
+
+### Why `/anthropic` and never `/v1/chat/completions`
+
+The gateway declares its Anthropic backend as `schema.name: Anthropic`, which means **no
+translation** — streaming, tool use and thinking blocks pass through exactly as they do against vLLM
+directly.
+
+Declared as `OpenAI`, Envoy's translator looks for a `thinking_blocks` field that our vLLM does not
+send (it sends `reasoning_content`), and **every thinking delta disappears silently**. Claude Code
+speaks the Anthropic protocol, so `/anthropic` is both correct and the only safe choice.
+
+This is the exact failure shape this repo keeps hitting: it compiles, it answers, it looks healthy,
+and a capability is quietly off. Treat it as a `silent-default` risk, not a config preference.
+
+**Open question for 3b — ANSWERED, 2026-08-15.** The worry was that the OpenAI surface might drop
+reasoning the way the wiki documents for a mis-declared Anthropic backend. It does not. Checked at
+the API before any profile was switched:
+
+| surface | request | result |
+|---|---|---|
+| `/anthropic/v1/messages` | `deepseek-v4-flash`, 64 tokens | 200, response carries a real `"type":"thinking"` block |
+| `/v1/chat/completions` | same | 200, message carries a populated `reasoning_content` (and a `reasoning` field) |
+| `/v1/models` | — | 200, exactly `["deepseek-v4-flash"]` — the exact-name trap is clear |
+| `/v1/models`, **no token** | — | **401** — Caddy is gating, as designed |
+
+So reasoning survives on **both** surfaces, and the `/anthropic` choice for `local` is about protocol
+correctness rather than a repair for a known loss. The last row matters on its own: the wiki warns
+the gateway's own `SecurityPolicy` fails open, so it is worth knowing the proxy in front really does
+refuse an unauthenticated request here.
+
+---
+
+## 4. Decisions
+
+### D1 — switch, but keep the direct path as an explicit profile · **recommended**
+
+Switching buys four things we do not have:
+
+- **Free opencode capacity, off the shared credential.** The largest single win. See §3b — it retires
+  a real single point of failure, not just a cost line.
+- **Per-consumer usage figures.** The cockpit counts requests per consumer. That is the first real
+  measurement of what the fleet consumes, and it feeds [CB-589](https://git.ltms.dev/fleet/fleetd/issues/74) Gap 2 directly.
+- **Our own revocable token.** One consumer to revoke if a worker ever leaks it, instead of a shared
+  `legacy` token used by four systems.
+- **It works off-LAN.** `gx00.gw` resolves on the LAN only.
+
+The cost is honest and worth stating: we add a TLS edge, an auth proxy and a gateway to the path of
+every member spawn. The wiki keeps the direct route open precisely because "if the gateway breaks,
+nothing that matters is blocked."
+
+So keep it. Add a second profile `local-direct` pointing at `http://gx00.gw:8000` with **`weight: 0`**
+— never auto-selected, still spawnable with an explicit `fleet_spawn{profile: "local-direct"}`.
+That is exactly what CB-554 made `weight: 0` mean, and it turns the escape hatch into something the
+lead can actually reach during an incident.
+
+### D2 — do members also mount the gateway's `/mcp`? · **OPEN, operator's call**
+
+Not a detail. `CLAUDE.md` states in two places that a member mounts **only** the bridge MCP, and a
+worker's honesty rule leans on it ("never claim the result of a check you had no way to run").
+
+- **Keep bridge-only.** The invariant stays true and simple. Workers stay cheap and narrow.
+- **Add the gateway MCP.** Implementers get context7 documentation lookups, which is genuinely useful
+  for library work. But `mcpUrl` in `FleetConfig.Profile` is a **single `String`**, so a
+  claude-code member can mount exactly one MCP — this needs a code change, not a config edit.
+
+Note the invariant is **already inaccurate**: `opencode.json` gives `sol` and `terra` both context7
+and gitea. So the choice is really "make the rule true" or "make the rule match reality". Either is
+defensible; picking one is not mine to do.
+
+### D3 — token scope
+
+One consumer, `claude-bridge`, its token in `${SHARED_ENV}/tools/secrets.sh` as `AI_GATEWAY_TOKEN`,
+referenced by name only. Never the literal value in `fleetd.yaml` — `tokenEnv` exists for this.
+
+---
+
+## 5. Units of work
+
+```mermaid
+flowchart TB
+    U1["U1 · consumer token<br/>issue via cockpit, add to secrets.sh"]
+    U2["U2 · profile + guard<br/>fleetd.yaml, restart"]
+    U3["U3 · verify live<br/>spawn, prove thinking survives"]
+    U4["U4 · context7 via gateway<br/>.mcp.json + opencode.json"]
+    U5["U5 · docs<br/>CLAUDE.md, wiki 11-Features"]
+    U1 --> U2 --> U3
+    U4 --> U5
+    U3 --> U5
+```
+
+| # | Scope | Who | Why |
+|---|---|---|---|
+| U1 | Issue the `claude-bridge` consumer at `auth.ltms.dev`; store as `AI_GATEWAY_TOKEN` | **operator** | touches secrets and a host we do not own |
+| U2a | New `gx` opencode profile on `/v1` — pure config, no guard change | **lead** | `fleetd.yaml` is gitignored, so a worker cannot see or edit it |
+| U2b | `local` → `/anthropic`; add `local-direct` weight 0; add `llm.ltms.dev` to the guard allowlist | **lead** | same |
+| U2c | One restart from a **login shell**, after U2a and U2b | **lead** | picks up `AI_GATEWAY_TOKEN` into the daemon env *and* the guard allowlist, in one stop |
+| U3 | Live spawn on both new profiles; confirm reasoning survives on each surface | **lead** | needs real spawns and the running daemon |
+| U4 | Point `.mcp.json` and `opencode.json` context7 at the gateway `/mcp`; rename pinned tools | delegatable | tracked files, self-contained |
+| U5 | Fix the "members mount only the bridge" claim; add a `wiki/11-Features.md` entry | delegatable | writing, clear criteria |
+
+U1 blocks U2a, U2b and U3. U4 and U5 do not depend on it.
+
+**Write U2a and U2b, then restart once (U2c), then verify `gx` before `local`.** Since both profiles
+need the same restart there is no reason to do two, but there is still a reason to *verify* in order:
+`gx` exercises the token and the gateway with no guard involved, so if it fails the cause is upstream.
+`local` adds the guard allowlist on top, so a failure there points at our config instead. Testing them
+in that order separates the two causes instead of confusing them.
+
+> **U1 status, 2026-08-15:** the operator issued the consumer and exported it as `AI_GATEWAY_TOKEN`
+> (one key for every agent and MCP client behind `llm.ltms.dev`). Confirmed: it resolves in a login
+> shell, is 48 characters and carries the documented `llmk-` prefix. The value was never printed.
+
+---
+
+## 6. Traps carried over from the wiki
+
+Each of these cost someone real debugging time upstream. They apply to us.
+
+1. **Rotating a token restarts the auth proxy, which drops in-flight streaming responses.** For us
+   that means rotating `AI_GATEWAY_TOKEN` kills every live member mid-turn, and an async ticket's
+   report goes with it. This is the same rule as a daemon redeploy: **drain the fleet first**
+   (`fleet_list` → `fleet_poll` anything wanted → `fleet_stop`), then rotate.
+2. **The gateway's own `SecurityPolicy` fails open.** Standalone `aigw run` accepts it and silently
+   ignores it — an unauthenticated request returned **200**. Auth is the Caddy proxy in front, and
+   nothing else. Never reason as if the gateway authenticates.
+3. **Exact model name.** A regex match routes fine but returns an **empty** `/v1/models` list while
+   completions keep working. A wrong name returns a bare 404 that reads exactly like a dead gateway.
+4. **MCP tool names changed prefix separator.** Bifrost used one dash (`ct7-resolve-library-id`); the
+   gateway uses **two underscores** (`ct7__resolve-library-id`). Relevant only if U4 is done.
+5. **`/v1/models` 404 vs empty list are different faults.** 404 means no route loaded at all; empty
+   means the model match is a regex. Do not conflate them when diagnosing.
+
+---
+
+## 7. Verification — what would prove this works
+
+Merging config is not proving it. The checks, in order:
+
+1. `fleet_spawn{profile: "gx"}` succeeds and the member completes a real turn ending in
+   `fleet_reply`. This is the first proof of the token, the URL and the model name, and it risks
+   nothing the fleet depends on.
+2. `fleet_spawn{profile: "local"}` succeeds. If the guard allowlist was missed, this **throws** — a
+   loud, self-correcting failure, which is the good kind. If the restart was missed, it also throws,
+   for the same reason.
+3. A `local` member completes a turn. That exercises streaming through two TLS edges, the auth proxy
+   and the gateway.
+4. **Reasoning survives, checked separately on each surface.** For `local` on `/anthropic` this is
+   the check that catches the `/v1` versus `/anthropic` mistake, and it is the only one that does —
+   nothing else distinguishes a working passthrough from a translator quietly dropping thinking
+   deltas. For `gx` on `/v1`, this answers the open question in §3 rather than assuming it.
+5. The cockpit at `auth.ltms.dev` shows requests counted against the `claude-bridge` consumer, not
+   `legacy`. That is the whole point of taking our own token.
+6. `fleet_spawn{profile: "local-direct"}` still works, so the escape hatch is real rather than
+   theoretical.
+7. `fleet_list` shows `gx` carrying no `credentialId`, so a `sol`/`terra` exhaustion cannot
+   quarantine it. This is the single-point-of-failure claim in §3b, checked rather than asserted.
+
+---
+
+## 7.1 What the live run actually found — 2026-08-15
+
+U1–U2c were done, the daemon restarted onto them, and both new profiles were spawned for real. The
+migration was then **reverted**. This section is the result, so none of it has to be re-derived.
+
+### The blocker
+
+`llm.ltms.dev` answers **HTTP 413 Request Entity Too Large** above **32 KiB (32768 bytes)**, on both
+surfaces:
+
+```
+/v1        32695 bytes -> 200        /anthropic  32095 bytes -> 200
+/v1        32795 bytes -> 413        /anthropic  32855 bytes -> 413
+```
+
+32 KiB is far below one real agent turn.
+
+**Root cause — confirmed by the systems/vms side, 2026-08-15.** My guess that it was a Caddy
+`request_body max_size` was **wrong**. It is Envoy, inside `aigw` on `llm.vm`. Envoy Gateway defaults
+a listener's `per_connection_buffer_limit_bytes` to **32768**, and the AI Gateway buffers the *whole*
+request body before it can route on the model name — so that default is not a network tuning knob
+here, it is a hard ceiling on prompt size. Read out of the live Envoy `config_dump`:
+
+```
+listener default/llm/http    per_connection_buffer_limit_bytes: 32768
+```
+
+Nobody chose 32 KiB; it was inherited from the default. Both TLS edges are innocent: the same
+boundary reproduces on the LAN path and the internet path, and both 413s carry an `x-llm-consumer`
+header their auth proxy sets only *after* authenticating — so the body cleared both edges and the
+auth. Directly on `llm.vm`, `aigw` 413s at 39 KB while the vLLM backend accepts the same 39 KB and
+answers 200.
+
+**Do not plan around 32 KiB.** The intended ceiling is far higher. Their fix — a `ClientTrafficPolicy`
+setting `bufferLimit: 8Mi` — is written but **not deployed** as of this note, pending their operator's
+approval. I have not re-tested and will not until they confirm, so as not to measure a half-changed
+system. Fixed in **systems/vms**, not here.
+
+### The part worth remembering
+
+Two members were spawned at the same moment with the same message:
+
+| | `local` (claude-code, `/anthropic`) | `gx` (opencode, `/v1`) |
+|---|---|---|
+| READY → BUSY | 19:07:26 | 19:07:45 |
+| BUSY → DONE | **19:08:51 (66s)** | **never — 10+ min, ticket FAILED** |
+
+**`local` passed.** It passed only because the probe was three trivial questions in a fresh session,
+so the request fit under 32 KiB. The profile looked healthy and was a landmine set to fire on the
+first turn that reads a file.
+
+So §7's checklist was not wrong, it was **too easy**. Any future run of it must use a task that reads
+a real file. A liveness probe proves the token and the URL; it does not prove the path.
+
+`gx` did not fail loudly either. Reproduced outside the bridge by running `opencode` by hand with the
+launcher's own generated config:
+
+```
+Error: Request Entity Too Large
+...compacts context, retries...
+Error: Request Entity Too Large
+```
+
+opencode **catches the 413, compacts, and retries — indefinitely**. A member that fails loudly costs
+one turn; this one costs the whole task and is indistinguishable from a slow worker.
+
+> **Diagnosing a stuck opencode member.** Do not read its pane. The launcher writes its config to a
+> temp dir and passes it as `OPENCODE_CONFIG` — find it with
+> `ls -dt /var/folders/*/*/T/fleetd-opencode-* | head -1`, check the provider block and the key's
+> length and prefix (never its value), then reproduce with `opencode run --auto -m <provider>/<model>`
+> using the same `OPENCODE_CONFIG`. That is what turned "it hangs" into a one-line error.
+
+### What checked out, and needs no re-testing
+
+- Token accepted on both surfaces. **Unauthenticated → 401**, so the Caddy proxy really does gate —
+  the wiki's "SecurityPolicy fails open" warning is about the gateway itself, not the edge.
+- `/v1/models` returns exactly `["deepseek-v4-flash"]`, so trap 3 is clear.
+- **Reasoning survives both surfaces** — see §3b above.
+- The launcher's generated opencode provider block is correct, carrying a real 48-character `llmk-`
+  key rather than the `fleetd-local-noauth` placeholder.
+- `SubscriptionGuard` accepted `llm.ltms.dev` after the allowlist edit and the restart: `local`
+  spawned without throwing, which is the check that catches a missed restart.
+
+### Resolution — both ceilings fixed, migration completed
+
+systems/vms fixed both, and each was re-checked from this side rather than taken on trust:
+
+| ceiling | was | now | our own check |
+|---|---|---|---|
+| listener buffer | 32 KiB | 32 Mi | 1.2 MB body → **200** (was 413) |
+| LLM route timeout | 60s | 86400s | the request that truncated: **101s, `message_stop` present, 4000/4000** |
+
+The timeout moved in two steps on 2026-08-15: 60s → 1800s, then 1800s → **86400s (24 hours)** after
+the truncation risk below was discussed. They tried `request: 0s` first, which removes the
+total-duration timer completely. It works, but on an `AIGatewayRoute` the **idle timeout is derived
+from the request timeout**, so `0s` also removed any bound on a stalled connection. 86400s keeps a
+reaper for dead connections while putting the truncation timer out of practical reach.
+
+Neither was deliberate. The 32 KiB was Envoy Gateway's default `per_connection_buffer_limit_bytes`;
+the 60s was Envoy AI Gateway's own documented default. The 60s bounded **generation** as well as
+prompt size — a tiny prompt with a long answer returned 504 at 60.05s.
+
+Two configuration facts worth keeping, from their bisection:
+
+- **`ClientTrafficPolicy` is honoured in standalone `aigw run`; `BackendTrafficPolicy` is NOT.** A
+  `BackendTrafficPolicy` setting `requestTimeout` is accepted, logs nothing, and leaves the routes
+  unchanged (upstream `envoyproxy/gateway#9513`). What works is `timeouts: {request: …}` on each
+  `AIGatewayRoute` rule. Nothing from the outside distinguishes the two — the same silent-default
+  shape as their `SecurityPolicy` caveat.
+- In that stack, "the config was accepted" proves nothing. Read the live `config_dump`.
+
+## 7.2 The risk we accepted, and why we could not remove it
+
+Raising the timeout made the failure **rare, not impossible**, and the residual failure is silent.
+
+On a mid-response timeout over chunked HTTP/1.1, Envoy ends the chunked encoding *cleanly* instead of
+resetting the connection, so the client receives what looks like a complete transfer
+(`envoyproxy/envoy#17186` — acknowledged as a bug in 2021, closed by a stale bot, never fixed). The
+December 2025 fix `envoyproxy/envoy#42269` changes locally-originated resets from `NO_ERROR` to
+`INTERNAL_ERROR`, but it is **HTTP/2 only** and SSE clients here speak HTTP/1.1.
+
+Measured on our side while the timeout was still 60s:
+
+```
+HTTP 200   61.07s   141992 bytes
+  message_stop 0    message_delta 0    error events 0
+  emitted 2473 of 4000, ending on a WELL-FORMED SSE frame
+```
+
+A syntactically valid stream that simply stops. Any timer firing mid-stream — route timeout, idle
+timeout, `max_stream_duration` — fails this same way.
+
+**The recommended defence does not transfer to us.** The right fix is to treat a stream with no
+`message_stop` / `[DONE]` / `finish_reason` as failed. We cannot: our members are Claude Code and
+opencode, third-party clients whose SSE parsing we do not own, and there is no seam to insert the
+check. Whether either detects a missing terminator is unverified — and opencode's handling of the 413
+(swallow, compact, retry forever, never surface an error) does not suggest it is strict.
+
+So the honest statement of our position:
+
+> Gateway traffic is acceptable at 86400s because a single request would have to run for 24 hours to
+> trip the bug — **not** because we could detect it if it did.
+
+At 86400s our **own** limit binds first, which is the ordering we want. `MessageService.ASYNC_TIMEOUT_MS`
+caps a turn at 30 minutes, so a runaway request ends as a clean `FAILED` ticket that we raised, rather
+than as a silently truncated `200` that we cannot see. While the gateway sat at 1800s the two numbers
+were equal and did not nest, so a gateway-side stall could have been misread as a bug in our own ticket
+handling. That ambiguity is now gone.
+
+**If a member ever returns a confident but truncated answer, suspect this before anything in our own
+code.** That is the whole reason this section exists.
+
+---
+
+## 8. Related
+
+- [CB-589 / #74](https://git.ltms.dev/fleet/fleetd/issues/74) — cost-first placement and a
+  gateway that reports live capacity. The per-consumer figures this migration unlocks are the first
+  input that ticket actually needs.
+- `docs/CB-500-Multi-Tier-Coordination.md` §11 — the distributed-sandbox topology this gateway is
+  part of.

docs/CB-5xx-Hardening.md

@@ -0,0 +1,242 @@
+# CB-5xx — Stage 5 Hardening (auth · metrics · CI · supervision · authz+audit)
+
+**Status:** design note (pre-implementation) — the single-host close-out before cross-host work.
+**Covers:** CB-501 (bearer auth + TLS) · CB-502 (`/metrics`) · CB-503 (mock-socket CI) ·
+CB-504 (service supervision) · CB-505 (per-session authz + audit log).
+**Depends on:** everything shipped through CB-402. Nothing here changes messaging semantics.
+**Blocks:** CB-308. The cross-host trust model is CB-308's own gating concern, and it inherits
+whatever identity/authz shape lands here — so this stage is deliberately *before* federation,
+not after it.
+
+---
+
+## 1. Why this stage is not optional bookkeeping
+
+`fleetd` today has **exactly one security control: the loopback bind**. Every other guarantee
+rests on it.
+
+The identity model (`mcp/ConnectionIdentity.java`) resolves a caller from the connection alone —
+the OS reports the connecting PID, herdr owns the PID→pane map, so a worker cannot forge another
+worker. Its own javadoc is explicit: *"Single-host only (the herd shares the `fleetd` host); the
+token path is the split-host fallback."* The token path does not exist yet.
+
+That leaves a seam that is **latent today and load-bearing the moment the bind moves**:
+
+```java
+// ConnectionIdentity.resolve — non-loopback callers get a null terminal
+if (!isLoopback(remoteAddr)) return new Caller(null, -1);
+```
+
+…and `null` terminal is interpreted downstream as **"this caller is the primary"**. Combined:
+
+> Any caller that is not a recognised on-host worker pane is treated as the primary — including,
+> if `bind.host` is ever widened, an arbitrary remote client.
+
+Today `bind` defaults to `127.0.0.1` so this is unreachable. But CB-308 exists precisely to widen
+the boundary, and the primary is the *most* privileged role on the bus (it spawns, stops, sends to
+any session, and drains any inbox). Shipping federation on top of "unauthenticated ⇒ primary"
+would be building the security boundary backwards.
+
+**So CB-501 is not "add a token header". It is: make identity explicit, and make the absence of
+identity mean *nothing*, not *everything*.**
+
+---
+
+## 2. Decisions (locked)
+
+### D1 — Three caller roles, one resolution path
+
+Introduce `Role { PRIMARY, WORKER, ANONYMOUS }` resolved by a single `CallerResolver` that both
+REST and MCP go through. Resolution order:
+
+1. **Connection identity wins where it applies.** A loopback peer PID that maps to a herdr worker
+   pane ⇒ `WORKER` with that terminal. Unforgeable, unchanged from today, zero config.
+2. **Token, if presented.** A valid bearer token ⇒ the role that token is provisioned for.
+3. **Otherwise `ANONYMOUS`** — *not* `PRIMARY`.
+
+This inverts today's default. `PRIMARY` becomes something you must *prove* (by being a loopback
+non-worker process when auth is disabled, or by presenting a primary-scoped token when it is
+enabled), rather than something you get by failing every other check.
+
+### D2 — Auth is opt-in by config, but the *default* must stay zero-friction on loopback
+
+The daemon is dogfooded constantly on one machine. If enabling hardening breaks the local setup,
+it will be disabled and the stage is wasted. So:
+
+```yaml
+auth:
+  mode: loopback-trust   # default — behaves exactly like today: loopback ⇒ PRIMARY, no token needed
+  # mode: token          # every non-worker caller must present a valid bearer token
+  # tokenEnv: FLEETD_API_TOKEN   # host env var holding the token; never the literal value
+```
+
+`mode: loopback-trust` is the current behaviour, named honestly and now *chosen* rather than
+implied. `mode: token` is what a non-loopback bind requires. **A non-loopback `bind.host` with
+`mode: loopback-trust` must fail fast at startup** — that check is the single highest-value line
+in this stage, because it makes the dangerous configuration unrepresentable rather than merely
+discouraged.
+
+### D3 — TLS terminates *outside* the JVM
+
+Do **not** add TLS config to Javalin/Jetty. The deployment story for a cross-host gateway is a
+reverse proxy (or an SSH/WireGuard tunnel) in front of the daemon; the AMQP link has its own TLS
+via the broker URI (`amqps://`). Adding keystore handling here would mean certificate lifecycle
+code in a daemon whose whole value is being small, and would duplicate what the proxy does better.
+
+**CB-501 therefore ships bearer auth + the fail-fast bind check, and documents TLS as a
+deployment concern with a worked reverse-proxy example.** This is a deliberate narrowing of the
+roadmap's "auth/TLS" wording — flagged in §6 for the lead.
+
+### D4 — Metrics without a new dependency
+
+The roadmap's tech-stack table says Micrometer→Prometheus. Recommend **not** taking that dep:
+
+- This pom already carries an unusually heavy dependency-reconciliation burden (a hand-pinned
+  `jackson-annotations` 3.0-rc5 to reconcile the MCP SDK's Jackson 3 with our Jackson 2.19, a
+  Jetty BOM import to stop version skew, plus four documented accepted-CVE advisories). Every new
+  transitive tree is a real cost here, not a hypothetical one.
+- The CVE gate that CLAUDE.md mandates for dependency changes (`jetbrains get_file_problems` →
+  Mend.io) **cannot currently be run** — no JetBrains MCP server is connected. Adding a dependency
+  tree we cannot scan violates the project's own stated policy.
+- The metric set is small and fully known (§4). Prometheus text exposition is a trivial,
+  stable, well-specified format.
+
+So: a ~120-line `metrics/Metrics.java` holding `LongAdder` counters and gauge suppliers, rendered
+to the Prometheus text format at `GET /metrics`. If Micrometer is wanted later for its
+registry/push ecosystem, this stays a drop-in swap behind the same endpoint. **Flagged in §6 —
+this deviates from a documented tech-stack choice.**
+
+### D5 — Supervision targets launchd first, systemd second
+
+The roadmap says "systemd unit". **This host is macOS — there is no systemd on it** (`systemctl`
+not found), and the daemon that has been dogfooded for weeks runs as a bare foreground
+`java -jar`. Ship **both**:
+
+- `deploy/dev.ltms.fleet.plist` — launchd agent, the *actual* runtime here, with `KeepAlive` and
+  ordered start after herdr.
+- `deploy/fleetd.service` — systemd unit for the Linux gateways CB-308 introduces.
+
+Ordering after herdr is advisory in both: the herdr socket may not exist at boot, so the daemon
+must **retry the socket rather than exit** — supervision ordering is a nicety, socket-retry is the
+actual fix. That retry behaviour is part of CB-504, not a separate ticket.
+
+### D6 — Audit log is a separate append-only stream, not the app log
+
+Privileged actions (spawn, stop, send, reply-drain, ack) emit a structured JSON line to a
+dedicated `audit` SLF4J logger with its own appender, carrying `{ts, role, terminal, pid, action,
+target, outcome}`. Keeping it off the chatty app logger is what makes it greppable and, later,
+shippable. **No message *content* in the audit record** — the bridge carries the user's source
+code and prompts; an audit trail that quietly becomes a transcript archive is a liability, not a
+control. Content stays out; correlation ids go in.
+
+---
+
+## 3. Authorization model (CB-505)
+
+With D1's roles, the rules are small enough to state completely:
+
+| Action | REST | PRIMARY | WORKER | ANONYMOUS |
+|---|---|---|---|---|
+| spawn worker | `POST /workers` | ✅ | ❌ | ❌ |
+| stop worker | `DELETE /workers/{paneId}` | ✅ | ❌ | ❌ |
+| send to a session | `POST /sessions/{id}/message` | ✅ | ❌ | ❌ |
+| reply | `POST /sessions/{id}/reply` | ❌ | ✅ **own session only** | ❌ |
+| ask | `POST /sessions/{id}/ask` | ❌ | ✅ **own session only** | ❌ |
+| drain replies | `GET /sessions/{id}/replies` | ✅ | ❌ | ❌ |
+| status / list / profiles | `GET …` | ✅ | ✅ | ❌ |
+| health | `GET /healthz` | ✅ | ✅ | ✅ (unauthenticated by design) |
+| metrics | `GET /metrics` | ✅ | ✅ | ❌ |
+
+The load-bearing row is **"own session only"**: a worker may only reply or ask *as itself*. That is
+already true de facto — `ConnectionIdentity` derives the terminal rather than reading it from the
+body — so CB-505 mostly **asserts an existing invariant explicitly** and adds the test that pins
+it. The one real change is rejecting a worker that names a *different* session id in the path.
+
+`/healthz` stays open: it must answer for a load balancer or supervisor before any credential is
+configured. It already leaks nothing but herdr's version and up/down.
+
+### 3.1 There are TWO entry paths, and only one of them has identity today
+
+The wiki describes MCP as "a thin adapter over the REST core". **At the code level that is not
+literally true, and the difference is security-relevant.** `FleetMcp` calls `MessageService` /
+`SessionManager` *directly*; it never issues an HTTP request against a Javalin route. And `/mcp` is
+mounted as a raw servlet on Jetty's `ServletContextHandler`
+(`FleetApp.build → cfg.jetty.modifyServletContextHandler`), so it does **not** pass through
+Javalin's `before` filters at all.
+
+The current split is the mirror image of what you'd expect:
+
+| Path | Caller identity today | Authz today |
+|---|---|---|
+| MCP `/mcp` | ✅ resolved per call (`ConnectionIdentity` via the transport-context extractor) | ❌ none |
+| REST routes | ❌ **none at all** — the session id is taken from the URL path and trusted | ❌ none |
+
+So REST is the *more* exposed surface: `POST /sessions/{id}/reply` accepts any `{id}` from the
+path, whereas the MCP `fleet_reply` derives the worker from the connection and refuses to read it
+from an argument. Loopback-only bind is what makes this safe today.
+
+**Therefore CB-505 must enforce on both paths against one shared resolver** — not at a single
+choke point. Concretely: a Javalin `before` filter for REST, and the existing transport-context
+extractor for MCP, both delegating to `auth.CallerResolver`. Any authz check that lives in only
+one of the two is not a control.
+
+---
+
+## 4. Metric set (CB-502)
+
+Deliberately small; every one maps to a failure mode we have actually hit.
+
+| Metric | Type | Why it exists |
+|---|---|---|
+| `fleet_sends_total{outcome}` | counter | outcome ∈ replied\|completion_fallback\|timeout\|failed — the completion-fallback rate is the health signal for turn detection (CB-115/116/118) |
+| `fleet_send_duration_seconds` | histogram | delegated turn latency |
+| `fleet_replies_total{path}` | counter | path ∈ rendezvous\|inbox — how often a reply strands (CB-307's whole reason to exist) |
+| `fleet_inbox_depth{target}` | gauge | undrained replies; steady-state should be 0 |
+| `fleet_push_nudges_total{outcome}` | counter | outcome ∈ delivered\|exhausted — a rising `exhausted` means the primary is not draining |
+| `fleet_spawns_total{kind,outcome}` | counter | outcome ∈ ready\|timeout\|guard_rejected; per peer kind (CB-402) |
+| `fleet_sessions{state}` | gauge | SPAWNING/READY/BUSY/DONE census |
+| `fleet_herdr_calls_total{method,outcome}` | counter | socket health — the dependency everything rests on |
+| `fleet_auth_failures_total{reason}` | counter | only meaningful once CB-501 lands; catches misconfigured workers |
+
+---
+
+## 5. Increment plan
+
+Ordered so each step is independently mergeable and the risky one lands first.
+
+1. **CB-501a — `CallerResolver` + `Role`.** Pure refactor: route today's connection identity through
+   the new type, `ANONYMOUS` not yet reachable (loopback-trust default preserves behaviour).
+   Green build, no behaviour change.
+2. **CB-501b — token mode + fail-fast bind check.** Config block, bearer parsing, the
+   non-loopback-bind guard. This is the security-relevant commit; keep it small and reviewable.
+3. **CB-505 — authz table + audit logger.** Enforce §3 on **both** entry paths (see §3.1); add the
+   audit appender.
+4. **CB-502 — `Metrics` + `/metrics`.** Instrument the paths in §4.
+5. **CB-503 — CI.** Runs `mvn -B clean install` with `-Dgroups='!contract'` so the live-herdr and
+   RabbitMQ contract tests are excluded; the mock-UDS suite is the CI surface, exactly as the
+   roadmap's testability section intends.
+6. **CB-504 — launchd plist + systemd unit + herdr-socket retry.**
+
+---
+
+## 6. Open questions for the lead
+
+*All four resolved 2026-07-29 — the lead confirmed D3, D4, and the D6 sink; the CI runner question
+was answered from the forge itself. Kept here as the decision record.*
+
+1. ✅ **TLS scope (D3) — confirmed.** Bearer auth + the fail-fast bind guard ship in the daemon;
+   TLS terminates at a reverse proxy, documented with a worked example. AMQP gets TLS via an
+   `amqps://` URI. No keystore handling in `fleetd`.
+2. ✅ **Micrometer (D4) — confirmed dropped.** Zero-dependency Prometheus text renderer, for the
+   reasons in D4 (pom reconciliation burden + the mandated CVE gate being un-runnable this
+   session). Revisit if a push-gateway or JVM-metrics requirement appears; the endpoint is the
+   swap seam.
+3. ~~**CI runner (CB-503).**~~ ✅ **Resolved during design** — a Gitea Actions runner *is*
+   registered and healthy (`lms/alms-memory` has 28 completed runs; `lms/alms` runs on push and
+   pull_request). CB-503 targets `.gitea/workflows/ci.yml` with `runs-on: ubuntu-latest`, matching
+   the sibling repo's convention. Note the runner's image ships an older `default-jdk`, so the
+   workflow must provision **JDK 25** explicitly rather than apt-installing the default.
+   Contract-test exclusion needs no CI flag: the pom's `default-excludes` profile already sets
+   `excludedGroups=contract`, so a plain `mvn -B clean install` *is* the mock-socket surface.
+4. ✅ **Audit sink — confirmed dedicated file.** Its own logback appender writing JSON lines beside
+   the daemon, separate from the app log, per D6. Content still never enters the record.

docs/M4-Fleet-Health.md

@@ -0,0 +1,972 @@
+# M4 - Fleet health, recovery, routing, and capacity
+
+**Status:** Design accepted on 2026-08-15. CB-573 part 1 has shipped the classification model and
+the `fleet_list` capacity view; the remaining M4 units are not yet shipped. See
+[Unit 2 — what has landed so far](#unit-2---what-has-landed-so-far) before planning Unit 2 work:
+some of its criteria were met by separate CB tickets, and one of them contradicts the unit text.
+**Scope:** Fleet evidence, safe mechanical repair, lead routing, capacity reporting, and optional
+human notification.
+**Grounded in:** `health/FleetHealth`, `health/PaneBudget`, `inject/StatusPoller`,
+`inject/StatusRefiner`, `inject/CompletionResolver`, `inject/Injector`, `session/SessionManager`,
+`msg/MessageService`, `msg/ReplyInbox`, `msg/ReplyPushLoop`, `msg/LeadHeartbeatLoop`,
+`mcp/PrimaryRegistry`, and `herdr/AgentControl`.
+
+## 1. Problem and decision boundary
+
+The operator asked the bridge to detect idle agents, exceptions, stopped work, and broken
+communication. The bridge may read an agent pane from time to time. It must notify a person when
+the fleet cannot move forward.
+
+The four operator terms are not four equal health states. `IDLE` is a normal mode. An exception is
+sometimes visible only as pane text. Stopped work may look the same as slow work. Broken
+communication can occur on several links.
+
+M4 uses this boundary:
+
+- The bridge detects facts and joins evidence.
+- The bridge repairs only mechanical failures with no judgement.
+- The lead decides whether to stop, retry, replace, or reassign a member.
+- A human is notified only when no healthy lead can act.
+- n8n may route an outbound incident. It never classifies state or chooses recovery.
+
+An inbound n8n decider would need bridge authority. No narrow machine-decider role exists. Giving a
+workflow engine lead authority is unsafe, while adding a new role is a separate authorization
+design. An outbound sink needs no bridge role.
+
+The bridge must never replay a delivered task. That task may already have changed files, pushed a
+branch, opened a pull request, or changed external state. A replay can run those side effects twice.
+This rule must remain true even if later code stores delivered prompt text.
+
+## 2. Evidence model
+
+A health state is mainly a comparison between two views:
+
+- **herdr view:** current agents and raw live status from one `AgentControl.list()` call.
+- **bridge view:** session FSM, MCP presence, accepted turns, tasks, inbox state, and lead ownership.
+
+A strong fault often appears as a disagreement between those views. For example, `BUSY` in the
+session FSM and `DONE` in herdr means the bridge missed a turn boundary. Pane reads support this
+model, but they are not the main monitor.
+
+`SessionManager.rosterView` already joins session state and live status. `AgentControl.list()`
+already gets the whole live fleet in one call. M4 makes that join persistent and adds timers,
+accepted-turn state, and incident state.
+
+### 2.1 Real traces behind the design
+
+The first trace was an architect that stopped making progress:
+
+```text
+profile=opus role=architect state=busy liveStatus=done
+```
+
+The session moved from `DONE` to `BUSY` for turn 2. Eighteen minutes later, the session still said
+`BUSY`, herdr still said `DONE`, the async task still said `PENDING`, and no completion fallback had
+run. This is `TURN_BOUNDARY_LOST`, not a general slow-turn guess.
+
+The second trace had two async sends to the same pane, one second apart. The pane was then stopped.
+One ticket became failed. The other stayed `pending - worker unknown`. Current
+`MessageService.abandon` resolves only `Rendezvous.currentWaiter(target)`, while async tasks live in
+a separate ticket map. CB-568 is intended to fix that bug. M4 still keeps an independent
+post-teardown invariant so a later regression becomes `DELEGATION_ORPHANED`.
+
+### 2.2 Corrections made during design
+
+The first state table missed `BUSY` in fleetd plus `IDLE` or `DONE` in herdr. It would have found
+the real trace only through a late, weak stall timer. The final model adds
+`TURN_BOUNDARY_LOST` as a strong disagreement state.
+
+The first notification design also required a webhook before `health.enabled` could turn on. That
+removed useful local detection to avoid a narrower human-notification gap. The final design splits
+detection from notification. Missing human escalation is shown as partial coverage instead of
+disabling health.
+
+## 3. Classification precedence
+
+Evidence is applied in this order. A lower rule cannot hide a higher one.
+
+1. **Control link:** failed fleet list plus failed ping becomes `CONTROL_LINK_DOWN`.
+2. **Definitive target loss:** `_not_found` becomes `GONE` or `LEAD_UNREACHABLE` when the control
+   link is healthy.
+3. **Startup and teardown invariants:** readiness expiry becomes `NEVER_READY`; surviving tasks
+   after teardown become `DELEGATION_ORPHANED`.
+4. **Bridge/live disagreement:** `BUSY` plus stable raw `IDLE` or `DONE` becomes
+   `TURN_BOUNDARY_LOST`.
+5. **Known screen evidence:** a tested fatal signature becomes `ERROR_ON_SCREEN`.
+6. **Timed suspicion:** unchanged sparse pane probes may become `STALL_SUSPECTED`.
+7. **Communication quality:** completion fallback becomes `MUTE`; an old inbox entry becomes
+   `REPLY_STRANDED`.
+8. **Normal mode:** `STARTING`, `IDLE`, `WORKING`, `WORK_PENDING`, or `BLOCKED_AMBIGUOUS`.
+
+The member flow in Figure 1 shows lifecycle states and the main fault exits. Fault states are
+reported beside the session FSM; most are not new FSM values.
+
+```mermaid
+flowchart TD
+    Registered["Member registered"] --> Starting["STARTING"]
+    Starting -->|"MCP presence"| Idle["IDLE"]
+    Starting -->|"Readiness grace expires"| NeverReady["NEVER_READY"]
+    Idle -->|"Accepted delivery"| Working["WORKING"]
+    Working -->|"Trusted turn boundary"| Idle
+    Working -->|"Bridge BUSY and herdr IDLE or DONE"| Lost["TURN_BOUNDARY_LOST"]
+    Working -->|"Known fatal screen"| Error["ERROR_ON_SCREEN"]
+    Working -->|"Long age and unchanged sparse probes"| Stall["STALL_SUSPECTED"]
+    Working -->|"Target not found"| Gone["GONE"]
+    Idle -->|"Inbox or queued delivery exists"| Pending["WORK_PENDING"]
+    Pending -->|"Delivery or collection finishes"| Idle
+    Idle -->|"Raw BLOCKED with an open turn"| Blocked["BLOCKED_AMBIGUOUS"]
+    Lost -->|"Strict guarded repair"| Repaired["DONE with reconciled completion"]
+    Lost -->|"Repair refused"| LeadDecision["Lead decision required"]
+```
+
+*Figure 1. The member lifecycle and the main health exits. Pane-based states never authorise an
+automatic retry of the task.*
+
+## 4. State model
+
+### 4.1 Normal and transitional member states
+
+| State | Exact evidence | Meaning and certainty |
+|---|---|---|
+| `STARTING` | Session is `SPAWNING`; MCP presence is absent | Normal inside the startup grace. MCP contact is the readiness signal. |
+| `IDLE` | Session is `READY` or `DONE`; live status is `IDLE` or `DONE`; no open turn or inbox item exists | Normal. Idle is not a fault. |
+| `WORKING` | Session is `BUSY`; raw live status is `WORKING`; the accepted turn is open | Certain that herdr sees work. It does not prove useful progress. |
+| `WORK_PENDING` | Queued delivery or inbox content exists while the target is injectable | Transitional. Existing injector or push logic should move it. |
+| `BLOCKED_AMBIGUOUS` | An open turn exists and raw live status is `BLOCKED` | The bridge cannot tell whether this is permission, input, or a settled screen. |
+
+Idle may drive configured resource cleanup. It never opens an incident and never pages a person.
+
+### 4.2 Member fault and quality states
+
+| State | Exact evidence | Certainty and action |
+|---|---|---|
+| `NEVER_READY` | `SPAWNING`, no MCP presence, and an accepted delivery waits through the existing readiness grace | Delivery never became possible. The exact cause is unknown. Fail the send, stop the process, and preserve a provisioned worktree. |
+| `GONE` | Per-target herdr call returns `_not_found` while fleet list or ping works | Certain target loss. Fail all target work. Do not replay it. |
+| `TURN_BOUNDARY_LOST` | Same session turn stays `BUSY`; same accepted task stays open; two raw snapshots show `IDLE` or `DONE` | Strong disagreement. Strict reconciliation may repair it. |
+| `ERROR_ON_SCREEN` | Suspicious non-working state survives grace; `detection` matches a tested adapter-specific fatal signature | Certain only for the matched signature. A bare word such as `Exception` is not enough. |
+| `STALL_SUSPECTED` | Open turn is older than the configured threshold; two normalised `recent_unwrapped` digests are unchanged; no boundary or reply occurs | Not certain. A long valid API call can look the same. Lead decides. |
+| `MUTE` | Turn resolves through completion fallback instead of `fleet_reply` | Certain that no structured reply won. It does not prove an MCP failure. A single event is a metric, not an incident. |
+| `REPLY_STRANDED` | Typed reply or health message remains after owning-lead push reaches its cap | Collection failed. This does not explain whether the lead is busy, dead, or ignoring the nudge. |
+| `DELEGATION_ORPHANED` | Target is gone, failed, or released, but one or more tasks remain `PENDING` after reconciliation grace | Certain bridge invariant failure. This is not an inbox-drain fault. |
+| `WORK_PRODUCT_AT_RISK` | Provisioned branch has commits after its recorded base; member is `DONE`, `FAILED`, or preserved after release; no turn or inbox item remains; long-idle threshold passed | A warning, not proof of loss. Work may already have an open pull request or a squash merge. |
+
+`MUTE` opens an incident only after a small fixed rate threshold for one target or profile, or when
+it appears with another fault.
+
+`WORK_PRODUCT_AT_RISK` must not become `WORK_PRODUCT_UNCOLLECTED`. The bridge does not know pull
+request or merge state. If committed work appears with `REPLY_STRANDED` or
+`DELEGATION_ORPHANED`, the existing incident gains `committedWorkAtRisk: true`.
+
+### 4.3 Control-link state
+
+| State | Exact evidence | Certainty and action |
+|---|---|---|
+| `CONTROL_LINK_DOWN` | Two full-fleet `agent.list` calls fail across the grace, and herdr `ping` also fails | Certain for the fleetd-to-herdr link. Retry calls, record the incident, and use human escalation if no lead can be reached. |
+
+A failed fleet list alone is not a dead-member claim. A single `_not_found` with a healthy global
+link is a target fault, not a control-link fault.
+
+### 4.4 Lead states
+
+| State | Exact evidence | Meaning and action |
+|---|---|---|
+| `LEAD_IDLE` | Expected lead is present with raw injectable status; no actionable state waits | Normal. Existing heartbeat may run under its own policy. |
+| `LEAD_WORKING` | Expected lead is present with raw `WORKING`; stall threshold is not met | Reachable and busy. Never inject into the live turn. |
+| `LEAD_STATUS_UNKNOWN` | Expected lead is present with raw `UNKNOWN` | Neither dead nor a healthy routing target. Retain evidence and retry. |
+| `LEAD_UNREACHABLE` | Expected lead is absent from two successful live-agent snapshots while ping works, or targeted lookup returns `_not_found` with a healthy control link | Route to a healthy peer. If none exists, use human escalation. |
+| `LEAD_UNRESPONSIVE` | Actionable state waits; lead stays injectable; bounded nudges exhaust; inbox remains uncollected | Route to a healthy peer or a person. |
+| `LEAD_STALL_SUSPECTED` | Lead stays `WORKING` past threshold; two sparse pane probes show no progress | Not certain. Never kill or restart automatically. Route to peer or person. |
+
+The monitor retains the lead name and terminal, last successful sighting, raw status and age,
+consecutive list absences, targeted errors, pane-probe facts, pending incident age, and nudge
+outcomes. Current heartbeat and push loops discard much of this history.
+
+Expected lead identity comes from the same supplier used by `CallerResolver`. It is not liveness
+evidence. `LeadTabScanner` keeps cached identity after a failed scan, so the health monitor compares
+that identity with a fresh successful agent list. A dynamic identity also survives a two-successful-
+snapshot retirement grace. This stops a dead lead from escaping health by disappearing from one map.
+
+### 4.5 Evidence limits
+
+M4 cannot tell these cases apart with current evidence:
+
+- A valid long call and a hung call may have the same status and pane digest.
+- `BLOCKED` does not explain which input is needed.
+- An idle prompt after failure may look like an idle prompt after success.
+- A missing structured reply does not prove a broken MCP connection.
+- An undrained inbox does not explain why the lead did not collect it.
+- Arbitrary pane text cannot safely classify arbitrary exceptions.
+- A branch ahead of its base does not prove that work was not collected.
+
+Logs are outputs, not classifier inputs. The monitor never parses its own logs.
+
+## 5. Automatic action and lead action
+
+### 5.1 Actions the bridge may take
+
+The bridge may:
+
+- retry transient herdr status, list, ping, and pane-read failures with bounded backoff;
+- re-submit Enter after the existing paste/submit race;
+- fail queued delivery after `NEVER_READY`;
+- stop a never-ready process while preserving its provisioned worktree;
+- fail all queued, accepted, and async tasks for a gone or released target;
+- reconcile one lost boundary when every strict gate in Section 8 passes;
+- hold typed messages, nudge the owning lead, and stop at the configured cap;
+- use the existing bounded idle-lead heartbeat;
+- deduplicate, route, update, and resolve incidents.
+
+These actions do not choose new work and do not replay old work.
+
+### 5.2 Decisions reserved for the lead
+
+Only the lead may:
+
+- stop or continue `BLOCKED_AMBIGUOUS`;
+- stop, inspect, or wait on `ERROR_ON_SCREEN`;
+- kill or continue `STALL_SUSPECTED`;
+- spawn a replacement or reassign work;
+- retry a delivered task;
+- choose how to use partial work in a worktree;
+- restart herdr or change network, model, credentials, backend, or configuration.
+
+Reports include literal safe tool calls such as `fleet_status(sessionId="...")`,
+`fleet_poll(ticket="...")`, `fleet_list()`, and optional `fleet_stop(paneId="...")`. A judgement
+state never presents stop as the only action.
+
+### 5.3 Release causes and worktree safety
+
+| Release cause | Process action | Provisioned worktree |
+|---|---|---|
+| `SPAWN_ROLLBACK` before registration or delivery | Stop and clean up | Remove |
+| `COMPLETED` for `READY` or `DONE` without pending work, idle TTL, or successful context-cap completion | Stop | Remove only if clean; preserve a dirty worktree (CB-576) |
+| `NEVER_READY` | Stop | Preserve |
+| `GONE` | Best-effort stop | Preserve |
+| `TURN_FAILED` or lead abort while `BUSY` or `FAILED` | Stop | Preserve |
+| `RELEASE_WITH_PENDING_TASKS` | Stop | Preserve |
+| `SHUTDOWN` | Stop | Preserve |
+
+Explicit stop is state-aware. `SPAWNING`, `BUSY`, `FAILED`, or any target with pending tasks uses a
+preserving cause.
+
+Before abnormal release removes the live session, M4 writes an atomic manifest under the worktree
+root. It records session identity, owner, role, profile, repository, path, branch, base commit,
+release cause, release time, state, and pending task ids. `fleet_list.preservedWorktrees` loads these
+manifests after restart. Stop output and WARN logs also name the path and cause. M4 never
+auto-deletes a preserved worktree.
+
+## 6. Fleet health monitor
+
+Add `FleetHealthMonitor`. Do not widen `StatusPoller` into a policy loop.
+
+`StatusPoller` has a 250 ms delivery cadence and samples only injector targets with outstanding
+work. Health needs all sessions, all leads, task state, inbox age, and global control evidence. One
+loop cannot serve both cadences safely.
+
+Build the monitor like `LeadHeartbeatLoop`:
+
+- pure `decide(snapshot, priorState, now)` logic;
+- a thin scheduler;
+- an injected clock;
+- edge-triggered state changes;
+- no network work in the pure function;
+- no sleeping in tests.
+
+Each enabled fleet tick reads:
+
+- one `AgentControl.list()` result for the whole fleet;
+- one in-memory `SessionManager.roster()` snapshot;
+- accepted turns and async task state;
+- typed inbox depth, kind, and age;
+- push and heartbeat outcomes;
+- configured and discovered leads.
+
+Existing failure paths publish structured evidence to the monitor. The monitor does not infer events
+from log text.
+
+### 6.1 Pane budget
+
+Healthy idle members, recent working members, and quiet leads cause no pane reads.
+
+A pane is eligible only for a stable lost boundary, sustained `BLOCKED` or `UNKNOWN`, work older
+than the suspect threshold, or one final evidence read for a confirmed fault when the pane exists.
+
+Compiled brakes apply even if config asks for more:
+
+- per-target pane cooldown is at least 60 seconds;
+- working age before the first progress probe is at least 300 seconds;
+- at most two pane reads occur in one fleet tick;
+- targets rotate fairly;
+- only a normalised digest and optional clipped local excerpt are stored;
+- no pane excerpt leaves fleetd in a human webhook.
+
+Use `detection` for tested screen signatures. Use normalised `recent_unwrapped` only for progress
+comparison.
+
+## 7. Typed inbox and routing
+
+### 7.1 Semantic record
+
+The typed inbox record carries:
+
+```text
+schemaVersion
+kind: reply | health
+msgId, target, subjectTerminal, recipientLead
+severity, state, evidence
+createdAtEpochMillis, firstSeenEpochMillis, lastSeenEpochMillis
+recoveryTried, suggestedToolCalls, content
+```
+
+A health message never calls `Rendezvous.resolve`. It cannot look like the member's task result.
+
+Both inbox adapters share field preservation, first-id-wins dedup, FIFO among decoded messages,
+explicit ownership, ack, and release rules. The in-memory adapter stores typed records directly. It
+does not copy AMQP migration logic.
+
+### 7.2 AMQP migration
+
+The reader uses AMQP `content_type`, never body sniffing:
+
+```text
+Legacy v0: text/plain
+Typed family: application/vnd.ltms.fleet.inbox-message+json
+```
+
+A legacy reply may begin with `{`. It remains plain text because its media type is `text/plain`.
+Legacy text becomes `kind=reply` with exact UTF-8 content and absent typed metadata.
+
+Typed JSON has required integer `schemaVersion: 1`. Version 1 ignores unknown optional fields.
+Missing required fields, invalid enums, malformed UTF-8 or JSON, and property/body identity mismatch
+are invalid data.
+
+An unknown schema version is not partly decoded. It remains unacknowledged on the original queue and
+creates one operator-visible `unsupported_version` failure. A newer daemon may read it later.
+
+Invalid known-format data is copied byte-for-byte to durable queue
+`agent.<target>.inbox.quarantine`. A dedicated confirm-mode publisher confirms the persistent copy
+before the original is acknowledged. A failed quarantine handoff leaves the original unacknowledged.
+The raw body never enters logs.
+
+Decode failure creates a redacted WARN, metric, `fleet_list` summary, and routed health incident.
+One bad entry never escapes the consumer callback and never stops later valid messages.
+
+Safe downgrade is not supported. The previous build ignores `content_type` and would show typed JSON
+as ordinary reply text. If drained, it would acknowledge the message and lose typed meaning. Typed
+queues must be drained or preserved before an old jar runs.
+
+The existing contract suite uses RabbitMQ. Production uses LavinMQ. The migration and lead-key
+ownership cases must run once against production LavinMQ before release, or the release must state
+that LavinMQ was not checked.
+
+### 7.3 Member routing
+
+A member incident first goes to the exact lead that owns its accepted delegation.
+`PrimaryRegistry` needs a no-fallback `delegatingLeadFor(memberTarget)` query. Health routing must not
+use the old singular-primary fallback when several leads exist.
+
+Publish the incident under the affected member target. Trigger the existing bounded push route. The
+push waits until the owning lead is injectable, so it does not interrupt a live lead turn.
+
+### 7.4 Peer lead routing
+
+Figure 2 shows the route from incident to lead, peer, or person.
+
+```mermaid
+flowchart TD
+    Incident["Open incident"] --> Member{"Member incident?"}
+    Member -->|"yes"| Known{"Exact delegation owner known?"}
+    Known -->|"no"| Sink{"Human webhook enabled and healthy?"}
+    Known -->|"yes"| Owner{"Owner lead healthy?"}
+    Owner -->|"yes"| OwnerInbox["Publish to owner lead path"]
+    Owner -->|"no"| PeerSet["Build healthy peer candidate set"]
+    Member -->|"no, lead incident"| PeerSet
+    PeerSet --> Peer{"Healthy peer exists?"}
+    Peer -->|"yes"| Select["Choose fewest assigned incidents<br/>then stable name and terminal id"]
+    Select --> PeerInbox["Publish to peer lead inbox<br/>and status-gated push"]
+    Peer -->|"no"| Sink
+    Sink -->|"yes"| Webhook["Send classified outbound incident"]
+    Sink -->|"no"| Passive["Keep incident open<br/>show partial coverage on local surfaces"]
+```
+
+*Figure 2. Routing keeps delegation ownership separate from temporary peer fallback.*
+
+Peer candidates exclude the incident subject, failed owner, absent leads, raw-unknown leads, and
+leads with an open unhealthy state. A reachable `WORKING` peer may be selected; its push waits for an
+injectable window.
+
+Choose the candidate with the fewest assigned foreign incidents. Break ties by stable lead name,
+then terminal id. Pin the recipient. Reassign only if that peer becomes unhealthy or retires. A
+routing generation marks a reassignment, and old pending assignments become superseded.
+
+`fleet_list` lead rows show health, health age, assigned foreign incident count, and a bounded list
+of incident id, subject, state, severity, age, and routing generation. The top-level view also shows
+owner, recipient, and routing reason.
+
+A peer incident is published under the recipient lead's inbox key, not the failed subject's key. Its
+status-gated nudge names the failed lead and gives the exact
+`fleet_poll(target="<recipient-terminal>")` call.
+
+### 7.5 Lead inbox ownership
+
+Add `LeadInboxRegistry`, driven by the same expected-lead supplier as `CallerResolver`.
+
+It calls `replyInbox.own(leadTerminal)` at startup for configured leads, after successful discovery,
+after config adds a lead, and before publication. Ownership is not an authorization side effect.
+
+A missing lead keeps its key owned. Release happens only after confirmed retirement, all incidents
+are reassigned or resolved, typed health messages move or ack, and the queue is empty. Own a
+replacement terminal before moving messages from the old key. Never release a non-empty in-memory
+lead key, because in-memory release clears local data.
+
+### 7.6 Single-lead deployment
+
+One lead and no peer is a normal mode, not an edge case.
+
+An idle, reachable lead may receive the existing bounded nudge. An unreachable or stalled sole lead
+has no safe in-loop recovery. The bridge must not restart or replace it. A new lead would not have the
+failed lead's plan or context, and an uncertain relaunch could create two orchestrators.
+
+With no webhook, only `fleet_list`, `/healthz`, metrics, WARN logs, and the incident journal remain.
+These are passive surfaces. They are not a human notification.
+
+## 8. Lost-boundary reconciliation
+
+This is the only M4 path that reconstructs a result. It must prefer a visible stall over a fabricated
+reply.
+
+### 8.1 Why normal completion rules are not enough
+
+Current `CompletionResolver.resolve` has two fail-open rules. It resolves when the delivery baseline
+is missing. It also resolves an empty completion when the pane read fails. Those choices are valid
+after a trusted `WORKING -> IDLE` boundary because the bridge knows the turn ran. They are unsafe
+when health only guesses that a boundary was lost.
+
+M4 gives each accepted send an internal `TurnToken`. It ties target, exact waiter, session turn,
+delivery baseline, and task outcome together.
+
+### 8.2 Delivery baseline
+
+Capture the baseline immediately after prompt send and before the delivery future completes. Store:
+
+```text
+TurnToken
+exact waiter identity
+capture time and pane source
+normalised assistant block clipped to MAX_SCRAPE_CHARS
+whether a supported assistant marker was recognised
+capture result: PRESENT | READ_FAILED | UNRECOGNISED
+```
+
+A failed or missing baseline never authorises repair. A late baseline is not valid evidence. After a
+daemon restart, the old waiter, task, token, and baseline are gone, so the old turn cannot be
+repaired.
+
+Automatic repair is enabled only for agent kinds with tested assistant-block fixtures. Current
+extraction is Claude Code-specific and falls back to arbitrary raw text without `⏺`. That raw fallback
+cannot authorise repair. OpenCode repair stays disabled until live pane fixtures exist.
+
+### 8.3 Strict gates and resolver result
+
+Figure 3 shows the repair gates. Any failed gate keeps the waiter unchanged.
+
+The two raw snapshots must describe the same `TurnToken` and session turn. No `WORKING`,
+`BLOCKED`, `UNKNOWN`, missing-agent, reply, failure, or new-delivery observation may occur between
+them.
+
+```mermaid
+flowchart TD
+    Candidate["TURN_BOUNDARY_LOST candidate"] --> Stable{"Same TurnToken and BUSY turn<br/>across two raw IDLE or DONE snapshots?"}
+    Stable -->|"no"| Resnapshot["Take a fresh snapshot"]
+    Stable -->|"yes"| Waiter{"Exact captured waiter<br/>still open by identity?"}
+    Waiter -->|"no"| Stale["STALE_TURN or ALREADY_RESOLVED"]
+    Waiter -->|"yes"| Baseline{"Successful recognised<br/>delivery baseline exists?"}
+    Baseline -->|"no"| Refuse["Refuse repair<br/>leave ticket pending"]
+    Baseline -->|"yes"| Read{"Fresh pane read succeeds?"}
+    Read -->|"no"| Refuse
+    Read -->|"yes"| Output{"Recognised non-blank assistant block<br/>differs from clipped baseline?"}
+    Output -->|"no"| Refuse
+    Output -->|"yes"| Resolve["Shared CompletionResolver guard core<br/>resolves exact waiter"]
+    Resolve -->|"won race"| Repaired["RECONCILED_COMPLETION<br/>same turn becomes DONE"]
+    Resolve -->|"lost race"| Resnapshot
+```
+
+*Figure 3. Repair needs stronger evidence than a normal observed turn boundary.*
+
+Refactor the current resolver into one guard core with two policies:
+
+```text
+resolveCaptured(target, inFlight, OBSERVED_BOUNDARY)
+resolveCaptured(target, inFlight, LOST_BOUNDARY_REPAIR)
+```
+
+The health monitor calls only:
+
+```text
+CompletionResolver.reconcileLostBoundary(target, expectedTurnToken)
+```
+
+It returns `REPAIRED`, `ALREADY_RESOLVED`, `REFUSED_NO_CAPTURE`, `REFUSED_NO_BASELINE`,
+`REFUSED_UNREADABLE`, `REFUSED_UNCHANGED`, `REFUSED_AMBIGUOUS_OUTPUT`, `STALE_TURN`, or
+`RACE_LOST`.
+
+Only `REPAIRED` and same-turn `ALREADY_RESOLVED` may move that turn from `BUSY` to `DONE`. A
+per-target reconciliation gate stops a queued second send from being accepted between waiter
+resolution and the FSM transition.
+
+### 8.4 Lead-visible marker and refusal
+
+A repaired result uses distinct `RECONCILED_COMPLETION` values in `Rendezvous`, `MessageService`,
+task poll source, and metrics. The lead sees:
+
+```text
+[repaired completion - fleetd detected a lost turn boundary. The member did not call
+fleet_reply; pane-derived text follows and may be partial]
+```
+
+Clipped text also keeps the existing clipped-tail marker.
+
+A refused repair leaves `TURN_BOUNDARY_LOST` open and the ticket pending. The report states that no
+reply was reconstructed and no task was replayed. `UNCHANGED`, `UNREADABLE`, and
+`AMBIGUOUS_OUTPUT` get at most one delayed retry for the same token. Missing capture or baseline gets
+no retry. After two refused scrapes, automatic repair stops for that token.
+
+### 8.5 Target-wide teardown invariant
+
+CB-568 owns the multi-ticket cancellation mechanism. M4 routes every terminal cause through that one
+idempotent operation and checks this independent invariant after teardown:
+
+- no injector entry exists for the target;
+- no accepted turn or completion record exists;
+- no rendezvous waiter or ask exists;
+- every async task is terminal or was already terminal;
+- no thread waiting for the target send lock can later accept it;
+- new sends fail immediately;
+- each old task has one terminal outcome and one metric count.
+
+A violation becomes `DELEGATION_ORPHANED`. The monitor may call the same idempotent target-wide
+failure operation once. It never recreates the task.
+
+## 9. Capacity and utilisation
+
+Capacity is a view, not a health state.
+
+`fleet_list` adds one block per profile:
+
+```text
+profile, maxLoad, live, free, reclaimable
+```
+
+For an unlimited profile, `maxLoad` and `free` are null. `free` is
+`max(0, maxLoad - live)` for a capped profile.
+
+The view must use the exact live-count function used by placement. A second calculation could show a
+free slot that placement then refuses. Member rows add `idleForSeconds` only when state is `READY` or
+`DONE`, no accepted turn exists, and the inbox is empty. `reclaimable` means only that the member
+holds capacity without open bridge work.
+
+The existing idle-lead nudge gains a bounded capacity summary. It lists per-profile live, cap, free,
+and reclaimable counts, plus at most three long-idle members. Capacity does not make
+`FleetState.hasPending()` true. A changed capacity fingerprint may re-arm one capped heartbeat
+sequence. The fingerprint excludes changing idle durations, so a static idle fleet cannot reset the
+cap forever. Reply-push stand-down remains first.
+
+The bridge must never:
+
+- spawn a member because a slot is free;
+- generate a task or acceptance criteria;
+- move queued work to another member or profile;
+- treat a free slot or idle member as an incident;
+- stop an idle member only to improve utilisation.
+
+The bridge knows capacity facts but has no work list. Only the lead has the plan, task context,
+side-effect history, and acceptance criteria.
+
+Capacity calculation is in memory and adds no pane reads. Work-product checks run on a terminal
+session edge, not every fleet tick.
+
+This capacity design adds no automatic stop. The accepted `NEVER_READY` cleanup can still stop a
+very slow startup after the existing grace, which is a known risk. Free capacity and long idle time
+never trigger that path.
+
+## 10. Human escalation and notification
+
+### 10.1 Escalation rule
+
+Notify a person only when no healthy lead can act:
+
+- `CONTROL_LINK_DOWN` survives grace;
+- a lead is unhealthy and no healthy peer can receive the incident;
+- a member incident has no known owning lead;
+- the only owning lead becomes unreachable, unresponsive, or stalled;
+- incident publication or routing itself fails.
+
+Do not page a person for a member fault while a healthy owning lead exists. An uncollected member
+incident feeds lead-health evidence. If the lead then becomes unhealthy, peer or human routing starts.
+
+### 10.2 Detection and notification switches
+
+`health.enabled` controls detection and bridge-local reporting. It does not require a webhook.
+
+`health.notifications.mode` is `disabled` or `webhook`. Disabled is valid and is the default.
+Webhook mode requires a resolved environment variable. Turning notification off stops outbound
+attempts but keeps incidents. Turning it back on resumes still-open human incidents.
+
+Without a sink, `fleet_list.healthCoverage` states that human escalation is unavailable. `/healthz`
+keeps its existing HTTP liveness result and adds a nested `fleetHealth.status=partial` component.
+Metrics and one startup or reload WARN expose the same limit.
+
+### 10.3 Incident and delivery deduplication
+
+One open incident uses this key:
+
+```text
+(scope, subjectStableId, state, causeFingerprint)
+```
+
+The cause fingerprint includes stable error codes, dependency names, signature ids, or invariant
+names. It excludes times, ages, retry counts, pane text, and changing digests. A later recurrence
+after resolution gets a new generation and incident id.
+
+Each outbound event uses:
+
+```text
+Idempotency-Key = hash(incidentId, eventType, eventRevision)
+```
+
+Event types are `open`, `severity_changed`, `reminder`, and `resolved`. Transport retries keep the
+same key.
+
+An atomic owner-only journal beside the active config stores open incidents, routing, delivered
+revisions, retry state, and resolution state. It stores no pane or task content. Journal failure does
+not stop detection, but notification coverage becomes degraded.
+
+### 10.4 Retry, reminder, and resolve
+
+Send the first event immediately. Retry network errors, timeouts, HTTP 408, HTTP 429, and HTTP 5xx
+with full-jitter exponential backoff:
+
+```text
+base: 5 seconds
+factor: 3
+maximum delay: 15 minutes
+one outstanding attempt per event
+```
+
+Respect `Retry-After` up to 15 minutes. Other HTTP 4xx responses are permanent for that event until
+config changes or a person requests replay.
+
+Transport retry is not an incident reminder. `humanRepeatSeconds` creates a new reminder revision
+for an unresolved critical incident after the last successful human event. Disabled mode does not
+build an unbounded reminder queue.
+
+Send `resolved` only if at least one human event for that incident was delivered. If an incident
+resolves before its first successful delivery, cancel the pending open event and record local
+resolution.
+
+### 10.5 Outbound payload boundary
+
+An outbound payload may contain incident id and event type, severity, state, scope, stable bridge
+ids, role or profile, times, duration, structured evidence type and counts, recovery attempted,
+routing reason, coverage, and safe tool calls.
+
+It must never contain:
+
+- raw pane text, pane excerpts, or pane digests;
+- task briefs, prompts, or member reply content;
+- source files, diffs, or worktree file content;
+- worktree paths;
+- environment values, tokens, credentials, headers, or webhook URL;
+- raw exception messages or stack traces;
+- arbitrary model output.
+
+The sink response body is ignored. A webhook cannot direct recovery. n8n remains outbound-only.
+
+### 10.6 Metrics
+
+M4 adds bounded-label series:
+
+```text
+fleet_health_incidents{scope,state,severity}
+fleet_health_incidents_total{event}
+fleet_health_notifications_total{event,outcome}
+fleet_health_notification_queue_depth
+fleet_health_notification_last_success_seconds
+fleet_health_notification_capability{mode,status}
+fleet_lead_health{lead,state}
+fleet_lead_assigned_incidents{lead}
+```
+
+Metric labels never include terminal ids, incident ids, URLs, or error text.
+
+## 11. Configuration
+
+The optional `health:` block is absent or disabled by default. The dormant monitor scheduler does no
+herdr or pane work while disabled. Every listed key is hot because the monitor reads `ConfigRef` on
+each tick or notification.
+
+| Key | Class | Default and hard bound | Purpose |
+|---|---|---|---|
+| `health.enabled` | Hot | `false` | Enable detection and bridge-local reporting. |
+| `health.snapshotIntervalSeconds` | Hot | default 30, minimum 15 | Whole-fleet comparison cadence. |
+| `health.workingSuspectAfterSeconds` | Hot | default 600, minimum 300 | Age before working-pane probes. |
+| `health.paneProbeIntervalSeconds` | Hot | default 60, minimum 60 | Per-target pane cooldown. |
+| `health.leadUnresponsiveAfterSeconds` | Hot | default 300, minimum 120 | Delay after exhausted actionable nudges before lead fault. |
+| `health.humanRepeatSeconds` | Hot | default 3600, minimum 900 | Minimum repeat period for one open human incident. |
+| `health.capacityLongIdleAfterSeconds` | Hot | default 900, minimum 300 | Long-idle threshold for capacity summaries. |
+| `health.includePaneExcerpt` | Hot | `false` | Allow a clipped excerpt in local lead reports only. Human payloads still exclude it. |
+| `health.notifications.mode` | Hot | `disabled` | Select `disabled` or `webhook`. |
+| `health.notifications.webhookUrlEnv` | Hot | required in webhook mode | Name of the environment variable that holds the sink URL. |
+| `health.notifications.requestTimeoutMs` | Hot | default 10000, range 1000-30000 | Whole webhook request limit. |
+
+Two consecutive snapshots are compiled floors for lost boundary, lead disappearance, and control
+link failure. The two-pane-reads-per-tick limit is also compiled and cannot be weakened by config.
+
+## 12. Delivery units and acceptance
+
+### Unit 1 - Evidence model and fleet snapshot
+
+Scope: health state model, fleet join, clocks, evidence retention, and pane budget.
+
+Acceptance criteria:
+
+1. One `agent.list` call covers one enabled fleet tick.
+2. Pure decision tests cover every state and every evidence limit in Section 4.
+3. `BUSY` plus stable raw `DONE` opens `TURN_BOUNDARY_LOST` after two snapshots.
+4. Healthy fleet snapshots perform zero pane reads.
+5. Pane cooldown, two-read fleet budget, and fair rotation cannot be disabled by config.
+6. Logs are outputs only; no log parsing exists.
+7. Fleet snapshots expose the same profile live-count calculation that placement uses.
+8. Capacity rows report cap, live, free, and reclaimable values without opening incidents.
+
+### Unit 2 - Lost boundary and task reconciliation
+
+Scope: accepted-turn identity, guarded repair, target-wide teardown, release causes, and preserved
+worktree discovery.
+
+Acceptance criteria:
+
+1. Every accepted send receives a stable `TurnToken` tied to target, exact waiter, and delivery
+   baseline.
+
+   **Corrected during implementation (2026-08-15).** This criterion first also required the session
+   turn number and the task outcome. That is not implementable at this layer, and the implementer
+   refused it three times rather than fabricate a value — correctly. The reason is an ordering fact
+   that is invisible from any single class: `MessageService` owns acceptance and holds the waiter and
+   the async `Task`, but it learns nothing about delivery, because the delivery event goes to
+   `CompletionResolver` through `TurnListener.onDelivered`. And `CompletionResolver.onDelivered` runs
+   *before* `SessionManager.onDelivered`, so the session turn number does not exist yet at the only
+   point where the token could capture it.
+
+   Two ways out were rejected. A shared registry keyed by target reintroduces exactly the "whichever
+   send happens to be waiting" ambiguity the token exists to remove — the same weak claim
+   `Rendezvous.currentWaiter` warns about. Injecting a turn counter into `MessageService` adds a
+   required cross-layer dependency to populate a field that nothing in this slice reads, which is
+   speculative coupling across a boundary already shown to be fragile.
+
+   So the token identifies the **accepted send**, and `SessionManager` keeps verifying its own
+   delivery separately. Repair (criterion 2) does need the session turn; binding it means resolving
+   that acceptance-versus-delivery ordering first, and that work belongs to the repair unit, not
+   here. The token record carries a comment saying the field is deliberately absent.
+2. Repair requires the same `BUSY` token, two raw `IDLE` or `DONE` snapshots, no conflicting
+   observation, exact open waiter, successful baseline, and new recognised assistant output.
+3. Missing, failed, late, or post-restart baseline never authorises repair.
+4. Repair is enabled only for agent kinds with tested assistant-block extraction. Raw-text fallback
+   without a recognised marker refuses repair.
+5. Normal completion and repair use one resolver guard core. Waiter, scrape, clipping, unchanged, and
+   exact-turn guards are not duplicated.
+6. `reconcileLostBoundary` returns every typed result named in Section 8.3.
+7. Only `REPAIRED` and same-turn `ALREADY_RESOLVED` may move the same turn to `DONE`.
+8. A per-target reconciliation gate blocks a queued second send during repair and FSM update.
+9. Repaired completion has distinct rendezvous kind, message outcome, poll source, lead marker, and
+   metric. Clipping keeps its extra marker.
+10. Unchanged, unreadable, or ambiguous evidence gets at most one delayed retry. Missing capture or
+    baseline gets none.
+11. Refusal leaves the ticket pending and tells the lead that no result was rebuilt or replayed.
+12. Release, gone, never-ready, and abnormal stop use CB-568's one idempotent target-wide failure
+    operation.
+13. The post-teardown invariant in Section 8.5 is tested independently of CB-568 internals.
+14. A violated teardown invariant creates `DELEGATION_ORPHANED` and retries only the idempotent
+    failure operation.
+15. `SPAWN_ROLLBACK` and normal `COMPLETED` remove worktrees. Abnormal and shutdown causes preserve
+    them.
+16. Explicit stop is state-aware. Any pending task or non-terminal state preserves the worktree.
+17. Atomic preserved-worktree manifests reload after restart and appear in lead-only
+    `fleet_list.preservedWorktrees`.
+18. Manifest failure preserves the worktree and opens an operator-visible health failure.
+19. Provision records the base commit. Terminal, long-idle worktrees report
+    `WORK_PRODUCT_AT_RISK` only under the evidence in Section 4.2 and never auto-delete work.
+20. No path replays a delivered task, rebuilds its brief, or retargets it, even when prompt text is
+    available.
+21. Tests cover both real traces, all repair refusals, clipping, explicit-reply and next-turn races,
+    restart without capture, concurrent send and release, and preserved discovery after restart.
+
+#### Unit 2 - what has landed so far
+
+Checked against `main` at `e09cac6` on 2026-08-15. Unit 2 was written as one block, but parts of it
+have since been built by separate CB tickets. Read this before planning the rest, or that work gets
+done twice.
+
+The check was a symbol survey of `fleetd/src/main/java` plus the merge history. It tells you whether
+the machinery exists at all. It is **not** a line-by-line audit of whether each criterion is fully
+met, and I did not run one.
+
+| Criterion | Marker searched for | Found in main source | Reading |
+|---|---|---|---|
+| 1 | `TurnToken` | 8 files | **Done** — unit 2a, merged as `fec284e`. Criterion 1 was corrected first; see the note under it. |
+| 2-5, 9 | `REPAIRED` | 0 files | Not started. The whole guarded-repair path is absent. |
+| 6, 7, 10 | `reconcileLostBoundary` | 0 files | Not started. |
+| 12 | CB-568 failure operation | via CB-580 | **Partial.** CB-580 (`0af902e`) routes `GONE` and `NEVER_READY` into the one idempotent target-wide failure. I did not check that release and abnormal stop go through the same call. |
+| 14 | `DELEGATION_ORPHANED` | 3 files | **Partial.** The health state exists. The teardown-invariant check that creates it, and the retry rule, do not. |
+| 15 | `SPAWN_ROLLBACK` | 0 files | **Contradicted — see below.** |
+| 16 | — | — | Partial at best. CB-576 made release preserve a dirty worktree; whether explicit stop is state-aware is not checked. |
+| 17, 18 | `preservedWorktrees` | 0 files | Not started. No manifest, and no lead-only `fleet_list` field. |
+| 19 | `WORK_PRODUCT_AT_RISK` | 0 files | Not started. |
+
+**Criterion 15 no longer matches the code, and the code is right.** It says "normal `COMPLETED`
+remove worktrees". Since CB-576 (`500bfa2`) that is false on purpose: a `COMPLETED` release now
+preserves the worktree when it still holds uncommitted work, because deleting it destroys work
+nobody can get back. CB-576 was filed after exactly that loss. CB-581 goes further — if the
+dirty-check itself fails, the worktree is preserved rather than removed, since "we could not tell"
+must not be treated as "it is clean".
+
+So criterion 15 should be rewritten as: `SPAWN_ROLLBACK` and a `COMPLETED` release with a **clean**
+worktree remove it; abnormal causes, shutdown, a dirty worktree, and a failed dirty-check all
+preserve it. `SPAWN_ROLLBACK` itself does not exist yet.
+
+### Unit 3 - Typed inbox and member routing
+
+Scope: semantic record, AMQP migration, both adapters, member routing, polling, and member health in
+`fleet_list`.
+
+Acceptance criteria:
+
+1. AMQP selects legacy or typed decoding only from `content_type`; it never sniffs the body.
+2. Persistent `text/plain` from the old build becomes `kind=reply` with exact UTF-8 content,
+   including content beginning with `{`.
+3. New entries use the vendor media type, `schemaVersion: 1`, UTF-8, persistent delivery, and AMQP
+   message ids.
+4. Version 1 ignores unknown optional fields but rejects missing fields and identity mismatch.
+5. Unknown versions are not decoded or acked. They remain on the original queue and create one
+   deduplicated failure.
+6. Invalid known data never escapes the callback, appears as a reply, or blocks later valid messages.
+7. Invalid data reaches durable per-target quarantine before original ack. Failed handoff leaves the
+   original unacked.
+8. Decode failures create redacted WARN, metric, `fleet_list` summary, and routed incident without
+   raw content.
+9. Both adapters pass one semantic contract for fields, FIFO, dedup, ownership, ack, and release.
+10. Lead keys require explicit ownership. Publication never claims a queue.
+11. Unit codec tests cover legacy `{`, Unicode, malformed UTF-8, typed round trip, additive fields,
+    malformed JSON, missing fields, identity mismatch, media type, version, and dedup.
+12. A live broker contract writes old wire data and reads it with the new adapter after reconnect.
+13. Live contract tests cover mixed entries, quarantine confirm-before-ack, unsupported redelivery,
+    later progress past poison, property persistence, lead ownership, and ack removal.
+14. Safe downgrade is documented as unsupported.
+15. RabbitMQ contract tests pass with `mvn test -Pcontract`. The same cases run once on production
+    LavinMQ, or the release states that LavinMQ was not checked.
+16. Member incidents route to the exact delegating lead and never resolve a task rendezvous.
+17. `fleet_list` shows compact member health and capacity without pane content. Member
+    `idleForSeconds` is present only when no accepted turn or inbox item exists.
+
+### Unit 4 - Lead health and peer routing
+
+Scope: lead evidence, exact ownership, peer selection, explicit-recipient push, and lead inbox
+lifecycle.
+
+Acceptance criteria:
+
+1. Lead identity uses the `CallerResolver` supplier. Liveness uses successful current agent data.
+2. Two successful-list absences with healthy ping become `LEAD_UNREACHABLE`; global link failure does
+   not.
+3. Raw `WORKING`, raw `UNKNOWN`, first-seen time, failures, last success, and error class persist
+   across ticks.
+4. Heartbeat and push publish status and nudge outcomes before safe no-injection decisions.
+5. Dynamic lead identity survives a two-successful-snapshot retirement grace.
+6. Member incidents first use exact delegation ownership with no singular-primary fallback.
+7. Peer selection follows the exclusions, load rule, and stable tie break in Section 7.4.
+8. A selected working peer is not interrupted. Its push waits for an injectable window.
+9. Recipient assignment stays pinned. Reassignment increments generation and supersedes old pending
+   assignment.
+10. `fleet_list` shows bounded foreign assignments, recipient, reason, and generation without pane
+    content.
+11. `LeadInboxRegistry` owns configured and discovered lead keys before publication.
+12. Missing leads keep ownership. Retirement needs an empty queue and handled incidents.
+13. Replacement owns the new key before messages move. Non-empty in-memory keys are not released.
+14. Tests cover dead versus busy, unknown, global failure, stale scan cache, disappearance, one peer,
+    several peers, reassignment, and no peer.
+15. Adapter tests cover lead ownership, restart re-ownership, retirement, and terminal replacement.
+    LavinMQ is checked or named as unchecked.
+16. A sole unreachable or stalled lead is never restarted or replaced. Without a sink, only passive
+    evidence remains and every coverage surface says so.
+
+### Unit 5 - Human sink, hot config, metrics, and operator coverage
+
+Scope: generic webhook, config split, incident journal, retry, resolve, metrics, example config, and
+operator documentation.
+
+Acceptance criteria:
+
+1. `health.enabled` works without a human sink.
+2. Notification mode is hot, defaults to disabled, and supports disabled or webhook.
+3. Webhook mode requires a resolved environment value. Bad notification config does not disable an
+   already valid detector.
+4. Mode changes keep open incidents. Re-enable resumes eligible incidents.
+5. `fleet_list`, `/healthz`, metrics, and one WARN show partial coverage without a sink. HTTP
+   liveness behavior stays unchanged.
+6. One-lead, no-sink coverage states that lead failure has no active notification or recovery.
+7. Incident and outbound dedupe use the stable keys in Section 10.3.
+8. The owner-only local journal survives restart and contains no pane or task content.
+9. Journal failure keeps detection running but marks notification coverage degraded.
+10. Retry tests cover network failure, timeout, 408, 429, `Retry-After`, 5xx, permanent 4xx, jitter,
+    delay cap, config re-arm, and one outstanding attempt.
+11. Reminders and transport retries remain separate. Disabled mode does not build an unbounded queue.
+12. Resolve sends only after an earlier human event succeeded. Resolve-before-delivery cancels stale
+    open delivery.
+13. Metrics use bounded labels and exclude ids, URLs, and error text.
+14. Payload tests reject every content type forbidden in Section 10.5.
+15. Webhook response bodies are ignored and cannot direct recovery.
+16. Tests cover disabled mode, one lead without sink, open/update/reminder/resolve, restart, dedup,
+    reassignment, disable/re-enable, and sink failure while local health continues.
+17. `fleetd.example.yaml` documents all hot keys and compiled floors.
+18. The operator Features wiki is updated separately. The portable `CLAUDE.md` block is checked and
+    changed only if shipped tool or inbox semantics make it untrue.
+19. `mvn clean install` passes.
+
+## 13. Not checked and release gates
+
+These limits are part of the design, not optional follow-up notes.
+
+- **OpenCode pane status and assistant markers were not checked.** OpenCode lost-boundary repair is
+  disabled until live fixtures exist.
+- **Permission-prompt status was not checked** for Claude Code or OpenCode. `BLOCKED` remains
+  ambiguous and has no automatic action.
+- **`recent_unwrapped` stability was not checked** across all supported agent kinds. If normalisation
+  is not stable, `STALL_SUSPECTED` must say its evidence is weaker.
+- **The real `BUSY + DONE` trace was not replayed against live herdr.** The design uses the observed
+  production trace and current poller behavior.
+- **CB-568 was not present when Unit 2 was designed.** Unit 2 must inspect the landed API and keep its
+  independent teardown invariant.
+- **Production LavinMQ was not checked.** Existing durable-inbox contracts use RabbitMQ. Migration,
+  quarantine, redelivery, lead ownership, and reassignment must run on LavinMQ before release or be
+  recorded as unchecked.
+- **Live multi-lead routing was not checked.** Peer choice and reassignment are design rules backed by
+  fake-clock and adapter tests until a live exercise runs.
+- **A live sole-lead failure with a webhook was not checked.** The no-peer path is a design result,
+  not a tested recovery.
+- **No n8n, Slack, PagerDuty, or other receiver was checked.** The webhook remains generic and
+  outbound-only.
+- **Deployment supervisor behavior for nested `/healthz` fields was not checked.** HTTP liveness
+  status stays unchanged to reduce this risk.
+- **Incident-journal crash behavior was not checked** because the journal does not exist yet. Unit 5
+  must test atomic replacement and restart recovery.
+- **Worktree merge state cannot be checked reliably** without forge or explicit collection evidence.
+  `WORK_PRODUCT_AT_RISK` stays a warning.
+
+## 14. Locked exclusions
+
+M4 does not expose `agent.read` as a bridge tool. It does not add a workflow engine, inbound n8n
+authority, automatic task assignment, task replay, automatic lead replacement, or automatic member
+spawn for free capacity.
+
+The bridge remains a message bus with evidence and bounded mechanical repair. The lead remains the
+place where judgement and work planning happen.

docs/MCP-Contract.md

@@ -1,296 +1,162 @@
-# MCP Contract — `bridged`'s unified gateway
+# MCP flows and error model — `fleetd`
 
-> **Status:** 🟡 Design (2026-07-14). Greenfield — no MCP code exists yet; the pom carries
-> only Javalin/Jackson. This page defines the tool surface that CB-104 and its followers
-> implement. It supersedes nothing; it fills the "MCP server face" left open by the
-> [Architecture](1-Architecture) page.
-
-`bridged` is the **sole communication gateway** for every Claude session in the bridge. Both
-the **primary** (Opus, on subscription) and every **worker** (off-subscription Claude Code)
-mount the *same* MCP server with a single `claude mcp add` line, and talk only through its
-tools. No Claude session ever addresses a broker, a peer, or the network directly.
-
-This document defines every MCP tool that face must expose, who may call it, its blocking
-semantics, and how it maps onto the code already in the tree.
+> **What this page is.** The **flows**: how a delegation, a clarification, a detached task and a
+> silent member each travel through `fleetd`. These shapes are what shipped, and they are hard to
+> read off the code because they span the MCP face, the rendezvous registry, the `Injector` and
+> herdr.
+>
+> **What this page is NOT: a tool reference.** It deliberately holds no tool catalogue, no
+> parameter tables and no REST paths. **The live MCP schema is the authority** — each tool's own
+> description and parameters, as mounted — with the intent→tool table in `CLAUDE.md` as the short
+> form.
+>
+> That absence is the fix for fleetd #114 (CB-609), and it is worth stating why. This page used to
+> carry a full tool catalogue written in July 2026, before any MCP code existed. The code shipped;
+> the page did not follow. By August it named two tools that do not exist, omitted five that do,
+> had the wrong name for nearly every parameter, pointed at REST paths the daemon does not serve,
+> and — worst — still described an identity model (*"any connection that does not map to a known
+> worker is treated as a primary"*) that was a real privilege bug, fixed since by the ancestry
+> walk in fleetd #161. Every one of those errors is the same error: **a second, hand-maintained
+> copy of something the code already states**. So the second copy is gone rather than corrected.
+> Only the flows remain, because a flow is a shape rather than a name, and shapes are what this
+> page was ever good for.
+>
+> The names that do appear below are checked by `McpContractDocTest`, which fails if this page
+> names a `fleet_*` tool the server does not register. That test is the whole reason it is safe to
+> write a tool name here at all.
 
 ---
 
-## 1. Design constraints (non-negotiable)
+## 1. Rendezvous flows
 
-These come from the project's core invariants and bound every decision below.
+### 1.1 Delegation — happy path
 
-1. **One server, both roles.** The primary and all workers mount an identical server. The
-   catalog must serve both, and `bridged` must decide *who is calling* from the connection —
-   never from a caller-supplied argument that could be spoofed.
-2. **Subscription-safe by construction.** No MCP tool ever reads, sets, or forwards
-   `ANTHROPIC_BASE_URL`. Mounting the bridge cannot move a session off subscription.
-   Enforced today by [`SubscriptionGuard`](1-Architecture).
-3. **Blocking rendezvous, no busy-poll.** The primary consumes a worker's reply through a
-   *single* MCP call that `bridged` holds open — never a cross-turn poll loop that would burn
-   subscription quota.
-4. **Status-gated delivery.** Anything that puts text into a worker flows through the existing
-   [`Injector`](1-Architecture): delivered only when the worker is `idle`/`blocked`, at most
-   one message per turn.
-5. **`bridged` owns policy; herdr owns PTYs.** MCP tools express *intent*; `bridged`
-   translates it into guard checks, rendezvous bookkeeping, and herdr `agent.*` calls.
-
----
-
-## 2. Topology
-
-Both faces live in the one daemon. The **north face** is MCP (this document); the **south
-face** is the herdr Unix socket. REST/SSE remains only for non-Claude clients and dashboards.
-
-```mermaid
-flowchart LR
-    OPUS["Opus — primary<br/>(Claude Code, env CLEAN)<br/>MCP client"]
-    subgraph BD["bridged — standalone daemon"]
-        MCP["MCP server (north face)<br/>bridge_send · bridge_reply<br/>bridge_ask · bridge_status · lifecycle"]
-        RDV["rendezvous registry<br/>(blocking-call waiters)"]
-        INJ["Injector + StatusPoller<br/>(status-gated writer)"]
-        SOCK["herdr socket client (south face)"]
-        MCP --> RDV
-        RDV --> INJ
-        INJ --> SOCK
-        MCP --> SOCK
-    end
-    HERDR["herdr<br/>panes · agent-status"]
-    W["worker claude pane<br/>ANTHROPIC_BASE_URL set<br/>MCP client"]
-
-    OPUS -->|"bridge_send (blocks)"| MCP
-    W -.->|"bridge_reply / bridge_ask"| MCP
-    SOCK -->|"agent.start · agent.send<br/>agent.get · pane.close"| HERDR
-    HERDR -->|"drives PTY"| W
-
-    classDef ext fill:#2b6cb0,stroke:#1a365d,color:#ffffff;
-    classDef core fill:#2f855a,stroke:#22543d,color:#ffffff;
-    class OPUS,W ext
-    class MCP,RDV,INJ,SOCK core
-```
-
----
-
-## 3. Identity & addressing
-
-Because the same server is mounted by everyone, `bridged` resolves the caller's role on every
-request — this is the linchpin of the whole contract and has no code yet.
-
-- **Workers are known.** `bridged` spawns every worker
-  ([`WorkerService`](1-Architecture)) and records its herdr session UUID / `terminal_id` on
-  the returned [`Agent`]. When a call arrives on a connection that maps to a known worker,
-  the caller is *that* worker — so **workers never pass a target**; routing is implicit.
-- **The primary is "not a worker".** Any connection that does not map to a known worker is
-  treated as a primary. It addresses workers **explicitly** by `target` — a session UUID,
-  a `terminal_id`, or a friendly `profile` name.
-- **Turn correlation.** A blocking `bridge_send` registers a *waiter* keyed by worker
-  identity. A worker's later `bridge_reply` / `bridge_ask` on the same identity resolves that
-  waiter. A `turn_id` is minted per exchange so a clarification round-trip
-  (§6.2) rejoins the right turn.
-
----
-
-## 4. Transport
-
-`bridged` is a long-lived daemon serving **multiple** concurrent clients (one primary + N
-workers), so a per-client stdio child is the wrong shape. The recommended transport is
-**streamable-HTTP / SSE** on the same bind as the REST face:
-
-```bash
-# identical on primary and every worker
-claude mcp add --transport http bridged http://127.0.0.1:8080/mcp
-```
-
-This adds an MCP-server dependency the pom does not yet carry. See [Open decisions](#10-open-decisions).
-
----
-
-## 5. Tool catalog
-
-| Tool | Caller | Blocks? | Backing (exists today?) |
-|---|---|---|---|
-| [`bridge_send`](#bridge_send) | primary | yes (default) | `Injector.enqueue` ✅ · rendezvous registry ❌ (CB-104) |
-| [`bridge_reply`](#bridge_reply) | worker | no | rendezvous ❌ · pane injection via `Injector` ✅ |
-| [`bridge_ask`](#bridge_ask) | worker | yes | reverse rendezvous ❌ |
-| [`bridge_status`](#bridge_status) | either | no | `AgentControl.status` ✅ · `Injector.activeTargets` ✅ |
-| [`bridge_spawn`](#lifecycle) | primary | no | `WorkerService.spawn` ✅ (`POST /workers`) |
-| [`bridge_list`](#lifecycle) | either | no | `WorkerService.list` ✅ (`/agents`) |
-| [`bridge_stop`](#lifecycle) | primary | no | `WorkerService.stop` ✅ (`DELETE /workers/{paneId}`) |
-| [`bridge_read`](#bridge_read) | primary | no | `AgentControl.read` ✅ |
-| [`bridge_cancel`](#bridge_cancel) | primary | no | — ❌ (future) |
-
-### Core: delegation & rendezvous
-
-#### `bridge_send`
-*(primary → worker — the headline tool, CB-104)*
-
-- **Params:** `message` (required); `target` (optional — defaults to the sole worker / default
-  profile); `timeout_seconds` (default 600); `block` (default `true`); `auto_spawn`
-  (default `true`); `turn_id` (optional — supplied when answering a worker's `bridge_ask`).
-- **Blocking (`block:true`):** enqueue `message` via the `Injector`, then hold the call open
-  until exactly one of:
-  - worker calls `bridge_reply` → `{ outcome:"reply", text }`
-  - worker calls `bridge_ask` → `{ outcome:"question", text, turn_id }`
-  - worker's `agent_status` reaches done/idle with no reply → `{ outcome:"turn_done", text:<terminal tail> }`
-  - deadline elapses → `{ outcome:"timeout" }`
-  - worker gone → error `worker_gone`
-- **Detached (`block:false`):** enqueue and return `{ outcome:"dispatched", dispatch_id }`
-  immediately. The eventual reply is injected into the primary's idle pane (§6.3), or drained
-  via `bridge_status` on a split-host primary.
-
-#### `bridge_reply`
-*(worker → primary)*
-
-- **Params:** `text` (required); `final` (default `true`).
-- **Behavior:** resolve the primary waiter registered against this worker with `text`. If no
-  waiter exists (detached delegation), `bridged` **injects the primary's idle pane** instead.
-  Returns `{ delivered:true, mode:"resolved"|"injected" }`. No `target` — identity is implicit.
-
-#### `bridge_ask`
-*(worker → primary — the reverse rendezvous)*
-
-- **Params:** `question` (required); `timeout_seconds`.
-- **Behavior:** blocks the *worker's* call. Surfaces the question to the primary (resolving its
-  open `bridge_send` with `outcome:"question"`, or injecting its pane). When the primary
-  answers — a `bridge_send` carrying the matching `turn_id` — that unblocks this call and
-  returns `{ answer }` to the worker, which continues **in the same turn**.
-
-### Worker lifecycle
-<a id="lifecycle"></a>
-Thin adapters over [`WorkerService`](1-Architecture) — parity with the existing REST routes.
-
-- **`bridge_spawn`** — `{ profile? }` → worker view (`sessionId`, `terminalId`, `paneId`,
-  `status`). Guard-checked; a boundary breach returns error `subscription_boundary` (the
-  REST `403`).
-- **`bridge_list`** — no params → all workers + `agent_status`. Read-only, either role.
-- **`bridge_stop`** — `{ target }` → tears down the pane and its dedicated tab. Idempotent.
-
-### Observability
-
-#### `bridge_status`
-*(either role — the README's 4th named tool)*
-
-- **Params:** `target?`.
-- **Behavior:** per-worker `agent_status`, queue depth (`Injector.activeTargets`), whether a
-  rendezvous is open, and ids. For the *calling* session it also reports/drains **pending
-  messages addressed to me** — the path a split-host primary's `Stop`-hook uses to wake and
-  collect replies without being injectable. Read-only, non-blocking.
-
-#### `bridge_read`
-*(primary)*
-
-- **Params:** `target`; `source` ∈ `visible | recent | recent_unwrapped | detection`.
-- **Behavior:** returns the worker's terminal text so the primary can peek at a *detached*
-  worker's progress. Adapter over `AgentControl.read`.
-
-### Control (future)
-
-#### `bridge_cancel`
-*(primary)*
-
-- **Params:** `target`. Interrupt the worker's current turn / abandon the rendezvous. No
-  backing code yet.
-
----
-
-## 6. Rendezvous flows
-
-### 6.1 Delegation — happy path
-
-One blocking call, zero polls.
+One blocking call, zero polls. The lead's call is held open by `fleetd` until the member answers.
 
 ```mermaid
 sequenceDiagram
-    participant P as Primary (Opus)
-    participant B as bridged (MCP + Injector)
+    participant P as "Lead (primary)"
+    participant B as "fleetd (MCP + Injector)"
     participant H as herdr
-    participant W as Worker (Claude)
+    participant W as "Member"
 
-    P->>B: bridge_send("do X", target=w) — blocks
-    B->>B: register waiter(w)
-    B->>H: agent.send(w, "do X")  (idle window)
-    H-->>W: prompt injected
-    W->>W: works the turn
-    W->>B: bridge_reply("result")
-    B->>B: resolve waiter(w)
-    B-->>P: { outcome:"reply", text:"result" }
+    P->>B: "fleet_send{sessionId, content} — blocks"
+    B->>B: "register waiter(sessionId)"
+    B->>H: "agent.send — only in an injectable window"
+    H-->>W: "prompt injected"
+    W->>W: "works the turn"
+    W->>B: "fleet_reply{content}"
+    B->>B: "resolve waiter"
+    B-->>P: "{ outcome: reply }"
 ```
 
-### 6.2 Clarification — reverse rendezvous (`bridge_ask`)
+**The cap that matters:** a blocking `fleet_send` is bounded by the *caller's own* MCP client
+timeout, about 60 seconds — not by the task. Anything slower than that must use the detached flow
+in §1.3, or the lead's call returns while the member is still working.
 
-The worker pauses mid-turn to ask; the primary answers; the worker resumes in the same turn.
+### 1.2 Clarification — reverse rendezvous
+
+The member pauses mid-turn to ask, the lead answers, and the member resumes **the same turn** with
+its context intact.
 
 ```mermaid
 sequenceDiagram
-    participant P as Primary
-    participant B as bridged
-    participant W as Worker
+    participant P as "Lead"
+    participant B as fleetd
+    participant W as "Member"
 
-    P->>B: bridge_send("do X", target=w) — blocks
-    B-->>W: "do X" (injected)
-    W->>B: bridge_ask("which config?") — worker blocks
-    B-->>P: { outcome:"question", text:"which config?", turn_id }
-    P->>B: bridge_send("config.yaml", target=w, turn_id) — blocks again
-    B-->>W: resolve bridge_ask → { answer:"config.yaml" }
-    W->>W: resumes same turn
-    W->>B: bridge_reply("done")
-    B-->>P: { outcome:"reply", text:"done" }
+    P->>B: "fleet_send{sessionId, content} — blocks"
+    B-->>W: "content injected"
+    W->>B: "fleet_ask{question} — member blocks"
+    B-->>P: "{ outcome: question, turnId }"
+    P->>B: "fleet_send{turnId, content} — answers THIS turn"
+    B-->>W: "fleet_ask returns the answer"
+    W->>W: "resumes the same turn"
+    W->>B: "fleet_reply{content}"
+    B-->>P: "{ outcome: reply }"
 ```
 
-### 6.3 Detached delegation — pane injection
+**Answer with `turnId`, never `sessionId`.** A `sessionId` send starts a new turn; it does not
+resolve the waiting `fleet_ask`.
 
-The primary does not block; the reply arrives later in its idle pane.
+**The window is about 55 seconds and no nudge extends it.** So never brief a member to "ask me":
+decide before delegating, or give the member an explicit default to fall back on.
+
+### 1.3 Detached delegation — the lead does not block
+
+The lead gets a ticket immediately and collects the answer later. This is the flow for any real
+task, because of the ~60s cap in §1.1.
 
 ```mermaid
 sequenceDiagram
-    participant P as Primary
-    participant B as bridged
-    participant W as Worker
+    participant P as "Lead"
+    participant B as fleetd
+    participant W as "Member"
 
-    P->>B: bridge_send("do X", target=w, block=false)
-    B-->>P: { outcome:"dispatched", dispatch_id }
-    P->>P: continues its own work
-    W->>B: bridge_reply("result")
-    Note over B: no waiter → detached path
-    B->>B: Injector.enqueue(primary_pane, "result")
-    B-->>P: injected into idle pane (status-gated)
+    P->>B: "fleet_send{sessionId, content, wait:false}"
+    B-->>P: "accepted — ticket"
+    P->>P: "continues its own work"
+    W->>B: "fleet_reply{content}"
+    Note over B: "no waiter is blocked — the reply is held"
+    B->>B: "nudge the lead's own pane (status-gated)"
+    P->>B: "fleet_poll{ticket}"
+    B-->>P: "the member's report"
+    P->>B: "fleet_ack{target, msgId}"
 ```
 
-### 6.4 Uncooperative worker — turn-done fallback
+A terminal ticket nudges the lead's pane by itself, so a detached task does not need watching. The
+nudge needs an injectable lead pane and is capped, so it is a convenience rather than a guarantee.
 
-A worker that never calls `bridge_reply` still returns a result: `bridged` reads its terminal
-tail when the turn completes.
+### 1.4 The member never replies — turn-done fallback
+
+A member that ends its turn without `fleet_reply` still produces something: `fleetd` reads its
+pane tail. This is a **fallback, not a channel** — it is lossy in three separate ways, and every
+one of them has produced a wrong answer in practice.
 
 ```mermaid
 sequenceDiagram
-    participant P as Primary
-    participant B as bridged
-    participant W as Worker
+    participant P as "Lead"
+    participant B as fleetd
+    participant W as "Member"
 
-    P->>B: bridge_send("do X", target=w) — blocks
-    B-->>W: "do X" (injected)
-    W->>W: works, never calls bridge_reply
-    B->>B: StatusPoller sees agent_status → idle/done
-    B->>B: AgentControl.read(w, "recent")
-    B-->>P: { outcome:"turn_done", text:<terminal tail> }
+    P->>B: "fleet_send — blocks or detaches"
+    B-->>W: "content injected"
+    W->>W: "works, never calls fleet_reply"
+    B->>B: "StatusPoller sees the turn end"
+    B->>B: "read the pane tail"
+    B->>B: "classify: exhausted? echoed brief? real report?"
+    B-->>P: "{ outcome: turn_done } or a named failure"
 ```
 
+The three ways it goes wrong, and what each looks like now:
+
+| What happened | What the lead used to get | What it gets today |
+|---|---|---|
+| The report is longer than the scrape window | The **end** silently cut off | Still clipped, but marked partial |
+| The member never started — spent credential | The lead's **own brief** echoed back as a report | A named failure: backend exhausted |
+| The member is simply slow | A tail of work in progress | Unchanged — read it as a hint, not a result |
+
+The echoed-brief case is the one to remember: it reads as a long, on-topic report with nothing in
+it from the member. It is suppressed now, but the general rule stands — **check the member's
+worktree with `git log` before believing a report you did not watch arrive.**
+
 ---
 
-## 7. Status gating
+## 2. Status gating
 
-Delivery only happens in a safe window. This is the state machine the `Injector` already
-enforces via `AgentStatus.injectable()`; MCP `bridge_send` is simply its producer.
+Delivery only happens in a safe window. `fleet_send` is a producer for the `Injector`, which
+already enforces this through `AgentStatus.injectable()`.
 
 ```mermaid
 stateDiagram-v2
     [*] --> IDLE
-    IDLE --> WORKING: message delivered / picks up
-    WORKING --> IDLE: turn done
-    WORKING --> BLOCKED: awaits input
-    BLOCKED --> WORKING: input delivered
-    IDLE --> UNKNOWN: detection glitch
-    BLOCKED --> UNKNOWN: detection glitch
-    UNKNOWN --> IDLE: re-detected
+    IDLE --> WORKING: "message delivered, picked up"
+    WORKING --> IDLE: "turn done"
+    WORKING --> BLOCKED: "awaits input"
+    BLOCKED --> WORKING: "input delivered"
+    IDLE --> UNKNOWN: "detection glitch"
+    BLOCKED --> UNKNOWN: "detection glitch"
+    UNKNOWN --> IDLE: "re-detected"
 
     note right of IDLE
         injectable — deliver head of FIFO
@@ -306,69 +172,17 @@ stateDiagram-v2
     end note
 ```
 
-At most one message is delivered per turn: after a send the `Injector` waits for a `WORKING`
-pickup before delivering the next, with a `PICKUP_GRACE_POLLS` fallback for turns faster than
-the poll interval. A herdr `events.subscribe` stream can later replace the sampling without
-touching this state machine.
+**At most one message per turn.** After a send, the `Injector` waits for a `WORKING` pickup before
+delivering the next, with a grace-poll fallback for turns that finish faster than the poll
+interval.
 
----
+Two consequences a lead feels directly:
 
-## 8. Error model
+- **A second send to a busy member never lands.** It reports as queued and times out. The member
+  is fine; the message simply waits, and then restarts the member when it next goes idle.
+- **A spawned member is not deliverable until it has mounted the MCP.** Until then a send waits on
+  that gate for about 60 seconds and then fails without ever reaching the pane.
 
-| Condition | `bridge_send` result | Notes |
-|---|---|---|
-| Worker replies | `{ outcome:"reply" }` | normal |
-| Worker asks | `{ outcome:"question", turn_id }` | answer with `bridge_send(turn_id)` |
-| Turn ends, no reply | `{ outcome:"turn_done" }` | terminal tail as text |
-| Deadline elapsed | `{ outcome:"timeout" }` | message may still be queued/delivered |
-| Worker vanished | error `worker_gone` | `Injector.drop` fails the queued future |
-| Guard breach on spawn | error `subscription_boundary` | REST `403` parity |
-| Delivery failed at herdr | error, message dropped | poisoned message not left blocking the FIFO |
-
-`bridge_reply` from a worker with no open waiter is **not** an error — it falls through to
-detached pane injection (§6.3).
-
----
-
-## 9. Mapping to existing code
-
-The MCP face is a thin adapter layer; nearly every capability already exists behind the REST
-seam. Only the **rendezvous registry** and the **caller-identity resolver** are new.
-
-| MCP tool | Existing collaborator | New work |
-|---|---|---|
-| `bridge_send` | `Injector.enqueue`, `AgentControl.send` | waiter registry, timeout, outcome mux (CB-104) |
-| `bridge_reply` / `bridge_ask` | `Injector` (pane injection) | reverse rendezvous, identity resolver |
-| `bridge_status` | `AgentControl.status`, `Injector.activeTargets` | pending-drain projection |
-| `bridge_spawn` / `list` / `stop` | `WorkerService.{spawn,list,stop}` | MCP adapter only |
-| `bridge_read` | `AgentControl.read` | MCP adapter only |
-
-Because the REST routes in `BridgedApp` already exercise the collaborators, MCP tools are
-validated by **parity** against those routes, not by re-testing behavior.
-
----
-
-## 10. Open decisions
-
-1. **`bridge_ask` direction.** This page defines it as *worker-asks-primary* (a genuine reverse
-   channel, matching the "inject the primary's pane" language). The alternative — a synonym for
-   a blocking primary→worker send — is weaker and produces different plumbing. **Recommend
-   worker-asks-primary.**
-2. **Detached delivery shape.** A `block:false` param on `bridge_send` (keeps the catalog
-   small) vs. a separate `bridge_dispatch` tool. **Recommend the param.**
-3. **Auto-spawn on send.** `bridge_send` provisions a worker per profile when none exists
-   (simplest primary UX) vs. requiring an explicit `bridge_spawn` first. **Recommend
-   auto-spawn, defaulting on.**
-4. **Transport & SDK.** Streamable-HTTP/SSE co-located with the REST bind (recommended) vs.
-   stdio. Requires choosing a Java MCP server SDK and adding it to the pom.
-
----
-
-## 11. Implementation staging
-
-- **CB-104** — blocking `bridge_send` + rendezvous registry + caller-identity resolver
-  (the producer that finally drives the inert `StatusPoller`).
-- **CB-1xx** — `bridge_reply` / `bridge_ask` reverse rendezvous + detached pane injection.
-- **CB-1xx** — lifecycle + observability adapters (`bridge_spawn/list/stop/status/read`).
-- **CB-1xx** — transport wiring + `claude mcp add` docs; parity tests vs. REST.
-- **Later** — `bridge_cancel`; swap `StatusPoller` for herdr `events.subscribe`.
+`UNKNOWN` is deliberately neither injectable nor a pickup. A pane whose status cannot be read is
+not a pane that is safe to write to — see fleetd #176 for what happens when a gate treats an
+unreadable pane as a ready one.

docs/RELEASE-NOTES-1.0.0.md

@@ -0,0 +1,119 @@
+# v1.0.0 — One leader, one host, complete
+
+This is the first release of **`fleetd`**.
+
+`fleetd` lets one main Claude Code session (the **leader**, on your Pro/Max subscription)
+run a team of **workers** — extra Claude Code sessions on a cheaper or local model, and
+non-Claude agents too. The leader's own session is never touched: it stays on subscription,
+with a clean environment.
+
+**This release finishes a full scope — it does not stop halfway.** The scope is *one leader
+on one machine*, running many workers. Everything that setup needs is now built, tested, and
+used daily: who-is-who, the subscription line, messages in both directions, worker start and
+stop, security, and monitoring. Nothing on the single-machine path is left as a known gap.
+
+This is also how the code is shaped: `PrimaryRegistry` holds exactly **one** leader. Running
+across many machines is the next big step (see *What comes next* below) — not a missing piece
+of this one.
+
+## One gateway for all messages
+
+- **Everyone talks through the same door.** The leader and every worker connect to the same
+  MCP server and use only its tools: `fleet_whoami` · `fleet_profiles` · `fleet_spawn` ·
+  `fleet_list` · `fleet_status` · `fleet_send` · `fleet_reply` · `fleet_ask` ·
+  `fleet_poll` · `fleet_ack` · `fleet_stop`.
+- **You are who your connection says you are.** The bridge finds out who is calling from the
+  connection itself, never from a name the caller sends. So a worker cannot pretend to be
+  someone else, and `fleet_whoami` tells each agent its own role — no guessing.
+- **The subscription line cannot be crossed.** Only a spawned worker gets
+  `ANTHROPIC_BASE_URL`; the leader never does. Each worker profile has a list of allowed
+  model hosts, checked before anything starts.
+- **Messages wait for the right moment.** The bridge sends one message per turn, only when
+  the other side is ready — no hammering a busy agent.
+
+## Worker lifecycle
+
+- **Start → work → stop.** Each worker gets its own git worktree (its own copy of the repo)
+  with the same setup as the leader — `CLAUDE.md`, skills, hooks — so it commits on its own
+  branch and opens its own PR. Ready-made playbooks ship in the repo:
+  `.claude/skills/implementer` and `.claude/skills/reviewer`.
+- **Fast failure, not a silent hang.** Starting a worker waits until it is really connected.
+  If it never connects, you get a clear error (`PeerUnreachableException`) instead of a stuck
+  send.
+- **Workers don't live forever.** Idle workers are cleaned up (`idle_ttl`), long sessions have
+  a turn limit (`context_cap`), shutdown drains work first, and workers left behind by an old
+  daemon are found and removed at startup.
+- **Predictable placement.** Each worker gets its own tab in a shared worker space, in the
+  same order every time.
+
+## No reply gets lost
+
+MCP only lets the client call the server, so the bridge could push to a worker but the leader
+had to ask for its replies. That gap is now closed on a single machine:
+
+- **Replies are kept, never dropped.** If a reply arrives and nobody is waiting, the bridge
+  holds it until the leader picks it up.
+- **Replies can survive a restart.** With a broker (LavinMQ or RabbitMQ) set up, held replies
+  live on the broker, so a daemon restart does not lose them — they come back, and repeats are
+  filtered out by `msgId`. No `broker:` in the config → replies are held in memory instead.
+- **The leader gets a tap on the shoulder.** When a reply lands, the bridge nudges the
+  leader's own pane — only when the leader is free, and only a few times. If the leader is on
+  another machine, this quietly falls back to pick-up mode; the reply still waits.
+- **Workers can ask questions.** With `fleet_ask`, a worker can pause mid-task, ask the
+  leader something, and continue the *same* task with the answer.
+
+## More than one kind of worker
+
+Workers are started through a small plug-in interface (`PeerLauncher`). Two plug-ins ship:
+one for Claude Code and one for **opencode** (tested live against opencode 1.18.5). The
+opencode one proves the interface is neutral — it uses nothing Claude-specific. Each worker
+only sees the tools its own launcher gives it.
+
+## Security & operations
+
+- **Auth.** Default is `loopback-trust`: only same-machine callers are trusted. Or set a
+  bearer `token`. Unknown callers count as `ANONYMOUS` — nobody is trusted by accident. If
+  the config would expose the daemon to the network without a token, it **refuses to start**.
+  Workers never need the token, so turning auth on cannot lock them out.
+- **Rules + audit log.** The role rules are checked on both doors (REST and MCP). A worker
+  may only act as itself. The audit log is JSON and never contains message text.
+- **Monitoring.** `/healthz` for liveness, `/metrics` for Prometheus — no extra libraries.
+- **Runs as a service.** launchd (macOS) and systemd (Linux) files are included. If herdr
+  isn't up yet at boot, the daemon waits up to 30 seconds and then runs in a reduced mode
+  instead of crash-looping.
+- **CI.** Every push builds and tests on the Gitea runner, including the broker test against
+  a real broker. Only the live-herdr test stays local (`-Pcontract`).
+
+## What you need
+
+Java 25 · Maven · **herdr 0.8.0 (protocol 19)** · optionally LavinMQ or RabbitMQ for
+restart-proof replies · macOS (launchd) or Linux (systemd). For TLS, put a reverse proxy in
+front — the daemon does not do TLS itself, by design.
+
+## Tested
+
+`mvn clean install` is green at `84081b2`: **399 tests**, coverage **75.6%** of instructions /
+**64.5%** of branches. Live end-to-end runs under `e2e/`: a worker asking the leader a
+question, one leader running several workers at once on a bug hunt, and a 30-turn
+back-and-forth conversation. The bridge is used on itself — worker-run code reviews have led
+to real committed fixes in this repo.
+
+## What comes next
+
+The single-machine story is done. The next big step stretches the same rules across machines:
+
+- **Many machines (CB-308).** A leader on machine A with workers on machines B and C — built
+  on this release's broker layer, with one gateway per machine. The design is written
+  (`docs/CB-308-Multi-Host-Federation.md`); the open question is trust between machines.
+- **Many leaders.** Today the bridge holds exactly one leader. The next idea is a small
+  council — for example one Claude and one Codex — that can discuss a problem together,
+  compare answers, and agree on a decision before the work is handed to workers. This needs
+  leader-to-leader messages and a simple way to settle disagreement, neither of which exists
+  yet.
+- **Third-party launcher plug-ins.** Loading launcher plug-ins from outside the project needs
+  a trust model first, because a launcher runs with daemon rights and can hand secrets to
+  workers.
+
+One thing we chose **not** to build, so it isn't read as a gap: the originally planned heavy
+message envelope (CB-201). Connection identity already routes every reply to the right place,
+so only a small `QUESTION` message kind and a `turn_id` were added.

docs/Team.md

@@ -1,9 +1,9 @@
 # Team — lead orchestrating a mixed Claude + local-LLM fleet
 
-The message server (`bridged`) delivers **one turn into one worker**. A **team** is the
+The message server (`fleetd`) delivers **one turn into one worker**. A **team** is the
 layer above it: a **Claude team-lead** that fans a job out across a **mixed fleet** of
 workers — some on Claude, some on the remote local LLM — and reduces their replies. Same
-`bridged` delivery, same subscription boundary; this doc is only about **orchestration** —
+`fleetd` delivery, same subscription boundary; this doc is only about **orchestration** —
 who the workers are, how the lead picks one, and how it runs many at once.
 
 > Delivery mechanics (blocking `POST /message`, status-gated reply envelope) live in the
@@ -12,12 +12,12 @@ who the workers are, how the lead picks one, and how it runs many at once.
 ## The team
 
 - **Team-lead** — the primary **Opus** (Claude Code, env **CLEAN**, on Pro/Max). Not a
-  worker; a **thin client of `bridged`**. It plans, routes, dispatches, and integrates, and
+  worker; a **thin client of `fleetd`**. It plans, routes, dispatches, and integrates, and
   never sets `ANTHROPIC_BASE_URL`.
-- **Workers** — a herd of `claude` panes in herdr, each an addressable `bridged` session
+- **Workers** — a herd of `claude` panes in herdr, each an addressable `fleetd` session
   with its **own model/env**:
   - **Claude workers** (clean env, e.g. Sonnet) — reasoning-heavy or high-accuracy subtasks.
-  - **Local workers** (`ANTHROPIC_BASE_URL=https://ollama.ltms.dev`) — bulk, cheap, or
+  - **Local workers** (`ANTHROPIC_BASE_URL=https://llm.ltms.dev/anthropic`) — bulk, cheap, or
     embarrassingly parallel subtasks.
 
 Every worker is still a *real Claude Code process* (inherits `CLAUDE.md`, hooks, skills,
@@ -28,14 +28,14 @@ MCP) — only its model differs. Scale each kind horizontally by adding panes.
 ```mermaid
 flowchart TB
     LEAD["lead — Opus<br/>(Claude Code, env CLEAN)"]
-    BD["bridged<br/>message server + router"]
+    BD["fleetd<br/>message server + router"]
     HERDR["herdr<br/>panes · agent-status"]
     WC1["w-claude-1<br/>Sonnet · CLEAN"]
     WC2["w-claude-2<br/>Sonnet · CLEAN"]
     WL1["w-local-1<br/>ANTHROPIC_BASE_URL set"]
     WL2["w-local-2<br/>ANTHROPIC_BASE_URL set"]
     ANT["api.anthropic.com<br/>(Pro/Max)"]
-    OLL["ollama.ltms.dev<br/>(local model)"]
+    OLL["llm.ltms.dev<br/>(gateway to the local model)"]
 
     LEAD -->|"blocking POST /message (target role)"| BD
     BD -->|"Unix socket · send_text · events.subscribe"| HERDR
@@ -62,14 +62,14 @@ flowchart TB
 | `w-local-*` | `ANTHROPIC_BASE_URL` set | local LLM | task is bulk / cheap / embarrassingly parallel |
 
 The lead applies this rubric itself, guided by its `CLAUDE.md` team charter (below). Worker
-selection is **policy in the lead**, not a `bridged` concern — `bridged` just delivers to
+selection is **policy in the lead**, not a `fleetd` concern — `fleetd` just delivers to
 the session the lead names.
 
 ## Subscription boundary in a team
 
 Unchanged from the base architecture, and it scales with the fleet: **only local-worker
 panes** launch with `ANTHROPIC_BASE_URL`. The lead and every Claude worker stay env-clean on
-the subscription. `bridged` enforces which panes may carry the off-subscription env, so
+the subscription. `fleetd` enforces which panes may carry the off-subscription env, so
 adding workers never widens the boundary.
 
 ## Parallel fan-out (map / reduce)
@@ -80,7 +80,7 @@ different workers at once, then results are gathered.
 ```mermaid
 sequenceDiagram
     participant L as lead (Opus)
-    participant B as bridged
+    participant B as fleetd
     participant WC as w-claude-1
     participant WL as w-local-1
 
@@ -100,26 +100,26 @@ sequenceDiagram
 ```
 
 - **Map:** the lead issues N concurrent blocking `POST /message` calls (one per subtask → its
-  chosen worker). Each call blocks only *that* request; `bridged` holds it open until the
+  chosen worker). Each call blocks only *that* request; `fleetd` holds it open until the
   worker's turn completes (status-gated) and returns the reply envelope.
 - **Reduce:** the lead collects the N envelopes and integrates. A slow local worker never
   blocks a fast Claude worker — wall-clock ≈ the slowest single subtask, not the sum.
 - **Detached / long jobs** use the async broker path instead of a held request (Channel 2 in
   the base architecture), so the lead never busy-polls across turns.
 
-Fan-out is bounded by the herd size (pane count) and `bridged`'s concurrency policy, not by
+Fan-out is bounded by the herd size (pane count) and `fleetd`'s concurrency policy, not by
 the lead.
 
 ## Knowing the roster
 
-The lead discovers its team from `bridged` (session list / roles) rather than hard-coding
+The lead discovers its team from `fleetd` (session list / roles) rather than hard-coding
 pane ids, so workers can be added or restarted without editing the lead. A minimal charter
 in the lead's `CLAUDE.md` turns Opus into the orchestrator:
 
 ```markdown
-## Your team (via bridged)
-You are the team-lead. Delegate through the bridged client — never launch workers yourself.
-Roster: ask bridged for current sessions/roles.
+## Your team (via fleetd)
+You are the team-lead. Delegate through the fleetd client — never launch workers yourself.
+Roster: ask fleetd for current sessions/roles.
 - w-claude-* — Claude Sonnet. Reasoning-heavy / high-accuracy subtasks.
 - w-local-*  — remote local LLM. Bulk, cheap, or parallelizable subtasks.
 
@@ -133,22 +133,22 @@ tool instead of hand-rolling the HTTP request.
 
 ## What this layer does NOT change
 
-- **Delivery** is still `bridged` → herdr `pane.send_text` + status events (Message-Server).
+- **Delivery** is still `fleetd` → herdr `pane.send_text` + status events (Message-Server).
 - **Completion timing** is still the worker status event; **reply content** still rides the
   worker `Stop`-hook envelope.
 - **Single-host** still applies: herdr's socket is local, so the whole herd lives on the
-  `bridged` host. The lead may be remote — it only needs HTTP to `bridged`.
+  `fleetd` host. The lead may be remote — it only needs HTTP to `fleetd`.
 
 ## Open questions
 
-- **Routing intelligence:** rubric-in-`CLAUDE.md` (lead decides) vs. a `bridged` role-router
+- **Routing intelligence:** rubric-in-`CLAUDE.md` (lead decides) vs. a `fleetd` role-router
   (label-based). Start with the former; promote to the latter if routing logic grows.
-- **Backpressure:** per-role concurrency caps in `bridged` so a fan-out can't exhaust the
+- **Backpressure:** per-role concurrency caps in `fleetd` so a fan-out can't exhaust the
   local gateway.
 - **Result schema:** whether reply envelopes should carry structured metadata (worker, model,
   tokens) to help the lead's reduce step.
 
 ## Status
 
-🟡 Design (2026-07-11). Orchestration layer over the selected `bridged` server; inherits
+🟡 Design (2026-07-11). Orchestration layer over the selected `fleetd` server; inherits
 herdr (chosen) + AgentAPI (fallback). Delivery unchanged — see the Message-Server design.

docs/Worker-Git-Workflow.md

@@ -20,7 +20,7 @@ requirement, not a nice-to-have.**
 - **Worktree provisioned by the daemon** — `SessionManager` creates a dedicated git worktree +
   branch per session, **hydrates it to full config parity** (below), and tears it down on release.
 - **Worker opens its own PR** — the worker commits, pushes its branch, and opens the PR/MR itself,
-  returning the PR URL in its `bridge_reply`.
+  returning the PR URL in its `fleet_reply`.
 
 ## Why worktrees (the hazard being fixed)
 
@@ -76,7 +76,7 @@ worktree checks out anyway. Amber is the real gap — untracked local config the
 3. **Never overlay the git plumbing** — the worktree's own `.git` file/branch is what gives
    isolation; that's the *one* thing that must differ from the main tree.
 
-The overlay set lives in config (`BridgedConfig.Worker.parityOverlay` — a list of repo-relative
+The overlay set lives in config (`FleetConfig.Worker.parityOverlay` — a list of repo-relative
 paths, with sane defaults) so it's auditable and per-repo tunable.
 
 > **Trust note (deliberate).** Hydrating local config means the primary's local secrets/tokens
@@ -103,7 +103,7 @@ sequenceDiagram
     Note over W: implement in the isolated worktree
     W->>G: git commit + git push (SSH, same user)
     W->>G: open PR (branch to main)
-    W-->>P: bridge_reply (prUrl, branch, summary, tests)
+    W-->>P: fleet_reply (prUrl, branch, summary, tests)
     P->>SM: release(paneId)
     SM->>G: git worktree remove wt
     Note over G: branch + PR persist for review/merge
@@ -115,9 +115,9 @@ earlier `STATE.md` idea — a PR is reviewable, mergeable, and self-describing.*
 
 ## Infra facts (verified this session)
 
-- **Remote:** `ssh://git@git.ltms.dev:2224/lms/claude-bridge.git` (gitea). Push is over **SSH** —
+- **Remote:** `ssh://git@git.ltms.dev:2224/fleet/fleetd.git` (gitea). Push is over **SSH** —
   a worker running as the same user with the same keys can `git push` **with no extra credential**.
-- **gitea is NOT in the project `.mcp.json`** (only `jetbrains`, `intellij-index`, `bridged`). The
+- **gitea is NOT in the project `.mcp.json`** (only `jetbrains`, `intellij-index`, `fleetd`). The
   primary's gitea MCP comes from a global/user config, so **workers do not inherit it**. A worker
   gets only the `bridge` MCP mounted (via `--mcp-config` launch flag).
 - **No gitea CLI** (`tea`) installed; `glab` is present but is the GitLab CLI (wrong backend).
@@ -128,7 +128,7 @@ earlier `STATE.md` idea — a PR is reviewable, mergeable, and self-describing.*
 
 | Option | Mechanism | Trade-off |
 |---|---|---|
-| **A. gitea REST + token** | Worker `curl`s `POST /api/v1/repos/lms/claude-bridge/pulls` with a scoped token injected by the daemon into the worker env | Minimal, no new server; token lives in the off-subscription worker's env (scope it tightly) |
+| **A. gitea REST + token** | Worker `curl`s `POST /api/v1/repos/fleet/fleetd/pulls` with a scoped token injected by the daemon into the worker env | Minimal, no new server; token lives in the off-subscription worker's env (scope it tightly) |
 | **B. mount gitea MCP into workers** | Add the gitea MCP to the worker's `--mcp-config` alongside `bridge` | Clean tool call, but the gitea MCP's own auth/token must be provisioned per worker; more moving parts |
 | **C. install `tea` CLI** | Worker runs `tea pr create` with a token | Another dependency to install + configure; same token question as A |
 
@@ -140,7 +140,7 @@ and the token is a single scoped secret the daemon injects like it already injec
 
 - Off-subscription workers already *could* push (SSH, same user). The **incremental grant is
   PR-create**, i.e. a gitea API token.
-- Scope the token **minimally**: the `lms/claude-bridge` repo, `write:repository` (create branch +
+- Scope the token **minimally**: the `fleet/fleetd` repo, `write:repository` (create branch +
   PR), **not** merge/admin/org. A leaked token can open PRs, not merge them — the primary/human is
   still the merge gate.
 - Inject via the daemon (env var, e.g. `GITEA_TOKEN`), never written to the worker's config dir —
@@ -153,11 +153,11 @@ and the token is a single scoped secret the daemon injects like it already injec
 |---|---|---|
 | Worktree provision/teardown | **CB-301 ext** — `SessionManager.acquire`/`release`; `WorkerSession` gains `worktree`, `branch` | daemon shells out to `git worktree add/remove` |
 | **Config-parity overlay** | **CB-301 ext** — `SessionManager.acquire`, after `git worktree add` | symlink/copy the `parityOverlay` set into the worktree so the worker is a full peer; **this is what makes worktrees viable, not a dead-end** |
-| Overlay config | `BridgedConfig.Worker.parityOverlay` — repo-relative paths, sane defaults | auditable, per-repo tunable; keep explicit + minimal (trust) |
+| Overlay config | `FleetConfig.Worker.parityOverlay` — repo-relative paths, sane defaults | auditable, per-repo tunable; keep explicit + minimal (trust) |
 | Branch naming | `worker/<ticket-slug>-<nonce>` off `main` (or a configured base) | one branch per session |
 | Commit + push + PR handoff | **CB-302** — worker-driven, guided by the skill | push = SSH; PR = option A |
 | Implementer skill | `.claude/skills/implementer/SKILL.md` | worktree-aware playbook (see below); mounts automatically since workers inherit repo cwd |
-| gitea token injection | `WorkerService` env + `BridgedConfig` | repo-scoped, minimal perms |
+| gitea token injection | `WorkerService` env + `FleetConfig` | repo-scoped, minimal perms |
 | PR review + merge | Primary (has gitea MCP + judgment) | merge on green; the human/primary gate stays |
 
 ## Implementer skill (outline)
@@ -170,7 +170,7 @@ A worker-facing playbook (sibling to the existing `reviewer` skill):
 3. **Push** your branch (`git push -u origin HEAD`).
 4. **Open a PR** to `main` (option A `curl`, or the decided mechanism) with a title/body describing
    the change and referencing the ticket.
-5. **Reply** via `bridge_reply` with the **PR URL**, branch name, files changed, and test names —
+5. **Reply** via `fleet_reply` with the **PR URL**, branch name, files changed, and test names —
    that reply is the whole handoff.
 6. Do **not** merge; do **not** touch `.mcp.json` or `wiki/`.
 

docs/Worker-Startup-and-Trust.md

@@ -1,6 +1,6 @@
 # Worker startup: working directory & the folder-trust prompt
 
-When `bridged` spawns a worker, the worker CLI may show an **interactive startup prompt** before it
+When `fleetd` spawns a worker, the worker CLI may show an **interactive startup prompt** before it
 is ready to accept a task — most importantly a *"Do you trust the files in this folder?"* dialog. An
 unattended worker parked on that prompt never becomes injectable: the status-gated injector waits for
 `idle`/`blocked`, the task is never delivered, and (worst case) a stray Enter answers the dialog
@@ -14,11 +14,11 @@ rule that **a worker inherits the primary's directory** (never `$HOME`), and how
 
 ```mermaid
 flowchart TD
-    A["bridge_spawn / POST /workers"] --> B{"explicit cwd?<br/>(profile cwd or spawn arg)"}
+    A["fleet_spawn / POST /workers"] --> B{"explicit cwd?<br/>(profile cwd or spawn arg)"}
     B -->|"yes — told otherwise"| C["use that cwd"]
     B -->|"no"| D{"caller PID resolvable?<br/>(MCP peer PID)"}
     D -->|"yes"| E["cwd = the primary's cwd<br/>lsof -a -p PID -d cwd"]
-    D -->|"no (REST / off-host)"| F["cwd = bridged daemon cwd<br/>(never $HOME by assumption)"]
+    D -->|"no (REST / off-host)"| F["cwd = fleetd daemon cwd<br/>(never $HOME by assumption)"]
     C --> G["ensureWorkspace → tab.create → agent.start {cwd}"]
     E --> G
     F --> G
@@ -51,10 +51,10 @@ only affect the seed shell, which the bridge closes).
 | # | Source | When |
 |---|--------|------|
 | 1 | Explicit `cwd` — a per-profile `cwd:` in config, or a spawn argument | "told otherwise" — pin a fixed workdir |
-| 2 | The **primary's cwd**, auto-detected from the `bridge_spawn` caller | normal MCP spawn from the primary |
-| 3 | The `bridged` daemon's own cwd | REST spawn / off-host caller — **never `$HOME`** |
+| 2 | The **primary's cwd**, auto-detected from the `fleet_spawn` caller | normal MCP spawn from the primary |
+| 3 | The `fleetd` daemon's own cwd | REST spawn / off-host caller — **never `$HOME`** |
 
-The primary's cwd (source 2) is discoverable with no new plumbing: `bridged` already resolves the MCP
+The primary's cwd (source 2) is discoverable with no new plumbing: `fleetd` already resolves the MCP
 caller's loopback **peer PID** for connection identity (`ConnectionIdentity` → `LsofPeerPidLookup`);
 the same PID yields its cwd via `lsof -a -p <pid> -d cwd -Fn` (the `n…` line). The primary maps to no
 worker pane (it is not a worker), but its PID and cwd are still readable.
@@ -62,10 +62,10 @@ worker pane (it is not a worker), but its PID and cwd are still readable.
 ```mermaid
 sequenceDiagram
     participant P as "Primary (main)"
-    participant B as "bridged"
+    participant B as "fleetd"
     participant O as "OS (lsof)"
     participant H as "herdr"
-    P->>B: "bridge_spawn {profile} (no cwd)"
+    P->>B: "fleet_spawn {profile} (no cwd)"
     B->>O: "peer PID for this connection's port"
     O-->>B: "pid"
     B->>O: "cwd of pid (lsof -d cwd)"
@@ -77,9 +77,9 @@ sequenceDiagram
 
 *Figure 2 — a no-cwd spawn inherits the primary's directory from the caller's PID.*
 
-> **Status:** implemented (CB-112). `bridged` threads the resolved `cwd` onto **`agent.start {cwd}`**
+> **Status:** implemented (CB-112). `fleetd` threads the resolved `cwd` onto **`agent.start {cwd}`**
 > (verified: the worker process is rooted there), keeping the single shared worker space. On an MCP
-> `bridge_spawn` the primary's cwd is auto-detected from the caller's PID; over REST (no MCP caller)
+> `fleet_spawn` the primary's cwd is auto-detected from the caller's PID; over REST (no MCP caller)
 > it is the explicit `cwd` param else the daemon's cwd. Both placements (`tab` and legacy `pane`)
 > carry it, since it rides `agent.start`.
 
@@ -133,5 +133,5 @@ unattended.
 
 ## See also
 
-- `docs/MCP-Contract.md` — the tool surface (`bridge_spawn`, `bridge_profiles`, …).
+- `docs/MCP-Contract.md` — the tool surface (`fleet_spawn`, `fleet_profiles`, …).
 - `wiki/2-Message-Server.md` — the herdr `agent.*` / `workspace.*` schema (`workspace.create {cwd}`).

docs/wiki-audit.md

@@ -0,0 +1,208 @@
+# Wiki audit for #168
+
+**Source checked:** `.wiki-snapshot/` at `68e32c6` (2026-08-31). I did not use
+`wiki/`. Code references below are from the current `fleetd` source tree. A quoted
+line is a concrete claim that needs correction, unless the table says `KEEP`.
+
+| Page | Verdict | One-line reason |
+|---|---|---|
+| `Home.md` | REVISE | Good overview, but it still names the retired product. |
+| `_Sidebar.md` | REVISE | The heading still says `claude-bridge`. |
+| `1-Architecture.md` | REBUILD | Its component contract mixes current names with removed tools, routes, and planned backends. |
+| `2-Message-Server.md` | REBUILD | The claimed MCP schema, mount command, REST/SSE surface, and fallback paths are pre-build design. |
+| `3-Approaches.md` | REVISE | Useful research history, but it presents unbuilt AgentAPI as a selectable fallback. |
+| `4-Setup.md` | RETIRE | It is an intentional stub that only redirects to chapter 13. |
+| `5-Operations.md` | RETIRE | It is an intentional stub that only redirects to chapter 13. |
+| `6-Team.md` | REBUILD | It teaches role-addressed sends and a Claude-only team model that the shipped API does not have. |
+| `7-Use-Cases.md` | REBUILD | Its flagship flow depends on removed `ccs` profiles and removed send parameters. |
+| `8-Roadmap.md` | REBUILD | It is a historical plan, but it presents old implementation choices and planned work as the current stack. |
+| `9-Implementation.md` | REBUILD | Its package, class, endpoint, and outcome map has drifted from the source. |
+| `10-Cross-Host-Messaging.md` | REVISE | It labels most federation work proposed, but misses the shipped `coordinator:` lead channel. |
+| `11-Features.md` | REVISE | It is the right catalogue, but code-path names are old and it misses the second-herdr-daemon capability. |
+| `12-Claude-to-OpenCode.md` | REVISE | The porting guide is mostly current, but calls the product and spawned-member path a bridge. |
+| `13-User-Guide.md` | REVISE | It is the best operator page, but needs the product rename and the second-herdr-daemon setup. |
+
+## Pages needing work
+
+### `Home.md` — REVISE
+
+- Quote: `# claude-bridge` (line 1) and `` `claude-bridge` keeps`` (line 11).
+  The product is `fleet` / `fleetd`. The MCP server identifies itself as `fleet` in
+  `fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java:313-315`.
+- Quote: `AgentAPI ... swappable fallback injector` (lines 73-76).
+  There is no AgentAPI implementation under `fleetd/src/main/java`; the actual
+  launchers are selected by `Profile.kind` in
+  `fleetd/src/main/java/dev/ltms/fleet/config/FleetConfig.java:265-270`.
+
+### `_Sidebar.md` — REVISE
+
+- Quote: `### 📖 claude-bridge` (line 1).
+  Rename it to `fleet`. `FleetMcp` registers the current product-facing tool set at
+  `fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java:301-326`.
+
+### `1-Architecture.md` — REBUILD
+
+- Quote: `` `claude-bridge` lets`` (line 3). The product was renamed; the MCP
+  server name is `fleet` (`FleetMcp.java:313-315`).
+- Quote: ``fleet_read`` in the tool list (line 102). No such tool is registered.
+  The complete registered list is `fleet_send` through `fleet_whoami` at
+  `FleetMcp.java:301-326`; `fleet_read` is absent.
+- Quote: `SSE (GET /events)` (line 143). `FleetApp.build()` registers no `/events`
+  route; its routes are listed at `FleetApp.java:143-159`.
+- Quote: `Redis Streams / NATS JetStream, or an embedded queue` (line 106).
+  The shipped durable inbox is AMQP, configured by `broker`, at
+  `FleetConfig.java:49-50` and `FleetConfig.java:655-714`.
+- Quote: `AgentAPI (fallback)` (line 107). No AgentAPI adapter exists; shipped
+  launcher kinds are `claude-code` and `opencode` (`FleetConfig.java:265-270`).
+
+### `2-Message-Server.md` — REBUILD
+
+- Quote: `claude mcp add --transport http bridge http://127.0.0.1:8080/mcp`
+  (line 67). The daemon defaults to port `8765` in `FleetConfig.java:183-187`,
+  and identifies its server as `fleet` at `FleetMcp.java:313-315`.
+- Quote: ``fleet_send(message, target?, {block, timeout_seconds, auto_spawn,
+  turn_id})`` (line 80). The real parameters are `sessionId`, `content`,
+  `timeoutMs`, `wait`, `turnId`, and `coordId` (`FleetMcp.java:1096-1108`).
+- Quote: ``fleet_read(target, source)`` (line 85). It is not registered; see the
+  complete registration at `FleetMcp.java:301-326`.
+- Quote: `docs/MCP-Contract.md ... normative` (lines 87-88). That is not a valid
+  reference: only §6 is current, as the current operator guide itself says at
+  `.wiki-snapshot/13-User-Guide.md:466`.
+- Quote: `SSE (GET /events)` (line 45). No route exists in the built REST surface,
+  `FleetApp.java:143-159`.
+
+### `3-Approaches.md` — REVISE
+
+- Quote: `AgentAPI ... remains a swappable fallback injector` (lines 78-84).
+  It was never built. The shipped adapter selection is only `claude-code` or
+  `opencode` (`FleetConfig.java:265-270`). Keep it as discarded research, not an
+  operational fallback.
+- Quote: `claude-bridge` (line 109). Rename the product to `fleet`; the runtime
+  package is `dev.ltms.fleet`, for example `FleetMcp.java:1`.
+
+### `4-Setup.md` — RETIRE
+
+It is a 25-line redirect and says its procedure was never written (lines 3-9).
+Chapter 13 is the maintained install procedure. Keeping a second navigation page
+adds no working documentation.
+
+### `5-Operations.md` — RETIRE
+
+It is a 35-line redirect and says its runbook was never written (lines 3-14).
+Chapter 13 now owns run and recovery instructions.
+
+### `6-Team.md` — REBUILD
+
+- Quote: `fleet_send {role: w-claude, prompt: A}` (line 98). `fleet_send` accepts
+  `sessionId` and `content`, not `role` or `prompt` (`FleetMcp.java:1096-1108`).
+- Quote: `some on Claude, some on the remote local LLM` (lines 3-5) and `Every
+  worker is ... Claude Code` (line 25). `opencode` is a first-class launcher kind,
+  not a Claude worker (`FleetConfig.java:265-270`).
+- Quote: `fleetd's concurrency policy` (line 121). The configured capacity control
+  is per-profile `maxLoad` (`FleetConfig.java:251-264`), not the role routing model
+  described here.
+
+### `7-Use-Cases.md` — REBUILD
+
+- Quote: `ccs profile` (line 10), `ccs + herdr` (line 22), and `ccs-spawn`
+  (line 45). The configuration has `profiles` and `fleet`, not `ccs`:
+  `FleetConfig.java:34-58` and `FleetConfig.java:81-101`.
+- Quote: `fleet_send({"to", "kind", "body", "block"})` (lines 55-62).
+  None of those are the shipped send parameters. The schema is
+  `FleetMcp.java:1096-1108`.
+- Quote: `fleet_list() → { "profiles": ... }` (lines 74-80). `fleet_list` is a
+  roster view; `fleet_profiles` is the configured-backend view, as registered at
+  `FleetMcp.java:307-311` and described at `FleetMcp.java:1176-1182`.
+
+### `8-Roadmap.md` — REBUILD
+
+- Quote: `Java 21+` (line 43). The current project guidance and source use Java 25;
+  the `FleetConfig` source itself uses Java 25 unnamed lambda parameters, for
+  example `FleetConfig.java:102`.
+- Quote: `herdr 0.7.0 / protocol 14` (line 46). The current REST health endpoint
+  reports the live protocol returned by herdr (`FleetApp.java:240-244`), while the
+  current operator guide records protocol 19 at
+  `.wiki-snapshot/13-User-Guide.md:76-85`.
+- Quote: `ccs <profile> claude` and `ccs env <profile>` (lines 47-48). Shipped
+  configuration uses `Profile` records and launcher `kind`,
+  `FleetConfig.java:313-330` and `FleetConfig.java:265-270`.
+- Quote: `Redis Streams via Lettuce` (line 50). The actual durable inbox is AMQP
+  `broker`, `FleetConfig.java:655-714`.
+
+### `9-Implementation.md` — REBUILD
+
+- Quote: `rest.FleetdApp` and `mcp.BridgeMcp` (lines 29-30). The classes are
+  `rest.FleetApp` and `mcp.FleetMcp` (`FleetApp.java:46`; `FleetMcp.java:67`).
+- Quote: `dev.ltms.fleetd` (line 67). The source package is `dev.ltms.fleet`
+  (`FleetMcp.java:1`).
+- Quote: `WorkerPresence` (line 110). The current class is `MemberPresence`, as
+  imported and used by `FleetMcp` at `FleetMcp.java:12` and `465-469`.
+- Quote: the outcome list ending in `STALE_TURN` (lines 128-131). The code also
+  has `BACKEND_EXHAUSTED` (`FleetMcp.java:550-554`) and async `ASKING` handling
+  (`FleetMcp.java:664-668`).
+- Quote: `FleetdApp` (line 207) and `FleetdConfig` (line 211). These names do not
+  resolve; current classes are `FleetApp` and `FleetConfig`.
+
+### `10-Cross-Host-Messaging.md` — REVISE
+
+- Quote: the chapter says the cross-host fabric is proposed except for the
+  single-host inbox (lines 3-8). Cross-host **lead-to-lead** delivery shipped:
+  `fleet_send` accepts `coordId` (`FleetMcp.java:1094-1107`) and publishes it at
+  `FleetMcp.java:616-641`; configuration has `coordinator` at
+  `FleetConfig.java:74-78` and `99-101`.
+- Quote: `bridge.dlx` (line 90). This product name is stale. The shipped lead path
+  uses `LeadChannel`, not the proposed exchange flow (`FleetMcp.java:95-96` and
+  `616-641`). Keep the proposed federation design, but add a clear shipped/proposed
+  boundary for CB-637.
+
+### `11-Features.md` — REVISE
+
+- Quote: `mcp/BridgeMcp` (line 22), `config/FleetdConfig` (lines 25-27), and other
+  index references. These paths no longer resolve; the source classes are
+  `mcp/FleetMcp` (`FleetMcp.java:67`) and `config/FleetConfig`
+  (`FleetConfig.java:81`).
+- Quote: `fleet_whoami` returns only `primary` or `worker` (lines 99-100).
+  It also returns `architect` (`FleetMcp.java:1235-1244`).
+- The page needs the missing separate member-herdr-daemon feature listed below.
+
+### `12-Claude-to-OpenCode.md` — REVISE
+
+- Quote: `same bridge mount` (line 5) and `a bridge-spawned worker` (line 94).
+  Rename the product path to `fleet`. The daemon exposes the MCP server as `fleet`
+  (`FleetMcp.java:313-315`), and profiles select OpenCode with `kind: opencode`
+  (`FleetConfig.java:332-335`).
+- Quote: the sample mount name is `fleetd` (line 67). The server name is `fleet`;
+  update the sample to avoid teaching a second product name.
+
+### `13-User-Guide.md` — REVISE
+
+- Quote: `The bridge is the only channel` (line 63). The invariant is correct, but
+  the product term needs the `fleet` rename. The daemon's MCP server name is
+  `fleet` (`FleetMcp.java:313-315`).
+- Quote: it describes one herdr socket (lines 72-85). It needs the optional
+  `memberHerdrSocket` setup and two-daemon health meaning. The config key is in
+  `FleetConfig.java:34-37`, and `/healthz` checks both daemons when configured at
+  `FleetApp.java:210-245`.
+
+## MISSING
+
+`11-Features.md` has a body section for **routing members through a separate herdr daemon**
+(`## memberHerdrSocket`, line 2174), but **no row in the index table** at the top of the page
+(lines 20-95). That table is how the page is meant to be read, so a capability absent from it is
+effectively undiscoverable. Lead note: this is my own omission — I added the section on 2026-08-31
+and did not add the matching row. Fixed in the wiki at `68e32c6`'s successor.
+
+The original audit stated the feature had no entry at all. That was wrong: the section exists. The
+gap is the index row. Recorded here rather than silently corrected, because the difference matters —
+"undocumented" and "documented but unindexed" are different jobs.
+
+Evidence for the feature itself: `FleetConfig.java:34-37` and `FleetApp.java:103-115`, `210-245`,
+and `247-263`.
+
+## Audit method and coverage
+
+I checked all 15 pages. I checked concrete tool, route, config, class, file, and
+product-name claims claim-by-claim on 11 pages: Home, Sidebar, 1, 2, 4, 5, 6, 7, 9,
+11, and 13. I skimmed the remaining four long historical or research pages (3, 8, 10,
+12), then checked their concrete claims that affect the verdict. This is an audit of
+the supplied snapshot, not a wiki rewrite.

e2e/README.md

@@ -2,11 +2,11 @@
 
 A standard, repeatable **live** end-to-end test of the two-way channel: it drives a real
 multi-turn conversation between a primary and an off-subscription worker **through the
-running `bridged` daemon**, captures the full transcript, and grades the channel.
+running `fleetd` daemon**, captures the full transcript, and grades the channel.
 
 This is the committed form of the ad-hoc channel test that discovered the CB-115 gaps
 (herdr `unknown` misclassification wedging delivery, dirty completion scrapes, and workers
-never calling `bridge_reply` in conversation). Run it after any change to the injector,
+never calling `fleet_reply` in conversation). Run it after any change to the injector,
 status handling, completion/failure paths, or the worker reply charter.
 
 ## What it exercises
@@ -20,7 +20,7 @@ construction** — it only calls the bridge's loopback REST face.
 ```mermaid
 sequenceDiagram
     participant T as conversation_test.py
-    participant B as bridged (REST)
+    participant B as fleetd (REST)
     participant W as worker (off-sub)
     T->>B: POST /workers  (spawn)
     T->>B: GET /sessions/{id}/status  (await ready)
@@ -28,7 +28,7 @@ sequenceDiagram
         T->>B: POST /sessions/{id}/message {wait:false}
         B-->>T: ticket
         B->>W: inject prompt (status-gated)
-        W-->>B: bridge_reply
+        W-->>B: fleet_reply
         T->>B: GET /tasks/{ticket}  (poll)
         B-->>T: done + reply
     end
@@ -37,7 +37,7 @@ sequenceDiagram
 
 ## Prerequisites
 
-- `bridged` is running (default REST on `http://127.0.0.1:8765`) with at least one worker
+- `fleetd` is running (default REST on `http://127.0.0.1:8765`) with at least one worker
   profile configured and its backend reachable.
 - herdr is up (the daemon needs it).
 - Python 3 (standard library only — no pip installs).
@@ -68,7 +68,7 @@ Per-turn grade:
 
 | Grade      | Meaning                                                              |
 |------------|---------------------------------------------------------------------|
-| `OK`       | delivered and resolved by an explicit `bridge_reply` (`source=reply`) |
+| `OK`       | delivered and resolved by an explicit `fleet_reply` (`source=reply`) |
 | `DEGRADED` | delivered and answered, but resolved via completion-scrape fallback |
 | `EMPTY`    | turn completed but the reply was empty                              |
 | `FAILED`   | the worker's turn ended in failure (`phase=failed`)                 |

e2e/conversation_sustained_test.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """Sustained back-and-forth bridge test — ONE primary, ONE worker, many dependent turns
-over a fixed wall-clock window (default 5 minutes), through the running `bridged` daemon.
+over a fixed wall-clock window (default 5 minutes), through the running `fleetd` daemon.
 
 Where conversation_test.py proves a handful of turns work and issue_hunt_test.py proves
 fan-out isolation, this proves the channel stays healthy under a *sustained, stateful*
@@ -24,7 +24,7 @@ Usage:
     --turn-timeout  per-turn max wait, seconds    (default 150)
     --keep-worker   do not stop the worker at the end
 
-Exit code: 0 if every turn in the window resolved via a clean bridge_reply with no channel
+Exit code: 0 if every turn in the window resolved via a clean fleet_reply with no channel
 break; 1 otherwise. A live per-turn log streams to stdout so the run can be watched.
 """
 import argparse
@@ -47,12 +47,12 @@ STEPS = [7, 3, 11, 5, 9, 4, 13, 6, 8, 2]
 RULES = (
     "Let's play a running-total game across several messages. The total starts at 0. "
     "In each message I'll tell you to add a number; keep the running total yourself and "
-    "reply via bridge_reply with ONLY the current total as a plain integer — no words, no "
+    "reply via fleet_reply with ONLY the current total as a plain integer — no words, no "
     "punctuation, just the number. Do not restate the arithmetic. First move: add {step}."
 )
-NEXT = ("Add {step}. Reply via bridge_reply with only the new running total.")
+NEXT = ("Add {step}. Reply via fleet_reply with only the new running total.")
 REANCHOR = ("Let's re-sync — the running total is {total}. Now add {step}. Reply via "
-            "bridge_reply with only the new running total.")
+            "fleet_reply with only the new running total.")
 
 
 def parse_int(reply):
@@ -142,15 +142,15 @@ def main():
     print("=" * 72)
     print(f"SUSTAINED CONVERSATION SUMMARY — 1 primary <-> 1 worker over {dur}s (~{dur/60:.1f} min)")
     print(f"  turns:            {turns}")
-    print(f"  clean bridge_reply exchanges: {oks + drifts}/{turns}   (channel breaks: {breaks})")
+    print(f"  clean fleet_reply exchanges: {oks + drifts}/{turns}   (channel breaks: {breaks})")
     print(f"  arithmetic correct (continuity held): {oks}/{turns}   (drifts: {drifts})")
     print(f"  latency:          avg {avg}s over {turns} turns")
     ok = breaks == 0 and turns >= 2
     if ok and drifts == 0:
-        print("  RESULT: PASS — every turn resolved via bridge_reply and the worker held the "
+        print("  RESULT: PASS — every turn resolved via fleet_reply and the worker held the "
               "running total across the whole window.")
     elif ok:
-        print(f"  RESULT: PASS (channel) — every turn resolved via bridge_reply for the full "
+        print(f"  RESULT: PASS (channel) — every turn resolved via fleet_reply for the full "
               f"window; {drifts} arithmetic drift(s) (worker recovered after re-anchor).")
     else:
         print("  RESULT: FAIL — the channel broke on at least one turn (see CHANNEL BREAK above).")

e2e/conversation_test.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 """Standard bridge conversation test — a multi-turn primary↔worker exchange through
-the running `bridged` daemon, fully captured, with automatic gap analysis.
+the running `fleetd` daemon, fully captured, with automatic gap analysis.
 
 This is the repeatable form of the ad-hoc channel test that surfaced the CB-115 gaps
 (herdr `unknown` misclassification, dirty completion scrape, workers not calling
-bridge_reply). It drives a real off-subscription worker over the live gateway exactly
+fleet_reply). It drives a real off-subscription worker over the live gateway exactly
 as a primary Opus session would (async fire-and-poll), records every turn, and grades
 the channel.
 
@@ -130,9 +130,9 @@ def grade(rec):
     phase, source, reply = rec["phase"], rec["source"], rec["reply"]
     has_reply = bool(reply and reply.strip())
     if phase == "done" and source == "reply" and has_reply:
-        return "OK", "clean explicit bridge_reply"
+        return "OK", "clean explicit fleet_reply"
     if phase == "done" and has_reply:
-        return "DEGRADED", f"resolved via {source} (worker did not call bridge_reply)"
+        return "DEGRADED", f"resolved via {source} (worker did not call fleet_reply)"
     if phase == "done" and not has_reply:
         return "EMPTY", "turn completed but reply was empty"
     if phase == "failed":
@@ -206,7 +206,7 @@ def main():
     ok = all(g in ("OK", "DEGRADED") for g in grades)
     reply_clean = all(g == "OK" for g in grades)
     if reply_clean:
-        print("  RESULT: PASS — every turn delivered and got a clean bridge_reply.")
+        print("  RESULT: PASS — every turn delivered and got a clean fleet_reply.")
     elif ok:
         print("  RESULT: PASS (with notes) — every turn delivered & replied, but some via fallback.")
     else:

e2e/fleet_ask_test.py

@@ -1,16 +1,16 @@
 #!/usr/bin/env python3
-"""Live bridge_ask test — the REVERSE rendezvous (CB-205), watched end to end.
+"""Live fleet_ask test — the REVERSE rendezvous (CB-205), watched end to end.
 
-Every other harness drives the forward path: primary `bridge_send` → worker `bridge_reply`.
+Every other harness drives the forward path: primary `fleet_send` → worker `fleet_reply`.
 This drives the one that runs the other way. A worker is told to pause its delegated turn,
-ask the primary a question via `bridge_ask`, and only finish once it has the answer — so the
+ask the primary a question via `fleet_ask`, and only finish once it has the answer — so the
 turn round-trips primary→worker→primary→worker inside a SINGLE delegation.
 
 The mechanics that only this path exercises:
 
   • a worker's mid-turn question surfacing on the primary's *own* blocked send (Outcome.QUESTION),
   • the `turnId` correlation that lets the primary answer the exact paused turn,
-  • the answer resuming that same turn and the worker's final `bridge_reply` landing on the
+  • the answer resuming that same turn and the worker's final `fleet_reply` landing on the
     re-opened forward waiter (never a stale or cross-wired one).
 
 It is two blocking REST calls, no polling:
@@ -24,7 +24,7 @@ Like the rest of the suite it talks ONLY to the bridge's REST face on loopback
 ANTHROPIC_BASE_URL and never touches herdr, so it is subscription-safe by construction.
 
 Usage:
-    python3 bridge_ask_test.py [--base URL] [--profile NAME] [--repo DIR] [--out DIR]
+    python3 fleet_ask_test.py [--base URL] [--profile NAME] [--repo DIR] [--out DIR]
                                [--send-timeout SECS] [--answer-timeout SECS] [--keep-worker]
 
     --base            bridge REST base URL              (default http://127.0.0.1:8765)
@@ -57,14 +57,14 @@ ANSWER_COLOR = "blue"
 
 # A task that CANNOT be completed without asking: the worker is not told which color to choose,
 # only that the primary will name one when asked. So a correct final reply is only reachable by
-# actually calling bridge_ask and using the answer.
+# actually calling fleet_ask and using the answer.
 TASK_PROMPT = (
     "You are a bridge worker in a quick coordination game. You do NOT know which color to pick — "
     "only the primary does. Do exactly this, in order:\n"
-    "1. Call the `bridge_ask` tool with EXACTLY this question: \"PICK A COLOR: red or blue?\"\n"
+    "1. Call the `fleet_ask` tool with EXACTLY this question: \"PICK A COLOR: red or blue?\"\n"
     "2. The primary will answer with one color word. Take that color and uppercase it.\n"
-    "3. Call `bridge_reply` with EXACTLY one line: CHOSEN=<COLOR>  (e.g. CHOSEN=GREEN if told green).\n"
-    "Do not guess a color. Do not call bridge_reply before bridge_ask has returned an answer. "
+    "3. Call `fleet_reply` with EXACTLY one line: CHOSEN=<COLOR>  (e.g. CHOSEN=GREEN if told green).\n"
+    "Do not guess a color. Do not call fleet_reply before fleet_ask has returned an answer. "
     "Do nothing else — no file reads, no other tools."
 )
 
@@ -134,7 +134,7 @@ def run(base, profile, repo, send_timeout, answer_timeout):
     rec.update(tid=tid, pane=pane, spawned=True)
     await_ready(base, tid)
 
-    # 1) Delegate the ask-forcing task. This blocks until the worker calls bridge_ask, at which
+    # 1) Delegate the ask-forcing task. This blocks until the worker calls fleet_ask, at which
     #    point our own send unblocks carrying the question and the turnId to answer on.
     print(f"[{now()}] delegating task (blocks until the worker asks; up to {send_timeout}s)…")
     t0 = time.time()
@@ -159,7 +159,7 @@ def run(base, profile, repo, send_timeout, answer_timeout):
         rec.update(phase="no_turnid", detail="question surfaced without a turnId to answer on")
         return rec
 
-    # 2) Answer on that exact turn. This blocks again until the resumed worker calls bridge_reply.
+    # 2) Answer on that exact turn. This blocks again until the resumed worker calls fleet_reply.
     print(f"[{now()}] answering '{ANSWER_COLOR}' on turn {rec['turnId']} (blocks until reply; up to {answer_timeout}s)…")
     t1 = time.time()
     rec["phase"] = "awaiting_reply"
@@ -188,7 +188,7 @@ def run(base, profile, repo, send_timeout, answer_timeout):
 def grade(rec):
     """PASS only if the worker asked, the turn resumed, and the reply reflects the answer."""
     if rec["phase"] == "no_question":
-        return "NO_ASK", "the worker finished/stalled without ever calling bridge_ask"
+        return "NO_ASK", "the worker finished/stalled without ever calling fleet_ask"
     if rec["phase"] in ("send_error", "answer_error", "spawn"):
         return "ERROR", rec.get("detail") or "transport error before the round-trip completed"
     if rec["phase"] == "no_turnid":
@@ -203,26 +203,26 @@ def grade(rec):
             return "OK", "asked, resumed the same turn, and the reply reflected the primary's answer"
         if reflected:
             return "DEGRADED", f"reply reflected the answer but resolved via {rec['replySource']} " \
-                               "(worker did not call bridge_reply cleanly)"
+                               "(worker did not call fleet_reply cleanly)"
         return "WRONG_ANSWER", f"the worker replied but did not reflect '{ANSWER_COLOR}' — " \
                                f"the answer may not have reached the resumed turn: {rec['reply']!r}"
     return "WEDGE", f"unexpected terminal phase {rec['phase']}: {rec.get('detail')}"
 
 
 def write_transcript(out_dir, rec, meta):
-    path = out_dir / "bridge_ask_transcript.md"
+    path = out_dir / "fleet_ask_transcript.md"
     g, note = grade(rec)
     with path.open("w") as f:
-        f.write(f"# Live bridge_ask — reverse rendezvous — {datetime.now():%Y-%m-%d %H:%M}\n\n")
+        f.write(f"# Live fleet_ask — reverse rendezvous — {datetime.now():%Y-%m-%d %H:%M}\n\n")
         f.write(f"One worker paused its delegated turn to ask the primary, then resumed with the "
                 f"answer (profile `{meta['profile']}`). Result: **`{g}`**.\n\n")
         f.write("## Round-trip\n\n")
         f.write(f"1. **primary → worker** (delegation): the ask-forcing task.\n")
-        f.write(f"2. **worker → primary** (`bridge_ask`, {rec.get('ask_latency')}s): "
+        f.write(f"2. **worker → primary** (`fleet_ask`, {rec.get('ask_latency')}s): "
                 f"{rec.get('question')!r} — surfaced on the primary's blocked send as a "
                 f"`question` with `turnId={rec.get('turnId')}`.\n")
         f.write(f"3. **primary → worker** (answer on that turn): `{ANSWER_COLOR}`.\n")
-        f.write(f"4. **worker → primary** (`bridge_reply`, {rec.get('answer_latency')}s, "
+        f.write(f"4. **worker → primary** (`fleet_reply`, {rec.get('answer_latency')}s, "
                 f"source={rec.get('replySource')}): {rec.get('reply')!r}\n\n")
         f.write(f"> **{g}:** {note}\n")
         if rec.get("detail"):
@@ -231,7 +231,7 @@ def write_transcript(out_dir, rec, meta):
 
 
 def main():
-    ap = argparse.ArgumentParser(description="Live bridge_ask reverse-rendezvous test (CB-205)")
+    ap = argparse.ArgumentParser(description="Live fleet_ask reverse-rendezvous test (CB-205)")
     ap.add_argument("--base", default="http://127.0.0.1:8765")
     ap.add_argument("--profile", default=None)
     ap.add_argument("--repo", default=str(REPO_ROOT))
@@ -241,7 +241,7 @@ def main():
     ap.add_argument("--keep-worker", action="store_true")
     args = ap.parse_args()
 
-    print(f"[{now()}] live bridge_ask: 1 primary, 1 worker "
+    print(f"[{now()}] live fleet_ask: 1 primary, 1 worker "
           f"(profile={args.profile or 'default'}, repo={args.repo})\n")
 
     rec = {"spawned": False, "pane": None}
@@ -262,7 +262,7 @@ def main():
 
     print()
     print("=" * 72)
-    print("LIVE bridge_ask SUMMARY — reverse rendezvous (CB-205)")
+    print("LIVE fleet_ask SUMMARY — reverse rendezvous (CB-205)")
     print(f"  asked:    {rec.get('question')!r}  (turnId={rec.get('turnId')}, {rec.get('ask_latency')}s)")
     print(f"  answered: {ANSWER_COLOR!r}")
     print(f"  replied:  {rec.get('reply')!r}  (source={rec.get('replySource')}, {rec.get('answer_latency')}s)")

e2e/fleet_ask_transcript.md

@@ -1,12 +1,12 @@
-# Live bridge_ask — reverse rendezvous — 2026-07-16 16:30
+# Live fleet_ask — reverse rendezvous — 2026-07-16 16:30
 
 One worker paused its delegated turn to ask the primary, then resumed with the answer (profile `default`). Result: **`OK`**.
 
 ## Round-trip
 
 1. **primary → worker** (delegation): the ask-forcing task.
-2. **worker → primary** (`bridge_ask`, 6.6s): 'PICK A COLOR: red or blue?' — surfaced on the primary's blocked send as a `question` with `turnId=term_656bb47d2c42a9e#1`.
+2. **worker → primary** (`fleet_ask`, 6.6s): 'PICK A COLOR: red or blue?' — surfaced on the primary's blocked send as a `question` with `turnId=term_656bb47d2c42a9e#1`.
 3. **primary → worker** (answer on that turn): `blue`.
-4. **worker → primary** (`bridge_reply`, 7.9s, source=reply): 'CHOSEN=BLUE'
+4. **worker → primary** (`fleet_reply`, 7.9s, source=reply): 'CHOSEN=BLUE'
 
 > **OK:** asked, resumed the same turn, and the reply reflected the primary's answer

e2e/issue_hunt_test.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """Standard bridge fan-out test — ONE primary vs MANY workers, concurrently, for
-issue hunting through the running `bridged` daemon, fully captured, with gap analysis.
+issue hunting through the running `fleetd` daemon, fully captured, with gap analysis.
 
 Where conversation_test.py exercises a single worker over multiple turns, this drives
 the path that only appears under fan-out: the primary spawns N workers, sends each a
@@ -12,7 +12,7 @@ and collects every reply concurrently. That stresses what a single worker never
   • reply routing under concurrency (worker A's answer must never resolve worker B's send),
 
 and, as the payload, whether a fleet of off-subscription workers can actually surface
-real issues in the repo and report them back structurally via bridge_reply.
+real issues in the repo and report them back structurally via fleet_reply.
 
 It talks ONLY to the bridge's REST face on loopback — it never sets ANTHROPIC_BASE_URL
 and never touches herdr directly, so it is subscription-safe by construction.
@@ -53,18 +53,18 @@ REPO_ROOT = HERE.parent
 # hot files this project has been iterating on, so a real issue is plausible to find.
 DEFAULT_ASSIGNMENTS = [
     {"id": "completion", "probe": "CompletionResolver",
-     "target": "bridged/src/main/java/dev/ltms/bridged/inject/CompletionResolver.java"},
+     "target": "fleetd/src/main/java/dev/ltms/fleet/inject/CompletionResolver.java"},
     {"id": "worker", "probe": "WorkerService",
-     "target": "bridged/src/main/java/dev/ltms/bridged/worker/WorkerService.java"},
+     "target": "fleetd/src/main/java/dev/ltms/fleet/worker/WorkerService.java"},
     {"id": "rendezvous", "probe": "Rendezvous",
-     "target": "bridged/src/main/java/dev/ltms/bridged/msg/Rendezvous.java"},
+     "target": "fleetd/src/main/java/dev/ltms/fleet/msg/Rendezvous.java"},
 ]
 
 PROMPT_TMPL = (
     "You are one of several issue-hunting workers in the claude-bridge repo (it is your "
     "current working directory). Your assignment: inspect the file `{target}` and find the "
     "SINGLE most important real bug, correctness gap, or risk in it. Read the file before "
-    "answering. Reply via bridge_reply with EXACTLY these four lines:\n"
+    "answering. Reply via fleet_reply with EXACTLY these four lines:\n"
     "1. {target}:<line>\n"
     "2. issue: <one sentence>\n"
     "3. fix: <one line>\n"
@@ -147,9 +147,9 @@ def grade(rec):
     phase, source, reply = rec["phase"], rec["source"], rec["reply"]
     has_reply = bool(reply and reply.strip())
     if phase == "done" and source == "reply" and has_reply:
-        return "OK", "clean explicit bridge_reply"
+        return "OK", "clean explicit fleet_reply"
     if phase == "done" and has_reply:
-        return "DEGRADED", f"resolved via {source} (worker did not call bridge_reply)"
+        return "DEGRADED", f"resolved via {source} (worker did not call fleet_reply)"
     if phase == "done" and not has_reply:
         return "EMPTY", "turn completed but reply was empty"
     if phase == "failed":

fleetd/.gitignore

@@ -0,0 +1,16 @@
+# Build output
+target/
+dependency-reduced-pom.xml
+
+# Local runtime config (copy from fleetd.example.yaml). Both names are ignored: fleetd.yaml is
+# the current name, and bridged.yaml is the legacy name Fleetd still falls back to.
+fleetd.yaml
+bridged.yaml
+
+# CB-505 audit trail + daemon stdout/stderr — runtime records, never source
+logs/
+
+# Editor / OS
+*.iml
+.idea/
+.DS_Store

fleetd/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 `fleet_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
+`fleet_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"] -->|"fleet_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["fleet_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 — `fleet_send`, `fleet_spawn`,
+`fleet_poll`, `fleet_list`, `fleet_status`, `fleet_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
+(`fleet_reply`, `fleet_ask`) never set it.
+
+- **Config override / pin:** a `primary: { terminal: "<id>" }` block in `FleetConfig`
+  (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 `fleet_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 `fleet_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` `fleet_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 `fleet_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
+   `FleetMcp` 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 `fleet_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.

fleetd/fleetd.example.yaml

@@ -0,0 +1,851 @@
+# fleetd configuration (example). Copy to fleetd.yaml and adjust.
+#
+# fleetd 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 unless you also switch auth.mode to `token`
+# below — fleetd REFUSES TO START on a non-loopback bind under loopback-trust (see auth).
+bind:
+  host: 127.0.0.1
+  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
+#                           FLEETD_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: FLEETD_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 fleet_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.
+#
+#   tab → the ONLY field identity depends on (CB-579); the exact label of the tab hosting the lead.
+#         Label the tab yourself, or let fleetd label one it launches — see `fleet.leaders:` below.
+#   kind/model → descriptive; they document what runs in the pane and are echoed by fleet_whoami
+#
+# A lead's tab must already carry its label (or be launched by fleetd, which labels it) — there is
+# no terminal id to paste in and nothing to re-pin when the session restarts: the tab survives, so
+# the same label resolves the same lead again on the next scan.
+# `fleet_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, and is a separate mechanism from lead identity — see `fleet.leaders:`.
+#
+# 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 fleetd 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 fleet_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
+
+# Fleet health detection is dormant unless enabled (CB-573). It reads one whole-fleet agent list
+# per tick.
+#   intervalSeconds → how often a tick runs (default 30). ENFORCED floor of 15: the code computes
+#                      Math.max(15, intervalSeconds), so a lower value is silently raised, not
+#                      rejected.
+#   workingSuspectAfterSeconds → age before a BUSY member is suspected of a stall (default 600).
+#                      ENFORCED floor of 300: a lower value is silently raised.
+#   paneProbeIntervalSeconds → accepted and parsed, but NOT YET READ by anything. Setting it changes
+#                      nothing right now. It exists so a later build can start honouring it without
+#                      another config-shape change.
+#   notifications.mode → "webhook" flips what fleet_list REPORTS (healthCoverage: "full" instead
+#                      of "detection-only") — it does NOT make fleetd send any webhook call; no
+#                      delivery mechanism is implemented yet. Any other value, or omitting the
+#                      block, reports "detection-only".
+# health:
+#   enabled: true
+#   intervalSeconds: 30               # floor 15
+#   workingSuspectAfterSeconds: 600   # floor 300 — how long BUSY with no activity means STALL_SUSPECTED
+#   paneProbeIntervalSeconds: 60      # parsed, but nothing reads it yet — changing it changes nothing
+#   notifications:
+#     mode: disabled
+
+# herdr Unix socket. Omit to use the client default
+# (${HERDR_SOCKET_PATH:-~/.config/herdr/herdr.sock}).
+herdrSocket: ~/.config/herdr/herdr.sock
+
+# Optional socket for member panes. Omit this to use herdrSocket for both leads and members.
+# memberHerdrSocket: /Users/member/.config/herdr/herdr.sock
+
+# fleetd #213: the login shell the member OS user (memberHerdrSocket above) actually runs. ONLY
+# read when memberHerdrSocket is set — fleetd's own $SHELL says nothing about a pane running
+# under a different OS user, and there is no channel to ask herdr for that user's shell, so this
+# must be told rather than guessed. Absent, blank, or anything not ending in "zsh" is treated the
+# same as "not zsh": the memberCredentials.policy: allow-list ZDOTDIR scrub (see worktreeGroup
+# below) is skipped in favour of the weaker CB-596 sentinel overlay — a degraded control, never a
+# refusal to spawn. When memberHerdrSocket is absent this key is never consulted at all.
+# memberLoginShell: /bin/zsh
+
+# 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           → fleetd mounts the bridge MCP (--mcp-config, inline) + reply charter
+#                      (--append-system-prompt) as launch flags; nothing is written to the profile.
+#   ideMcpUrl        → opt-in (CB-634), default off. When set, fleetd mounts the IDE Index MCP as a
+#                      second inline server named `intellij`, and adds an IDE charter that pins every
+#                      ide_* call to the member's own worktree. A URL, not a boolean — host and port
+#                      are host-specific. Set it only on a host where the IDE actually runs.
+#   ideProjectDir    → repo-relative module dir the IDE opens and the overlay pins (CB-634). Only read
+#                      when ideMcpUrl is set. This repo's Maven pom lives in `fleetd/`, not at the
+#                      worktree root, so opening the root imports no module and ide_* resolves nothing;
+#                      set this to `fleetd`. Omit for a repo whose project is the worktree root.
+#   ideOpenCommand   → host command that opens ideProjectDir in the IDE at spawn (CB-634 auto-open).
+#                      Only read when ideMcpUrl is set. `{dir}` is replaced with the absolute module
+#                      dir and the command runs through `/bin/sh -c`, so set env inline if needed —
+#                      e.g. `env DISPLAY=:10.0 idea {dir}`. Best-effort: a failure is logged, never
+#                      fails the spawn. Omit to open the member's module by hand. There is no close
+#                      half yet — an opened module stays open until the operator closes it.
+#   autoCompactWindow → opt-in, default off. A bounded token window that forces a spawned member to
+#                      compact its context instead of running on the backend's own default and dying
+#                      mid-turn (losing its fleet_reply — the whole point of the turn — with it).
+#                      Validated at config load to [100000, 1000000] — the band Claude Code's own
+#                      --autocompact flag accepts.
+#                      CROSS-BACKEND SEMANTICS DIFFER: on claude-code this is a launch-time
+#                      `--autocompact <tokens>` flag — the member compacts AT this window. opencode
+#                      has no equivalent flag (it only forces `compaction.auto: true`, unconditionally,
+#                      already), so this is instead applied as the model's `limit.context` in the
+#                      generated opencode.json — the member compacts WITHIN this window, not exactly
+#                      at it — and only when this profile's `model:` is in `provider/model` form; if it
+#                      isn't, fleetd logs a WARN naming the profile rather than silently doing nothing.
+#   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:
+#                      [.env] only (CB-148). .envrc is left out of the default on purpose: it is
+#                      executable shell that direnv runs on every cd, so copying it carries
+#                      behaviour into the worker, not just values, unlike .env. An operator who
+#                      wants it copied can still write parityOverlay: [.env, .envrc] explicitly.
+#                      (.claude/settings.local.json is NOT in the default — it
+#                      pre-approves IDE/tool grants a member must not hold ambiently; CB-525/CB-634.)
+#
+#                      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.
+#                      fleetd 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.
+#   exhaustedPattern → regex matched against a completion-fallback scrape (CB-578 stage A) to
+#                      classify a turn that ended with no fleet_reply as the backend having
+#                      refused on a subscription usage limit, rather than a real answer. Opt-in —
+#                      omit and this profile's completion fallback behaves exactly as before.
+#                      Every backend words its refusal differently, so this is config, never a
+#                      vendor string baked into fleetd itself.
+#                      DEFERRED: compiled once into a startup pattern map — editing it needs a
+#                      daemon restart, same as this profile's model/baseUrl/argv.
+#   credentialId     → CB-578 stage B: the credential this profile quarantines WITH when a
+#                      BACKEND_EXHAUSTED classification fires. Two profiles that set the SAME
+#                      credentialId share one quarantine — the case this exists for is two models
+#                      on one account (e.g. sol and terra both billing one OpenAI credential): an
+#                      exhaustion on either one must lock out both, or the fleet just walks onto
+#                      the same dead account under the sibling's name. Opt-in — omit and this
+#                      profile quarantines alone, under its own name, exactly as if the field did
+#                      not exist. Cooldown length is the top-level quarantineCooldownSeconds below.
+#                      HOT: read live at every spawn/exhaustion check — no restart needed.
+#   errorPattern     → fleetd #201 / #227: regex matched against a completion-fallback scrape to
+#                      classify a turn that ended with no fleet_reply as a BACKEND ERROR — a
+#                      credential outage or a provider 5xx — rather than a real answer or a
+#                      usage-limit exhaustion (exhaustedPattern above always wins when a line
+#                      matches both). Opt-in. Omit it and this profile falls back to fleetd's
+#                      built-in legacy pattern `(?i)\bAPI Error\s*:` — classification still
+#                      happens, just without a profile-specific match; every backend words its
+#                      failure differently, so a hardcoded sentence would only ever match one
+#                      of them.
+#                      DEFERRED: compiled once into a startup pattern map, same as exhaustedPattern
+#                      — editing it needs a daemon restart.
+#                      # errorPattern: "503 Service Unavailable"   # opt-in: classify a backend outage
+#
+#                      What happens once a match fires (BackendOutagePolicy, credentialId-keyed,
+#                      SEPARATE from the CB-578 stage B quarantine above and never merged with it):
+#                        - threshold 2 — TWO DISTINCT TARGETS (never raw events) on the same
+#                          effective credential inside a 60-second window start an "incident" and a
+#                          60-second cool-off for that credential. One member repeating the same
+#                          classified line twice never cools anything off — a real outage hits
+#                          every target on that credential, so requiring a second, independent
+#                          target loses nothing against the case this guards against, while
+#                          protecting against a heuristic misfire on one flaky member.
+#                        - a fresh error while a credential is already cooling off is ignored
+#                          outright: it neither extends the 60s deadline nor starts a new incident.
+#                        - `fleet_list`/`fleet_profiles` report a cooling credential with
+#                          `coolingOffForSeconds` (never `quarantinedForSeconds`, unless CB-578
+#                          exhaustion quarantine is ALSO independently active for the same
+#                          credential — the two checks can both fire at once). A spawn onto a
+#                          cooling profile is refused with a message naming the credential and
+#                          remaining seconds — "cooling off", never "exhausted", so an operator can
+#                          tell a short transient fault from a spent subscription at a glance.
+#                        - the lead gets ONE nudge per incident (not one per affected target), via
+#                          the same push loop that already delivers ticket/question reminders.
+#   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. fleetd 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.
+#                      fleetd 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.fleet.plist and deploy/fleetd.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: fleetd-workers
+    # tabLabel: an optional per-profile override; the fleet template usually covers it
+    mcpUrl: http://127.0.0.1:8765/mcp
+    tokenEnv: FLEETD_WORKER_TOKEN
+    argv: ["ccs", "gx10"]
+    # weight: relative selection weight for automatic placement (weighted, round-robin, and
+    # fixed's fallback walk). Absent defaults to 1.0. An explicit 0 or negative value means
+    # "never auto-select this profile" (CB-554) — it stays reachable via an explicit
+    # `fleet_spawn{profile:"gx10"}`, which bypasses placement entirely; only automatic
+    # selection skips it.
+    weight: 0.5
+    # maxLoad: max live workers on this profile. Omit for unlimited. An explicit 0 (CB-585) caps
+    # the profile at zero live members — it is excluded from automatic placement and an explicit
+    # `fleet_spawn{profile:"gx10"}` against it is refused too; a cap holds even when the profile
+    # is named directly. Negative is refused at config load — there is no sane meaning for it.
+    maxLoad: 2
+    # subscription: true
+    #   THE KNOB THAT DECIDES WHO PAYS (CB-539). Default false. When true, this profile's members
+    #   run on the OPERATOR'S OWN Claude subscription instead of a metered endpoint — every spawn
+    #   bills your plan and eats your usage limit. Off-subscription is the whole point of this
+    #   daemon, so treat `true` as a deliberate exception, not a convenience.
+    #
+    #   What changes when it is set (ClaudeCodeLauncher):
+    #     - no ANTHROPIC_BASE_URL and no ANTHROPIC_AUTH_TOKEN are injected — the member inherits
+    #       the operator's own Claude Code auth, which is exactly why it bills the plan;
+    #     - SubscriptionGuard never vets it, because there is no baseUrl to vet;
+    #     - no token is required, so `tokenEnv` is irrelevant here.
+    #
+    #   MUTUALLY EXCLUSIVE with `baseUrl` — setting both is refused at config load (CB-542). On the
+    #   subscription path no guard would vet the URL, so allowing both would be a way around the
+    #   guard rather than a configuration.
+    #
+    #   GOTCHA 1 — it is invisible to the startup secret check. `Fleetd.reportRequiredSecrets`
+    #   skips subscription profiles on purpose (they need no token), so a boot log that reports
+    #   every secret as fine says nothing about these profiles.
+    #
+    #   GOTCHA 2 — `maxLoad` is the ONLY throttle you have here. There is no metering, no budget
+    #   and no refusal on cost; the cap on live members is the single thing standing between a
+    #   fan-out and your monthly limit. Set it deliberately and keep it small.
+    #
+    #   GOTCHA 3 (fleetd #176, corrected by fleetd #257) — `maxLoad` counts members, never the lead
+    #   itself. The lead is a live `claude` session on this SAME account (a lead is never moved
+    #   off-subscription, whatever its own profile says), so it already holds one seat before any
+    #   member spawns. If a lead's `fleet.leaders.<name>.profile` names THIS profile — or ANY OTHER
+    #   `subscription: true` profile that shares this one's account (see THE SENTINEL, just below,
+    #   next to `credentialId:`) — `fleet_list` reports that seat count under `leadSeats`; see
+    #   `profile:` under THE FLEET below. `free` itself is NEVER reduced by `leadSeats`: `free` means
+    #   "what the real placement gate (`CompositePeerLauncher#enforceMaxLoad`) will actually grant a
+    #   fresh `fleet_spawn` right now", and that gate only ever compares live members against
+    #   `maxLoad` — it has no notion of the lead's own seat. An earlier cut of this feature
+    #   subtracted `leadSeats` from `free` on the theory it made `free` describe the true ceiling on
+    #   the account, but no backend seat ceiling shared with the lead has ever actually been
+    #   measured, and the subtraction just made `free` disagree with the one thing it is supposed to
+    #   describe — the fleetd #257 fix. `maxLoad: 3` means 3 member slots, full stop; a lead sharing
+    #   the account is a fact you can see in `leadSeats`, not a reason `free` undercounts spawns that
+    #   will, in practice, succeed.
+    #
+    #   THE SENTINEL (fleetd #176 stage 2, correcting an inert stage 1 fix): every `subscription:
+    #   true` profile that leaves `credentialId` unset shares ONE implicit account-wide credential
+    #   id with every other such profile on this host — because a subscription profile doesn't
+    #   authenticate with a credential of its own, it authenticates as the operator's own Claude
+    #   login, and there is exactly one of those. So on a typical host, `opus` (the lead's profile)
+    #   and `sonnet` (the members' profile) are linked automatically, with NOTHING to set here — that
+    #   is what makes GOTCHA 3 above work without also writing matching `credentialId:` values on
+    #   both. This linkage is not just cosmetic: it is the same key `BackendQuarantine`/cool-off use,
+    #   so a usage-limit hit on `opus` now quarantines `sonnet` too (and vice versa) — correct, since
+    #   they are one Claude account, but worth knowing before you wonder why an unrelated-looking
+    #   profile went quarantined.
+    #
+    #   WHEN TO OVERRIDE — set explicit, DIFFERENT `credentialId:` values on two `subscription: true`
+    #   profiles only when they are genuinely two separate Claude logins on the same host (a real,
+    #   if unusual, setup). An explicit `credentialId` always wins over the sentinel, so this is the
+    #   one way to keep two subscription profiles from being treated as one account for lead-seat
+    #   counting AND for quarantine/cool-off grouping alike.
+    # 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
+    # exhaustedPattern: "usage limit has been reached"   # opt-in: classify a usage-limit refusal (CB-578)
+    # credentialId: shared-openai   # opt-in: quarantine together with every other profile sharing this id (CB-578)
+    # errorPattern: "503 Service Unavailable"   # opt-in: classify a backend outage (fleetd #201/#227) — see the key doc above
+    # 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: [".env"]   # the default; add ".envrc" explicitly if you want it copied too (CB-148) — never add .mcp.json or .claude/settings.local.json — see above
+    # ideMcpUrl: http://127.0.0.1:29170/index-mcp/streamable-http   # opt-in (CB-634): IDE code intelligence, pinned to the worktree
+    # ideProjectDir: fleetd          # CB-634: module dir the IDE opens + the overlay pins (this repo's pom is in fleetd/)
+    # ideOpenCommand: env DISPLAY=:10.0 idea {dir}   # CB-634 auto-open: opens {dir} in the IDE at spawn; omit to open by hand
+    # autoCompactWindow: 250000   # opt-in: bound member context; claude-code compacts AT this, opencode within it (model limit.context)
+  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: fleetd-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 → fleet_send →
+  # structured fleet_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: fleetd-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: fleetd-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.
+#
+# `weighted` IS NOT "cheapest first" — read this before you set weights (CB-589).
+# It is smooth weighted round-robin: it spreads spawns across EVERY profile that has a free slot,
+# in weight ratio. It has no idea which profile costs money. So with local:10 / paid:2 you do not
+# get "use local, overflow to paid" — you get roughly one spawn in six going to the paid profile
+# while the local box still has a free slot.
+#
+# There is a sharper second effect. The policy's running score map lives for the daemon's whole
+# life. While a profile is at maxLoad it is filtered out and its score FREEZES, so the paid
+# profiles keep accumulating against it. When the local slot frees up it returns with a stale
+# score and can LOSE the next pick — a paid spawn while the free box sits idle.
+#
+# Until a real cost-first policy exists, the workaround is to make the ratio decisive rather than
+# proportional: give the free profile a weight so large that it wins every pick it is eligible
+# for, and paid profiles only ever take genuine overflow. On this host that is local weight 100
+# against paid weights of ~1.
+#
+# The gotcha with that workaround: it expresses a PREFERENCE ORDER through a RATIO knob. Add a
+# future profile at weight 150 and it silently outranks the free box, with nothing to warn you.
+# Re-check the weights whenever you add a profile.
+placement: weighted
+
+# How long a credential sits out after a BACKEND_EXHAUSTED classification (CB-578 stage B), in
+# seconds, before a spawn may land on it again. Applies to every profile's effective credential
+# (its own name, or its credentialId if set above) — there is no per-profile override. Default
+# 1800 (30 minutes) when omitted or non-positive.
+# DEFERRED: baked once into the BackendQuarantine built at startup — a running quarantine keeps
+# its original cooldown regardless; a new value only applies to a quarantine that starts after a
+# restart. Editing this needs a daemon restart to take effect.
+#
+# This does NOT govern the fleetd #201 / #227 backend-error cool-off documented under errorPattern
+# above — that mechanism is a separate, shorter-lived, NOT-configurable policy (threshold 2 distinct
+# targets, 60-second window, 60-second cool-off), on purpose: it exists to survive a brief transient
+# fault, not to replace this 30-minute exhaustion quarantine. Do not conflate the two when reading
+# fleet_list/fleet_profiles — coolingOffForSeconds and quarantinedForSeconds are independent facts.
+# quarantineCooldownSeconds: 1800
+
+# Re-read this file without restarting the daemon (CB-559). Off unless you add this block, so an
+# upgraded fleetd keeps the old behaviour: the file is read once at boot and never again.
+#   enabled          → turn the watch on. fleetd 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,
+#               `charters`, and `tabLabel`), `placement:`, and an existing profile's weight / maxLoad
+#               / credentialId. Those are hot because the placement policy (and, for credentialId,
+#               the CB-578 stage B quarantine check) reads them through a supplier — being config is
+#               not by itself enough to make a key hot.
+#               EXCEPT `fleet.leaders`: Fleetd.main reads it once at startup to build the lead tab
+#               scanner and launcher, and neither is rebuilt on reload. A changed/added/removed
+#               `fleet.leaders` entry is silently accepted — the reload reports "config reloaded"
+#               with nothing in the deferred list — but has NO effect until you restart. Treat it
+#               as deferred in practice, even though today's reload output does not say so.
+#   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`, `quarantineCooldownSeconds` (CB-578
+#               stage B — baked once into the quarantine tracker built at startup), 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, exhaustedPattern, errorPattern (fleetd #201 / #227 —
+#               compiled once into a startup pattern map the same way exhaustedPattern is). 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 launch-charter text, keyed only by the singular role wire names: architect, dev,
+  # reviewer. Changes are HOT and reach the next spawn without a daemon restart. Do not put secrets
+  # here: a later launch step writes this text to a world-readable temp file, and ${ENV} interpolation
+  # is deliberately not supported.
+  charters:
+    architect: |-
+      You are an architect in this fleet. You refine work before anyone builds it:
+      scope, acceptance criteria, risks, and a unit split. You read the repo and
+      write analysis. You never commit production code and never open a PR.
+      A design task is worked by two architects. Design alone first, then exchange
+      and say plainly where you disagree. Do not concede just to agree.
+    dev: |-
+      You implement the one unit you were given, and nothing else. You test it,
+      commit it, and open your own pull request. You never merge.
+    reviewer: |-
+      You review the diff you were given. You report bugs, risks and missing tests.
+      You do not change code.
+
+  # 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. Omit `profile:` and it is recognise-only, as before.
+  #
+  # `profile:` has a SECOND job as of fleetd #176, even for a recognise-only lead you never want
+  # auto-launched: it is also how fleetd learns which account this lead's own session shares. A
+  # `subscription: true` profile bills the operator's Claude account, and the lead itself is always
+  # a live `claude` session on that same account — `maxLoad` never counted that seat. If a lead
+  # entry here names a profile that shares a worker profile's account, `fleet_list` reports the
+  # lead's live seat(s) on that worker profile under `leadSeats` — informational only, as of fleetd
+  # #257 it is NEVER subtracted from `free` (see GOTCHA 3, next to `maxLoad:`, in THE WORKERS above,
+  # for why). "Shares the account" is decided by matching `effectiveCredentialId()`, which (fleetd
+  # #176 stage 2 — see THE SENTINEL, next to `credentialId:`, in THE WORKERS above) means: an
+  # explicit, matching `credentialId:` on both, OR — the common case, needing NO extra config — both
+  # being `subscription: true` with `credentialId` left unset, since those all share one implicit
+  # account-wide id. A lead on `opus` and workers on `sonnet` link automatically this way; they do
+  # NOT need the same profile name. Setting `profile:` on an already-running, recognise-only lead is
+  # safe — the daemon only launches the SHORTFALL below `instances`, so naming a profile here does
+  # not, by itself, start anything. Omit it and fleetd has no way to derive the sharing — there is
+  # no other reliable signal on the daemon's side — so that lead's seat never appears in `leadSeats`.
+  #
+  # `tab:` (CB-579) is REQUIRED and is the only field identity depends on — the exact label of the
+  # tab hosting the lead, matched case-insensitively. Label the tab yourself and put that same
+  # string here, and the pane is recognised on the next rescan. Reopen the tab later, or the session
+  # inside it restarts — the terminal id changes; the tab, and its label, do not, so no config edit
+  # follows a restart.
+  #
+  # A lead the daemon launches is labelled BY the daemon with this same `tab:` value, 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, and a tab that is
+  # gone entirely drops out of the next scan rather than being remembered forever.
+  #
+  # 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.
+  #
+  # GET THE `tab:` VALUE RIGHT. A pane that does not match any configured `tab:` (a typo, a renamed
+  # tab, a pane no entry names at all) is not recognised as a lead — it resolves as an ordinary
+  # WORKER instead, silently, and every orchestration call it makes (spawn/stop/send/drain) is
+  # refused. There is no error at startup for this: an unmatched pane is simply not a lead. If your
+  # primary suddenly can't spawn or send, check this section first.
+  # 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
+  #     tab: "lead: opus-5.0"        # REQUIRED — the exact tab label this lead lives in
+  #     tabPrefix: "lead:"           # only used to guard against a worker tabLabel colliding with
+  #                                  # this convention at startup; plays no part in matching a lead
+  #     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: fleetd's own)
+  #     kind: claude                 # descriptive; reported by fleet_whoami
+  #   gpt-sol-5.6:
+  #     tab: "lead: gpt-sol-5.6"
+  #     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. Every profile above must have its host listed here.
+guard:
+  offSubscriptionHosts:
+    - gx00.gw
+    - gx01.gw
+
+# Member credential policy (CB-596, gitea issue #82). A herdr pane runs a LOGIN shell, and that
+# shell re-sources the operator's own secret store — so a spawned member inherits every credential
+# the operator's shell holds, not just the ones fleetd means to give it. Measured on this host:
+# 31 credential names, all set, with only ONE (GITEA_ACCESS_TOKEN) blocked before this — and that
+# block was a single name hardcoded in HerdrPeerLauncher.java, not driven by this file. This block
+# replaces that hardcoded shadow with a config-driven list of names.
+#
+# ROUND-2 CORRECTION, measured live: the pane-creation env overlay below (applied at tab.create /
+# pane.split, BEFORE the pane's login shell runs) does NOT survive that login shell for any name
+# secrets.sh actually exports — the shell re-exports it afterwards and overwrites the sentinel.
+# Proof: GITEA_ACCESS_TOKEN comes back blocked only because secrets.sh itself carries a guarded
+# export (`[ -n "${BRIDGED_MEMBER:-}" ] || export GITEA_ACCESS_TOKEN=...`) — that guard, not this
+# file, is what wins. No other name in `known` below has a matching guard in secrets.sh yet (1
+# guard measured against 33 export lines there). So today this block's overlay is REAL protection
+# only for a name secrets.sh does not export, or a peer kind whose pane never runs a login shell —
+# for everything secrets.sh exports and guards, the guard in secrets.sh (out of scope for this
+# ticket) is what actually blocks it, not this list. An exec-time fix (winning after the login
+# shell finishes, before the agent process starts) was attempted and found to have no seam in the
+# current herdr protocol — AgentControl.start takes a fixed `kind` (herdr resolves the executable)
+# plus trailing CLI args for that binary, not an arbitrary argv or an env map; only tab.create /
+# pane.split accept `env`, and that is this same pane-creation overlay. See gitea #82 for the open
+# design question this leaves.
+#
+# DENY-BY-DEFAULT, NOT A DENY-LIST. A deny-list (name the bad ones, let everything else through) is
+# silently wrong the moment the operator's store gains a new secret — nothing would ever report it.
+# Deny-by-default inverts that: `known` bounds the blast radius to names actually enumerated below,
+# and EVERY one of them is blocked UNLESS it is also in `allow`. Omitting this block entirely (the
+# shipped default) blocks NOTHING — unlike most optional blocks in this file, absence here is a real
+# gap, not a safe "feature off". A name that is neither `known` nor `allow`-ed is not silently let
+# through either: the daemon logs a WARN naming any credential-shaped env var it finds on neither
+# list (never its value), so a secret added to the store later does not go unnoticed forever.
+#
+#   policy → "deny-by-default" (the default; also accepted spelled "deny-list") overlays each
+#            known-but-not-allowed name BEFORE the pane's login shell runs — real protection only
+#            where that shell does not re-export the name (see ROUND-2 CORRECTION above). An
+#            unrecognized value refuses to start, naming it.
+#   policy → "allow-list" (CB-633) moves the control to a per-spawn ZDOTDIR directory the daemon
+#            generates and passes through tab.create's env map. Each generated startup file sources
+#            its ~/ counterpart FIRST and then runs the scrub, so the scrub happens after the
+#            operator's whole chain and no sourced file can undo it.
+#            The scrub is sourced from BOTH the generated .zshrc and the generated .zlogin, because
+#            herdr does not open the same kind of shell everywhere: macOS panes run a LOGIN zsh (so
+#            .zlogin runs), Linux panes run a plain interactive zsh (so .zlogin never runs at all).
+#            A scrub in .zlogin alone would be a control that silently does nothing on Linux.
+#            The allow-list is DERIVED, never typed:
+#            every profile's tokenEnv/gitTokenEnv/gitHostEnv values and env-map keys, plus an
+#            infrastructure set (PATH HOME SHELL TERM LANG LC_* TMPDIR USER LOGNAME PWD SHLVL EDITOR
+#            PAGER JAVA_HOME XDG_* ZDOTDIR), plus whatever keys this spawn's own env overlay carries.
+#            Adding a profile can therefore only widen the list, never break another spawn's scrub.
+#            Under this policy `known`/`allow` below become REPORTING ONLY — they feed the gap WARN,
+#            they are no longer a control. If the member's login shell is NOT zsh, the daemon logs a
+#            loud WARN saying protection is off and falls back to deny-by-default's overlay.
+#            Each pane writes a scrub-report.txt naming how many variables it kept of how many it
+#            saw; the daemon logs that "allowed N of M" line when the pane stops. If the report is
+#            MISSING the daemon logs a WARN instead — the scrub cannot then be confirmed to have
+#            run, and a silently-dead control is exactly what this policy exists to prevent.
+#   allow  → credential names a member legitimately needs. Under deny-by-default, left OUT of the
+#            pane's env overlay entirely, so the value the pane's own (login) shell exports passes
+#            through untouched. Under allow-list: reporting only.
+#   known  → every credential name the operator's store is known to export. Under deny-by-default,
+#            every name here NOT also in `allow` is overlaid with a non-secret sentinel value before
+#            the pane's login shell runs — real protection only for names that shell does not itself
+#            re-export (see the ROUND-2 CORRECTION note above). Under allow-list: reporting only.
+#   sshAgentEnv → whether SSH_AUTH_SOCK may pass through under allow-list ("inherit") or is omitted
+#            from the member environment ("omit", the default). Omitting it only omits the
+#            inherited ssh-agent path. It discourages automatic use of the operator's agent.
+#            It does not deny same-user access to that socket. It also does not block SSH keys that
+#            are readable on disk. Git over SSH may still work from inside a member. Keep the block:
+#            it is correct and costs nothing, but it is not a control. A member runs as the same OS
+#            user as the lead. Inside one uid, ordinary Unix permissions provide no meaningful
+#            confidentiality boundary. A real boundary needs a different OS user or OS-level
+#            confinement, such as a container or VM. That is the open question in fleetd #184.
+#
+#            Still do not set this to "inherit" casually. SSH_AUTH_SOCK is a live handle to YOUR
+#            ssh-agent, so a member holding it can sign with EVERY key the agent holds. It sits in
+#            no secret file and looks like no credential, which is why it slipped past three
+#            earlier tickets (gitea #110). Blocking it does not contain a member, but allowing it
+#            hands one a signing capability for no gain — the block costs nothing, so keep it.
+#
+#            Both halves of this are measured, not argued. 2026-08-28: a member with
+#            SSH_AUTH_SOCK blanked pushed to the forge over SSH successfully, because `ssh -G`
+#            resolves an IdentityFile outside ~/.ssh that is readable and has no passphrase. An
+#            earlier version of this comment claimed blocking the socket BREAKS git over SSH. It
+#            does not. That claim came from looking only in ~/.ssh, which holds nothing but four
+#            `Include` lines — looking in one place and concluding about the whole host.
+#
+# HOT-RELOADABLE the same way `fleet:` is (CB-559): read fresh on every spawn, so editing this list
+# and reloading config (or restarting) changes what the NEXT spawn inherits; already-running members
+# are unaffected either way.
+# memberCredentials:
+#   policy: deny-by-default        # or "deny-list", or "allow-list" (CB-633) — see above
+#   sshAgentEnv: omit              # allow-list only; see the sshAgentEnv note above
+#   allow:
+#     - AI_GATEWAY_TOKEN     # named in a profile's tokenEnv (local/gx) — a member reaching the
+#                            # gateway is by design, not a leak
+#     - WORKER_GITEA_TOKEN   # the repo-scoped forge token a member needs to open its own PR (CB-302)
+#     - CONTEXT7_TOKEN       # already decided as allowed by CB-593
+#     - GITEA_HOST           # not a credential — a hostname, paired with the forge token above
+#   known:
+#     - AI_GATEWAY_TOKEN
+#     - BESZEL_ADMIN_EMAIL
+#     - BESZEL_ADMIN_PASSWORD
+#     - BESZEL_HUB_URL
+#     - BESZEL_KEY
+#     - BESZEL_UNIVERSAL_TOKEN
+#     - BRAIN_MCP_TOKEN
+#     - CF_ACCOUNT_ID
+#     - CF_API_TOKEN
+#     - CF_USER_TOKEN
+#     - CONFLUENCE_API_TOKEN
+#     - CONFLUENCE_USERNAME
+#     - CONTEXT7_TOKEN
+#     - GITEA_ACCESS_TOKEN
+#     - GITEA_HOST
+#     - GITLAB_OAUTH_CLIENT_SECRET
+#     - GITLAB_PERSONAL_ACCESS_TOKEN
+#     - GRAFANA_ADMIN_PASSWORD
+#     - GRAFANA_ADMIN_USER
+#     - HASS_TOKEN
+#     - HW_PASSWORD
+#     - HW_USER
+#     - LTMS_API_KEY
+#     - MEMORY_MCP_TOKEN
+#     - METRICS_PUSH_TOKEN
+#     - OPENCODE_AUTOMODE_MODEL
+#     - TELEGRAM_BOT_TOKEN
+#     - TELEGRAM_CHAT_ID
+#     - TS_API_KEY
+#     - TS_AUTHKEY
+#     - WORKER_GITEA_TOKEN
+
+# 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
+
+# Worktree group sharing (fleetd #185 stage 3). OPTIONAL, off by default. Names an OS group
+# that a provisioned worktree's repo is made group-writable for (git config
+# core.sharedRepository group, plus a one-time chgrp/chmod/setgid fix-up), so a member spawned
+# under a DIFFERENT OS user (see memberHerdrSocket) can write its own worktree, its
+# per-worktree git metadata, and its own commit objects — without it, every file GitWorktrees
+# creates is owned by fleetd's own uid and unwritable by another user.
+# CAUTION: this isolates credentials, not the repository — a member in the group can still
+# write the operator's git objects and refs in the shared repo. The operator running fleetd
+# must already be a member of the named group, or every provisioning spawn fails loudly.
+#
+# fleetd #213: this is also the ONE group the memberCredentials.policy: allow-list ZDOTDIR scrub
+# reuses when memberHerdrSocket is set — deliberately not a second config key. Under
+# memberHerdrSocket, the scrub directory is generated under worktreeRoot (never java.io.tmpdir,
+# which the member OS user cannot reach) and shared read-only with this group. If worktreeGroup
+# is unset while memberHerdrSocket is set, the scrub cannot be guaranteed reachable by the member,
+# so fleetd falls back to the weaker CB-596 sentinel overlay instead (a WARN names the gap).
+# worktreeGroup: fleet-workers
+
+# 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
+#   clearAfterTurn     → whether a reusable worker discards its conversation context after every
+#                        completed delegated turn (default false). Works for claude-code workers
+#                        only — any other peer kind (e.g. opencode) logs "context reset is
+#                        unsupported for peer kind …" once and the reset is a no-op.
+# lifecycle:
+#   idleTtlSeconds: 300
+#   contextCap: 10
+#   drainTimeoutSeconds: 5
+#   clearAfterTurn: false
+
+# 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.
+#   uriEnv   → CB-151: name of a host env var holding the AMQP URI, preferred over `uri` (wins
+#              whenever set). The URI carries `user:pass@` inline, so naming a variable keeps the
+#              password out of fleetd.yaml — same pattern as auth.tokenEnv/Profile.tokenEnv. A
+#              uriEnv that resolves to an unset or blank variable is treated as NOT configured and
+#              the daemon falls back to the in-memory inbox, warning loudly.
+#   prefetch → CB-527: consumer basicQos, capping how many unacked messages the inbox holds
+#              in-heap per owned target (the rest sits on the broker's durable queue instead of
+#              growing the JVM heap). Default 32 when omitted.
+# broker:
+#   uriEnv: LAVINMQ_URI
+#   prefetch: 32
+
+# Shared cross-host LEADER coordination broker. OMIT this block to leave lead-to-lead messaging
+# off entirely (config-only in this ticket — nothing here wires it into a live LeadMailbox yet).
+# This is a SEPARATE AMQP vhost from `broker:` above: member/worker inboxes always stay on the
+# per-fleet `broker:` vhost, and this vhost carries only leader-to-leader traffic, so two fleets
+# whose members must never see each other can still share one coordination vhost for their leads.
+#   uriEnv   → name of a host env var holding the coordination AMQP URI, same convention as
+#              broker.uriEnv (keeps the credential out of fleetd.yaml). Wins over `uri` when set.
+#   selfId   → this daemon's own lead coord-id — the name its mailbox is owned under
+#              (lead.<selfId>.inbox), e.g. "mac-opus" or "fleet01-lead". Must be globally unique
+#              across every daemon sharing this vhost.
+#   prefetch → consumer basicQos, capping how many unacked messages the mailbox holds in-heap.
+#              Default 32 when omitted.
+# coordinator:
+#   uriEnv: LEAD_COORD_URI
+#   selfId: mac-opus
+#   prefetch: 32
+
+# Active push-to-primary (CB-307 Stage 3). When a worker reply lands with no open fleet_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 fleetd-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 fleet_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

fleetd/pom.xml

@@ -5,17 +5,17 @@
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>dev.ltms</groupId>
-    <artifactId>bridged</artifactId>
-    <version>0.1.0-SNAPSHOT</version>
+    <artifactId>fleetd</artifactId>
+    <version>1.0.0</version>
     <packaging>jar</packaging>
 
-    <name>bridged</name>
-    <description>claude-bridge message server: sole gateway between primary/worker Claude sessions and herdr</description>
+    <name>fleetd</name>
+    <description>fleet message server: sole gateway between a lead session, its members, and herdr</description>
 
     <properties>
         <maven.compiler.release>25</maven.compiler.release>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <mainClass>dev.ltms.bridged.Bridged</mainClass>
+        <mainClass>dev.ltms.fleet.Fleetd</mainClass>
 
         <jackson.version>2.19.0</jackson.version>
         <javalin.version>6.7.0</javalin.version>
@@ -24,6 +24,12 @@
         <slf4j.version>2.0.16</slf4j.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>
+        <sqlite-jdbc.version>3.53.4.0</sqlite-jdbc.version>
+        <archunit.version>1.5.0</archunit.version>
     </properties>
 
     <!--
@@ -40,6 +46,12 @@
           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.
+
+      fleetd #206: org.xerial:sqlite-jdbc 3.53.4.0 (added for OpenCodeSessionDiscovery) — the
+      only known advisory against this artifact is CVE-2023-32697 (RCE via an attacker-controlled
+      JDBC URL), fixed in 3.41.2.2; 3.53.4.0 is well past that fix and OSV.dev reports no open
+      advisory against it. Checked via the OSV.dev API (no Mend.io/JetBrains IDE MCP mount
+      available from this worktree) on 2026-08-31.
     -->
 
     <!-- Force the latest patched Jetty 11.x across all Javalin-pulled Jetty modules (no version
@@ -62,6 +74,22 @@
                 <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>
 
@@ -86,13 +114,34 @@
         </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. -->
+             /mcp, exposing fleet_send/fleet_reply/fleet_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>
+
+        <!-- fleetd #206: opencode moved its session store from a JSON tree to SQLite
+             (opencode.db). This is the JDBC driver OpenCodeSessionDiscovery uses to read it
+             read-only. Ships bundled native libraries (linux/mac/windows, several archs), so it
+             is a heavier jar than most deps here — see the pom's dependency-security note below
+             for the size/CVE tradeoff actually measured. -->
+        <dependency>
+            <groupId>org.xerial</groupId>
+            <artifactId>sqlite-jdbc</artifactId>
+            <version>${sqlite-jdbc.version}</version>
+        </dependency>
+
         <!-- Logging -->
         <dependency>
             <groupId>org.slf4j</groupId>
@@ -112,10 +161,37 @@
             <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>
+
+        <!-- fleetd #131: package-boundary and cycle enforcement (PackageCyclesTest). -->
+        <dependency>
+            <groupId>com.tngtech.archunit</groupId>
+            <artifactId>archunit-junit5</artifactId>
+            <version>${archunit.version}</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>
-        <finalName>bridged</finalName>
+        <!-- CB-634: the cutover renamed the module dir (bridged/ -> fleetd/), the jar, and the
+         launchd plist together. The installed plist names fleetd/target/fleetd.jar and
+         KeepAlive is armed, so this name, the plist, and the wrapper must move as one. -->
+        <finalName>fleetd</finalName>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -123,6 +199,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>
@@ -133,7 +233,7 @@
                 </configuration>
             </plugin>
 
-            <!-- Runnable fat jar: java -jar target/bridged.jar -->
+            <!-- Runnable fat jar: java -jar target/fleetd.jar -->
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-shade-plugin</artifactId>
@@ -166,6 +266,26 @@
         <profile>
             <id>contract</id>
             <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>

fleetd/src/main/java/dev/ltms/fleet/auth/AuditLog.java

@@ -0,0 +1,72 @@
+package dev.ltms.fleet.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");
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/auth/Authz.java

@@ -0,0 +1,82 @@
+package dev.ltms.fleet.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 FleetMcp} 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();
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/auth/CallerResolver.java

@@ -0,0 +1,284 @@
+package dev.ltms.fleet.auth;
+
+import dev.ltms.fleet.mcp.ConnectionIdentity;
+import dev.ltms.fleet.peer.MemberRole;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.Map;
+import java.util.function.Function;
+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 FleetMcp}
+ * 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 Fleetd} reads a constant from config, which is the degenerate live case.
+     */
+    private final Supplier<Map<String, String>> architectTerminals;
+    private final Function<String, MemberRole> memberSlotRoles;
+    private final Function<String, String> memberSlotNames;
+
+    /** Loopback-trust resolver: no token required, historical behaviour. Test-only. */
+    CallerResolver(ConnectionIdentity identity) {
+        this(identity, false, null, Map.of());
+    }
+
+    /** As {@link #CallerResolver(ConnectionIdentity, boolean, String, Map)} with no leads pinned. Test-only. */
+    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)
+     */
+    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.
+     */
+    CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token,
+                   Map<String, String> leadTerminals) {
+        this(identity, tokenMode, token, fixed(leadTerminals), null);
+    }
+
+    /**
+     * 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}.
+     */
+    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 that can confirm a bound slot is an architect slot.
+     *
+     * <p>This is the only public construction path. It keeps terminal bindings and slot roles in
+     * the same {@link MemberRegistry}, so a configured architect can resolve as an architect.
+     */
+    public static CallerResolver withLeadsAndMembers(ConnectionIdentity identity,
+                                                       boolean tokenMode, String token,
+                                                       Supplier<Map<String, String>> leadTerminals,
+                                                       MemberRegistry members) {
+        return new CallerResolver(identity, tokenMode, token, leadTerminals,
+                members == null ? null : members::snapshot,
+                members == null ? null : members::roleForSlot,
+                members == null ? null : members::nameForSlot);
+    }
+
+    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) {
+        this(identity, tokenMode, token, leadTerminals, architectTerminals, null);
+    }
+
+    private CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token,
+                           Supplier<Map<String, String>> leadTerminals,
+                           Supplier<Map<String, String>> architectTerminals,
+                           Function<String, MemberRole> memberSlotRoles) {
+        this(identity, tokenMode, token, leadTerminals, architectTerminals, memberSlotRoles, null);
+    }
+
+    private CallerResolver(ConnectionIdentity identity, boolean tokenMode, String token,
+                           Supplier<Map<String, String>> leadTerminals,
+                           Supplier<Map<String, String>> architectTerminals,
+                           Function<String, MemberRole> memberSlotRoles,
+                           Function<String, String> memberSlotNames) {
+        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;
+        this.memberSlotRoles = memberSlotRoles == null ? _ -> null : memberSlotRoles;
+        this.memberSlotNames = memberSlotNames == null ? Function.identity() : memberSlotNames;
+    }
+
+    /**
+     * 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 && memberSlotRoles.apply(slot) == MemberRole.ARCHITECT) {
+                // 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.
+                // Check the slot role too: this defence in depth prevents a bad lifecycle bind from
+                // escalating a dev or reviewer into an architect. Checked before the worker fallback.
+                return Principal.architect(memberSlotNames.apply(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
+        // (FleetConfig.validateAuthExposure), so this is defence in depth, not the control.
+        //
+        // fleetd #317: "not a worker" must not be conflated with "identity unresolved". The real
+        // primary is a real process — its pid resolves (c.resolved()), it just owns no herdr pane.
+        // A caller whose peer-PID lookup failed (LsofPeerPidLookup's -1 sentinel — on any failure,
+        // silently including "lsof found no match") has no such pid, and PaneLocator's own javadoc
+        // already names what happens if that case is handed the primary role: a worker→primary
+        // escalation. So an unresolved caller is refused (ANONYMOUS — the same clean, already-tested
+        // "authenticated as nothing" outcome used everywhere else in this method), never promoted.
+        return isLoopback(remoteAddr) && c.resolved() ? 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;
+    }
+
+    /**
+     * fleetd #305: delegates to {@link ConnectionIdentity#isLoopback}. This used to be a second,
+     * independent copy of the same rule, and the two drifted: this one accepted all of
+     * {@code 127.0.0.0/8}, {@code ConnectionIdentity}'s accepted only {@code 127.0.0.1}. A caller
+     * from {@code 127.0.0.2} therefore had its identity skipped (so it had no terminal) and was
+     * then read as loopback here — which under loopback-trust is the primary. Sharing the inputs
+     * would not have prevented that; only sharing the computation does.
+     */
+    private static boolean isLoopback(String remoteAddr) {
+        return ConnectionIdentity.isLoopback(remoteAddr);
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/auth/MemberLifecycle.java

@@ -0,0 +1,74 @@
+package dev.ltms.fleet.auth;
+
+import dev.ltms.fleet.peer.MemberRole;
+
+/** Optional session lifecycle hook for live member-slot bindings. */
+public interface MemberLifecycle {
+
+    /** A slot held before a member process starts. */
+    record SlotReservation(String slot, String profile) { }
+
+    MemberLifecycle NONE = new MemberLifecycle() {
+        @Override
+        public MemberRole acquired(MemberRole role, String profile, String terminal) {
+            return role; // no registry configured — nothing to bind against, so the request stands
+        }
+
+        @Override
+        public void released(String terminal) {
+        }
+
+        @Override
+        public void requireSlotFor(MemberRole role, String profile) {
+            // no registry configured — nothing to validate against, so nothing is refused
+        }
+
+        @Override
+        public SlotReservation reserve(MemberRole role, String profile) {
+            return null;
+        }
+
+        @Override
+        public boolean bind(SlotReservation reservation, String terminal) {
+            return false;
+        }
+
+        @Override
+        public void release(SlotReservation reservation) {
+        }
+    };
+
+    /**
+     * Try to bind a newly spawned {@code terminal} into the role it was granted.
+     *
+     * @return the role this session actually holds: {@code role} unchanged for a role with no
+     *         live slot-binding semantics (dev, reviewer), or when the bind succeeded; a fallback
+     *         role — never {@code role} — when a slot-bound role (architect) could not be bound.
+     *         Callers must record THIS value on the session, never the requested {@code role}, so
+     *         a later roster read never reports a role the session does not hold (CB-619). In
+     *         normal operation this fallback should not happen once a reservation has been bound.
+     *         It remains the honest answer if a caller has no reservation, or if binding a
+     *         reservation unexpectedly fails.
+     */
+    MemberRole acquired(MemberRole role, String profile, String terminal);
+
+    void released(String terminal);
+
+    /**
+     * Refuse an acquire before anything spawns when {@code role} requires a live slot binding and
+     * no configured slot carries {@code profile} (CB-619 / fleetd #123). A no-op for a role with
+     * no slot-binding semantics.
+     *
+     * @throws IllegalArgumentException naming the role, the profile, and the pools that do carry it
+     */
+    void requireSlotFor(MemberRole role, String profile);
+
+    /** Reserve a matching slot before launch, or refuse before a charter can be delivered. */
+    SlotReservation reserve(MemberRole role, String profile);
+
+    /** Convert a reservation into a live terminal binding. */
+    boolean bind(SlotReservation reservation, String terminal);
+
+    /** Return an unbound reservation after a failed launch. */
+    void release(SlotReservation reservation);
+}

fleetd/src/main/java/dev/ltms/fleet/auth/MemberRegistry.java

@@ -0,0 +1,332 @@
+package dev.ltms.fleet.auth;
+
+import dev.ltms.fleet.config.FleetConfig;
+import dev.ltms.fleet.peer.MemberRole;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * 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 implements MemberLifecycle {
+
+    private static final Logger log = LoggerFactory.getLogger(MemberRegistry.class);
+
+    /**
+     * 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 terminalToSlot}. */
+    private final Map<String, String> terminalToSlot = new HashMap<>();
+    /** Slot keys held between reservation and the terminal binding. Guarded by terminalToSlot. */
+    private final java.util.Set<String> reservedSlots = new java.util.HashSet<>();
+
+    /** Flatten every role pool in {@code fleet} into one registry. Leaders are not members. */
+    public MemberRegistry(FleetConfig.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 fleet_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();
+    }
+
+    /** The unqualified configured name for a slot, or {@code null} if it is unknown. */
+    public String nameForSlot(String slotName) {
+        Entry e = slots.get(slotName);
+        return e == null ? null : e.name();
+    }
+
+    /** 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) || reservedSlots.contains(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;
+        }
+    }
+
+    /**
+     * Bind only architect sessions to a free slot with the resolved profile.
+     *
+     * <p>The role check is lifecycle policy. {@link CallerResolver} repeats it when resolving a
+     * binding, so a later lifecycle regression cannot turn a worker into an architect.
+     *
+     * <p>CB-619 / fleetd #123: the return value is the role this session actually holds, and the
+     * caller is required to record THAT — never the requested {@code role} — on the session. Before
+     * this fix the caller kept the requested role regardless of whether the bind below succeeded, so
+     * a demoted session's {@code GET /members} row still said {@code "architect"} while
+     * {@code fleet_whoami} (which reads the live binding, not the request) correctly said
+     * {@code "worker"} — three sources of truth that disagreed about one live member, silently.
+     */
+    @Override
+    public MemberRole acquired(MemberRole role, String profile, String terminal) {
+        if (role != MemberRole.ARCHITECT || terminal == null || terminal.isBlank()) {
+            return role;
+        }
+        // slotsFor preserves definition order, so duplicate-profile slots use the first free one.
+        for (Entry entry : slotsFor(MemberRole.ARCHITECT).values()) {
+            if (Objects.equals(profile, entry.profile()) && bind(entry.key(), terminal)) {
+                return MemberRole.ARCHITECT;
+            }
+        }
+        // fleetd #123: at least WARN — a role downgrade that the roster must now also reflect is
+        // not routine bookkeeping. requireSlotFor already refuses the config-gap case (no slot at
+        // all carries this profile) before a process ever spawns; reaching here means the config DID
+        // carry a matching slot but every one of them was already bound to a different terminal — a
+        // race this pre-spawn check cannot close on its own (see requireSlotFor's javadoc).
+        log.warn("member slot: no free architect slot for profile={} terminal={}; holding the session "
+                + "as {} instead of the architect it asked for — every configured slot for this "
+                + "profile is already bound to a different terminal", profile, terminal,
+                MemberRole.DEV.wireName());
+        return MemberRole.DEV;
+    }
+
+    /**
+     * CB-619 / fleetd #123: refuse an architect acquire before anything spawns when no configured
+     * slot carries {@code profile} — the config-gap case from the original defect report (a spawn
+     * asked for {@code role=architect, profile=sonnet}, and {@code fleet.architects} carried only
+     * {@code opus} and {@code sol}). A dev/reviewer acquire is always a no-op: those pools are
+     * placement candidates only (see {@code CompositePeerLauncher}), never a live identity binding,
+     * so there is nothing here to refuse — an explicit profile outside the pool for those roles is a
+     * documented operator override, not a defect.
+     *
+     * <p>This closes the config-gap case, not the live-capacity case: a profile that DOES carry a
+     * slot can still lose the race to a concurrent spawn between this check and the actual
+     * {@link #bind}, which is why {@link #acquired} must still answer honestly even after this
+     * check has passed.
+     */
+    @Override
+    public void requireSlotFor(MemberRole role, String profile) {
+        if (role != MemberRole.ARCHITECT) {
+            return;
+        }
+        boolean hasSlot = slotsFor(MemberRole.ARCHITECT).values().stream()
+                .anyMatch(e -> Objects.equals(profile, e.profile()));
+        if (hasSlot) {
+            return;
+        }
+        List<String> pools = slotsFor(MemberRole.ARCHITECT).values().stream()
+                .map(Entry::profile)
+                .distinct()
+                .toList();
+        throw new IllegalArgumentException(
+                "no " + role.wireName() + " slot for profile '" + profile + "' — an architect's "
+                        + "identity IS the slot it is bound to, so there is nothing to bind this "
+                        + "session's identity to. fleet." + role.configKey() + " carries profiles: "
+                        + (pools.isEmpty() ? "(none configured)" : String.join(", ", pools))
+                        + "; add profile '" + profile + "' there, or spawn " + role.wireName()
+                        + " on one of those profiles instead");
+    }
+
+    @Override
+    public SlotReservation reserve(MemberRole role, String profile) {
+        if (role != MemberRole.ARCHITECT) {
+            return null;
+        }
+        synchronized (terminalToSlot) {
+            for (Entry entry : slotsFor(MemberRole.ARCHITECT).values()) {
+                if ((profile == null || profile.isBlank() || Objects.equals(profile, entry.profile()))
+                        && !terminalToSlot.containsValue(entry.key()) && reservedSlots.add(entry.key())) {
+                    return new SlotReservation(entry.key(), entry.profile());
+                }
+            }
+        }
+        throw new IllegalArgumentException("no free architect slot for profile '" + profile
+                + "' — every matching slot is already bound or reserved");
+    }
+
+    @Override
+    public boolean bind(SlotReservation reservation, String terminal) {
+        if (reservation == null || terminal == null || terminal.isBlank()) {
+            return false;
+        }
+        synchronized (terminalToSlot) {
+            if (!reservedSlots.remove(reservation.slot())) {
+                return false;
+            }
+            if (!isSlot(reservation.slot()) || terminalToSlot.containsKey(terminal)
+                    || terminalToSlot.containsValue(reservation.slot())) {
+                return false;
+            }
+            terminalToSlot.put(terminal, reservation.slot());
+            return true;
+        }
+    }
+
+    @Override
+    public void release(SlotReservation reservation) {
+        if (reservation != null) {
+            synchronized (terminalToSlot) {
+                reservedSlots.remove(reservation.slot());
+            }
+        }
+    }
+
+    /** Unbind a released terminal using the compare-safe registry operation. */
+    @Override
+    public void released(String terminal) {
+        String slot = slotForTerminal(terminal);
+        if (slot != null) {
+            unbind(slot, terminal);
+        }
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/auth/Principal.java

@@ -0,0 +1,127 @@
+package dev.ltms.fleet.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 fleet_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 fleet_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 #isSpawnedMember()} 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 fleet_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;
+    }
+
+    /**
+     * Whether this caller is a spawned member with its own pane.
+     *
+     * <p>Both workers and architects are spawned members. A lead is excluded because recording it
+     * as present would count it as an available member in the roster.
+     */
+    public boolean isSpawnedMember() {
+        return role == Role.WORKER || role == Role.ARCHITECT;
+    }
+
+    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";
+        };
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/auth/Role.java

@@ -0,0 +1,39 @@
+package dev.ltms.fleet.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
+}

fleetd/src/main/java/dev/ltms/fleet/config/ConfigRef.java

@@ -0,0 +1,597 @@
+package dev.ltms.fleet.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 FleetConfig}, 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 four 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 placement:}, and an existing profile's {@code weight} / {@code maxLoad}. Both are
+ *       read through a supplier on {@code CompositePeerLauncher}, which is what makes them hot —
+ *       not the fact that they are config. Most of {@code fleet:} — every role pool
+ *       ({@code architects}/{@code developers}/{@code reviewers}), {@code charters}, and
+ *       {@code tabLabel} — is read the same live way, through the same supplier
+ *       ({@code () -> config.get().fleet()}). <strong>But {@code fleet:} as a whole is NOT in this
+ *       class</strong>: {@code fleet.leaders} inside the same key is frozen, which is exactly what
+ *       makes {@code fleet:} split rather than hot — see below.</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 quarantineCooldownSeconds}
+ *       (CB-578 stage B — baked once into the {@code BackendQuarantine} built at startup),
+ *       {@code guard:}, {@code worktreeRoot:} and {@code worktreeGroup:} (both baked once into the
+ *       {@code GitWorktrees} built at {@code Fleetd.java:251} and never rebuilt — fleetd #323
+ *       instance 2 found {@code worktreeGroup} missing from this list and from
+ *       {@link #changedDeferredKeys}), {@code primary:} (fleetd #326 — {@code Fleetd.java:506, 519,
+ *       520} read {@code cfg.primary()} only off the startup snapshot to build {@code
+ *       PrimaryRegistry} and size {@code ReplyPushLoop}'s reminder cap/backoff, and neither is
+ *       rebuilt on reload. Say the consequence exactly: {@code primary.terminal} is DEPRECATED
+ *       (CB-532, and {@code Fleetd.java:511} warns about it at startup) — a lead's identity comes
+ *       from {@code leaders:}/{@code leadScan:}, so changing this pin does not demote or promote a
+ *       lead that uses those. What a changed pin still does not take effect on until a restart is
+ *       the fallback nudge destination the pin remains, the deprecated identity path for an operator
+ *       who still relies on it, and {@code pushReminders}/{@code pushBackoffMs}), {@code configReload:} (fleetd #326 — {@code
+ *       Fleetd.java:679-680} read it only at startup to decide whether to build a {@code
+ *       ConfigWatcher} at all and with what interval; the watcher that would apply a later change is
+ *       itself built once, so a running watcher keeps polling on its original enabled flag and
+ *       interval regardless of what a reload changes it to, the same shape as {@code lifecycle} —
+ *       not cold, because no already-open resource goes inconsistent with the new value, the watcher
+ *       (if any) simply keeps its old settings), 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},
+ *       {@code exhaustedPattern} (CB-578 stage A — compiled once into {@code Fleetd.main}'s
+ *       pattern map at startup), {@code errorPattern} (fleetd #201 Unit 5 — compiled once into
+ *       {@code Fleetd.main}'s backend-error pattern map at startup, the same way),
+ *       {@code ideProjectDir} / {@code ideOpenCommand} / {@code autoCompactWindow} (fleetd #323
+ *       instance 1 — all three are read at spawn off the same frozen profile map and were missing
+ *       from {@link #sameLaunchSettings}), and the rest of {@link #sameLaunchSettings}.
+ *       {@code credentialId} (CB-578 stage B) is NOT on
+ *       this list — it is read live off the config supplier at every quarantine check and
+ *       exhaustion event, exactly like {@code weight} / {@code maxLoad}, so it is hot instead.
+ *       {@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>Split</strong> (fleetd #330; extended to a third key by fleetd #333) — read
+ *       <em>both</em> ways at different sites, so the key does not fit any class above as a whole:
+ *       {@code health:}, {@code coordinator:} and {@code fleet:}. Each is read off the startup
+ *       snapshot to build a long-lived object, and read live off {@link #get()} at a different,
+ *       unrelated site — so half of a reload's effect already applies while the other half waits
+ *       for a restart, and a bare "config reloaded" would under-claim by exactly that half.
+ *       <ul>
+ *         <li>{@code health:} — the monitor itself ({@code enabled}, {@code intervalSeconds},
+ *             {@code workingSuspectAfterSeconds}) is built once at {@code Fleetd.java:556-563}
+ *             and never rebuilt, so a changed value needs a restart to actually start, stop, or
+ *             retime it. The coverage string {@code fleet_profiles} reports
+ *             ({@code Fleetd.java:648-650}) is read live off {@link #get()} on every call, so it
+ *             already reflects the new value.</li>
+ *         <li>{@code coordinator:} — the {@code LeadMailbox} connection ({@code uri},
+ *             {@code uriEnv}, {@code selfId}, {@code prefetch}) is opened once at
+ *             {@code Fleetd.java:502} and never reopened, so a changed value needs a restart —
+ *             {@code selfId} in particular names this daemon's own AMQP inbox queue, and a peer
+ *             lead that learned the old name would not discover a new one on its own. The broker
+ *             URI env-var <em>name</em> that {@code MemberEnvAllowList} keeps out of a member's
+ *             environment is read live off {@link #get()} on every spawn
+ *             ({@code HerdrPeerLauncher.java:1530}), so it already applies.</li>
+ *         <li>{@code fleet:} (fleetd #333) — {@code fleet.leaders} is the frozen half:
+ *             {@code Fleetd.java:281} reads {@code cfg.fleet().leaders()} off the startup snapshot
+ *             for two long-lived objects built right after it and never rebuilt — the
+ *             {@code LeadTabScanner}'s {@code tab label → lead name} map ({@code Fleetd.java:301},
+ *             wired into {@code CallerResolver.withLeadsAndMembers} at {@code Fleetd.java:620/624},
+ *             which is how a caller's pane is recognised as a lead at all) and, when herdr answered
+ *             at startup, {@code LeadLauncher(...).ensureLeads()} ({@code Fleetd.java:315}), which
+ *             auto-launches each declared lead up to its {@code instances} count. So a lead added,
+ *             removed, or given a new {@code tab:} label under {@code fleet.leaders} needs a
+ *             restart — until then it is invisible to identity resolution, and this is exactly the
+ *             scenario fleetd #333 named: an operator edits a lead's {@code tab:} to match a
+ *             renamed pane, sees "config reloaded", and the pane keeps resolving as a worker,
+ *             because {@code CallerResolver} is still matching against the old label. The live
+ *             half is the rest of {@code fleet:} — {@code architects}/{@code developers}/
+ *             {@code reviewers}, {@code charters}, {@code tabLabel} — read live through the same
+ *             {@code CompositePeerLauncher} supplier the Hot bullet above names, so a reload that
+ *             only touches those already applies with nothing to report. Because the hot and frozen
+ *             halves of {@code fleet:} are disjoint sub-fields rather than the same fields read two
+ *             ways (contrast {@code coordinator.uriEnv} above), {@link #changedSplitKeys} compares
+ *             {@code fleet.leaders} alone, not the whole {@code Fleet} record — comparing the whole
+ *             record would report "split" for a {@code tabLabel}-only change that is actually fully
+ *             hot, over-claiming in exactly the direction this class exists to avoid under-claiming
+ *             in.</li>
+ *       </ul>
+ *       A split change is still accepted — {@link Outcome#applied()} stays {@code true}, the same
+ *       as a deferred change — because the live half genuinely took effect; refusing the whole
+ *       reload would leave the operator worse off than today. {@link Outcome#split()} names the
+ *       key and says which half is which each time, rather than trying to score "how changed" a
+ *       mixed key is or handle "both halves changed in one reload" as a special case.</li>
+ *   <li><strong>Cold</strong> — cannot change at all under a running daemon. All five of
+ *       {@link #COLD_KEYS}: {@code bind:}, {@code herdrSocket:}, {@code memberHerdrSocket:},
+ *       {@code broker:} and {@code auth:}. The sockets are already connected, the broker
+ *       connection is open, and the auth mode decides who may reach the port that is already
+ *       listening. This bullet omitted {@code memberHerdrSocket:} until fleetd #333 — say "all
+ *       five of COLD_KEYS" rather than re-listing them, so prose and set cannot drift again.</li>
+ * </ul>
+ *
+ * <p><strong>The denominator, measured on 2026-09-04 (fleetd #330; recounted for fleetd #333).</strong>
+ * {@code FleetConfig} has 22 top-level record components: 5 cold, 11 deferred, 3 split, 3
+ * hot-excluded. Three of them are named nowhere in this file, and the reason is the same for all
+ * three: {@code placement}, {@code memberCredentials} and {@code memberLoginShell} are
+ * <strong>hot</strong> and correctly absent — all three are read live off {@code config.get()}
+ * (placement through the {@code CompositePeerLauncher} supplier the Hot bullet names;
+ * {@code memberCredentials}/{@code memberLoginShell} at spawn time, {@code Fleetd.java:198, 205, 729}
+ * and {@code HerdrPeerLauncher#configuredMemberLoginShell}), so a reload takes effect on the next
+ * spawn with no entry needed here.
+ * {@code health} and {@code coordinator} used to be a third kind — <strong>undecided</strong>, not
+ * hot — until fleetd #330 added the <strong>split</strong> class above and gave them a home. A
+ * reload touching either used to report a bare "config reloaded", which under-claimed; now it names
+ * the key and says which half is which. {@code fleet} was the same story in reverse: fleetd #330's
+ * own fact-find named {@code health}/{@code coordinator} as "the complete set of split-shaped keys"
+ * and filed {@code fleet.leaders}'s restart requirement as a documented caveat sitting in the
+ * <strong>hot-excluded</strong> escape hatch instead — correctly documented, but in the one bucket
+ * this file's own coverage test cannot check the truth of (see that test's javadoc). fleetd #333
+ * moved it into <strong>split</strong>, where {@link #changedSplitKeys} actually reports it.
+ * <p>The point of writing the count down: "not mentioned in this file" looks identical for a key
+ * that is correctly hot and for a key nobody triaged. Three times now — {@code worktreeGroup} (#323),
+ * {@code primary}/{@code configReload} (#326), and {@code fleet.leaders} sitting in the escape hatch
+ * (#333) — the second kind hid among the first. A top-level coverage checker in the
+ * {@link ConfigRefProfileCoverageTest} shape (one level up, over {@code FleetConfig} itself rather
+ * than {@code FleetConfig.Profile}) proves this file's four classes exhaust the record's components
+ * — see {@code ConfigRefTopLevelCoverageTest}. That test proves the record's <em>shape</em> is fully
+ * triaged; it does NOT prove a {@code SPLIT_KEYS}/{@code COLD_KEYS}/{@code DEFERRED_KEYS} member has
+ * any reporting code behind it at all — {@code ConfigRefTopLevelReportingCoverageTest} is what
+ * fleetd #333 added for that, after measuring that a {@code SPLIT_KEYS} entry with its reporting
+ * branch deleted passes both this file's own "kept in step" assert and
+ * {@code ConfigRefTopLevelCoverageTest} unchanged. fleetd #337 extended it to {@code DEFERRED_KEYS}
+ * after measuring the same one-way gap there directly: dropping {@code guard}'s branch out of
+ * {@link #changedDeferredKeys} while {@code "guard"} stayed in the set left the whole suite green.
+ *
+ * <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. A split change does <em>not</em> refuse, for a different reason than a
+ * deferred change does not: its live half genuinely took effect, so refusing would throw that away
+ * and leave the operator worse off than the partial-but-honest report {@link Outcome#split()} gives.
+ *
+ * <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<FleetConfig> {
+
+    private static final Logger log = LoggerFactory.getLogger(ConfigRef.class);
+
+    /**
+     * Keys that cannot change under a running daemon — see the class doc.
+     *
+     * <p>Package-private (not {@code private}) so {@code ConfigRefTopLevelCoverageTest} can fold it
+     * into the top-level triage it checks, the same way it reads {@link #SPLIT_KEYS}.
+     */
+    static final Set<String> COLD_KEYS =
+             Set.of("bind", "herdrSocket", "memberHerdrSocket", "broker", "auth");
+
+    /**
+     * Keys read BOTH off the startup snapshot and live off {@link #get()} at different sites, so
+     * neither the hot, deferred nor cold class fits them as a whole — see the class doc's Split
+     * bullet (fleetd #330). A changed split key is accepted ({@link Outcome#applied()} stays
+     * {@code true}) and reported by name, with a message naming which half is live and which needs
+     * a restart.
+     */
+    static final Set<String> SPLIT_KEYS = Set.of("health", "coordinator", "fleet");
+
+    /**
+     * Top-level keys {@link #changedDeferredKeys} compares — see the class doc's Deferred bullet.
+     * Promoted here from a test-side copy in {@code ConfigRefTopLevelCoverageTest} by fleetd #337,
+     * the same reason {@link #COLD_KEYS} and {@link #SPLIT_KEYS} live here rather than in a test: a
+     * second, hand-maintained copy of this set is exactly the kind of thing that silently drifts
+     * from the method it is supposed to describe. {@code spawnReadyTimeoutMs} and
+     * {@code spawnReadyPollMs} are compared together in one branch and reported under the combined
+     * label {@code "spawnReady*"}; {@code profiles} is compared twice over (added/removed names,
+     * then an existing profile's launch settings) — see {@link #changedDeferredKeys}.
+     *
+     * <p>Package-private (not {@code private}) so {@code ConfigRefTopLevelCoverageTest} and
+     * {@code ConfigRefTopLevelReportingCoverageTest} can both read it, the same way they already
+     * read {@link #COLD_KEYS} and {@link #SPLIT_KEYS}.
+     */
+    static final Set<String> DEFERRED_KEYS = Set.of(
+            "guard", "worktreeRoot", "worktreeGroup", "primary", "configReload",
+            "leadHeartbeat", "lifecycle", "spawnReadyTimeoutMs", "spawnReadyPollMs",
+            "quarantineCooldownSeconds", "profiles");
+
+    private final Path path;
+    private final AtomicReference<FleetConfig> current;
+
+    public ConfigRef(Path path, FleetConfig 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(FleetConfig cfg) {
+        return new ConfigRef(null, cfg);
+    }
+
+    /** The live configuration. Read this per use; do not cache it in a field. */
+    @Override
+    public FleetConfig 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.
+     *
+     * <p>{@code split} is a separate field from {@code deferred} rather than a differently-worded
+     * entry inside it, because the two carry different guarantees for any caller that branches on
+     * them rather than just printing {@link #summary()}: every {@code deferred} entry means "this
+     * key's whole change waits for a restart", while every {@code split} entry means "part of this
+     * key's change already applied, and the message says which part" — collapsing them would force
+     * a caller to re-parse the message to tell those apart. See the class doc's Split bullet
+     * (fleetd #330) for why the key needs this at all.
+     *
+     * @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 entirely on a
+     *                 restart
+     * @param split    split keys that changed and were accepted, each named with which half of it
+     *                 is already live and which half 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,
+                          List<String> split, String error) {
+
+        public Outcome {
+            coldKeys = List.copyOf(coldKeys);
+            deferred = List.copyOf(deferred);
+            split = List.copyOf(split);
+        }
+
+        static Outcome refusedCold(List<String> keys) {
+            return new Outcome(false, keys, List.of(), List.of(), null);
+        }
+
+        static Outcome failed(String error) {
+            return new Outcome(false, List.of(), 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 fleetd to apply them.";
+            }
+            if (deferred.isEmpty() && split.isEmpty()) {
+                return "config reloaded";
+            }
+            StringBuilder out = new StringBuilder("config reloaded");
+            if (!deferred.isEmpty()) {
+                out.append("; these changes need a restart to take effect: ")
+                        .append(String.join(", ", deferred));
+            }
+            if (!split.isEmpty()) {
+                out.append("; partially live — ").append(String.join(" | ", split));
+            }
+            return out.toString();
+        }
+    }
+
+    /**
+     * 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");
+        }
+        FleetConfig old = current.get();
+        FleetConfig fresh;
+        try {
+            fresh = FleetConfig.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.validateCharters();
+            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);
+        List<String> split = changedSplitKeys(old, fresh);
+        current.set(fresh);
+        Outcome out = new Outcome(true, List.of(), deferred, split, null);
+        log.info(out.summary());
+        return out;
+    }
+
+    /**
+     * Cold keys whose value differs between the running config and the candidate.
+     *
+     * <p>Package-private (not {@code private}) so {@code ConfigRefTopLevelReportingCoverageTest}
+     * can call it directly with a reflection-built {@code FleetConfig} pair, the same reason
+     * {@link #sameLaunchSettings} is package-private — see that test's class doc (fleetd #333).
+     */
+    static List<String> changedColdKeys(FleetConfig old, FleetConfig 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.memberHerdrSocket(), fresh.memberHerdrSocket())) {
+            changed.add("memberHerdrSocket");
+        }
+        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.
+     *
+     * <p>Package-private (not {@code private}) so {@code ConfigRefTopLevelReportingCoverageTest}
+     * can call it directly with a reflection-built {@code FleetConfig} pair, the same reason
+     * {@link #changedColdKeys} and {@link #changedSplitKeys} already are (fleetd #333, extended to
+     * this method by fleetd #337 — membership in {@link #DEFERRED_KEYS} proved nothing about this
+     * method on its own until then; see that test's class doc).
+     */
+    static List<String> changedDeferredKeys(FleetConfig old, FleetConfig 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");
+        }
+        // Baked into the same GitWorktrees as worktreeRoot (Fleetd.java:251) and never rebuilt
+        // either — see the class doc. Missing this check was fleetd #323 instance 2: a reload
+        // that changed only worktreeGroup reported "config reloaded" with nothing deferred, and
+        // newly provisioned worktrees kept the old sharing behaviour.
+        if (!Objects.equals(old.worktreeGroup(), fresh.worktreeGroup())) {
+            changed.add("worktreeGroup");
+        }
+        // fleetd #326: Fleetd.java:506, 519, 520 read cfg.primary() only off the startup snapshot
+        // (PrimaryRegistry's pinned terminal, ReplyPushLoop's reminder cap and backoff) — neither is
+        // rebuilt on reload, so a changed value needs a restart. Note what it does NOT mean:
+        // primary.terminal is deprecated (CB-532), identity comes from leaders:/leadScan:, so a lead
+        // using those is unaffected by this pin either way. See the class doc for the exact scope.
+        if (!Objects.equals(old.primary(), fresh.primary())) {
+            changed.add("primary");
+        }
+        // fleetd #326: Fleetd.java:679-680 read cfg.configReload() only at startup to decide whether
+        // to build a ConfigWatcher at all and with what interval — the watcher that would apply a
+        // later change is itself built once, so a running watcher keeps its original enabled flag and
+        // interval regardless of what a reload changes it to. Not cold: no already-open resource goes
+        // inconsistent with the new value, a watcher (if any) simply keeps polling on the old settings.
+        if (!Objects.equals(old.configReload(), fresh.configReload())) {
+            changed.add("configReload");
+        }
+        if (!Objects.equals(old.spawnReadyTimeoutMs(), fresh.spawnReadyTimeoutMs())
+                || !Objects.equals(old.spawnReadyPollMs(), fresh.spawnReadyPollMs())) {
+            changed.add("spawnReady*");
+        }
+        // CB-578 stage B: baked once into the BackendQuarantine built at startup — a running
+        // quarantine keeps its original cooldown regardless, and a new cooldown only applies to a
+        // quarantine that starts after a restart.
+        if (!Objects.equals(old.quarantineCooldownSeconds(), fresh.quarantineCooldownSeconds())) {
+            changed.add("quarantineCooldownSeconds");
+        }
+        Map<String, FleetConfig.Profile> before =
+                old.profiles() == null ? Map.of() : old.profiles();
+        Map<String, FleetConfig.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) -> {
+            FleetConfig.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;
+    }
+
+    /**
+     * Split keys whose value differs between the running config and the candidate — see the class
+     * doc's Split bullet (fleetd #330, extended for {@code fleet:} by fleetd #333). Unlike
+     * {@link #changedDeferredKeys}, this does not try to tell which sub-field moved for {@code
+     * health:} or {@code coordinator:}: any change to either gets the same fixed message, because
+     * the message already names both halves every time, so there is no "which half changed"
+     * question left for the caller to answer. {@code fleet:} is different on purpose — see below.
+     *
+     * <p>Package-private (not {@code private}) so {@code ConfigRefTopLevelReportingCoverageTest}
+     * can call it directly with a reflection-built {@code FleetConfig} pair, the same reason
+     * {@link #sameLaunchSettings} is package-private — see that test's class doc (fleetd #333). That
+     * test exists because membership in {@link #SPLIT_KEYS} proves nothing about this method on its
+     * own: fleetd #333 measured that dropping the {@code coordinator} branch out of this method
+     * while leaving {@code "coordinator"} in {@code SPLIT_KEYS} left the whole suite green except a
+     * hand-written {@code ConfigRefTest} case — neither {@code ConfigRefTopLevelCoverageTest} (it
+     * only reads the set) nor the "kept in step" assert below (it only checks the reported keys are
+     * a SUBSET of {@code SPLIT_KEYS}, never that every {@code SPLIT_KEYS} member has a branch here)
+     * would have caught it.
+     */
+    static List<String> changedSplitKeys(FleetConfig old, FleetConfig fresh) {
+        List<String> changed = new ArrayList<>();
+        if (!Objects.equals(old.health(), fresh.health())) {
+            changed.add("health: the monitor itself (enabled, interval, workingSuspectAfter) is "
+                    + "frozen at startup and needs a restart; the coverage status fleet_profiles "
+                    + "reports is read live and already applied");
+        }
+        if (!Objects.equals(old.coordinator(), fresh.coordinator())) {
+            changed.add("coordinator: the LeadMailbox connection (uri, uriEnv, selfId, prefetch) is "
+                    + "opened once and needs a restart; the broker URI env-var name kept out of a "
+                    + "member's environment is read live on every spawn and already applied");
+        }
+        // fleetd #333: unlike health/coordinator above, most of `fleet:` (architects, developers,
+        // reviewers, charters, tabLabel) is genuinely hot — ConfigRefTest.aHotChangeIsAppliedAndRead-
+        // ThroughGet and aCharterChangeIsHotAndReachesTheLiveConfig prove it reaches the live config
+        // with no restart note. Only fleet.leaders is frozen (Fleetd.java:281 reads
+        // cfg.fleet().leaders() off the startup snapshot to build both the LeadTabScanner's
+        // tab-label-to-name map, wired into CallerResolver.withLeadsAndMembers at Fleetd.java:620/624,
+        // and — when herdr answered — LeadLauncher(...).ensureLeads() at Fleetd.java:315, which
+        // auto-launches each lead up to its `instances` count; neither is rebuilt on reload). So this
+        // compares fleet.leaders alone, not the whole Fleet record: comparing the whole record would
+        // report "split" for a tabLabel-only or charters-only change that is actually fully hot,
+        // which is the over-claim mirror of the under-claim bug this class exists to prevent.
+        if (!Objects.equals(leadersOf(old), leadersOf(fresh))) {
+            changed.add("fleet: fleet.leaders (each lead's tab, workspace, cwd, profile and "
+                    + "instances count) is read once at startup to build the LeadTabScanner's "
+                    + "identity map and to auto-launch leads, and neither is rebuilt on reload, so a "
+                    + "lead added, removed, or given a new tab: label needs a restart — until then it "
+                    + "stays unrecognised, and a caller from its new tab resolves as a worker, not a "
+                    + "lead; the rest of fleet: (architects, developers, reviewers, charters, "
+                    + "tabLabel) is read live through the supplier on CompositePeerLauncher and "
+                    + "already applied");
+        }
+        // Kept in step with SPLIT_KEYS the same way changedColdKeys is kept in step with COLD_KEYS —
+        // every message here must be traceable to one of the split keys the class doc documents.
+        // NOTE what this does NOT prove, per the javadoc above: it does not catch a SPLIT_KEYS
+        // member with no branch above at all, only a branch whose message is mis-worded relative to
+        // the set. ConfigRefTopLevelReportingCoverageTest is what proves the former.
+        assert changed.stream().allMatch(m -> SPLIT_KEYS.stream().anyMatch(k -> m.startsWith(k + ":")))
+                : "a split entry was reported that does not start with a SPLIT_KEYS name: " + changed;
+        return changed;
+    }
+
+    /** {@code cfg.fleet().leaders()}, defensively, in case a caller hands in a non-defaulted config. */
+    private static Map<String, FleetConfig.Leader> leadersOf(FleetConfig cfg) {
+        return cfg.fleet() == null ? Map.of() : cfg.fleet().leaders();
+    }
+
+    /**
+     * {@link FleetConfig.Profile} record components deliberately left out of
+     * {@link #sameLaunchSettings} because they are read <em>live</em>, not baked in at spawn — see
+     * the class doc's <em>Hot</em> bullet. {@code weight} and {@code maxLoad} are read live by the
+     * placement policy on every spawn; {@code credentialId} is read live by
+     * {@code CompositePeerLauncher} and the CB-578 stage B exhaustion sink. Nothing else is
+     * excluded — see {@code sameLaunchSettingsComparesEveryProfileComponentOrExcludesIt} in
+     * {@code ConfigRefProfileCoverageTest}, which enumerates every {@code Profile} record component
+     * by reflection and fails the build if one is neither compared below nor named here.
+     */
+    static final Set<String> LAUNCH_SETTINGS_EXCLUDED = Set.of("weight", "maxLoad", "credentialId");
+
+    /**
+     * Whether two versions of a profile would launch a peer identically.
+     *
+     * <p>This must compare every {@link FleetConfig.Profile} record component except the three in
+     * {@link #LAUNCH_SETTINGS_EXCLUDED}. That is not a claim this javadoc can make good on by
+     * itself — a javadoc saying "compares every component" is exactly what fleetd #323 found to be
+     * false for three fields (and a sibling method's field list, for a fourth). The actual
+     * guarantee comes from {@code ConfigRefProfileCoverageTest}: it enumerates every record
+     * component of {@code FleetConfig.Profile} by reflection, mutates each one not in
+     * {@code LAUNCH_SETTINGS_EXCLUDED} on a base profile, and asserts this method reports a
+     * difference — so a new component that is neither compared here nor added to
+     * {@code LAUNCH_SETTINGS_EXCLUDED} (with a reason) fails that test by name, rather than
+     * silently reporting "config reloaded" for a value the daemon never picked up.
+     */
+    static boolean sameLaunchSettings(FleetConfig.Profile a, FleetConfig.Profile b) {
+        return Objects.equals(a.profile(), b.profile())
+                && 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())
+                // CB-634: the IDE MCP mount is a launch flag, fixed at spawn like mcpUrl — a
+                // reload changes it only for members spawned after, so a changed value is deferred.
+                && Objects.equals(a.ideMcpUrl(), b.ideMcpUrl())
+                && 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())
+                // CB-578 stage B: exhaustedPattern is compiled once into Fleetd.main's pattern map
+                // at startup (see ExhaustedPatternLookup wiring) — a reload never re-reads it, so a
+                // changed pattern must be reported as deferred, exactly like model/baseUrl/argv.
+                && Objects.equals(a.exhaustedPattern(), b.exhaustedPattern())
+                // fleetd #201 Unit 5: errorPattern is compiled once into Fleetd.main's backend-error
+                // pattern map at startup (see BackendErrorPatternLookup wiring), the same way
+                // exhaustedPattern is — a reload never re-reads it either.
+                && Objects.equals(a.errorPattern(), b.errorPattern())
+                // fleetd #323 instance 1: ideProjectDir and ideOpenCommand are read at spawn off the
+                // same frozen profile map as ideMcpUrl above (ClaudeCodeLauncher.java:267/269,
+                // OpenCodeLauncher.java:474/480/486) and were missing from this comparison.
+                && Objects.equals(a.ideProjectDir(), b.ideProjectDir())
+                && Objects.equals(a.ideOpenCommand(), b.ideOpenCommand())
+                // fleetd #323 instance 1: autoCompactWindow is read at spawn the same way
+                // (ClaudeCodeLauncher.java:926, OpenCodeLauncher.java:650). Comparing it here only
+                // makes the reload REPORT that a restart is needed — it deliberately does not make
+                // autoCompactWindow take effect live, which is a separate, larger change.
+                && Objects.equals(a.autoCompactWindow(), b.autoCompactWindow());
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/config/ConfigWatcher.java

@@ -0,0 +1,96 @@
+package dev.ltms.fleet.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 fleetd.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();
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/guard/GuardException.java

@@ -1,4 +1,4 @@
-package dev.ltms.bridged.guard;
+package dev.ltms.fleet.guard;
 
 /** Thrown when the subscription boundary would be violated. Never swallow this. */
 public class GuardException extends RuntimeException {

fleetd/src/main/java/dev/ltms/fleet/guard/SubscriptionGuard.java

@@ -1,4 +1,4 @@
-package dev.ltms.bridged.guard;
+package dev.ltms.fleet.guard;
 
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -16,7 +16,7 @@ import java.util.Set;
  *       means its traffic would leave the subscription. That is a hard stop.</li>
  * </ul>
  *
- * Both checks throw {@link GuardException} on violation. {@code bridged} calls
+ * Both checks throw {@link GuardException} on violation. {@code fleetd} calls
  * {@link #assertWorker} before spawning a worker and {@link #assertPrimaryClean}
  * against its own environment at startup.
  */

fleetd/src/main/java/dev/ltms/fleet/health/FleetHealth.java

@@ -0,0 +1,40 @@
+package dev.ltms.fleet.health;
+
+import dev.ltms.fleet.herdr.AgentStatus;
+import dev.ltms.fleet.session.MemberSession;
+
+/**
+ * Pure classifier. Collection and repair are deliberately outside this package.
+ * {@link HealthState#ERROR_ON_SCREEN} is not decided yet because it needs a bounded pane detection
+ * read and an adapter-specific fatal signature; status facts alone must not guess it.
+ */
+public final class FleetHealth {
+    private FleetHealth() { }
+
+    public static HealthDecision decide(HealthSnapshot s, HealthPrior prior, long nowNanos) {
+        if (s.controlLinkDown()) return result(HealthState.CONTROL_LINK_DOWN, false);
+        if (s.targetNotFound()) return result(HealthState.GONE, false);
+        if (s.sessionState() == MemberSession.State.SPAWNING && !s.present() && s.readinessGraceElapsed()) {
+            return result(HealthState.NEVER_READY, false);
+        }
+        if (s.orphanedDelegation()) return result(HealthState.DELEGATION_ORPHANED, false);
+        boolean disagreement = s.sessionState() == MemberSession.State.BUSY && s.acceptedDelivery()
+                && (s.liveStatus() == AgentStatus.IDLE || s.liveStatus() == AgentStatus.DONE);
+        if (disagreement && prior.busyButDone()) return result(HealthState.TURN_BOUNDARY_LOST, true);
+        if (s.stalled()) return result(HealthState.STALL_SUSPECTED, disagreement);
+        if (s.replyStranded()) return result(HealthState.REPLY_STRANDED, disagreement);
+        if (s.queuedDelivery() || s.inboxMessage()) return result(HealthState.WORK_PENDING, disagreement);
+        if (s.sessionState() == MemberSession.State.SPAWNING) return result(HealthState.STARTING, disagreement);
+        if (s.acceptedDelivery() && s.liveStatus() == AgentStatus.BLOCKED) {
+            return result(HealthState.BLOCKED_AMBIGUOUS, disagreement);
+        }
+        // An accepted delivery remains bridge work even when herdr is late, unknown, or has already
+        // reported DONE once. It cannot be IDLE until the delegation has resolved.
+        if (s.acceptedDelivery()) return result(HealthState.WORKING, disagreement);
+        return result(HealthState.IDLE, disagreement);
+    }
+
+    private static HealthDecision result(HealthState state, boolean disagreement) {
+        return new HealthDecision(state, new HealthPrior(disagreement));
+    }
+}

fleetd/src/main/java/dev/ltms/fleet/health/FleetHealthMonitor.java

@@ -0,0 +1,270 @@
+package dev.ltms.fleet.health;
+
+import dev.ltms.fleet.herdr.Agent;
+import dev.ltms.fleet.herdr.AgentControl;
+import dev.ltms.fleet.herdr.AgentStatus;
+import dev.ltms.fleet.herdr.HerdrException;
+import dev.ltms.fleet.msg.MessageService;
+import dev.ltms.fleet.session.MemberSession;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import java.util.function.BiConsumer;
+import java.util.function.LongSupplier;
+import java.util.function.Supplier;
+
+/** Slow whole-fleet evidence collection. It is deliberately separate from the delivery poller. */
+public final class FleetHealthMonitor {
+    private static final Logger log = LoggerFactory.getLogger(FleetHealthMonitor.class);
+
+    /** Bounded attempts to run {@link #failTarget} for one transition. Never retried tick-to-tick (CB-580). */
+    static final int MAX_FAIL_TARGET_ATTEMPTS = 3;
+    // CB-641: Match the injector's 60s readiness gate so health allows a full first boot.
+    static final long READINESS_GRACE_NANOS = TimeUnit.SECONDS.toNanos(60);
+    /**
+     * fleetd #280: how long after a terminal transition to wait before the one bounded re-check
+     * fires. Must exceed the worst-case reverse-rendezvous {@code fleet_ask} window (55-115s, see
+     * {@code FleetMcp.ASK_DEFAULT_TIMEOUT_MS} / {@code FleetApp.MAX_ASK_TIMEOUT_MS}) so that, if the
+     * target was genuinely {@code ASKING} when {@code state} was first observed, its own ask has had
+     * time to lapse (clearing {@code Task#question} back to {@code null}) before this fires.
+     */
+    static final long ASK_LAPSE_RECHECK_DELAY_SECONDS = 120;
+
+    private final AgentControl agents;
+    private final Supplier<List<MemberSession>> roster;
+    private final MessageService messages;
+    private final ScheduledExecutorService scheduler;
+    private final LongSupplier clock;
+    private final long intervalSeconds;
+    private final long workingSuspectAfterNanos;
+    private final BiConsumer<String, String> failTarget;
+    private final Map<String, HealthPrior> priors = new HashMap<>();
+    /**
+     * The live classification per member, and the only one of this class's three maps that more
+     * than one scheduler task touches. {@code tick} writes it (and prunes it to the roster);
+     * fleetd #280's delayed {@link #recheckTerminalTarget} reads it from its own separate scheduled
+     * task. Both run on the single-threaded scheduler {@code Fleetd} passes in today, so they are
+     * serialised — but nothing in this class enforces that, and an unsynchronised {@link HashMap}
+     * read racing a resize can spin a CPU forever rather than fail visibly. {@code priors} and
+     * {@code orphanStreaks} stay plain maps because {@code tick} is still their only toucher.
+     */
+    private final Map<String, HealthState> states = new ConcurrentHashMap<>();
+    /**
+     * CB-643: consecutive ticks on which a target looked like an orphaned delegation. The fact
+     * {@link MessageService#hasOrphanedDelegation} reports is a true snapshot, but it can read true
+     * for one tick during an ordinary race — an async ticket exists before its virtual thread has
+     * reached {@code rendezvous.open()}, so for that instant nothing is accepted or queued behind
+     * it. {@code decide} maps the field straight to {@code DELEGATION_ORPHANED} with no cross-tick
+     * smoothing of its own, so a single racy read would log a fault that clears on the next tick.
+     * Requiring two consecutive observations costs one interval of latency on a real orphan and
+     * removes that false positive entirely.
+     */
+    private final Map<String, Integer> orphanStreaks = new HashMap<>();
+
+    /** How many consecutive ticks a target must look orphaned before health reports it (CB-643). */
+    static final int ORPHAN_CONFIRM_TICKS = 2;
+
+    // CB-643: every HealthSnapshot field now carries real evidence. The NOT_YET_OBSERVED placeholder
+    // that stood in for 7 of the 12 is gone, and with it the reason 8 of the 9 fault states were
+    // unreachable — GONE and NEVER_READY included, which is what kept CB-580's failTarget from ever
+    // firing. Do not reintroduce a constant here: a field with no publisher is a dead state, and the
+    // tests pass either way, so nothing else will tell you.
+
+    /**
+     * @param failTarget CB-568's idempotent target-wide failure operation (e.g. {@code messages::abandon}),
+     *                   invoked once when a member transitions into a terminal health state. Required —
+     *                   there is deliberately no defaulting overload; a caller that does not want the
+     *                   fail-tickets-on-terminal-health behavior must pass an explicit inert value (see
+     *                   {@code TestTurnTokens.inert} / {@code FleetMcp.CapacitySource.none()} for the pattern).
+     */
+    public FleetHealthMonitor(AgentControl agents, Supplier<List<MemberSession>> roster, MessageService messages,
+                              ScheduledExecutorService scheduler, LongSupplier clock, long intervalSeconds,
+                              long workingSuspectAfterSeconds, BiConsumer<String, String> failTarget) {
+        this.agents = agents;
+        this.roster = roster;
+        this.messages = messages;
+        this.scheduler = scheduler;
+        this.clock = clock;
+        this.intervalSeconds = intervalSeconds;
+        this.workingSuspectAfterNanos = TimeUnit.SECONDS.toNanos(workingSuspectAfterSeconds);
+        this.failTarget = Objects.requireNonNull(failTarget, "failTarget");
+    }
+
+    /** Pure per-member decision seam. */
+    static HealthDecision decide(HealthSnapshot snapshot, HealthPrior prior, long nowNanos) {
+        return FleetHealth.decide(snapshot, prior, nowNanos);
+    }
+
+    public void start() { scheduler.schedule(this::tick, intervalSeconds, TimeUnit.SECONDS); }
+    public void stop() { scheduler.shutdownNow(); }
+
+    // Package-private so tests can run one tick without waiting.
+    void tick() {
+        try {
+            List<MemberSession> rosterNow = roster.get(); // One in-memory roster snapshot for this tick.
+            List<Agent> agentsNow;
+            boolean controlLinkDown = false;
+            try {
+                agentsNow = agents.list(); // Exactly one list call for this complete observation.
+            } catch (HerdrException error) {
+                agentsNow = List.of();
+                controlLinkDown = true;
+                log.warn("fleet health control link unavailable; classifying roster", error);
+            }
+            Map<String, Agent> live = new HashMap<>();
+            for (Agent agent : agentsNow) live.put(agent.terminalId(), agent);
+            HashSet<String> current = new HashSet<>();
+            long nowNanos = clock.getAsLong();
+            for (MemberSession session : rosterNow) {
+                current.add(session.terminalId());
+                Agent agent = live.get(session.terminalId());
+                AgentStatus status = agent == null ? AgentStatus.UNKNOWN : agent.status();
+                boolean accepted = messages.hasAcceptedDelivery(session.terminalId());
+                boolean present = agent != null;
+                boolean targetNotFound = !controlLinkDown && !present
+                        && session.state() != MemberSession.State.SPAWNING;
+                boolean readinessGraceElapsed = nowNanos - session.spawnedAtNanos() >= READINESS_GRACE_NANOS;
+                boolean stalled = session.state() == MemberSession.State.BUSY
+                        && nowNanos - session.lastActivityAtNanos() >= workingSuspectAfterNanos;
+                // CB-643: the three message-layer facts CB-640 published. Read them here rather than
+                // leaving them false — that constant is what made 8 of the 9 fault states dead.
+                boolean queuedDelivery = messages.hasQueuedDelivery(session.terminalId());
+                boolean replyStranded = messages.hasStrandedReply(session.terminalId());
+                boolean orphanedDelegation = confirmOrphan(session.terminalId(),
+                        messages.hasOrphanedDelegation(session.terminalId()));
+                HealthSnapshot snapshot = new HealthSnapshot(session.state(), status, accepted, queuedDelivery,
+                        messages.hasInboxMessage(session.terminalId()), present, targetNotFound, controlLinkDown,
+                        readinessGraceElapsed, orphanedDelegation, replyStranded, stalled);
+                HealthDecision decision = decide(snapshot, priors.getOrDefault(session.terminalId(), HealthPrior.NONE),
+                        nowNanos);
+                priors.put(session.terminalId(), decision.prior());
+                reportTransition(session.terminalId(), decision.state());
+            }
+            priors.keySet().retainAll(current);
+            states.keySet().retainAll(current);
+            orphanStreaks.keySet().retainAll(current);
+        } catch (Throwable error) {
+            // Any unclassified collection failure must never kill the monitor's only scheduler task.
+            log.warn("fleet health collection failed; will retry next tick", error);
+        } finally {
+            if (!scheduler.isShutdown()) {
+                scheduler.schedule(this::tick, intervalSeconds, TimeUnit.SECONDS);
+            }
+        }
+    }
+
+    /**
+     * Debounce {@link MessageService#hasOrphanedDelegation} across ticks (CB-643). Returns true only
+     * once {@code observed} has held for {@link #ORPHAN_CONFIRM_TICKS} consecutive ticks; a single
+     * false reading resets the streak, so a transient race never reaches the classifier.
+     */
+    private boolean confirmOrphan(String target, boolean observed) {
+        if (!observed) {
+            orphanStreaks.remove(target);
+            return false;
+        }
+        int streak = orphanStreaks.merge(target, 1, Integer::sum);
+        return streak >= ORPHAN_CONFIRM_TICKS;
+    }
+
+    void reportTransition(String target, HealthState next) {
+        HealthState previous = states.put(target, next);
+        if (previous == next) return;
+        if (fault(next)) {
+            log.warn("fleet health member={} state={} previous={}", target, next, previous);
+        } else if (previous != null && fault(previous)) {
+            log.info("fleet health member={} recovered state={} previous={}", target, next, previous);
+        }
+        // CB-580: a member entering GONE/NEVER_READY must not leave its waiting tickets pending
+        // forever. Fire exactly once per transition — never on a tick where the state is unchanged,
+        // which is what made the rejected commit call abandon() once per tick for as long as a
+        // member stayed terminal.
+        if (terminal(next)) {
+            failTerminalTarget(target, next);
+            scheduleTerminalRecheck(target, next);
+        }
+    }
+
+    private void failTerminalTarget(String target, HealthState state) {
+        String reason = "fleet health: member reached terminal state " + state.name();
+        RuntimeException last = null;
+        for (int attempt = 1; attempt <= MAX_FAIL_TARGET_ATTEMPTS; attempt++) {
+            try {
+                failTarget.accept(target, reason);
+                return;
+            } catch (RuntimeException error) {
+                last = error;
+                log.warn("fleet health: failTarget attempt {}/{} failed for member={} state={}",
+                        attempt, MAX_FAIL_TARGET_ATTEMPTS, target, state, error);
+            }
+        }
+        log.warn("fleet health: giving up on failTarget for member={} state={} after {} attempts",
+                target, state, MAX_FAIL_TARGET_ATTEMPTS, last);
+    }
+
+    /**
+     * fleetd #280: schedule the one bounded, delayed follow-up for a terminal transition — never a
+     * per-tick retry (CB-580 rejected that shape; {@link #reportTransition} still fires
+     * {@link #failTerminalTarget} exactly once per transition, unconditionally on the tick loop).
+     * This is a single one-shot task, scheduled once per transition into GONE/NEVER_READY, so a
+     * member stuck terminal for the rest of its life gets exactly one extra attempt, not one per
+     * tick. See {@link #recheckTerminalTarget} for why the extra attempt is safe.
+     */
+    private void scheduleTerminalRecheck(String target, HealthState state) {
+        if (scheduler.isShutdown()) return;
+        try {
+            scheduler.schedule(() -> recheckTerminalTarget(target, state),
+                    ASK_LAPSE_RECHECK_DELAY_SECONDS, TimeUnit.SECONDS);
+        } catch (RuntimeException e) {
+            log.warn("fleet health: could not schedule terminal re-check for member={} state={}",
+                    target, state, e);
+        }
+    }
+
+    /**
+     * fleetd #280: the delayed re-check {@link #scheduleTerminalRecheck} scheduled for one terminal
+     * transition. By now, a {@code fleet_ask} that was still open when {@code state} was first
+     * observed has had time to lapse on its own (see {@link #ASK_LAPSE_RECHECK_DELAY_SECONDS}),
+     * clearing {@code Task#question} back to {@code null} — which is exactly what
+     * {@link MessageService#abandon(String, String, boolean)}'s {@code sweepAsking=false} filter
+     * needs to finally match it. Calling {@link #failTerminalTarget} again is safe only because
+     * {@code sweepAsking} stays {@code false}: a task genuinely still {@code ASKING} is skipped
+     * exactly as it was on the very first attempt — this never fails a ticket whose ask has not yet
+     * lapsed.
+     *
+     * <p><strong>Guarded on "target is still classified {@code state}."</strong> Without this guard,
+     * a member that recovered (or was released and dropped from the roster) between the transition
+     * and this re-check would still take a blind {@code failTarget} call — reaching into whatever
+     * brand-new, unrelated turn it has since picked up and failing it too. {@link #states} already
+     * carries the live classification (updated every tick, pruned to the current roster on release),
+     * so a stale or recovered target simply reads as a mismatch here and this is a no-op.
+     */
+    void recheckTerminalTarget(String target, HealthState state) {
+        if (states.get(target) != state) return;
+        failTerminalTarget(target, state);
+    }
+
+    private static boolean terminal(HealthState state) {
+        return state == HealthState.GONE || state == HealthState.NEVER_READY;
+    }
+
+    private static boolean fault(HealthState state) {
+        return switch (state) {
+            case NEVER_READY, GONE, TURN_BOUNDARY_LOST, ERROR_ON_SCREEN, STALL_SUSPECTED,
+                    MUTE, REPLY_STRANDED, DELEGATION_ORPHANED, CONTROL_LINK_DOWN -> true;
+            default -> false;
+        };
+    }
+
+    public static String coverage(boolean enabled, boolean notificationConfigured) {
+        return !enabled ? "off" : notificationConfigured ? "full" : "detection-only";
+    }
+}