CB-599: surface a capacity refusal's reason instead of a bare 500

PlacementException extends IllegalStateException, which neither BridgedApp
nor BridgeMcp's spawn catch blocks handled, so a maxLoad/quarantine/
all-exhausted refusal fell through to a blank 500 on REST and lost its
message on MCP. Catch it on both surfaces, ahead of the unrelated
IllegalArgumentException(unknown_profile) mapping, and return its message
structured: REST as {"error":"no_capacity","detail":...} with status 503,
MCP as an isError result prefixed "no capacity: ...".

bridged/bridged.example.yaml

@@ -88,28 +88,15 @@ bind:
 #   backoffMs: 60000
 #   quietNudgeCap: 3
 
-# Fleet health detection is dormant unless enabled (CB-573). It reads one whole-fleet agent list
-# per tick.
-#   intervalSeconds → how often a tick runs (default 30). ENFORCED floor of 15: the code computes
-#                      Math.max(15, intervalSeconds), so a lower value is silently raised, not
-#                      rejected.
-#   workingSuspectAfterSeconds, paneProbeIntervalSeconds → accepted and parsed, but NOT YET READ by
-#                      anything — the dormant monitor only consumes intervalSeconds today (CB-573
-#                      shipped ahead of the evidence publishers these two knobs are for). Setting
-#                      them changes nothing right now, and no minimum is enforced on either, because
-#                      nothing reads them to enforce one. They exist so a later build can start
-#                      honouring them without another config-shape change.
-#   notifications.mode → "webhook" flips what bridge_list REPORTS (healthCoverage: "full" instead
-#                      of "detection-only") — it does NOT make bridged send any webhook call; no
-#                      delivery mechanism is implemented yet. Any other value, or omitting the
-#                      block, reports "detection-only".
+# Fleet health detection is dormant unless enabled. It reads one whole-fleet agent list per tick.
+# It can run without a webhook; bridge_list then reports healthCoverage: detection-only.
 # health:
 #   enabled: true
-#   intervalSeconds: 30
-#   workingSuspectAfterSeconds: 600
-#   paneProbeIntervalSeconds: 60
+#   intervalSeconds: 30              # minimum 15
+#   workingSuspectAfterSeconds: 600  # minimum 300
+#   paneProbeIntervalSeconds: 60     # minimum 60
 #   notifications:
-#     mode: disabled
+#     mode: disabled                 # disabled (default) or webhook
 
 # herdr Unix socket. Omit to use the client default
 # (${HERDR_SOCKET_PATH:-~/.config/herdr/herdr.sock}).
@@ -299,11 +286,6 @@ placement: weighted
 #               / credentialId. Those are hot because the placement policy (and, for credentialId,
 #               the CB-578 stage B quarantine check) reads them through a supplier — being config is
 #               not by itself enough to make a key hot.
-#               EXCEPT `fleet.leaders`: Bridged.main reads it once at startup to build the lead tab
-#               scanner and launcher, and neither is rebuilt on reload. A changed/added/removed
-#               `fleet.leaders` entry is silently accepted — the reload reports "config reloaded"
-#               with nothing in the deferred list — but has NO effect until you restart. Treat it
-#               as deferred in practice, even though today's reload output does not say so.
 #   DEFERRED  → accepted into the new config, but the wiring built at startup keeps the old value
 #               until you restart: `lifecycle:`, `leadHeartbeat:`, `guard:`, `worktreeRoot:`,
 #               `spawnReadyTimeoutMs` / `spawnReadyPollMs`, `quarantineCooldownSeconds` (CB-578
@@ -386,12 +368,6 @@ fleet:
   # An auto-launched lead is NOT a member: it gets no worker reply charter, is never registered with
   # the session lifecycle (the idle reaper would kill your orchestrator), and stays on the
   # subscription — ANTHROPIC_BASE_URL/AUTH_TOKEN are stripped from its env whatever the profile says.
-  #
-  # GET THE `tab:` VALUE RIGHT. A pane that does not match any configured `tab:` (a typo, a renamed
-  # tab, a pane no entry names at all) is not recognised as a lead — it resolves as an ordinary
-  # WORKER instead, silently, and every orchestration call it makes (spawn/stop/send/drain) is
-  # refused. There is no error at startup for this: an unmatched pane is simply not a lead. If your
-  # primary suddenly can't spawn or send, check this section first.
   # leaders:
   #   opus-5.0:
   #     profile: opus                # omit to never create this lead, only recognise it
@@ -447,15 +423,10 @@ guard:
 #   idleTtlSeconds     → reap READY/DONE sessions idle longer than this (never BUSY/SPAWNING)
 #   contextCap         → force-release a session after this many delegated turns
 #   drainTimeoutSeconds → seconds to wait for BUSY sessions on shutdown before forced teardown
