CB-602: guard against a config key that never reaches the example

BridgedConfig.KNOWN_TOP_LEVEL_KEYS is now package-private so a test can assert
every key the parser accepts appears in bridged.example.yaml — live or
commented-out, since the file is gitignored and the example is the only
committed description of the config schema. The existing tests only checked
the example->code direction; this adds code->example.

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/config/BridgedConfig.java

@@ -967,8 +967,12 @@ public record BridgedConfig(
     /**
      * Top-level keys this version understands. Used only to warn about the rest — see
      * {@link #warnUnknownTopLevelKeys}. Keep in step with the record components.
+     *
+     * <p>Package-private (not {@code private}) so a test can assert every key here is documented in
+     * {@code bridged.example.yaml} — the only committed description of the config schema, since
+     * {@code bridged.yaml} itself is gitignored.
      */
-    private static final Set<String> KNOWN_TOP_LEVEL_KEYS = Set.of(
+    static final Set<String> KNOWN_TOP_LEVEL_KEYS = Set.of(
             "bind", "herdrSocket", "profiles", "guard", "worktreeRoot",
             "lifecycle", "spawnReadyTimeoutMs", "spawnReadyPollMs", "broker", "primary", "fleet",
             "leadHeartbeat", "health", "placement", "auth", "configReload", "quarantineCooldownSeconds");

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/config/BridgedConfigTest.java

@@ -10,6 +10,7 @@ import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Pattern;
 
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -1189,6 +1190,79 @@ class BridgedConfigTest {
         assertEquals(5, cfg.leadHeartbeat().quietNudgeCap());
     }
 
+    /**
+     * A top-level key {@code BridgedConfig} reads but that appears nowhere in
+     * {@code bridged.example.yaml} — live or commented — is invisible drift: {@code bridged.yaml}
+     * is gitignored, so the example is the ONLY committed description of the config schema, and
+     * neither {@link #shippedExampleConfigParses} (example → code: does the example still parse)
+     * nor {@link #everyOptionalKnobDocumentedInTheExampleBinds} (a hand-maintained list of keys
+     * that must bind) can catch a brand-new key nobody added to either.
+     *
+     * <p>This test compares the OTHER direction: every key in {@link BridgedConfig#KNOWN_TOP_LEVEL_KEYS}
+     * (the parser's own accepted set, which backs the unknown-key WARN) must appear as a top-level
+     * key in the example text, live or commented-out — see {@link #topLevelKeyDocumented}.
+     */
+    @Test
+    void everyKnownTopLevelKeyIsDocumentedInTheExample() throws Exception {
+        Path example = Path.of("bridged.example.yaml");
+        assertTrue(Files.exists(example), "bridged.example.yaml must ship next to the pom");
+        String text = Files.readString(example);
+
+        List<String> undocumented = BridgedConfig.KNOWN_TOP_LEVEL_KEYS.stream()
+                .filter(key -> !topLevelKeyDocumented(text, key))
+                .sorted()
+                .toList();
+
+        assertTrue(undocumented.isEmpty(), () -> "key(s) " + undocumented
+                + " are read by BridgedConfig but appear nowhere in bridged.example.yaml — "
+                + "document each one there, commented out if optional. bridged.yaml is "
+                + "gitignored, so this file is the only committed description of the config "
+                + "schema an operator or a worker can see.");
+    }
+
+    /**
+     * Most of {@code bridged.example.yaml} is deliberately commented out — optional sections are
+     * documented as commented blocks so the shipped file stays a working minimal config. A key
+     * documented ONLY as a comment must still count as documented; parsing the file as YAML and
+     * reading its live key set (as an earlier attempt at this guard did) gets this wrong, because
+     * every commented section then looks entirely absent.
+     */
+    @Test
+    void commentedOnlyTopLevelKeyCountsAsDocumented() {
+        String yaml = """
+                bind:
+                  port: 8765
+                # broker:
+                #   uri: amqp://guest:guest@127.0.0.1:5672
+                """;
+        assertTrue(topLevelKeyDocumented(yaml, "broker"),
+                "a key documented only inside a commented-out block must still count as documented");
+    }
+
+    /** A key that appears in neither a live nor a commented top-level line must NOT count. */
+    @Test
+    void absentTopLevelKeyIsNotDocumented() {
+        String yaml = """
+                bind:
+                  port: 8765
+                """;
+        assertFalse(topLevelKeyDocumented(yaml, "broker"),
+                "a key mentioned nowhere in the example must not be reported as documented");
+    }
+
+    /**
+     * True when {@code key} appears as a top-level YAML key in {@code yaml} — either live
+     * ({@code key:} at column 0) or commented out ({@code # key:}, also at column 0, with only
+     * whitespace between the {@code #} and the key). Anchoring on column 0 is what keeps this a
+     * top-level check: an indented occurrence (a nested field, or prose inside a comment that
+     * happens to end in a colon) never matches, because {@code ^} requires the key's own first
+     * character — or the sole leading {@code #} — to sit at the very start of the line.
+     */
+    private static boolean topLevelKeyDocumented(String yaml, String key) {
+        Pattern p = Pattern.compile("(?m)^(?:#\\s*)?" + Pattern.quote(key) + ":");
+        return p.matcher(yaml).find();
+    }
+
     @Test
     void placementDefaultsToFixedForExistingConfigs(@TempDir Path dir) throws Exception {
         Path f = dir.resolve("no-placement.yaml");

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)"