spexcode 0.6.5 → 0.6.7

package/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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/node_modules/@spexcode/spec-cli/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;

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

@@ -178,17 +178,15 @@ export function startGateway(opts) {
     // narrows the public gateway's reach. The gate note keys on LOOPBACK, not on host-being-explicit:
     // an ungated loopback bind is normal, an ungated wide bind is announced — never silent.
     const isLoopback = opts.host === '127.0.0.1' || opts.host === 'localhost' || opts.host === '::1';
-    const onListen = () => {
-        const scheme = secure ? 'https' : 'http';
-        const label = opts.label ?? 'public mode';
-        const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
-        console.log(`[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`);
-        if (!secure && !isLoopback && !opts.host)
-            console.log('[gateway] (TLS off — --http)');
-    };
+    const scheme = secure ? 'https' : 'http';
+    const label = opts.label ?? 'public mode';
+    const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
+    const ready = [...(opts.readyLines ?? []), `[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`];
+    if (!secure && !isLoopback && !opts.host)
+        ready.push('[gateway] (TLS off — --http)');
     // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
     // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex serve ui` fail a port clash identically.
-    listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, onListen });
+    listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, ready });
 }
 // re-serialize an upgrade request's headers for replay against the upstream (exported for the host
 // gateway's per-project WS pipe, which replays the same way).
@@ -223,6 +221,16 @@ function doLogin(req, res, password, setCookie) {
 // and would fight Range requests.
 const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml)|image\/svg)/;
 const wantsGzip = (req) => /\bgzip\b/.test(String(req.headers['accept-encoding'] || ''));
+// zlib's larger default table can be counterproductive for minified text: memLevel 5 both compresses it
+// further and lowers each stream's working memory. One policy drives buffered and streamed gzip.
+const GZIP_OPTIONS = { level: 9, memLevel: 5 };
+function appendVary(current, token) {
+    const values = (Array.isArray(current) ? current : [current ?? ''])
+        .flatMap((value) => value.split(',')).map((value) => value.trim()).filter(Boolean);
+    if (!values.some((value) => value === '*' || value.toLowerCase() === token.toLowerCase()))
+        values.push(token);
+    return values.join(', ');
+}
 // reverse-proxy an /api request to the loopback supervisor (which forwards to the live child) —
 // stream-gzipping compressible bodies (measured: the board JSON rides down at under a third).
 // `path` and `headers` optionally override routing inputs (the host gateway strips its /p/:projectId
@@ -322,16 +330,19 @@ export function proxyHttp(req, res, upstreamPort, path, headers = req.headers, u
         received.once('close', () => { if (!received.complete)
             failFromUpstream(); });
         const type = String(received.headers['content-type'] || '');
-        const skip = !wantsGzip(req) || received.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream');
-        if (skip) {
-            res.writeHead(received.statusCode || 502, received.headers);
+        const eligible = !received.headers['content-encoding'] && COMPRESSIBLE.test(type) && !type.startsWith('text/event-stream');
+        const responseHeaders = eligible
+            ? { ...received.headers, vary: appendVary(received.headers.vary, 'Accept-Encoding') }
+            : received.headers;
+        if (!eligible || !wantsGzip(req)) {
+            res.writeHead(received.statusCode || 502, responseHeaders);
             received.pipe(res);
             return;
         }
-        const headers = { ...received.headers, 'content-encoding': 'gzip', vary: 'Accept-Encoding' };
+        const headers = { ...responseHeaders, 'content-encoding': 'gzip' };
         delete headers['content-length']; // streamed; the encoded length isn't knowable up front
         res.writeHead(received.statusCode || 502, headers);
-        transform = createGzip();
+        transform = createGzip(GZIP_OPTIONS);
         transform.once('error', failFromUpstream);
         received.pipe(transform).pipe(res);
     });
