@spexcode/spec-cli 0.6.7 → 0.7.0-next.0

package/dist/client.js

@@ -5,7 +5,8 @@ import { repoRoot } from '@spexcode/spec-core';
 import { resourceBudgets } from './host-resources.js';
 import { envSessionId, listSessionIds, readPublicRecordEntry } from '@spexcode/spec-core';
 import { cockpitReview } from './cockpit.js';
-import { apiBaseInfo, assertProjectMatch, findSessionClosure, fromRaw, optionArgv, resolveSession, toSession } from './sessions.js';
+import { configuredSessionApplicationIfCutover, sessionApplicationCutoverState } from './session-application.js';
+import { apiBaseInfo, assertProjectMatch, displayStatusForProposal, fromRaw, optionArgv, resolveSession, toSession } from './sessions.js';
 import { resolveMachinePeer } from './machine-peer.js';
 export class BackendError extends Error {
     status;
@@ -136,7 +137,7 @@ function cachedStatus(rec) {
     if (rec.archived)
         return 'offline';
     if (rec.status === 'awaiting')
-        return rec.proposal === 'merge' ? 'review' : rec.proposal === 'close' ? 'close-pending' : 'done';
+        return displayStatusForProposal(rec.proposal);
     return rec.status === 'active' || rec.status === 'idle' ? 'unknown' : rec.status;
 }
 function corruptCachedSession(id, reason) {
@@ -145,7 +146,7 @@ function corruptCachedSession(id, reason) {
         id, node: null, branch: null, path: '', label, title: label, raw: { name: null, title: null },
         parent: null, harness: 'unknown', capabilities: { headless: false }, launcher: null,
         lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
-        note: `session record is unreadable: ${reason}`, archived: false, archiveHazard: null,
+        note: `session record is unreadable: ${reason}`, archived: false, closedAt: null, archiveHazard: null,
         prompt: null, promptPreview: null, created: 0, activity: null, sortKey: null,
     };
 }
@@ -154,18 +155,59 @@ function corruptCachedSession(id, reason) {
 // follow exists to eliminate. Every field here comes from the store — nothing is probed.
 export function localCachedSessions(includeArchived = false) {
     const rows = [];
+    // The runtime envelope is deliberately metadata-only after migration. A live session may therefore have
+    // a canonical application row before its runtime.json is materialized (or after it is retired). Selectors
+    // must still resolve that row; treating the missing envelope as "no such session" strands watch/cancel.
+    // Do not create a fresh SQLite store while merely reading an empty project. A canonical application is
+    // needed only when a marker or legacy records prove that this project already has session state.
+    const cutover = sessionApplicationCutoverState();
+    const application = cutover === 'fresh' ? undefined : configuredSessionApplicationIfCutover();
     for (const id of listSessionIds()) {
         const entry = readPublicRecordEntry(id);
         if (entry.kind === 'corrupt') {
             rows.push(corruptCachedSession(id, entry.error));
             continue;
         }
-        if (entry.kind !== 'ok')
+        if (entry.kind === 'ok') {
+            const rec = fromRaw(entry.raw);
+            if (!rec.governed)
+                continue;
+            rows.push(toSession(rec, cachedStatus(rec), 'unknown'));
             continue;
-        const rec = fromRaw(entry.raw);
-        if (!rec.governed)
+        }
+        const state = application?.readState(id);
+        if (!state)
             continue;
-        rows.push(toSession(rec, cachedStatus(rec), 'unknown'));
+        const lifecycle = state.status;
+        const status = state.status === 'awaiting'
+            ? displayStatusForProposal(state.proposal)
+            : state.status === 'archived' ? 'offline' : state.status;
+        rows.push({
+            id,
+            node: null,
+            branch: null,
+            path: '',
+            label: id,
+            title: id,
+            raw: { name: null, title: null },
+            parent: state.parentSessionId,
+            harness: 'unknown',
+            capabilities: { headless: false },
+            launcher: null,
+            lifecycle,
+            proposal: state.proposal,
+            merges: 0,
+            status,
+            liveness: 'unknown',
+            note: state.note,
+            archived: state.status === 'archived',
+            closedAt: null,
+            prompt: null,
+            promptPreview: null,
+            created: state.updatedAtMs,
+            activity: null,
+            sortKey: null,
+        });
     }
     return rows.filter((session) => includeArchived || !session.archived)
         .sort((a, b) => (a.sortKey ?? a.created) - (b.sortKey ?? b.created) || a.id.localeCompare(b.id));
@@ -226,20 +268,6 @@ export async function clientListSessions(includeArchived = false) {
         return await r.json();
     }, () => localCachedSessions(includeArchived));
 }
-// A terminal close removes the record from the board. The audit lookup is deliberately id-addressed and is
-// consulted only after an explicit selector missed that board, so ordinary lists stay a current-state read.
-export async function clientSessionClosure(selector) {
-    return cachedRead(async () => {
-        const r = await apiFetch(`/api/sessions/${seg(selector)}/closure`);
-        if (r.headers.get('x-spexcode-close-history') !== 'v1')
-            throw new BackendError(`backend does not support terminal close history; refusing to label ${selector} as never existed (update the backend)`, 501);
-        if (r.status === 404)
-            return null;
-        if (!r.ok)
-            throw new BackendError(`backend error ${r.status} retrieving close history for ${selector}`, r.status);
-        return await r.json();
-    }, () => findSessionClosure(selector));
-}
 export async function clientResources() {
     return cachedRead(async () => {
         const r = await apiFetch('/api/resources');
@@ -429,15 +457,6 @@ export async function clientRestoreQuarantine(id) {
         throw new BackendError(`backend returned an invalid quarantine restore for ${id}`, r.status);
     return { id: body.id, bundle: body.bundle, sha256: body.sha256, observedAt: body.observedAt };
 }
-// POST /api/sessions/:id/archive — cold-archive the session ([[archive]]). The legacy on=false spelling is a
-// signpost to the same resume transition; it never performs a record-only unarchive.
-export async function clientArchive(id, on = true) {
-    await guarded(on ? 'session archive' : 'session unarchive');
-    const r = await apiFetch(`/api/sessions/${seg(id)}/archive`, post({ on }));
-    if (!r.ok)
-        throw new BackendError(`backend refused to ${on ? 'archive' : 'unarchive'} ${id}: ${await r.text()}`, r.status);
-    return !!(await r.json().catch(() => ({ ok: false })))?.ok;
-}
 // POST /api/sessions/:id/rename — set (or clear, with a blank) the session's display-name override
 // ([[session-rename]] as a CLI verb). {ok:false} = no such session (404).
 export async function clientRename(id, name) {

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

@@ -31,6 +31,8 @@ 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 declare function ensureCodexGenerationLedger(root: string): Promise<CodexGenerationLedger>;
+export declare function withCodexGenerationMutex<T>(root: string, body: () => Promise<T>): Promise<T>;
 export type CodexGenerationRotation = Readonly<{
     previous: CodexGenerationEndpoint;
     current: CodexGenerationEndpoint;
@@ -55,4 +57,13 @@ export declare function reclaimDrainingCodexGeneration(root: string, generationI
     reclaimed: boolean;
     reason: string;
 }>;
+export declare function reclaimDrainingCodexGenerations(root: string, census: (endpoint: CodexGenerationEndpoint) => Promise<{
+    healthy: boolean;
+    referenceIds: string[];
+    peerCount: number;
+}>): Promise<Array<{
+    generationId: string;
+    reclaimed: boolean;
+    reason: string;
+}>>;
 export {};

package/dist/codex-runtime-generations.js

@@ -82,6 +82,16 @@ export function readCodexGenerationLedger(root) {
         return emptyLedger();
     return parseLedger(JSON.parse(readFileSync(ledgerPath(root), 'utf8')));
 }
+// The backend startup sweep must see legacy roots too. Bootstrap only when the legacy residue is present; an
+// empty project remains an empty ledger and no runtime is created by inspection.
+export async function ensureCodexGenerationLedger(root) {
+    return withLedgerLock(root, async () => {
+        const current = readCodexGenerationLedger(root);
+        if (existsSync(ledgerPath(root)) || current.revision !== 0)
+            return current;
+        return writeLedger(root, current, bootstrapLedger(root));
+    });
+}
 function writeLedger(root, previous, next) {
     const observed = readCodexGenerationLedger(root);
     if (observed.revision !== previous.revision)
@@ -244,6 +254,12 @@ async function withLedgerLock(root, body) {
         releaseLedgerLock(root, owner);
     }
 }
+// Codex accepts only a bounded amount of concurrent thread/start work. The generation ledger lock is already
+// the cross-process project mutex with exact stale-owner recovery, so use it for native thread admission too.
+// This keeps launch serialization in the runtime owner rather than making callers invent their own queue.
+export async function withCodexGenerationMutex(root, body) {
+    return withLedgerLock(root, body);
+}
 function withLedgerLockSync(root, body) {
     const owner = acquireLedgerLockSync(root);
     try {
@@ -317,7 +333,7 @@ function bootstrapBindings(root, generationId) {
     }
     for (const sessionId of ids) {
         try {
-            const record = JSON.parse(readFileSync(join(sessions, sessionId, 'session.json'), 'utf8'));
+            const record = JSON.parse(readFileSync(join(sessions, sessionId, 'runtime.json'), 'utf8'));
             const harness = record.harness;
             const threadId = record.harness_session_id;
             if (record.governed === true && (harness === 'codex' || harness === 'codex-headless') && typeof threadId === 'string' && threadId) {
@@ -328,20 +344,28 @@ function bootstrapBindings(root, generationId) {
     }
     return result;
 }
-function pendingBindingHasRecord(root, sessionId, binding) {
+function readBindingRecord(root, sessionId) {
     if (!sessionId || sessionId.includes('/') || sessionId.includes('\\'))
-        return false;
+        return null;
     try {
-        const record = JSON.parse(readFileSync(join(root, 'sessions', sessionId, 'session.json'), 'utf8'));
-        const harness = record.harness;
-        return record.governed === true && (harness === 'codex' || harness === 'codex-headless') && record.harness_session_id === binding.threadId;
+        return JSON.parse(readFileSync(join(root, 'sessions', sessionId, 'runtime.json'), 'utf8'));
     }
     catch {
-        return false;
+        return null;
     }
 }
+function bindingRecordMatches(record, binding) {
+    const harness = record?.harness;
+    return !!record && record.governed === true && (harness === 'codex' || harness === 'codex-headless') && record.harness_session_id === binding.threadId;
+}
 function bindingProtectsGeneration(root, sessionId, binding) {
-    return binding.phase === undefined || pendingBindingHasRecord(root, sessionId, binding);
+    // A close transaction remains protective until its record is physically removed. Once a historical
+    // record is archived, its durable rollout is still recoverable but the record no longer routes or pins
+    // a live generation; the native census remains the independent guard for any still-loaded thread.
+    const record = readBindingRecord(root, sessionId);
+    if (!record)
+        return binding.phase !== 'record-pending' && binding.phase !== 'record-removing';
+    return bindingRecordMatches(record, binding) && (binding.phase === 'record-removing' || record.archived !== true);
 }
 function bootstrapLedger(root) {
     const legacy = legacyCodexGenerationEndpoint(root);
@@ -626,7 +650,7 @@ export function bindCodexGeneration(root, sessionId, threadId, generationId) {
         writeLedger(root, previous, { current: previous.current, pending: previous.pending, generations: previous.generations, bindings });
     });
 }
-// Native thread creation and session.json persistence are separate writes. A pending registration can be
+// Native thread creation and runtime envelope persistence are separate writes. A pending registration can be
 // recovered only when the durable record names the same exact thread; otherwise it cannot pin a root forever.
 export function prepareCodexGenerationRegistration(root, sessionId, threadId, generationId) {
     withLedgerLockSync(root, () => {
@@ -796,3 +820,16 @@ export async function reclaimDrainingCodexGeneration(root, generationId, census)
         return { reclaimed: true, reason: 'exact drained generation reclaimed after zero-reference census' };
     });
 }
+// Startup/rotation callers use this sweep to make stale generation cleanup a property of the shared runtime
+// owner. The census remains adapter-supplied and fail-closed; a missing or unhealthy descriptor is retained.
+export async function reclaimDrainingCodexGenerations(root, census) {
+    const generations = readCodexGenerationLedger(root).generations;
+    const results = [];
+    for (const [generationId, generation] of Object.entries(generations)) {
+        if (generation.state !== 'draining')
+            continue;
+        const result = await reclaimDrainingCodexGeneration(root, generationId, census);
+        results.push({ generationId, ...result });
+    }
+    return results;
+}

package/dist/delivery-lock.d.ts

@@ -0,0 +1,2 @@
+/** Serialize delivery claims without making the transport itself part of SQLite. */
+export declare function withDeliveryLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;

package/dist/delivery-lock.js

@@ -0,0 +1,58 @@
+import { mkdirSync, openSync, readFileSync, unlinkSync, writeSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '@spexcode/spec-core';
+const lockRoot = () => join(runtimeRoot(), '.delivery-locks');
+const lockPath = (id) => join(lockRoot(), `${id}.lock`);
+const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+async function acquire(id, timeoutMs) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* a dead owner may have reclaimed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* creator/releaser race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`delivery queue ${id}: timed out waiting for transaction lock`);
+            await pause(25);
+        }
+    }
+}
+/** Serialize delivery claims without making the transport itself part of SQLite. */
+export async function withDeliveryLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
+    if (index >= ids.length)
+        return body();
+    const release = await acquire(ids[index], 30_000);
+    try {
+        return await withDeliveryLocks(ids, body, index + 1, ids);
+    }
+    finally {
+        release();
+    }
+}

package/dist/doctor.js

@@ -3,9 +3,10 @@ import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
-import { loadSystemConfig, loadSkillConfig, loadSpecs } from '@spexcode/spec-core';
-import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from '@spexcode/spec-core';
+import { loadSystemConfig, loadSkillConfig, loadAgentConfig, loadSpecs } from '@spexcode/spec-core';
+import { treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from '@spexcode/spec-core';
 import { loadConfig } from './lint.js';
+import { GENERATED_MARK } from './harness.js';
 import { trackedSourceFiles } from './source-files.js';
 import { gitBinary } from '@spexcode/spec-core';
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
@@ -211,6 +212,25 @@ function manifestScripts(text) {
     }
     return [...out];
 }
+// which EVENTS the manifest actually binds. A tree can carry handlers and still be ungoverned in the way
+// that matters, because a handler answers an event and the lifecycle rides on specific ones.
+function manifestEvents(text) {
+    const out = new Set();
+    for (const line of text.split('\n')) {
+        const f = line.split('\t');
+        if (f.length >= 4 && f[0])
+            out.add(f[0]);
+    }
+    return out;
+}
+// THE LIFECYCLE EVENTS, and why they are named here rather than derived from an adapter's full event list.
+// A tree that binds no turn-end event has a shim, a manifest, and readable handlers — every check above it
+// passes — and still cannot report that its agent stopped: the record keeps whatever state it last held and
+// a dead turn still shows as running. That is not hypothetical; a deployment whose `.config` predated
+// the stop-gate node hit exactly this, and nothing in the diagnosis said so. Stop is the gate; StopFailure
+// is the failed-turn writer; PostToolUse is the freshness mark. Missing any of them is a distinct break
+// from "no manifest", and it is the one a passing installation can hide.
+const LIFECYCLE_EVENTS = ['Stop', 'StopFailure', 'PostToolUse'];
 // the bundle's declared name, from plugin.json (root or the .claude-plugin/ convention), or null when none.
 function pluginName(dir) {
     for (const p of [join(dir, 'plugin.json'), join(dir, '.claude-plugin', 'plugin.json')]) {
@@ -263,6 +283,12 @@ async function doubleDeliveryReport(base) {
     catch {
         return [];
     } })();
+    const ourAgents = (() => { try {
+        return loadAgentConfig().map((c) => c.name);
+    }
+    catch {
+        return [];
+    } })();
     const L = [];
     const line = (k, v) => L.push(`  ${k.padEnd(16)}: ${v}`);
     let conflict = false;
@@ -282,6 +308,13 @@ async function doubleDeliveryReport(base) {
             ...(looseDispatch ? [`loose ${rel(shimFile)}`] : []),
             ...bundles.filter((b) => b.hooksToDispatch).map((b) => `plugin "${b.name}" (${b.scope})`),
         ];
+        // a DIFFERENT collision from the double-delivery channels below: a skill/agent path a live spec node
+        // names, already occupied by a file the user wrote (no GENERATED_MARK). materialize skips those, so the
+        // node silently never reaches this harness — worth naming here, where somebody asks "do we clash?".
+        const userOwned = [
+            ...(looseSkillDir ? ourSkills.map((s) => join(looseSkillDir, s, 'SKILL.md')) : []),
+            ...((dir) => dir ? ourAgents.map((a) => join(dir, `${a}.md`)) : [])(h.agentDir(base)),
+        ].filter((f) => existsSync(f) && !read(f).includes(GENERATED_MARK));
         // channel 2 — same-named skill in loose skillDir AND a bundle's skills dir
         const skillHits = [];
         for (const s of ourSkills) {
@@ -302,6 +335,7 @@ async function doubleDeliveryReport(base) {
             line('  plugin', `"${b.name}" (${b.scope}) — ${b.dir}`);
         line('hooks→dispatch', `${hookSrc.length}${hookSrc.length > 1 ? '  (>1 → CONFLICT): ' + hookSrc.join(', ') : hookSrc.length === 1 ? '  (single — ok)' : '  (none wired)'}`);
         line('skill shadowing', skillHits.length ? `CONFLICT: ${skillHits.join(', ')}` : 'none');
+        line('your files kept', userOwned.length ? `${userOwned.map(rel).join(', ')} — yours (no spexcode stamp), so the same-named spec node is NOT delivered here` : 'none');
         L.push('');
     }
     if (conflict) {
@@ -423,31 +457,39 @@ async function doctor() {
         const shim = read(h.shimFile(base));
         line(`${h.id} shim`, /dispatch\.sh/.test(shim) ? `wired (${h.shimFile(base).replace(base + '/', '')})` : 'NOT wired (no dispatch shim)');
     }
-    // manifest resolution mirrors dispatch.sh: this tree's materialize slot first, then the legacy global file
-    // (a pre-slot tree's migration-window fallback) — so the doctor reads exactly what a dispatch would.
+    // Manifest resolution mirrors dispatch.sh: only the current tree slot is executable.
     let manifestText = '';
     let manifestHome = 'tree slot';
     try {
         manifestText = read(join(treeSlotDir(base), 'hooks-manifest'));
     }
     catch { /* non-git / no store */ }
-    if (!manifestText) {
-        try {
-            manifestText = read(join(runtimeRoot(base), 'hooks-manifest'));
-            manifestHome = 'legacy global file (pre-slot materialize — re-run `spex materialize`)';
-        }
-        catch { /* neither */ }
+    const manifestFile = (() => { try {
+        return join(treeSlotDir(base), 'hooks-manifest');
     }
+    catch {
+        return null;
+    } })();
+    const manifestPresent = !!manifestFile && existsSync(manifestFile);
     if (!manifestText) {
-        line('manifest', 'MISSING from the global store — materialize never ran (hooks fire but find no manifest)');
+        // ABSENT and EMPTY are different breaks and want different repairs, and the dispatcher cannot tell them
+        // apart at all: a missing file is a loud exit 78, an empty one dispatches nothing and exits 0 in silence.
+        line('manifest', manifestPresent
+            ? 'EMPTY in the current tree slot — materialize ran and bound ZERO handlers: this tree has no hook nodes, so every event dispatches nothing and exits 0 in silence'
+            : 'MISSING from the current tree slot — materialize must run before hooks can execute');
     }
     else {
         const scripts = manifestScripts(manifestText);
         const missing = scripts.filter((s) => !existsSync(join(base, s)));
+        const events = manifestEvents(manifestText);
         line('manifest', `${scripts.length} handler(s) in the ${manifestHome}`);
         line('handlers', missing.length === 0 ? 'all readable in the worktree' : `${missing.length} MISSING in the worktree → those hooks SILENTLY NO-OP:`);
         for (const m of missing)
             L.push(`      ✗ ${m}`);
+        const unbound = LIFECYCLE_EVENTS.filter((event) => !events.has(event));
+        line('lifecycle events', unbound.length === 0
+            ? `${LIFECYCLE_EVENTS.join(', ')} all bound`
+            : `${unbound.join(', ')} NOT bound → this tree cannot report its own turn ending; the record keeps its last state and a stopped agent still shows as running`);
     }
     // codex trust
     const trustPresent = codexCfg.includes(`# spexcode:trust:${base}`);

package/dist/file-write.js

@@ -1,15 +1,27 @@
-import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+// A differing target is replaced by rename, never rewritten in place: a concurrent reader — codex re-reading its
+// own config.toml, a harness loading its hooks file — sees the old bytes or the new bytes, never a truncated
+// middle. The replacement lands on the real file behind a symlink and keeps that file's mode.
 export function writeFileIfChanged(path, content) {
     const next = Buffer.from(content);
+    let target = path;
+    let mode;
     try {
         if (readFileSync(path).equals(next))
             return false;
+        target = realpathSync(path);
+        mode = statSync(target).mode;
     }
     catch (error) {
         if (error?.code !== 'ENOENT')
             throw error;
     }
-    writeFileSync(path, content);
+    const staged = join(dirname(target), `.${basename(target)}.${process.pid}.tmp`);
+    writeFileSync(staged, next);
+    if (mode !== undefined)
+        chmodSync(staged, mode);
+    renameSync(staged, target);
     return true;
 }
 export function copyFileIfChanged(source, target) {

package/dist/gateway-hub.js

@@ -11,6 +11,7 @@
 //                                       mounted, an explicit text/html GET gets the Projects UI instead
 //   PUT|DELETE /projects/admin-password admin: set/clear the admin password
 //   PUT|DELETE /projects/:id/password   admin: set/clear one project's password
+//   DELETE /projects/:id                host extension: high-friction catalog registration removal
 //   /p/:projectId/login|logout          project session for that project
 //   ANY /p/:projectId/*  (+ WS upgrade) authorized → proxied, prefix-stripped, to that project's backend
 // Authorization never trusts the cookie's name or Path — the token's projectId claim is validated against
@@ -332,7 +333,7 @@ export function startHubGateway(opts) {
         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/*`,
+        ready: (actualPort) => `[hub] multi-project gateway on ${scheme}://${opts.host ?? '0.0.0.0'}:${actualPort} — /projects + /p/:projectId/*`,
     });
     return server;
 }

package/dist/gateway.js

@@ -181,9 +181,12 @@ export function startGateway(opts) {
     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)');
+    const ready = (port) => {
+        const lines = [...(opts.readyLines ?? []), `[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${port}${gate}, proxying /api to :${opts.upstreamPort}`];
+        if (!secure && !isLoopback && !opts.host)
+            lines.push('[gateway] (TLS off — --http)');
+        return lines;
+    };
     // 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, ready });

package/dist/graphCache.js

@@ -11,6 +11,7 @@ import { residentForgeState } from '@spexcode/spec-forge/resident';
 import { resolveProjectIdentity } from '@spexcode/spec-core';
 import { readReviewSnapshot } from '@spexcode/spec-core';
 import { sessionEvalProjection } from '@spexcode/spec-eval/sessioneval';
+import { resolveDatabasePath } from '@spexcode/session-selflaunch';
 const DEBUG = process.env.SPEXCODE_BOARD_DEBUG === '1';
 function textOrNull(path) {
     try {
@@ -128,6 +129,28 @@ function strictSpecTreeRevision(wtPath) {
     }
     return parts.sort().join('\n');
 }
+// The canonical session database ([[production-cutin]]) is a board input exactly like the runtime envelope:
+// lifecycle status lives there, and ANY process may commit to it — a hook's `spex internal session-state`, a CLI
+// declaration, the backend's own routes. Its file identity folds into the session revision, so a commit no leaf
+// pushed (graph-stream's `session-db` leaf held or disabled) is still a moved revision that the patrol answers
+// with the sessions splice. journal_mode=delete rewrites the file in place on every commit, so this is the same
+// strict stat contract as the `.spec` walk: ctime catches a same-size rewrite, ENOENT is a legitimate fresh
+// store, and every other read failure is loud.
+function strictFileRevision(path) {
+    try {
+        const stat = statSync(path);
+        return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+function sessionDatabaseRevision() {
+    const databasePath = resolveDatabasePath();
+    return [databasePath, strictFileRevision(databasePath)];
+}
 function worktreeRevision(root) {
     return {
         root,
@@ -153,12 +176,17 @@ function sessionInputRevision() {
         textOrNull(sessionRecordPath(id)),
         textOrNull(sessionArtifactPath(id, 'prompt')),
     ]);
+    // The canonical database carries the lifecycle those envelopes no longer do, and a commit from ANY process
+    // moves it. It is an input only while a record exists to read it through: with no session records the board
+    // has no row that derives from the store, and the store's own birth — the first canonical access inside a
+    // build initializes it — must not read as an input that moved during that build.
+    const canonical = ids.length ? sessionDatabaseRevision() : null;
     const projections = digest(ids.map((id) => [id, sessionEvalProjection(id)]));
     const activeRoots = [...new Set(ids.flatMap((id) => {
             const entry = readPublicRecordEntry(id);
             return entry.kind === 'ok' && entry.raw.governed && !entry.raw.archived ? [entry.raw.worktree_path] : [];
         }))].sort();
-    return { sessions: digest(sessionInputs), projections, projectionIds: ids, activeRoots };
+    return { sessions: digest([canonical, sessionInputs]), projections, projectionIds: ids, activeRoots };
 }
 function boardInputRevision(board) {
     const root = repoRoot();
@@ -444,6 +472,8 @@ function startBuild(mode = 'dirty') {
     });
     // Give a stale HTTP response a turn to flush before the producer's synchronous setup occupies the event
     // loop. Fresh callers simply absorb this small scheduling window while waiting on the same flight.
+    // A direct cold reader may be the only live work in a short-lived CLI process. Keep this one-shot
+    // scheduler referenced until it starts the producer, otherwise Node can exit with its fresh read pending.
     setTimeout(() => {
         if (controller.signal.aborted) {
             rejectBuild(Object.assign(new Error('graph build aborted before start'), { name: 'AbortError' }));
@@ -547,7 +577,7 @@ function startBuild(mode = 'dirty') {
         catch (error) {
             rejectBuild(error);
         }
-    }, mode === 'patrol' ? 0 : BACKGROUND_START_DELAY_MS).unref?.();
+    }, mode === 'patrol' ? 0 : BACKGROUND_START_DELAY_MS);
     const timeoutError = () => new Error(`graph build did not settle within ${BUILD_TIMEOUT_MS}ms`);
     // `settle` owns the real builder. The watchdog only rejects `wait`; the slot remains occupied until this
     // promise settles, so a next read can never overlap an abandoned git/fs build.

package/dist/graphSnapshot.js

@@ -1,4 +1,6 @@
-import { loadSpecs, requireGitWorkspace } from '@spexcode/spec-core';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { loadSpecs, requireGitWorkspace, headSha } from '@spexcode/spec-core';
 import { resolveLayout } from '@spexcode/spec-core';
 import { listSessions } from './sessions.js';
 import { driftIndex, historyIndex, repoRoot } from '@spexcode/spec-core';
@@ -9,6 +11,46 @@ import { buildBoard as assembleBoard, spliceSessions as spliceBoardSessions } fr
 import { evalContext, evalTimelines } from '@spexcode/spec-eval/evaltab';
 import { evalNodesAsync } from '@spexcode/spec-eval/scenarios';
 import { sessionEvalProjections } from '@spexcode/spec-eval/sessioneval';
+import { evalRemarkSourceFingerprint } from '@spexcode/spec-eval/host';
+import { listBlobs } from '@spexcode/spec-eval/cache';
+let timelineCache = null;
+function fileFingerprint(path) {
+    try {
+        return readFileSync(path).toString('base64');
+    }
+    catch {
+        return '<missing>';
+    }
+}
+function timelineCacheKey(root, nodeIds, specs, evalNodes) {
+    const hash = createHash('sha256');
+    hash.update(root);
+    hash.update('\0');
+    hash.update(headSha(root) || '<no-head>');
+    hash.update('\0');
+    hash.update(JSON.stringify(nodeIds));
+    for (const spec of specs) {
+        hash.update('\0spec\0');
+        hash.update(spec.path);
+        hash.update('\0');
+        hash.update(spec.body);
+    }
+    for (const node of evalNodes) {
+        hash.update('\0eval\0');
+        hash.update(node.id);
+        hash.update('\0');
+        hash.update(node.evalSource ?? '');
+        hash.update('\0');
+        hash.update(fileFingerprint(node.sidecarPath));
+    }
+    // Issue remarks are an eval input even though they live outside the spec tree.
+    hash.update('\0remarks\0');
+    hash.update(evalRemarkSourceFingerprint());
+    // Evidence presence is part of each published timeline row (`present` vs `miss`).
+    hash.update('\0blobs\0');
+    hash.update(listBlobs().join('\0'));
+    return hash.digest('hex');
+}
 // The application adapter is the sole reader of runtime/forge state. graph.ts only receives this result.
 export async function boardSnapshot() {
     const root = repoRoot();
@@ -22,7 +64,20 @@ export async function boardSnapshot() {
     const { issues, stamp: issuesStamp } = boardThreads({ host: resolveForgeHost(), state: residentForgeState() }, nodeIds);
     const [idx, hidx, evalNodes] = await Promise.all([driftIndex(root), historyIndex(root), evalNodesAsync(root)]);
     const context = await evalContext(root, specs, idx, hidx, undefined, evalNodes);
-    const timelines = await evalTimelines(nodeIds, context);
+    const key = timelineCacheKey(root, nodeIds, specs, evalNodes);
+    let timelines;
+    if (timelineCache?.key === key) {
+        timelines = timelineCache.timelines;
+    }
+    else {
+        // The board carries only latest-per-scenario counts, so the cold build reads latest-only: the retained
+        // sidecar history is served by the detail endpoints and probing it here scales graph latency with the
+        // reading count instead of the live verdict population. Freshness itself is NOT deferred — the board
+        // publishes verdicts, and a verdict whose freshness was never computed is not a stale verdict, it is no
+        // verdict at all. An order-only board would report every measured row as stale and none as fresh.
+        timelines = await evalTimelines(nodeIds, context, { latestOnly: true });
+        timelineCache = { key, timelines };
+    }
     return {
         root, specs, layout, sessions, issues, issuesStamp, forgeRevision: residentForgeRevision(),
         evalTimelines: new Map(nodeIds.map((nodeId, index) => [nodeId, timelines[index]])),