spexcode 0.5.1 → 0.5.3

package/spec-cli/src/cli.ts

@@ -20,7 +20,8 @@ const cmd = process.argv[2]
 // (loadConfig on a malformed spexcode.json) surfaces as uncaughtException, not unhandledRejection, so BOTH
 // paths route through the same printer.
 function fatal(e: unknown): never {
-  if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError'].includes(e.name)) console.error(`spex: ${e.message}`)
+  if (e instanceof Error && e.name === 'SessionMaintenanceError') console.error(`spex: ${(e as Error & { code?: string }).code ?? 'maintenance_error'}: ${e.message}`)
+  else if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError'].includes(e.name)) console.error(`spex: ${e.message}`)
   else console.error(e)
   process.exit(1)
 }
@@ -49,7 +50,7 @@ function flushExit(code = 0): Promise<never> {
 }
 const has = (name: string) => 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', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys'])
+const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys', '--allow-stop', '--allow-resume', '--ttl-ms', '--wait-ms'])
 function positionals(from: number): string[] {
   const out: string[] = []
   for (let i = from; i < process.argv.length; i++) {
@@ -126,25 +127,6 @@ function signpost(oldSpelling: string, newSpelling: string): never {
 }
 if (cmd !== undefined && SIGNPOSTS[cmd]) signpost(`spex ${cmd}`, SIGNPOSTS[cmd])
 
-// After a successful launch, nudge the caller to actually MONITOR the session — launch-then-forget is a real
-// gap (a supervisor or human launches and then never watches, so a review/failure goes unnoticed). Goes to
-// STDERR so the JSON on stdout (which callers parse) stays clean; keyed to whoever's calling — a supervising
-// agent has an own-session id, a human at a terminal does not. The hint also names the COMM channel
-// (`spex session send`) — field-tested gap: callers who couldn't find it reached for raw tmux keystrokes instead.
-async function launchMonitorReminder(id: string): Promise<void> {
-  const { ownSessionId } = await import('./sessions.js')
-  const agent = ownSessionId()
-  console.error(`\nspex: launched session ${id} — now MONITOR it, or its review/failure goes unnoticed:`)
-  if (agent) {
-    // a supervising agent: the per-worker monitor is a backgrounded `spex session wait`, which is edge-triggered.
-    console.error(`  supervising agent → background \`spex session wait ${id}\` (edge-triggered: exits when it OBSERVES the session transition into an actionable status — also how you await a dispatched merge actually landing; its exit is your wake-up. Already actionable and you just want to read it? \`spex session ls\`)`)
-    console.error(`  or watch the whole stream: \`spex session watch\``)
-  } else {
-    console.error(`  \`spex session watch\` — the live stream of actionable session transitions (or \`spex session wait ${id}\` to sleep until this one's next transition into actionable)`)
-  }
-  console.error(`  talk to it: \`spex session send ${id} "<msg>"\` — plain text; \`send --keys\` is a LAST RESORT (unstable raw TUI keys — only when a text send provably can't land)`)
-}
-
 const greeted = new Set<string>()
 async function greetWatchTargets(watcher: string, selectors: string[]): Promise<void> {
   try {
@@ -216,8 +198,9 @@ async function evalExport(id: string): Promise<never> {
   process.exit(0)
 }
 
-// appended to a done/ask/block declaration: states (not commands) that the next tool call's mark-active hook re-flips the global record to active, so a re-read won't show this.
-const DECLARED = ' — recorded; the human sees it in the dashboard. This state lives in your session\'s global record; your next tool call flips that record back to active (the mark-active hook, by design), so it is normal for this declaration not to persist.'
+// appended to a done/ask/block declaration: the note is durable conversation history even though the
+// CURRENT board projection correctly flips back to active on the next tool call.
+const DECLARED = ' — recorded; the human sees it in the dashboard. This declaration remains in the session timeline; your next tool call flips only the current graph state back to active (the mark-active hook, by design).'
 // appended ONLY to a propose-close declaration: a worktree about to be discarded may still own ephemeral things the agent started to test this change; nudge (not gate) it to reclaim them before the worktree goes, keyed on whether the thing should outlive the task — never on who started it (a deliberately long-running service / a production build is started-by-you yet must be left alone). Project-agnostic on purpose.
 const CLOSE_CLEANUP = '\n\nBefore this worktree closes, check whether you left anything running that you started to test this change — a background process, a dev or preview server, a bound port, a scratch session. If nothing depends on it anymore, shut it down, or it keeps running as an orphan. Leave anything meant to keep running: a service you deliberately stood up, a production build, anything other work relies on. What matters is whether it still needs to exist after this task, not whether you started it. If unsure, leave it. This is a reminder to check, not a required step.'
 
@@ -249,9 +232,16 @@ async function stateKit() {
   }
   // a state writer from a non-repo cwd throws git's not-a-repo before it can return false — map exactly
   // that throw to the no-record path (noRecord re-probes and names the cwd); anything else stays loud.
-  const mark = (fn: () => boolean): boolean => {
-    try { return fn() }
-    catch (e) { if (/not a git repository/i.test(String((e as any)?.stderr ?? e))) return false; throw e }
+  // A record that exists but CANNOT carry state (unreadable bytes, or a worktree that is gone) is its own
+  // answer: the writer refused on purpose and already knows why, so that reason is what the caller prints —
+  // never the no-record diagnosis, which would send the author chasing a wrong cwd ([[sessions-core]]).
+  const mark = (fn: () => boolean): { ok: boolean; reason?: string } => {
+    try { return { ok: fn() } }
+    catch (e) {
+      if (e instanceof s.SessionRecordUnusable) return { ok: false, reason: e.message }
+      if (/not a git repository/i.test(String((e as any)?.stderr ?? e))) return { ok: false }
+      throw e
+    }
   }
   // truncation transparency ([[state]]): the session table shows only the first NOTE_BOARD_LIMIT chars of a
   // note. When a declared note overflows that cap, the confirmation says so — length, what the board shows,
@@ -277,12 +267,12 @@ async function stateKit() {
 
 // a trailing --help/-h prints help and exits BEFORE any verb runs, so a help probe never fires a
 // streaming/mutating command. It prints THAT command's usage when an entry exists (the second layer
-// of the help journey — see help.ts): a drawer sub's probe (`spex session send --help`) answers with the
-// drawer's entry. Unknown tokens fall back to the map. (Removed spellings never reach here — the signpost
-// table above already exited.)
+// of the help journey — see help.ts); session noun-verb probes project the exact verb from the shared
+// drawer definition. Unknown tokens preserve the existing drawer/map fallback. (Removed spellings never
+// reach here — the signpost table above already exited.)
 if (cmd && cmd !== 'help' && (has('help') || process.argv.includes('-h'))) {
   const { commandHelp, overviewHelp } = await import('./help.js')
-  console.log(commandHelp(cmd) ?? overviewHelp())
+  console.log(commandHelp(cmd, cmd === 'session' ? process.argv[3] : undefined) ?? overviewHelp())
   process.exit(0)
 }
 
@@ -454,14 +444,21 @@ if (cmd === 'serve') {
       console.log(`${rel} is governed whole-file by ${whole.length} specs (all claims: ${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
     }
   } else if (sub === 'lint') {
-    const { specLint, DRIFT_GUIDANCE } = await import('./lint.js')
-    const findings = await specLint()
+    const { specLint, pendingTouchesGoverned, DRIFT_GUIDANCE } = await import('./lint.js')
+    const pending = flag('pending')
+    if (pending && process.env.SPEXCODE_GATE_SCOPE_ONLY === '1') {
+      const touches = await pendingTouchesGoverned(process.cwd(), pending)
+      if (!touches) process.exit(76)
+    }
+    const findings = await specLint(undefined, undefined, {
+      tip: pending || 'HEAD',
+    })
     const errors = findings.filter((f) => f.level === 'error')
     for (const f of findings) console.error(`  ${f.level === 'error' ? '✗' : '•'} ${f.rule}: ${f.msg}`)
     console.error(`spex spec lint: ${errors.length} error(s), ${findings.length - errors.length} warning(s)`)
     // drift teaches from the ONE `spex spec lint` (no flag). Unanchored drift stays advisory forever; the
-    // blocking tier is anchor-drift ([[code-anchor]]) — an ERROR like any other, so the pre-commit shim
-    // (and CI) gates on it with no separate staged-index machinery.
+    // Blocking tier is anchor-drift ([[code-anchor]]) — CI/default lint judges HEAD; the local armed hook
+    // supplies --pending <real commit oid>; canonical pre-commit leaves the whole lint to that one run.
     if (findings.some((f) => f.rule === 'drift' || f.rule === 'anchor-drift')) console.error(`\n${DRIFT_GUIDANCE}`)
     process.exit(errors.length ? 1 : 0)
   } else if (sub === 'ack') {
@@ -512,9 +509,9 @@ if (cmd === 'serve') {
   } else if (sub === 'ls' && flag('session') !== undefined) {
     // the session EVAL read ([[session-eval]]'s interactive face as a CLI verb): the dashboard Eval tab's
     // text twin. Renders the session's changed nodes with each DECLARED scenario at its CURRENT score
-    // (latest reading per scenario, worktree-rooted) — blind spots lead, the session's OWN measurements
-    // ✦-marked ahead of the inherited baseline under its divider. --export writes the self-contained HTML
-    // artifact instead.
+    // (latest reading per scenario, worktree-rooted) — filed results keep the backend's newest-first order
+    // across ownership, the session's OWN measurements are ✦-marked, and blind spots follow. --export writes
+    // the self-contained HTML artifact instead.
     const id = await resolveSelectorOrExit(flag('session')!)
     if (has('export')) await evalExport(id)
     const { clientEvals } = await import('./client.js')
@@ -522,35 +519,31 @@ if (cmd === 'serve') {
     if (!r.ok) { console.error(`no evals for ${id} (status ${r.status})`); process.exit(1) }
     if (has('json')) { console.log(JSON.stringify(r.model, null, 2)); await flushExit(0) }
     const m = r.model
-    const byNode = new Map<string, any[]>()
-    for (const item of m.items) {
-      const rows = byNode.get(item.node) ?? []
-      rows.push(item)
-      byNode.set(item.node, rows)
-    }
-    const groups = [...byNode].map(([node, rows]) => ({ node, rows }))
     const own = m.items.filter((item) => item.inSession).length
     console.log(`eval session  [${m.id}]`)
     console.log(`  gates  : ${m.gates.map((g) => `${g.ok ? '✓' : '✗'} ${g.label} — ${g.detail}`).join(' · ')}`)
-    if (own) console.log(`  ✦      : ${own} scenario(s) measured by THIS session (unmarked rows = inherited baseline)`)
+    if (own) console.log(`  ✦      : ${own} scenario(s) measured by THIS session (unmarked rows = evals filed by other sessions)`)
     if (!m.items.length) console.log('\n  no affected scenarios to evaluate yet')
-    for (const { node, rows } of groups) {
-      console.log(`\n${node}`)
-      for (const item of rows.filter((row) => row.filterKind === 'blind')) console.log(`      ∅ unmeasured  ${item.scenario}  — declared, never measured (blind spot)`)
-      let divided = false
-      for (const e of rows.filter((row) => row.filterKind === 'result')) {
-        if (!e.inSession && !divided && rows.some((x) => x.filterKind === 'result' && x.inSession)) { console.log(`      ── inherited baseline (other sessions' latest evals) ──`); divided = true }
-        const verdict = e.verdict?.status === 'pass' ? '✓ pass' : e.verdict?.status === 'fail' ? '✗ fail' : '· unscored'
-        const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`
-        console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
+    let lastNode: string | null = null
+    for (const e of m.items) {
+      if (e.node !== lastNode) {
+        console.log(`\n${e.node}`)
+        lastNode = e.node
       }
+      if (e.filterKind === 'blind') {
+        console.log(`      ∅ unmeasured  ${e.scenario}  — declared, never measured (blind spot)`)
+        continue
+      }
+      const verdict = e.verdict?.status === 'pass' ? '✓ pass' : e.verdict?.status === 'fail' ? '✗ fail' : '· unscored'
+      const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`
+      console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
     }
   } else if (['add', 'ls', 'scenario', 'matrix', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
     // node-scoped verbs — thin route; the logic lives in spec-eval.
     const { runEval } = await import('../../spec-eval/src/cli.js')
     await flushExit(await runEval(process.argv.slice(3)))
   } else {
-    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | matrix | lint | ok | retract | clean  (spex help eval)`)
+    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls/write | matrix | lint | ok | retract | clean  (spex help eval)`)
     if (!sub.startsWith('--')) console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`) // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     process.exit(2)
   }
@@ -623,6 +616,51 @@ if (cmd === 'serve') {
     console.log((await import('./help.js')).commandHelp('session'))
   } else if (SESSION_SIGNPOSTS[sub]) {
     signpost(`spex session ${sub}`, SESSION_SIGNPOSTS[sub])
+  } else if (sub === 'maintain') {
+    const args = process.argv.slice(4)
+    if (args.length === 1 && args[0] === '--status') {
+      const state = await (await import('./client.js')).clientMaintenanceStatus()
+      console.log(JSON.stringify(state, null, 2))
+    } else {
+      const separator = args.indexOf('--')
+      if (separator < 0 || separator === args.length - 1) {
+        console.error('usage: spex session maintain [--allow-stop SEL] [--allow-resume SEL[:force]] [--ttl-ms MS] [--wait-ms MS] -- <command> [args...]')
+        process.exit(2)
+      }
+      const options = args.slice(0, separator)
+      const command = args.slice(separator + 1)
+      const capabilities: import('./session-maintenance.js').Capability[] = []
+      let ttlMs = 30_000
+      let waitMs = 10_000
+      for (let i = 0; i < options.length; i++) {
+        const option = options[i]
+        if (option === '--api' || option === '--port') { i++; continue }
+        if (option === '--ttl-ms' || option === '--wait-ms') {
+          const value = Number(options[++i])
+          if (!Number.isSafeInteger(value)) { console.error(`spex session maintain: ${option} requires an integer millisecond value`); process.exit(2) }
+          if (option === '--ttl-ms') ttlMs = value
+          else waitMs = value
+          continue
+        }
+        if (option === '--allow-stop' || option === '--allow-resume') {
+          const raw = options[++i]
+          if (!raw) { console.error(`spex session maintain: ${option} requires a session selector`); process.exit(2) }
+          if (option === '--allow-stop') {
+            capabilities.push({ op: 'stop', sessionId: await resolveSelectorOrExit(raw) })
+          } else {
+            const force = raw.endsWith(':force')
+            const selector = force ? raw.slice(0, -':force'.length) : raw
+            capabilities.push({ op: 'resume', sessionId: await resolveSelectorOrExit(selector), force })
+          }
+          continue
+        }
+        console.error(`spex session maintain: unknown option ${option}`)
+        process.exit(2)
+      }
+      if (capabilities.length === 0) { console.error('spex session maintain: at least one exact stop/resume capability is required'); process.exit(2) }
+      const { runMaintenanceWrapper } = await import('./maintenance-wrapper.js')
+      process.exit(await runMaintenanceWrapper({ capabilities, ttlMs, waitMs, command }))
+    }
   } else if (sub === 'new') {
     // spex session new "<prompt>"  (prompt = first positional or --prompt, or --prompt-file
     // <path>|- so a long multi-paragraph prompt never fights shell quoting — [[prompt-file]]).
@@ -647,22 +685,40 @@ if (cmd === 'serve') {
     }
     const created = await createSession(prompt, flag('launcher') ?? undefined)
     console.log(JSON.stringify(created, null, 2))
-    await launchMonitorReminder(created.id)
+    console.error((await import('./help.js')).sessionLaunchReceipt(created.id))
   } else if (sub === 'ls') {
     // pretty list of living sessions + states. `spex session ls [SEL...] [--status a,b] [--json]`
     // 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 { selectSessions, formatTable } = await import('./sessions.js')
     const { clientListSessions } = await import('./client.js')
-    const picked = selectSessions(await clientListSessions(), positionals(4), flag('status')?.split(','))
+    // The backend's default projection excludes cold archives. --all and an explicit selector request the
+    // history projection so an operator can still inspect or unarchive one deliberately.
+    const selectors = positionals(4)
+    const all = await clientListSessions(has('all') || selectors.length > 0)
+    const visible = all
+    const picked = selectSessions(visible, selectors, flag('status')?.split(','))
     console.log(has('json') ? JSON.stringify(picked, null, 2) : formatTable(picked))
+  } else if (sub === 'resources') {
+    rejectUnknownFlags('spex session resources', 4, ['json', 'api', 'port'])
+    const { clientResources } = await import('./client.js')
+    const report = await clientResources()
+    if (has('json')) console.log(JSON.stringify(report, null, 2))
+    else console.log((await import('./host-resources.js')).formatResourceReport(report))
   } else if (sub === 'watch') {
     const { watchSessions } = await import('./sessions.js')
     const { clientListSessions } = await import('./client.js')
     const selectors = positionals(4)
     const intervalMs = (Number(flag('interval')) || 5) * 1000
+    // Broad watch keeps the default active-only event population, so the archive shelf is not replayed into
+    // ordinary monitoring. Presence is a separate all-record read: hiding a cold row must not turn it into
+    // "gone"/closed. An explicit selector opts into the history population so its archive/offline transition
+    // remains observable.
+    const history = () => clientListSessions(true)
+    const events = selectors.length ? history : () => clientListSessions(false)
     await withWatchEdge(selectors, intervalMs, () => watchSessions((line) => console.log(line), {
-      source: clientListSessions,   // poll the backend, so watch streams the (possibly remote) backend's board
+      source: events,
+      presenceSource: history,
       selectors,
       statuses: flag('status')?.split(','),
       includeIdle: has('idle'),
@@ -682,8 +738,12 @@ if (cmd === 'serve') {
     if (own) console.error(`spex session wait: heads-up (managed agent ${own.slice(0, 8)}) — this command BLOCKS until it OBSERVES ${id} transition from non-actionable into an actionable status (edge-triggered: an already-actionable current state does NOT return it — to just read the state now, use \`spex session ls\`/\`review\`); run it in the BACKGROUND or it freezes your whole turn (its exit is your wake-up). Proceeding.`)
     const intervalMs = (Number(flag('interval')) || 2) * 1000
     const timeoutSec = Number(flag('timeout')) || 1200
+    // `wait` addresses one explicit record. Read its history row for both events and presence so archive is an
+    // offline transition, not a vanished session; only a missing all-record row is a genuine gone/closed result.
+    const history = () => clientListSessions(true)
     const r = await withWatchEdge([id], intervalMs, () => watchSessions(() => {}, {
-      source: clientListSessions,
+      source: history,
+      presenceSource: history,
       selectors: [id],
       includeIdle: has('idle'),
       intervalMs,
@@ -731,6 +791,11 @@ if (cmd === 'serve') {
       console.log('  gates:')
       console.log(`    conflicts w/ main : ${g.conflictsWithMain ? 'YES' : 'no'}`)
       console.log(`    lint              : ${g.lint.errorCount} error(s), ${g.lint.warningCount} warning(s)`)
+      // measured loss is REPORTED, never graded — and a projection that isn't ready says so instead of
+      // printing four zeros that would read as a clean session.
+      console.log(`    evals             : ${g.evals.phase === 'ready'
+        ? `${g.evals.freshPass} fresh pass, ${g.evals.freshFail} fresh fail, ${g.evals.needReview} need review, ${g.evals.blind} blind`
+        : `not measured yet (${g.evals.phase})`}`)
       console.log(`  diff (merge-base, ${r.diff.length} file(s)):`)
       for (const f of r.diff) console.log(`    ${f.status.padEnd(12)} +${f.additions} -${f.deletions}  ${f.path}`)
     }
@@ -770,30 +835,44 @@ if (cmd === 'serve') {
         try { closeNote += (await import('./localIssues.js')).closeoutNudge(sess ?? s.ownSessionId()) }
         catch (e) { console.error(`issue closeout check failed (declaration unaffected): ${e instanceof Error ? e.message : e}`) }
       }
-      console.log(mark(() => s.markDone(p, sess, flag('note'))) ? `done (${p})${DECLARED}${noteEcho(flag('note'))}${closeNote}` : noRecord())
+      const done = mark(() => s.markDone(p, sess, flag('note')))
+      console.log(done.ok ? `done (${p})${DECLARED}${noteEcho(flag('note'))}${closeNote}` : done.reason ?? noRecord())
     } else if (sub === 'park') {
       // sugar: the agent is waiting on a background task; it will self-resume (NOT idle/awaiting)
       const { s, sess, mark, noRecord, noteEcho } = await stateKit()
-      console.log(mark(() => s.markState('parked', { note: flag('note'), sessionId: sess })) ? `parked${DECLARED}${noteEcho(flag('note'))}` : noRecord())
+      const parked = mark(() => s.markState('parked', { note: flag('note'), sessionId: sess }))
+      console.log(parked.ok ? `parked${DECLARED}${noteEcho(flag('note'))}` : parked.reason ?? noRecord())
     } else if (sub === 'ask') {
       // the agent DELIBERATELY declares it is pausing to ask the human a question (like `done`/`park`, an
       // authored state — NOT guarded active-only). The --note carries the question. Distinct from `park`
       // (waiting on a background task, self-resumes): an asking agent resumes only when the human replies.
       const { s, sess, mark, noRecord, noteEcho } = await stateKit()
-      console.log(mark(() => s.markState('asking', { note: flag('note'), sessionId: sess })) ? `asking${DECLARED}${noteEcho(flag('note'))}` : noRecord())
+      const asked = mark(() => s.markState('asking', { note: flag('note'), sessionId: sess }))
+      console.log(asked.ok ? `asking${DECLARED}${noteEcho(flag('note'))}` : asked.reason ?? noRecord())
     } else if (sub === 'stop') {
       // the SOFT stop: kill the agent's tmux + socket but KEEP the worktree, so the session goes offline and
       // can be resumed (`session resume`). Distinct from `close`, which removes the worktree.
       const full = await resolveSelectorOrExit(id)
-      console.log(await c.clientStop(full) ? `stopped ${full} (worktree kept — resumable)` : `no such session ${full}`)
+      const stopped = await c.clientStop(full)
+      if (!stopped) { console.error(`spex session stop: no such session ${full} (no stop transition was committed)`); process.exit(1) }
+      console.log(`stopped ${full} (worktree kept — resumable)`)
     } else if (sub === 'interrupt') {
       const full = await resolveSelectorOrExit(id)
       const r = await c.clientInterrupt(full)
       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 = await resolveSelectorOrExit(id)
-      console.log(await c.clientClose(full) ? `closed ${full}` : `no such session ${full}`)
+      const closed = await c.clientClose(full)
+      if (!closed) { console.error(`spex session close: no such session ${full} (record remains; no close was committed)`); process.exit(1) }
+      console.log(`closed ${full}`)
     } else if (sub === 'send') {
       const full = await resolveSelectorOrExit(id)
       if (has('keys')) {
@@ -871,7 +950,7 @@ if (cmd === 'serve') {
       // machine's) and terminal-only (an agent must never block its turn on it — capture/send).
       const { assertLocalBackend, attachSession } = await import('./attach.js')
       await assertLocalBackend()
-      await attachSession(await resolveSelectorOrExit(id))
+      process.exit(await attachSession(await resolveSelectorOrExit(id)))
     } else {
       console.error(`spex session: unknown verb '${sub}' — new | ls | show | watch | wait | review | merge | send | interrupt | rename | resume | stop | close | attach | done | park | ask  (spex help session)`)
       process.exit(2)
@@ -900,6 +979,58 @@ if (cmd === 'serve') {
       if (!path) throw new Error(`governor '${owner.id}' has no live spec path`)
       console.log(`${owner.id}\t${path}`)
     }
+  } else if (sub === 'maintenance-begin') {
+    const ownerPid = Number(process.argv[4]), sessionId = process.argv[5]
+    if (!Number.isInteger(ownerPid) || ownerPid <= 0 || !sessionId) {
+      console.error('usage: spex internal maintenance-begin <owner-pid> <session-id>')
+      process.exit(2)
+    }
+    const { exactProcessIdentity, maintenanceErrorPayload, sessionMaintenance } = await import('./session-maintenance.js')
+    const owner = exactProcessIdentity(ownerPid)
+    if (!owner) { console.error('maintenance_identity_unknown: hook dispatcher owner identity is not exact'); process.exit(2) }
+    try {
+      console.log(sessionMaintenance().beginExternalOperation({ op: 'hook-state', sessionId }, owner))
+    } catch (error) {
+      const payload = maintenanceErrorPayload(error)
+      console.error(payload ? `${payload.code}: ${payload.error}` : String(error))
+      process.exit(2)
+    }
+  } else if (sub === 'maintenance-end') {
+    const ticket = process.argv[4], ownerPid = Number(process.argv[5])
+    if (!ticket || !Number.isInteger(ownerPid) || ownerPid <= 0) {
+      console.error('usage: spex internal maintenance-end <ticket-id> <owner-pid>')
+      process.exit(2)
+    }
+    const { exactProcessIdentity, sessionMaintenance } = await import('./session-maintenance.js')
+    const owner = exactProcessIdentity(ownerPid)
+    if (!owner) { console.error('maintenance_identity_unknown: hook dispatcher owner identity is not exact'); process.exit(2) }
+    sessionMaintenance().finishExternalOperation(ticket, owner)
+  } else if (sub === 'shared-runtime-spawn') {
+    const [cwd, logFile, pidFile, isolationFile, command] = process.argv.slice(4, 9)
+    const args = process.argv.slice(9)
+    if (!cwd || !logFile || !pidFile || !isolationFile || !command) {
+      console.error('usage: spex internal shared-runtime-spawn <cwd> <log> <pid-file> <isolation-file> <command> [args...]')
+      process.exit(2)
+    }
+    const { readFileSync } = await import('node:fs')
+    const { runSessionOperation } = await import('./session-maintenance.js')
+    const { spawnDetachedRuntime } = await import('./runtime-ownership.js')
+    const delegateFdValue = process.env.SPEXCODE_MAINTENANCE_DELEGATE_FD
+    const delegateChannelPresent = delegateFdValue !== undefined
+    const delegateFd = Number(delegateFdValue)
+    let delegate = ''
+    if (delegateChannelPresent && Number.isInteger(delegateFd) && delegateFd >= 3) {
+      try { delegate = readFileSync(delegateFd, 'utf8').trim() } catch { delegate = '' }
+    }
+    const sessionId = process.env.SPEXCODE_MAINTENANCE_SESSION_ID?.trim()
+      || process.env.SPEXCODE_SESSION_ID?.trim() || 'shared-runtime'
+    const env = { ...process.env }
+    delete env.SPEXCODE_MAINTENANCE_DELEGATE_FD
+    delete env.SPEXCODE_MAINTENANCE_SESSION_ID
+    delete env.SPEXCODE_SESSION_ID
+    const runtime = await runSessionOperation({ op: 'shared-spawn', sessionId, ...(delegateChannelPresent ? { delegate } : {}) }, () =>
+      spawnDetachedRuntime({ cwd, logFile, pidFile, isolationFile, command, args, env }))
+    console.log(runtime.pid)
   } else if (sub === 'codex-launch') {
     // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
     // (codex loads that worktree's config/hooks/AGENTS.md), store the new id on the governed record (keyed by
@@ -914,7 +1045,11 @@ if (cmd === 'serve') {
     // 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 bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(process.env.SPEXCODE_CODEX_CMD || 'codex'))
-    const r = await codexStartThread(sock, cwd, bypassHookTrust)
+    // 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)
     if (!r.ok) { console.error(r.error); process.exit(1) }
     if (prompt) {
       const t = await codexTurn(sock, r.threadId, prompt, cwd)
@@ -993,24 +1128,38 @@ if (cmd === 'serve') {
     const { s, sess, mark, noRecord, noteEcho } = await stateKit()
     const st = process.argv[4] as any
     const ok = mark(() => s.markState(st, { proposal: flag('propose') as any, note: flag('note'), sessionId: sess }))
-    console.log(ok ? `state -> ${st}${noteEcho(flag('note'))}` : noRecord())
+    console.log(ok.ok ? `state -> ${st}${noteEcho(flag('note'))}` : ok.reason ?? noRecord())
   } else if (sub === 'session-fail') {
     // the StopFailure hook marks its session (--session from the payload) as error (turn died on an API error)
     const { s, sess, mark, noRecord } = await stateKit()
-    console.log(mark(() => s.markError(sess)) ? 'marked error' : noRecord())
+    const failed = mark(() => s.markError(sess))
+    console.log(failed.ok ? 'marked error' : failed.reason ?? noRecord())
+  } else if (sub === 'session-turn-fail') {
+    // Headless adapters report an ephemeral turn's non-zero exit through this one shared CAS. A declaration
+    // that landed before teardown wins, so a late child close can never erase an agent-authored state.
+    const sessionId = process.argv[4], harness = process.argv[5], exitCode = process.argv[6]
+    if (!sessionId || !harness || !exitCode) {
+      console.error('usage: spex internal session-turn-fail <session-id> <harness> <exit-code|signal>')
+      process.exit(2)
+    }
+    const { markHeadlessTurnFailure } = await import('./sessions.js')
+    console.log(markHeadlessTurnFailure(sessionId, harness, exitCode) ? `marked error (${harness} ${exitCode})` : 'noop (no active session record)')
   } else if (sub === 'session-idle') {
     // the Notification(idle_prompt) hook marks its session (--session from the payload) idle when claude waits
     // at its prompt. INFERRED, so guarded active-only: it no-ops unless the current status is exactly `active`,
     // never clobbering a deliberate awaiting/asking/parked/error declaration. Distinct from `session ask`
     // (the agent deliberately asking the human) — idle is the undeclared stop the Stop gate missed.
-    const { s, sess } = await stateKit()
-    console.log(s.markIdle(sess) ? 'idle' : 'noop (no session record, or not active)')
+    const { s, sess, mark } = await stateKit()
+    const idled = mark(() => s.markIdle(sess))
+    console.log(idled.ok ? 'idle' : idled.reason ?? 'noop (no session record, or not active)')
   } 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/merge (work committed + ahead of main), else print the reason and exit 1. Uses
+    // ready to declare done, else print the reason and exit 1. Takes the PROPOSAL being judged — `merge`
+    // additionally requires commits ahead of main, `nothing` only a clean tree (see mergeReadiness). Uses
     // git() so the hook's exported GIT_DIR/GIT_INDEX_FILE don't misdirect repo discovery (see git.ts).
     const { s } = await stateKit()
-    const r = s.mergeReadiness()
+    const kind = positionals(4)[0] === 'nothing' ? 'nothing' : 'merge'
+    const r = s.mergeReadiness(kind)
     if (r.ready) { console.log('ready'); process.exit(0) }
     console.log(r.reason)
     process.exit(1)