-#   clearAfterTurn     → whether a reusable worker discards its conversation context after every
-#                        completed delegated turn (default false). Works for claude-code workers
-#                        only — any other peer kind (e.g. opencode) logs "context reset is
-#                        unsupported for peer kind …" once and the reset is a no-op.
 # lifecycle:
 #   idleTtlSeconds: 300
 #   contextCap: 10
 #   drainTimeoutSeconds: 5
-#   clearAfterTurn: false
 
 # Durable reply delivery (CB-307 Stage 2). OMIT this block entirely to keep the default
 # in-memory, soft-state reply inbox (late worker replies are held only until a daemon bounce).

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

@@ -83,6 +83,10 @@ public final class Bridged {
     static void main(String[] args) {
         Path configPath = Path.of(args.length > 0 ? args[0] : "bridged.yaml");
         BridgedConfig cfg = BridgedConfig.load(configPath);
+        // CB-594: report which secret env vars the config actually needs, by name, before anything
+        // else can fail on a silently-empty one. A daemon started without a login shell (launchd)
+        // boots fine either way — this is the only thing that says so out loud.
+        reportRequiredSecrets(cfg);
         // CB-559: `cfg` stays the startup snapshot — every validation and every piece of one-time
         // wiring below reads it, and must, because those decisions cannot be unmade. `config` is the
         // live reference the hot paths read per use. Which keys can actually move is ConfigRef's
@@ -544,6 +548,63 @@ public final class Bridged {
         return target -> presence.isPresent(target) || leads.get().containsKey(target);
     }
 
+    /**
+     * CB-594: which env vars the loaded config actually needs, and why — every non-{@code
+     * subscription} profile's {@code tokenEnv} (a subscription profile never reads one, see
+     * {@link BridgedConfig.Profile#isSubscription()}), plus every profile's {@code gitTokenEnv}
+     * where set (opt-in). Derived from the config, not hard-coded, so a new profile is covered for
+     * free. A var required by more than one profile is one entry naming every profile that needs
+     * it. Deliberately excludes {@code auth.tokenEnv}: that one is already enforced loudly, by a
+     * startup throw, a few lines above this method's call site.
+     *
+     * <p>Package-private and pure (no I/O, no logging) so the derivation is unit-testable without
+     * capturing log output; {@link #reportRequiredSecrets(BridgedConfig)} is the logging caller.
+     */
+    static Map<String, List<String>> requiredSecretEnvVars(BridgedConfig cfg) {
+        Map<String, List<String>> requiredBy = new LinkedHashMap<>();
+        cfg.profiles().forEach((name, profile) -> {
+            if (!profile.isSubscription()) {
+                requiredBy.computeIfAbsent(profile.tokenEnv(), _ -> new ArrayList<>())
+                        .add("profile '" + name + "' tokenEnv");
+            }
+            if (profile.hasGitToken()) {
+                requiredBy.computeIfAbsent(profile.gitTokenEnv(), _ -> new ArrayList<>())
+                        .add("profile '" + name + "' gitTokenEnv");
+            }
+        });
+        return requiredBy;
+    }
+
+    /**
+     * CB-594: log, by name only, which required env vars (see {@link #requiredSecretEnvVars}) are
+     * set in the daemon's own process environment — the environment every profile's {@code
+     * tokenEnv}/{@code gitTokenEnv} is read from at spawn time (see
+     * {@code HerdrPeerLauncher.resolveEnv}). Never logs a value, a prefix, or a length.
+     *
+     * <p>A missing entry only warns — it must never refuse to start. A daemon that boots and says
+     * what is wrong is strictly more useful than one that will not boot at all.
+     */
+    private static void reportRequiredSecrets(BridgedConfig cfg) {
+        Map<String, List<String>> requiredBy = requiredSecretEnvVars(cfg);
+        if (requiredBy.isEmpty()) {
+            log.info("startup secrets: no profile references a token env var — nothing to check");
+            return;
+        }
+        Map<String, String> env = System.getenv();
+        requiredBy.forEach((varName, sources) -> {
+            String value = env.get(varName);
+            if (value != null && !value.isBlank()) {
+                log.info("startup secret {}: set ({})", varName, String.join(", ", sources));
+            } else {
+                log.warn("startup secret {}: MISSING ({}) — the daemon will start anyway, and this "
+                                + "failure stays invisible until a worker actually needs it. Fix "
+                                + "${SHARED_ENV}/tools/secrets.sh and restart bridged from a LOGIN "
+                                + "shell (see scripts/redeploy-bridged.sh).",
+                        varName, String.join(", ", sources));
+            }
+        });
+    }
+
     /**
      * Poll herdr's {@code ping} until it answers or {@link #HERDR_WAIT_SECONDS} elapses (CB-504).
      *

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

@@ -15,6 +15,7 @@ import dev.ltms.bridged.msg.MessageService;
 import dev.ltms.bridged.msg.Rendezvous;
 import dev.ltms.bridged.peer.PeerUnreachableException;
 import dev.ltms.bridged.placement.BackendQuarantine;
+import dev.ltms.bridged.placement.PlacementException;
 import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.session.MemberSession;
 import dev.ltms.bridged.session.WorktreeRequest;
@@ -692,6 +693,10 @@ public final class BridgeMcp {
             return text(json(memberView(member)));
         } catch (GuardException e) {
             return error("subscription boundary: " + e.getMessage());
+        } catch (PlacementException e) {
+            // CB-599: no candidate had capacity (maxLoad, quarantine, or all-exhausted) — distinct
+            // from "profile does not exist" below.
+            return error("no capacity: " + e.getMessage());
         } catch (IllegalArgumentException e) {
             return error(e.getMessage()); // unknown / no-default profile, or a refused resumeSessionId
         } catch (PeerUnreachableException e) {

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

@@ -13,6 +13,7 @@ import dev.ltms.bridged.herdr.HerdrClient;
 import dev.ltms.bridged.herdr.HerdrException;
 import dev.ltms.bridged.inject.MemberPresence;
 import dev.ltms.bridged.peer.PeerUnreachableException;
+import dev.ltms.bridged.placement.PlacementException;
 import dev.ltms.bridged.msg.MessageService;
 import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.peer.MemberRole;
@@ -292,6 +293,11 @@ public final class BridgedApp {
             ctx.status(201).json(view(member));
         } catch (GuardException e) {
             ctx.status(403).json(Map.of("error", "subscription_boundary", "detail", e.getMessage()));
+        } catch (PlacementException e) {
+            // CB-599: no candidate had capacity (maxLoad, quarantine, or all-exhausted) — a benign,
+            // likely-transient refusal, distinct from "profile does not exist" below. 503: the
+            // request was valid and will likely succeed later.
+            ctx.status(503).json(Map.of("error", "no_capacity", "detail", e.getMessage()));
         } catch (IllegalArgumentException e) {
             ctx.status(400).json(Map.of("error", "unknown_profile", "detail", e.getMessage()));
         } catch (PeerUnreachableException e) {

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

@@ -0,0 +1,114 @@
+package dev.ltms.bridged;
+
+import dev.ltms.bridged.config.BridgedConfig;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * CB-594: {@link Bridged#requiredSecretEnvVars(BridgedConfig)} is what decides what the startup
+ * secret report checks — it must derive that set from the config, not a hand-written list, or a
+ * new profile's token silently stops being reported.
+ */
+class RequiredSecretEnvVarsTest {
+
+    private static BridgedConfig load(Path dir, String yaml) throws Exception {
+        Path f = dir.resolve("bridged.yaml");
+        Files.writeString(f, yaml);
+        return BridgedConfig.load(f);
+    }
+
+    @Test
+    void collectsATokenEnvPerNonSubscriptionProfile(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                """);
+
+        Map<String, List<String>> required = Bridged.requiredSecretEnvVars(cfg);
+
+        assertTrue(required.containsKey("AI_GATEWAY_TOKEN"));
+        assertEquals(List.of("profile 'local' tokenEnv"), required.get("AI_GATEWAY_TOKEN"));
+    }
+
+    @Test
+    void aSubscriptionProfileNeedsNoTokenEnv(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  opus:
+                    subscription: true
+                    model: claude-opus-5
+                """);
+
+        assertTrue(Bridged.requiredSecretEnvVars(cfg).isEmpty(),
+                "subscription: true never reads ANTHROPIC_AUTH_TOKEN — see Profile#isSubscription");
+    }
+
+    @Test
+    void gitTokenEnvIsOptInAndCollectedWhenSet(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                    gitTokenEnv: WORKER_GITEA_TOKEN
+                """);
+
+        Map<String, List<String>> required = Bridged.requiredSecretEnvVars(cfg);
+
+        assertTrue(required.containsKey("WORKER_GITEA_TOKEN"));
+        assertEquals(List.of("profile 'local' gitTokenEnv"), required.get("WORKER_GITEA_TOKEN"));
+    }
+
+    @Test
+    void noGitTokenEnvMeansNothingIsRequiredForIt(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                """);
+
+        assertFalse(Bridged.requiredSecretEnvVars(cfg).containsKey("WORKER_GITEA_TOKEN"));
+    }
+
+    @Test
+    void aVarSharedByTwoProfilesIsReportedOnceNamingBoth(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, """
+                profiles:
+                  local:
+                    baseUrl: http://gx00.gw:8000
+                    tokenEnv: AI_GATEWAY_TOKEN
+                    gitTokenEnv: WORKER_GITEA_TOKEN
+                  gx:
+                    kind: opencode
+                    baseUrl: https://llm.ltms.dev/v1
+                    tokenEnv: AI_GATEWAY_TOKEN
+                    gitTokenEnv: WORKER_GITEA_TOKEN
+                """);
+
+        Map<String, List<String>> required = Bridged.requiredSecretEnvVars(cfg);
+
+        assertEquals(List.of("profile 'local' tokenEnv", "profile 'gx' tokenEnv"),
+                required.get("AI_GATEWAY_TOKEN"));
+        assertEquals(List.of("profile 'local' gitTokenEnv", "profile 'gx' gitTokenEnv"),
+                required.get("WORKER_GITEA_TOKEN"));
+    }
+
+    @Test
+    void noProfilesMeansNothingIsRequired(@TempDir Path dir) throws Exception {
+        BridgedConfig cfg = load(dir, "bind:\n  host: 127.0.0.1\n  port: 8765\n");
+
+        assertTrue(Bridged.requiredSecretEnvVars(cfg).isEmpty());
+    }
+}

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

