CB-594: make supervision and a working fleet possible at the same time

Adds scripts/bridged-launchd-wrapper.sh so the launchd-run daemon still gets
WORKER_GITEA_TOKEN/AI_GATEWAY_TOKEN by execing through a login shell (launchd
never sources secrets.sh itself). bridged now logs at startup which required
token env vars (derived from each profile's tokenEnv/gitTokenEnv, not a
hand-written list) resolved or are MISSING, by name only. Fills in the real
paths in deploy/dev.ltms.bridged.plist for this host and points it at the
wrapper. scripts/redeploy-bridged.sh now detects a loaded launchd agent and
uses launchctl unload/load instead of a raw kill+nohup, because a bare
SIGTERM exits this JVM at 143 (measured) which KeepAlive.SuccessfulExit=false
reads as a crash and would race the script's own restart; --check reports
installed/loaded state and stays read-only.

CLAUDE.md

@@ -81,9 +81,9 @@ below are the procedure — run them in order, every task, not only the big ones
 5. **Collect** — `bridge_poll{ticket}` → `bridge_ack{ticket, msgId}`. Answer a worker's `bridge_ask`
    with `bridge_send{turnId, content}` — **not** `sessionId`. A worker gone quiet is diagnosed with
    `bridge_status`, never by reading its terminal.
-6. **Verify yourself.** Re-run the build and the checks. A worker mounts only the bridge MCP and
-   cannot run your other tooling, and a piped command (`… | tail`) hides failures behind a zero
-   exit — never promote a worker's "clean" to a fact.
+6. **Verify yourself.** Re-run the build and the checks. A worker cannot run your IDE tooling, any
+   forge tools it appears to have hold a blocked credential and fail, and a piped command
+   (`… | tail`) hides failures behind a zero exit — never promote a worker's "clean" to a fact.
 7. **Review — fan out.** Spawn reviewers against the diff, one per dimension or per file, with
    `wait:false`. Never the implementer of the scope it reviews, and brief them from the diff — not
    from the implementer's rationale, which carries its own blind spot. Dispatch each PR's reviewers
@@ -155,9 +155,13 @@ you.
    without replying, the bridge scrapes your pane, and it can return only the last 4000 characters.
    A clipped scrape is marked as partial, but the missing text is gone — your report reaches the
    lead with its end cut off.
-5. **Report honestly.** State only what you actually ran and its real output, including failures.
-   You mount **only** the bridge MCP — the primary's other servers (IDE, forge, docs) are not yours,
-   so never claim the result of a check you had no way to run.
+5. **Report honestly.** State only what you actually ran and its real output, including failures,
+   and never claim the result of a check you had no way to run. **Measure your own tools; do not
+   assume them.** What you mount depends on your backend: an opencode member gets the bridge and
+   nothing else, while a Claude Code member also inherits the operator's user-scope MCP servers,
+   which the bridge never chose for you. Two rules follow. The primary's IDE tooling is still not
+   yours, whatever you see. And **a mounted tool is not a working tool** — the forge server you may
+   find there holds a deliberately blocked credential and fails every call, by design.
 6. **Never merge.** Stage files explicitly — never `git add -A` — and leave alone anything the
    project marks as not-yours-to-commit.
 

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
@@ -543,6 +547,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/member/CompositePeerLauncher.java

@@ -372,8 +372,11 @@ public final class CompositePeerLauncher implements PeerLauncher {
     }
 
     private void enforceMaxLoad(String profile) {
-        // Absent config, or a config whose maxLoad normalized to null (non-positive ⇒ unlimited at
-        // load), means no cap — never cap what wasn't configured.
+        // Absent config, or a config whose maxLoad normalized to null (ABSENT ⇒ unlimited at load),
+        // means no cap — never cap what wasn't configured. Note "non-positive ⇒ unlimited" was true
+        // until CB-585: an explicit `maxLoad: 0` now survives as 0 and is a real cap of zero, so the
+        // check below refuses every spawn on that profile, and a negative value is refused at config
+        // load rather than normalized away.
         BridgedConfig.Profile cfg = profiles0().get(profile);
         Integer cap = (cfg == null) ? null : cfg.maxLoad();
         if (cap == null) {

bridged/src/main/java/dev/ltms/bridged/member/HerdrPeerLauncher.java

@@ -766,10 +766,61 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         }
     }
 
