fleetd #116 : recover the already-gone-worktree teardown regression test

Ports the intent of the lost CB-576 commit c393600 (worker/cb576-01a04b-17, never merged, package dev.ltms.bridged.*) onto main's dev.ltms.fleet.* tree. Adds FakeWorktrees.markGone (tracks which add()'d worktree paths still "exist", mirroring GitWorktrees.hasUncommitted's Files.exists guard for the already-gone case) and a regression test, releaseStillStopsPaneAndNotifiesWhenWorktreeIsGone, asserting that SessionManager.release still fires notifyReleased, stops the pane, and falls through to remove() when the worktree is already gone.
#252 : the route scrape counted commented-out registrations as live
2026-09-03 16:11:27 +07:00 · 2026-09-03 15:59:35 +07:00 · 2026-09-03 15:56:15 +07:00 · 2026-09-03 15:54:45 +07:00 · 2026-09-03 14:01:45 +07:00 · 2026-09-03 13:32:16 +07:00
14 changed files with 1199 additions and 124 deletions
@@ -306,6 +306,35 @@ 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) — `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`'s `free` for this profile subtracts that lead's live
+    #   seat(s) automatically; see `profile:` under THE FLEET below. If no lead entry names a
+    #   profile sharing this account, fleetd has no way to know a lead holds a seat here, and `free`
+    #   will overstate what a fresh `fleet_spawn` actually gets by exactly the seats the lead is
+    #   quietly holding.
+    #
+    #   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 +532,22 @@ 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`'s `free` for
+  # that worker profile subtracts the lead's live seat(s) automatically. "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 goes uncounted, exactly as before this ticket.
+  #
  # `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
@@ -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
@@ -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
@@ -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,24 @@ public final class FleetMcp {
        }
    }

+    /**
+     * fleetd #176: the seats a profile's own live LEAD session(s) hold on the same Claude
+     * subscription — the third reason (alongside {@link QuarantineSource} and {@link OutageSource})
+     * {@code free} can overstate what a fresh {@code fleet_spawn} would actually get.
+     *
+     * <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}). So a fan-out that fills every member slot still leaves the lead's
+     * own seat unaccounted for, and the daemon reports a slot that was never really free. 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.
+     */
+    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 +169,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 +183,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 +197,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 +348,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 +1032,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 +1050,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 +1058,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 +1094,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 +1133,33 @@ 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), and it is subtracted from {@code free} the same way {@code live} already is —
+     * {@code maxLoad} itself is left untouched, so the row still reports the configured cap. The
+     * {@code leadSeats} key is added only when the count is positive, for the same
+     * byte-identical-when-unused reason as the quarantine/cool-off keys above.
     */
    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);
+        row.put("free", cap == null ? null : Math.max(0, cap - live - leadSeatCount));
+        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 -> {
@@ -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);
        }
    }
@@ -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"));
+    }
+}
@@ -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.");
+    }
+}
@@ -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");
@@ -651,6 +651,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 +809,68 @@ class FleetMcpTest {
        assertFalse(out.contains("quarantinedForSeconds"), out);
    }

