CB-600: make it safe to install the launchd agent

- redeploy-bridged.sh now refuses (not warns) a supervised restart when
  its computed log path disagrees with the loaded plist's StandardOutPath
  — otherwise every post-restart check reads the wrong file and can
  report a clean restart while the daemon crash-loops. The check is a
  pure, testable function; the script gained a source-for-test guard so
  it can be exercised without installing the agent or touching launchd.
- a failed 'launchctl load' after a successful 'unload' now retries once
  and, on ultimate failure, tells the operator the agent is stopped AND
  disabled plus the exact recovery command, instead of leaving that
  silently worse than the pre-redeploy state.
- the plist documents honestly that the crash loop launchd retries is
  unbounded (ThrottleInterval only paces it), and what actually stops it.
- fixed the requiredSecretEnvVars javadoc: the auth.tokenEnv startup
  throw is ~370 lines below its call site, not a few lines above it, and
  only fires in auth.mode: token.

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

@@ -555,7 +555,10 @@ public final class Bridged {
      * 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.
+     * startup throw in {@code main()} — about 370 lines <em>below</em> this method's call site
+     * ({@link #reportRequiredSecrets(BridgedConfig)}), not a few lines above it. That throw only
+     * fires when {@code auth.mode: token} is configured; under the default loopback-trust mode it
+     * never runs, and {@code auth.tokenEnv} is simply not required.
      *
      * <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.

bridged/src/main/java/dev/ltms/bridged/config/BridgedConfig.java

@@ -967,12 +967,8 @@ 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.
      */
-    static final Set<String> KNOWN_TOP_LEVEL_KEYS = Set.of(
+    private 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/test/java/dev/ltms/bridged/config/BridgedConfigTest.java

@@ -10,7 +10,6 @@ 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.*;
 
@@ -1190,79 +1189,6 @@ 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");

deploy/dev.ltms.bridged.plist

@@ -82,8 +82,25 @@
     <key>RunAtLoad</key>
     <true/>
 
-    <!-- Restart on crash, but not in a tight loop if the config is bad (bridged fails fast on a
-         non-loopback bind without token auth — that is a config error, not a transient one). -->
+    <!--
+      CB-600 — read this before assuming ThrottleInterval bounds anything. It paces restarts to at
+      most one per 10s; it does NOT cap how many times launchd retries. If bridged fails fast on
+      every start — a bad bridged.yaml, for example auth.mode: token with the token env var unset,
+      which throws in main() before the daemon ever binds a port — launchd restarts it forever,
+      once every 10s, until a human intervenes. LaunchAgents have no "give up after N attempts"
+      primitive, so this is not something a config change here can fix.
+
+      That loop stops only two ways: (1) `launchctl unload -w ~/Library/LaunchAgents/dev.ltms.bridged.plist`,
+      or (2) the underlying cause gets fixed, so the process starts successfully and stays up (no
+      more exits to restart). scripts/redeploy-bridged.sh does not add a third way — it does not
+      make bridged self-disable on a config error, on purpose: a fail-fast exit path that
+      sometimes decides "this is unrecoverable, stop trying" is one more thing that can misfire,
+      and a wrongly self-disabled daemon needs the exact same manual `launchctl load -w` recovery
+      this comment already names — so it buys nothing an operator watching for the crash loop
+      doesn't already have, at the cost of a new way to be silently down. Watch for it with
+      `launchctl list dev.ltms.bridged` (a high restart count) or by tailing bridged.out for the
+      same startup error repeating every ~10s.
+    -->
     <key>KeepAlive</key>
     <dict>
         <key>SuccessfulExit</key>

scripts/redeploy-bridged.sh

@@ -79,6 +79,53 @@ running_pid() { pgrep -f "$PATTERN" || true; }
 launchd_installed() { [ -f "$LAUNCHD_PLIST" ]; }
 launchd_loaded() { launchctl list "$LAUNCHD_LABEL" >/dev/null 2>&1; }
 
+# CB-600: the script computes its own log path from where it sits on disk (REPO, above); the
+# plist hard-codes an absolute StandardOutPath. Nothing forced the two to agree — if this script
+# were ever run from a checkout other than the one the loaded plist names, launchd would start and
+# log the daemon correctly, while every check below (the fresh "bridged listening" line, the
+# ERROR-count scan) would read a different, empty or stale file and the script would report a
+# clean restart while the daemon crash-loops. Pure and side-effect-free besides `die`/`ok` — reads
+# the two paths, resolves them, compares — so it never touches launchd or the daemon and can be
+# exercised by sourcing this script (see the SOURCED guard below) without installing the agent.
+check_log_path_matches_plist() {
+  local script_out="$1" plist_path="$2"
+  local plist_out resolved_out resolved_plist_out
+  # Checked by exit status, not by emptiness: on a missing file/key PlistBuddy exits nonzero but
+  # still writes a message ("File Doesn't Exist, Will Create: ...") that command substitution
+  # would happily capture as if it were the real value — testing only `-z` missed that case.
+  if ! plist_out="$(/usr/libexec/PlistBuddy -c 'Print :StandardOutPath' "$plist_path" 2>/dev/null)" \
+      || [ -z "$plist_out" ]; then
+    die "launchd agent is loaded but PlistBuddy could not read StandardOutPath from
+        $plist_path
+      — cannot verify the daemon logs where this script is about to look. Fix the plist before
+      redeploying supervised."
+  fi
+  resolved_out="$(cd "$(dirname "$script_out")" 2>/dev/null && pwd -P)/$(basename "$script_out")" || true
+  resolved_plist_out="$(cd "$(dirname "$plist_out")" 2>/dev/null && pwd -P)/$(basename "$plist_out")" || true
+  if [ -z "$resolved_out" ] || [ -z "$resolved_plist_out" ] || [ "$resolved_out" != "$resolved_plist_out" ]; then
+    die "log path mismatch — this script reads
+        $script_out  (resolved: ${resolved_out:-<directory does not exist>})
+      but the loaded plist's StandardOutPath is
+        $plist_out  (resolved: ${resolved_plist_out:-<directory does not exist>})
+      Under supervision the daemon writes to the PLIST's path, not necessarily this script's — every
+      post-restart check below (the fresh 'bridged listening' line, the ERROR-count scan) would read
+      the wrong file and could report a clean restart while the daemon crash-loops. Fix the mismatch
+      (move this checkout to match the plist, or edit the plist's StandardOutPath/StandardErrorPath)
+      before redeploying supervised."
+  fi
+  ok "log path check: script and plist agree ($resolved_out)"
+}
+
+# CB-600: sourceable for testing. When this file is SOURCED (not executed) it stops here — nothing
+# below runs — so a test harness can `source` it to call check_log_path_matches_plist (or the
+# other pure helpers above) against a throwaway plist fixture without ever reaching the mutating
+# flow (build/stop/start) or touching the real daemon or launchd. On a normal `./redeploy-bridged.sh`
+# invocation `(return 0 2>/dev/null)` fails (return is illegal at top level of an executed script),
+# so this whole block is a no-op and every line below still runs exactly as before.
+if (return 0 2>/dev/null); then
+  return 0
+fi
+
 # ---------------------------------------------------------------- report state
 
 say "current state"
@@ -103,6 +150,9 @@ SUPERVISED=0
 if launchd_loaded; then
   SUPERVISED=1
   ok "launchd agent loaded ($LAUNCHD_LABEL) — launchd supervises this daemon"
+  # CB-600: fail loudly here, before ANY other check runs, if this script and the loaded plist
+  # would read different log files — every check after this point is worthless otherwise.
+  check_log_path_matches_plist "$OUT" "$LAUNCHD_PLIST"
 else
   warn "launchd agent not loaded — this script is the only thing that will restart the daemon."
 fi
@@ -222,7 +272,22 @@ say "start"
 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"
+  # CB-600: 'launchctl unload -w' above already persisted Disabled=true for this label. A load -w
+  # that succeeds clears it; a load -w that FAILS leaves the agent both stopped and disabled — worse
+  # than before this script ran, because a later reboot or login will not bring it back either. One
+  # retry covers a transient race (e.g. launchd not yet fully done deregistering); if it still fails,
+  # die with the exact recovery command rather than a bare "failed".
+  if ! launchctl load -w "$LAUNCHD_PLIST" 2>/dev/null; then
+    warn "launchctl load failed on the first attempt — retrying once after a short pause"
+    sleep 2
+    launchctl load -w "$LAUNCHD_PLIST" || die "launchctl load failed twice.
+        The agent is now STOPPED and DISABLED — it will NOT come back on its own, not even after a
+        reboot or login, because 'launchctl unload -w' above persisted Disabled=true and load -w
+        never got the chance to clear it. Recover with:
+            launchctl load -w \"$LAUNCHD_PLIST\"
+        If that still fails, check 'launchctl list $LAUNCHD_LABEL', validate the plist with
+        'plutil -lint \"$LAUNCHD_PLIST\"', and check $OUT before assuming a retry will succeed."
+  fi
 else
   # Absolute jar path so `ps` names which checkout is running.
   ( cd "$BRIDGED" && zsh -lc "nohup java -jar '$JAR' >> bridged.out 2>&1 &" )