@@ -16,12 +16,15 @@ import dev.ltms.bridged.inject.MemberPresence;
 import dev.ltms.bridged.session.MemberSession;
 import dev.ltms.bridged.session.WorktreeRequest;
 import dev.ltms.bridged.member.ClaudeCodeLauncher;
+import dev.ltms.bridged.member.CompositePeerLauncher;
 import dev.ltms.bridged.placement.BackendQuarantine;
+import dev.ltms.bridged.placement.PlacementPolicies;
 import io.modelcontextprotocol.spec.McpSchema;
 import dev.ltms.bridged.msg.InMemoryReplyInbox;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
+import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
@@ -423,6 +426,35 @@ class BridgeMcpTest {
         assertTrue(textOf(res).contains("unknown worker profile"), textOf(res));
     }
 
+    /**
+     * CB-599: a profile at its {@code maxLoad} cap must surface a readable reason on the MCP
+     * surface too, not merely flip {@code isError} with an opaque or absent message.
+     */
+    @Test
+    void spawnAtMaxLoadSurfacesTheCapacityReason() {
+        FakeHerdr h = new FakeHerdr();
+        BridgedConfig.Profile wcfg = new BridgedConfig.Profile(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN", null,
+                "tab", "bridged-workers", "worker: {profile} #{n}", null,
+                null, null, null, null, null, null, null, 0, null, null, null);
+        Map<String, BridgedConfig.Profile> profiles = Map.of(wcfg.profile(), wcfg);
+        ClaudeCodeLauncher delegate = new ClaudeCodeLauncher(
+                new AgentControl(h), new WorkspaceControl(h), new SubscriptionGuard(Set.of("gx00.gw")),
+                profiles, wcfg.profile(), k -> "BRIDGED_WORKER_TOKEN".equals(k) ? "tok" : null);
+        CompositePeerLauncher composite = new CompositePeerLauncher(
+                List.of(delegate), wcfg.profile(), profiles, PlacementPolicies.fixed(), _ -> 0);
+        SessionManager sm = new SessionManager(composite);
+
+        McpSchema.CallToolResult res = BridgeMcp.spawn(sm, "ltms-local");
+
+        assertTrue(res.isError());
+        String text = textOf(res);
+        assertTrue(text.contains("no capacity"), "surfaces a capacity reason, not a bare error: " + text);
+        assertTrue(text.contains("ltms-local"), "names the profile: " + text);
+        assertTrue(text.contains("maxLoad"), "explains the refusal: " + text);
+        assertFalse(h.called("agent.start"), "at cap, the spawn is refused before any herdr call");
+    }
+
     @Test
     void spawnPassesTheRequestedCwdToTheWorker() {
         FakeHerdr h = new FakeHerdr();

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

@@ -18,6 +18,8 @@ import dev.ltms.bridged.session.GitWorktrees;
 import dev.ltms.bridged.session.SessionManager;
 import dev.ltms.bridged.session.Worktrees;
 import dev.ltms.bridged.member.ClaudeCodeLauncher;
+import dev.ltms.bridged.member.CompositePeerLauncher;
+import dev.ltms.bridged.placement.PlacementPolicies;
 import io.javalin.Javalin;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
@@ -240,6 +242,43 @@ class BridgedAppTest {
         assertFalse(herdr.called("agent.start"), "an unknown profile must not spawn anything");
     }
 
+    /**
+     * CB-599: a profile at its {@code maxLoad} cap must not surface as a bare 500 — the caller
+     * needs a structured, readable reason, distinct from "unknown_profile".
+     */
+    @Test
+    void spawnAtMaxLoadIs503WithTheCapacityReasonNotABare500() throws Exception {
+        FakeHerdr herdr = new FakeHerdr();
+        BridgedConfig.Profile wcfg = new BridgedConfig.Profile(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN", null,
+                "tab", "bridged-workers", "worker: {profile} #{n}", null,
+                null, null, null, null, null, null, null, 0, null, null, null);
+        Map<String, BridgedConfig.Profile> profiles = Map.of(wcfg.profile(), wcfg);
+        ClaudeCodeLauncher delegate = new ClaudeCodeLauncher(
+                new AgentControl(herdr), new WorkspaceControl(herdr), new SubscriptionGuard(Set.of("gx00.gw")),
+                profiles, wcfg.profile(), k -> "BRIDGED_WORKER_TOKEN".equals(k) ? "tok-abc" : null);
+        CompositePeerLauncher workers = new CompositePeerLauncher(
+                List.of(delegate), wcfg.profile(), profiles, PlacementPolicies.fixed(), _ -> 0);
+        SessionManager sessions = new SessionManager(workers, new GitWorktrees());
+        this.presence = sessions.asPresence();
+        Injector injector = new Injector(new AgentControl(herdr));
+        InMemoryReplyInbox inbox = new InMemoryReplyInbox();
+        sessions.onAcquire(inbox::own);
+        MessageService messages = new MessageService(new AgentControl(herdr), injector, new Rendezvous(), inbox);
+        app = new BridgedApp(herdr, workers, sessions, messages, this.presence, null).build().start("127.0.0.1", 0);
+        int port = app.port();
+
+        HttpResponse<String> res = req(port, "POST", "/members?profile=ltms-local");
+
+        assertEquals(503, res.statusCode(), res.body());
+        JsonNode body = mapper.readTree(res.body());
+        assertEquals("no_capacity", body.get("error").asText());
+        String detail = body.get("detail").asText();
+        assertTrue(detail.contains("ltms-local"), "detail names the profile: " + detail);
+        assertTrue(detail.contains("maxLoad"), "detail explains the refusal: " + detail);
+        assertFalse(herdr.called("agent.start"), "at cap, the spawn is refused before any herdr call");
+    }
+
     @Test
     void spawnWorkerReusesExistingWorkerSpace() throws Exception {
         // A space labelled "bridged-workers" already exists → no second workspace.create.

deploy/dev.ltms.bridged.plist

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <!--
-  CB-504 — launchd agent for bridged (macOS).
+  CB-504 / CB-594 — launchd agent for bridged (macOS).
 
   This is the real supervision target today: the dogfooded daemon runs on macOS, where there is
   no systemd. A systemd unit ships alongside (deploy/bridged.service) for the Linux gateways
@@ -9,14 +9,33 @@
 
   Install:
     cp deploy/dev.ltms.bridged.plist ~/Library/LaunchAgents/
-    # edit the paths + JAVA_HOME below to match this host, then:
     launchctl load -w ~/Library/LaunchAgents/dev.ltms.bridged.plist
     launchctl list | grep bridged
 
+  The paths below are already filled in for this host (resolved 2026-08-16 from
+  `/usr/libexec/java_home`... except that reported the system Applet-plugin JVM, not the jenv-
+  managed JDK 25 actually used to build/run bridged, so JAVA_HOME here is the real one:
+  `JENV_VERSION=25.0.3 java -XshowSettings:properties -version 2>&1 | grep java.home`; `which mvn`;
+  `echo $HOME`). If this file is copied to a different host, re-resolve all three paths and check
+  no placeholder path is left behind; scripts/redeploy-bridged.sh's check mode does not (and
+  cannot) check this file for you.
+
+  CB-594 — launchd cannot run a login shell (see the PATH comment on EnvironmentVariables below,
+  and scripts/bridged-launchd-wrapper.sh for the fix): ProgramArguments below execs THAT wrapper,
+  not java directly, so WORKER_GITEA_TOKEN and AI_GATEWAY_TOKEN still get sourced from
+  ${SHARED_ENV}/tools/secrets.sh even though launchd itself never sources anything.
+
   Note on ordering: launchd has no "start after herdr" primitive for user agents, and neither
   does systemd in a way that survives a socket appearing late. bridged retries the herdr socket
   on startup instead, so an agent that comes up before herdr converges rather than dying — that
   retry is the actual fix; KeepAlive below is the backstop.
+
+  CB-594 — KeepAlive vs. scripts/redeploy-bridged.sh: a bare SIGTERM makes this JVM exit 143 even
+  with its shutdown hook running to completion (measured, see the CB-594 report), which
+  SuccessfulExit:false below reads as a crash and races to restart the OLD jar. The redeploy
+  script now detects a loaded agent and uses `launchctl unload`/`load` instead of a raw kill, so
+  only one supervisor ever touches the process at a time — read that script's own output on a
+  redeploy for the confirmation.
 -->
 <plist version="1.0">
 <dict>
@@ -25,22 +44,23 @@
 
     <key>ProgramArguments</key>
     <array>
-        <string>/Users/CHANGEME/Tool/jdk-25.0.2.jdk/Contents/Home/bin/java</string>
+        <string>/Users/dai.ha/LTMS/claude-bridge/scripts/bridged-launchd-wrapper.sh</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home/bin/java</string>
         <string>-jar</string>
-        <string>/Users/CHANGEME/src/claude-bridge/bridged/target/bridged.jar</string>
+        <string>/Users/dai.ha/LTMS/claude-bridge/bridged/target/bridged.jar</string>
         <string>bridged.yaml</string>
     </array>
 
     <!-- Config path in ProgramArguments is relative, so the working directory must be the module. -->
     <key>WorkingDirectory</key>
-    <string>/Users/CHANGEME/src/claude-bridge/bridged</string>
+    <string>/Users/dai.ha/LTMS/claude-bridge/bridged</string>
 
     <key>EnvironmentVariables</key>
     <dict>
         <key>JAVA_HOME</key>
-        <string>/Users/CHANGEME/Tool/jdk-25.0.2.jdk/Contents/Home</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home</string>
         <key>HERDR_SOCKET_PATH</key>
-        <string>/Users/CHANGEME/.config/herdr/herdr.sock</string>
+        <string>/Users/dai.ha/.config/herdr/herdr.sock</string>
         <!--
           PATH matters more than it looks (CB-511): bridged propagates its own PATH to every worker
           it spawns, so this line decides whether the fleet can run a build at all. launchd does NOT
@@ -48,11 +68,14 @@
           bare /usr/bin:/bin and no JDK or Maven. Keep the toolchain entries first.
         -->
         <key>PATH</key>
-        <string>/Users/CHANGEME/Tool/jdk-25.0.2.jdk/Contents/Home/bin:/Users/CHANGEME/Tool/apache-maven-3.9.16/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <string>/Users/dai.ha/Softwares/jdks/jdk-25.0.3.jdk/Contents/Home/bin:/Users/dai.ha/Softwares/apache-maven/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
         <!--
-          Worker/API tokens are NOT set here: this file is committed. Export them from a private
-          launchd override or a wrapper script. bridged reads the API token from the env var named
-          by auth.tokenEnv (default BRIDGED_API_TOKEN) and only in auth.mode: token.
+          Worker/API tokens are NOT set here: this file is committed. CB-594 —
+          scripts/bridged-launchd-wrapper.sh (named in ProgramArguments above) is what supplies
+          them, by execing a login shell that sources ${SHARED_ENV}/tools/secrets.sh before the
+          daemon itself starts. bridged also reads the API token from the env var named by
+          auth.tokenEnv (default BRIDGED_API_TOKEN) and only in auth.mode: token — the wrapper
+          covers that one too, since it is the same login shell.
         -->
     </dict>
 
@@ -69,10 +92,17 @@
     <key>ThrottleInterval</key>
     <integer>10</integer>
 
+    <!--
+      CB-594 — same file scripts/redeploy-bridged.sh already tails ($BRIDGED/bridged.out), and both
+      streams point at it, not two separate log files: the script's fresh-line / ERROR-count checks
+      after a restart read this one path regardless of whether launchd or the script started the
+      process, and a stdout/stderr split would make half of what happens during a launchd-driven
+      restart invisible to it.
+    -->
     <key>StandardOutPath</key>
-    <string>/Users/CHANGEME/src/claude-bridge/bridged/logs/bridged.out.log</string>
+    <string>/Users/dai.ha/LTMS/claude-bridge/bridged/bridged.out</string>
     <key>StandardErrorPath</key>
-    <string>/Users/CHANGEME/src/claude-bridge/bridged/logs/bridged.err.log</string>
+    <string>/Users/dai.ha/LTMS/claude-bridge/bridged/bridged.out</string>
 
     <key>ProcessType</key>
     <string>Background</string>

scripts/bridged-launchd-wrapper.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# CB-594 — the only reason this file exists: launchd does not run a login shell.
+#
+# WORKER_GITEA_TOKEN and AI_GATEWAY_TOKEN live in ${SHARED_ENV}/tools/secrets.sh, sourced only by a
+# LOGIN shell (.zprofile/.zshrc etc). launchd execs a job's ProgramArguments directly — no shell, no
+# profile, nothing sourced (the plist's own PATH comment documents the same gap one variable over).
+# A daemon started that way boots fine and looks healthy; the failure is invisible until a worker
+# tries to open a PR (WORKER_GITEA_TOKEN empty) or a gateway profile gets a 401 (AI_GATEWAY_TOKEN
+# empty) — hours later, with nothing tying the two together (CB-591, CLAUDE.md "Redeploying the
+# daemon"). Bridged now also logs which required secret names resolved at startup (see
+# Bridged.reportRequiredSecrets), but that log line can only tell the truth if the tokens had a
+# chance to be sourced in the first place — which is this script's entire job.
+#
+# So: launchd execs THIS script instead of java directly. This script execs a login shell
+# ('zsh -l'), which sources secrets.sh, and that shell execs the real command in its place — one
+# process throughout (exec, not a subshell fork), so launchd's PID tracking, KeepAlive, and
+# StandardOut/ErrorPath all still see the one process they expect.
+#
+# The plist passes the full command as THIS script's own arguments, e.g.:
+#   ProgramArguments = [ .../bridged-launchd-wrapper.sh, /path/to/java, -jar, /path/to/bridged.jar,
+#                        bridged.yaml ]
+# so the wrapper stays generic and the actual command lives in exactly one place (the plist), not
+# duplicated here.
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "bridged-launchd-wrapper.sh: no command given — check the plist's ProgramArguments" >&2
+  exit 2
+fi
+
+exec /bin/zsh -lc 'exec "$@"' -- "$@"

scripts/redeploy-bridged.sh

@@ -5,13 +5,14 @@
 # A merge is not a deployment: the running daemon holds the jar it was started with, so code merged
 # to main does nothing until this runs. See CLAUDE.md -> "Redeploying the daemon".
 #
-# This script exists to turn five remembered traps into one auditable command:
+# This script exists to turn six remembered traps into one auditable command:
 #
 #   1. A piped `mvn` hides BUILD FAILURE behind a zero exit, so the build here is never piped.
 #   2. The daemon must start from a LOGIN shell, or the tokens it hands to members are empty:
 #      WORKER_GITEA_TOKEN (workers cannot open a PR) and AI_GATEWAY_TOKEN (401 at llm.ltms.dev).
 #      Both are read from the DAEMON's own environment at spawn time, so a value added to
-#      secrets.sh after startup is absent. Nothing logs this, so the script checks and says so.
+#      secrets.sh after startup is absent. Nothing logs this here, so the script checks and says
+#      so — and since CB-594, bridged's own startup log says so too, by env var name.
 #   3. An old daemon that never actually died looks identical from the outside, so the script waits
 #      for the process to exit and for the port to free before it starts a new one.
 #   4. "It started" is not "it works": the script polls /healthz until it answers, and reports the
@@ -19,6 +20,13 @@
 #      mismatch.
 #   5. Restarting under live members drops their tickets, so the script refuses unless you confirm
 #      the fleet is drained.
+#   6. CB-594 — the launchd agent (deploy/dev.ltms.bridged.plist), if installed and loaded, is a
+#      SECOND supervisor: its KeepAlive.SuccessfulExit=false restarts the daemon on any nonzero
+#      exit, and a bare SIGTERM makes this JVM exit 143 even with its shutdown hook running to
+#      completion (measured — see the CB-594 report). A plain `kill` here would race launchd's own
+#      restart of the OLD jar. So this script detects whether the agent is loaded and, only then,
+#      swaps `kill` + manual `nohup` for `launchctl unload`/`load` — the one supervisor in control
+#      at any moment is whichever one you asked to act, never both.
 #
 # Usage:
 #   scripts/redeploy-bridged.sh              # build, confirm, restart, verify
@@ -43,13 +51,17 @@ HEALTH='http://127.0.0.1:8765/healthz'
 STOP_WAIT=30      # seconds to wait for a clean exit before reporting failure
 HEALTH_WAIT=60    # seconds to wait for /healthz to answer after start
 
+# CB-594: the launchd agent this script must not fight with (see trap 6 above).
+LAUNCHD_LABEL='dev.ltms.bridged'
+LAUNCHD_PLIST="$HOME/Library/LaunchAgents/$LAUNCHD_LABEL.plist"
+
 DO_BUILD=1; ASSUME_YES=0; CHECK_ONLY=0
 for arg in "$@"; do
   case "$arg" in
     --yes|-y)   ASSUME_YES=1 ;;
     --no-build) DO_BUILD=0 ;;
     --check)    CHECK_ONLY=1 ;;
