CB-306: spawn-readiness gate — ClaudeCodeLauncher blocks until the worker is injectable or throws PeerUnreachableException

The launcher now polls AgentControl.status(paneId) after starting the pane.
It returns the handle only once the worker reports an injectable state
(IDLE/BLOCKED/DONE). If the timeout elapses while still UNKNOWN, the
pane is self-reaped and a PeerUnreachableException is thrown — no orphan
left behind. The gate is disabled when spawnReadyTimeoutMs == 0 (legacy
non-blocking spawn, the default for the 6-arg constructor).

Key changes:
- PeerUnreachableException (new) in dev.ltms.bridged.peer
- BridgedConfig: spawnReadyTimeoutMs (default 20000), spawnReadyPollMs (default 300)
- ClaudeCodeLauncher: 3 constructor overloads:
  (a) 6-arg backward-compat: gate disabled (timeout=0)
  (b) 8-arg production: gate with config knobs + real clock/sleep
  (c) 10-arg testability: full seam (LongSupplier clock + Runnable sleeper)
- waitUntilInjectableOrThrow() loop in spawn(SpawnRequest)
- sleepUninterruptibly() helper for the production sleeper
- BridgeMcp.spawn + BridgedApp.spawnWorker catch PeerUnreachableException
  → clean tool error / 502 response (not an uncaught 500)
- SessionManager.acquire inherently registers nothing on throw (both
  worktree and non-worktree paths) — confirmed by new test

Tests:
- ClaudeCodeLauncherTest: 4 new tests
  - unknown→idle: returns handle, no pane.close
  - always-unknown: throws PeerUnreachableException, pane closed,
    clock advanced past timeout
  - timeout=0 (6-arg ctor): no agent.get calls, returns handle
  - timeout=0 (10-arg ctor): no orphan pane close
- SessionManagerTest: 1 new test
  - acquire → PeerUnreachableException: roster remains empty
Total: 188 tests, all pass (no existing test changed semantics)

bridged/src/test/java/dev/ltms/bridged/session/SessionManagerTest.java

@@ -6,6 +6,7 @@ import dev.ltms.bridged.herdr.AgentControl;
 import dev.ltms.bridged.herdr.FakeHerdr;
 import dev.ltms.bridged.herdr.WorkspaceControl;
 import dev.ltms.bridged.worker.ClaudeCodeLauncher;
+import dev.ltms.bridged.peer.PeerUnreachableException;
 import org.junit.jupiter.api.Test;
 
 import java.util.List;
@@ -332,4 +333,33 @@ class SessionManagerTest {
                 .filter(c -> paneId.equals(((Map<?, ?>) c.params()).get("pane_id")))
                 .count();
     }
+
+    // --- CB-306 spawn-readiness gate: no half-registered session on timeout ----------------
+
+    @Test
+    void acquireThrowsPeerUnreachableWhenGateTimesOutAndRegistersNoSession() {
+        FakeHerdr herdr = new FakeHerdr();
+        herdr.agentStatus("unknown"); // never becomes injectable
+        long[] clock = {0};
+
+        // Gate-enabled launcher (1 ms timeout + no-op sleeper that advances clock past deadline)
+        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
+                "ltms-local", "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
+                List.of("ccs", "ltms-local"), "tab", "bridged-workers",
+                "worker: {profile} #{n}", null, null, null);
+        ClaudeCodeLauncher workers = new ClaudeCodeLauncher(
+                new AgentControl(herdr), new WorkspaceControl(herdr),
+                new SubscriptionGuard(Set.of("gx00.gw")), Map.of(cfg.profile(), cfg), cfg.profile(), _ -> null,
+                1, 1, () -> clock[0], () -> clock[0] += 10);
+        SessionManager sessions = new SessionManager(workers, new GitWorktrees(), () -> 0L, 0);
+
+        assertThrows(PeerUnreachableException.class,
+                () -> sessions.acquire("ltms-local", null, "/caller", "term_primary"),
+                "acquire must throw PeerUnreachableException when spawn times out");
+
+        // No half-registered session — the error happened inside spawn, before
+        // SessionManager could put() anything into the registry.
+        assertTrue(sessions.roster().isEmpty(),
+                "no session is registered when spawn times out (roster empty)");
+    }
 }

bridged/src/test/java/dev/ltms/bridged/worker/ClaudeCodeLauncherTest.java

@@ -7,6 +7,7 @@ import dev.ltms.bridged.herdr.FakeHerdr;
 import dev.ltms.bridged.herdr.WorkspaceControl;
 import dev.ltms.bridged.peer.Capability;
 import dev.ltms.bridged.peer.PeerHandle;
+import dev.ltms.bridged.peer.PeerUnreachableException;
 import dev.ltms.bridged.peer.SpawnRequest;
 import org.junit.jupiter.api.Test;
 
@@ -318,4 +319,102 @@ class ClaudeCodeLauncherTest {
 
         assertTrue(herdr.called("pane.close"), "stop via handle.id() must close the pane");
     }
