spexcode 0.5.6 → 0.5.7

package/spec-cli/src/harness.ts

@@ -16,7 +16,7 @@ import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless } from '.
 import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath } from './layout.js'
 import { git } from './git.js'
 import { shQuote } from './sh.js'
-import { detachedRuntimeGenerationToken, processStartToken, verifyDetachedRuntime, type VerifiedDetachedRuntime } from './process-identity.js'
+import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime, type VerifiedDetachedRuntime } from './process-identity.js'
 
 // @@@ harness-adapter - the ONE seam between SpexCode and the coding-agent harness (Claude Code, Codex, …).
 // Every harness-specific fact lives behind THIS interface with one implementation per harness; product code
@@ -86,6 +86,13 @@ export type HarnessColdPreflight =
   | { ok: true; alreadyCold?: boolean; receipt?: unknown }
   | { ok: false; reason: string }
 
+// The corrupt-record quarantine path has no typed session record to pass into cold storage. The adapter therefore
+// owns this separate proof: it can archive one exact native orphan, return only public audit facts, and retain an
+// in-memory compensation closure for the caller's atomic record move. Product code never sees a native receipt.
+export type HarnessOrphanThreadQuarantine =
+  | { ok: true; audit: { adapter: string; threadId: string; action: 'archived' | 'already-unloaded' }; compensate(): Promise<{ ok: true } | { ok: false; reason: string }> }
+  | { ok: false; reason: string }
+
 export type AdapterLoadedReferenceState = {
   healthy: boolean
   loaded: boolean
@@ -298,6 +305,9 @@ export interface Harness {
   // reference or return a loud reason; adapters without such a resident reference return {ok:true}.
   coldRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }, receipt?: unknown): Promise<{ ok: true } | { ok: false; reason: string }>
   restoreRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }, receipt?: unknown): Promise<{ ok: true } | { ok: false; reason: string }>
+  // Recovery for an unreadable governed record. This accepts no record-shaped ownership claim: the adapter must
+  // prove the native target has zero other governed owners, is idle and descendant-free, then archive only it.
+  quarantineOrphanThread?(threadId: string, opts: { excludingSessionId: string }): Promise<HarnessOrphanThreadQuarantine>
   // Project-scoped runtimes are adapter facts. Resource governance consumes these descriptors to report
   // references and protect a sibling-owned control plane without learning harness command names.
   sharedRuntimes?(runtimeDir: string): readonly SharedRuntimeDescriptor[]
@@ -328,19 +338,26 @@ export interface Harness {
   resumeArg(rec: { session: string; harnessSessionId?: string | null }): string
 }
 
-// a prompt-dispatch outcome. ok=true means delivery is confirmed at the layer that harness proves it: claude at
+// A prompt-dispatch outcome. `accepted` means the native control plane acknowledged the turn; `rejected` means
+// it definitely did not; `commit-unknown` means the request crossed a transport boundary but its native result
+// was lost, so replaying it could duplicate a turn. The latter is deliberately distinct from a normal rejection.
+export type DispatchOutcome = 'accepted' | 'rejected' | 'commit-unknown'
+// ok=true means delivery is confirmed at the layer that harness proves it: claude at
 // the DAEMON-PARSE layer (the atomic reply+repaint chunk answered `repaint-done`, or the wall expired on a
 // still-open connection — busy, not lost; see replyViaSocket); codex at the application layer (the app-server
 // accepted `turn/steer`/`turn/start`). `error` carries a human-readable reason that propagates to the API route
 // (non-2xx) and the CLI/dashboard. Defined here because it is the harness DELIVERY contract; sessions.ts
 // re-exports it for its existing importers.
-export type DispatchResult = { ok: boolean; error?: string }
+export type DispatchResult = { ok: boolean; outcome?: DispatchOutcome; error?: string }
 export type HarnessDeliveryRecord = {
   session: string
   worktreePath?: string
   harnessSessionId?: string | null
   runtimeDir?: string
   launchCmd?: string | null
+  // Opaque caller-owned marker. Codex maps it to its native `clientUserMessageId`, while other adapters may
+  // ignore it; product routing never needs to know which harness recognizes the marker.
+  deliveryId?: string
 }
 // the on-demand surface artifacts a materialize pass wrote, by node NAME — so clean() knows EXACTLY which
 // skill subdirs / agent files are SpexCode's to remove (name-scoped, never a blind wipe of a dir the user may