-    -h|--help)  sed -n '3,30p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -h|--help)  sed -n '3,37p' "${BASH_SOURCE[0]}"; exit 0 ;;
     *) echo "unknown option: $arg (try --help)" >&2; exit 2 ;;
   esac
 done
@@ -61,6 +73,11 @@ die()  { printf '\n   FAIL  %s\n\n' "$*" >&2; exit 1; }
 
 jar_id() { [ -f "$JAR" ] && shasum -a 256 "$JAR" | cut -c1-12 || echo "absent"; }
 running_pid() { pgrep -f "$PATTERN" || true; }
+# `launchctl list <label>` exits 0 iff the label is loaded (registered with launchd) — true whether
+# or not it is currently running, which is exactly "supervision is active" for our purposes. Read-
+# only: neither helper below changes anything, so both are also safe under --check.
+launchd_installed() { [ -f "$LAUNCHD_PLIST" ]; }
+launchd_loaded() { launchctl list "$LAUNCHD_LABEL" >/dev/null 2>&1; }
 
 # ---------------------------------------------------------------- report state
 
@@ -74,6 +91,22 @@ fi
 ok "jar on disk: $(jar_id)  ($([ -f "$JAR" ] && date -r "$JAR" '+%Y-%m-%d %H:%M:%S' || echo 'none'))"
 ok "HEAD: $(git -C "$REPO" log --oneline -1)"
 