+    /**
+     * fleetd #176: this is the exact shape measured on the Mac fleet — {@code maxLoad:3, live:2},
+     * where one of the "free" three is really the lead's own seat on the same subscription. The old
+     * formula ({@code max(0, cap - live)}) reported {@code free:1}; the real ceiling is {@code 0}
+     * (two members plus the lead's own seat already fill all three).
+     */
+    @Test
+    void leadSeatSubtractsFromFreeTheSameWayLiveDoes() {
+        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\":0"), "2 live + 1 lead seat fills all 3: " + out);
+        assertTrue(out.contains("\"leadSeats\":1"), out);
+    }
+
+    /**
+     * fleetd #176: the OTHER measurement in the issue — a completely idle fleet still overstates
+     * {@code free} by the lead's own seat. {@code maxLoad:3, live:0} must report {@code free:2}, the
+     * real fan-out ceiling, not {@code 3}.
+     */
+    @Test
+    void leadSeatLowersFreeOnAnOtherwiseIdleSubscriptionProfile() {
+        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\":2"), "an idle fleet's real ceiling is 3 minus the lead's own seat: " + out);
+        assertTrue(out.contains("\"leadSeats\":1"), out);
+    }
+
+    /** 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();
@@ -19,6 +19,8 @@ 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;
@@ -32,6 +34,7 @@ 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;
@@ -147,18 +150,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 +181,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 +196,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 +212,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 +237,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 +308,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 +335,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 +372,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 +1477,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 +1500,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());
    }

    /**
@@ -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) {
@@ -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");
+    }
+}
@@ -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;
    }

@@ -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();
Author	SHA1	Message	Date
Dai Ha	8308c0b68f	fleetd #116 : recover the already-gone-worktree teardown regression test CI / contract (pull_request) Successful in 1m16s Details CI / build (pull_request) Successful in 1m23s Details Ports the intent of the lost CB-576 commit `c393600` (worker/cb576-01a04b-17, never merged, package dev.ltms.bridged.) onto main's dev.ltms.fleet. tree. Adds FakeWorktrees.markGone (tracks which add()'d worktree paths still "exist", mirroring GitWorktrees.hasUncommitted's Files.exists guard for the already-gone case) and a regression test, releaseStillStopsPaneAndNotifiesWhenWorktreeIsGone, asserting that SessionManager.release still fires notifyReleased, stops the pane, and falls through to remove() when the worktree is already gone.	2026-09-03 16:11:27 +07:00
Dai Ha	3b3063eb2b	#252 : the route scrape counted commented-out registrations as live CI / build (push) Successful in 1m44s Details CI / contract (push) Successful in 2m21s Details Follow-up to #259, found by verifying the guard rather than trusting it. The scrape read FleetApp's raw source, so a registration disabled with `//` still matched. Measured: commenting out `app.get("/tasks/{ticket}", ...)` left the test GREEN, while deleting the same line was caught. Only the commented-out shape was blind, and it is the silent direction — the inventory would keep claiming a route the server no longer serves. Drop whole-line comments before scraping. Only lines starting with //, * or /* are dropped, deliberately not every // on a line: that would also cut a string literal containing // (a URL) and could silently delete a real registration sharing the line. The remaining gap is a trailing comment beside real code; no registration here has that shape, and the vacuity test catches a scrape that loses registrations wholesale. Proof: with the fix, the comment-out mutation fails naming "Removed ... [GET /tasks/{ticket}]"; reverted, FleetApp.java confirmed clean. mvn clean install: 0 compile errors, 1257 tests, BUILD SUCCESS.	2026-09-03 15:59:35 +07:00
Dai Ha	df9086263d	Merge #259 : guard the REST route inventory against drift (#252 )	2026-09-03 15:56:15 +07:00
Dai Ha	eb568ff451	fleetd #252 : guard test for the REST route inventory CI / contract (pull_request) Successful in 1m16s Details CI / build (pull_request) Successful in 1m27s Details FleetApp's route list has never been checked against anything and has already drifted once (GET /member-credentials shipped hours before the #252 ticket and was missing from its list). Add RestRouteInventoryTest, modelled on McpContractDocTest, which scrapes FleetApp.java's app.<verb>("path") calls with a regex and compares them against an explicit expected inventory, failing loudly with the added/removed routes when they diverge.	2026-09-03 15:54:45 +07:00
Dai Ha	ac790e4cce	#258 : stop two test fixtures writing the operator's real ~/.claude.json CI / contract (push) Successful in 48s Details CI / build (push) Successful in 1m29s Details seedTrustDialog targets ~/.claude.json when a profile sets no configDir. Two IDE-overlay fixtures built a worktree-shaped @TempDir, which opens the #149 isProvisionedWorktree gate, and left configDir null — so every test run added two project entries to the operator's real file. 116 had accumulated, none of them still existing on disk, and 32 of those came from current code. The #149 gate only closed the opposite case: a fixture with cwd unset falling back to user.dir. A fixture that builds a worktree on purpose walks straight through it. - ideProfile/ideProfileModule now take configDir first and mandatory, so each fixture states where the trust seed goes. - noFixtureSeededTheDefaultClaudeJson snapshots the temp-dir project keys in @BeforeAll and fails in @AfterAll on any key this class added. Differential, not absolute: an absolute check would fail on every host still carrying the historical entries, and such a check gets deleted rather than fixed. Not done: a blanket -Duser.home redirect in surefire. EnvAllowListScrubTest tests the credential scrub against the operator's real login chain and guards with assumeTrue($HOME/.zshrc exists), so the redirect would silently skip two security tests. Proof: with the bug put back on one fixture the guard fails and names the path; reverted and confirmed identical with diff -q. A full suite run under a fake home now creates no .claude.json at all. mvn clean install: 0 compile errors, 1255 tests, BUILD SUCCESS.	2026-09-03 14:01:45 +07:00
Dai Ha	6b5f3f472f	Merge #111 : the credential probe reads the policy instead of copying it CI / contract (push) Successful in 1m19s Details CI / build (push) Successful in 1m30s Details scripts/probe-member-credentials.sh carried its own NAMES array of 31 names. The live policy has 34. The probe reported 26 blocked against a policy that blocks 29, exited 0, and printed a table that looked complete. A verification tool that under-reports is worse than none, because its clean output stops anyone looking. Same defect as #114, fixed the same way: DELETE the second copy rather than correct it. The NAMES array is gone, not updated. The daemon now serves GET /member-credentials — names and counts, never a value; MemberCredentialPolicyView reads no environment at all, so there is nothing to redact by construction. The probe fetches it and refuses with a non-zero exit when the daemon is unreachable, the policy is absent or empty, or knownCount disagrees with the length of known[]. No local fallback: a verification tool must not quietly degrade into a weaker check. The startup log line and the endpoint now share that one class, so the counting exists once. That also protects a subtlety I measured before briefing this: blocked is NOT known - allowed. Live, known=34 and allow=7, but only 5 of those 7 appear in known, so blocked=29 and the naive subtraction gives 27. The view reuses creds.blockedSet(), the existing derivation, so it keeps 29. Worker's mutation: MemberCredentialPolicyView.of(...) forced to return ABSENT turned 4 tests red with 0 compile errors — including MemberCredentialsGapReportTest, which proves the startup log really does run through this path. Reverted and confirmed with diff -q. It also caught a bug in its own first draft: jq's // operator treats false and 0 as missing, so `.present // empty` turned a genuine "present": false into "unknown". Fixed by reading the fields directly. NOT yet verified: acceptance criterion 5, the live 34/29/5 run. The route does not exist until the daemon is redeployed onto this jar, so that check comes next and is mine, not the worker's. Merged clean, then built on the merged tree: 1255 tests, 0 failures, 0 compile errors.	2026-09-03 13:32:16 +07:00
Dai Ha	38dec72152	Merge #155 : refuse the spawn when allow-list policy cannot be enforced CI / contract (push) Successful in 46s Details CI / build (push) Successful in 2m15s Details policy=allow-list is enforced by a ZDOTDIR scrub, and a non-zsh login shell ignores ZDOTDIR entirely, so no scrub runs. The launcher already DETECTED this and logged a WARN — then degraded to the weaker overlay and spawned anyway. The operator asked for the blocking control and silently got the weaker one, which is the defect the ticket is about. Detection existed; refusal did not. Under policy=allow-list a non-zsh shell now throws IllegalArgumentException before any ZDOTDIR or env work, naming the actual shell and giving three ways out. Under policy=deny-by-default nothing changes: that overlay is applied to the pane before any shell runs, so it does not depend on the shell. Checked against the live config myself, because this refuses spawns and no worker can see fleetd.yaml: memberHerdrSocket : NOT set -> the shell comes from fleetd's own $SHELL, not the unset memberLoginShell policy : allow-list fleetd's $SHELL : zsh, proven by behaviour rather than by reading the process env — the daemon log shows the ZDOTDIR scrub generating a directory 147 times, most recently minutes ago, and that only happens when isZshShell() returned true So the new refusal cannot fire on this host. Had memberHerdrSocket been set, the unset memberLoginShell would have read as "<unset>", non-zsh, and refused every spawn — worth knowing before anyone sets that key. Worker's mutation evidence, re-stated: `if (!zsh)` -> `if (false)` turned the refusal test RED with 0 compile errors, then reverted clean. NOT verified: a live non-zsh member spawn. Forcing it means changing the daemon's own environment, and the value of the test does not justify that. The unit tests drive the real launcher.spawn entry point. Merged clean, then built on the merged tree: 1250 tests, 0 failures, 0 compile errors.	2026-09-03 13:29:53 +07:00
Dai Ha	0e8bfb74fc	Merge #176 stage 2: group subscription profiles by account, not by name CI / contract (push) Successful in 1m10s Details CI / build (push) Successful in 1m34s Details Stage 1 shipped INERT on this host and every test was green. The matcher compared effectiveCredentialId(), which fell back to the profile's own NAME when credentialId was unset. This host runs the lead on `opus` and members on `sonnet`; both are subscription:true with no credentialId, so it compared "opus" against "sonnet", never matched, and charged 0 seats. Every stage-1 test put the lead on the SAME profile name as the target, so the fixture encoded the one shape the live config does not have. Stage 2 returns a "<subscription>" sentinel when credentialId is unset and subscription is true. An explicit credentialId still wins, so an operator with two genuinely separate Claude logins can keep them apart. Verified by me on the live config shape, not by reasoning: opus.effectiveCredentialId() = <subscription> sonnet.effectiveCredentialId() = <subscription> seats charged to sonnet = 1 (was 0 before this change) Only opus and sonnet join the sentinel group on this host; local, local-direct, gx, xf, sol and terra are unaffected. free is clamped with Math.max(0, ...), so the subtraction cannot report a negative. Second, wider consequence, flagged by the worker and confirmed here: CompositePeerLauncher.credentialIdFor feeds enforceNotQuarantined and enforceNotCoolingOff, so quarantining one subscription profile now also refuses spawns on the other. That is correct — one Claude subscription hitting a usage limit really does take out every profile on it — but it is a behavioural change beyond fleet_list's numbers. Checked all 5 logical callers of effectiveCredentialId(); every one wants "this account", none wants "this exact profile". Merged clean, then built: 1250 tests, 0 failures, 0 compile errors. An auto-merge with no conflicts is not a compiling merge, so the build was run on the merged tree before this landed.	2026-09-03 13:24:19 +07:00
Dai Ha	21c539f22e	#113 : derive the config guard from the record tree, both directions CI / contract (push) Successful in 53s Details CI / build (push) Successful in 1m48s Details The existing guard walks KNOWN_TOP_LEVEL_KEYS and anchors its regex at column 0, so it sees only top-level keys. Every nested key was outside its scope and nothing said so, which is the shape #113 collects: a checker narrower than it looks, whose green run stops anyone looking. Two derived guards replace the assumption: everyNestedConfigKeyIsDocumentedInTheExample walks FleetConfig's record components (17 records, 83 distinct key names) and requires each to be documented in the example. everyLiveKeyInTheExampleBindsToARecordComponent resolves every live key path in the example against the record tree, so a documented key that binds to nothing fails here instead of being silently ignored in production. Neither carries a list, so a key added to any nested record is covered the moment it compiles (criterion 2). Both mutations run through the real caller, not the helper (criterion 1, which asks for exactly that): removed every mention of paneProbeIntervalSeconds from the example -> FAILS, naming health.paneProbeIntervalSeconds added a live bind.totallyMadeUpKnob to the example -> FAILS, naming bind.totallyMadeUpKnob 0 compile errors in both; both reverted and confirmed with diff -q. The first attempt at mutation 1 removed only the `key:` line and the run stayed green — correctly, because the key was still documented in prose. An incomplete mutation proves nothing, so it was redone. Denominators (criterion 3): both guards print how many keys they checked, and the floor for "did the walk descend?" is derived from KNOWN_TOP_LEVEL_KEYS.size() rather than being a literal. Scope is stated in the javadoc rather than implied: the guards do not check a key sits at the right path, do not parse commented prose for the reverse direction, and do not prove a parsed key is read by anything. paneProbeIntervalSeconds is parsed and read by nothing, and these guards pass it -- the example already says so in its own text. everyOptionalKnobDocumentedInTheExampleBinds keeps its hand-written list but is re-documented as a value-binding spot check, explicitly not a coverage guard; coverage now comes from the two derived tests. broker.uri is documented only in the example's prose convention (`# uri -> ...`), never as a copy-pasteable `uri:` key, because writing it out invites pasting a password into a file -- the thing uriEnv exists to avoid. The matcher accepts that convention rather than pushing the file toward doing it. Full build: 1236 tests, 0 failures, 0 compile errors.	2026-09-03 13:18:50 +07:00
Dai Ha	bd2774b5f1	fleetd #155 : refuse a member spawn under memberCredentials.policy=allow-list on a non-zsh shell CI / contract (pull_request) Successful in 1m1s Details CI / build (pull_request) Successful in 1m56s Details The ZDOTDIR scrub that enforces policy=allow-list only runs on zsh. The daemon already detected a non-zsh login shell (isZshShell/warnNonZsh, from #213), but degraded to the weaker CB-596 overlay and spawned anyway — the exact "control silently does nothing" defect this ticket is about. Now a non-zsh shell under policy=allow-list refuses the spawn (IllegalArgumentException, naming the shell), surfaced by FleetMcp.spawn's existing catch(IllegalArgumentException). policy=deny-by-default is unaffected in substance (its overlay never depended on the shell) but now also logs a one-time WARN naming the shell, since the stronger allow-list control is unavailable there. The worktreeRoot/worktreeGroup-missing degrade path under memberHerdrSocket is untouched — that gap is fleetd #213's scope, not this one.	2026-09-03 13:13:23 +07:00
Dai Ha	c50f5b2d61	fleetd #176 stage 2: make effectiveCredentialId() subscription-aware CI / contract (pull_request) Successful in 44s Details CI / build (pull_request) Successful in 1m44s Details Stage 1's lead-seat matcher (leadSeatLookup) was correct but inert on the live host: the lead runs on profile 'opus', members on 'sonnet', both subscription:true with no explicit credentialId. Because effectiveCredentialId() fell back to the profile's own name, opus and sonnet never matched even though they share one Claude login, so the matcher charged zero seats. FleetConfig.Profile.effectiveCredentialId() now falls back to a shared sentinel (SUBSCRIPTION_CREDENTIAL_ID = "<subscription>") instead of the profile name when subscription:true and credentialId is unset. An explicit credentialId still wins, so two separate Claude logins on one host can still be kept apart. This is also BackendQuarantine's and BackendOutagePolicy's grouping key and CompositePeerLauncher's spawn-time enforcement key, so the fix also links quarantine/cool-off across subscription profiles sharing an account -- intentional: one usage limit really does take out every profile on that login, mirroring credentialId: openai-shared already doing this for off-subscription profiles. Every caller was reviewed; none wants "this exact profile" over "this account". Tests added: - FleetdLeadSeatLookupTest: the live shape itself (lead on a DIFFERENT subscription profile than the target, same account, neither sets credentialId) -- the case stage 1's suite never covered - FleetMcpTest: quarantining one subscription profile's shared account zeroes free on another sharing it, via the same effectiveCredentialId()-driven wiring Fleetd.main uses Mutation-tested: reverting the subscription branch to the old fall-back-to-profile-name behavior sends both new tests RED with 0 compile errors; reverting the mutation restores byte-identical (diff -q) source and green tests. fleetd.example.yaml's fleetd #176 notes are rewritten for the sentinel semantics and when to override it with an explicit credentialId.	2026-09-03 13:10:10 +07:00
Dai Ha	c796eac09c	fleetd #176 : subtract the lead's own subscription seat from free CI / contract (pull_request) Successful in 1m11s Details CI / build (pull_request) Successful in 1m16s Details maxLoad counted panes, never subscription seats: a subscription:true profile's lead is itself a live claude session on that same account, so free overstated capacity by the lead's own seat (measured free:1 with a real ceiling of 0, and free:3 on an idle fleet with a real ceiling of 2). Add FleetMcp.LeadSeatSource (same shape as QuarantineSource/ OutageSource) and Fleetd.leadSeatLookup, which derives the seat count from fleet.leaders.<name>.profile matched against the target profile by effectiveCredentialId() - no hardcoded "-1", and no new config key: profile: already exists for this exact "which account does this lead share" question. maxLoad itself is left untouched; only free (and a new, additive-only leadSeats field) changes. Exhaustion quarantine (cause 2 in the ticket) already forced free to 0 via the same BackendQuarantine capacityView already reads - confirmed by reading the exhaustionSink wiring, no code change needed there.	2026-09-03 12:55:08 +07:00