fleetd #184: correct sshAuthSock guidance

The merged fix told the operator to look in journalctl for
"Fleetd.reportRequiredSecrets". That string never appears there — it is a
method name. The logger is d.l.f.Fleetd and the lines read
"startup secret NAME: set|MISSING", so the advice sent the operator looking
for text that does not exist.

Give the grep instead, and say what the report does not cover: it lists only
names a configured profile references, so a secret nothing references is never
reported.

deploy/fleetd.service

@@ -31,11 +31,27 @@ Environment=HERDR_SOCKET_PATH=%h/.config/herdr/herdr.sock
 # 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 the API/worker tokens in a private
-# drop-in that systemd reads with restrictive permissions:
-#   systemctl --user edit fleetd     →  [Service] / Environment=FLEETD_API_TOKEN=...
-# or point EnvironmentFile at a 0600 file:
+# 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

fleetd/fleetd.example.yaml

@@ -306,6 +306,41 @@ 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)
@@ -503,6 +538,23 @@ fleet:
   # 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
@@ -624,13 +676,15 @@ guard:
 #            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.
-#   sshAuthSock → whether SSH_AUTH_SOCK may pass through under allow-list ("allow") or must be
-#            blanked like any other non-derived name ("block", the default). This is a decision you
-#            have to make explicitly: SSH_AUTH_SOCK is a handle to YOUR ssh-agent, and a member
-#            holding it can sign with your keys — it sits in no secret file and looks like no
-#            credential, which is why it slipped past three earlier tickets (gitea #110). Blocking
-#            it breaks git over SSH inside members (push/fetch authenticate as you); use HTTPS
-#            remotes or scoped deploy keys instead of allowing it lightly.
+#   sshAuthSock → whether SSH_AUTH_SOCK may pass through under allow-list ("allow") or is omitted
+#            from the member environment ("block", the default). Blocking 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.
 #
 # 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

fleetd/src/main/java/dev/ltms/fleet/Fleetd.java

@@ -641,7 +641,8 @@ public final class Fleetd {
                 new FleetMcp.OutageSource(profile -> {
                     var configured = config.get().profiles().get(profile);
                     return configured == null ? null : configured.effectiveCredentialId();
-                }, outagePolicy));
+                }, outagePolicy),
+                new FleetMcp.LeadSeatSource(leadSeatLookup(() -> config.get().profiles(), leaders, leads)));
 
         // CB-637: the receive half. Only constructed when a lead mailbox actually opened — with no
         // coordinator (or an unreachable one) there is nothing to deliver, so no scheduler is
@@ -769,6 +770,68 @@ public final class Fleetd {
                 .orElse(null);
     }
 
+    /**
+     * fleetd #176: per-profile factory for {@link FleetMcp.LeadSeatSource} — how many seats a
+     * profile's own live LEAD session(s) hold on the same Claude subscription.
+     *
+     * <p>{@code maxLoad} counts only members; the lead itself is a live {@code claude} session that
+     * is never moved off-subscription ({@code LeadLauncher} strips {@code ANTHROPIC_BASE_URL}/
+     * {@code AUTH_TOKEN} from a lead's env whatever its profile says), so a {@code subscription:
+     * true} profile's real ceiling is lower than its configured {@code maxLoad} by exactly the
+     * number of lead seats sharing that same account.
+     *
+     * <p><b>The derivation, and why this route was chosen over a new config key.</b> The link is
+     * {@code fleet.leaders.<name>.profile} — the field the operator already sets to name which
+     * {@code profiles:} entry a lead runs on (CB-557; see {@code fleetd.example.yaml}) — matched
+     * against the profile passed in here via {@link FleetConfig.Profile#effectiveCredentialId()},
+     * the same grouping key {@link dev.ltms.fleet.placement.BackendQuarantine} already uses to say
+     * two profiles share one account. Nothing new is added to the config schema: this reuses a field
+     * that already exists and already means "the profile this lead's own session runs on". A lead
+     * entry that names no {@code profile:} (recognise-only, CB-558) says nothing about which account
+     * it shares, and there is no other reliable signal on the daemon's side to derive that from — so
+     * such a lead contributes no seats, exactly as before this ticket. Making that lead's seat count
+     * requires the operator to add one line (`profile: sonnet` under its {@code fleet.leaders} entry)
+     * — a config statement, not a code change, and the smallest one available given the field
+     * already exists for a closely related purpose.
+     *
+     * <p>Only counts leads {@code liveLeadTerminals} currently reports — CB-531's live tab scan (or
+     * the legacy {@code primary.terminal} pin) — never every configured lead: an entry whose
+     * {@code instances} nobody has actually started is not really competing for a seat, and must not
+     * shrink capacity for one that was never live.
+     *
+     * @param profiles          the live profile map, normally {@code () -> config.get().profiles()}
+     *                          in {@code main} — hot, like every other {@code maxLoad}/
+     *                          {@code credentialId} read {@link FleetMcp.CapacitySource} already does
+     * @param leaders           {@code fleet.leaders}, read once at startup like the rest of that
+     *                          block ({@code fleetd.example.yaml} notes it is not hot) — passed as a
+     *                          plain map, never re-read from {@code config.get()}
+     * @param liveLeadTerminals terminal_id → lead name for every CURRENTLY recognised lead, normally
+     *                          the same supplier {@link dev.ltms.fleet.auth.CallerResolver#leads()}
+     *                          and {@code LeadCoordLoop} already consult
+     */
+    static Function<String, Integer> leadSeatLookup(Supplier<Map<String, FleetConfig.Profile>> profiles,
+            Map<String, FleetConfig.Leader> leaders, Supplier<Map<String, String>> liveLeadTerminals) {
+        return profileName -> {
+            FleetConfig.Profile target = profiles.get().get(profileName);
+            if (target == null || !target.isSubscription()) {
+                return 0;
+            }
+            String targetCredential = target.effectiveCredentialId();
+            int seats = 0;
+            for (String leadName : liveLeadTerminals.get().values()) {
+                FleetConfig.Leader lead = leaders.get(leadName);
+                if (lead == null || lead.profile() == null || lead.profile().isBlank()) {
+                    continue;
+                }
+                FleetConfig.Profile leadProfile = profiles.get().get(lead.profile());
+                if (leadProfile != null && targetCredential.equals(leadProfile.effectiveCredentialId())) {
+                    seats++;
+                }
+            }
+            return seats;
+        };
+    }
+
     /**
      * fleetd #248 / fleetd#201 Unit 5: package-private factory for the per-target backend-error
      * pattern lookup {@link CompletionResolver} classifies a pane scrape against. Closes over the

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

@@ -92,9 +92,15 @@ import java.util.regex.PatternSyntaxException;
  *                      fleetd's own process, so fleetd's own {@code $SHELL} says nothing about what
  *                      that pane runs. There is no channel to ask herdr for another user's shell, so
  *                      this must be told, never guessed. {@code null}/blank (or a value not ending
- *                      in {@code zsh}) is treated the same as "not zsh": the {@code
- *                      memberCredentials.policy: allow-list} ZDOTDIR scrub is skipped in favour of
- *                      the CB-596 sentinel overlay — a degraded control, never a refusal to spawn.
+ *                      in {@code zsh}) is treated the same as "not zsh". fleetd #155: what that means
+ *                      now depends on {@code memberCredentials.policy}. Under {@code deny-by-default}
+ *                      it stays a degraded control, never a refusal to spawn — the pane-creation
+ *                      overlay is unaffected by shell type, so the spawn proceeds with a WARN naming
+ *                      the shell. Under {@code allow-list} the spawn is REFUSED instead: that policy's
+ *                      whole point is a control a sourced file cannot undo, so silently falling back
+ *                      to the weaker overlay would be the same "control silently does nothing" defect
+ *                      #155 exists to remove — configure this field (or move the account to zsh, or
+ *                      switch policy back to {@code deny-by-default}) to unblock the spawn.
  *                      When {@code memberHerdrSocket} is NOT configured this field is never
  *                      consulted at all; fleetd keeps reading its own {@code $SHELL}, exactly as
  *                      before this field existed.
@@ -644,14 +650,46 @@ public record FleetConfig(
         }
 
         /**
-         * The credential group this profile quarantines with (CB-578 stage B): the configured
-         * {@link #credentialId} when set, else this profile's own name — so an unconfigured profile
-         * quarantines alone, exactly as it did before this field existed. Two profiles that set the
-         * same non-blank {@code credentialId} share one quarantine: a {@code BACKEND_EXHAUSTED}
-         * classification on either one quarantines both.
+         * The shared credential id every {@code subscription: true} profile falls back to when it
+         * sets no explicit {@link #credentialId} (fleetd #176 stage 2, correcting an inert first cut
+         * of that ticket). A subscription profile has no credential of its own to fall back to its
+         * name for: it authenticates as the operator's own Claude login, and a host has exactly one
+         * of those, whatever names the operator gives the profiles running on it. Falling back to the
+         * profile's own name (the way an ordinary off-subscription profile does) would keep two
+         * subscription profiles on one login apart from each other, which is the opposite of what
+         * "one account" means.
+         *
+         * <p>Measured live and what it broke: a lead on profile {@code opus}, members on profile
+         * {@code sonnet}, same Claude login, neither setting {@code credentialId}. Before this
+         * sentinel, {@code opus.effectiveCredentialId()} was {@code "opus"} and {@code sonnet
+         * .effectiveCredentialId()} was {@code "sonnet"} — so fleetd #176's lead-seat matcher (and,
+         * this sentinel now also fixes, {@code CompositePeerLauncher}'s quarantine/cool-off spawn
+         * refusal and {@code BackendOutagePolicy}'s incident grouping) silently never linked them: the
+         * fix shipped, and stayed inert on the one host it was written for.
+         */
+        public static final String SUBSCRIPTION_CREDENTIAL_ID = "<subscription>";
+
+        /**
+         * The credential group this profile quarantines with (CB-578 stage B; extended fleetd #176
+         * stage 2 — see {@link #SUBSCRIPTION_CREDENTIAL_ID}): the configured {@link #credentialId}
+         * when set — that always wins, so an operator with two separate Claude logins on one host can
+         * still keep them apart. Otherwise, a {@code subscription: true} profile falls back to
+         * {@link #SUBSCRIPTION_CREDENTIAL_ID} rather than its own name; an ordinary off-subscription
+         * profile falls back to its own name, exactly as it did before this field existed, so an
+         * unconfigured off-subscription profile still quarantines alone.
+         *
+         * <p>A {@code BACKEND_EXHAUSTED} (or repeated backend-error) classification on any profile
+         * sharing the result quarantines/cools off every profile that shares it — including, now,
+         * every {@code subscription: true} profile with no explicit {@code credentialId}. That is
+         * intended, not incidental: one Claude subscription hitting a usage limit really does take out
+         * every profile running on it, the same way {@code credentialId: openai-shared} already lets
+         * two OpenAI-backed profiles share one quarantine.
          */
         public String effectiveCredentialId() {
-            return (credentialId == null || credentialId.isBlank()) ? profile : credentialId;
+            if (credentialId != null && !credentialId.isBlank()) {
+                return credentialId;
+            }
+            return isSubscription() ? SUBSCRIPTION_CREDENTIAL_ID : profile;
         }
 
         /** True when this profile's workers are granted a forge token to open their own PR (CB-302). */
