spexcode 0.6.7 → 0.7.0-next.0

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

@@ -89,8 +89,16 @@ export const SpexcodePlugin = async (ctx) => {
   }
 
   // The shared rendezvous server receives best-effort reply pokes. An unadopted plugin simply leaves the
-  // timeline line for its next turn boundary; the SDK injection remains host-owned.
-  rt.serveRendezvous(injectPrompt, { canInject: () => !!(client && rootSession) })
+  // timeline line for its next turn boundary; the SDK injection remains host-owned. An interrupt is
+  // opencode's own session abort on the adopted root session, confirmed back over the same socket.
+  rt.serveRendezvous(injectPrompt, {
+    canInject: () => !!(client && rootSession),
+    interrupt: async () => {
+      if (!client || !rootSession) throw new Error("no opencode session is adopted - nothing to interrupt")
+      const r = await client.session.abort({ path: { id: rootSession } })
+      if (r === false || (r && r.data === false)) throw new Error("no opencode turn is running - nothing to interrupt")
+    },
+  })
 
   const toolPayload = (input, output) => {
     const sid = (input && input.sessionID) || ""

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

@@ -39,21 +39,34 @@ export default function spexcode(pi: ExtensionAPI) {
   const toolFields = (toolName: string, input: unknown) =>
     ({ tool_name: TOOL[toolName] ?? toolName, tool_input: rt.toolInput(input, "path") })
 
+  // the RUNNING turn's context, kept from the events pi hands us mid-turn: ctx.abort() is pi's own "stop the
+  // current agent operation" — the one honest interrupt — and only a turn that is actually streaming has one.
+  let turn: { abort: () => void; isIdle: () => boolean } | null = null
   // bound as soon as the extension loads so liveness reads online early; only a governed launch carries the
   // socket env (sessions.ts rvEnv) — a self-launched bare \`pi\` skips this.
-  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }))
+  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }), {
+    interrupt: () => {
+      if (!turn || turn.isIdle()) throw new Error("no pi turn is running - nothing to interrupt")
+      turn.abort()
+    },
+  })
 
   pi.on("session_start", async (_event, ctx) => {
     sessionId = ctx.sessionManager.getSessionId() || sessionId
     process.env.PI_SESSION_ID = sessionId   // tool subprocesses inherit it → spex CLI knows its session
     await rt.dispatchEvent("SessionStart")
   })