-    /** A fresh mutable env map — the conventional starting point for {@link #buildLaunch}. */
+    /**
+     * CB-592: overlay value that shadows the admin {@code GITEA_ACCESS_TOKEN} a herdr pane
+     * otherwise inherits from herdr's own login-shell process environment (gitea issue #77).
+     * herdr spawns a pane from its <em>own</em> process environment and layers our map on top —
+     * {@link dev.ltms.bridged.herdr.WorkspaceControl#createTab} and {@code #splitPane} send only
+     * the keys we put in that map, so any key we never mention passes straight through from
+     * herdr's own shell, admin token included.
+     *
+     * <p>Deliberately a non-blank sentinel, not {@code ""}. Whether an empty-string overlay value
+     * overrides an inherited variable or is skipped as blank could not be settled by reading this
+     * codebase — herdr's server-side merge is an external process, not something in this repo.
+     * A non-blank replacement sidesteps that ambiguity entirely: {@link #baseEnv}'s own {@code
+     * PATH} seeding already depends on the overlay reliably replacing an inherited value (see its
+     * javadoc), and that is only demonstrated for a non-blank value, so this reuses the same,
+     * proven-reliable shape rather than the unverified one.
+     *
+     * <p><b>MEASURED ON A LIVE PANE, 2026-08-15: this sentinel alone does NOT hold.</b> The overlay
+     * itself works — {@code GITEA_TOKEN} is injected here, is exported by no shell file, and does
+     * reach the pane. The sentinel loses one step later. A herdr pane runs a <em>login</em> shell,
+     * {@code ~/.zprofile} sources {@code ${SHARED_ENV}/tools/secrets.sh}, and that file does a plain
+     * unconditional {@code export GITEA_ACCESS_TOKEN=...}. A login shell overwrites a value already
+     * in the environment, so the real admin token is put back over this sentinel before the member
+     * process ever starts. That defeat applies to <em>every</em> name {@code secrets.sh} exports,
+     * and no launcher-side overlay can win against it.
+     *
+     * <p>So this constant is not the control on its own — {@link #MEMBER_MARKER} is the other half.
+     * Keeping the sentinel is still worth it: it is correct for any peer kind whose pane does not
+     * start a login shell, and it makes the intent explicit at the one place every adapter passes.
+     */
+    private static final String BLOCKED_GITEA_ACCESS_TOKEN =
+            "blocked-by-bridged-cb592-see-gitea-issue-77";
+
+    /**
+     * CB-592: marks a pane as a bridged member so a shell startup file can decline to export
+     * operator-only credentials into it (gitea issue #77).
+     *
+     * <p>This name is deliberately one that {@code secrets.sh} never exports, which is exactly why
+     * it survives the login shell that wipes {@link #BLOCKED_GITEA_ACCESS_TOKEN}. The mechanism is
+     * measured, not assumed: {@code GITEA_TOKEN} is injected the same way, is absent from a login
+     * shell of its own, and was observed set inside a live member pane.
+     *
+     * <p>It is a no-op until the operator guards the export, which is a one-line change in a file
+     * this repo does not own and must not edit unasked:
+     *
+     * <pre>{@code
+     * [ -n "${BRIDGED_MEMBER:-}" ] || export GITEA_ACCESS_TOKEN=...
+     * }</pre>
+     *
+     * <p>Setting the marker now costs nothing and means that edit is the whole remaining fix.
+     */
+    static final String MEMBER_MARKER = "BRIDGED_MEMBER";
+
     /**
      * Seed a worker's environment (CB-511): the daemon's own {@code PATH}, then the profile's
-     * {@code env:} entries.
+     * {@code env:} entries, then the CB-592 admin-token shadow.
      *
      * <p>Why this exists: bridged passes herdr an explicit env map, and herdr merges it into
      * <em>its own</em> process environment. So before this, a worker inherited whatever PATH the
@@ -783,6 +834,12 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
      * overriding {@code ANTHROPIC_BASE_URL} and slipping past {@link
      * dev.ltms.bridged.guard.SubscriptionGuard}, which is checked against the profile's
      * {@code baseUrl} and nothing else.
+     *
+     * <p>The CB-592 shadow and marker are put in <em>last</em>, after the profile's own
+     * {@code env:}, so no profile — present or future — can restore the admin token, or hide that
+     * the pane is a member, by naming either in config. This is the one place both are applied:
+     * every {@code buildLaunch} in every adapter calls this first, so a new profile, and a peer
+     * kind not yet written, gets them for free.
      */
     protected Map<String, String> baseEnv(BridgedConfig.Profile cfg) {
         Map<String, String> workerEnv = new LinkedHashMap<>();
@@ -793,6 +850,8 @@ public abstract class HerdrPeerLauncher implements PeerLauncher {
         if (cfg != null && cfg.env() != null) {
             workerEnv.putAll(cfg.env());
         }
+        workerEnv.put("GITEA_ACCESS_TOKEN", BLOCKED_GITEA_ACCESS_TOKEN);
+        workerEnv.put(MEMBER_MARKER, "1");
         return workerEnv;
     }
 

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/member/ClaudeCodeLauncherTest.java

@@ -676,6 +676,85 @@ class ClaudeCodeLauncherTest {
                 "the guard-checked baseUrl must win over any env: entry, or the boundary is bypassable");
     }
 