@@ -440,6 +457,7 @@ export const codexAppServerSock = (dir = runtimeRoot()) => {
 }
 export const codexAppServerPid = (dir = runtimeRoot()) => join(dir, 'codex-app-server.pid')
 export const codexAppServerReceipt = (dir = runtimeRoot()) => join(dir, 'codex-app-server.detached.json')
+const codexAppServerLegacyScope = (dir = runtimeRoot()) => join(dir, 'codex-app-server.scope')
 type CodexRuntimeGenerationProof = Readonly<{
   identity: VerifiedDetachedRuntime
   socket: Readonly<{ path: string; dev: number; ino: number }>
@@ -464,6 +482,18 @@ function codexRuntimeGeneration(dir = runtimeRoot()): string | null {
   return proof ? codexRuntimeGenerationToken(proof) : null
 }
 
+function codexMutationGeneration(dir = runtimeRoot()): string | null {
+  const current = codexRuntimeGeneration(dir)
+  if (current) return current
+  let pid: number
+  try {
+    pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim())
+    if (!Number.isInteger(pid) || pid <= 0 || !statSync(codexAppServerSock(dir)).isSocket()) return null
+  } catch { return null }
+  if (!migrateLegacyDetachedRuntimeReceipt(pid, codexAppServerLegacyScope(dir), codexAppServerReceipt(dir))) return null
+  return codexRuntimeGeneration(dir)
+}
+
 // the spex launcher (bin/spex.mjs), baked into the codex launch script (mirrors materialize.ts's SPEX) so
 // the launch shell can call back into `spex codex-launch` to own the thread + fire the first turn before it
 // exec's the visible TUI. The launcher, never a raw `tsx cli.ts` pair: it owns tsx resolution and the
