spexcode 0.6.5 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/harness.js

@@ -1,4 +1,4 @@
-import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { closeSync, openSync, readSync, writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
@@ -9,11 +9,11 @@ import { fileURLToPath } from 'node:url';
 import { claudeSlashCommands, codexSlashCommands, opencodeSlashCommands, piSlashCommands } from './slash-commands.js';
 import { OPENCODE_EVENTS, opencodePluginSource } from './opencode.js';
 import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js';
-import { claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
+import { claudeHeadlessColdRuntime, claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
 import { codexHeadlessLaunchCommand } from './codex-headless.js';
-import { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
+import { opencodeHeadlessColdRuntime, opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
 import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
-import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath } from '@spexcode/spec-core';
+import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath, spexcodeHome } from '@spexcode/spec-core';
 import { git } from '@spexcode/spec-core';
 import { shQuote } from './sh.js';
 import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime } from '@spexcode/spec-core';
@@ -67,9 +67,9 @@ export async function adapterLoadedReferenceState(records, runtimeDir = runtimeR
 // sessions.ts starts `claude` with CLAUDE_BG_BACKEND=daemon + CLAUDE_BG_RENDEZVOUS_SOCK=<this path> set ONLY on
 // that one spawned command (env prefix, never global). claude opens a unix socket here; writing one line
 // `{"type":"reply","text":"…"}\n` injects + submits the text as a prompt — no PTY typing, so multi-line input
-// and Enters can't be corrupted the way `tmux send-keys` was. It lives in tmpdir tied to the claude process, so
-// no extra lifecycle. liveness CONNECTS to it (a live LISTENER, not merely the file — see rendezvousListening);
-// deliver writes to it.
+// and Enters can't be corrupted the way `tmux send-keys` was. It lives in SpexCode's own durable store, and
+// its launch-time stamp still gives it no independent lifecycle. liveness CONNECTS to it (a live LISTENER, not
+// merely the file — see rendezvousListening); deliver writes to it.
 //
 // The path is a LAUNCH-TIME FACT, recorded — not a formula every consumer re-derives. The id alone was not
 // enough to name it: `SPEXCODE_HOME` scopes the store and `SPEXCODE_TMUX` scopes the tmux server, so two
@@ -83,18 +83,22 @@ export async function adapterLoadedReferenceState(records, runtimeDir = runtimeR
 // `legacyRvSock` is the answer for a session launched BEFORE the stamp existed — its agent really did bind
 // the unscoped path — so those keep working untouched, and the fallback retires as they turn over.
 export const legacyRvSock = (id) => join(tmpdir(), `spexcode-rv-${id}.sock`);
-// @@@ rendezvousSocketBase - macOS's TMPDIR commonly expands to /var/folders/<long-user-path>, leaving a
-// UUID-scoped socket beyond its 104-byte sun_path limit. It can be created and observed by pathname but every
-// connect fails EINVAL, which looks exactly like an unresponsive worker. Use a literal short /tmp spelling
-// (not tmpdir(), whose resolved form is long on macOS) with the same private per-uid directory pattern as the
-// Codex runtime socket. Existing launches retain their stamped old path through rvSock(); only new launches use
-// this base.
-const rendezvousSocketBase = () => {
-    const base = join('/tmp', `spexcode-rv-${process.getuid?.() ?? 0}`);
-    mkdirSync(base, { recursive: true, mode: 0o700 });
-    return base;
-};
-export const scopedRvSock = (id, dir = runtimeRoot()) => join(rendezvousSocketBase(), `spexcode-rv-${createHash('sha1').update(dir).digest('hex').slice(0, 12)}-${id}.sock`);
+// @@@ scoped rendezvous path - a rendezvous endpoint IS this session's address, so it needs a durable home and
+// a bounded name. `<SPEXCODE_HOME>/s/<16hex>/c` is both: the store is SpexCode-owned (normally ~/.spexcode),
+// while one fixed digest of runtime scope + session identity gives every world/session its own short directory
+// without carrying either raw value in the pathname. This is deliberately NOT the Codex app-server rule: that
+// endpoint routes project-shared threads; this one names a session-owned listener. Existing launches retain
+// their stamped old path through rvSock(); only a new stamp uses this derivation.
+const RENDEZVOUS_SUN_PATH_LIMIT = 104;
+export const scopedRvSock = (id, dir = runtimeRoot()) => join(spexcodeHome(), 's', createHash('sha1').update(`${dir}\0${id}`).digest('hex').slice(0, 16), 'c');
+export function assertRvSockPath(id, dir = runtimeRoot()) {
+    const path = scopedRvSock(id, dir);
+    const bytes = Buffer.byteLength(path);
+    if (bytes >= RENDEZVOUS_SUN_PATH_LIMIT) {
+        throw new Error(`rendezvous socket path is ${bytes} bytes (must be < ${RENDEZVOUS_SUN_PATH_LIMIT}): ${path}; shorten SPEXCODE_HOME before creating this session`);
+    }
+    return path;
+}
 const rvStamp = (id) => sessionArtifactPath(id, 'rv.path');
 export const rvSock = (id) => {
     try {
@@ -107,7 +111,8 @@ export const rvSock = (id) => {
 // launch's half: derive this session's socket in ITS runtime and record it, so every later reader (launch env,
 // liveness probe, delivery, teardown) reads the one path the agent actually bound.
 export function stampRvSock(id, dir = runtimeRoot()) {
-    const path = scopedRvSock(id, dir);
+    const path = assertRvSockPath(id, dir);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     mkdirSync(dirname(rvStamp(id)), { recursive: true });
     writeFileSync(rvStamp(id), path);
     return path;
@@ -140,6 +145,15 @@ export function listenerAt(path, timeoutMs = 800) {
     });
 }
 export const rendezvousListening = (id, timeoutMs = 800) => listenerAt(rvSock(id), timeoutMs);
+const rendezvousDeliveryTransportAt = async (path) => {
+    const probe = await listenerAt(path);
+    if (probe === 'live')
+        return { kind: 'reachable' };
+    if (probe === 'unproven')
+        return { kind: 'unproven' };
+    return { kind: 'unreachable', reason: 'its launch-time rendezvous listener is absent or refusing connections' };
+};
+const rendezvousDeliveryTransport = (rec) => rendezvousDeliveryTransportAt(rvSock(rec.session));
 // The app-server Unix socket MUST live on a SHORT, sun_path-safe path — NOT nested under the project runtime
 // dir. macOS caps `sun_path` at ~104 bytes, and `runtimeRoot()` flattens the ENTIRE project path into one
 // dash-segment (`encodeProject`), so `<runtimeRoot>/codex-app-server.sock` blew past the cap on a deep macOS
@@ -277,6 +291,17 @@ function claudeForkTransport(sourceSessionId, runtimeDir) {
     }
     return null;
 }
+async function claudeDeliveryTransport(rec) {
+    const fork = claudeForkTransport(rec.session, rec.runtimeDir);
+    if (!fork)
+        return rendezvousDeliveryTransport(rec);
+    const forkState = await rendezvousDeliveryTransportAt(fork.sock);
+    if (forkState.kind !== 'unreachable' || fork.sock === rvSock(rec.session))
+        return forkState;
+    // A stale roster row must not strand a source worker whose stamped launch transport is still reachable.
+    return rendezvousDeliveryTransport(rec);
+}
+const unprovenDeliveryTransport = async () => ({ kind: 'unproven' });
 function replyViaSocket(sock, text, mid, auth) {
     return new Promise((resolve) => {
         let settled = false;
@@ -505,8 +530,8 @@ export function codexLaunchCommand(id, codexCmd = 'codex', serverCmd, dir = runt
         // TWO launch modes, on ONE tail channel ("$@"). reopen() hands a `--resume <thread-id>` tail (see
         // codexHarness.resumeArg) to bring the SAME conversation back: resume that OWNED thread DIRECTLY — no new
         // thread, no first-turn prompt. ANY other tail is a NEW launch: BACKEND owns the thread — `codex-launch`
-        // does thread/start { cwd = this worktree } on the shared per-project app-server, stores the new id on the
-        // governed record (SPEXCODE_SESSION_ID), and fires the tail as the FIRST turn, materializing the rollout.
+        // does thread/start { cwd = this worktree } on the shared per-project app-server, fires the tail as the
+        // FIRST turn, materializes the rollout, and stages the new id + payload proof for the lifecycle owner.
         // Either way it ends with a thread id, which the visible TUI then RESUMES (the rollout persists on disk),
         // rendering it natively. A new launch's tail is always ONE single-quoted prompt arg, so it can never be the
         // literal "--resume" marker — the discriminator is unambiguous. codex-launch only prints an id once its
@@ -1290,8 +1315,15 @@ async function codexColdPreflightOnce(threadId, dir = runtimeRoot(), expectedGen
         const presence = codexPresenceFromStatus(statusById.get(id));
         if (presence === 'active')
             return { ok: false, reason: `Codex subtree member ${id} has an active turn` };
-        if (presence === 'unknown')
-            return { ok: false, reason: `Codex subtree member ${id} turn state is unknown` };
+        if (presence === 'unknown') {
+            const rollout = codexRolloutTurnSettlement(id);
+            if (!rollout.settled) {
+                return {
+                    ok: false,
+                    reason: `Codex subtree member ${id} turn state is unknown: live Codex client did not report a determinate turn state; ${rollout.reason}`,
+                };
+            }
+        }
         if (archivedSet.has(id))
             return { ok: false, reason: `Codex archived subtree member ${id} remains loaded` };
     }
@@ -1329,17 +1361,49 @@ async function codexColdPreflight(threadId, dir = runtimeRoot(), expectedGenerat
     }
     throw new Error('unreachable Codex cold preflight retry state');
 }
+// A corrupt record has no binding we can trust. Locate its one materialized native thread before cold proof;
+// choosing current or legacy would redirect a destructive operation across a generation boundary.
+async function codexEndpointForOrphanThread(threadId, dir = runtimeRoot()) {
+    const tracked = codexGenerationEndpoints(dir);
+    const endpoints = tracked.length ? tracked : [legacyCodexGenerationEndpoint(dir)];
+    const scans = await Promise.all(endpoints.map(async (endpoint) => {
+        const generation = codexMutationGeneration(dir, endpoint);
+        if (!generation)
+            return { endpoint, reason: 'Codex shared app-server generation is unproven' };
+        const [active, archived] = await Promise.all([
+            codexThreadList(endpoint.socketPath, { archived: false, sourceKinds: [] }),
+            codexThreadList(endpoint.socketPath, { archived: true, sourceKinds: [] }),
+        ]);
+        if (codexRuntimeGeneration(dir, endpoint) !== generation)
+            return { endpoint, reason: 'Codex shared app-server generation changed during orphan location' };
+        if (!active.ok)
+            return { endpoint, reason: active.error };
+        if (!archived.ok)
+            return { endpoint, reason: archived.error };
+        return { endpoint, generation, containsTarget: active.ids.includes(threadId) || archived.ids.includes(threadId) };
+    }));
+    const failed = scans.find((scan) => 'reason' in scan);
+    if (failed)
+        return { ok: false, reason: `${failed.reason} while locating orphan Codex thread ${threadId} on generation ${failed.endpoint.id}` };
+    const matches = scans.filter((scan) => 'containsTarget' in scan && scan.containsTarget);
+    if (matches.length !== 1) {
+        const detail = matches.length ? matches.map((scan) => scan.endpoint.id).join(', ') : 'none';
+        return { ok: false, reason: `Codex orphan thread ${threadId} has ${matches.length === 0 ? 'no materialized' : 'ambiguous'} generation location (${detail})` };
+    }
+    return { ok: true, endpoint: matches[0].endpoint, generation: matches[0].generation };
+}
 async function codexQuarantineOrphanThread(threadId, opts) {
     const dir = runtimeRoot();
-    const generation = codexMutationGeneration(dir);
-    if (!generation)
-        return { ok: false, reason: 'Codex shared app-server generation is unproven' };
     const owners = governedSharedRuntimeOwners(dir, 'codex-app-server', threadId, opts.excludingSessionId);
     if (owners === null)
         return { ok: false, reason: 'governed Codex thread-owner census is unreadable' };
     if (owners.length)
         return { ok: false, reason: `Codex native thread ${threadId} has governed owner(s) ${owners.join(', ')}` };
-    const before = await codexColdPreflight(threadId, dir, generation);
+    const location = await codexEndpointForOrphanThread(threadId, dir);
+    if (!location.ok)
+        return location;
+    const { endpoint, generation } = location;
+    const before = await codexColdPreflight(threadId, dir, generation, endpoint);
     if (!before.ok)
         return before;
     const plan = before.receipt;
@@ -1362,7 +1426,6 @@ async function codexQuarantineOrphanThread(threadId, opts) {
     if (plan.activeIds.length !== 1 || plan.activeIds[0] !== threadId || plan.archivedIds.length)
         return { ok: false, reason: `Codex native thread ${threadId} is not one exact active orphan` };
     const siblingIds = plan.guard.referenceIds.filter((id) => id !== threadId);
-    const legacy = legacyCodexGenerationEndpoint(dir);
     // Quarantine archives one exact orphan, so it pays the same flush a subtree member does when that orphan is
     // loaded; the budget is derived the same way rather than being a second, differently-wrong constant.
     let orphanBudgetMs = CODEX_MUTATION_BASE_MS;
@@ -1372,10 +1435,10 @@ async function codexQuarantineOrphanThread(threadId, opts) {
             return { ok: false, reason: `Codex native thread ${threadId} is loaded and its rollout exists but cannot be measured, so the archive flush budget is unknown` };
         orphanBudgetMs = codexArchiveBudgetMs(rollout.bytes);
     }
-    const archived = await codexThreadMutation(legacy.socketPath, 'thread/archive', threadId, { dir, endpoint: legacy, generation }, undefined, orphanBudgetMs);
+    const archived = await codexThreadMutation(endpoint.socketPath, 'thread/archive', threadId, { dir, endpoint, generation }, undefined, orphanBudgetMs);
     if (!archived.ok)
         return { ok: false, reason: `${archived.error} while archiving orphan Codex thread ${threadId}${archived.commit === 'unknown' ? '; commit state is unknown' : ''}` };
-    const after = await codexColdPreflight(threadId, dir, generation);
+    const after = await codexColdPreflight(threadId, dir, generation, endpoint);
     const failed = (reason) => ({ ok: false, reason });
     if (!after.ok) {
         const restored = await rollback();
@@ -1917,6 +1980,45 @@ export function codexRolloutBytes(threadId, root) {
     }
     return { bytes: 0 };
 }
+const CODEX_ROLLOUT_TAIL_BYTES = 64 * 1024;
+const CODEX_ROLLOUT_TERMINAL_EVENTS = new Set(['task_complete', 'task_completed', 'turn_complete', 'turn_completed']);
+function codexRolloutTurnSettlement(threadId, root) {
+    const path = codexRolloutPath(threadId, root);
+    if (!path)
+        return { settled: false, reason: 'rollout is missing' };
+    let fd = null;
+    try {
+        const size = statSync(path).size;
+        if (size === 0)
+            return { settled: false, reason: 'rollout has no terminal record' };
+        const length = Math.min(size, CODEX_ROLLOUT_TAIL_BYTES);
+        const tail = Buffer.allocUnsafe(length);
+        fd = openSync(path, 'r');
+        if (readSync(fd, tail, 0, length, size - length) !== length)
+            return { settled: false, reason: 'rollout tail is unreadable' };
+        const line = tail.toString('utf8').split('\n').reverse().find((value) => value.trim());
+        if (!line)
+            return { settled: false, reason: 'rollout has no terminal record' };
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return { settled: false, reason: 'rollout tail is incomplete or malformed' };
+        }
+        const payload = event && typeof event === 'object' ? event.payload : null;
+        const terminal = event && typeof event === 'object' && event.type === 'event_msg' &&
+            payload && typeof payload === 'object' && CODEX_ROLLOUT_TERMINAL_EVENTS.has(String(payload.type || ''));
+        return terminal ? { settled: true } : { settled: false, reason: 'rollout has no terminal record' };
+    }
+    catch {
+        return { settled: false, reason: 'rollout tail is unreadable' };
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
 // poll until the thread's rollout lands (resume-ready) or the budget runs out. Returns false on timeout so the
 // caller can FAIL LOUD instead of handing `resume` / the stored record a non-resumable id. The budget must
 // exceed launch.sh's fast-fail threshold so a genuine failure exits PAST it — the retry loop then treats it as a
@@ -2262,6 +2364,7 @@ const socketListenerLiveness = (_rec, tmuxAlive, _runtimeDir, _pane, socketLive)
 const socketListenerOrPidAliveLiveness = (_rec, tmuxAlive, _runtimeDir, pane, socketLive) => (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline');
 const panePidLiveness = (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && pane?.pidAlive === true ? 'online' : 'offline');
 const recordOnline = (rec) => rec.stopped ? 'offline' : 'online';
+const sessionHomeLiveness = (_rec, tmuxAlive) => tmuxAlive ? 'online' : 'offline';
 // @@@ unlinkSocks - remove ONLY the transport this teardown PROVED dead. `cleanupRuntime` unlinks *their*
 // socket, and the honest test of "theirs" is that the agent it just killed is GONE. It used to unlink on
 // faith, which is unsound because a socket path is derived from the session id ALONE: it is the one
@@ -2333,7 +2436,8 @@ export const claudeHarness = {
     // the caller) — NOT the mere existence of a stale socket FILE a crashed claude leaves behind (the 30-min
     // dead-pane-reads-working bug). See rendezvousListening.
     liveness: socketListenerLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: (rec) => rec.session,
+    deliveryTransport: claudeDeliveryTransport,
     deliver: (rec, text) => deliverViaClaudeRendezvous(rec.session, text, rec.mid, rec.runtimeDir),
     cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
     coldRuntime: async () => ({ ok: true }),
@@ -2359,18 +2463,20 @@ export const claudeHeadlessHarness = {
     id: 'claude-headless',
     sessionEnvVar: harnessIdentity('claude-headless').sessionEnvVar,
     headless: true,
-    runtimeOwnership: 'adapter',
+    runtimeOwnership: 'leaf',
     ownsRendezvous: false,
     paneTitleIsSelfSummary: false,
     launchCmd: (id, runtimeDir, cmd) => claudeHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), claudeBaseCmd(cmd)),
     launchEnv: noLaunchEnv,
-    // Liveness is the intact, non-stopped record's property. A missing controller/child fails loudly at control
-    // time rather than turning an idle (no child) session into a speculative offline row.
-    liveness: recordOnline,
+    liveness: sessionHomeLiveness,
+    deliveryTransport: unprovenDeliveryTransport,
     deliver: deliverViaClaudeHeadless,
     interrupt: interruptClaudeHeadless,
     cleanupRuntime: (rec) => unlinkSocks(claudeHeadlessSock(rec.session)),
-    coldRuntime: async () => ({ ok: false, reason: 'claude-headless has no exact resident unload verification' }),
+    coldRuntime: async (rec) => {
+        const result = await claudeHeadlessColdRuntime(rec);
+        return result.ok ? { ok: true } : { ok: false, reason: result.error || 'claude-headless runtime remains unproven' };
+    },
     deliveryBlockedBy: undefined,
 };
 function codexRuntimeDescriptor(endpoint, runtimeDir) {
@@ -2405,8 +2511,16 @@ function codexRuntimeDescriptors(runtimeDir) {
     return (endpoints.length ? endpoints : [legacyCodexGenerationEndpoint(runtimeDir)])
         .map((endpoint) => codexRuntimeDescriptor(endpoint, runtimeDir));
 }
+function codexResumeArg(rec, pendingLaunchPayload) {
+    if (rec.harnessSessionId)
+        return `--resume ${rec.harnessSessionId}`;
+    if (pendingLaunchPayload == null)
+        throw new Error(`session ${rec.session}: native identity is absent and the authoritative resolved launch payload is missing; refusing to create an empty thread`);
+    return shQuote(pendingLaunchPayload);
+}
 export const codexHarness = {
     id: 'codex',
+    launchPayloadProof: true,
     dispatchId: 'codex',
     headless: false,
     sharedRuntimeSpawn: true,
@@ -2477,7 +2591,7 @@ export const codexHarness = {
             return pane.pidAlive ? 'online' : 'offline';
         return paneTreeRunsCodex(pane) ? 'online' : 'offline';
     },
-    leafOwnerNeedle: (rec) => rec.harnessSessionId ?? null,
+    exactNativeTargetId: (rec) => rec.harnessSessionId || null,
     deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
     observeTurnFailures: codexTurnFailureObserver,
     interrupt: interruptCodexTurn,
@@ -2641,8 +2755,8 @@ export const codexHarness = {
     sharedRuntimes: codexRuntimeDescriptors,
     // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
     // a tail handed to a bare `codex` — the script's final `codex … resume "$tid"` performs codex's own resume on
-    // the owned id, the SAME conversation); none → empty tail → relaunch a FRESH thread on the same worktree/record.
-    resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
+    // the owned id, the SAME conversation); no identity → replay the authoritative resolved launch payload.
+    resumeArg: codexResumeArg,
     // codex's own settled failure: a thread id whose rollout is not on disk can never be resumed, so the launch
     // that says so has already decided. (Its transient sibling — the rollout still being written — is handled
     // BEFORE launch by waitForCodexRollout, so what reaches here is the permanent case.)
@@ -2754,6 +2868,7 @@ async function codexHeadlessReadinessProof(current) {
 export const codexHeadlessHarness = {
     ...codexHarness,
     id: 'codex-headless',
+    launchPayloadProof: true,
     sessionEnvVar: harnessIdentity('codex-headless').sessionEnvVar,
     headless: true,
     runtimeOwnership: 'adapter',
@@ -2779,9 +2894,9 @@ export const codexHeadlessHarness = {
             await new Promise((resolve) => setTimeout(resolve, Math.min(200, remaining)));
         }
     },
-    // There is no TUI to restart and the project app-server keeps the thread addressable. A forced reopen therefore
-    // runs the headless launch's empty-tail no-op; normal resume remains guarded by record-backed online liveness.
-    resumeArg: () => '',
+    // There is no TUI to restart and the project app-server keeps an identified thread addressable. A pre-identity
+    // recovery still replays the authoritative resolved launch payload through codex-launch.
+    resumeArg: codexResumeArg,
 };
 // @@@ piHarness - the pi adapter (@earendil-works/pi-coding-agent). pi is the CLOSEST to claude of the four:
 // the caller pins the session id at launch (`--session-id <id>`, creating the session if missing), the shim
@@ -2824,7 +2939,8 @@ export const piHarness = {
     // claude's exact liveness: the window is up AND a live LISTENER answers on the rendezvous socket — the
     // socket the generated extension binds. socketLive is already probed for every windowed session.
     liveness: socketListenerLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: (rec) => rec.session,
+    deliveryTransport: rendezvousDeliveryTransport,
     deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
     cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
     coldRuntime: async () => ({ ok: true }),
@@ -2835,18 +2951,19 @@ export const piHarness = {
 // pi-headless is an independent harness: its materialization surface is literally pi's, while a resident
 // controller owns non-interactive text-mode turns. Active turns steer through pi's rendezvous extension;
 // idle delivery cold-wakes the exact saved session with `--session` (never `--session-id`, which would create a
-// new conversation). The controller deliberately reports record-backed liveness, matching Claude headless.
+// new conversation). The exact tmux home is its public addressability and physical-cold boundary.
 export const piHeadlessHarness = {
     ...piHarness,
     id: 'pi-headless',
     sessionEnvVar: harnessIdentity('pi-headless').sessionEnvVar,
     headless: true,
+    deliveryTransport: unprovenDeliveryTransport,
     // The controller is a per-session process launched in the target tmux pane. Its launch-registered PID
-    // and argv session id are exact leaf ownership evidence; record-backed liveness does not make it shared.
+    // and argv session id are exact leaf ownership evidence.
     runtimeOwnership: 'leaf',
     paneTitleIsSelfSummary: false,
     launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
-    liveness: recordOnline,
+    liveness: sessionHomeLiveness,
     deliver: deliverViaPiHeadless,
     cleanupRuntime: (rec) => unlinkSocks(piHeadlessSock(rec.session), rvSock(rec.session)),
     coldRuntime: async (rec) => {
@@ -2888,7 +3005,7 @@ export const zcodeHarness = {
     clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject); },
     slashCommands: () => [],
     liveness: panePidLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: () => null,
     deliver: async () => { throw new Error(ZCODE_CONTROL_UNAVAILABLE); },
     cleanupRuntime: async () => { },
     coldRuntime: async () => ({ ok: true }),
@@ -2934,7 +3051,8 @@ export const opencodeHarness = {
     // (the plugin is alive), FALL BACK to the launch-registered agent.pid (kill-0) so a plugin that failed to
     // load still reads honestly from the process signal instead of a false offline.
     liveness: socketListenerOrPidAliveLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: (rec) => rec.harnessSessionId || null,
+    deliveryTransport: rendezvousDeliveryTransport,
     deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
     cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
     coldRuntime: async () => ({ ok: true }),
@@ -2951,12 +3069,14 @@ export const opencodeHeadlessHarness = {
     id: 'opencode-headless',
     sessionEnvVar: harnessIdentity('opencode-headless').sessionEnvVar,
     headless: true,
-    runtimeOwnership: 'adapter',
+    runtimeOwnership: 'leaf',
+    deliveryTransport: unprovenDeliveryTransport,
     launchCmd: (_id, _runtimeDir, cmd) => opencodeHeadlessLaunchCommand(opencodeBaseCmd(cmd)),
-    // A sleeping native conversation is still addressable by its non-stopped record. Transport breakage belongs
-    // to the next delivery, where the live rendezvous or pane wake reports it loudly.
-    liveness: recordOnline,
-    coldRuntime: async () => ({ ok: false, reason: 'opencode-headless has no exact resident unload verification' }),
+    liveness: sessionHomeLiveness,
+    coldRuntime: async (rec) => {
+        const result = await opencodeHeadlessColdRuntime(rec);
+        return result.ok ? { ok: true } : { ok: false, reason: result.error || 'opencode-headless runtime remains unproven' };
+    },
     deliver: async (rec, text) => {
         return deliverViaSocketOrWake(rec.session, text, rec.mid, () => spawnOpenCodeHeadlessTurn(rec, text, opencodeBaseCmd(rec.launchCmd ?? undefined), rvSock(rec.session)), `opencode-headless rendezvous probe was inconclusive for session ${rec.session} - refusing to start a possibly duplicate turn`);
     },

package/node_modules/@spexcode/spec-cli/dist/help.d.ts

@@ -1,4 +1,9 @@
 export declare function commandHelp(name: string, verb?: string): string | null;
+export type PublicCommand = Readonly<{
+    name: string;
+    text: string;
+}>;
+export declare function publicCommands(): readonly PublicCommand[];
 export type HelpCatalogEntry = Readonly<{
     id: string;
     title: string;

package/node_modules/@spexcode/spec-cli/dist/help.js

@@ -36,7 +36,7 @@ session to that node. --prompt-file <path>|- carries a long prompt without shell
 reproduced against a frozen commit; a base that names no commit is refused before anything is created.
 The successful receipt names what to read, monitor, and reply on. --ssh uses an existing gateway-to-gateway
 communication tunnel: its full id anchors the remote project, creation stays parentless and remote, and its
-prompt carries a runnable reply path over that same tunnel.`],
+prompt carries a runnable reply path over that same tunnel.`, ['project-bound']],
         ls: [['spex session ls [SEL…] [--children[=<PARENT-SEL>]] [--status a,b] [--all] [--json]', 'spex session ls --ssh <address> <FULL-SESSION-ID> [--children=<PARENT-SEL>] [--status a,b] [--json]'],
             'One-shot table of this project\'s live sessions, with each direct parent beside the row. --children scopes it to the caller\'s direct children; --children=<PARENT-SEL> names another parent without changing positional selector grammar. The heading summarizes the displayed scope by status. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it. An explicit id missing from the session list is diagnosed from terminal-close history: closed is a successful answer, while no live, archived, or closed history is a named miss. --ssh uses an existing gateway-to-gateway communication tunnel; its full id anchors one remote project rather than filtering the table, and archive projection stays unavailable on that peer route.', ['selector']],
         resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
@@ -96,8 +96,8 @@ const SESSION_HELP_GROUPS = [
     { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask', 'files', 'web'] },
     { title: 'Human escape hatch', verbs: ['attach'] },
 ];
-const SESSION_WRITE_NOTE = `Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
-another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.`;
+const SESSION_WRITE_NOTE = `PROJECT-BOUND WRITES loudly refuse a backend serving another project's repo —
+name the target with --api <url> to drive it on purpose.`;
 function indent(text, spaces) {
     const prefix = ' '.repeat(spaces);
     return text.split('\n').map((line) => `${prefix}${line}`).join('\n');
@@ -127,7 +127,7 @@ function sessionVerbHelp(verb) {
 const ENTRIES = {
     // ── project verbs (implicit object = this project) ────────────────────────
     graph: {
-        line: 'graph                 the assembled view: bare = readable tree · --json = full payload · --public = static graph snapshot',
+        line: 'graph                 list the assembled spec nodes: bare = readable tree · --json = full payload · --public = static graph snapshot',
         body: `Usage: spex graph [--focus <id>] [--depth N] [--json] | spex graph --public [--out <path>] [--content-dir <path>]
 
 The normal assembled view is merged spec tree + worktree overlay + sessions. Bare it renders the
@@ -170,15 +170,22 @@ hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arriv
         see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
     },
     doctor: {
-        line: 'doctor                diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]',
+        line: 'doctor                diagnose project health; repair app-server only on explicit request  [--contract|--conflicts]',
         body: `Usage: spex doctor                spec-health findings + delivery report: preconditions · git-hook floor ·
                                   contract · hooks + handler existence · backend · footprint
        spex doctor --contract     print the composed surface:system text any agent here reads
        spex doctor --conflicts    detect double-delivery (loose artifacts beside the managed ones)
+       spex doctor repair app-server [--launcher <name>]
+                                  prove a fresh app-server, then switch new sessions to it
 
 Bare doctor is the opt-in, read-only health surface: it reports altitude and breadth findings without
 putting them in the lint gate, then audits workflow delivery. Run it directly or let the tidy workflow
-consume the same visible diagnosis.`,
+consume the same visible diagnosis.
+
+Use repair app-server only when new sessions cannot be accepted and existing work must stay connected.
+It proves a fresh app-server before routing future Codex sessions there. Existing sessions stay on the
+previous server while it drains; the command does not kill or move them. --launcher selects a configured
+Codex launcher, or the configured default is used when it is one.`,
         see: 'spex spec lint (deterministic graph/contract gate) · spex materialize (repair delivery artifacts)',
     },
     flat: {
@@ -495,6 +502,14 @@ export function commandHelp(name, verb) {
         if (exact)
             return `${exact}\n\nsee also: spex session (the complete drawer)\n\nmap: spex help · skills: spex guide`;
     }
+    if (name === 'doctor' && verb === 'repair') {
+        return `Usage: spex doctor repair app-server [--launcher <name>]
+
+Use this explicit repair when new sessions cannot be accepted but existing work must stay connected.
+It proves a fresh app-server, then routes future Codex sessions there. Existing sessions stay bound to
+the prior server while it drains; this command never kills or moves them. --launcher must name a
+configured Codex launcher.\n\nsee also: spex doctor (the complete command) · spex session resources\n\nmap: spex help · skills: spex guide`;
+    }
     const e = ENTRIES[name];
     if (!e)
         return null;
@@ -502,6 +517,11 @@ export function commandHelp(name, verb) {
     const header = oneLiner ? `spex ${name} — ${oneLiner}\n\n` : ''; // unlisted entries (internal, help) lead with their own Usage
     return `${header}${e.body}${e.see ? `\n\nsee also: ${e.see}` : ''}\n\nmap: spex help · skills: spex guide`;
 }
+export function publicCommands() {
+    return Object.entries(ENTRIES)
+        .filter(([name]) => name !== 'internal')
+        .map(([name, entry]) => ({ name, text: `${entry.line}\n${entry.body}` }));
+}
 // The guidance catalog consumes this registry projection rather than copying help prose or maintaining a
 // second command list. Each returned text is exactly what the corresponding public help probe prints.
 export function helpCatalogEntries() {

package/node_modules/@spexcode/spec-cli/dist/index.js

@@ -751,8 +751,9 @@ app.get('/api/sessions/:id/socket', upgradeWebSocket((c) => {
 }));
 // ONE input route, `kind` the discriminator — the transport split is an implementation fact, not API surface.
 // kind:"text" (`spex session send`, the server-side merge dispatch) appends the prompt to the
-// target timeline, then best-effort pokes its adapter. A dead channel delays context injection but does not
-// change the successful append response; 502 means the record rejected the write.
+// target timeline, then best-effort pokes its adapter. A proven-unreachable transport joined to a live
+// registered agent is stranded and refuses before append; an unproven/dead-restartable channel stays queued.
+// 502 means the record rejected the write.
 // kind:"keys" is the LAST-RESORT raw face (`spex session send --keys`): an ORDERED BATCH of
 // nav-mode key tokens over tmux send-keys, delivered in array order so tap order survives
 // ([[nav-mode-key-ordering]]); unstable by nature — callers try a plain text send first. An unknown kind is a
@@ -878,7 +879,6 @@ superviseBridges(); // restore visible helpers after failure; their viewer subsc
 superviseQueue(); // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
 superviseTurnFailures(); // reconcile adapter-owned native failure subscriptions across backend replacement
 superviseDelivery(); // hand over messages an earlier pass could not ([[delivery-queue]]): the retry half of dispatch
-console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`);
 let graphWatchersClosed = false;
 const closeGraphWatchers = () => {
     if (graphWatchersClosed)

package/node_modules/@spexcode/spec-cli/dist/listen.d.ts

@@ -3,5 +3,6 @@ export declare function listenOrExit(server: Server, port: number, opts: {
     host?: string;
     label: string;
     cleanup?: () => void;
-    onListen: () => void;
+    onListen?: () => void;
+    ready: string | string[];
 }): void;

package/node_modules/@spexcode/spec-cli/dist/listen.js

@@ -1,11 +1,6 @@
-// @@@ listenOrExit - the shared "I own this port; if I cannot bind it, I have failed" contract for the two
-// public-port listeners: the supervisor's raw-TCP proxy (supervise.ts) and the dashboard/public gateway
-// (gateway.ts). A bind failure is the ONE thing neither may survive — it is the opposite of the keep-serving
-// process guard, which rides out transient throws once the port is already held. So instead of leaving the
-// listen error unhandled (under `serve` the supervisor's uncaughtException guard would SWALLOW it into a
-// portless zombie on a random child port; under `dashboard`, with no guard, it would crash with a raw stack),
-// we attach one handler that fails loudly the same way on both surfaces: name the busy port and the repair,
-// reap any child booted for this bind so none is orphaned, and exit non-zero.
+// @@@ listenOrExit ([[listener-readiness]]) - the one public-listener transition: before `listening`, a bind
+// failure is loud and fatal; after it, publication side effects and user-visible ready lines may run. Keeping
+// both halves here prevents a private child or pre-bind caller from announcing a surface it does not own.
 //
 // http.Server / https.Server both extend net.Server, so this one signature covers every caller.
 export function listenOrExit(server, port, opts) {
@@ -17,8 +12,13 @@ export function listenOrExit(server, port, opts) {
         console.error(`spec-cli: ${opts.label} cannot bind — ${why}. Free :${port} (e.g. lsof -i :${port}) or pick another port, then retry.`);
         process.exit(1);
     });
+    const publishReady = () => {
+        opts.onListen?.();
+        for (const line of Array.isArray(opts.ready) ? opts.ready : [opts.ready])
+            console.log(line);
+    };
     if (opts.host)
-        server.listen(port, opts.host, opts.onListen);
+        server.listen(port, opts.host, publishReady);
     else
-        server.listen(port, opts.onListen);
+        server.listen(port, publishReady);
 }

package/node_modules/@spexcode/spec-cli/dist/opencode-headless.d.ts

@@ -1,4 +1,5 @@
 import { type DispatchResult, type HarnessDeliveryRecord } from './harness.js';
 export declare function opencodeHeadlessLaunchCommand(opencodeCmd?: string): string;
 export declare function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionId: string | null | undefined, text: string, outcomePath?: string): string;
+export declare function opencodeHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
 export declare function spawnOpenCodeHeadlessTurn(rec: HarnessDeliveryRecord, text: string, opencodeCmd: string, socketPath: string): Promise<DispatchResult>;

package/node_modules/@spexcode/spec-cli/dist/opencode-headless.js

@@ -97,6 +97,13 @@ export function opencodeHeadlessWakeCommand(opencodeCmd, harnessSessionId, text,
     ];
     return turnHome([...runPrelude(opencodeCmd), ...resume].join('\n'), outcomePath);
 }
+export async function opencodeHeadlessColdRuntime(rec) {
+    const { rendezvousListening } = await import('./harness.js');
+    const probe = await rendezvousListening(rec.session);
+    return probe === 'dead'
+        ? { ok: true }
+        : { ok: false, error: `opencode-headless rendezvous is still ${probe === 'live' ? 'live' : 'unproven'}` };
+}
 function readTurnOutcome(path) {
     let value;
     try {

package/node_modules/@spexcode/spec-cli/dist/runtime-rotate.d.ts

@@ -0,0 +1 @@
+export declare function runDoctorRepairAppServer(args: string[]): Promise<number>;