+    // --- CB-592: the admin GITEA_ACCESS_TOKEN never reaches a member -----------------------------
+
+    /**
+     * herdr's env map is an overlay onto its own (login-shell) process environment, so a worker
+     * inherits whatever the daemon's shell carries — including the admin GITEA_ACCESS_TOKEN — for
+     * every key baseEnv does not explicitly shadow. This pins that the launcher DOES send an
+     * explicit (non-blank) GITEA_ACCESS_TOKEN to herdr on every spawn, whatever the profile is, so
+     * a future baseEnv refactor cannot silently drop it and reopen the leak. Asserted against what
+     * tab.create's params actually carry, not an internal map built in the test (gitea #77).
+     *
+     * <p>Scope, measured on a live pane 2026-08-15: this pins what the launcher SENDS, and that is
+     * all it can pin. It does not prove the value survives, and it does not: the pane runs a login
+     * shell, ~/.zprofile sources secrets.sh, and its unconditional `export GITEA_ACCESS_TOKEN=...`
+     * puts the real token back over this sentinel. Closing that needs the operator to guard the
+     * export on BRIDGED_MEMBER — see everySpawnMarksThePaneAsAMember below.
+     */
+    @Test
+    void everySpawnShadowsTheAdminGiteaAccessToken() {
+        FakeHerdr herdr = new FakeHerdr();
+        service(herdr, List.of("claude"), null).spawn();
+
+        String shadowed = startEnv(herdr).get("GITEA_ACCESS_TOKEN");
+        assertNotNull(shadowed, "GITEA_ACCESS_TOKEN must be explicitly overlaid, not left unmentioned");
+        assertFalse(shadowed.isBlank(), "a blank overlay value's override behaviour is unverified — must be non-blank");
+    }
+
+    /**
+     * No profile — present or future — may restore the admin token by naming it in {@code env:}.
+     * The shadow is applied after the profile's own env in {@link HerdrPeerLauncher#baseEnv}
+     * precisely so this can never happen; this test pins that ordering.
+     */
+    @Test
+    void aProfileEnvEntryCannotRestoreTheAdminGiteaAccessToken() {
+        FakeHerdr herdr = new FakeHerdr();
+        BridgedConfig.Profile cfg = new BridgedConfig.Profile(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
+                List.of("claude"), "tab", "bridged-workers", "w #{n}", null, null, null, null, null,
+                null, Map.of("GITEA_ACCESS_TOKEN", "admin-secret-from-profile-config"), null, null);
+        new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
+                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(),
+                _ -> null).spawn();
+
+        assertNotEquals("admin-secret-from-profile-config", startEnv(herdr).get("GITEA_ACCESS_TOKEN"),
+                "a profile's own env: must not be able to smuggle the admin token back in");
+    }
+
+    /**
+     * The half of CB-592 that can actually survive the pane's login shell. BRIDGED_MEMBER is a name
+     * secrets.sh never exports, so nothing overwrites it — measured: GITEA_TOKEN is injected the
+     * same way, is absent from a login shell of its own, and was observed set inside a live member
+     * pane. It lets the operator guard the admin export with
+     * `[ -n "${BRIDGED_MEMBER:-}" ] || export GITEA_ACCESS_TOKEN=...`, which is the whole fix.
+     * Pinned here so a refactor cannot drop the marker and quietly un-guard every member (#77).
+     */
+    @Test
+    void everySpawnMarksThePaneAsAMember() {
+        FakeHerdr herdr = new FakeHerdr();
+        service(herdr, List.of("claude"), null).spawn();
+
+        assertEquals("1", startEnv(herdr).get("BRIDGED_MEMBER"),
+                "every member pane must be marked, or a shell file cannot tell it apart from the operator's");
+    }
+
+    /** A profile must not be able to hide that its pane is a member, for the same reason as above. */
+    @Test
+    void aProfileEnvEntryCannotClearTheMemberMarker() {
+        FakeHerdr herdr = new FakeHerdr();
+        BridgedConfig.Profile cfg = new BridgedConfig.Profile(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
+                List.of("claude"), "tab", "bridged-workers", "w #{n}", null, null, null, null, null,
+                null, Map.of("BRIDGED_MEMBER", ""), null, null);
+        new ClaudeCodeLauncher(new AgentControl(herdr), new WorkspaceControl(herdr),
+                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(),
+                _ -> null).spawn();
+
+        assertEquals("1", startEnv(herdr).get("BRIDGED_MEMBER"),
+                "a profile's own env: must not be able to unmark its pane");
+    }
+
     // ── CB-533: the model is pinned on the command line, not only in the environment ────────────
 
     /** A launcher for a profile identical but for its {@code model:} — the only variable here. */