@@ -595,10 +625,11 @@ export function codexHandshakeMessages(threadId: string): JsonRpc[] {
 // only sent with a turnId read live from the thread, never from SpexCode's session status. When the thread is
 // idle (no active turn id), START a fresh turn (turn/start). `id` is parameterized so a steer that loses the
 // expectedTurnId race (turn ended in the read→steer window) can retry as a turn/start with id 5.
-export function codexInjectMessage(threadId: string, text: string, cwd: string | undefined, activeTurnId: string | null, id = 4): JsonRpc {
+export function codexInjectMessage(threadId: string, text: string, cwd: string | undefined, activeTurnId: string | null, id = 4, clientUserMessageId?: string): JsonRpc {
+  const marker = clientUserMessageId ? { clientUserMessageId } : {}
   if (activeTurnId)
-    return { id, method: 'turn/steer', params: { threadId, input: codexTextInput(text), expectedTurnId: activeTurnId } }
-  return { id, method: 'turn/start', params: { threadId, input: codexTextInput(text), ...(cwd ? { cwd } : {}) } }
+    return { id, method: 'turn/steer', params: { threadId, input: codexTextInput(text), expectedTurnId: activeTurnId, ...marker } }
+  return { id, method: 'turn/start', params: { threadId, input: codexTextInput(text), ...(cwd ? { cwd } : {}), ...marker } }
 }
 
 // the in-progress turn id from a `thread/read{includeTurns}` result, or null when the thread is idle. With
@@ -1138,7 +1169,7 @@ function codexThreadCollection(sock: string, params: Record<string, unknown>): P
 }
 
 async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()): Promise<SharedRuntimeMutationGuard> {
-  const generationBefore = codexRuntimeGeneration(dir)
+  const generationBefore = codexMutationGeneration(dir)
   if (!generationBefore) return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'Codex shared app-server generation is unproven' }
   const sock = codexAppServerSock(dir)
   const [loaded, activeDescendants, archivedDescendants] = await Promise.all([
@@ -1195,7 +1226,7 @@ const isCodexColdPlan = (value: unknown): value is CodexColdPlan => {
 }
 
 async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string): Promise<CodexColdPreflight> {
-  const generation = expectedGeneration ?? codexRuntimeGeneration(dir)
+  const generation = expectedGeneration ?? codexMutationGeneration(dir)
   if (!generation || codexRuntimeGeneration(dir) !== generation)
     return { ok: false, reason: 'Codex shared app-server generation is unproven or changed before subtree census' }
   const sock = codexAppServerSock(dir)
@@ -1295,6 +1326,55 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
   return { ok: true, ...(activeIds.length ? {} : { alreadyCold: true }), receipt }
 }
 
+async function codexQuarantineOrphanThread(threadId: string, opts: { excludingSessionId: string }): Promise<HarnessOrphanThreadQuarantine> {
+  const dir = runtimeRoot()
+  const generation = codexMutationGeneration(dir)
+  if (!generation) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
+  const owners = governedSharedRuntimeOwners(dir, 'codex-app-server', threadId, opts.excludingSessionId)
+  if (owners === null) return { ok: false, reason: 'governed Codex thread-owner census is unreadable' }
+  if (owners.length) return { ok: false, reason: `Codex native thread ${threadId} has governed owner(s) ${owners.join(', ')}` }
+  const before = await codexColdPreflight(threadId, dir, generation)
+  if (!before.ok) return before
+  const plan = before.receipt
+  if (plan.descendantIds.length || plan.guard.descendantIds.length)
+    return { ok: false, reason: `Codex native thread ${threadId} has descendants (${[...new Set([...plan.descendantIds, ...plan.guard.descendantIds])].join(', ')})` }
+  if (plan.guard.targetTurnPresence === 'active' || plan.guard.targetTurnPresence === 'unknown')
+    return { ok: false, reason: `Codex native thread ${threadId} is ${plan.guard.targetTurnPresence === 'active' ? 'active' : 'unknown'}` }
+  if (plan.subtreeIds.length !== 1 || plan.subtreeIds[0] !== threadId)
+    return { ok: false, reason: `Codex native thread ${threadId} has an ambiguous ownership closure` }
+  const unchangedOwners = () => governedSharedRuntimeOwners(dir, 'codex-app-server', threadId, opts.excludingSessionId)
+  const rollback = () => codexRestoreColdPlan(plan, dir)
+  if (plan.activeIds.length === 0) {
+    if (plan.archivedIds.length !== 1 || plan.archivedIds[0] !== threadId || plan.guard.referenceIds.includes(threadId))
+      return { ok: false, reason: `Codex native thread ${threadId} is not uniquely archived and unloaded` }
+    const afterOwners = unchangedOwners()
+    if (afterOwners === null || afterOwners.length) return { ok: false, reason: 'governed Codex thread-owner census changed during quarantine verification' }
+    return { ok: true, audit: { adapter: 'codex', threadId, action: 'already-unloaded' }, compensate: async () => ({ ok: true }) }
+  }
+  if (plan.activeIds.length !== 1 || plan.activeIds[0] !== threadId || plan.archivedIds.length)
+    return { ok: false, reason: `Codex native thread ${threadId} is not one exact active orphan` }
+  const siblingIds = plan.guard.referenceIds.filter((id) => id !== threadId)
+  const archived = await codexThreadMutation(codexAppServerSock(dir), 'thread/archive', threadId, { dir, generation })
+  if (!archived.ok) return { ok: false, reason: `${archived.error} while archiving orphan Codex thread ${threadId}` }
+  const after = await codexColdPreflight(threadId, dir, generation)
+  const failed = (reason: string): HarnessOrphanThreadQuarantine => ({ ok: false, reason })
+  if (!after.ok) {
+    const restored = await rollback()
+    return failed(restored.ok ? after.reason : `${after.reason}; ${restored.reason}`)
+  }
+  const afterOwners = unchangedOwners()
+  const afterPlan = after.receipt
+  const valid = afterPlan.descendantIds.length === 0 && afterPlan.subtreeIds.length === 1 && afterPlan.subtreeIds[0] === threadId &&
+    afterPlan.activeIds.length === 0 && afterPlan.archivedIds.length === 1 && afterPlan.archivedIds[0] === threadId &&
+    !afterPlan.guard.referenceIds.includes(threadId) && siblingIds.every((id) => afterPlan.guard.referenceIds.includes(id)) &&
+    afterOwners !== null && afterOwners.length === 0
+  if (!valid) {
+    const restored = await rollback()
+    return failed(restored.ok ? `Codex orphan thread ${threadId} changed during archive verification` : `Codex orphan thread ${threadId} changed during archive verification; ${restored.reason}`)
+  }
+  return { ok: true, audit: { adapter: 'codex', threadId, action: 'archived' }, compensate: rollback }
+}
+
 async function codexMutationGuard(
   threadId: string,
   dir = runtimeRoot(),
@@ -1598,13 +1678,19 @@ export function codexStartThread(sock: string, cwd?: string, bypassHookTrust = f
   })
 }
 
