spexcode 0.6.7 → 0.6.8

package/node_modules/@spexcode/session-topology/dist/schema.js

@@ -0,0 +1,27 @@
+export const TOPOLOGY_MIGRATION_SQL = `
+CREATE TABLE topology_edges (
+  edge_id          TEXT    NOT NULL PRIMARY KEY,
+  from_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  to_session_id    TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  relation_type    TEXT    NOT NULL,
+  created_at_ms    INTEGER NOT NULL,
+  removed_at_ms    INTEGER,
+  CHECK (length(edge_id) = 32 AND edge_id NOT GLOB '*[^0-9a-f]*'),
+  CHECK (from_session_id <> to_session_id),
+  CHECK (length(relation_type) BETWEEN 1 AND 64),
+  CHECK (relation_type NOT GLOB '*[^0-9A-Za-z._:-]*'),
+  CHECK (created_at_ms >= 0),
+  CHECK (removed_at_ms IS NULL OR removed_at_ms >= 0)
+) STRICT;
+
+CREATE UNIQUE INDEX topology_active_edge
+  ON topology_edges (from_session_id, to_session_id, relation_type)
+  WHERE removed_at_ms IS NULL;
+
+CREATE INDEX topology_active_to
+  ON topology_edges (to_session_id, relation_type, from_session_id)
+  WHERE removed_at_ms IS NULL;
+`;
+export const TOPOLOGY_MIGRATIONS = [
+    { version: 1, sql: TOPOLOGY_MIGRATION_SQL },
+];

package/node_modules/@spexcode/session-topology/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@spexcode/session-topology",
+  "version": "0.6.8",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "A neutral SQLite relation model for session addresses.",
+  "files": ["dist"],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": { "@spexcode/session-protocol": "0.6.8" },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/spec-cli/bin/spex.mjs

