@spexcode/spec-cli 0.6.5 → 0.6.6

package/bin/spex.mjs

@@ -16,7 +16,7 @@ const workspace = join(pkg, '..')
 // carry unresolved conflict markers, so hooks keep the retryable exit-75 contract during a merge.
 const sourceRoot = join(pkg, 'src')
 if (existsSync(sourceRoot)) {
-  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'packages', 'session-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
   const conflicted = srcRoots.flatMap((root) => {
     if (!existsSync(root)) return []
     return readdirSync(root, { recursive: true })
@@ -39,6 +39,7 @@ if (existsSync(sourceRoot)) {
   const runtimeEntries = [
     cli,
     join(workspace, 'packages', 'spec-core', 'dist', 'index.js'),
+    join(workspace, 'packages', 'session-core', 'dist', 'index.js'),
     join(workspace, 'spec-eval', 'dist', 'index.js'),
     join(workspace, 'spec-forge', 'dist', 'index.js'),
   ]

package/dist/claude-headless.d.ts

@@ -5,7 +5,10 @@ type ClaudeHeadlessDeliveryRecord = HarnessDeliveryRecord & {
 export declare const claudeHeadlessSock: (id: string) => string;
 export declare function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, claudeCmd: string): string;
 export declare const deliverViaClaudeHeadless: (rec: ClaudeHeadlessDeliveryRecord, text: string) => Promise<DispatchResult>;
-export declare const interruptClaudeHeadless: (rec: HarnessDeliveryRecord) => Promise<DispatchResult>;
+export declare const interruptClaudeHeadless: (rec: HarnessDeliveryRecord) => Promise<{
+    ok: boolean;
+}>;
+export declare function claudeHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
 export declare class ClaudeHeadlessController {
     private readonly id;
     private readonly claudeCmd;

package/dist/claude-headless.js

@@ -28,10 +28,19 @@ export const deliverViaClaudeHeadless = (rec, text) => controlRequest(claudeHead
     name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
     rejected: 'claude-headless control rejected the request',
 });
-export const interruptClaudeHeadless = (rec) => controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
-    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
-    rejected: 'claude-headless control rejected the request',
-});
+export const interruptClaudeHeadless = (rec) => rec.stopped || rec.archived
+    ? Promise.resolve({ ok: true })
+    : controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
+        name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+        rejected: 'claude-headless control rejected the request',
+    });
+export async function claudeHeadlessColdRuntime(rec) {
+    const { listenerAt } = await import('./harness.js');
+    const probe = await listenerAt(claudeHeadlessSock(rec.session));
+    return probe === 'dead'
+        ? { ok: true }
+        : { ok: false, error: `claude-headless controller is still ${probe === 'live' ? 'live' : 'unproven'}` };
+}
 export class ClaudeHeadlessController {
     id;
     claudeCmd;

package/dist/cli.js

@@ -6,6 +6,34 @@ import { installEvalHost } from './eval-host.js';
 installEvalHost();
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 const cmd = process.argv[2];
+function levenshtein(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+}
+function nearestPublicCommand(input, commands) {
+    const query = input.toLowerCase();
+    if (!/^[a-z0-9-]+$/.test(query))
+        return null;
+    const similarity = (a, b) => 1 - levenshtein(a, b) / Math.max(a.length, b.length);
+    const words = (text) => text.toLowerCase().match(/[a-z0-9-]+/g) ?? [];
+    let best = null;
+    for (const command of commands) {
+        const [headline = '', ...detail] = command.text.split('\n');
+        const score = Math.max(similarity(query, command.name), ...words(headline).map((word) => similarity(query, word)), ...words(detail.join('\n')).map((word) => similarity(query, word) * 0.8));
+        if (!best || score > best.score)
+            best = { name: command.name, score };
+    }
+    return best && best.score >= 0.8 ? best.name : null;
+}
 if (cmd === '--version' || cmd === '-v') {
     const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
     console.log(manifest.version);
@@ -31,14 +59,15 @@ async function assertDaemonDependencies(command) {
     process.exit(1);
 }
 // Registered before any await so a fatal top-level error lands here. Errors we OWN — BackendError, the
-// loud malformed-config ConfigError, the --api/--port UsageError, the write-guard GuardError — are
+// loud malformed-config ConfigError, the --api/--port UsageError, the write-guard GuardError, and a
+// GitWorkspaceError that teaches a fresh directory how to continue — are
 // matched BY NAME (to avoid importing them) and rendered as a one-line `spex: <message>` (a user's
 // config typo or a refused cross-project write must read as their situation, not a SpexCode stack dump);
 // anything else prints in full so a real bug keeps its trace. A synchronous throw inside an awaited call
 // (loadConfig on a malformed spexcode.json) surfaces as uncaughtException, not unhandledRejection, so BOTH
 // paths route through the same printer.
 function fatal(e) {
-    if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError', 'DashboardAssetError'].includes(e.name))
+    if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError', 'DashboardAssetError', 'GitWorkspaceError'].includes(e.name))
         console.error(`spex: ${e.message}`);
     else
         console.error(e);
@@ -68,6 +97,13 @@ function flushExit(code = 0) {
 const has = (name) => process.argv.includes(`--${name}`);
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
 const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--content-dir', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys', '--ssh', '--allow-stop', '--allow-resume', '--ttl-ms', '--wait-ms', '--adapter', '--thread', '--tmux', '--worktree', '--branch', '--to', '--name', '--base', '--path', '--owner', '--details', '--variant', '--cli', '--count', '--ids']);
+const EXPLICIT_BACKEND_ROUTE_FLAGS = ['api', 'port', 'password', 'insecure'];
+const EXPLICIT_BACKEND_VALUE_FLAGS = EXPLICIT_BACKEND_ROUTE_FLAGS
+    .filter((name) => VALUE_FLAGS.has(`--${name}`))
+    .map((name) => `--${name}`);
+const EXPLICIT_BACKEND_BARE_FLAGS = EXPLICIT_BACKEND_ROUTE_FLAGS
+    .filter((name) => !VALUE_FLAGS.has(`--${name}`))
+    .map((name) => `--${name}`);
 function positionals(from) {
     const out = [];
     for (let i = from; i < process.argv.length; i++) {
@@ -81,7 +117,7 @@ function positionals(from) {
     }
     return out;
 }
-function rejectUnknownFlags(command, from, allowed, attached = []) {
+function rejectFlags(command, from, allowed, attached = []) {
     const known = new Set(allowed.map((name) => `--${name}`));
     for (let i = from; i < process.argv.length; i++) {
         const token = process.argv[i];
@@ -97,6 +133,12 @@ function rejectUnknownFlags(command, from, allowed, attached = []) {
             i++;
     }
 }
+function rejectUnknownFlags(command, from, allowed, attached = []) {
+    rejectFlags(command, from, allowed, attached);
+}
+function rejectUnknownBackendFlags(command, from, allowed, attached = []) {
+    rejectFlags(command, from, [...allowed, ...EXPLICIT_BACKEND_ROUTE_FLAGS], attached);
+}
 // `--children` deliberately has an optional value only in its attached form. A separated following token
 // remains a normal ls selector, so the long-standing `ls --children <child-SEL>` grammar keeps its meaning.
 function childrenScopeOption() {
@@ -125,8 +167,8 @@ function sessionSendUsage(detail, keys = false) {
     process.exit(2);
 }
 function parseSessionSendArgs(args) {
-    const valueFlags = new Set(['--api', '--port', '--keys', '--password', '--ssh']);
-    const bareFlags = new Set(['--insecure']);
+    const valueFlags = new Set([...EXPLICIT_BACKEND_VALUE_FLAGS, '--keys', '--ssh']);
+    const bareFlags = new Set(EXPLICIT_BACKEND_BARE_FLAGS);
     const values = new Map();
     const positionals = [];
     let endOfOptions = false;
@@ -210,8 +252,8 @@ function sessionTargetUsage(verb, detail) {
 }
 function parseSessionTargetArgs(verb, args) {
     const values = new Map();
-    const valueFlags = new Set(['--api', '--port', '--password', '--ssh']);
-    const bareFlags = new Set(verb === 'show' ? ['--capture', '--json', '--insecure'] : ['--insecure']);
+    const valueFlags = new Set([...EXPLICIT_BACKEND_VALUE_FLAGS, '--ssh']);
+    const bareFlags = new Set([...EXPLICIT_BACKEND_BARE_FLAGS, ...(verb === 'show' ? ['--capture', '--json'] : [])]);
     const positionals = [];
     for (let i = 0; i < args.length; i++) {
         const token = args[i];
@@ -253,6 +295,7 @@ const SIGNPOSTS = {
     blob: 'spex evidence put|get',
     issues: 'spex issue — ls (was: bare issues) · show · open · reply · close · promote; on|off|status → the `issues.enabled` key in spexcode.json; `issues nudge` → spex internal nudge',
     forge: 'spex issue links [--pending] [--store <host>]  (--host is now --store)',
+    runtime: 'spex doctor repair app-server',
     new: 'spex session new',
     ls: 'spex session ls',
     watch: 'spex session watch',
@@ -395,7 +438,7 @@ async function stateKit() {
 // reach here — the signpost table above already exited.)
 if (cmd && cmd !== 'help' && (has('help') || process.argv.includes('-h'))) {
     const { commandHelp, overviewHelp } = await import('./help.js');
-    console.log(commandHelp(cmd, cmd === 'session' ? process.argv[3] : undefined) ?? overviewHelp());
+    console.log(commandHelp(cmd, cmd === 'session' || cmd === 'doctor' ? process.argv[3] : undefined) ?? overviewHelp());
     process.exit(0);
 }
 if (cmd === 'serve') {
@@ -955,7 +998,7 @@ else if (cmd === 'session') {
         }
         const newPositionals = positionals(4);
         const peerAnchor = parseSessionPeerAnchor('new', newPositionals);
-        rejectUnknownFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'name', 'base', 'api', 'port', 'ssh']);
+        rejectUnknownBackendFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'name', 'base', 'ssh']);
         if (peerAnchor && newPositionals.length > 2)
             sessionPeerAnchorUsage('new', '--ssh accepts one full-id anchor and one inline prompt at most');
         const { createSession, ownSessionId, withPeerSenderHint } = await import('./sessions.js');
@@ -1023,7 +1066,7 @@ else if (cmd === 'session') {
         // The backend's default projection excludes cold archives. --all and an explicit selector request the
         // history projection so an operator can still inspect or unarchive one deliberately.
         const selectors = positionals(4);
-        rejectUnknownFlags('spex session ls', 4, ['status', 'all', 'json', 'api', 'port', 'ssh', 'children'], ['children']);
+        rejectUnknownBackendFlags('spex session ls', 4, ['status', 'all', 'json', 'ssh', 'children'], ['children']);
         const peerAnchor = parseSessionPeerAnchor('ls', selectors);
         const children = childrenScopeOption();
         if (peerAnchor && selectors.length !== 1)
@@ -1089,7 +1132,7 @@ else if (cmd === 'session') {
         }
     }
     else if (sub === 'resources') {
-        rejectUnknownFlags('spex session resources', 4, ['json', 'api', 'port']);
+        rejectUnknownBackendFlags('spex session resources', 4, ['json']);
         const { clientResources } = await import('./client.js');
         const report = await clientResources();
         if (has('json'))
@@ -1368,7 +1411,7 @@ else if (cmd === 'session') {
             console.log(`closed ${full}`);
         }
         else if (sub === 'quarantine') {
-            rejectUnknownFlags('spex session quarantine', 4, ['adapter', 'thread', 'tmux', 'worktree', 'branch', 'restore', 'api', 'port']);
+            rejectUnknownBackendFlags('spex session quarantine', 4, ['adapter', 'thread', 'tmux', 'worktree', 'branch', 'restore']);
             if (!id) {
                 console.error('usage: spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <session-id> --worktree <absent-path> --branch <absent-branch> (--thread is adapter-native; omit it for Claude)');
                 process.exit(2);
@@ -1390,7 +1433,7 @@ else if (cmd === 'session') {
             }
         }
         else if (sub === 'reparent') {
-            rejectUnknownFlags('spex session reparent', 4, ['to', 'api', 'port']);
+            rejectUnknownBackendFlags('spex session reparent', 4, ['to']);
             const children = positionals(4);
             const to = flag('to');
             if (!children.length || !to) {
@@ -1425,8 +1468,8 @@ else if (cmd === 'session') {
                 console.error(`spex session send --keys: nothing delivered to ${full} (offline, unknown session, or no valid key token)`);
                 process.exit(1);
             }
-            // The backend decides send success at the timeline append. A dead adapter poke only delays context
-            // injection, while a refused record write prints the reason and exits non-zero.
+            // A send is accepted at its timeline append, except a proven-unreachable transport attached to a live
+            // registered agent: that stranded combination refuses before it can add unclaimable queue debt.
             // BIDIRECTIONAL: stamp the SENDER (this send process's OWN session — the only process that knows it, via
             // ownSessionId from CLAUDE_CODE_SESSION_ID) + a one-line reply hint into the delivered
             // message, so the recipient can reply over the SAME send. The sender's row (hence its display label) is
@@ -1455,8 +1498,12 @@ else if (cmd === 'session') {
             const r = sendArgs.sshAddress
                 ? await c.clientSendThroughPeer(sendArgs.sshAddress, full, text, from)
                 : await c.clientSend(full, text, from);
-            console.log(r.ok ? 'sent' : `dispatch failed: ${r.error}`);
-            process.exit(r.ok ? 0 : 1);
+            if (r.ok) {
+                console.log('sent');
+                process.exit(0);
+            }
+            console.error(`dispatch failed: ${r.error}`);
+            process.exit(1);
         }
         else if (sub === 'show') {
             // the session RECORD as one per-id read (status · node · branch · launcher · the full originating
@@ -1637,11 +1684,11 @@ else if (cmd === 'internal') {
     }
     else if (sub === 'codex-launch') {
         // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
-        // (codex loads that worktree's config/hooks/AGENTS.md), store the new id on the governed record (keyed by
-        // SPEXCODE_SESSION_ID), fire the launch prompt as the FIRST turn — materializing the rollout — and print the
-        // thread id. The launch script then `resume`s it in the visible TUI.
+        // (codex loads that worktree's config/hooks/AGENTS.md), fire the launch prompt as the FIRST turn —
+        // materializing the rollout — then stage the id + exact-payload proof for the session lifecycle owner and
+        // print the thread id. The launch script then `resume`s it in the visible TUI.
         const { codexStartThread, codexTurn, waitForCodexRollout, codexBinary, codexSupportsBypassHookTrust, codexLauncherThreadPolicy } = await import('./harness.js');
-        const { markHarnessSessionId } = await import('./sessions.js');
+        const { stageHarnessLaunchProof } = await import('./sessions.js');
         const sock = process.argv[4], cwd = process.argv[5];
         const prompt = process.argv.slice(6).join(' ');
         if (!sock || !cwd) {
@@ -1680,7 +1727,7 @@ else if (cmd === 'internal') {
         }
         const sid = process.env.SPEXCODE_SESSION_ID;
         if (sid)
-            markHarnessSessionId(sid, r.threadId);
+            stageHarnessLaunchProof(sid, r.threadId, prompt);
         console.log(r.threadId);
     }
     else if (sub === 'opencode-capture') {
@@ -1854,6 +1901,8 @@ else if (cmd === 'internal') {
     }
 }
 else {
-    console.error(`spex: unknown command '${cmd}' (try: spex help)`);
+    const { publicCommands } = await import('./help.js');
+    const suggestion = nearestPublicCommand(cmd, publicCommands());
+    console.error(`spex: unknown command '${cmd}'${suggestion ? ` — try: spex ${suggestion}` : ''} (try: spex help)`);
     process.exit(2);
 }

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { type CockpitReview } from './cockpit.js';
+import type { SessionEvalRevision } from '@spexcode/spec-eval/sessioneval';
 import { type Session, type SessionClosure, type Resolved, type DispatchResult } from './sessions.js';
 export declare class BackendError extends Error {
     readonly status?: number | undefined;
@@ -48,7 +49,7 @@ type SessionEvalPage = {
     unknown: number;
     revision: string;
     summary?: any;
-    evalRevision?: any;
+    evalRevision?: SessionEvalRevision;
 };
 export type EvalsResult = {
     ok: true;

package/dist/client.js

@@ -259,7 +259,7 @@ export async function clientCapture(id) {
     return { ok: false, status: r.status, reason: (await r.text().catch(() => '')) || `status ${r.status}` };
 }
 // POST /api/sessions/:id/input {kind:"text"} appends the prompt to the durable timeline, then best-effort
-// pokes the resolved adapter. HTTP failure means the append itself was refused.
+// pokes the resolved adapter. HTTP failure means the append was refused, including a proven stranded transport.
 export async function clientSend(id, text, from) {
     await guarded('session send');
     // `from` = the sending agent's own session id; the recipient's log records the sender ([[session-timeline]]) only when
@@ -331,30 +331,35 @@ export async function clientEvalExport(id) {
         return { ok: true, body: await r.text() };
     return { ok: false, status: r.status };
 }
+const evalRevisionKey = (revision) => JSON.stringify([revision.epoch, revision.generation, revision.content]);
+const formatEvalRevision = (revision) => revision ? `${revision.epoch}@${revision.generation} (${revision.content})` : 'missing';
 export async function clientEvals(id) {
     const q = encodeURIComponent(`is:eval scope:${id}`);
+    const drifts = [];
     for (let attempt = 0; attempt < 2; attempt++) {
         const items = [];
         let first = null;
-        let changed = false;
+        let snapshot = null;
         for (let page = 1;; page++) {
             const r = await apiFetch(`/api/evals?q=${q}&page=${page}`);
             if (!r.ok)
                 return { ok: false, status: r.status };
             const current = await r.json();
             first ??= current;
-            if (current.revision !== first.revision) {
-                changed = true;
+            if (current.pageCount > 1 && !current.evalRevision) {
+                throw new BackendError(`session eval page ${page}/${current.pageCount} for ${id} has no evalRevision; cannot assemble a consistent snapshot`);
+            }
+            snapshot ??= current.evalRevision ?? null;
+            if (current.evalRevision && snapshot && evalRevisionKey(current.evalRevision) !== evalRevisionKey(snapshot)) {
+                drifts.push(`attempt ${attempt + 1}: ${formatEvalRevision(snapshot)} -> ${formatEvalRevision(current.evalRevision)} at page ${page}`);
                 break;
             }
             items.push(...current.items);
             if (page >= current.pageCount)
-                break;
+                return { ok: true, model: { ...first, id, items } };
         }
-        if (!changed)
-            return { ok: true, model: { ...first, id, items } };
     }
-    throw new BackendError(`session eval pages changed while fetching ${id}; retry the command`);
+    throw new BackendError(`session eval snapshot changed during both fetch attempts for ${id} (${drifts.join('; ')}); retry the command`);
 }
 // POST /api/sessions/:id/merge — a human merge intent dispatched to the session's own agent.
 export async function clientMerge(id) {

package/dist/codex-runtime-generations.d.ts

@@ -31,7 +31,12 @@ export type CodexGenerationLedger = Readonly<{
 export declare function codexGenerationSocketPath(root: string, generationId?: string): string;
 export declare function legacyCodexGenerationEndpoint(root: string): CodexGenerationEndpoint;
 export declare function readCodexGenerationLedger(root: string): CodexGenerationLedger;
+export type CodexGenerationRotation = Readonly<{
+    previous: CodexGenerationEndpoint;
+    current: CodexGenerationEndpoint;
+}>;
 export declare function ensureCodexCurrentGeneration(root: string, start: (endpoint: CodexGenerationEndpoint) => Promise<void>): Promise<CodexGenerationEndpoint>;
+export declare function rotateCodexCurrentGeneration(root: string, start: (endpoint: CodexGenerationEndpoint) => Promise<void>): Promise<CodexGenerationRotation>;
 export declare function bindCodexGeneration(root: string, sessionId: string, threadId: string, generationId: string | null): void;
 export declare function prepareCodexGenerationRegistration(root: string, sessionId: string, threadId: string, generationId: string): void;
 export declare function commitCodexGenerationRegistration(root: string, sessionId: string, threadId: string, generationId: string): void;

package/dist/codex-runtime-generations.js

@@ -497,6 +497,118 @@ export async function ensureCodexCurrentGeneration(root, start) {
         return publishPendingGeneration(root, action.endpoint);
     }
 }
+// An operator can move NEW traffic off a current root that is still exactly identifiable but unhealthy. This is
+// deliberately not a restart: bindings remain on the old endpoint, which keeps serving them as draining until
+// its ordinary zero-reference reclamation proof succeeds.
+async function publishRotatedGeneration(root, endpoint) {
+    return withLedgerLock(root, async () => {
+        let previous = readCodexGenerationLedger(root);
+        if (previous.pending !== endpoint.id || !endpointIdentity(endpoint))
+            throw new Error('Codex generation rotation CAS lost or candidate identity changed before publication');
+        const previousId = previous.current;
+        const old = previousId ? previous.generations[previousId] : null;
+        if (!previousId || !old || old.state !== 'current')
+            throw new Error('canonical Codex generation changed during rotation; retry');
+        if (!endpointIdentity(old.endpoint)) {
+            // A root proven gone during the finite start window is safe to retire. Ambiguity remains a refusal: a
+            // ready candidate stays durably pending for a later explicit retry, rather than guessing at ownership.
+            const retired = retireGoneGenerationLocked(root, previous, previousId);
+            if (!retired)
+                throw new Error('canonical Codex generation became unproven during rotation; refusing to switch traffic');
+            previous = retired;
+        }
+        const generations = {
+            ...previous.generations,
+            [endpoint.id]: { state: 'current', endpoint },
+        };
+        if (previous.current)
+            generations[previous.current] = { state: 'draining', endpoint: old.endpoint };
+        writeLedger(root, previous, { current: endpoint.id, pending: null, generations, bindings: previous.bindings });
+        return { previous: old.endpoint, current: endpoint };
+    });
+}
+export async function rotateCodexCurrentGeneration(root, start) {
+    const deadline = Date.now() + 30_000;
+    for (;;) {
+        const action = await withLedgerLock(root, async () => {
+            let previous = readCodexGenerationLedger(root);
+            if (previous.revision === 0 && !existsSync(ledgerPath(root))) {
+                const bootstrapped = bootstrapLedger(root);
+                previous = writeLedger(root, previous, bootstrapped);
+            }
+            const current = previous.current ? previous.generations[previous.current] : null;
+            if (!current || current.state !== 'current')
+                throw new Error('there is no proven canonical app-server generation to switch; launch a Codex session first');
+            if (!endpointIdentity(current.endpoint)) {
+                if (goneGeneration(current.endpoint))
+                    throw new Error('canonical Codex generation is already dead; a normal Codex launch will replace it');
+                throw new Error('canonical app-server generation is unproven; refusing to switch traffic');
+            }
+            if (previous.pending) {
+                const pending = previous.generations[previous.pending];
+                if (!pending || pending.state !== 'starting')
+                    throw new Error('Codex generation ledger pending rotation is malformed');
+                // A prior coordinator may have completed the detached spawn but crashed before the pointer CAS.
+                if (endpointIdentity(pending.endpoint))
+                    return { kind: 'publish', endpoint: pending.endpoint };
+                if (pending.reservation && processStartToken(pending.reservation.pid) === pending.reservation.startToken)
+                    return { kind: 'wait' };
+                const generations = { ...previous.generations };
+                delete generations[pending.endpoint.id];
+                writeLedger(root, previous, { current: previous.current, pending: null, generations, bindings: previous.bindings });
+                return { kind: 'retry' };
+            }
+            const endpoint = newEndpoint(root);
+            const startToken = processStartToken(process.pid);
+            if (!startToken)
+                throw new Error('cannot prove coordinator process identity for Codex generation rotation reservation');
+            mkdirSync(dirname(endpoint.pidFile), { recursive: true, mode: 0o700 });
+            writeLedger(root, previous, {
+                current: previous.current,
+                pending: endpoint.id,
+                generations: { ...previous.generations, [endpoint.id]: { state: 'starting', endpoint, reservation: { pid: process.pid, startToken } } },
+                bindings: previous.bindings,
+            });
+            return { kind: 'start', endpoint };
+        });
+        if (action.kind === 'publish')
+            return publishRotatedGeneration(root, action.endpoint);
+        if (action.kind === 'retry')
+            continue;
+        if (action.kind === 'wait') {
+            if (Date.now() >= deadline)
+                throw new Error('Codex generation rotation reservation owner is still live but did not publish; retry after it exits');
+            await sleep(50);
+            continue;
+        }
+        try {
+            await start(action.endpoint);
+        }
+        catch (error) {
+            await withLedgerLock(root, async () => {
+                const previous = readCodexGenerationLedger(root);
+                if (previous.pending !== action.endpoint.id || endpointIdentity(action.endpoint))
+                    return;
+                const generations = { ...previous.generations };
+                delete generations[action.endpoint.id];
+                writeLedger(root, previous, { current: previous.current, pending: null, generations, bindings: previous.bindings });
+            });
+            throw error;
+        }
+        if (!await waitForEndpoint(action.endpoint)) {
+            await withLedgerLock(root, async () => {
+                const previous = readCodexGenerationLedger(root);
+                if (previous.pending !== action.endpoint.id || endpointIdentity(action.endpoint))
+                    return;
+                const generations = { ...previous.generations };
+                delete generations[action.endpoint.id];
+                writeLedger(root, previous, { current: previous.current, pending: null, generations, bindings: previous.bindings });
+            });
+            throw new Error(`candidate Codex generation ${action.endpoint.id} did not prove a live detached endpoint; current pointer was not switched`);
+        }
+        return publishRotatedGeneration(root, action.endpoint);
+    }
+}
 export function bindCodexGeneration(root, sessionId, threadId, generationId) {
     withLedgerLockSync(root, () => {
         const previous = readCodexGenerationLedger(root);

package/dist/doctor.js

@@ -518,7 +518,9 @@ function usage() {
     console.error(`spex doctor — diagnose spec health and how the SpexCode workflow reaches your agent
   (bare)         spec-health findings + delivery report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
   --contract     print the surface:system contract text (hand it to any agent)
-  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)`);
+  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
+  repair app-server [--launcher <name>]
+                  prove a fresh app-server, then switch new sessions to it without moving existing sessions`);
     return 0;
 }
 export async function runDoctor(args) {
@@ -530,6 +532,10 @@ export async function runDoctor(args) {
         return contract();
     if (args.includes('--conflicts'))
         return await conflicts();
+    if (args[0] === 'repair') {
+        const { runDoctorRepairAppServer } = await import('./runtime-rotate.js');
+        return await runDoctorRepairAppServer(args);
+    }
     switch (args[0]) {
         case undefined: return await doctor();
         case 'contract':

package/dist/gateway-hub.js

@@ -327,11 +327,13 @@ export function startHubGateway(opts) {
         socket.once('close', () => upstream.destroy());
         upstream.once('close', () => socket.destroy());
     });
-    const onListen = () => {
-        const scheme = secure ? 'https' : 'http';
-        console.log(`[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${port} — /projects + /p/:projectId/*`);
-    };
-    listenOrExit(server, port, { host: opts.host, label: opts.label ?? 'hub gateway', cleanup: opts.onBindFail, onListen });
+    const scheme = secure ? 'https' : 'http';
+    listenOrExit(server, port, {
+        host: opts.host,
+        label: opts.label ?? 'hub gateway',
+        cleanup: opts.onBindFail,
+        ready: `[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${port} — /projects + /p/:projectId/*`,
+    });
     return server;
 }
 // replay an upgrade's headers with the Cookie header rewritten to exclude the gateway's own cookies.

package/dist/gateway.d.ts

@@ -22,6 +22,7 @@ export type GatewayOpts = {
     label?: string;
     onBindFail?: () => void;
     projectRoot?: string;
+    readyLines?: string[];
 };
 export declare function startGateway(opts: GatewayOpts): void;
 export declare function rawHeaders(req: http.IncomingMessage): string;