+# CB-594: supervision state. Installed and loaded are different facts — a copied-but-never-loaded
+# plist supervises nothing, and a loaded label with no file backing it (rare, but possible after an
+# edited/moved plist) is still what launchd will act on.
+if launchd_installed; then
+  ok "launchd agent installed: $LAUNCHD_PLIST"
+else
+  warn "launchd agent NOT installed (no supervision — a crash will not restart the daemon)."
+fi
+SUPERVISED=0
+if launchd_loaded; then
+  SUPERVISED=1
+  ok "launchd agent loaded ($LAUNCHD_LABEL) — launchd supervises this daemon"
+else
+  warn "launchd agent not loaded — this script is the only thing that will restart the daemon."
+fi
+
 # The trap with no log line. Checked in a LOGIN shell, because that is how the daemon is started
 # below. Never prints the value — only whether it resolved.
 if zsh -lc '[ -n "${WORKER_GITEA_TOKEN:-}" ]' 2>/dev/null; then
@@ -137,11 +170,26 @@ if [ -n "$OLD_PID" ] && [ "$ASSUME_YES" = 0 ]; then
 fi
 
 # ------------------------------------------------------------------ stop
+#
+# CB-594: when SUPERVISED, launchd owns the stop — never a raw `kill` here. A bare SIGTERM makes
+# this JVM exit 143 even with its shutdown hook running to completion (verified separately: a
+# throwaway Java process with an equivalent shutdown hook, sent SIGTERM from a login shell that
+# could `wait` on it directly, reported exit code 143 every time — never 0). launchd's
+# KeepAlive.SuccessfulExit=false treats any nonzero exit as a crash and restarts the OLD jar,
+# which would race this script's own restart of the NEW one. `launchctl unload` avoids that race
+# by deregistering the job first, so no KeepAlive is left armed when the process actually stops.
 
 if [ -n "$OLD_PID" ]; then
   say "stop"
   RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"   # verify a FRESH line appears later
