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

package/bin/spex.mjs

@@ -2,7 +2,8 @@
 // @@@ 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 { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
@@ -16,7 +17,19 @@ 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 buildTargets = [
+    ['packages/session-protocol', 'dist/index.js'],
+    ['packages/session-topology', 'dist/index.js'],
+    ['packages/session-runtime', 'dist/index.js'],
+    ['packages/session-events', 'dist/index.js'],
+    ['packages/session-application', 'dist/index.js'],
+    ['packages/session-selflaunch', 'dist/index.js'],
+    ['packages/spec-core', 'dist/index.js'],
+    ['spec-eval', 'dist/index.js'],
+    ['spec-forge', 'dist/index.js'],
+    ['spec-cli', 'dist/cli.js'],
+  ]
+  const srcRoots = buildTargets.map(([packagePath]) => join(pkg, '..', packagePath, 'src'))
   const conflicted = srcRoots.flatMap((root) => {
     if (!existsSync(root)) return []
     return readdirSync(root, { recursive: true })
@@ -34,33 +47,174 @@ if (existsSync(sourceRoot)) {
   }
 
   // @@@ source-workspace build ([[release-launcher]]) - the git hooks invoke this launcher straight from a
-  // checkout, where dist is intentionally untracked. Rebuild the complete runtime closure before linting
-  // candidate source; an installed package has no src tree and stays a pure Node -> dist execution path.
+  // checkout, where dist is intentionally untracked. Import main's fresh closure and rebuild only changed
+  // packages plus dependents before linting candidate source; an untrusted baseline falls back to the complete
+  // ordered driver. Every package still publishes its dist atomically. An installed package has no src tree
+  // and stays a pure Node -> dist execution path.
   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))
-      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 */ }
+  // 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 newestRuntimeSource = (root) => {
+    const roots = buildTargets.map(([packagePath]) => join(root, packagePath, 'src'))
+    return roots.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)
+  }
+  const newestPackageSource = (root, packagePath) => {
+    const source = join(root, packagePath, 'src')
+    if (!existsSync(source)) return 0
+    let newest = 0
+    const visit = (dir) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name)
+        if (entry.isDirectory()) visit(path)
+        else if (isRuntimeSource(path)) {
+          try { newest = Math.max(newest, statSync(path).mtimeMs) } catch { /* retry on the next launch */ }
+        }
+      }
     }
+    visit(source)
     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)