@@ -473,17 +484,21 @@ export function serveStatic(req, res, distDir, urlPath) {
     const type = MIME[extname(file)] || 'application/octet-stream';
     const cacheControl = /[\\/]assets[\\/]/.test(file) ? 'public, max-age=31536000, immutable' : 'no-cache';
     const raw = readFileSync(file);
-    if (wantsGzip(req) && COMPRESSIBLE.test(type)) {
+    const compressible = COMPRESSIBLE.test(type);
+    const headers = { 'Content-Type': type, 'Cache-Control': cacheControl };
+    if (compressible)
+        headers.Vary = appendVary(undefined, 'Accept-Encoding');
+    if (wantsGzip(req) && compressible) {
         const mtime = statSync(file).mtimeMs;
         let hit = gzMemo.get(file);
         if (!hit || hit.mtime !== mtime) {
-            hit = { mtime, gz: gzipSync(raw) };
+            hit = { mtime, gz: gzipSync(raw, GZIP_OPTIONS) };
             gzMemo.set(file, hit);
         }
-        res.writeHead(200, { 'Content-Type': type, 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding', 'Cache-Control': cacheControl });
+        res.writeHead(200, { ...headers, 'Content-Encoding': 'gzip' });
         return res.end(hit.gz);
     }
-    res.writeHead(200, { 'Content-Type': type, 'Cache-Control': cacheControl });
+    res.writeHead(200, headers);
     res.end(raw);
 }
 function sendHtml(res, status, html) {
@@ -498,6 +513,15 @@ function sendHtml(res, status, html) {
 // installed user has no source tree for). See [[packaging]].
 export function serveDashboardLocal(opts) {
     const distDir = resolveDistDir();
-    console.log(`[dashboard] serving ${distDir}, /api → backend :${opts.apiPort}`);
-    startGateway({ host: opts.host ?? '127.0.0.1', publicPort: opts.port, upstreamPort: opts.apiPort, password: '', tls: null, distDir, label: 'dashboard', projectRoot: opts.projectRoot });
+    startGateway({
+        host: opts.host ?? '127.0.0.1',
+        publicPort: opts.port,
+        upstreamPort: opts.apiPort,
+        password: '',
+        tls: null,
+        distDir,
+        label: 'dashboard',
+        projectRoot: opts.projectRoot,
+        readyLines: [`[dashboard] serving ${distDir}, /api → backend :${opts.apiPort}`],
+    });
 }

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

@@ -3,7 +3,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { rebasePublishedSessions } from '@spexcode/spec-core';
 import { buildBoard, spliceSessions } from './graphSnapshot.js';
-import { headSha, repoRoot, withGitAbortSignal } from '@spexcode/spec-core';
+import { headSha, repoRoot, requireGitWorkspace, withGitAbortSignal } from '@spexcode/spec-core';
 import { listSessionIds, mainBranch, mainCheckout, readPublicRecordEntry, sessionArtifactPath, sessionRecordPath } from '@spexcode/spec-core';
 import { boardThreads } from './issues.js';
 import { resolveForgeHost } from '@spexcode/spec-forge/drivers';
@@ -162,6 +162,7 @@ function sessionInputRevision() {
 }
 function boardInputRevision(board) {
     const root = repoRoot();
+    requireGitWorkspace(root);
     const session = sessionInputRevision();
     // Durable active records are the current root set; a cached ordinary row may be stale and must not replace
     // them. The one projection-only addition is explicit: listSessions republishes an archived-runtime hazard

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

@@ -1,4 +1,4 @@
-import { loadSpecs } from '@spexcode/spec-core';
+import { loadSpecs, requireGitWorkspace } from '@spexcode/spec-core';
 import { resolveLayout } from '@spexcode/spec-core';
 import { listSessions } from './sessions.js';
 import { driftIndex, historyIndex, repoRoot } from '@spexcode/spec-core';
@@ -12,6 +12,7 @@ import { sessionEvalProjections } from '@spexcode/spec-eval/sessioneval';
 // The application adapter is the sole reader of runtime/forge state. graph.ts only receives this result.
 export async function boardSnapshot() {
     const root = repoRoot();
+    requireGitWorkspace(root);
     const [specs, sessions] = await Promise.all([loadSpecs(), listSessions()]);
     const layout = await resolveLayout({ activeSessionIds: sessions.map((session) => session.id) });
     const nodeIds = [...new Set([