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

@@ -555,10 +555,7 @@ 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 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.
+     * 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.

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

deploy/dev.ltms.bridged.plist

@@ -82,25 +82,8 @@
     <key>RunAtLoad</key>
     <true/>
 
-    <!--
-      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.
-    -->
+    <!-- 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). -->
     <key>KeepAlive</key>
     <dict>
         <key>SuccessfulExit</key>

scripts/redeploy-bridged.sh

@@ -79,53 +79,6 @@ 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"
@@ -150,9 +103,6 @@ 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
@@ -272,22 +222,7 @@ 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."
-  # 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
+  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 &" )