-  pi.on("input", async (event) => { await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
-  pi.on("tool_call", async (event) => {
+  // agent_start is the earliest event a running turn hands us — before the first model token — so an
+  // interrupt that arrives while the model is still thinking finds a turn to abort rather than nothing.
+  pi.on("agent_start", async (_event, ctx) => { turn = ctx })
+  pi.on("turn_start", async (_event, ctx) => { turn = ctx })
+  pi.on("input", async (event, ctx) => { turn = ctx; await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
+  pi.on("tool_call", async (event, ctx) => {
+    turn = ctx
     const r = await rt.dispatchEvent("PreToolUse", toolFields(event.toolName, event.input))
     if (rt.blocked(r)) return { block: true, reason: rt.blockReason(r, "blocked by a SpexCode hook") }
   })
-  pi.on("tool_result", async (event) => { await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
+  pi.on("tool_result", async (event, ctx) => { turn = ctx; await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
   // Stop rides the runtime's dispatchStop on TWO bindings that never duplicate: agent_end performs the
   // NORMAL dispatch (pi awaits its listeners inside the run loop and drains a queued teach as the SAME
   // awaited prompt's continuation — never the orphaned settle-time prompt whose late inject threw
@@ -69,7 +82,7 @@ export default function spexcode(pi: ExtensionAPI) {
     async (reason: string) => pi.sendUserMessage(reason, { deliverAs: "steer" }),
     "a SpexCode Stop hook blocked this stop without giving a reason",
   )
-  pi.on("agent_end", async () => { await stop() })
+  pi.on("agent_end", async () => { turn = null; await stop() })
   pi.on("agent_settled", async () => { if (rt.stopPending()) await stop() })
   pi.on("session_shutdown", async () => { rv?.close() })
 }

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

@@ -3,6 +3,7 @@ import type { DispatchResult, HarnessDeliveryRecord } from './harness.js';
 export declare const piHeadlessSock: (id: string) => string;
 export declare function piHeadlessLaunchCommand(id: string, runtimeDir: string, piCmd: string): string;
 export declare const deliverViaPiHeadless: (rec: HarnessDeliveryRecord, text: string) => Promise<DispatchResult>;
+export declare const interruptPiHeadless: (rec: HarnessDeliveryRecord) => Promise<DispatchResult>;
 export declare function piHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
 export declare class PiHeadlessController {
     private readonly id;
@@ -19,6 +20,7 @@ export declare class PiHeadlessController {
     private terminateTurn;
     private waitForExit;
     private accept;
+    private interrupt;
     private handle;
     private spawnTurn;
 }

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

@@ -12,6 +12,7 @@ const CONTROL_TIMEOUT_MS = 30_000;
 const START_TIMEOUT_MS = 30_000;
 const TERM_EXIT_GRACE_MS = 500;
 const KILL_EXIT_GRACE_MS = 2_000;
+const INTERRUPT_EXIT_GRACE_MS = 15_000;
 /** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
 export const piHeadlessSock = (id) => join(tmpdir(), `spexcode-ph-${id}.sock`);
 export function piHeadlessLaunchCommand(id, runtimeDir, piCmd) {
@@ -21,6 +22,13 @@ export const deliverViaPiHeadless = (rec, text) => controlRequest(piHeadlessSock
     name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
     rejected: 'pi-headless controller rejected the request',
 });
+// The controller owns the turn child, so it is the one actor that can both abort the turn natively and
+// know when that turn is actually over — an interrupt confirmed here means no pi process serves this
+// session any more, and the next delivery is a clean cold wake rather than a poke into an exiting agent.
+export const interruptPiHeadless = (rec) => controlRequest(piHeadlessSock(rec.session), { type: 'interrupt' }, {
+    name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'pi-headless controller rejected the interrupt',
+});
 // The resident controller and a running pi turn own two per-session listeners. The generic lifecycle
 // teardown has already proved and removed the exact controller leaf before this runs; cold filing is valid
 // only once neither listener can still accept work for this session.
@@ -137,7 +145,25 @@ export class PiHeadlessController {
             });
         });
     }
+    // Abort the running turn through pi's own ctx.abort() (the shim answers over the child's rendezvous socket,
+    // so pi records the turn as aborted and the conversation stays resumable), then wait for that child to
+    // exit. A turn whose extension holds no context yet — pi still booting, before its first agent event —
+    // is still THIS controller's process, so it is terminated as the owner rather than left to run.
+    async interrupt() {
+        const turn = this.child;
+        if (!turn || turn.process.exitCode !== null)
+            return { ok: false, error: `no pi-headless turn is running for session ${this.id} - nothing to interrupt` };
+        const { interruptViaRendezvous } = await import('./harness.js');
+        const aborted = await interruptViaRendezvous(this.id, 'pi-headless');
+        if (!aborted.ok && !/no pi turn is running|nothing to interrupt/.test(aborted.error || ''))
+            return aborted;
+        if (!aborted.ok || !await this.waitForExit(turn, INTERRUPT_EXIT_GRACE_MS))
+            await this.terminateTurn(turn);
+        return { ok: true };
+    }
     async handle(request) {
+        if (request.type === 'interrupt')
+            return this.interrupt();
         if (request.type !== 'deliver')
             return { ok: false, error: 'unknown pi-headless control request' };
         if (!request.text)
@@ -171,6 +197,7 @@ export class PiHeadlessController {
             if (this.child === turn)
                 this.child = null;
             resolveExit(code);
+            // an aborted child leaves non-zero too; the session layer's interrupt marker reads that exit as the interrupt it was
             if (code !== 0 && !this.closing)
                 void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'pi-headless', code, this.cwd));
         });

package/node_modules/@spexcode/spec-cli/dist/pty-bridge.js

@@ -1,7 +1,7 @@
 import { execFile, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
-import { alive, withSessionInputLock } from './sessions.js';
+import { alive } from './sessions.js';
 const pexec = promisify(execFile);
 const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode';
 const HELPER = fileURLToPath(new URL('./pty-helper.mjs', import.meta.url));
@@ -9,8 +9,9 @@ const subscribers = new Map();
 const BSU = Buffer.from('\x1b[?2026h');
 const ESU = Buffer.from('\x1b[?2026l');
 const GEOMETRY_STABILIZATION_MS = 400;
-// A hidden but still-alive browser keeps its own client briefly so a quick return is continuous. A dead
-// socket bypasses this window and detaches immediately.
+// A hidden but still-alive browser keeps its own native client briefly so a quick return skips helper spawn
+// and tmux attach. It receives no output while hidden; the return always repaints. A dead socket bypasses
+// this window and detaches immediately.
 const LINGER_MS = Number(process.env.SPEXCODE_TERM_LINGER_MS) > 0 ? Number(process.env.SPEXCODE_TERM_LINGER_MS) : 30_000;
 function subscriptionMap(id) {
     let map = subscribers.get(id);
@@ -26,7 +27,7 @@ function isCurrent(bridge) {
 }
 function deliver(bridge, data) {
     const subscription = currentSubscription(bridge.id, bridge.viewer);
-    if (!subscription || (!subscription.visible && !subscription.lingering))
+    if (!subscription?.visible)
         return;
     try {
         bridge.viewer.send(data);
@@ -174,7 +175,6 @@ function cancelLinger(subscription) {
     if (subscription.lingerTimer)
         clearTimeout(subscription.lingerTimer);
     subscription.lingerTimer = undefined;
-    subscription.lingering = false;
 }
 function cancelRestore(subscription) {
     if (subscription.restoreTimer)
@@ -309,7 +309,7 @@ export function attachViewer(id, viewer) {
     const previous = map.get(viewer);
     if (previous)
         killBridge(previous);
-    map.set(viewer, { visible: false, lingering: false, cols: 0, rows: 0 });
+    map.set(viewer, { visible: false, cols: 0, rows: 0 });
 }
 export function hideViewer(id, viewer) {
     const subscription = currentSubscription(id, viewer);
@@ -318,7 +318,6 @@ export function hideViewer(id, viewer) {
     subscription.visible = false;
     if (!subscription.bridge)
         return;
-    subscription.lingering = true;
     if (subscription.lingerTimer)
         return;
     subscription.lingerTimer = setTimeout(() => {
@@ -346,15 +345,15 @@ export function resizeBridge(id, viewer, colsValue, rowsValue) {
     const subscription = currentSubscription(id, viewer);
     if (!subscription)
         return;
-    const seamless = subscription.lingering && !!subscription.bridge
-        && subscription.bridge.cols === cols && subscription.bridge.rows === rows;
     cancelLinger(subscription);
     subscription.visible = true;
     subscription.cols = cols;
     subscription.rows = rows;
     const { bridge, created } = ensureBridge(id, viewer, subscription, cols, rows);
-    if (!bridge || created || seamless)
+    if (!bridge || created)
         return;
+    // A helper kept alive across a hidden window has been rendering to nobody: the browser cache behind this
+    // claim is stale by exactly that window, so an unchanged grid still answers with one atomic repaint.
     if (bridge.cols === cols && bridge.rows === rows) {
         beginDelivery(bridge);
         queueRefresh(bridge);
@@ -364,14 +363,15 @@ export function resizeBridge(id, viewer, colsValue, rowsValue) {
     }
 }
 const MAX_INPUT_BYTES = 64 * 1024;
+// Input is transport: it goes straight to the helper. It never waits for, or is refused by, the session record
+// lock — that lock serializes lifecycle writers, which hold it for a noticeable share of a busy session's wall
+// time, and a keystroke that lost that race used to vanish silently.
 export function forwardInput(id, viewer, data) {
     const subscription = currentSubscription(id, viewer);
     if (!subscription?.visible || !subscription.bridge || !data || Buffer.byteLength(data, 'utf8') > MAX_INPUT_BYTES)
         return false;
-    return withSessionInputLock(id, () => {
-        sendControl(subscription.bridge, { t: 'input', data });
-        return true;
-    }) ?? false;
+    sendControl(subscription.bridge, { t: 'input', data });
+    return true;
 }
 async function restoreBridge(id, viewer, subscription) {
     subscription.restoreTimer = undefined;

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

@@ -86,7 +86,9 @@ export async function issuesReview(query, requestedPage) {
         }),
     };
 }
-const byNewest = (a, b) => Number(b.filterKind === EVAL_FILTER_KIND.RESULT) - Number(a.filterKind === EVAL_FILTER_KIND.RESULT)
+const orderableEval = (item) => item.filterKind === EVAL_FILTER_KIND.RESULT
+    || item.filterKind === EVAL_FILTER_KIND.DEFERRED;
+const byNewest = (a, b) => Number(orderableEval(b)) - Number(orderableEval(a))
     || String(b.ts ?? '').localeCompare(String(a.ts ?? ''))
     || String(a.node ?? '').localeCompare(String(b.node ?? ''))
     || String(a.scenario ?? '').localeCompare(String(b.scenario ?? ''));
@@ -114,10 +116,11 @@ export function trunkEvalReviewItems(nodes) {
                 ...reading,
                 expected: scenario.expected ?? reading.expected,
                 tags: scenario.tags,
-                state: evalReviewState(reading),
+                ...(reading.freshnessDeferred
+                    ? { state: 'deferred', filterKind: EVAL_FILTER_KIND.DEFERRED }
+                    : { state: evalReviewState(reading), filterKind: EVAL_FILTER_KIND.RESULT }),
                 node: node.id,
                 hue: node.hue,
-                filterKind: EVAL_FILTER_KIND.RESULT,
             });
         }
     }
@@ -149,10 +152,11 @@ export function scopedEvalReviewItems(model) {
                 expected: scenario.expected ?? reading.expected,
                 tags: scenario.tags,
                 impact: scenario.impact,
-                state: evalReviewState(reading),
+                ...(reading.freshnessDeferred
+                    ? { state: 'deferred', filterKind: EVAL_FILTER_KIND.DEFERRED }
+                    : { state: evalReviewState(reading), filterKind: EVAL_FILTER_KIND.RESULT }),
                 node: node.id,
                 hue: node.hue,
-                filterKind: EVAL_FILTER_KIND.RESULT,
             };
             items.push(item);
         }
@@ -278,9 +282,10 @@ export function timelineEvalReviewItems(timeline, node) {
         })),
         ...[...latest.values()].map((reading) => ({
             ...reading,
-            state: evalReviewState(reading),
+            ...(reading.freshnessDeferred
+                ? { state: 'deferred', filterKind: EVAL_FILTER_KIND.DEFERRED }
+                : { state: evalReviewState(reading), filterKind: EVAL_FILTER_KIND.RESULT }),
             node,
-            filterKind: EVAL_FILTER_KIND.RESULT,
             filterKey: `${EVAL_FILTER_KIND.RESULT}:${reading.scenario}`,
         })),
         ...(timeline.dangling ?? []).map((track) => ({

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

@@ -10,6 +10,16 @@ export type BackendInstanceRecord = {
 export declare function readBackendInstanceRecords(root?: string): BackendInstanceRecord[];
 export declare function registerBackendInstance(instanceId: string, pid?: number, root?: string): BackendInstanceRecord;
 export declare function unregisterBackendInstance(instanceId: string, pid?: number): void;
+type ProcBackendCandidate = BackendInstanceRecord & {
+    candidatePid: number;
+    command: string;
+};
+/**
+ * Reap only backend children whose supervisor identity is provably stale. A dead registry PID alone is not
+ * enough: the live process must carry the exact instance id and project root, run the backend entrypoint, and
+ * have been orphaned to PID 1. Ordinary launchers, shells, and app-server generations do not match.
+ */
+export declare function reapOrphanBackendInstances(root?: string): ProcBackendCandidate[];
 export declare function spawnDetachedRuntime(opts: {
     cwd: string;
     logFile: string;
@@ -19,3 +29,4 @@ export declare function spawnDetachedRuntime(opts: {
     args: string[];
     env?: NodeJS.ProcessEnv;
 }): ProcessIdentity;
+export {};

package/node_modules/@spexcode/spec-cli/dist/runtime-ownership.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { closeSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { repoRoot } from '@spexcode/spec-core';
 import { readJsonConfig, runtimeRoot } from '@spexcode/spec-core';
@@ -47,6 +47,84 @@ export function unregisterBackendInstance(instanceId, pid = process.pid) {
     }
     catch { /* not ours / already removed */ }
 }
+const procRows = () => {
+    try {
+        return readdirSync('/proc').filter((name) => /^\d+$/.test(name)).map(Number);
+    }
+    catch {
+        return [];
+    }
+};
+const procEnv = (pid) => {
+    try {
+        return Object.fromEntries(readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0').flatMap((entry) => {
+            const split = entry.indexOf('=');
+            return split > 0 ? [[entry.slice(0, split), entry.slice(split + 1)]] : [];
+        }));
+    }
+    catch {
+        return {};
+    }
+};
+const procCommand = (pid) => {
+    try {
+        return readFileSync(`/proc/${pid}/cmdline`, 'utf8').replaceAll('\0', ' ').trim();
+    }
+    catch {
+        return '';
+    }
+};
+const procParent = (pid) => {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        const close = stat.lastIndexOf(')');
+        const fields = stat.slice(close + 2).split(' ');
+        return Number(fields[1]) || null;
+    }
+    catch {
+        return null;
+    }
+};
+const isBackendCommand = (command) => /(?:^|\/)spec-cli\/(?:src\/index\.ts|dist\/index\.js)(?:\s|$)/.test(command);
+/**
+ * Reap only backend children whose supervisor identity is provably stale. A dead registry PID alone is not
+ * enough: the live process must carry the exact instance id and project root, run the backend entrypoint, and
+ * have been orphaned to PID 1. Ordinary launchers, shells, and app-server generations do not match.
+ */
+export function reapOrphanBackendInstances(root = repoRoot()) {
+    const records = readBackendInstanceRecords(root);
+    const liveCurrent = records.filter((record) => processStartToken(record.pid) === record.startToken);
+    const currentIds = new Set(liveCurrent.map((record) => record.instanceId));
+    const candidates = [];
+    for (const record of records) {
+        if (currentIds.has(record.instanceId))
+            continue;
+        if (processStartToken(record.pid) === record.startToken)
+            continue;
+        for (const pid of procRows()) {
+            const env = procEnv(pid);
+            if (env.SPEXCODE_INSTANCE_ID !== record.instanceId || env.SPEXCODE_PROJECT_ROOT !== root)
+                continue;
+            if (procParent(pid) !== 1)
+                continue;
+            const command = procCommand(pid);
+            if (!isBackendCommand(command))
+                continue;
+            candidates.push({ ...record, candidatePid: pid, command });
+        }
+    }
+    for (const candidate of candidates) {
+        try {
+            process.kill(candidate.candidatePid, 'SIGTERM');
+        }
+        catch { /* exact process already exited */ }
+        try {
+            rmSync(backendInstancePath(candidate.instanceId), { force: true });
+        }
+        catch { /* stale record is advisory */ }
+    }
+    return candidates;
+}
 export function spawnDetachedRuntime(opts) {
     mkdirSync(dirname(opts.logFile), { recursive: true });
     mkdirSync(dirname(opts.pidFile), { recursive: true });

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

@@ -0,0 +1,23 @@
+import { type CommittedSessionChange, type ProductionSessionApplication } from '@spexcode/session-application';
+type SessionApplicationCommitWake = (recipients: readonly string[]) => void;
+/** The application owns commit ordering; Spex supplies the adopter transport wake. */
+export declare function setSessionApplicationCommitWake(wake: SessionApplicationCommitWake): void;
+/** Allow the adopter to refresh its board stream after the canonical transaction commits. */
+export declare function setSessionApplicationCommitObserver(observer: (change: Pick<CommittedSessionChange, 'recipients'>) => void): void;
+/** The backend's sole session application composition. Path selection is shared with self-launch. */
+export declare function configuredSessionApplication(): ProductionSessionApplication;
+export type SessionApplicationCutoverState = 'ready' | 'residue' | 'fresh' | 'migration-required' | 'fenced' | 'ambiguous';
+/** Inspect cutover state without initializing a fresh database as a side effect of a rejected request. */
+export declare function sessionApplicationCutoverState(): SessionApplicationCutoverState;
+/** Resolve the canonical application. A legacy tree is cut over at its first canonical access; runtime code
+ * never gets to choose between JSON and SQLite based on the caller or request path. */
+export declare function configuredSessionApplicationIfCutover(): ProductionSessionApplication | undefined;
+/** Initialize a fresh canonical store only after an accepted create has crossed its no-side-effect boundary. */
+export declare function initializeFreshSessionApplication(): ProductionSessionApplication;
+export declare function acquireFreshSessionApplicationForCreate(): {
+    application: ProductionSessionApplication;
+    owned: boolean;
+};
+export declare function releaseFreshSessionApplicationForCreate(owned: boolean, committed: boolean): void;
+export declare function resetConfiguredSessionApplicationForTest(): void;
+export {};

package/node_modules/@spexcode/spec-cli/dist/session-application.js

@@ -0,0 +1,189 @@
+import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { openProjectSessionApplication, legacyResidueExists, migrateJsonSessionRecords, } from '@spexcode/session-application';
+import { requireLocalDatabasePath, resolveDatabasePath } from '@spexcode/session-selflaunch';
+import { runtimeRoot } from '@spexcode/spec-core';
+import { jsonMigrationFencePath } from '@spexcode/session-application';
+let cached;
+let cachedPath;
+let freshStoreOwned = false;
+let freshStoreCommitted = false;
+let freshStoreLeases = 0;
+let commitWake = () => { };
+let commitObserver;
+/** The application owns commit ordering; Spex supplies the adopter transport wake. */
+export function setSessionApplicationCommitWake(wake) {
+    commitWake = wake;
+}
+/** Allow the adopter to refresh its board stream after the canonical transaction commits. */
+export function setSessionApplicationCommitObserver(observer) {
+    commitObserver = observer;
+}
+/** The backend's sole session application composition. Path selection is shared with self-launch. */
+export function configuredSessionApplication() {
+    const databasePath = resolveDatabasePath();
+    if (cached !== undefined && cachedPath === databasePath)
+        return cached;
+    if (cached !== undefined)
+        cached.close();
+    cached = openProjectSessionApplication({
+        databasePath,
+        locality: path => { requireLocalDatabasePath(path); },
+        onCommitted: result => {
+            commitWake(result.recipients);
+            if (commitObserver)
+                setImmediate(() => commitObserver?.(result));
+        },
+        onRuntimeBound: sessionId => commitWake([sessionId]),
+    });
+    cachedPath = databasePath;
+    return cached;
+}
+// A marked store is `ready` only once its legacy tree holds nothing left to absorb. The scan runs once per process
+// per store: after residue is migrated (or none was found) no legacy writer exists to create more, so later calls
+// answer from memory instead of walking every session directory on the hot path.
+const settledResidueStores = new Set();
+/** Inspect cutover state without initializing a fresh database as a side effect of a rejected request. */
+export function sessionApplicationCutoverState() {
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    const storeKey = `${databasePath}\0${recordsRoot}`;
+    if (existsSync(`${databasePath}.json-migration.json`)) {
+        if (settledResidueStores.has(storeKey))
+            return 'ready';
+        if (legacyResidueExists(recordsRoot))
+            return 'residue';
+        settledResidueStores.add(storeKey);
+        return 'ready';
+    }
+    if (existsSync(jsonMigrationFencePath(recordsRoot)))
+        return 'fenced';
+    if (existsSync(recordsRoot) && readdirSync(recordsRoot, { withFileTypes: true }).some(entry => entry.isDirectory()))
+        return 'migration-required';
+    if (existsSync(databasePath))
+        return 'ambiguous';
+    return 'fresh';
+}
+/** Resolve the canonical application. A legacy tree is cut over at its first canonical access; runtime code
+ * never gets to choose between JSON and SQLite based on the caller or request path. */
+export function configuredSessionApplicationIfCutover() {
+    const state = sessionApplicationCutoverState();
+    if (state === 'ready')
+        return configuredSessionApplication();
+    if (state === 'migration-required' || state === 'residue')
+        return initializeMigratedSessionApplication(state);
+    if (state === 'fresh')
+        return initializeFreshSessionApplication();
+    if (state === 'fenced' || state === 'ambiguous') {
+        throw new Error(`session application cutover is ${state}; refusing a legacy/runtime split`);
+    }
+    return undefined;
+}
+// One importer for both shapes of legacy tree. Before the marker it installs the canonical store; after the
+// marker it absorbs whatever residue the tree still holds into the store this process already owns, then
+// retires the tree. Either way the tree is gone when this returns, so the cutover state settles to `ready`.
+function initializeMigratedSessionApplication(state) {
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    const locality = (path) => { requireLocalDatabasePath(path); };
+    if (state === 'migration-required') {
+        migrateJsonSessionRecords({ databasePath, recordsRoot, locality });
+        return configuredSessionApplication();
+    }
+    const application = configuredSessionApplication();
+    const report = migrateJsonSessionRecords({ databasePath, recordsRoot, locality, application });
+    settledResidueStores.add(`${databasePath}\0${recordsRoot}`);
+    const residue = report.residue;
+    if (residue) {
+        console.log(`[session-application] migrated legacy residue from ${recordsRoot}: ${residue.records} record(s), ${residue.events} event(s), ${residue.parentEdges} parent edge(s), ${residue.watchEdges} watch edge(s), ${residue.pending} pending; ${residue.unclaimed.length} unclaimed dir(s)${residue.unclaimed.length ? ` (${residue.unclaimed.join(', ')})` : ''}; backup ${residue.backupRoot}`);
+    }
+    return application;
+}
+/** Initialize a fresh canonical store only after an accepted create has crossed its no-side-effect boundary. */
+export function initializeFreshSessionApplication() {
+    const state = sessionApplicationCutoverState();
+    if (state === 'ready')
+        return configuredSessionApplication();
+    if (state === 'residue')
+        return initializeMigratedSessionApplication(state);
+    if (state !== 'fresh')
+        throw new Error(`cannot initialize a fresh session store from cutover state: ${state}`);
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    migrateJsonSessionRecords({ databasePath, recordsRoot, locality: path => { requireLocalDatabasePath(path); } });
+    return configuredSessionApplication();
+}
+export function acquireFreshSessionApplicationForCreate() {
+    const state = sessionApplicationCutoverState();
+    if (state === 'fresh') {
+        const application = initializeFreshSessionApplication();
+        freshStoreOwned = true;
+        freshStoreCommitted = false;
+        freshStoreLeases++;
+        return { application, owned: true };
+    }
+    if (state === 'ready' && freshStoreOwned && !freshStoreCommitted) {
+        freshStoreLeases++;
+        return { application: configuredSessionApplication(), owned: true };
+    }
+    if (state === 'residue')
+        return { application: initializeMigratedSessionApplication(state), owned: false };
+    if (state !== 'ready')
+        throw new Error(`cannot initialize a session store from cutover state: ${state}`);
+    return { application: configuredSessionApplication(), owned: false };
+}
+export function releaseFreshSessionApplicationForCreate(owned, committed) {
+    if (!owned)
+        return;
+    if (committed)
+        freshStoreCommitted = true;
+    freshStoreLeases = Math.max(0, freshStoreLeases - 1);
+    if (freshStoreLeases !== 0)
+        return;
+    if (freshStoreCommitted) {
+        try {
+            unlinkSync(jsonMigrationFencePath(join(runtimeRoot(), 'sessions')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        return;
+    }
+    const application = cached;
+    const rows = application?.protocol.withTransaction(tx => Number(tx.query('SELECT COUNT(*) AS count FROM session_application_state')[0]?.count ?? 0)) ?? 0;
+    if (rows !== 0) {
+        freshStoreCommitted = true;
+        try {
+            unlinkSync(jsonMigrationFencePath(join(runtimeRoot(), 'sessions')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        return;
+    }
+    application?.close();
+    cached = undefined;
+    const databasePath = resolveDatabasePath();
+    const recordsRoot = join(runtimeRoot(), 'sessions');
+    for (const path of [databasePath, `${databasePath}.json-migration.json`, jsonMigrationFencePath(recordsRoot)]) {
+        try {
+            unlinkSync(path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    rmSync(`${databasePath}.json-migration-backup`, { recursive: true, force: true });
+    freshStoreOwned = false;
+}
+export function resetConfiguredSessionApplicationForTest() {
+    cached?.close();
+    cached = undefined;
+    settledResidueStores.clear();
+    freshStoreOwned = false;
+    freshStoreCommitted = false;
+    freshStoreLeases = 0;
+}

package/node_modules/@spexcode/spec-cli/dist/session-declarations.js

@@ -27,7 +27,11 @@ export async function sessionStateKit(sessionId) {
     // the agent-authored state writers resolve WHICH session by id: a `--session <id>` flag (the lifecycle
     // hooks pass it, parsed from the payload, since they no longer have a cwd `.session`) wins, else the
     // harness env var (ownSessionId — the agent's own `spex session …` carries the harness session id).
-    const sess = sessionId;
+    // Hook payloads from Codex carry the native thread id, while the canonical
+    // application is keyed by the Spex session id. Resolve that alias once at
+    // the state-writer boundary; shell hooks stay transport-only and every
+    // lifecycle producer writes the same canonical record.
+    const sess = sessionId ? (l.readAliasedRawRecord(sessionId)?.session_id ?? sessionId) : undefined;
     // @@@ no-record diagnosis ([[state]]) - the session store resolves from the CURRENT directory (runtimeRoot
     // ← the cwd's git common dir), so the classic declaration failure is a cd OUTSIDE the session's project —
     // and a bare "no session record" told the author none of that (field-reported). Name the actual cause and
@@ -99,6 +103,14 @@ export async function runSessionDeclaration(verb, argv = process.argv) {
         if (proposal === 'nothing')
             nothingProposalTrap();
         const { s, sess, mark, noRecord, noteEcho } = await sessionStateKit(sessionId);
+        if (proposal === 'merge') {
+            const readiness = s.mergeReadiness('merge');
+            if (!readiness.ready) {
+                console.error(`review declaration refused: ${readiness.reason}`);
+                process.exitCode = 1;
+                return;
+            }
+        }
         let closeNote = proposal === 'close' ? CLOSE_CLEANUP : '';
         if (proposal === 'close') {
             // The closeout nudge is advisory: a declaration must land even if the local issue store fails.

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

@@ -6,6 +6,12 @@ type SessionFileLock = <T>(id: string, body: () => T) => T;
 export declare const SESSION_FILE_PREVIEW_MAX_BYTES: number;
 export type SessionFilePreviewKind = 'text' | 'image' | 'html';
 export declare function listSessionFiles(id: string): string[];
+export type SessionFileStatus = {
+    path: string;
+    valid: boolean;
+    reason?: string;
+};
+export declare function inspectSessionFiles(id: string): SessionFileStatus[];
 export declare function readSessionFiles(id: string): string[];
 export declare function addSessionFile(id: string, input: string, lock: SessionFileLock, cwd?: string): {
     path: string;