+
+    // --- CB-306 spawn-readiness gate -----------------------------------------------------------
+
+    private static Map<String, BridgedConfig.Worker> workerConfigMap(String profile, String mcpUrl) {
+        BridgedConfig.Worker cfg = new BridgedConfig.Worker(
+                profile, "http://gx00.gw:8000", "coder", null, "BRIDGED_WORKER_TOKEN",
+                List.of("ccs", profile), "tab", "bridged-workers",
+                "worker: {profile} #{n}", mcpUrl, null, null);
+        return Map.of(cfg.profile(), cfg);
+    }
+
+    @Test
+    void spawnWaitsUntilInjectableThenReturnsHandle() {
+        FakeHerdr herdr = new FakeHerdr();
+        herdr.agentStatus("unknown"); // first status call sees UNKNOWN
+        long[] clock = {0};
+        boolean[] firstSleep = {true};
+        // The sleeper: advance the fake clock, and on the first call flip the
+        // agent status to IDLE so the next poll succeeds.
+        Runnable sleeper = () -> {
+            clock[0] += 300;
+            if (firstSleep[0]) {
+                herdr.agentStatus("idle");
+                firstSleep[0] = false;
+            }
+        };
+
+        ClaudeCodeLauncher svc = new ClaudeCodeLauncher(
+                new AgentControl(herdr), new WorkspaceControl(herdr),
+                new SubscriptionGuard(Set.of("gx00.gw")),
+                workerConfigMap("ltms-local", null), "ltms-local", _ -> null,
+                5000, 300, () -> clock[0], sleeper);
+
+        PeerHandle handle = svc.spawn(new SpawnRequest(null, null, null));
+
+        assertNotNull(handle, "spawn returns a handle when worker becomes injectable");
+        assertEquals("w9:pW_1", handle.id(), "handle id matches the started pane");
+        assertEquals(0, paneCloseCount(herdr, "w9:pW_1"),
+                "no pane.close when worker becomes injectable before timeout");
+    }
+
+    @Test
+    void spawnThrowsPeerUnreachableWhenNeverInjectableAndReapsPane() {
+        FakeHerdr herdr = new FakeHerdr();
+        herdr.agentStatus("unknown"); // always UNKNOWN
+        long[] clock = {0};
+
+        ClaudeCodeLauncher svc = new ClaudeCodeLauncher(
+                new AgentControl(herdr), new WorkspaceControl(herdr),
+                new SubscriptionGuard(Set.of("gx00.gw")),
+                workerConfigMap("ltms-local", null), "ltms-local", _ -> null,
+                1000, 50, () -> clock[0], () -> clock[0] += 50);
+
+        PeerUnreachableException ex = assertThrows(
+                PeerUnreachableException.class,
+                () -> svc.spawn(new SpawnRequest(null, null, null)));
+
+        assertTrue(ex.getMessage().contains("w9:pW_1"),
+                "exception message references the paneId: " + ex.getMessage());
+        assertTrue(ex.getMessage().contains("1000"),
+                "exception message references the timeout: " + ex.getMessage());
+        assertTrue(clock[0] >= 1000, "fake clock advanced past the timeout: " + clock[0]);
+        assertEquals(1, paneCloseCount(herdr, "w9:pW_1"),
+                "pane was closed on timeout (no orphan left behind)");
+    }
+
+    @Test
+    void spawnReturnsImmediatelyWhenGateIsDisabled() {
+        FakeHerdr herdr = new FakeHerdr();
+        // The default 6-arg constructor has spawnReadyTimeoutMs=0 (gate disabled).
+        ClaudeCodeLauncher svc = service(herdr, List.of("ccs", "ltms-local"), null);
+
+        PeerHandle handle = svc.spawn(new SpawnRequest(null, null, null));
+
+        assertNotNull(handle, "spawn returns a handle when the gate is disabled");
+        assertFalse(herdr.called("agent.get"),
+                "agent.get is never called when the gate is disabled (no polling)");
+    }
+
+    @Test
+    void spawnGateRespectsZeroTimeoutEvenWithFullConstructor() {
+        FakeHerdr herdr = new FakeHerdr();
+        long[] clock = {0};
+
+        // Explicit zero timeout with the full testability constructor — should
+        // skip polling entirely, just like the legacy default path.
+        ClaudeCodeLauncher svc = new ClaudeCodeLauncher(
+                new AgentControl(herdr), new WorkspaceControl(herdr),
+                new SubscriptionGuard(Set.of("gx00.gw")),
+                workerConfigMap("ltms-local", null), "ltms-local", _ -> null,
+                0, 300, () -> clock[0], () -> clock[0] += 1);
+
+        PeerHandle handle = svc.spawn(new SpawnRequest(null, null, null));
+
+        assertNotNull(handle, "spawn still succeeds with zero timeout");
+        assertEquals(0, paneCloseCount(herdr, handle.id()),
+                "no orphan pane close from the gate path");
+    }
 }