-  kill "$OLD_PID"
+  if [ "$SUPERVISED" = 1 ]; then
+    echo "   supervision is ON: using 'launchctl unload' (not kill) so launchd's own KeepAlive"
+    echo "   cannot restart the OLD jar out from under this script — see the CB-594 comment above."
+    launchctl unload -w "$LAUNCHD_PLIST" \
+      || die "launchctl unload failed — the daemon may still be under supervision; investigate before retrying"
+  else
+    kill "$OLD_PID"
+  fi
   for _ in $(seq "$STOP_WAIT"); do
     [ -z "$(running_pid)" ] && break
     sleep 1
@@ -152,18 +200,33 @@ if [ -n "$OLD_PID" ]; then
         leave worktrees and panes behind. Investigate, then kill -9 by hand if you accept that."
   fi
   ok "pid $OLD_PID exited"
+elif [ "$SUPERVISED" = 1 ]; then
+  # Loaded but not currently running (e.g. throttled after a crash loop). Unload it anyway so the
+  # start step below does a clean load, never a load stacked on an already-loaded label.
+  say "stop"
+  RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"
+  launchctl unload -w "$LAUNCHD_PLIST" 2>/dev/null || true
+  ok "launchd agent unloaded (was already not running)"
 else
   RESTART_MARK="$(wc -l < "$OUT" 2>/dev/null || echo 0)"
 fi
 
 # ------------------------------------------------------------------ start