bridged/src/test/java/dev/ltms/bridged/member/OpenCodeLauncherTest.java

@@ -208,6 +208,21 @@ class OpenCodeLauncherTest {
                 "a git-token profile gets the peer-neutral GITEA_TOKEN grant, same as Claude");
     }
 
+    /**
+     * CB-592: the shadow lives in {@link HerdrPeerLauncher#baseEnv}, shared by every adapter — this
+     * pins that the opencode path gets it too, not just Claude's. See the matching test in
+     * {@code ClaudeCodeLauncherTest} for the full rationale (gitea #77).
+     */
+    @Test
+    void everySpawnShadowsTheAdminGiteaAccessToken(@TempDir Path root) {
+        FakeHerdr herdr = new FakeHerdr();
+        service(herdr, root, opencodeCfg(null, null, null)).spawn();
+
+        String shadowed = startEnv(herdr).get("GITEA_ACCESS_TOKEN");
+        assertNotNull(shadowed, "GITEA_ACCESS_TOKEN must be explicitly overlaid, not left unmentioned");
+        assertFalse(shadowed.isBlank(), "a blank overlay value's override behaviour is unverified — must be non-blank");
+    }
+
     @Test
     void capabilitiesDeclareOrphanReapAndMcpAskAndConditionalSelfPr(@TempDir Path root) {
         FakeHerdr herdr = new FakeHerdr();

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>

docs/CB-591-Gateway-Migration.md

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

opencode.json

@@ -26,7 +26,7 @@
       ],
       "enabled": true,
       "environment": {
-        "GITEA_ACCESS_TOKEN": "{env:GITEA_ACCESS_TOKEN}",
+        "GITEA_ACCESS_TOKEN": "{env:WORKER_GITEA_TOKEN}",
         "GITEA_HOST": "{env:GITEA_HOST}"
       }
     }

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,11 +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 WORKER_GITEA_TOKEN is empty and workers cannot
-#      open a PR. Nothing in the daemon logs this, so the script checks it and says so out loud.
+#   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 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
@@ -17,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
@@ -41,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
@@ -59,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
 
@@ -72,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
@@ -82,6 +117,18 @@ else
   warn "Fix \${SHARED_ENV}/tools/secrets.sh before relying on worker checkpoints."
 fi
 
+# Same trap, second variable (CB-591). A profile's `tokenEnv:` is resolved from the DAEMON's own
+# process environment by HerdrPeerLauncher.resolveEnv, so a token added to secrets.sh after the
+# daemon started is simply absent. The launcher then injects an empty token and llm.ltms.dev answers
+# 401 — long after the restart, and with nothing tying the two together.
+if zsh -lc '[ -n "${AI_GATEWAY_TOKEN:-}" ]' 2>/dev/null; then
+  ok "AI_GATEWAY_TOKEN resolves in a login shell"
+else
+  warn "AI_GATEWAY_TOKEN is EMPTY in a login shell."
+  warn "Any profile whose tokenEnv is AI_GATEWAY_TOKEN will get an empty token and 401 at the gateway."
+  warn "This only matters once a profile points at llm.ltms.dev — harmless before that."
+fi
+
 if [ "$CHECK_ONLY" = 1 ]; then
   say "--check: nothing changed"
   exit 0
@@ -123,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
@@ -138,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)"