-function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cwd?: string): Promise<DispatchResult> {
+const codexTurnConfirmMs = () => {
+  const configured = Number(process.env.SPEXCODE_CODEX_TURN_CONFIRM_MS)
+  return Number.isFinite(configured) && configured >= 100 ? configured : 15_000
+}
+
+function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cwd?: string, clientUserMessageId?: string): Promise<DispatchResult> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
     const hs = codexHandshakeMessages(threadId)   // [initialize(1), initialized, thread/loaded/list(2), thread/read(3)]
     let buf = Buffer.alloc(0), upgraded = false, settled = false
     let fragOp = 0, fragBuf = Buffer.alloc(0)
     let steering = false   // the id-4 message we sent was a steer → an expectedTurnId race may retry as start(5)
+    let injected = false
     const done = (r: DispatchResult) => {
       if (settled) return
       settled = true
@@ -1612,9 +1698,10 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
       try { conn.destroy() } catch { /* */ }
       resolve(r)
     }
-    const timer = setTimeout(() => done({ ok: false, error: 'codex app-server did not confirm the turn within 5000ms' }), 5000)
-    conn.on('error', (e) => done({ ok: false, error: `codex app-server connection failed: ${rpcError(e)}` }))
-    conn.on('close', () => done({ ok: false, error: 'codex app-server closed the connection before the turn was confirmed' }))
+    const unresolved = (error: string) => done({ ok: false, outcome: injected ? 'commit-unknown' : 'rejected', error })
+    const timer = setTimeout(() => unresolved(`codex app-server did not confirm the turn within ${codexTurnConfirmMs()}ms`), codexTurnConfirmMs())
+    conn.on('error', (e) => unresolved(`codex app-server connection failed: ${rpcError(e)}`))
+    conn.on('close', () => unresolved('codex app-server closed the connection before the turn was confirmed'))
     const send = (m: JsonRpc) => conn.write(wsText(JSON.stringify(m)))
     conn.on('connect', () => {
       const key = randomBytes(16).toString('base64')
@@ -1625,12 +1712,14 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
       try { m = JSON.parse(json) } catch { return }
       if (m.error) {
         if (m.id === 4 && steering)                                         // active turn ended in the read→steer window → just start a fresh turn
-          return send(codexInjectMessage(threadId, text, cwd, null, 5))
+          return send(codexInjectMessage(threadId, text, cwd, null, 5, clientUserMessageId))
         if (m.id === 3)                                                     // thread not readable yet (a freshly-started thread is "not materialized
-          return send(codexInjectMessage(threadId, text, cwd, null, 5))     // before its first user message") → no in-progress turn possible, so just turn/start
-        return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` })
+          return send(codexInjectMessage(threadId, text, cwd, null, 5, clientUserMessageId)) // before its first user message") → just turn/start
+        return done({ ok: false, outcome: 'rejected', error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` })
       }
-      if (m.id === 1 && m.result) return send(hs[2])                       // initialize ack → ask which threads are loaded
+      // JSON-RPC initialization is ordered. Under a quiet server the premature notification happened to win;
+      // under shared app-server load it was ignored and every later turn waited until the old 5s wall expired.
+      if (m.id === 1 && m.result) { send(hs[1]); return send(hs[2]) }      // initialize ack → initialized → ask which threads are loaded
       if (m.id === 2 && m.result) {                                         // loaded-thread list → confirm OUR thread is live, then read it
         const loaded = (m.result as { data?: unknown })?.data
         if (Array.isArray(loaded) && !loaded.includes(threadId))
@@ -1640,9 +1729,10 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
       if (m.id === 3 && m.result) {                                        // thread read → in-progress turn? steer into it; else start a new one
         const turnId = activeTurnIdFromThread(m.result)
         steering = !!turnId
-        return send(codexInjectMessage(threadId, text, cwd, turnId))      // id 4: turn/steer the live turn, or turn/start
+        injected = true
+        return send(codexInjectMessage(threadId, text, cwd, turnId, 4, clientUserMessageId)) // id 4: turn/steer the live turn, or turn/start
       }
-      if ((m.id === 4 || m.id === 5) && m.result) return done({ ok: true }) // steer/start accepted → the model has the message
+      if ((m.id === 4 || m.id === 5) && m.result) return done({ ok: true, outcome: 'accepted' }) // steer/start accepted → the model has the message
     }
     const drainFrames = () => {
       for (;;) {
@@ -1656,7 +1746,7 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
         let payload = buf.slice(dataStart, dataStart + len)
         if (masked) { const mk = buf.slice(off, off + 4); const u = Buffer.alloc(len); for (let i = 0; i < len; i++) u[i] = payload[i] ^ mk[i % 4]; payload = u }
         buf = buf.slice(dataStart + len)
-        if (op === 0x8) return done({ ok: false, error: 'codex app-server sent a WebSocket close before turn/start was confirmed' })
+        if (op === 0x8) return unresolved('codex app-server sent a WebSocket close before turn/start was confirmed')
         if (op === 0x9) { conn.write(encodeWsFrame(0xa, payload)); continue }   // ping → pong
         if (op === 0xa) continue                                                // pong
         if (op === 0x0) fragBuf = Buffer.concat([fragBuf, payload])             // continuation
@@ -1673,7 +1763,7 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
         if (!/^HTTP\/1\.1 101/.test(head)) return done({ ok: false, error: `codex app-server refused the WebSocket upgrade: ${head.split('\r\n')[0]}` })
         upgraded = true
         buf = buf.slice(i + 4)
-        send(hs[0]); send(hs[1])   // initialize + the initialized notification; loaded/list → read → inject follow on the acks
+        send(hs[0])                 // wait for initialize before its required initialized notification
       }
       drainFrames()
     })