@@ -2,7 +2,7 @@
 // @@@ spex launcher ([[release-launcher]]) - package installs execute the package's compiled CLI directly;
 // tsx remains a development tool and never enters an adopter's runtime closure.
 import { spawn, spawnSync } from 'node:child_process'
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
@@ -16,7 +16,7 @@ const workspace = join(pkg, '..')
 // carry unresolved conflict markers, so hooks keep the retryable exit-75 contract during a merge.
 const sourceRoot = join(pkg, 'src')
 if (existsSync(sourceRoot)) {
-  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'packages', 'session-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
   const conflicted = srcRoots.flatMap((root) => {
     if (!existsSync(root)) return []
     return readdirSync(root, { recursive: true })
@@ -39,28 +39,65 @@ if (existsSync(sourceRoot)) {
   const runtimeEntries = [
     cli,
     join(workspace, 'packages', 'spec-core', 'dist', 'index.js'),
-    join(workspace, 'packages', 'session-core', 'dist', 'index.js'),
     join(workspace, 'spec-eval', 'dist', 'index.js'),
     join(workspace, 'spec-forge', 'dist', 'index.js'),
   ]
-  const newestSource = srcRoots.reduce((newest, root) => {
-    if (!existsSync(root)) return newest
-    for (const entry of readdirSync(root, { recursive: true })) {
-      const path = join(root, String(entry))
+  // Tests and declaration files are typecheck inputs, not runtime build inputs. Counting them here makes a
+  // harmless test edit look like a stale CLI and rebuilds every workspace on the next hook invocation.
+  const isRuntimeSource = (path) => {
+    return /\.(ts|tsx|js|mjs)$/.test(path)
+      && !/\.d\.ts$/.test(path)
+      && !/(^|[./])[^/]+\.test\.(ts|tsx|js|mjs)$/.test(path)
+  }
+  const sourceIsStale = () => {
+    const newestSource = srcRoots.reduce((newest, root) => {
+      if (!existsSync(root)) return newest
+      for (const entry of readdirSync(root, { recursive: true })) {
+        const path = join(root, String(entry))
+        try {
+          if (isRuntimeSource(path)) newest = Math.max(newest, statSync(path).mtimeMs)
+        } catch { /* a concurrent source edit can only make the next invocation rebuild again */ }
+      }
+      return newest
+    }, 0)
+    return runtimeEntries.some((entry) => {
+      try { return statSync(entry).mtimeMs < newestSource } catch { return true }
+    })
+  }
+  if (sourceIsStale()) {
+    // A hook, poller, and human shell can all invoke spex at once. The lock is deliberately at the
+    // launcher boundary: only one process pays the full workspace build, and waiters re-check freshness
+    // after the owner exits. A dead owner is recoverable; a live build gets two minutes before it is stale.
+    const buildLock = join(workspace, '.spex-build.lock')
+    const wait = new Int32Array(new SharedArrayBuffer(4))
+    const deadline = Date.now() + 120_000
+    let owner = false
+    while (!owner) {
       try {
-        if (/\.(ts|tsx|js|mjs)$/.test(path)) newest = Math.max(newest, statSync(path).mtimeMs)
-      } catch { /* a concurrent source edit can only make the next invocation rebuild again */ }
+        mkdirSync(buildLock)
+        owner = true
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        try {
+          if (Date.now() - statSync(buildLock).mtimeMs > 120_000) rmSync(buildLock, { recursive: true, force: true })
+        } catch { /* the owner may have completed between the stat and the next check */ }
+        if (Date.now() >= deadline) {
+          console.error('spex: source workspace build lock did not clear; remove .spex-build.lock after confirming no build is running.')
+          process.exit(75)
+        }
+        Atomics.wait(wait, 0, 0, 100)
+      }
     }
-    return newest
-  }, 0)
-  const rebuild = runtimeEntries.some((entry) => {
-    try { return statSync(entry).mtimeMs < newestSource } catch { return true }
-  })
-  if (rebuild) {
-    const build = spawnSync('npm', ['run', 'build'], { cwd: workspace, stdio: 'inherit' })
-    if (build.error || build.status !== 0 || !existsSync(cli)) {
-      console.error('spex: source workspace build failed; fix it, then retry.')
-      process.exit(build.status ?? 1)
+    try {
+      if (sourceIsStale()) {
+        const build = spawnSync('npm', ['run', 'build'], { cwd: workspace, stdio: 'inherit' })
+        if (build.error || build.status !== 0 || !existsSync(cli)) {
+          console.error('spex: source workspace build failed; fix it, then retry.')
+          process.exit(build.status ?? 1)
+        }
+      }
+    } finally {
+      rmSync(buildLock, { recursive: true, force: true })
     }
   }
 }

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

@@ -67,7 +67,7 @@ async function assertDaemonDependencies(command) {
 // (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', 'GitWorkspaceError'].includes(e.name))
+    if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError', 'DashboardAssetError', 'GitWorkspaceError', 'SessionFileError'].includes(e.name))
         console.error(`spex: ${e.message}`);
     else
         console.error(e);
@@ -96,7 +96,7 @@ 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 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', '--candidate', '--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}`))
@@ -213,6 +213,8 @@ function parseSessionSendArgs(args) {
     }
     if (positionals.length !== 2)
         sessionSendUsage('plain send requires exactly one selector and one message');
+    if (!positionals[1].trim())
+        sessionSendUsage('message must not be empty or whitespace');
     return { selector: positionals[0], kind: 'text', text: positionals[1], ...(values.has('--ssh') ? { sshAddress: values.get('--ssh') } : {}) };
 }
 const FULL_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -339,6 +341,7 @@ async function followKit(selectors, verb) {
     const { localCachedSessions } = await import('./client.js');
     const { fromRaw, ownSessionId, selectSessions, toSession } = await import('./sessions.js');
     const { listSessionIds, readPublicRecordEntry } = await import('@spexcode/spec-core');
+    const { configuredSessionApplicationIfCutover, sessionApplicationCutoverState } = await import('./session-application.js');
     const real = selectors.filter((sel) => sel && sel !== '@all');
     let picked = [];
     if (real.length) {
@@ -353,9 +356,38 @@ async function followKit(selectors, verb) {
     // a fresh sample of the mutable record — that resample is what made the old poll lose moves.
     const row = (id, status, note) => {
         const entry = readPublicRecordEntry(id);
-        if (entry.kind !== 'ok')
+        if (entry.kind === 'ok')
+            return { ...toSession(fromRaw(entry.raw), status, 'unknown'), note };
+        const cutover = sessionApplicationCutoverState();
+        const state = cutover === 'fresh' ? null : configuredSessionApplicationIfCutover()?.readState(id);
+        if (!state)
             return null;
-        return { ...toSession(fromRaw(entry.raw), status, 'unknown'), note };
+        return {
+            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: state.status,
+            proposal: state.proposal,
+            merges: 0,
+            status,
+            liveness: 'unknown',
+            note,
+            archived: state.status === 'archived',
+            closedAt: null,
+            prompt: null,
+            promptPreview: null,
+            created: state.updatedAtMs,
+            activity: null,
+            sortKey: null,
+        };
     };
     const watcher = ownSessionId();
     return { watcher, follow: (emit, opts) => followSessions(emit, { ...opts, targets, self: watcher, row }) };
@@ -1062,9 +1094,9 @@ else if (cmd === 'session') {
         // the board comes from the backend (so it shows the sessions of whatever SPEXCODE_API_URL points at,
         // incl. a remote machine); selectSessions/formatTable are pure presentation, applied client-side.
         const { ownSessionId, resolveSession, selectChildren, selectSessions, formatTable } = await import('./sessions.js');
-        const { clientListSessions, clientListSessionsThroughPeer, clientSessionClosure } = await import('./client.js');
-        // 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 { clientListSessions, clientListSessionsThroughPeer } = await import('./client.js');
+        // The backend's default projection excludes closed records. --all and an explicit selector request the
+        // retained record projection so an operator can inspect or resume one deliberately.
         const selectors = positionals(4);
         rejectUnknownBackendFlags('spex session ls', 4, ['status', 'all', 'json', 'ssh', 'children'], ['children']);
         const peerAnchor = parseSessionPeerAnchor('ls', selectors);
@@ -1117,19 +1149,10 @@ else if (cmd === 'session') {
         const selected = selectSessions(scoped, peerAnchor ? [] : selectors);
         const picked = flag('status') ? selected.filter((session) => flag('status').split(',').includes(session.status)) : selected;
         if (!peerAnchor && children === undefined && selectors.length === 1 && !selected.length && idLikeSelector(selectors[0])) {
-            const closure = await clientSessionClosure(selectors[0]);
-            if (closure) {
-                const result = { id: closure.id, status: 'closed', closedAt: closure.closedAt };
-                console.log(has('json') ? JSON.stringify([result], null, 2) : `${closure.id.slice(0, 8)}: closed at ${closure.closedAt}`);
-            }
-            else {
-                console.error(`spex session ls: ${selectors[0]} was not found in this project's live, archive, or terminal-close history`);
-                process.exit(2);
-            }
-        }
-        else {
-            console.log(has('json') ? JSON.stringify(picked, null, 2) : formatTable(picked, true, scope));
+            console.error(`spex session ls: ${selectors[0]} was not found in this project's session records`);
+            process.exit(2);
         }
+        console.log(has('json') ? JSON.stringify(picked, null, 2) : formatTable(picked, true, scope));
     }
     else if (sub === 'resources') {
         rejectUnknownBackendFlags('spex session resources', 4, ['json']);
@@ -1155,8 +1178,8 @@ else if (cmd === 'session') {
         }
         const files = await import('./session-files.js');
         if (verb === 'ls') {
-            for (const file of files.listSessionFiles(id))
-                console.log(file);
+            for (const file of files.inspectSessionFiles(id))
+                console.log(file.valid ? file.path : `INVALID ${file.path} — ${file.reason}`);
         }
         else if (verb === 'add') {
             const result = files.addSessionFile(id, path, withSessionRecordLockSync);
@@ -1389,14 +1412,6 @@ else if (cmd === 'session') {
             console.log(r.ok ? `interrupted ${full}` : `interrupt failed: ${r.error}`);
             process.exit(r.ok ? 0 : 1);
         }
-        else if (sub === 'archive' || sub === 'unarchive') {
-            // ARCHIVING/legacy unarchive ([[archive]]) — archive exact-stops before filing; unarchive signposts to
-            // resume and recreates the same conversation.
-            const on = sub === 'archive';
-            const full = await resolveSelectorOrExit(id);
-            const ok = await c.clientArchive(full, on);
-            console.log(!ok ? `no such session ${full}` : `${on ? 'archived' : 'resumed'} ${full}`);
-        }
         else if (sub === 'close') {
             const full = targetArgs?.sshAddress
                 ? (FULL_SESSION_ID.test(id ?? '') ? id : sessionTargetUsage('close', '--ssh requires a full session id, not a selector'))
@@ -1688,47 +1703,59 @@ else if (cmd === 'internal') {
         // 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 { stageHarnessLaunchProof } = await import('./sessions.js');
+        const { existingHarnessLaunchTarget, stageHarnessLaunchProof } = await import('./sessions.js');
         const sock = process.argv[4], cwd = process.argv[5];
         const prompt = process.argv.slice(6).join(' ');
         if (!sock || !cwd) {
             console.error('usage: spex internal codex-launch <sock> <cwd> [prompt...]');
             process.exit(2);
         }
-        // On the bypass-trust path (the codex install supports the flag → materialize skipped writeCodexTrust's hash),
-        // the thread the BACKEND owns must carry `bypass_hook_trust` in thread/start's config so the app-server fires
-        // the worktree's local hooks — mirror materialize's capability decision so the two stay in lockstep.
-        const launcherCmd = process.env.SPEXCODE_CODEX_CMD || 'codex';
-        const bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(launcherCmd));
-        // The governed record id rides into the thread's own shell environment (shell_environment_policy.set), so
-        // every command this thread spawns knows which session it is — the codex equivalent of the launch-injected
-        // id claude gets. codex-launch is exactly where both ids are known ([[harness-adapter]]).
-        const ownId = process.env.SPEXCODE_SESSION_ID?.trim();
-        const r = await codexStartThread(sock, cwd, bypassHookTrust, ownId ? { SPEXCODE_SESSION_ID: ownId } : undefined, codexLauncherThreadPolicy(launcherCmd));
-        if (!r.ok) {
-            console.error(r.error);
-            process.exit(1);
+        const sid = process.env.SPEXCODE_SESSION_ID;
+        // The visible TUI can fail after codex-launch has already staged the native id and first-turn proof
+        // (for example, a remote-workspace validation error). The bounded shell retry re-enters this command;
+        // reuse the proven target instead of minting a second thread or asking stageHarnessLaunchProof to consume
+        // a payload that the lifecycle owner may already have committed.
+        const existingTarget = sid ? existingHarnessLaunchTarget(sid) : null;
+        if (existingTarget) {
+            console.log(existingTarget);
         }
-        if (prompt) {
-            const t = await codexTurn(sock, r.threadId, prompt, cwd);
-            if (!t.ok) {
-                console.error(t.error);
+        else {
+            // On the bypass-trust path (the codex install supports the flag → materialize skipped writeCodexTrust's hash),
+            // the thread the BACKEND owns must carry `bypass_hook_trust` in thread/start's config so the app-server fires
+            // the worktree's local hooks — mirror materialize's capability decision so the two stay in lockstep.
+            const launcherCmd = process.env.SPEXCODE_CODEX_CMD || 'codex';
+            const bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(launcherCmd));
+            // The governed record id rides into the thread's own shell environment (shell_environment_policy.set), so
+            // every command this thread spawns knows which session it is — the codex equivalent of the launch-injected
+            // id claude gets. codex-launch is exactly where both ids are known ([[harness-adapter]]).
+            const ownId = process.env.SPEXCODE_SESSION_ID?.trim();
+            const { withCodexGenerationMutex } = await import('./codex-runtime-generations.js');
+            const { runtimeRoot: projectRuntimeRoot } = await import('@spexcode/spec-core');
+            const r = await withCodexGenerationMutex(projectRuntimeRoot(cwd), () => codexStartThread(sock, cwd, bypassHookTrust, ownId ? { SPEXCODE_SESSION_ID: ownId } : undefined, codexLauncherThreadPolicy(launcherCmd)));
+            if (!r.ok) {
+                console.error(r.error);
                 process.exit(1);
             }
-            // The visible TUI resumes this thread from its ON-DISK rollout; a freshly-spawned app-server acks the turn
-            // but persists the rollout a few seconds LATE (verified live: the SAME thread's file lands at ~2-4s, not
-            // lost). WAIT for it to land BEFORE storing the id / printing it, else FAIL LOUD — never store a
-            // non-resumable harness_session_id (that permanently wedges every reopen). The 15s budget exceeds launch.sh's
-            // fast-fail threshold, so a real failure exits past it and the retry loop won't spray duplicate-prompt threads.
-            if (!await waitForCodexRollout(r.threadId, 20000)) {
-                console.error(`codex thread ${r.threadId} started but persisted no rollout within 20s — app-server not ready; not storing a non-resumable id`);
-                process.exit(1);
+            if (prompt) {
+                const t = await codexTurn(sock, r.threadId, prompt, cwd);
+                if (!t.ok) {
+                    console.error(t.error);
+                    process.exit(1);
+                }
+                // The visible TUI resumes this thread from its ON-DISK rollout; a freshly-spawned app-server acks the turn
+                // but persists the rollout a few seconds LATE (verified live: the SAME thread's file lands at ~2-4s, not
+                // lost). WAIT for it to land BEFORE storing the id / printing it, else FAIL LOUD — never store a
+                // non-resumable harness_session_id (that permanently wedges every reopen). The 15s budget exceeds launch.sh's
+                // fast-fail threshold, so a real failure exits past it and the retry loop won't spray duplicate-prompt threads.
+                if (!await waitForCodexRollout(r.threadId, 20000)) {
+                    console.error(`codex thread ${r.threadId} started but persisted no rollout within 20s — app-server not ready; not storing a non-resumable id`);
+                    process.exit(1);
+                }
             }
+            if (sid)
+                stageHarnessLaunchProof(sid, r.threadId, prompt);
+            console.log(r.threadId);
         }
-        const sid = process.env.SPEXCODE_SESSION_ID;
-        if (sid)
-            stageHarnessLaunchProof(sid, r.threadId, prompt);
-        console.log(r.threadId);
     }
     else if (sub === 'opencode-capture') {
         // opencode MINTS its own session id (no launch flag pins it), so the generated plugin's FIRST event calls
@@ -1845,6 +1872,22 @@ else if (cmd === 'internal') {
         const idled = mark(() => s.markIdle(sess));
         console.log(idled.ok ? 'idle' : idled.reason ?? 'noop (no session record, or not active)');
     }
+    else if (sub === 'session-hook-state') {
+        // Stop/idle/failure hooks are thin CLI shims. They may use the envelope for governed identity, but
+        // lifecycle claims must come from the canonical session application after the JSON cutover.
+        const id = flag('session');
+        if (!id) {
+            console.error('usage: spex internal session-hook-state --session <id>');
+            process.exit(2);
+        }
+        const { sessionHookState } = await import('./sessions.js');
+        const state = sessionHookState(id);
+        if (!state)
+            process.exit(1);
+        // Tab-separated fields are deliberately closed vocabulary: governed, lifecycle, proposal. Notes are
+        // not needed by the hook and must not become shell-parsed input.
+        console.log([state.governed ? '1' : '0', state.status, state.proposal ?? ''].join('\t'));
+    }
     else if (sub === 'commit-gate') {
         // the Stop gate's deterministic commit check (from cwd = the worktree): exit 0 if the node branch is
         // ready to declare done, else print the reason and exit 1. Takes the PROPOSAL being judged — `merge`

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

@@ -1,6 +1,6 @@
 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';
+import { type Session, type Resolved, type DispatchResult } from './sessions.js';
 export declare class BackendError extends Error {
     readonly status?: number | undefined;
     readonly transport?: unknown | undefined;
@@ -9,7 +9,6 @@ export declare class BackendError extends Error {
 export declare function backendConnectionRefused(error: unknown): boolean;
 export declare function localCachedSessions(includeArchived?: boolean): Session[];
 export declare function clientListSessions(includeArchived?: boolean): Promise<Session[]>;
-export declare function clientSessionClosure(selector: string): Promise<SessionClosure | null>;
 export declare function clientResources(): Promise<import('./host-resources.js').ResourceReport>;
 export declare function resolveClientSession(selector: string, includeArchived?: boolean): Promise<Resolved>;
 export type CaptureResult = {
@@ -94,7 +93,6 @@ export declare function clientRestoreQuarantine(id: string): Promise<{
     sha256: string;
     observedAt: string;
 }>;
-export declare function clientArchive(id: string, on?: boolean): Promise<boolean>;
 export declare function clientRename(id: string, name: string): Promise<boolean>;
 export declare function clientReparent(children: string[], parent: string | null): Promise<import('./sessions.js').SessionReparentResult>;
 export declare function clientSendRawKeys(id: string, keys: string[]): Promise<boolean>;

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