-# Login shell (zsh -l) is what puts the secrets on the daemon's environment. cwd must be bridged/
-# because the daemon resolves bridged.yaml, logs/ and target/ relative to it.
+# Unsupervised: login shell (zsh -l) is what puts the secrets on the daemon's environment, and cwd
+# must be bridged/ because the daemon resolves bridged.yaml, logs/ and target/ relative to it.
+# Supervised: launchd does both — deploy/dev.ltms.bridged.plist points ProgramArguments at
+# scripts/bridged-launchd-wrapper.sh (CB-594), which is what execs the login shell in launchd's
+# place, and WorkingDirectory in the plist already pins bridged/.
 
 say "start"
-# Absolute jar path so `ps` names which checkout is running; cwd still bridged/ because the daemon
-# resolves bridged.yaml, logs/ and target/ relative to it.
-( cd "$BRIDGED" && zsh -lc "nohup java -jar '$JAR' >> bridged.out 2>&1 &" )
+if [ "$SUPERVISED" = 1 ]; then
+  echo "   supervision is ON: using 'launchctl load' so launchd starts and keeps supervising this"
+  echo "   process, instead of a manual nohup that launchd would know nothing about."
+  launchctl load -w "$LAUNCHD_PLIST" || die "launchctl load failed"
+else
+  # Absolute jar path so `ps` names which checkout is running.
+  ( cd "$BRIDGED" && zsh -lc "nohup java -jar '$JAR' >> bridged.out 2>&1 &" )
+fi
 
 for _ in $(seq 10); do
   NEW_PID="$(running_pid)"