@@ -1683,8 +1773,8 @@ function sendCodexAppServerTurn(sock: string, threadId: string, text: string, cw
 // fire a turn on an owned thread over the per-project socket — the same steer-vs-start delivery the live UI
 // uses. The launcher calls this to materialize a freshly-started thread's rollout (the first turn = the launch
 // prompt), and delivery reuses it for follow-ups. Exported so the CLI's `codex-launch` can fire the first turn.
-export function codexTurn(sock: string, threadId: string, text: string, cwd?: string): Promise<DispatchResult> {
-  return sendCodexAppServerTurn(sock, threadId, text, cwd)
+export function codexTurn(sock: string, threadId: string, text: string, cwd?: string, clientUserMessageId?: string): Promise<DispatchResult> {
+  return sendCodexAppServerTurn(sock, threadId, text, cwd, clientUserMessageId)
 }
 
 // @@@ codex rollout on disk - the visible TUI resumes a thread via `codex --remote resume <tid>`, which reads
@@ -1740,7 +1830,7 @@ async function deliverViaCodexAppServer(rec: HarnessDeliveryRecord, text: string
     if (!r.ok) return { ok: false, error: `${r.error} — prompt NOT delivered` }
     threadId = r.threadId
   }
-  return sendCodexAppServerTurn(sock, threadId, text, rec.worktreePath)
+  return sendCodexAppServerTurn(sock, threadId, text, rec.worktreePath, rec.deliveryId)
 }
 
 // idempotent replace of the content between sentinels; the user's own content above/below is preserved. The
@@ -2280,6 +2370,7 @@ export const codexHarness: Harness = {
     if (verified.ok) return verified
     return compensate(verified.reason)
   },
+  quarantineOrphanThread: codexQuarantineOrphanThread,
   restoreRuntime: async (rec, suppliedReceipt) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
     if (suppliedReceipt !== undefined) {
@@ -2363,7 +2454,7 @@ const sameCodexHeadlessReadinessProof = (left: CodexHeadlessLaunchReadinessProof
   left.target.referenceState === right.target.referenceState &&
   left.target.protectsControlPlane === right.target.protectsControlPlane
 
-const governedSharedRuntimeOwners = (runtimeDir: string, descriptorKey: string, threadId: string): string[] | null => {
+const governedSharedRuntimeOwners = (runtimeDir: string, descriptorKey: string, threadId: string, excludingSessionId?: string): string[] | null => {
   const root = join(runtimeDir, 'sessions')
   let entries
   try { entries = readdirSync(root, { withFileTypes: true }) }
@@ -2371,6 +2462,7 @@ const governedSharedRuntimeOwners = (runtimeDir: string, descriptorKey: string,
   const owners: string[] = []
   for (const entry of entries) {
     if (!entry.isDirectory()) continue
+    if (entry.name === excludingSessionId) continue
     let parsed: unknown
     try { parsed = JSON.parse(readFileSync(join(root, entry.name, 'session.json'), 'utf8')) }
     catch (error) {

package/spec-cli/src/help.ts

@@ -70,6 +70,8 @@ provably cannot land.`, ['selector', 'project-bound']],
     archive: ['spex session archive <SEL>', 'Cold-archive it: exact leaf/runtime stopped, worktree and conversation kept.', ['selector']],
     unarchive: ['spex session unarchive <SEL>', 'Deprecated compatibility spelling: same behavior as resume, relaunching the same conversation.', ['selector']],
     close: ['spex session close <SEL>', 'Retire the session and its worktree.', ['selector', 'project-bound']],
+    quarantine: ['spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <id> --worktree <absent-path> --branch <absent-branch> [--restore]',
+      'Move only an unreadable record after the backend proves every named residue absent. Quarantine and --restore both require the original exact id because corrupt rows are outside selectors.', ['project-bound']],
     maintain: [[
       'spex session maintain --allow-stop <SEL> [--allow-resume <SEL>[:force]] … -- <command> [args…]',
       'spex session maintain --status',
@@ -86,7 +88,7 @@ LOCAL-only (fails loud on a remote backend); show --capture and send are non-int
 
 const SESSION_HELP_GROUPS = [
   { title: 'Manager verbs (dispatch, monitor, land)', verbs: ['new', 'ls', 'resources', 'watch', 'wait', 'review', 'merge'] },
-  { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'archive', 'unarchive', 'close', 'maintain'] },
+  { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'archive', 'unarchive', 'close', 'quarantine', 'maintain'] },
   { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask'] },
   { title: 'Human escape hatch', verbs: ['attach'] },
 ] as const

package/spec-cli/src/index.ts

@@ -1,5 +1,6 @@
 import { serve } from '@hono/node-server'
-import type { Server as HttpServer } from 'node:http'
+import type { Server as HttpServer, ServerResponse as HttpServerResponse } from 'node:http'
+import { randomUUID } from 'node:crypto'
 import { installConnectionReaper } from './reaper.js'
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
@@ -15,7 +16,7 @@ import { resolveLayout, mainBranch } from './layout.js'
 import { getBoardJson } from './graphCache.js'
 import { boardStream, closeBoardFileWatchers, ensureBoardFileWatchers, notifyBoardChanged } from './graphStream.js'
 import { gitA, gitTry, repoRoot } from './git.js'
-import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, archiveSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
+import { listSessions, sendText, interruptSession, rawKey, stopSession, closeSession, quarantineCorruptRecord, restoreQuarantinedRecord, archiveSession, resumeSession, mergeSession, reviewPayload, captureSessionResult, sessionPrompt, sessionGraph, registerWatch, deregisterWatch, renameSession, setSessionSort, sessionCreateRequest, superviseQueue, superviseTurnFailures, SessionRecordUnusable, TMUX_SOCK } from './sessions.js'
 import { superviseTimeline, readTimeline } from './session-timeline.js'
 import { defaultHarness, HARNESSES, dashboardLauncherList, launcherDefault } from './harness.js'
 import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
@@ -461,9 +462,28 @@ app.post('/api/sessions/edges/unwatch', async (c) => {
   return c.json({ ok }, ok ? 200 : 404)
 })
 app.post('/api/sessions', async (c) => {
-  const body = await c.req.json().catch(() => null)
-  const result = await sessionCreateRequest(body)
-  return result.status === 201 ? c.json(result.session, 201) : c.json({ error: result.error }, 400)
+  const requestKey = c.req.header('idempotency-key') || randomUUID()
+  const controller = new AbortController()
+  const rawSignal = c.req.raw.signal
+  const outgoing = (c.env as { outgoing?: HttpServerResponse }).outgoing
+  const cancel = () => {
+    if (!outgoing?.writableEnded) controller.abort(new Error('session-create caller disconnected'))
+  }
+  const cancelFromRequest = () => controller.abort(rawSignal.reason)
+  rawSignal.addEventListener('abort', cancelFromRequest, { once: true })
+  outgoing?.once('close', cancel)
+  try {
+    const body = await c.req.json().catch(() => null)
+    const result = await sessionCreateRequest(body, { requestKey, signal: controller.signal })
+    if (result.status === 201) {
+      c.header('Idempotency-Key', requestKey)
+      return c.json(result.session, 201)
+    }
+    return c.json({ error: result.error, ...(result.code ? { code: result.code } : {}), ...(result.phase ? { phase: result.phase } : {}) }, result.status as any)
+  } finally {
+    rawSignal.removeEventListener('abort', cancelFromRequest)
+    outgoing?.off('close', cancel)
+  }
 })
 // one server-side merge bundle (ahead/dirty/diff(merge-base)/gates/proposal) for the manager cockpit;
 // dashboard and `spex session review` are thin callers. 404 for an unknown id. See [[manager-cockpit]].
@@ -616,8 +636,10 @@ app.post('/api/sessions/:id/input', async (c) => {
     // `from` (the sender's session id) rides only an agent-to-agent send → the backend records the comms
     // edge ([[comms-edge]]); a raw human dispatch omits it and is not logged. `replyVia:"note"` marks a
     // terminal-free sender ([[session-timeline]]): the server appends the note-reply insert to the delivery.
-    const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined,
-      body?.replyVia === 'note' ? { replyVia: 'note' } : {})
+    const r = await sendText(c.req.param('id'), typeof body?.text === 'string' ? body.text : '', typeof body?.from === 'string' ? body.from : undefined, {
+      ...(body?.replyVia === 'note' ? { replyVia: 'note' as const } : {}),
+      ...(typeof body?.deliveryId === 'string' && body.deliveryId ? { deliveryId: body.deliveryId } : {}),
+    })
     return c.json(r, r.ok ? 200 : 502)
   }
   if (body?.kind === 'keys') {
@@ -642,8 +664,20 @@ app.post('/api/sessions/:id/interrupt', async (c) => {
 app.post('/api/sessions/:id/close', async (c) => {
   const sessionId = c.req.param('id')
   const ok = await closeSession(sessionId)
+  // The close route owns its write's visible boundary: filesystem watchers can be unavailable, so cache
+  // invalidation must happen before the success response rather than leaving the confirming board to patrol.
+  if (ok) notifyBoardChanged('sessions')
   return c.json(ok ? { ok: true } : { ok: false, error: `no close transition was committed for session ${sessionId}` }, ok ? 200 : 404)
 })
+app.post('/api/sessions/:id/quarantine', async (c) => {
+  const body = await c.req.json().catch(() => null)
+  const result = await quarantineCorruptRecord(c.req.param('id'), body)
+  return c.json({ ok: true, ...result })
+})
+app.post('/api/sessions/:id/quarantine/restore', async (c) => {
+  const result = await restoreQuarantinedRecord(c.req.param('id'))
+  return c.json({ ok: true, ...result })
+})
 // archive / legacy unarchive signpost ([[archive]]) — archive proves exact cold/offline ownership before filing;
 // `{on:false}` enters the same resume transition and recreates the preserved conversation. {ok:false}=no such session.
 app.post('/api/sessions/:id/archive', async (c) => {

package/spec-cli/src/layout.ts

@@ -184,6 +184,8 @@ export type RawRecord = {
   adapter_recovery?: string // explicit lifecycle recovery required after a partial adapter mutation; absent on old records
   launcher?: string   // the launcher profile this session was created under ([[launcher-select]]); absent/empty only on old records predating launchers
   launch_cmd?: string // the RESOLVED base launcher command PINNED at creation, so a resume replays the EXACT launcher (and its config-dir env) that made the conversation, never a since-changed default ([[launcher-select]] resume-launcher-pin); absent → old record, fall back to the launcher name / ambient
+  create_request_id?: string // SHA-256 digest of the create Idempotency-Key; the raw key is never persisted
+  create_payload_hash?: string // normalized create payload bound to create_request_id
   launch_readiness_pending?: '' | RawLaunchReadinessPending
 }
 

package/spec-cli/src/mentions.ts

@@ -2,7 +2,7 @@
 // node) and `@session` (an ACTOR — a live session, or `@new` for a fresh worker). The same parser resolves
 // them in ANY input box; the resolve+dispatch live HERE (CLI-first) so the issues page, the composer, and an agent's
 // own prompt share one implementation. An `@` "just auto-sends a prompt": resolve it against the live board
-// sessions and dispatch via [[dispatch]]'s sendText / [[launch]]'s newSession — storage and delivery stay
+// sessions and dispatch via [[dispatch]]'s sendText / [[launch]]'s bounded create owner — storage and delivery stay
 // separate, and sessions.ts is imported LAZILY so a mention-free post pays nothing.
 
 // ── parse (pure) ──────────────────────────────────────────────────────────────────────────────────────
@@ -87,7 +87,7 @@ function mentionPrompt(threadId: string, node: string | null, author: string, te
 // A non-open thread is settled work: a fresh worker spawned onto it must not re-implement what already
 // landed, so the prompt leads with the status and a verify-on-main-first instruction.
 export function newWorkerPrompt(threadId: string, node: string | null, author: string, text: string, status?: string | null): string {
-  // Keep inherited scope inside the text the worker receives: newSession derives its node only from the
+  // Keep inherited scope inside the text the worker receives: the create transaction derives its node only from the
   // raw prompt's first [[id]] mention, so issue dispatch gets no private node-binding argument.
   const on = node ? ` on node [[${node}]]` : ''
   const settled = status && status !== 'open'
@@ -109,7 +109,7 @@ export async function dispatchMentions(
 ): Promise<DispatchOutcome[]> {
   const { actors } = parseMentions(text)
   if (!actors.length) return []
-  const { sendText, listSessions, newSession } = await import('./sessions.js')
+  const { sendText, listSessions, sessionCreateRequest } = await import('./sessions.js')
   const sessions = await listSessions()
   const resolved = resolveActors(actors, sessions as unknown as ActorSession[])
   const out: DispatchOutcome[] = []
@@ -120,8 +120,13 @@ export async function dispatchMentions(
       // deliberate audit/re-measure), but the worker prompt carries the status and the outcome line warns.
       const settled = ctx.status && ctx.status !== 'open' ? ctx.status : undefined
       try {
-        const s = await newSession(newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status), spawnParent(ctx.author, sessions), r.launcher)
-        out.push({ token: r.token, result: 'spawned', detail: s.id, ...(settled ? { note: `thread ${settled}` } : {}) })
+        const created = await sessionCreateRequest({
+          prompt: newWorkerPrompt(ctx.threadId, ctx.node, ctx.author, text, ctx.status),
+          parent: spawnParent(ctx.author, sessions),
+          launcher: r.launcher,
+        })
+        if (created.status !== 201) throw new Error(`${created.code || 'session_create_failed'}: ${created.error}`)
+        out.push({ token: r.token, result: 'spawned', detail: created.session.id, ...(settled ? { note: `thread ${settled}` } : {}) })
       } catch (e) { out.push({ token: r.token, result: 'failed', detail: e instanceof Error ? e.message : String(e) }) }
       continue
     }

package/spec-cli/src/process-identity.ts

@@ -142,6 +142,26 @@ export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter:
   return live
 }
 
+// A v3 scope is only a migration witness when every recorded and live Linux identity agrees. Readers never
+// call this: minting a v4 receipt belongs to the write admission path that needs the shared runtime.
+export function migrateLegacyDetachedRuntimeReceipt(
+  pid: number,
+  legacyScopeFile: string,
+  receiptFile: string,
+  adapter: ProcessAdapter = hostProcessAdapter,
+): boolean {
+  if (adapter.platform !== 'linux' || verifyDetachedRuntime(pid, receiptFile, adapter).ok) return false
+  let fields: string[]
+  try { fields = readFileSync(legacyScopeFile, 'utf8').trim().split(/\s+/) }
+  catch { return false }
+  const observed = observeDetachedRuntime(pid, adapter)
+  if (!observed.ok || observed.identity.linuxSessionId === undefined) return false
+  const expected = ['detached-v3', String(pid), observed.identity.startToken, String(observed.identity.processGroupId), String(observed.identity.linuxSessionId)]
+  if (fields.length !== expected.length || fields.some((field, index) => field !== expected[index])) return false
+  try { writeDetachedRuntimeReceipt(pid, receiptFile, adapter); return true }
+  catch { return false }
+}
+
 export function writeDetachedRuntimeReceipt(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): VerifiedDetachedRuntime {
   const observed = observeDetachedRuntime(pid, adapter)
   if (!observed.ok) throw new Error(`cannot prove detached shared runtime: ${observed.reason}`)

package/spec-cli/src/session-maintenance.ts

@@ -29,6 +29,7 @@ export type Operation =
   | ({ op: 'resume'; sessionId: string; force: boolean } & Partial<{ authorization: Authorization }>)
   | { op: 'archive'; sessionId: string }
   | { op: 'close'; sessionId: string }
+  | { op: 'quarantine'; sessionId: string }
   | { op: 'merge-dispatch'; sessionId: string }
   | { op: 'queue-drain' }
   | { op: 'attach'; sessionId: string }
@@ -105,7 +106,7 @@ type CoordinatorInput = {
 
 const OPERATIONS = new Set<Operation['op']>([
   'create', 'fallback-create', 'lifecycle-transition', 'hook-state', 'send', 'raw-key-input',
-  'terminal-input', 'interrupt', 'rename', 'sort', 'stop', 'resume', 'archive', 'close',
+  'terminal-input', 'interrupt', 'rename', 'sort', 'stop', 'resume', 'archive', 'close', 'quarantine',
   'merge-dispatch', 'queue-drain', 'attach', 'shared-spawn',
 ])
 const MIN_TTL_MS = 5_000