@@ -946,7 +984,15 @@ public record FleetConfig(
      * survives restarts of the agent inside it — so identity is now the tab label alone.
      *
      * @param profile             the {@code profiles:} entry to launch this lead on when one must
-     *                            be created; {@code null} ⇒ recognise-only, never create
+     *                            be created; {@code null} ⇒ recognise-only, never create.
+     *                            <p>fleetd #176: also the field {@code Fleetd.leadSeatLookup} reads
+     *                            to learn which account this lead's own live session shares — set it
+     *                            (safely, even on an already-running recognise-only lead: naming a
+     *                            profile here never starts anything beyond {@code instances}) so a
+     *                            {@code subscription: true} worker profile sharing its
+     *                            {@code effectiveCredentialId()} has this lead's seat subtracted from
+     *                            {@code fleet_list}'s {@code free}. {@code null} here also means this
+     *                            lead's seat cannot be derived and is not counted.
      * @param tab                 the exact tab label hosting this lead, matched case-insensitively;
      *                            the only field identity depends on. Required — a lead with no
      *                            {@code tab} can never be discovered, launched or not

fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java

@@ -96,6 +96,8 @@ public final class FleetMcp {
     private final QuarantineSource quarantine;
     /** fleetd #201 Unit 5: SEPARATE from {@link #quarantine} — see {@link OutageSource}'s doc. */
     private final OutageSource outage;
+    /** fleetd #176: SEPARATE from both of the above — see {@link LeadSeatSource}'s doc. */
+    private final LeadSeatSource leadSeats;
     /** CB-637: this daemon's lead-to-lead channel; {@code null} when no coordinator is configured. */
     private final LeadChannel leadChannel;
 
@@ -135,6 +137,32 @@ public final class FleetMcp {
         }
     }
 
+    /**
+     * fleetd #176: the seats a profile's own live LEAD session(s) hold on the same Claude
+     * subscription — a fact {@code fleet_list} reports alongside {@code free} via the
+     * {@code leadSeats} key.
+     *
+     * <p>{@code maxLoad} counts only <em>members</em>, never the lead itself. But a
+     * {@code subscription: true} profile bills the operator's own Claude account, and the lead is
+     * always a live {@code claude} session on that same account (it is never moved off-subscription
+     * — see {@code LeadLauncher}). See {@code Fleetd.leadSeatLookup} for how the count is derived —
+     * from {@code fleet.leaders.<name>.profile} and each profile's {@code effectiveCredentialId()},
+     * never a hardcoded constant.
+     *
+     * <p>fleetd #257: this count is reported, never subtracted from {@code free}. An earlier cut of
+     * this feature subtracted it, on the theory that it made {@code free} describe the real ceiling
+     * on the account — but the real spawn gate ({@code CompositePeerLauncher#enforceMaxLoad}) never
+     * read this count at all, so the subtraction made {@code free} disagree with the one thing it is
+     * supposed to describe: what a fresh {@code fleet_spawn} will actually get. No backend seat
+     * ceiling shared with the lead has been measured either — see {@code fleetd.example.yaml}'s
+     * {@code maxLoad} docs. {@code free} now always equals {@code max(0, maxLoad - live)}, and
+     * {@code leadSeats} is reported purely as a fact the caller may act on however it likes.
+     */
+    public record LeadSeatSource(Function<String, Integer> seatsFor) {
+        /** Inert source — no profile is ever reported as sharing a seat with a lead. */
+        public static LeadSeatSource none() { return new LeadSeatSource(_ -> 0); }
+    }
+
     /**
      * @param callers resolves each call's {@link Principal}; {@code null} disables authorization.
      *                This surface needs its own enforcement: {@code /mcp} is a raw servlet on
@@ -149,7 +177,7 @@ public final class FleetMcp {
                       CallerResolver callers, Metrics metrics, CapacitySource capacity, HealthCoverageSource healthCoverage,
                       QuarantineSource quarantine) {
         this(messages, workers, sessions, identity, presence, primaryRegistry, callers, metrics, capacity,
-                healthCoverage, quarantine, null, OutageSource.none());
+                healthCoverage, quarantine, null, OutageSource.none(), LeadSeatSource.none());
     }
 
     /**
@@ -163,12 +191,12 @@ public final class FleetMcp {
                       CallerResolver callers, Metrics metrics, CapacitySource capacity, HealthCoverageSource healthCoverage,
                       QuarantineSource quarantine, LeadChannel leadChannel) {
         this(messages, workers, sessions, identity, presence, primaryRegistry, callers, metrics, capacity,
-                healthCoverage, quarantine, leadChannel, OutageSource.none());
+                healthCoverage, quarantine, leadChannel, OutageSource.none(), LeadSeatSource.none());
     }
 
     /**
      * As above, with fleetd #201 Unit 5 cool-off facts for {@code fleet_list}/{@code fleet_profiles}
-     * (see {@link OutageSource}). This is what {@code Fleetd.main} actually wires up.
+     * (see {@link OutageSource}).
      *
      * @param outage required — pass {@link OutageSource#none()} for a caller that does not want the
      *               feature, never a defaulting overload (the same rule {@code quarantine} follows).
@@ -177,10 +205,28 @@ public final class FleetMcp {
                      ConnectionIdentity identity, MemberPresence presence, PrimaryRegistry primaryRegistry,
                       CallerResolver callers, Metrics metrics, CapacitySource capacity, HealthCoverageSource healthCoverage,
                       QuarantineSource quarantine, LeadChannel leadChannel, OutageSource outage) {
+        this(messages, workers, sessions, identity, presence, primaryRegistry, callers, metrics, capacity,
+                healthCoverage, quarantine, leadChannel, outage, LeadSeatSource.none());
+    }
+
+    /**
+     * As above, with fleetd #176 lead-seat facts (see {@link LeadSeatSource}). This is what
+     * {@code Fleetd.main} actually wires up.
+     *
+     * @param leadSeats required — pass {@link LeadSeatSource#none()} for a caller that does not want
+     *                  the feature, never a defaulting overload (the same rule {@code quarantine} and
+     *                  {@code outage} follow).
+     */
+    public FleetMcp(MessageService messages, PeerLauncher workers, SessionManager sessions,
+                     ConnectionIdentity identity, MemberPresence presence, PrimaryRegistry primaryRegistry,
+                      CallerResolver callers, Metrics metrics, CapacitySource capacity, HealthCoverageSource healthCoverage,
+                      QuarantineSource quarantine, LeadChannel leadChannel, OutageSource outage,
+                      LeadSeatSource leadSeats) {
         this.leadChannel = leadChannel;
         this.capacity = capacity;
         this.quarantine = Objects.requireNonNull(quarantine, "quarantine");
         this.outage = Objects.requireNonNull(outage, "outage");
+        this.leadSeats = Objects.requireNonNull(leadSeats, "leadSeats");
         this.healthCoverage = healthCoverage;
         McpJsonMapper json = new JacksonMcpJsonMapperSupplier().get();
         this.transport = HttpServletStreamableServerTransportProvider.builder()
@@ -310,7 +356,7 @@ public final class FleetMcp {
                     McpSchema.CallToolResult denied = deny(exchange, Authz.Action.READ, null);
                     if (denied != null) return denied;
                     return listFleet(workers, sessions, messages, capacity, healthCoverage, quarantine, outage,
-                            callers == null ? Map.of() : callers.leads(),
+                            leadSeats, callers == null ? Map.of() : callers.leads(),
                             callerTerminal(exchange),
                             leadChannel == null ? null : leadChannel.selfCoordId());
                 };
@@ -994,7 +1040,8 @@ public final class FleetMcp {
                                                CapacitySource capacity, HealthCoverageSource healthCoverage,
                                                QuarantineSource quarantine, OutageSource outage,
                                                Map<String, String> leads, String selfTerm) {
-        return listFleet(workers, sessions, messages, capacity, healthCoverage, quarantine, outage, leads, selfTerm, null);
+        return listFleet(workers, sessions, messages, capacity, healthCoverage, quarantine, outage,
+                LeadSeatSource.none(), leads, selfTerm, null);
     }
 
     /**
@@ -1011,7 +1058,7 @@ public final class FleetMcp {
                                                QuarantineSource quarantine, Map<String, String> leads, String selfTerm,
                                                String selfCoordId) {
         return listFleet(workers, sessions, messages, capacity, healthCoverage, quarantine, OutageSource.none(),
-                leads, selfTerm, selfCoordId);
+                LeadSeatSource.none(), leads, selfTerm, selfCoordId);
     }
 
     /** As above, plus fleetd #201 Unit 5 cool-off facts (see {@link OutageSource}). */
@@ -1019,6 +1066,16 @@ public final class FleetMcp {
                                                CapacitySource capacity, HealthCoverageSource healthCoverage,
                                                QuarantineSource quarantine, OutageSource outage,
                                                Map<String, String> leads, String selfTerm, String selfCoordId) {
+        return listFleet(workers, sessions, messages, capacity, healthCoverage, quarantine, outage,
+                LeadSeatSource.none(), leads, selfTerm, selfCoordId);
+    }
+
+    /** As above, plus fleetd #176 lead-seat facts (see {@link LeadSeatSource}). */
+    static McpSchema.CallToolResult listFleet(PeerLauncher workers, SessionManager sessions, MessageService messages,
+                                               CapacitySource capacity, HealthCoverageSource healthCoverage,
+                                               QuarantineSource quarantine, OutageSource outage,
+                                               LeadSeatSource leadSeats, Map<String, String> leads, String selfTerm,
+                                               String selfCoordId) {
         try {
             Map<String, Agent> live = workers.list().stream()
                     .map(Agent.class::cast)
@@ -1045,7 +1102,7 @@ public final class FleetMcp {
             }
             if (capacity.available()) result.put("capacity", profiles.stream()
                     .map(profile -> capacityView(profile, capacity.liveCount(), capacity.maxLoad(), roster, messages,
-                            capacity.clock().getAsLong(), quarantine, outage)).toList());
+                            capacity.clock().getAsLong(), quarantine, outage, leadSeats)).toList());
             return text(json(result));
         } catch (HerdrException e) {
             return error("herdr error listing the fleet: " + e.getMessage());
@@ -1084,20 +1141,45 @@ public final class FleetMcp {
      * {@code credentialId}/{@code coolingOffForSeconds}, but never {@code quarantinedForSeconds} —
      * that key is added only when exhaustion quarantine is ALSO active for this profile, since the
      * two checks are independent and either, both, or neither can be true.
+     *
+     * <p>fleetd #176: {@code maxLoad} counts panes, not subscription seats — it never counted the
+     * lead's own seat on a {@code subscription: true} profile's account. {@link LeadSeatSource}
+     * reports that count (0 for a non-subscription profile, or when no live lead shares its
+     * credential) via the {@code leadSeats} key, added only when the count is positive, for the
+     * same byte-identical-when-unused reason as the quarantine/cool-off keys above.
+     *
+     * <p>fleetd #257: {@code leadSeatCount} is reported, never subtracted from {@code free}.
+     * {@code free} means "what a fresh {@code fleet_spawn} on this profile will actually get", and
+     * the real gate ({@code CompositePeerLauncher#enforceMaxLoad}) only ever compares {@code live}
+     * against {@code maxLoad} — it has no notion of a lead's own seat. Subtracting
+     * {@code leadSeatCount} here made {@code free} disagree with the gate it is supposed to
+     * describe: it could report {@code free: 0} while a spawn on that exact profile still
+     * succeeded. {@code leadSeats} stays in the row as a fact the caller can act on however it
+     * likes, but it no longer changes what {@code free} means.
      */
     private static Map<String, Object> capacityView(String profile, Function<String, Integer> liveCount,
                                                      Function<String, Integer> maxLoad, List<MemberSession> roster,
                                                      MessageService messages, long nowNanos, QuarantineSource quarantine,
-                                                     OutageSource outage) {
+                                                     OutageSource outage, LeadSeatSource leadSeats) {
         Integer cap = maxLoad.apply(profile);
         int live = liveCount.apply(profile);
+        int leadSeatCount = leadSeats.seatsFor().apply(profile);
         int reclaimable = (int) roster.stream().filter(s -> profile.equals(s.profile()))
                 .filter(s -> (s.state() == MemberSession.State.READY || s.state() == MemberSession.State.DONE))
                 .filter(s -> messages == null || (!messages.hasAcceptedDelivery(s.terminalId()) && !messages.hasInboxMessage(s.terminalId())))
                 .count();
         Map<String, Object> row = new LinkedHashMap<>();
         row.put("profile", profile); row.put("maxLoad", cap); row.put("live", live);
-        row.put("free", cap == null ? null : Math.max(0, cap - live)); row.put("reclaimable", reclaimable);
+        // fleetd #257: free must report what the real spawn gate (CompositePeerLauncher#enforceMaxLoad)
+        // will actually grant, and that gate never reads leadSeatCount — only maxLoad and live. Not
+        // subtracting the lead's seat here used to make free UNDERSTATE what a fresh fleet_spawn would
+        // get, so a lead believing free:0 gave up on a profile the gate would still spawn onto.
+        // leadSeatCount is still reported via the leadSeats key below, just never subtracted from free.
+        row.put("free", cap == null ? null : Math.max(0, cap - live));
+        row.put("reclaimable", reclaimable);
+        if (leadSeatCount > 0) {
+            row.put("leadSeats", leadSeatCount);
+        }
         String credentialId = quarantine.credentialIdFor().apply(profile);
         if (credentialId != null) {
             quarantine.quarantine().remainingSeconds(credentialId).ifPresent(remaining -> {
@@ -1298,8 +1380,13 @@ public final class FleetMcp {
                         + "member spawned without one shares its directory with others and never reports "
                         + "an id, however long it runs (fleetd #249). An empty 'members' "
                         + "means no members are spawned; it says nothing about peers. When capacity "
-                        + "facts are configured, a 'capacity' row per profile also reports free: 0 for "
-                        + "a quarantined profile's credential (see fleet_profiles), whatever its "
+                        + "facts are configured, a 'capacity' row per profile reports 'free' — the "
+                        + "slots a fresh fleet_spawn on that profile will actually be granted right "
+                        + "now (max(0, maxLoad - live)), the same check the spawn gate itself runs. A "
+                        + "'leadSeats' key, when present, reports how many of those live slots are a "
+                        + "lead session sharing this profile's subscription — informational only, "
+                        + "already NOT subtracted from 'free' (fleetd #257). It also reports free: 0 "
+                        + "for a quarantined profile's credential (see fleet_profiles), whatever its "
                         + "maxLoad/live — with credentialId and quarantinedForSeconds naming the "
                         + "quarantine, so 'free: 0, busy' can be told apart from 'free: 0, refusing "
                         + "for N seconds'.",

fleetd/src/main/java/dev/ltms/fleet/member/ClaudeCodeLauncher.java

@@ -19,6 +19,7 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
 import java.nio.file.attribute.PosixFileAttributeView;
+import java.util.Arrays;
 import java.util.EnumSet;
 import java.util.List;
 import java.util.Map;
@@ -519,6 +520,26 @@ public final class ClaudeCodeLauncher extends HerdrPeerLauncher {
      * the first. Both exist because of a real incident: see {@link HerdrPeerLauncher#isProvisionedWorktree}'s javadoc
      * and {@link #writeAtomically}'s javadoc.
      *
+     * <p><b>Compare-and-swap against a writer the lock cannot reach (fleetd #247).</b>
+     * {@code TRUST_JSON_LOCK} only serialises calls this launcher itself makes inside this one JVM.
+     * It does nothing about a writer outside it — and on a host where the profile's
+     * {@code configDir} is the operator's own {@code CLAUDE_CONFIG_DIR}, the file this method writes
+     * IS the operator's own live Claude Code session's config file, being read and written by that
+     * session while it runs. Measured 2026-09-03: its mtime moved minutes after a spawn while that
+     * session was active. A plain read-modify-write there is a routine lost update, not a rare one:
+     * fleetd reads v1, the operator's session reads v1 and writes v2 with their own change, fleetd's
+     * {@code ATOMIC_MOVE} then lands v3 built from v1 — atomic, but v2's change is gone. So before
+     * the move this method re-reads {@code target}'s exact bytes and compares them with the bytes it
+     * built its update from; a mismatch means someone else wrote in between, and it discards its
+     * work and rebuilds from the fresh bytes, up to {@link #MAX_TRUST_JSON_CAS_ATTEMPTS} times.
+     * <b>Exhausting the retries writes nothing</b> — see the WARN at the end of the loop for why
+     * that, not a last write-anyway, is the safe failure: the member shows the trust dialog and
+     * fails to reach an injectable state, which is visible, logged and recoverable; overwriting the
+     * operator's live config with a stale copy is neither. This narrows the lost-update window, it
+     * does not close it — a write landing between the final re-read and the {@code ATOMIC_MOVE}
+     * itself is still lost, because there is no OS-level compare-and-swap on a plain file, only this
+     * cooperative narrowing of the gap.
+     *
      * @param configDir the profile's {@code CLAUDE_CONFIG_DIR} ({@code cfg.configDir()}), or
      *                  {@code null}/blank to target the default {@code ~/.claude.json}
      * @param cwd       the spawn's resolved working directory — the exact key Claude Code will look
@@ -528,55 +549,118 @@ public final class ClaudeCodeLauncher extends HerdrPeerLauncher {
         if (!isProvisionedWorktree(cwd)) {
             return;
         }
-        Path target = (configDir == null || configDir.isBlank())
+        boolean unsetConfigDir = configDir == null || configDir.isBlank();
+        Path target = unsetConfigDir
                 ? Path.of(System.getProperty("user.home"), ".claude.json")
                 : Path.of(configDir, ".claude.json");
+        if (unsetConfigDir) {
+            // fleetd #247: configDir unset is the ONLY path that targets ~/.claude.json — the
+            // operator's own home file, not a per-profile one — and it is the default, so a
+            // profile that simply forgot to set configDir gets no signal at all short of the
+            // operator noticing their own file changing. Say so loudly, every time it is about to
+            // happen, rather than only once ever: each occurrence is a live write to a real
+            // person's home config and deserves its own log line.
+            log.warn("seedTrustDialog: profile has no configDir set, so the workspace-trust seed "
+                    + "for cwd '{}' is about to write the operator's own default '{}' — set "
+                    + "configDir on this profile to target a per-member config file instead",
+                    cwd, target);
+        }
         synchronized (TRUST_JSON_LOCK) {
             try {
                 if (target.getParent() != null) {
                     Files.createDirectories(target.getParent());
                 }
-                ObjectNode root = null;
-                if (Files.isRegularFile(target)) {
-                    JsonNode existing = TRUST_JSON.readTree(target.toFile());
-                    if (existing instanceof ObjectNode existingObject) {
-                        root = existingObject;
+                for (int attempt = 1; attempt <= MAX_TRUST_JSON_CAS_ATTEMPTS; attempt++) {
+                    byte[] before = Files.isRegularFile(target) ? Files.readAllBytes(target) : null;
+                    ObjectNode root = parseTrustJsonOrEmpty(before);
+                    JsonNode projectsNode = root.get("projects");
+                    ObjectNode projects = projectsNode instanceof ObjectNode projectsObject
+                            ? projectsObject : TRUST_JSON.createObjectNode();
+                    if (!(projectsNode instanceof ObjectNode)) {
+                        root.set("projects", projects);
                     }
+                    JsonNode projectNode = projects.get(cwd);
+                    ObjectNode project = projectNode instanceof ObjectNode projectObject
+                            ? projectObject : TRUST_JSON.createObjectNode();
+                    if (!(projectNode instanceof ObjectNode)) {
+                        projects.set(cwd, project);
+                    }
+                    // fleetd #247: ONLY hasTrustDialogAccepted. We used to write
+                    // hasCompletedProjectOnboarding beside it; do not put it back. Measured on
+                    // 2026-09-03, minutes after a live spawn seeded this file: 28 of 28 project
+                    // entries carried hasTrustDialogAccepted and 0 of 28 carried the onboarding key
+                    // — including the 27 entries Claude Code wrote for itself. Claude Code
+                    // normalises the whole file when it saves and drops that key every time, so
+                    // writing it achieved nothing except making the next reader think it mattered.
+                    // The member reached idle with the trust flag alone, which is the only outcome
+                    // this seed exists for. If a future Claude Code needs the second flag the
+                    // symptom returns as the trust dialog fleetd #149 describes — re-measure then,
+                    // do not restore it on a guess.
+                    project.put("hasTrustDialogAccepted", true);
+                    String newContent = TRUST_JSON.writerWithDefaultPrettyPrinter().writeValueAsString(root);
+
+                    trustJsonCasTestHook.run();
+
+                    // fleetd #247 CAS: re-read immediately before the move and compare with what
+                    // this attempt built its update from. A mismatch means another writer (most
+                    // plausibly the operator's own live Claude Code — see this method's javadoc)
+                    // landed a change in between; discard this attempt's work and rebuild from the
+                    // fresh bytes rather than blindly overwriting it.
+                    byte[] atMove = Files.isRegularFile(target) ? Files.readAllBytes(target) : null;
+                    if (!Arrays.equals(before, atMove)) {
+                        continue;
+                    }
+                    writeAtomically(target, newContent);
+                    return;
                 }
-                if (root == null) {
-                    root = TRUST_JSON.createObjectNode();
-                }
-                JsonNode projectsNode = root.get("projects");
-                ObjectNode projects = projectsNode instanceof ObjectNode projectsObject
-                        ? projectsObject : TRUST_JSON.createObjectNode();
-                if (!(projectsNode instanceof ObjectNode)) {
-                    root.set("projects", projects);
-                }
-                JsonNode projectNode = projects.get(cwd);
-                ObjectNode project = projectNode instanceof ObjectNode projectObject
-                        ? projectObject : TRUST_JSON.createObjectNode();
-                if (!(projectNode instanceof ObjectNode)) {
-                    projects.set(cwd, project);
-                }
-                // fleetd #247: ONLY hasTrustDialogAccepted. We used to write
-                // hasCompletedProjectOnboarding beside it; do not put it back. Measured on
-                // 2026-09-03, minutes after a live spawn seeded this file: 28 of 28 project
-                // entries carried hasTrustDialogAccepted and 0 of 28 carried the onboarding key
-                // — including the 27 entries Claude Code wrote for itself. Claude Code
-                // normalises the whole file when it saves and drops that key every time, so
-                // writing it achieved nothing except making the next reader think it mattered.
-                // The member reached idle with the trust flag alone, which is the only outcome
-                // this seed exists for. If a future Claude Code needs the second flag the
-                // symptom returns as the trust dialog fleetd #149 describes — re-measure then,
-                // do not restore it on a guess.
-                project.put("hasTrustDialogAccepted", true);
-                writeAtomically(target, TRUST_JSON.writerWithDefaultPrettyPrinter().writeValueAsString(root));
+                // fleetd #247: deliberately do NOT write here. A member that starts without the
+                // seed still starts — it may hit the trust dialog fleetd #149 describes and fail to
+                // reach an injectable state, but that failure is visible (herdr reports it, the
+                // spawn-readiness gate times out) and recoverable (retry the spawn). Writing our
+                // stale copy over whatever the other writer left would be silent and, if that other
+                // writer is the operator's own live session, could destroy real configuration —
+                // fail toward the recoverable outcome, not the silent one.
+                log.warn("seedTrustDialog: gave up seeding workspace-trust for cwd '{}' into '{}' "
+                        + "after {} attempts — another writer (most plausibly the operator's own "
+                        + "live Claude Code sharing this file) kept changing it faster than we could "
+                        + "re-read it, so nothing was written; the member may show the trust dialog "
+                        + "instead", cwd, target, MAX_TRUST_JSON_CAS_ATTEMPTS);
             } catch (Exception e) {
                 log.debug("cannot seed workspace-trust entry for cwd '{}' into '{}'", cwd, target, e);
             }
         }
     }
 
+    /** Bound on {@link #seedTrustDialog}'s fleetd #247 compare-and-swap retry loop. */
+    private static final int MAX_TRUST_JSON_CAS_ATTEMPTS = 5;
+
+    /**
+     * Test-only seam for fleetd #247: invoked once per CAS attempt inside {@link #seedTrustDialog}'s
+     * retry loop, after that attempt has read the target's bytes and built its replacement content,
+     * but immediately before the final re-read/compare that decides whether to write. A no-op in
+     * production. Package-visible (not {@code private}) so {@code ClaudeCodeLauncherTest} can install
+     * a hook here that writes to the target file, deterministically simulating a writer racing
+     * fleetd's own read-modify-write at the exact instant the CAS is meant to catch — the same race
+     * an external process (most plausibly the operator's own live Claude Code) creates, without
+     * depending on real thread scheduling to land the interleaving. A test that sets this MUST
+     * restore it to the no-op default in a {@code finally} block — it is shared, static state.
+     */
+    static Runnable trustJsonCasTestHook = () -> {};
+
+    /**
+     * Parse {@code bytes} as a {@code .claude.json} tree, or hand back a fresh empty object when
+     * {@code bytes} is {@code null} (no file yet) or does not parse to a JSON object — the same
+     * missing-or-unreadable-is-empty fallback {@link #seedTrustDialog} always used, factored out so
+     * the fleetd #247 CAS loop can call it once per attempt.
+     */
+    private static ObjectNode parseTrustJsonOrEmpty(byte[] bytes) throws IOException {
+        if (bytes == null) {
+            return TRUST_JSON.createObjectNode();
+        }
+        JsonNode existing = TRUST_JSON.readTree(bytes);
+        return existing instanceof ObjectNode existingObject ? existingObject : TRUST_JSON.createObjectNode();
+    }
+
     /**
      * Write {@code content} to {@code target} atomically: serialise to a sibling temp file in the
      * <strong>same directory</strong> as {@code target} (an atomic move is only guaranteed within

fleetd/src/main/java/dev/ltms/fleet/member/HerdrPeerLauncher.java

@@ -184,7 +184,11 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
      */
     private final ConcurrentMap<String, Path> zdotdirByPane = new ConcurrentHashMap<>();
 
-    /** Guards {@link #warnNonZsh} to one WARN per launcher instance, not one per spawn. */
+    /**
+     * Guards {@link #warnNonZsh} to one WARN per launcher instance, not one per spawn. fleetd #155:
+     * only the {@code policy: deny-by-default} path still warns on a non-zsh shell — the {@code
+     * policy: allow-list} path refuses the spawn instead (see {@link #applyEnvironmentAllowListPolicy}).
+     */
     private final AtomicBoolean nonZshShellWarned = new AtomicBoolean();
     /** Live config provides URI environment names that must never enter member panes. */
     private final Supplier<FleetConfig> config;
@@ -1255,6 +1259,11 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         if (!creds.isAllowList()) {
             overlayBlockedCredentials(workerEnv, creds);
             logCredentialGap(creds, null);
+            // fleetd #155: this overlay itself does not depend on the shell (it lands in the
+            // pane-creation env map before any shell runs), so the spawn is never refused here —
+            // only policy=allow-list's ZDOTDIR scrub needs a login shell to run at all. Still worth
+            // telling the operator: the stronger post-shell control is unavailable on this shell.
+            warnNonZsh(memberLoginShell());
         }
     }
 
@@ -1307,10 +1316,16 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
      *       dev.ltms.fleet.session.Worktrees#shareWithGroup} already uses, reused rather than
      *       inventing a second group key. Either one missing means the scrub cannot be guaranteed
      *       reachable by the member, which is the same "cannot guarantee the scrub runs" case as a
-     *       non-zsh shell, so it gets the identical fallback.</li>
+     *       non-zsh shell — that one still gets the fallback (see fleetd #155's javadoc note below
+     *       on why a missing worktreeRoot/worktreeGroup is a different defect, out of that ticket's
+     *       scope).</li>
      * </ul>
-     * In every branch: never refuse to spawn. A degraded credential control must not become an
-     * outage for an opt-in feature.
+     * fleetd #155: the one exception to "never refuse to spawn" is a non-zsh login shell, right
+     * below. The operator asked for {@code policy: allow-list} specifically — its whole point is a
+     * control a sourced file cannot undo — so silently degrading to the weaker overlay is exactly
+     * the "silently does nothing" failure this ticket exists to remove. Every other branch in this
+     * method (worktreeRoot/worktreeGroup missing) keeps the old "degrade, never refuse" behaviour;
+     * that gap is real but is fleetd #213's scope, not this one.
      */
     private Path applyEnvironmentAllowListPolicy(FleetConfig.Profile cfg, Launch launch) {
         FleetConfig.MemberCredentials creds = memberCredentials == null ? null : memberCredentials.get();
@@ -1324,20 +1339,21 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         // must not even be called on this path, only the explicit memberLoginShell: config can
         // answer it. With memberHerdrSocket absent, nothing here changes: fleetd's own $SHELL is
         // still the input, exactly as before this fix.
-        String loginShell = memberHerdrSocket ? configuredMemberLoginShell() : resolveEnv("SHELL");
+        String loginShell = memberLoginShell();
         boolean zsh = isZshShell(loginShell);
         if (!zsh) {
-            // A non-zsh login shell ignores ZDOTDIR entirely: NO scrub would run, so pretending
-            // otherwise would be worse than saying so. Warn loudly and fall back to the CB-596
-            // sentinel overlay over the enumerated known: names — weaker (a sourced file can undo
-            // it), but strictly better than nothing. Deliberately no "allowed N of M" line here: the
-            // scrub this count describes does not run on this path, so printing it would tell an
-            // operator that a fraction of names were blocked when the real number blocked is zero.
-            // logCredentialGap's WARN (below) is the only signal for this path.
-            warnNonZsh(loginShell);
-            overlayBlockedCredentials(launch.env(), creds);
-            logCredentialGap(creds, null);
-            return null;
+            // fleetd #155: a non-zsh login shell ignores ZDOTDIR entirely — NO scrub would run. The
+            // operator explicitly asked for policy=allow-list's blocking control, so degrading to
+            // the weaker CB-596 overlay and spawning anyway would be the same "control silently does
+            // nothing" defect this ticket exists to close. Refuse instead — the caller (FleetMcp.spawn)
+            // catches IllegalArgumentException and surfaces the message to the operator.
+            throw new IllegalArgumentException(
+                    "memberCredentials policy=allow-list requires the member's login shell to be "
+                            + "zsh, so the ZDOTDIR scrub can run after it — refusing to spawn under "
+                            + "login shell '" + (loginShell == null ? "<unset>" : loginShell)
+                            + "'. Configure memberLoginShell: as a zsh path (only read when "
+                            + "memberHerdrSocket is set), move the member's OS account onto zsh, or "
+                            + "set memberCredentials.policy: deny-by-default instead.");
         }
         Path parentDir;
         String group = null;
@@ -1392,6 +1408,20 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         return cfg == null ? null : cfg.memberLoginShell();
     }
 
+    /**
+     * fleetd #155: the member pane's login shell, using the same {@code memberHerdrSocket} routing
+     * {@link #applyEnvironmentAllowListPolicy} already used — fleetd's own {@code $SHELL} decides it
+     * when {@code memberHerdrSocket} is absent (today's only mode); the configured {@code
+     * memberLoginShell:} decides it otherwise, since fleetd's own {@code $SHELL} names a different
+     * user's shell once member panes run under a different OS user. Shared by both {@link
+     * #applyEnvironmentAllowListPolicy} (allow-list: refuses on non-zsh) and {@link
+     * #applyMemberCredentialPolicy} (deny-by-default: warns on non-zsh) so the two policies agree on
+     * what "the member's shell" means.
+     */
+    private String memberLoginShell() {
+        return memberHerdrSocketConfigured() ? configuredMemberLoginShell() : resolveEnv("SHELL");
+    }
+
     /**
      * fleetd #213: {@code worktreeRoot}, as the ZDOTDIR scrub's parent directory under {@code
      * memberHerdrSocket}, or {@code null} when unconfigured — the same "cannot guarantee the scrub
@@ -1476,15 +1506,23 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
     private static final String SSH_AUTH_SOCK = MemberEnvAllowList.SSH_AUTH_SOCK;
 
     /**
-     * CB-633: a non-zsh login shell means the allow-list control CANNOT run — say so once per
-     * launcher instance, naming the shell, instead of failing silently.
+     * fleetd #155: called ONLY from the {@code policy: deny-by-default} branch of {@link
+     * #applyMemberCredentialPolicy} — under {@code policy: allow-list}, a non-zsh shell now REFUSES
+     * the spawn instead (see {@link #applyEnvironmentAllowListPolicy}), since that policy's whole
+     * point is a control a sourced file cannot undo. deny-by-default's own overlay does not depend
+     * on the shell (it lands in the pane-creation env map before any shell runs), so this is a
+     * heads-up, not a defect report: say once per launcher instance, naming the shell, that the
+     * stronger allow-list control is unavailable here — never silently.
      */
     private void warnNonZsh(String shell) {
+        if (isZshShell(shell)) {
+            return;
+        }
         if (nonZshShellWarned.compareAndSet(false, true)) {
-            log.warn("memberCredentials policy=allow-list: member login shell '{}' is NOT zsh — "
-                            + "ZDOTDIR scrubbing cannot run, so members' inherited environment is "
-                            + "UNPROTECTED beyond the enumerated known: fallback. Move herdr onto a "
-                            + "zsh account or switch policy back to deny-by-default.",
+            log.warn("memberCredentials policy=deny-by-default: member login shell '{}' is NOT zsh — "
+                            + "the pane-creation credential overlay still applies here (it does not "
+                            + "depend on the shell), but policy=allow-list's stronger post-shell "
+                            + "ZDOTDIR scrub is unavailable on this shell.",
                     shell == null ? "<unset>" : shell);
         }
     }

fleetd/src/test/java/dev/ltms/fleet/FleetdLeadSeatLookupTest.java

@@ -0,0 +1,156 @@
+package dev.ltms.fleet;
+
+import dev.ltms.fleet.config.FleetConfig;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+import java.util.function.Function;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * fleetd #176: {@link Fleetd#leadSeatLookup} is the factory {@code Fleetd.main} wires into {@code
+ * FleetMcp.LeadSeatSource} so {@code fleet_list}'s {@code free} can subtract the seat(s) a
+ * {@code subscription: true} profile's own live LEAD session holds on that same account —
+ * {@code maxLoad} never counted the lead, only members. {@code FleetdLeadSeatWiringTest} proves
+ * {@code main} still passes this factory's result in; this class proves the factory's own matching
+ * logic: subscription-only, credential-matched, and counting only CURRENTLY LIVE leads.
+ */
+class FleetdLeadSeatLookupTest {
+
+    private static FleetConfig.Profile subscriptionProfile(String name, String credentialId) {
+        return new FleetConfig.Profile(name, null, "claude-sonnet-5", null, null, null,
+                "tab", "fleet", "w #{n}", null, null, null, null, null, null, null,
+                null, 3, true, null, credentialId, null);
+    }
+
+    private static FleetConfig.Profile offSubscriptionProfile(String name, String credentialId) {
+        return new FleetConfig.Profile(name, "http://gx00.gw:8000", "coder", null, "FLEETD_WORKER_TOKEN",
+                null, "tab", "fleet", "w #{n}", null, null, null, null, null, null, null,
+                null, 2, false, null, credentialId, null);
+    }
+
+    private static FleetConfig.Leader leadOnProfile(String profile) {
+        return new FleetConfig.Leader(profile, "lead: primary", 1, "lead:", 10, "claude", "claude-sonnet-5");
+    }
+
+    @Test
+    @DisplayName("a live lead sharing the target profile's credential counts as one seat")
+    void liveLeadSharingCredentialCountsAsOneSeat() {
+        Map<String, FleetConfig.Profile> profiles = Map.of("sonnet", subscriptionProfile("sonnet", null));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("sonnet"));
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders,
+                () -> Map.of("term_primary", "primary"));
+
+        assertEquals(1, lookup.apply("sonnet"));
+    }
+
+    @Test
+    @DisplayName("no live lead names this profile ⇒ zero seats, exactly as before this ticket")
+    void noLiveLeadOnTheProfileCountsAsZero() {
+        Map<String, FleetConfig.Profile> profiles = Map.of("sonnet", subscriptionProfile("sonnet", null));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("sonnet"));
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders, Map::of);
+
+        assertEquals(0, lookup.apply("sonnet"));
+    }
+
+    @Test
+    @DisplayName("a lead entry with no `profile:` (recognise-only) contributes no seats — cannot be derived")
+    void recogniseOnlyLeadWithNoProfileContributesNothing() {
+        Map<String, FleetConfig.Profile> profiles = Map.of("sonnet", subscriptionProfile("sonnet", null));
+        FleetConfig.Leader recogniseOnly = new FleetConfig.Leader(null, "lead: primary", 1, "lead:", 10,
+                "claude", "claude-sonnet-5");
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", recogniseOnly);
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders,
+                () -> Map.of("term_primary", "primary"));
+
+        assertEquals(0, lookup.apply("sonnet"));
+    }
+
+    @Test
+    @DisplayName("a non-subscription profile never has a lead seat subtracted, whatever the credential match")
+    void nonSubscriptionProfileIsNeverAdjusted() {
+        Map<String, FleetConfig.Profile> profiles = Map.of(
+                "terra", offSubscriptionProfile("terra", "shared-openai"),
+                "sonnet", subscriptionProfile("sonnet", "shared-openai"));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("sonnet"));
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders,
+                () -> Map.of("term_primary", "primary"));
+
+        assertEquals(0, lookup.apply("terra"), "terra is not subscription:true, so it must never be adjusted");
+    }
+
+    @Test
+    @DisplayName("explicit, different credentialIds still separate two subscription profiles (post fleetd #176 "
+            + "stage 2 sentinel)")
+    void differentCredentialIsNotCounted() {
+        Map<String, FleetConfig.Profile> profiles = Map.of(
+                "sonnet", subscriptionProfile("sonnet", "claude-account-a"),
+                "opus", subscriptionProfile("opus", "claude-account-b"));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("opus"));
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders,
+                () -> Map.of("term_primary", "primary"));
+
+        assertEquals(0, lookup.apply("sonnet"), "different accounts must never be conflated into one seat count "
+                + "— an explicit credentialId on both sides must still win over the subscription sentinel, so an "
+                + "operator with two separate Claude logins on one host can keep them apart");
+    }
+
+    /**
+     * fleetd #176 stage 2 — the exact live shape that shipped inert: a lead on subscription profile
+     * {@code opus}, members on a DIFFERENTLY NAMED subscription profile {@code sonnet}, same Claude
+     * login, and NEITHER profile sets {@code credentialId}. Every other test in this class puts the
+     * lead on the SAME profile name as the target, which happened to keep working even with the old
+     * fall-back-to-profile-name {@code effectiveCredentialId()} — this is the one that did not, and
+     * its absence is what let the stage-1 fix ship without ever catching the bug it was filed for.
+     */
+    @Test
+    @DisplayName("[LIVE SHAPE] lead on a DIFFERENT subscription profile, same account, neither sets "
+            + "credentialId ⇒ still counts as a seat")
+    void leadOnADifferentSubscriptionProfileSameAccountStillCountsAsASeat() {
+        Map<String, FleetConfig.Profile> profiles = Map.of(
+                "opus", subscriptionProfile("opus", null),
+                "sonnet", subscriptionProfile("sonnet", null));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("opus"));
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders,
+                () -> Map.of("term_primary", "primary"));
+
+        assertEquals(1, lookup.apply("sonnet"), "opus and sonnet are both subscription:true with no explicit "
+                + "credentialId, so they share one Claude login and the lead's live seat on opus must be charged "
+                + "against sonnet too — this is the live host's actual shape (fleetd #176 stage 2)");
+    }
+
+    @Test
+    @DisplayName("two live instances of the same lead count as two seats")
+    void twoLiveInstancesOfTheSameLeadCountAsTwoSeats() {
+        Map<String, FleetConfig.Profile> profiles = Map.of("sonnet", subscriptionProfile("sonnet", null));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("sonnet"));
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders,
+                () -> Map.of("term_a", "primary", "term_b", "primary"));
+
+        assertEquals(2, lookup.apply("sonnet"));
+    }
+
+    @Test
+    @DisplayName("an unconfigured target profile resolves to zero, not a thrown exception")
+    void unconfiguredTargetProfileIsZero() {
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(Map::of, Map.of(), Map::of);
+
+        assertEquals(0, lookup.apply("ghost"));
+    }
+
+    @Test
+    @DisplayName("live leads are read through the supplier on every call, not snapshotted")
+    void liveLeadsAreReadThroughOnEveryCall() {
+        Map<String, FleetConfig.Profile> profiles = Map.of("sonnet", subscriptionProfile("sonnet", null));
+        Map<String, FleetConfig.Leader> leaders = Map.of("primary", leadOnProfile("sonnet"));
+        java.util.Map<String, String> live = new java.util.HashMap<>();
+        Function<String, Integer> lookup = Fleetd.leadSeatLookup(() -> profiles, leaders, () -> live);
+
+        assertEquals(0, lookup.apply("sonnet"));
+        live.put("term_primary", "primary");
+        assertEquals(1, lookup.apply("sonnet"));
+    }
+}

fleetd/src/test/java/dev/ltms/fleet/FleetdLeadSeatWiringTest.java

@@ -0,0 +1,43 @@
+package dev.ltms.fleet;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * fleetd #176: {@code Fleetd.main} builds its {@code FleetMcp} from a 14-argument constructor whose
+ * last argument is a {@code FleetMcp.LeadSeatSource} wrapping {@link Fleetd#leadSeatLookup}. That
+ * argument is exactly the kind of wiring fleetd #248 warned about: dropping it (or swapping it for
+ * the inert {@code FleetMcp.LeadSeatSource.none()}) compiles with 0 errors and leaves every test
+ * that builds its own {@code FleetMcp}/{@code CapacitySource} directly — every test that predates
+ * this ticket — green, because none of them go through {@code main} at all.
+ *
+ * <p>{@link FleetdLeadSeatLookupTest} proves the factory's own matching logic; this class is the
+ * plain source-text assertion that proves {@code main} still passes its result in, mirroring
+ * {@code FleetdCompletionResolverWiringTest}'s approach for the same class of gap.
+ *
+ * <p><b>This test checks source text, not runtime behaviour.</b> It never constructs a
+ * {@code FleetMcp} and never runs {@code main}.
+ */
+class FleetdLeadSeatWiringTest {
+
+    private static String fleetdSource() throws Exception {
+        return Files.readString(Path.of("src/main/java/dev/ltms/fleet/Fleetd.java"));
+    }
+
+    @Test
+    @DisplayName("[SOURCE TEXT] FleetMcp's construction call still passes a LeadSeatSource built from leadSeatLookup(...)")
+    void fleetMcpConstructionStillWiresLeadSeatLookup() throws Exception {
+        String source = fleetdSource();
+        assertTrue(source.contains("new FleetMcp.LeadSeatSource(leadSeatLookup(() -> config.get().profiles(), "
+                        + "leaders, leads))"),
+                "FleetMcp's construction call must still pass a LeadSeatSource built from "
+                        + "Fleetd.leadSeatLookup(...). Dropping it or swapping in "
+                        + "FleetMcp.LeadSeatSource.none() (fleetd #176's would-be silent regression, the same "
+                        + "shape as fleetd #248's measured mutations) compiles with 0 errors and leaves every "
+                        + "existing behavioural test green — this source check is what must go red instead.");
+    }
+}

fleetd/src/test/java/dev/ltms/fleet/config/FleetConfigTest.java

@@ -6,11 +6,18 @@ import dev.ltms.fleet.peer.MemberRole;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.RecordComponent;
+import java.lang.reflect.Type;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.TreeMap;
+import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 import static org.junit.jupiter.api.Assertions.*;
@@ -1366,9 +1373,18 @@ class FleetConfigTest {
     }
 
     /**
-     * Every optional knob the example documents must bind under the exact spelling used there.
-     * Keep this list in step with {@code fleetd.example.yaml}: a rename that updates the record
-     * but not the example (or vice versa) fails here instead of silently no-op'ing in production.
+     * A spot check that the knobs listed below bind under the exact spelling the example uses —
+     * it asserts real VALUES arrive in the record, which no name-matching guard can do.
+     *
+     * <p><b>This is NOT a coverage guard, and must not be read as one</b> (fleetd #113). The list
+     * inside it is hand-written, so it only ever covers what someone remembered to add. Coverage
+     * — "is every key the code reads documented, and does every documented key bind?" — comes
+     * from {@link #everyNestedConfigKeyIsDocumentedInTheExample} and
+     * {@link #everyLiveKeyInTheExampleBindsToARecordComponent}, both of which derive their key
+     * set from the record tree and therefore cannot drift.
+     *
+     * <p>Adding a knob here is optional. Leaving one out is not a coverage gap, because the two
+     * derived guards above already fail on an undocumented or unbindable key.
      */
     @Test
     void everyOptionalKnobDocumentedInTheExampleBinds(@TempDir Path dir) throws Exception {
@@ -1525,6 +1541,230 @@ class FleetConfigTest {
         return p.matcher(yaml).find();
     }
 
+    /**
+     * The nested half of {@link #everyKnownTopLevelKeyIsDocumentedInTheExample} (fleetd #113).
+     *
+     * <p>That guard walks {@link FleetConfig#KNOWN_TOP_LEVEL_KEYS} and anchors its regex at
+     * column 0, so it sees ONLY top-level keys. Every nested key — {@code profiles.<name>.model},
+     * {@code health.paneProbeIntervalSeconds} and a hundred others — is outside its scope, and
+     * neither its name nor its output says so. A green run then reads as "the example documents
+     * the schema" when most of the schema was never looked at.
+     *
+     * <p>This walks the record tree rather than a name list, so a key added to any nested record
+     * is covered the moment it compiles, with no edit here. That is the point: a hand-maintained
+     * second copy of a list always drifts from the thing it mirrors.
+     *
+     * <p><b>Scope, stated on purpose</b> (fleetd #113 criterion 3 — every check reports what it
+     * did and did not look at):
+     * <ul>
+     *   <li>It checks each key NAME appears somewhere in the example as a YAML key, live or
+     *       commented out. It does NOT check the key sits at the right path.</li>
+     *   <li>It does NOT check a documented key is read by anything. {@code paneProbeIntervalSeconds}
+     *       is parsed into {@link FleetConfig.Health} and used nowhere, and this guard passes it.
+     *       Proving a key is live code needs a call graph, which this is not.</li>
+     * </ul>
+     */
+    @Test
+    void everyNestedConfigKeyIsDocumentedInTheExample() throws Exception {
+        Path example = Path.of("fleetd.example.yaml");
+        assertTrue(Files.exists(example), "fleetd.example.yaml must ship next to the pom");
+        String text = Files.readString(example);
+
+        Map<String, String> pathByName = configKeyPaths();
+
+        // The denominator. An under-counting walk passes every subset check vacuously, which is
+        // the exact shape fleetd #113 collects — so the walk has to prove it descended at all.
+        // The floor is DERIVED, not a literal: the nested walk must find substantially more keys
+        // than the top-level set the old guard used, or it has not gone below the first level.
+        int topLevel = FleetConfig.KNOWN_TOP_LEVEL_KEYS.size();
+        assertTrue(pathByName.size() > topLevel * 2,
+                "the record walk found " + pathByName.size() + " config key(s) against "
+                        + topLevel + " top-level key(s) — it has stopped descending into the "
+                        + "nested records, so this guard would pass vacuously. Fix the walk "
+                        + "before trusting a green run.");
+
+        List<String> undocumented = pathByName.entrySet().stream()
+                .filter(e -> !keyDocumentedAnywhere(text, e.getKey()))
+                .map(Map.Entry::getValue)
+                .sorted()
+                .toList();
+
+        assertTrue(undocumented.isEmpty(), () -> "checked " + pathByName.size()
+                + " config key(s) that FleetConfig can bind; " + undocumented.size()
+                + " appear nowhere in fleetd.example.yaml: " + undocumented
+                + " — document each one there, commented out if optional. fleetd.yaml is "
+                + "gitignored, so the example is the only committed description of the schema.");
+    }
+
+    /**
+     * The other direction: a LIVE key in the example that {@link FleetConfig} cannot bind. That is
+     * a key an operator would copy into {@code fleetd.yaml} expecting it to do something, where it
+     * would be silently ignored.
+     *
+     * <p><b>Scope, stated on purpose:</b> only live (uncommented) keys are checked. Most of the
+     * example is commented-out prose, and that prose contains lines like {@code #   mode: token}
+     * that are indistinguishable from keys by text alone. Parsing them would produce false
+     * failures, so they are deliberately out of scope — and saying so here is the point, rather
+     * than letting a reader assume the whole file was validated.
+     */
+    @Test
+    void everyLiveKeyInTheExampleBindsToARecordComponent() throws Exception {
+        Path example = Path.of("fleetd.example.yaml");
+        String text = Files.readString(example);
+
+        List<List<String>> paths = liveKeyPaths(text);
+        assertTrue(paths.size() >= 20,
+                "only " + paths.size() + " live key path(s) were parsed out of the example — the "
+                        + "parser is not seeing the file, so this guard would pass vacuously.");
+
+        List<String> unbindable = paths.stream()
+                .filter(path -> !pathBinds(path))
+                .map(path -> String.join(".", path))
+                .distinct()
+                .sorted()
+                .toList();
+
+        assertTrue(unbindable.isEmpty(), () -> "checked " + paths.size()
+                + " live key path(s) in fleetd.example.yaml; " + unbindable.size()
+                + " bind to nothing in FleetConfig: " + unbindable
+                + " — an operator copying one of these into fleetd.yaml gets silence, not an error.");
+    }
+
+    /**
+     * Every configuration key {@link FleetConfig} can bind, at every depth, as
+     * {@code name -> a dotted path to one place it appears}. Derived from the record components,
+     * so it cannot drift from the code.
+     */
+    private static Map<String, String> configKeyPaths() {
+        Map<String, String> out = new TreeMap<>();
+        collectConfigKeys(FleetConfig.class, "", new HashSet<>(), out);
+        return out;
+    }
+
+    private static void collectConfigKeys(Class<?> type, String prefix, Set<String> seen,
+                                          Map<String, String> out) {
+        if (!type.isRecord() || !seen.add(type.getName())) {
+            return;
+        }
+        for (RecordComponent rc : type.getRecordComponents()) {
+            String path = prefix.isEmpty() ? rc.getName() : prefix + "." + rc.getName();
+            out.putIfAbsent(rc.getName(), path);
+            Class<?> nested = rc.getType();
+            if (nested.isRecord()) {
+                collectConfigKeys(nested, path, seen, out);
+            } else if (Map.class.isAssignableFrom(nested) || List.class.isAssignableFrom(nested)) {
+                Class<?> element = elementRecord(rc);
+                if (element != null) {
+                    String childPrefix = Map.class.isAssignableFrom(nested)
+                            ? path + ".<name>" : path + "[]";
+                    collectConfigKeys(element, childPrefix, seen, out);
+                }
+            }
+        }
+    }
+
+    /** The record type inside a {@code Map<String, X>} or {@code List<X>} component, else null. */
+    private static Class<?> elementRecord(RecordComponent rc) {
+        if (rc.getGenericType() instanceof ParameterizedType pt) {
+            Type[] args = pt.getActualTypeArguments();
+            if (args.length > 0 && args[args.length - 1] instanceof Class<?> c && c.isRecord()) {
+                return c;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * True when {@code key} is documented in the example, in either of the two conventions that
+     * file actually uses:
+     * <ol>
+     *   <li>as a YAML key at any indentation, live or commented out ({@code key:}); or</li>
+     *   <li>in a prose block that describes a section's sub-keys, one per line, as
+     *       {@code #   key   → what it does}.</li>
+     * </ol>
+     *
+     * <p>The second form is not decoration. {@code broker.uri} is documented ONLY that way, on
+     * purpose: writing it out as a copy-pasteable {@code uri: amqp://user:pass@host} invites an
+     * operator to paste a password into a file, which is the very thing {@code uriEnv} exists to
+     * avoid. A guard that demanded the key form would push the file toward doing that. So this
+     * encodes the convention the example really uses rather than imposing a new one.
+     */
+    private static boolean keyDocumentedAnywhere(String yaml, String key) {
+        String quoted = Pattern.quote(key);
+        Pattern asYamlKey = Pattern.compile("(?m)^\\s*(?:#\\s*)?" + quoted + ":");
+        Pattern asProseEntry = Pattern.compile("(?m)^\\s*#\\s*" + quoted + "\\s+\u2192");
+        return asYamlKey.matcher(yaml).find() || asProseEntry.matcher(yaml).find();
+    }
+
+    /** Every live (uncommented) key in {@code yaml}, as a path from the document root. */
+    private static List<List<String>> liveKeyPaths(String yaml) {
+        Pattern keyLine = Pattern.compile("^(\\s*)([A-Za-z][A-Za-z0-9_]*):(\\s.*)?$");
+        List<String> stack = new ArrayList<>();
+        List<Integer> indents = new ArrayList<>();
+        List<List<String>> paths = new ArrayList<>();
+        for (String line : yaml.split("\n", -1)) {
+            if (line.isBlank() || line.stripLeading().startsWith("#")) {
+                continue;
+            }
+            Matcher m = keyLine.matcher(line);
+            if (!m.matches()) {
+                continue;
+            }
+            int indent = m.group(1).length();
+            while (!indents.isEmpty() && indents.get(indents.size() - 1) >= indent) {
+                indents.remove(indents.size() - 1);
+                stack.remove(stack.size() - 1);
+            }
+            indents.add(indent);
+            stack.add(m.group(2));
+            paths.add(List.copyOf(stack));
+        }
+        return paths;
+    }
+
+    /** True when a dotted YAML path resolves to something {@link FleetConfig} can bind. */
+    private static boolean pathBinds(List<String> path) {
+        Class<?> type = FleetConfig.class;
+        boolean nextSegmentIsAFreeFormName = false;
+        for (int i = 0; i < path.size(); i++) {
+            if (nextSegmentIsAFreeFormName) {
+                nextSegmentIsAFreeFormName = false;
+                continue;
+            }
+            RecordComponent rc = componentNamed(type, path.get(i));
+            if (rc == null) {
+                return false;
+            }
+            Class<?> t = rc.getType();
+            if (t.isRecord()) {
+                type = t;
+            } else if (Map.class.isAssignableFrom(t)) {
+                Class<?> element = elementRecord(rc);
+                if (element == null) {
+                    return true; // Map<String,String>: its entries are data, not schema
+                }
+                type = element;
+                nextSegmentIsAFreeFormName = true;
+            } else {
+                // A scalar or a list of scalars: nothing may legitimately nest under it.
+                return i == path.size() - 1;
+            }
+        }
+        return true;
+    }
+
+    private static RecordComponent componentNamed(Class<?> type, String name) {
+        if (type == null || !type.isRecord()) {
+            return null;
+        }
+        for (RecordComponent rc : type.getRecordComponents()) {
+            if (rc.getName().equals(name)) {
+                return rc;
+            }
+        }
+        return null;
+    }
+
     @Test
     void placementDefaultsToFixedForExistingConfigs(@TempDir Path dir) throws Exception {
         Path f = dir.resolve("no-placement.yaml");

fleetd/src/test/java/dev/ltms/fleet/mcp/FleetMcpTest.java

@@ -34,6 +34,7 @@ import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -651,6 +652,48 @@ class FleetMcpTest {
         assertEquals(2, out.split("\"free\":0", -1).length - 1, out);
     }
 
+    /**
+     * fleetd #176 stage 2 (correcting the inert stage 1): two {@code subscription: true} profiles,
+     * {@code opus} and {@code sonnet}, neither setting an explicit {@code credentialId} — the exact
+     * shape measured on the live Mac fleet. This is INTENDED, not a regression: a real Claude usage
+     * limit on the one login behind both profiles really does take out every profile running on it,
+     * the same way {@code credentialId: openai-shared} already lets two OpenAI-backed profiles share
+     * one quarantine (see {@code everyProfileSharingTheQuarantinedCredentialReportsZeroFree} above).
+     * The {@code credentialIdFor} function here is built the same way {@code Fleetd.main} wires it —
+     * {@code profile -> profiles.get(profile).effectiveCredentialId()} — so this proves the actual
+     * config-driven behaviour, not just {@code capacityView}'s arithmetic with a hand-picked string.
+     */
+    @Test
+    void quarantiningOneSubscriptionProfileZeroesFreeOnTheOtherSharingTheSameAccount() {
+        FakeHerdr h = new FakeHerdr();
+        SessionManager sessions = new SessionManager(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")));
+        Map<String, FleetConfig.Profile> profiles = Map.of(
+                "opus", new FleetConfig.Profile("opus", null, "claude-opus-4", null, null, null,
+                        "tab", "fleet", "w #{n}", null, null, null, null, null, null, null,
+                        null, 3, true, null, null, null),
+                "sonnet", new FleetConfig.Profile("sonnet", null, "claude-sonnet-5", null, null, null,
+                        "tab", "fleet", "w #{n}", null, null, null, null, null, null, null,
+                        null, 3, true, null, null, null));
+        BackendQuarantine quarantine = new BackendQuarantine(() -> 0L, TimeUnit.MINUTES.toNanos(20));
+        quarantine.quarantine(FleetConfig.Profile.SUBSCRIPTION_CREDENTIAL_ID);
+        FleetMcp.QuarantineSource source = new FleetMcp.QuarantineSource(profile -> {
+            FleetConfig.Profile configured = profiles.get(profile);
+            return configured == null ? null : configured.effectiveCredentialId();
+        }, quarantine);
+
+        String out = textOf(FleetMcp.listFleet(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")),
+                sessions, null, new FleetMcp.CapacitySource(profile -> 0, profile -> 3,
+                () -> Set.of("opus", "sonnet"), () -> 0), new FleetMcp.HealthCoverageSource(() -> "off"),
+                source, Map.of(), ""));
+
+        assertEquals(2, out.split("\"free\":0", -1).length - 1,
+                "opus and sonnet share one Claude login with neither setting credentialId, so quarantining "
+                        + "opus's account must also zero sonnet's free — this is intended, not a side effect: "
+                        + out);
+        assertEquals(2, out.split("\"credentialId\":\"" + FleetConfig.Profile.SUBSCRIPTION_CREDENTIAL_ID + "\"", -1)
+                .length - 1, out);
+    }
+
     /** fleetd #201 Unit 5: cool-off forces {@code free:0} but never adds {@code quarantinedForSeconds}. */
     @Test
     void coolingOffProfileReportsZeroFreeButNeverQuarantinedForSeconds() {
@@ -767,6 +810,137 @@ class FleetMcpTest {
         assertFalse(out.contains("quarantinedForSeconds"), out);
     }
 
+    /**
+     * fleetd #257: this is the exact shape measured on the Mac fleet — {@code maxLoad:3, live:2},
+     * one lead sharing the subscription. The OLD formula ({@code max(0, cap - live - leadSeats)})
+     * reported {@code free:0} here, disagreeing with the real spawn gate (which never read
+     * {@code leadSeats} and would still grant one more spawn — see
+     * {@code freeMatchesWhatTheRealPlacementGateActuallyGrants} below for that proof against the
+     * actual gate). {@code free} must report {@code 1}: {@code leadSeats} is carried as a fact, not
+     * subtracted.
+     */
+    @Test
+    void leadSeatIsReportedButNeverSubtractedFromFree() {
+        FakeHerdr h = new FakeHerdr();
+        SessionManager sessions = new SessionManager(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")));
+        FleetMcp.LeadSeatSource leadSeats = new FleetMcp.LeadSeatSource(
+                profile -> "sonnet".equals(profile) ? 1 : 0);
+
+        String out = textOf(FleetMcp.listFleet(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")),
+                sessions, null, new FleetMcp.CapacitySource(profile -> 2, profile -> 3,
+                () -> Set.of("sonnet"), () -> 0), new FleetMcp.HealthCoverageSource(() -> "off"),
+                FleetMcp.QuarantineSource.none(), FleetMcp.OutageSource.none(), leadSeats, Map.of(), "", null));
+
+        assertTrue(out.contains("\"maxLoad\":3"), "maxLoad itself must be left untouched: " + out);
+        assertTrue(out.contains("\"live\":2"), out);
+        assertTrue(out.contains("\"free\":1"), "free is maxLoad - live only, never minus leadSeats: " + out);
+        assertTrue(out.contains("\"leadSeats\":1"), "leadSeats is still reported, just not subtracted: " + out);
+    }
+
+    /**
+     * fleetd #257: the OTHER measurement in the issue — a completely idle fleet with a lead sharing
+     * the subscription. {@code maxLoad:3, live:0} must report {@code free:3}, matching what the
+     * spawn gate (which has no notion of a lead's seat) would actually grant.
+     */
+    @Test
+    void leadSeatDoesNotLowerFreeOnAnOtherwiseIdleSubscriptionProfile() {
+        FakeHerdr h = new FakeHerdr();
+        SessionManager sessions = new SessionManager(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")));
+        FleetMcp.LeadSeatSource leadSeats = new FleetMcp.LeadSeatSource(
+                profile -> "sonnet".equals(profile) ? 1 : 0);
+
+        String out = textOf(FleetMcp.listFleet(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")),
+                sessions, null, new FleetMcp.CapacitySource(profile -> 0, profile -> 3,
+                () -> Set.of("sonnet"), () -> 0), new FleetMcp.HealthCoverageSource(() -> "off"),
+                FleetMcp.QuarantineSource.none(), FleetMcp.OutageSource.none(), leadSeats, Map.of(), "", null));
+
+        assertTrue(out.contains("\"live\":0"), out);
+        assertTrue(out.contains("\"free\":3"), "the real gate never subtracts the lead's seat: " + out);
+        assertTrue(out.contains("\"leadSeats\":1"), out);
+    }
+
+    /**
+     * fleetd #257 — the defect, driven against the REAL placement gate, not a copy of its
+     * arithmetic. {@code free} must equal exactly how many more spawns
+     * {@link CompositePeerLauncher#spawn} (routed through the same {@link SessionManager} fleet_spawn
+     * itself uses) will grant on this profile right now: this test reads whatever number
+     * {@code fleet_list}'s real {@code listFleet} call reports, then drives that many spawns through
+     * the REAL composite launcher and asserts every one succeeds, and the next one — one past what
+     * fleet_list promised — is refused. A test that instead hand-computed {@code cap - live} and
+     * compared it to {@code free} would pass even if both sides shared the same wrong formula (this
+     * repo has been bitten by exactly that before); this one only passes when fleet_list's number and
+     * the gate's real behaviour actually agree.
+     *
+     * <p>{@code liveCount} here is wired the same way {@code Fleetd.main} wires it in production: one
+     * function, read by both the {@link CompositePeerLauncher}'s {@code maxLoad} gate and
+     * {@code fleet_list}'s {@code CapacitySource}, off the SAME {@link SessionManager#roster()} — so
+     * the two paths cannot silently drift on what "live" means.
+     */
+    @Test
+    void freeMatchesWhatTheRealPlacementGateActuallyGrants() {
+        FakeHerdr h = new FakeHerdr();
+        FleetConfig.Profile wcfg = new FleetConfig.Profile(
+                "sonnet", "http://gx00.gw:8000", "coder", null, "FLEETD_WORKER_TOKEN", null,
+                "tab", "fleetd-workers", "worker: {profile} #{n}", null,
+                null, null, null, null, null, null, null, 3);
+        Map<String, FleetConfig.Profile> profiles = Map.of(wcfg.profile(), wcfg);
+        ClaudeCodeLauncher delegate = new ClaudeCodeLauncher(
+                new AgentControl(h), new WorkspaceControl(h), new SubscriptionGuard(Set.of("gx00.gw")),
+                profiles, wcfg.profile(), k -> "FLEETD_WORKER_TOKEN".equals(k) ? "tok" : null);
+
+        java.util.concurrent.atomic.AtomicReference<SessionManager> smRef =
+                new java.util.concurrent.atomic.AtomicReference<>();
+        Function<String, Integer> liveCount = profile -> (int) smRef.get().roster().stream()
+                .filter(s -> profile.equals(s.profile())).count();
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(delegate), wcfg.profile(), profiles, PlacementPolicies.fixed(), liveCount);
+        SessionManager sm = new SessionManager(composite);
+        smRef.set(sm);
+
+        // Two members already live — the exact shape measured in fleetd #257 (maxLoad:3, live:2).
+        assertFalse(FleetMcp.spawn(sm, "sonnet").isError(), "setup: first live member must spawn cleanly");
+        assertFalse(FleetMcp.spawn(sm, "sonnet").isError(), "setup: second live member must spawn cleanly");
+
+        // A lead session shares this profile's subscription — leadSeats:1, same as the ticket.
+        FleetMcp.LeadSeatSource leadSeats = new FleetMcp.LeadSeatSource(p -> "sonnet".equals(p) ? 1 : 0);
+        String out = textOf(FleetMcp.listFleet(composite, sm, null,
+                new FleetMcp.CapacitySource(liveCount, p -> profiles.get(p).maxLoad(), profiles::keySet, () -> 0),
+                new FleetMcp.HealthCoverageSource(() -> "off"), FleetMcp.QuarantineSource.none(),
+                FleetMcp.OutageSource.none(), leadSeats, Map.of(), "", null));
+        int reportedFree = extractInt(out, "free");
+
+        for (int i = 0; i < reportedFree; i++) {
+            McpSchema.CallToolResult res = FleetMcp.spawn(sm, "sonnet");
+            assertFalse(res.isError(), "fleet_list promised free:" + reportedFree + "; spawn #" + (i + 1)
+                    + " of that many was refused by the real gate: " + textOf(res));
+        }
+        McpSchema.CallToolResult overflow = FleetMcp.spawn(sm, "sonnet");
+        assertTrue(overflow.isError(), "fleet_list reported free:" + reportedFree
+                + " but the real placement gate granted at least one more spawn than that: " + textOf(overflow));
+    }
+
+    private static int extractInt(String json, String key) {
+        java.util.regex.Matcher m = java.util.regex.Pattern.compile("\"" + key + "\":(-?\\d+)").matcher(json);
+        assertTrue(m.find(), "no \"" + key + "\" field in: " + json);
+        return Integer.parseInt(m.group(1));
+    }
+
+    /** A profile with no lead seats reported must be byte-identical to before this ticket. */
+    @Test
+    void zeroLeadSeatsOmitsTheKeyAndLeavesFreeUnchanged() {
+        FakeHerdr h = new FakeHerdr();
+        SessionManager sessions = new SessionManager(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")));
+
+        String out = textOf(FleetMcp.listFleet(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")),
+                sessions, null, new FleetMcp.CapacitySource(profile -> 0, profile -> 2,
+                () -> Set.of("terra"), () -> 0), new FleetMcp.HealthCoverageSource(() -> "off"),
+                FleetMcp.QuarantineSource.none(), FleetMcp.OutageSource.none(), FleetMcp.LeadSeatSource.none(),
+                Map.of(), "", null));
+
+        assertTrue(out.contains("\"free\":2"), out);
+        assertFalse(out.contains("leadSeats"), "no lead shares this profile's credential: " + out);
+    }
+
     @Test
     void listReportsLeadsAndFlagsTheCallersOwnRow() {
         FakeHerdr h = new FakeHerdr();

fleetd/src/test/java/dev/ltms/fleet/member/ClaudeCodeLauncherTest.java

@@ -19,11 +19,14 @@ import dev.ltms.fleet.peer.PeerHandle;
 import dev.ltms.fleet.peer.PeerLauncher;
 import dev.ltms.fleet.peer.PeerUnreachableException;
 import dev.ltms.fleet.peer.SpawnRequest;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 import org.slf4j.LoggerFactory;
 
 import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.attribute.PosixFileAttributeView;
@@ -32,10 +35,12 @@ import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.TreeSet;
 import java.util.UUID;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 import java.util.function.Supplier;
@@ -147,18 +152,25 @@ class ClaudeCodeLauncherTest {
     // every ide_* call to the member's own worktree via the charter.
 
     /** A profile carrying an ideMcpUrl (plus optional bridge mcpUrl and cwd). ideMcpUrl is the last record component. */
-    private FleetConfig.Profile ideProfile(String mcpUrl, String ideMcpUrl, String cwd) {
+    /**
+     * {@code configDir} is first and mandatory on purpose (fleetd #258). A profile that sets no
+     * {@code configDir} sends {@code seedTrustDialog}'s write to the operator's real
+     * {@code ~/.claude.json}, and the fleetd #149 gate does not stop that when the fixture's
+     * {@code cwd} is worktree-shaped — which every IDE-overlay fixture's is. Pass a {@code @TempDir}
+     * whenever {@code cwd} has a {@code .git} FILE; {@code null} is only safe when it does not.
+     */
+    private FleetConfig.Profile ideProfile(String configDir, String mcpUrl, String ideMcpUrl, String cwd) {
         return new FleetConfig.Profile(
-                "ltms-local", "http://gx00.gw:8000", "coder", null, "FLEETD_WORKER_TOKEN",
+                "ltms-local", "http://gx00.gw:8000", "coder", configDir, "FLEETD_WORKER_TOKEN",
                 List.of("claude"), "tab", "fleetd-workers", "w #{n}", mcpUrl, cwd, null,
                 null, null, null, null, null, null, null, null, null, ideMcpUrl);
     }
 
     /** As {@link #ideProfile} but carrying the CB-634 auto-open fields (module subdir + open command). */
-    private FleetConfig.Profile ideProfileModule(String ideMcpUrl, String cwd, String ideProjectDir,
-                                                 String ideOpenCommand) {
+    private FleetConfig.Profile ideProfileModule(String configDir, String ideMcpUrl, String cwd,
+                                                 String ideProjectDir, String ideOpenCommand) {
         return new FleetConfig.Profile(
-                "ltms-local", "http://gx00.gw:8000", "coder", null, "FLEETD_WORKER_TOKEN",
+                "ltms-local", "http://gx00.gw:8000", "coder", configDir, "FLEETD_WORKER_TOKEN",
                 List.of("claude"), "tab", "fleetd-workers", "w #{n}", null, cwd, null,
                 null, null, null, null, null, null, null, null, null, ideMcpUrl, ideProjectDir, ideOpenCommand);
     }
@@ -171,7 +183,7 @@ class ClaudeCodeLauncherTest {
     @Test
     void mountsIdeMcpAsSecondServerWhenIdeMcpUrlSet() {
         FakeHerdr herdr = new FakeHerdr();
-        launcher(herdr, ideProfile("http://127.0.0.1:8765/mcp",
+        launcher(herdr, ideProfile(null, "http://127.0.0.1:8765/mcp",
                 "http://127.0.0.1:29170/index-mcp/streamable-http", null)).spawn();
 
         List<String> args = spawnedArgs(herdr);
@@ -186,7 +198,8 @@ class ClaudeCodeLauncherTest {
     @Test
     void ideMcpUrlAloneStillEmitsTheMount() {
         FakeHerdr herdr = new FakeHerdr();
-        launcher(herdr, ideProfile(null, "http://127.0.0.1:29170/index-mcp/streamable-http", null)).spawn();
+        launcher(herdr, ideProfile(null, null, "http://127.0.0.1:29170/index-mcp/streamable-http", null))
+                .spawn();
 
         List<String> args = spawnedArgs(herdr);
         assertTrue(args.contains("--mcp-config"),
@@ -201,7 +214,7 @@ class ClaudeCodeLauncherTest {
         FakeHerdr herdr = new FakeHerdr();
         String roleCharter = "You review changes.";
         String worktree = "/tmp/.fleet-worktrees/rev-1";
-        FleetConfig.Profile cfg = ideProfile("http://127.0.0.1:8765/mcp",
+        FleetConfig.Profile cfg = ideProfile(null, "http://127.0.0.1:8765/mcp",
                 "http://127.0.0.1:29170/index-mcp/streamable-http", worktree);
         ClaudeCodeLauncher svc = new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
                 new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null,
@@ -226,6 +239,62 @@ class ClaudeCodeLauncherTest {
         }, "the --append-system-prompt-file path must be a readable file");
     }
 
+    // ---- fleetd #258: no fixture in this class may seed the operator's real ~/.claude.json ----
+    //
+    // seedTrustDialog writes <configDir>/.claude.json, or ~/.claude.json when the profile sets no
+    // configDir. The fleetd #149 gate (isProvisionedWorktree) closes the case where a fixture leaves
+    // cwd unset and it falls back to user.dir. It does NOT close the case where a fixture builds a
+    // worktree-shaped @TempDir on purpose — the gate opens, and a null configDir still points the
+    // write at the real home. Two IDE-overlay fixtures did exactly that on EVERY run; by 2026-09-03
+    // the operator's ~/.claude.json carried 116 dead JUnit temp paths, none of which still existed.
+    //
+    // DIFFERENTIAL, not absolute: it snapshots the temp-dir project keys already present and fails
+    // only on keys this class ADDS. An absolute check would fail on any host still carrying the
+    // historical entries, and a check that fails for a reason nobody can fix gets deleted, not fixed.
+
+    private static Set<String> tempProjectKeysBefore;
+
+    @BeforeAll
+    static void snapshotTempProjectKeysInTheDefaultClaudeJson() {
+        tempProjectKeysBefore = tempProjectKeysInDefaultClaudeJson();
+    }
+
+    @AfterAll
+    static void noFixtureSeededTheDefaultClaudeJson() {
+        Set<String> added = new TreeSet<>(tempProjectKeysInDefaultClaudeJson());
+        added.removeAll(tempProjectKeysBefore);
+        assertTrue(added.isEmpty(),
+                "a fixture in this class seeded the DEFAULT .claude.json (the operator's real file "
+                        + "when user.home is not redirected) with " + added.size() + " temp-dir "
+                        + "project entry/entries: " + added + ". Give that fixture's profile a "
+                        + "@TempDir configDir — see ideProfile's javadoc.");
+    }
+
+    /**
+     * Project keys under the JVM temp dir in {@code <user.home>/.claude.json}, or an empty set when
+     * the file is absent or unreadable. Only key NAMES are read; nothing in the operator's file is
+     * copied, asserted on, or written back.
+     */
+    private static Set<String> tempProjectKeysInDefaultClaudeJson() {
+        Set<String> keys = new TreeSet<>();
+        Path target = Path.of(System.getProperty("user.home"), ".claude.json");
+        if (!Files.isRegularFile(target)) {
+            return keys;
+        }
+        String tmp = System.getProperty("java.io.tmpdir");
+        try {
+            JsonNode projects = new ObjectMapper().readTree(target.toFile()).path("projects");
+            projects.fieldNames().forEachRemaining(name -> {
+                if (name.startsWith(tmp) || name.contains("/junit-")) {
+                    keys.add(name);
+                }
+            });
+        } catch (IOException e) {
+            return keys; // unreadable file proves nothing either way
+        }
+        return keys;
+    }
+
     // CB-634: the IDE guidance is delivered as a CLAUDE.local.md overlay (written only into a
     // provisioned worktree — cwd with a `.git` FILE) and registered in the repository's COMMON
     // info/exclude. git reads a worktree's excludes from the common dir, not the per-worktree
@@ -241,8 +310,8 @@ class ClaudeCodeLauncherTest {
         Files.writeString(worktree.resolve(".git"), "gitdir: " + gitDir);
 
         FakeHerdr herdr = new FakeHerdr();
-        launcher(herdr, ideProfile(null, "http://127.0.0.1:29170/index-mcp/streamable-http",
-                worktree.toString())).spawn();
+        launcher(herdr, ideProfile(root.toString(), null,
+                "http://127.0.0.1:29170/index-mcp/streamable-http", worktree.toString())).spawn();
 
         Path overlay = worktree.resolve("CLAUDE.local.md");
         assertTrue(Files.exists(overlay), "the overlay is written beside the project's CLAUDE.md");
@@ -268,8 +337,9 @@ class ClaudeCodeLauncherTest {
 
         FakeHerdr herdr = new FakeHerdr();
         // ideProjectDir "fleetd" ⇒ the pin is <worktree>/fleetd, not <worktree>.
-        launcher(herdr, ideProfileModule("http://127.0.0.1:29170/index-mcp/streamable-http",
-                worktree.toString(), "fleetd", null)).spawn();
+        launcher(herdr, ideProfileModule(root.toString(),
+                "http://127.0.0.1:29170/index-mcp/streamable-http", worktree.toString(), "fleetd", null))
+                .spawn();
 
         Path overlay = worktree.resolve("CLAUDE.local.md");
         assertTrue(Files.exists(overlay), "the overlay file still lives at the worktree root");
@@ -304,8 +374,8 @@ class ClaudeCodeLauncherTest {
         Files.createDirectories(worktree.resolve(".git"));
 
         FakeHerdr herdr = new FakeHerdr();
-        launcher(herdr, ideProfile(null, "http://127.0.0.1:29170/index-mcp/streamable-http",
-                worktree.toString())).spawn();
+        launcher(herdr, ideProfile(root.toString(), null,
+                "http://127.0.0.1:29170/index-mcp/streamable-http", worktree.toString())).spawn();
 
         assertFalse(Files.exists(worktree.resolve("CLAUDE.local.md")),
                 "the safety gate refuses to write into a non-worktree cwd (.git directory)");
@@ -1409,14 +1479,16 @@ class ClaudeCodeLauncherTest {
     }
 
     /**
-     * CB-633 follow-up (#192): the mirror of the zsh test above. On a non-zsh login shell {@code
-     * ZDOTDIR} is ignored, so no scrub ever runs — the report must keep the WARN wording (a name here
-     * really is inherited unblocked) rather than claiming a scrub protects it. This is the trap PR
-     * #174 fell into the other direction: keying the wording on the shell, not on {@code
-     * creds.isAllowList()}, is what keeps this branch correct.
+     * fleetd #155 (was CB-633 follow-up (#192) "allowListPolicyOnNonZshKeepsTheWarnWording"): on a
+     * non-zsh login shell {@code ZDOTDIR} is ignored, so no scrub could ever run there. Before #155
+     * the launcher degraded to the weaker overlay and spawned anyway; that is exactly the "control
+     * silently does nothing" failure #155 exists to close, since {@code policy: allow-list} is the
+     * operator explicitly asking for a control a sourced file cannot undo. Now the spawn is REFUSED
+     * instead — this test asserts the refusal, naming the shell, on the real spawn path ({@link
+     * ClaudeCodeLauncher#spawn}), not merely on the launcher method that computes it.
      */
     @Test
-    void allowListPolicyOnNonZshKeepsTheWarnWording() {
+    void allowListPolicyOnNonZshRefusesTheSpawn() {
         FakeHerdr herdr = new FakeHerdr();
         FleetConfig.Profile cfg = new FleetConfig.Profile(
                 "ltms-local", "http://gx00.gw:8000", "coder", null, "FLEETD_WORKER_TOKEN",
@@ -1430,27 +1502,12 @@ class ClaudeCodeLauncherTest {
                 0, System::currentTimeMillis, () -> {}, null, () -> creds,
                 () -> Set.of("AI_GATEWAY_TOKEN", "A_BRAND_NEW_SECRET_TOKEN"));
 
-        Logger logger = (Logger) LoggerFactory.getLogger(HerdrPeerLauncher.class);
-        ListAppender<ILoggingEvent> appender = new ListAppender<>();
-        appender.start();
-        logger.addAppender(appender);
-        try {
-            svc.spawn();
-        } finally {
-            logger.detachAppender(appender);
-        }
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class, svc::spawn,
+                "policy=allow-list on a non-zsh shell must refuse the spawn, not silently degrade "
+                        + "to the weaker overlay");
 
-        assertTrue(appender.list.stream().anyMatch(e ->
-                        e.getFormattedMessage().contains("memberCredentials gap")
-                                && e.getFormattedMessage().contains("UNBLOCKED")
-                                && e.getFormattedMessage().contains("A_BRAND_NEW_SECRET_TOKEN")),
-                "no scrub runs on a non-zsh shell, so the WARN wording must be kept — got: "
-                        + appender.list.stream().map(ILoggingEvent::getFormattedMessage).toList());
-        assertFalse(appender.list.stream().anyMatch(e ->
-                        e.getFormattedMessage().contains("memberCredentials gap")
-                                && e.getFormattedMessage().toLowerCase(java.util.Locale.ROOT).contains("scrub")),
-                "nothing is scrubbed on this path, so the report must not claim otherwise — got: "
-                        + appender.list.stream().map(ILoggingEvent::getFormattedMessage).toList());
+        assertTrue(e.getMessage().contains("allow-list") && e.getMessage().contains("/bin/bash"),
+                "the refusal must name the policy and the actual shell, got: " + e.getMessage());
     }
 
     /**
@@ -2539,4 +2596,150 @@ class ClaudeCodeLauncherTest {
                 + tornRead.get());
         assertEquals(newContent, Files.readString(target), "the final content must be the new content");
     }
+
+    // --- fleetd #247: CAS against a writer TRUST_JSON_LOCK cannot reach --------------------------
+    //
+    // fleetd #149's lock only serialises seedTrustDialog calls THIS launcher makes inside this one
+    // JVM. It does nothing about the one writer that actually shares this file on a real host: the
+    // operator's own live Claude Code, whose CLAUDE_CONFIG_DIR is routinely the very configDir this
+    // profile is given. A plain read-modify-write there is a routine lost update — fleetd reads v1,
+    // the operator's session writes v2, fleetd's ATOMIC_MOVE lands v3 built from v1, and v2 is gone,
+    // atomically. The fix re-reads the file's exact bytes immediately before the move and compares
+    // them with what the update was built from, retrying from fresh bytes on a mismatch.
+    //
+    // Both tests below drive the race through the real seedTrustDialog/spawn() path (not a
+    // hand-rolled call to some extracted primitive) using trustJsonCasTestHook — a seam fired once
+    // per CAS attempt, at the exact point between the read and the final compare, so the race is
+    // deterministic instead of depending on real thread timing.
+
+    @Test
+    void seedTrustDialogRetriesAndPreservesAConcurrentExternalWritersChange(
+            @TempDir Path configDir, @TempDir Path worktree) throws Exception {
+        markAsProvisionedWorktree(worktree);
+        Path claudeJson = configDir.resolve(".claude.json");
+        Files.writeString(claudeJson, "{\"projects\":{}}");
+
+        // Fires exactly once, on the first CAS attempt — simulating the operator's own live Claude
+        // Code landing its own write to this SAME file in the gap between fleetd's read and write.
+        AtomicBoolean fired = new AtomicBoolean(false);
+        ClaudeCodeLauncher.trustJsonCasTestHook = () -> {
+            if (fired.compareAndSet(false, true)) {
+                try {
+                    Files.writeString(claudeJson,
+                            "{\"projects\":{\"/operator/own/project\":"
+                                    + "{\"hasTrustDialogAccepted\":true}}}");
+                } catch (IOException e) {
+                    throw new UncheckedIOException(e);
+                }
+            }
+        };
+        try {
+            FakeHerdr herdr = new FakeHerdr();
+            FleetConfig.Profile cfg = trustProfile(configDir.toString(), worktree.toString());
+            new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
+                    new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null)
+                    .spawn();
+        } finally {
+            ClaudeCodeLauncher.trustJsonCasTestHook = () -> {};
+        }
+
+        assertTrue(fired.get(), "the race hook must actually have fired during the spawn");
+        JsonNode root = new ObjectMapper().readTree(claudeJson.toFile());
+        assertTrue(root.path("projects").path("/operator/own/project")
+                        .path("hasTrustDialogAccepted").asBoolean(false),
+                "the external writer's change, landed between fleetd's read and write, must SURVIVE "
+                        + "— this is the whole point of the CAS: without it, fleetd's stale-built "
+                        + "ATOMIC_MOVE would have silently discarded it. Final file: "
+                        + Files.readString(claudeJson));
+        assertTrue(root.path("projects").path(worktree.toString())
+                        .path("hasTrustDialogAccepted").asBoolean(false),
+                "fleetd's own retry must still land its own trust entry, built from the fresh bytes");
+    }
+
+    /**
+     * Retry-exhaustion path: an external writer that changes the file on EVERY attempt (not just
+     * once) exhausts all {@code MAX_TRUST_JSON_CAS_ATTEMPTS} retries. fleetd must then write nothing
+     * at all — not even a partial/best-effort write — and log a WARN naming the file it gave up on.
+     */
+    @Test
+    void seedTrustDialogWritesNothingAndWarnsWhenCasRetriesAreExhausted(
+            @TempDir Path configDir, @TempDir Path worktree) throws Exception {
+        markAsProvisionedWorktree(worktree);
+        Path claudeJson = configDir.resolve(".claude.json");
+        Files.writeString(claudeJson, "{\"marker\":\"start\"}");
+
+        AtomicInteger hookCalls = new AtomicInteger();
+        ClaudeCodeLauncher.trustJsonCasTestHook = () -> {
+            try {
+                Files.writeString(claudeJson,
+                        "{\"marker\":\"race-" + hookCalls.incrementAndGet() + "\"}");
+            } catch (IOException e) {
+                throw new UncheckedIOException(e);
+            }
+        };
+
+        Logger logger = (Logger) LoggerFactory.getLogger(ClaudeCodeLauncher.class);
+        ListAppender<ILoggingEvent> appender = new ListAppender<>();
+        appender.start();
+        logger.addAppender(appender);
+        try {
+            FakeHerdr herdr = new FakeHerdr();
+            FleetConfig.Profile cfg = trustProfile(configDir.toString(), worktree.toString());
+            new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
+                    new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null)
+                    .spawn();
+        } finally {
+            logger.detachAppender(appender);
+            ClaudeCodeLauncher.trustJsonCasTestHook = () -> {};
+        }
+
+        assertEquals(5, hookCalls.get(), "the race hook must fire exactly once per CAS attempt");
+        String finalContent = Files.readString(claudeJson);
+        assertEquals("{\"marker\":\"race-" + hookCalls.get() + "\"}", finalContent,
+                "the file must be left exactly as the external writer last left it — fleetd must not "
+                        + "have written at all once retries are exhausted");
+        assertFalse(finalContent.contains("hasTrustDialogAccepted"),
+                "the trust entry must never appear — its presence would mean the CAS gave up and "
+                        + "wrote anyway instead of skipping the seed");
+
+        assertTrue(appender.list.stream().anyMatch(e -> e.getLevel() == Level.WARN
+                        && e.getFormattedMessage().contains("gave up seeding workspace-trust")
+                        && e.getFormattedMessage().contains(worktree.toString())
+                        && e.getFormattedMessage().contains(claudeJson.toString())),
+                "a WARN naming both the cwd and the file it gave up on must be logged: "
+                        + appender.list.stream().map(ILoggingEvent::getFormattedMessage).toList());
+    }
+
+    /**
+     * The loud-default WARN (fleetd #247): a profile with no {@code configDir} targets the
+     * operator's real {@code ~/.claude.json} (redirected here to a {@code @TempDir}), and every time
+     * that happens must be logged, not just detected.
+     */
+    @Test
+    void seedTrustDialogWarnsEveryTimeItTargetsTheDefaultClaudeJson(
+            @TempDir Path fakeHome, @TempDir Path worktree) throws Exception {
+        markAsProvisionedWorktree(worktree);
+        String originalHome = System.getProperty("user.home");
+        System.setProperty("user.home", fakeHome.toString());
+        Logger logger = (Logger) LoggerFactory.getLogger(ClaudeCodeLauncher.class);
+        ListAppender<ILoggingEvent> appender = new ListAppender<>();
+        appender.start();
+        logger.addAppender(appender);
+        try {
+            FakeHerdr herdr = new FakeHerdr();
+            FleetConfig.Profile cfg = trustProfile(null, worktree.toString());
+            new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
+                    new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null)
+                    .spawn();
+        } finally {
+            logger.detachAppender(appender);
+            System.setProperty("user.home", originalHome);
+        }
+
+        assertTrue(appender.list.stream().anyMatch(e -> e.getLevel() == Level.WARN
+                        && e.getFormattedMessage().contains("no configDir set")
+                        && e.getFormattedMessage().contains(worktree.toString())),
+                "a WARN naming the cwd must fire when the profile sets no configDir: "
+                        + appender.list.stream().map(ILoggingEvent::getFormattedMessage).toList());
+    }
 }

fleetd/src/test/java/dev/ltms/fleet/member/HerdrPeerLauncherAllowListWiringTest.java

@@ -29,6 +29,7 @@ import java.util.function.Supplier;
 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.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
@@ -99,18 +100,26 @@ class HerdrPeerLauncherAllowListWiringTest {
     }
 
     /**
-     * A non-zsh shell cannot read {@code ZDOTDIR} at all. The launcher must fall back rather than
-     * generate a directory nothing will ever read — a directory that would look like protection.
+     * fleetd #155: a non-zsh shell cannot read {@code ZDOTDIR} at all, so under {@code
+     * policy: allow-list} — the policy the operator picked specifically for a control a sourced file
+     * cannot undo — the launcher must REFUSE the spawn rather than silently generate a directory
+     * nothing will ever read (protection theatre) or fall back to the weaker overlay (exactly the
+     * "control silently does nothing" defect this ticket exists to close). Real path: through {@link
+     * HerdrPeerLauncher#spawn}, the method the daemon actually calls.
      */
     @Test
-    void aNonZshShellGeneratesNothingAndFallsBack() {
+    void aNonZshShellUnderAllowListPolicyRefusesTheSpawn() {
         FakeHerdr herdr = new FakeHerdr();
         WiringLauncher launcher = new WiringLauncher(herdr, allowList(), "/bin/bash");
 
-        launcher.spawn(new SpawnRequest("test", null, null, null, null, MemberRole.DEV));
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> launcher.spawn(new SpawnRequest("test", null, null, null, null, MemberRole.DEV)),
+                "policy=allow-list on a non-zsh shell must refuse the spawn, not silently degrade");
 
+        assertTrue(e.getMessage().contains("allow-list") && e.getMessage().contains("/bin/bash"),
+                "the refusal must name the policy and the actual shell, got: " + e.getMessage());
         assertFalse(launcher.env.containsKey("ZDOTDIR"),
-                "bash ignores ZDOTDIR; setting it would be protection theatre");
+                "a refused spawn must not have generated (or wired in) a scrub directory: " + launcher.env);
     }
 
     private static Supplier<FleetConfig.MemberCredentials> allowList() {
@@ -246,11 +255,14 @@ class HerdrPeerLauncherAllowListWiringTest {
      * "allowed N of M" line — which describes what the scrub does — must not be printed there either.
      * Before this fix the line was logged BEFORE the zsh gate, so a non-zsh host printed e.g.
      * "allowed 1 of 3" while blocking nothing at all, telling an operator a control ran when it did
-     * not. Real path: goes through {@link HerdrPeerLauncher#spawn}, same as the sibling test above,
-     * with the shell fixed to bash so the fallback branch is the one exercised.
+     * not. fleetd #155: the spawn itself is now refused on this path (see {@code
+     * aNonZshShellUnderAllowListPolicyRefusesTheSpawn}) rather than falling back — this test's own
+     * concern still holds under the refusal: the "allowed N of M" line describes a scrub that never
+     * ran here, so it must still never appear. Real path: goes through {@link
+     * HerdrPeerLauncher#spawn}, same as the sibling test above, with the shell fixed to bash.
      */
     @Test
-    void noAllowedCountLineIsEmittedOnTheNonZshFallbackPath() {
+    void noAllowedCountLineIsEmittedOnTheNonZshRefusalPath() {
         FakeHerdr herdr = new FakeHerdr();
         Set<String> hostEnvNames = Set.of(INJECTED, "SOME_UNRELATED_NAME", "ANOTHER_UNRELATED_NAME");
         WiringLauncher launcher = new WiringLauncher(herdr, allowList(), "/bin/bash", () -> hostEnvNames);
@@ -262,7 +274,9 @@ class HerdrPeerLauncherAllowListWiringTest {
         appender.start();
         logger.addAppender(appender);
         try {
-            launcher.spawn(new SpawnRequest("test", null, null, null, null, MemberRole.DEV));
+            assertThrows(IllegalArgumentException.class,
+                    () -> launcher.spawn(new SpawnRequest("test", null, null, null, null, MemberRole.DEV)),
+                    "policy=allow-list on a non-zsh shell must refuse the spawn");
         } finally {
             logger.detachAppender(appender);
             logger.setLevel(original);
@@ -310,13 +324,20 @@ class HerdrPeerLauncherAllowListWiringTest {
      * different OS user — {@link HerdrPeerLauncher#hostEnvNames} describes fleetd's own process, not
      * that user's. Neither "inherits them UNBLOCKED" nor "scrub blanks them" is evidence-backed
      * there, so neither may print; the single unknown-environment WARN must, naming the config key.
+     *
+     * <p>fleetd #155: {@code memberLoginShell} is now given explicitly as zsh, so the spawn reaches
+     * this WARN through the (still-degrading, not refusing) missing-{@code worktreeRoot}/{@code
+     * worktreeGroup} fallback rather than through the zsh gate, which now refuses instead of falling
+     * back — see {@code aNonZshShellUnderAllowListPolicyRefusesTheSpawn}. This test's own concern
+     * (the unknown-environment WARN) is orthogonal to which fallback reached {@code
+     * logCredentialGap}, so it still holds.
      */
     @Test
     void gapDetectorReportsUnknownInsteadOfAConclusionWhenMemberHerdrSocketIsConfigured() {
         FakeHerdr herdr = new FakeHerdr();
         Set<String> hostEnvNames = Set.of("FLEETD_WORKER_TOKEN", "SOME_UNKNOWN_SECRET_TOKEN");
         WiringLauncher launcher = new WiringLauncher(herdr, allowList(), "/bin/zsh", () -> hostEnvNames,
-                () -> configWithMemberHerdrSocket("/tmp/other-user-herdr.sock"));
+                () -> configWithMemberHerdrSocket("/tmp/other-user-herdr.sock", "/bin/zsh"));
 
         List<String> messages = spawnAndCaptureLogs(launcher);
 
@@ -340,8 +361,9 @@ class HerdrPeerLauncherAllowListWiringTest {
     void theUnknownEnvironmentWarnFiresOnceNotOncePerSpawn() {
         FakeHerdr herdr = new FakeHerdr();
         Set<String> hostEnvNames = Set.of("FLEETD_WORKER_TOKEN", "SOME_UNKNOWN_SECRET_TOKEN");
+        // fleetd #155: memberLoginShell given explicitly as zsh — see the sibling test above for why.
         WiringLauncher launcher = new WiringLauncher(herdr, allowList(), "/bin/zsh", () -> hostEnvNames,
-                () -> configWithMemberHerdrSocket("/tmp/other-user-herdr.sock"));
+                () -> configWithMemberHerdrSocket("/tmp/other-user-herdr.sock", "/bin/zsh"));
 
         Logger logger = (Logger) LoggerFactory.getLogger(HerdrPeerLauncher.class);
         Level original = logger.getLevel();
@@ -389,42 +411,44 @@ class HerdrPeerLauncherAllowListWiringTest {
     }
 
     /**
-     * fleetd #213 defect 1, acceptance criterion 1: {@code memberHerdrSocket} configured and {@code
-     * memberLoginShell} configured as non-zsh must fall back to the sentinel overlay exactly like a
-     * non-zsh {@code $SHELL} does today — and the "generated ZDOTDIR" INFO must not appear, since no
-     * scrub actually runs. The WiringLauncher's own {@code env("SHELL")} is deliberately set to
-     * {@code /bin/zsh} — the OPPOSITE of what {@code memberLoginShell} says — so a launcher that
-     * (incorrectly) fell back to fleetd's own {@code $SHELL} here would wrongly pass the gate and
-     * fail this test.
+     * fleetd #213 defect 1, acceptance criterion 1 — updated by fleetd #155: {@code
+     * memberHerdrSocket} configured and {@code memberLoginShell} configured as non-zsh must now
+     * REFUSE the spawn (not fall back to the sentinel overlay — see {@code
+     * aNonZshShellUnderAllowListPolicyRefusesTheSpawn}'s javadoc for why). The WiringLauncher's own
+     * {@code env("SHELL")} is deliberately set to {@code /bin/zsh} — the OPPOSITE of what {@code
+     * memberLoginShell} says — so a launcher that (incorrectly) fell back to fleetd's own {@code
+     * $SHELL} here would wrongly pass the gate and fail this test.
      */
     @Test
-    void memberHerdrSocketWithNonZshMemberLoginShellFallsBackToTheOverlay() {
+    void memberHerdrSocketWithNonZshMemberLoginShellRefusesTheSpawn() {
         FakeHerdr herdr = new FakeHerdr();
         WiringLauncher launcher = new WiringLauncher(herdr, allowListWithKnown(List.of("SOME_TOKEN")),
                 "/bin/zsh", null,
                 () -> configWithMemberHerdrSocket("/tmp/other-user-herdr.sock", "/bin/bash"));
 
-        List<String> messages = spawnAndCaptureLogs(launcher);
+        IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+                () -> launcher.spawn(new SpawnRequest("test", null, null, null, null, MemberRole.DEV)),
+                "a non-zsh configured memberLoginShell under policy=allow-list must refuse the spawn");
 
-        assertEquals("blocked-by-fleetd-cb596-see-gitea-issue-82", launcher.env.get("SOME_TOKEN"),
-                "a non-zsh memberLoginShell must fall back to the CB-596 sentinel overlay, exactly "
-                        + "like a non-zsh $SHELL does when memberHerdrSocket is absent");
+        assertTrue(e.getMessage().contains("/bin/bash"),
+                "the refusal must name the configured memberLoginShell, got: " + e.getMessage());
+        assertFalse(launcher.env.containsKey("SOME_TOKEN"),
+                "a refused spawn must not have touched the pane env at all: " + launcher.env);
         assertFalse(launcher.env.containsKey("ZDOTDIR"),
                 "no scrub directory may be generated when the configured member login shell is not zsh");
-        assertFalse(messages.stream().anyMatch(m -> m.contains("generated ZDOTDIR")),
-                "the 'generated ZDOTDIR' INFO must not appear when the scrub never runs — got: " + messages);
     }
 
     /**
-     * fleetd #213 defect 1, acceptance criterion 2: {@code memberHerdrSocket} configured and NO
-     * {@code memberLoginShell} configured must fall back exactly like criterion 1 above — AND
-     * fleetd's own {@code $SHELL} must never even be consulted (not merely "not decisive"). The
-     * fixture's {@code env} function reports {@code /bin/zsh} for {@code SHELL} — a value that would
-     * WRONGLY pass the zsh gate if the fix regressed to reading it — while flagging whether it was
-     * ever asked for at all, so this test fails loudly on either kind of regression.
+     * fleetd #213 defect 1, acceptance criterion 2 — updated by fleetd #155: {@code
+     * memberHerdrSocket} configured and NO {@code memberLoginShell} configured must now REFUSE the
+     * spawn exactly like criterion 1 above — AND fleetd's own {@code $SHELL} must never even be
+     * consulted (not merely "not decisive"). The fixture's {@code env} function reports {@code
+     * /bin/zsh} for {@code SHELL} — a value that would WRONGLY pass the zsh gate if the fix
+     * regressed to reading it — while flagging whether it was ever asked for at all, so this test
+     * fails loudly on either kind of regression.
      */
     @Test
-    void memberHerdrSocketWithNoMemberLoginShellFallsBackAndNeverConsultsFleetdsOwnShell() {
+    void memberHerdrSocketWithNoMemberLoginShellRefusesAndNeverConsultsFleetdsOwnShell() {
         FakeHerdr herdr = new FakeHerdr();
         AtomicBoolean shellQueried = new AtomicBoolean(false);
         Function<String, String> env = name -> {
@@ -437,15 +461,18 @@ class HerdrPeerLauncherAllowListWiringTest {
         WiringLauncher launcher = new WiringLauncher(herdr, allowListWithKnown(List.of("SOME_TOKEN")), env,
                 () -> configWithMemberHerdrSocket("/tmp/other-user-herdr.sock", null));
 
-        List<String> messages = spawnAndCaptureLogs(launcher);
+        assertThrows(IllegalArgumentException.class,
+                () -> launcher.spawn(new SpawnRequest("test", null, null, null, null, MemberRole.DEV)),
+                "no configured memberLoginShell under policy=allow-list must refuse the spawn, same "
+                        + "as an explicit non-zsh one");
 
         assertFalse(shellQueried.get(), "fleetd's own $SHELL must never be consulted once "
                 + "memberHerdrSocket is configured — only memberLoginShell: may decide the gate");
-        assertEquals("blocked-by-fleetd-cb596-see-gitea-issue-82", launcher.env.get("SOME_TOKEN"),
-                "no memberLoginShell configured must fall back to the sentinel overlay, same as a "
+        assertFalse(launcher.env.containsKey("SOME_TOKEN"),
+                "a refused spawn must not have touched the pane env at all, same as a "
                         + "configured non-zsh shell");
-        assertFalse(messages.stream().anyMatch(m -> m.contains("generated ZDOTDIR")),
-                "no scrub may run without a configured memberLoginShell — got: " + messages);
+        assertFalse(launcher.env.containsKey("ZDOTDIR"),
+                "no scrub may run without a configured memberLoginShell");
     }
 
     /**
@@ -700,7 +727,8 @@ class HerdrPeerLauncherAllowListWiringTest {
     /**
      * fleetd #213: as above, plus {@code worktreeRoot:}/{@code worktreeGroup:} — both required for
      * the ZDOTDIR scrub to run at all once {@code memberHerdrSocket} is configured; either missing
-     * falls back to the sentinel overlay, same as a non-zsh {@code memberLoginShell}.
+     * falls back to the sentinel overlay (fleetd #155 left this branch alone — it is not a shell
+     * problem, so it is not this ticket's refusal).
      */
     private static FleetConfig configWithMemberHerdrSocketRootAndGroup(String memberHerdrSocket,
             String memberLoginShell, String worktreeRoot, String worktreeGroup) {

fleetd/src/test/java/dev/ltms/fleet/rest/RestRouteInventoryTest.java

@@ -0,0 +1,147 @@
+package dev.ltms.fleet.rest;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.LinkedHashSet;
+import java.util.Locale;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * fleetd #252: the REST surface has no supported operator entry point of its own — it is the
+ * documented fallback for when the MCP mount drops (see the operator wiki's REST page), and
+ * nothing has ever checked a hand-written route list against it. Proof it drifts: the ticket
+ * itself was filed with 14 routes, and {@link FleetApp} registers 15 — {@code GET
+ * /member-credentials} (fleetd #111) shipped hours before the ticket and was already missing from
+ * its list.
+ *
+ * <p>This test is modelled on {@code McpContractDocTest} (fleetd #114 / CB-609), which solved the
+ * same shape of problem for the MCP tool catalogue: read the source text with a regex instead of
+ * trusting a maintained copy. Here the "doc" is an explicit inventory written directly in this
+ * test rather than a separate Markdown file, because the operator wiki page lives in a submodule
+ * a worker cannot read reliably (see {@code CLAUDE.md} → Project addendum). Keeping the expected
+ * list in the test means it still fails loudly the moment {@link FleetApp} changes, which is the
+ * property that actually matters; a human keeps the wiki page in sync using the failure message
+ * below as the diff.
+ *
+ * <p><b>It checks source text, not behaviour.</b> It reads {@link FleetApp}'s source for {@code
+ * app.<verb>("<path>")} registrations and does not boot a server. It cannot catch a route that is
+ * registered through some other mechanism entirely (a filter, a redirect) — only ones shaped like
+ * the {@code app.get/post/delete/put/patch(...)} calls every route here actually uses.
+ */
+class RestRouteInventoryTest {
+
+    /** Tests run with the module directory as cwd. */
+    private static final Path REST_SOURCE = Path.of("src/main/java/dev/ltms/fleet/rest/FleetApp.java");
+
+    /**
+     * The REST surface as verified against {@link FleetApp} on 2026-09-03 (fleetd #252). Update
+     * this list AND the operator wiki's REST-surface entry together whenever a route is added,
+     * removed, or renamed — never one without the other.
+     *
+     * <p>{@code /mcp} is deliberately excluded: it is a raw Jetty {@code ServletHolder} mount
+     * (see {@code FleetApp.build()}, around the {@code modifyServletContextHandler} call), not an
+     * {@code app.<verb>(...)} route, so it is a different registration mechanism and this test's
+     * regex does not — and should not — see it. If {@code /mcp} ever moves to a Javalin route,
+     * add it here explicitly rather than relying on the regex to pick it up by accident.
+     */
+    private static final Set<String> EXPECTED_ROUTES = Set.of(
+            "GET /healthz",
+            "GET /metrics",
+            "GET /sessions",
+            "GET /agents",
+            "GET /members",
+            "GET /profiles",
+            "GET /member-credentials",
+            "POST /members",
+            "DELETE /members/{paneId}",
+            "POST /sessions/{id}/message",
+            "POST /sessions/{id}/reply",
+            "GET /sessions/{id}/replies",
+            "POST /sessions/{id}/ask",
+            "GET /sessions/{id}/status",
+            "GET /tasks/{ticket}"
+    );
+
+    private static final Pattern ROUTE_CALL =
+            Pattern.compile("app\\.(get|post|delete|put|patch)\\(\\s*\"([^\"]+)\"");
+
+    /**
+     * Drop whole-line comments before scraping. Without this the scrape reads commented-out code as
+     * live: a registration disabled with {@code //} still matched, so the route stayed in the
+     * inventory while the server no longer served it — a silent false PASS, measured on 2026-09-03
+     * by commenting out {@code app.get("/tasks/{ticket}", ...)} and watching this test stay green.
+     * Deleting the same line was caught correctly, so only the commented-out shape was blind.
+     *
+     * <p>Only lines whose first non-blank characters are {@code //}, {@code *} or {@code /*} are
+     * dropped — deliberately NOT every {@code //} anywhere on a line, because that would also cut a
+     * string literal containing {@code //} (a URL) and could silently delete a real registration
+     * sharing that line. The remaining gap is a trailing comment on the same line as real code; no
+     * registration in this file has that shape, and the vacuity test below would catch a scrape that
+     * lost registrations wholesale.
+     */
+    private static String withoutCommentLines(String source) {
+        return source.lines()
+                .filter(line -> {
+                    String t = line.stripLeading();
+                    return !(t.startsWith("//") || t.startsWith("*") || t.startsWith("/*"));
+                })
+                .collect(Collectors.joining("\n"));
+    }
+
+    /**
+     * Every {@code app.<verb>("<path>")} call in {@link FleetApp}'s source, as {@code "VERB path"}.
+     * This matches inside an {@code if (...) { ... }} block just as well as a top-level statement —
+     * the regex only looks for the call shape, not its surrounding control flow — which is what
+     * catches {@code GET /metrics} (registered conditionally on {@code metrics != null}).
+     */
+    private static Set<String> routesTheServerRegisters() throws Exception {
+        Matcher m = ROUTE_CALL.matcher(withoutCommentLines(Files.readString(REST_SOURCE)));
+        Set<String> found = new LinkedHashSet<>();
+        while (m.find()) {
+            found.add(m.group(1).toUpperCase(Locale.ROOT) + " " + m.group(2));
+        }
+        return found;
+    }
+
+    @Test
+    @DisplayName("[SOURCE TEXT] FleetApp registers exactly the documented REST route inventory")
+    void theRegisteredRoutesMatchTheExpectedInventory() throws Exception {
+        Set<String> actual = routesTheServerRegisters();
+
+        Set<String> added = new LinkedHashSet<>(actual);
+        added.removeAll(EXPECTED_ROUTES);
+        Set<String> removed = new LinkedHashSet<>(EXPECTED_ROUTES);
+        removed.removeAll(actual);
+
+        assertTrue(added.isEmpty() && removed.isEmpty(),
+                "FleetApp's registered REST routes no longer match this test's expected inventory. "
+                        + "Added (in FleetApp, not in this test): " + added + ". "
+                        + "Removed (in this test, not in FleetApp): " + removed + ". "
+                        + "Update EXPECTED_ROUTES in RestRouteInventoryTest AND the operator wiki's "
+                        + "REST-surface entry together — this is the fleetd #252 defect: the route "
+                        + "list drifted for a month with nothing checking it. Do NOT weaken this test.");
+    }
+
+    /**
+     * The denominator guard (same shape as {@code McpContractDocTest}'s vacuity check). Pins that
+     * the regex really is still finding registrations, so a scrape that silently stops matching
+     * can't make the check above pass by finding nothing on both sides.
+     */
+    @Test
+    @DisplayName("[SOURCE TEXT] the route scrape is not vacuous — it found the expected count")
+    void theScrapeActuallyFoundRoutes() throws Exception {
+        Set<String> actual = routesTheServerRegisters();
+        assertTrue(actual.size() >= EXPECTED_ROUTES.size(),
+                "scraped only " + actual.size() + " route registration(s) from FleetApp (" + actual
+                        + "), but this test expects at least " + EXPECTED_ROUTES.size()
+                        + "; the app.<verb>(\"...\") scrape has stopped matching and the check above "
+                        + "is now vacuous");
+    }
+}

fleetd/src/test/java/dev/ltms/fleet/session/FakeWorktrees.java

@@ -45,6 +45,9 @@ public final class FakeWorktrees implements Worktrees {
     private final List<String> overlayShareOrder = new CopyOnWriteArrayList<>();
     private final Set<String> existingPaths = ConcurrentHashMap.newKeySet();
     private final Set<String> trackedPaths = ConcurrentHashMap.newKeySet();
+    /** Worktree paths that currently exist, mirroring GitWorktrees' {@code Files.exists} check for
+     *  the already-gone case (CB-576 review, fleetd #116). */
+    private final Set<String> worktreePaths = ConcurrentHashMap.newKeySet();
     private final AtomicLong snapshotSeq = new AtomicLong();
     private volatile RuntimeException addFailure;
     private volatile RuntimeException snapshotFailure;
@@ -115,7 +118,15 @@ public final class FakeWorktrees implements Worktrees {
         }
         // 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('/', '_');
+        String path = prefix + "/" + branch.replace('/', '_');
+        worktreePaths.add(path);
+        return path;
+    }
+
+    /** Model an operator / {@code git worktree prune} removing the worktree before release. */
+    public FakeWorktrees markGone(String worktreePath) {
+        worktreePaths.remove(worktreePath);
+        return this;
     }
 
     @Override
@@ -125,6 +136,11 @@ public final class FakeWorktrees implements Worktrees {
 
     @Override
     public boolean hasUncommitted(String worktreePath) {
+        // A path that was never added, or was marked gone, is reported clean, mirroring
+        // GitWorktrees' already-gone guard — never an error, so teardown still completes.
+        if (!worktreePaths.contains(worktreePath)) {
+            return false;
+        }
         return dirty;
     }
 

fleetd/src/test/java/dev/ltms/fleet/session/WorktreeSessionManagerTest.java

@@ -258,6 +258,38 @@ class WorktreeSessionManagerTest {
         }
     }
 
+    /**
+     * CB-576 review (fleetd #116). A worktree that is already gone (operator cleanup,
+     * {@code git worktree prune}, an earlier half-completed release) must not break teardown.
+     * {@code hasUncommitted} reports the missing path clean (mirroring {@code GitWorktrees}), so
+     * {@code release} still runs {@code notifyReleased} (the CB-516 fast-fail for a blocked
+     * {@code fleet_send} caller) and {@code launcher.stop} (so the pane is not orphaned), and falls
+     * through to the already-gone-tolerant {@code remove}. Since CB-581 this all happens because the
+     * notify-and-stop work sits in {@code release}'s {@code finally}/post-try block rather than a
+     * checked branch — this test pins that shape by construction.
+     */
+    @Test
+    void releaseStillStopsPaneAndNotifiesWhenWorktreeIsGone() {
+        FakeHerdr herdr = new FakeHerdr();
+        FakeWorktrees worktrees = new FakeWorktrees().withRepoRoot("/repo").withPrefix("/wt");
+        SessionManager sessions = new SessionManager(workerService(herdr), worktrees);
+        List<SessionManager.ReleaseDetail> released = new java.util.concurrent.CopyOnWriteArrayList<>();
+        sessions.onRelease(released::add);
+        MemberSession s = sessions.acquire("ltms-local", null, "/caller/proj", null,
+                new WorktreeRequest("cb-576g", null));
+
+        worktrees.markGone(s.worktree());
+        sessions.release(s.paneId());
+
+        assertEquals(1, released.size(),
+                "notifyReleased must still fire when the worktree is already gone (CB-516)");
+        assertEquals(s.terminalId(), released.getFirst().terminalId());
+        assertTrue(herdr.called("pane.close"),
+                "the pane must still be stopped when the worktree is already gone");
+        assertEquals(1, worktrees.removeCalls().size(),
+                "release still calls the already-gone-tolerant remove");
+    }
+
     @Test
     void drainAllPreservesWorktreeOfIdleSession() {
         FakeHerdr herdr = new FakeHerdr();