+  }
+  const entriesAreFresh = (root) => {
+    const newestSource = newestRuntimeSource(root)
+    return buildTargets.every(([packagePath, entry]) => {
+      try { return statSync(join(root, packagePath, entry)).mtimeMs >= newestSource } catch { return false }
+    })
+  }
+  const packageFingerprint = (root, packagePath) => {
+    const hash = createHash('sha256')
+    const packageRoot = join(root, packagePath)
+    const files = ['package.json', 'tsconfig.build.json'].map((name) => join(packageRoot, name)).filter(existsSync)
+    const visit = (dir, relative = '') => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name)
+        const child = relative ? `${relative}/${entry.name}` : entry.name
+        if (entry.isDirectory()) visit(path, child)
+        else if (isRuntimeSource(path)) files.push(path)
+      }
+    }
+    const source = join(packageRoot, 'src')
+    if (existsSync(source)) visit(source)
+    files.sort()
+    for (const path of files) hash.update(path.slice(packageRoot.length)).update('\0').update(readFileSync(path)).update('\0')
+    return hash.digest('hex')
+  }
+  const packageDependents = {
+    'packages/session-protocol': ['packages/session-topology', 'packages/session-runtime', 'packages/session-events', 'packages/session-application', 'packages/session-selflaunch', 'spec-cli'],
+    'packages/session-topology': ['packages/session-application', 'spec-cli'],
+    'packages/session-runtime': ['packages/session-application', 'packages/session-selflaunch', 'spec-cli'],
+    'packages/session-events': ['packages/session-application', 'spec-cli'],
+    'packages/session-application': ['spec-cli'],
+    'packages/session-selflaunch': ['spec-cli'],
+    'packages/spec-core': ['spec-eval', 'spec-forge', 'spec-cli'],
+    'spec-eval': ['spec-cli'],
+    'spec-forge': ['spec-cli'],
+    'spec-cli': [],
+  }
+  const changedBuildPackages = (root) => {
+    const changed = new Set(buildTargets
+      .map(([packagePath]) => packagePath)
+      .filter((packagePath) => packageFingerprint(workspace, packagePath) !== packageFingerprint(root, packagePath)))
+    for (const [packagePath, entry] of buildTargets) {
+      try {
+        if (statSync(join(root, packagePath, entry)).mtimeMs < newestPackageSource(workspace, packagePath)) changed.add(packagePath)
+      } catch { changed.add(packagePath) }
+    }
+    for (const packagePath of [...changed]) for (const dependent of packageDependents[packagePath]) changed.add(dependent)
+    return buildTargets.map(([packagePath]) => packagePath).filter((packagePath) => changed.has(packagePath))
+  }
+  const mainRoot = (() => {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: workspace, encoding: 'utf8' })
+    if (result.status !== 0) return null
+    const commonDir = result.stdout.trim()
+    return commonDir ? dirname(commonDir) : null
+  })()
+  const reusableMainBuild = () => mainRoot && mainRoot !== workspace && entriesAreFresh(mainRoot)
+  const importMainBuild = () => {
+    for (const [packagePath] of buildTargets) {
+      const source = join(mainRoot, packagePath, 'dist')
+      const target = join(workspace, packagePath, 'dist')
+      const temporary = `${target}.from-main-${process.pid}`
+      const previous = `${target}.from-main-previous-${process.pid}`
+      rmSync(temporary, { recursive: true, force: true })
+      rmSync(previous, { recursive: true, force: true })
+      cpSync(source, temporary, { recursive: true })
+      if (existsSync(target)) renameSync(target, previous)
+      renameSync(temporary, target)
+      rmSync(previous, { recursive: true, force: true })
+    }
+  }
+  const sourceIsStale = () => {
+    const newestSource = newestRuntimeSource(workspace)
+    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 {
+        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)
+      }
+    }
+    try {
+      if (sourceIsStale()) {
+        if (reusableMainBuild()) {
+          const changed = changedBuildPackages(mainRoot)
+          console.error(`spex: importing fresh runtime closure from main; rebuilding ${changed.length} package(s)`)
+          importMainBuild()
+          if (changed.length) {
+            const build = spawnSync(process.execPath, [join(workspace, 'scripts', 'build-workspaces.mjs'), ...changed], { cwd: workspace, stdio: 'inherit' })
+            if (build.error || build.status !== 0 || !existsSync(cli)) {
+              console.error('spex: source workspace selective build failed; fix it, then retry.')
+              process.exit(build.status ?? 1)
+            }
+          }
+        } else {
+          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/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
@@ -1804,6 +1831,25 @@ else if (cmd === 'internal') {
             process.exit(1);
         }
     }
+    else if (sub === 'codex-reopen') {
+        // A headless resume reloads its evicted thread into the shared app-server (thread/resume, no turn), so
+        // readiness — which proves online only for a RESIDENT thread — can see it. The visible TUI does this
+        // implicitly by attaching; headless has no TUI, so its launch.sh resume branch calls this.
+        const { codexReopenThread } = await import('./harness.js');
+        const sock = process.argv[4], tid = process.argv[5];
+        if (!sock || !tid) {
+            console.error('usage: spex internal codex-reopen <sock> <threadId>');
+            process.exit(2);
+        }
+        const r = await codexReopenThread(sock, tid);
+        if (r.ok) {
+            console.log('reopened');
+        }
+        else {
+            console.error(r.error);
+            process.exit(1);
+        }
+    }
     else if (sub === 'check-staged') {
         // the pre-commit hook's eval backstop: a staged stray evidence blob or malformed eval.md rejects the
         // commit. Logic lives in spec-eval; the hook shims here.
@@ -1845,6 +1891,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/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>;