spexcode 0.5.3 → 0.5.5

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

@@ -1,10 +1,36 @@
+import { randomUUID } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { platform } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 
 export type ProcessIdentity = { pid: number; startToken: string }
-export type ProcessTopology = ProcessIdentity & { processGroupId: number; sessionId: number }
+
+export type ProcessAdapter = Readonly<{
+  platform: NodeJS.Platform
+  startToken(pid: number): string | null
+  processGroupId(pid: number): number | null
+  linuxSessionId(pid: number): number | null
+}>
+
+export type VerifiedDetachedRuntime = Readonly<ProcessIdentity & {
+  receiptVersion: 4
+  processGroupId: number
+  linuxSessionId?: number
+}>
+
+export type DetachedRuntimeVerification =
+  | { ok: true; identity: VerifiedDetachedRuntime }
+  | { ok: false; reason: string }
+
+type DetachedLaunchReceiptV4 = {
+  version: 4
+  kind: 'spexcode-detached-runtime'
+  pid: number
+  startToken: string
+  processGroupId: number
+  linuxSessionId?: number
+}
 
 export function parseProcStat(text: string): { ppid: number; processGroupId: number; sessionId: number; ticks: number; startToken: string; rssPages: number } {
   const end = text.lastIndexOf(')')
@@ -21,22 +47,6 @@ export function parseProcStat(text: string): { ppid: number; processGroupId: num
   }
 }
 
-export function processTopology(pid: number, procRoot = '/proc'): ProcessTopology | null {
-  if (platform() === 'linux' || procRoot !== '/proc') {
-    try {
-      const stat = parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8'))
-      return { pid, startToken: stat.startToken, processGroupId: stat.processGroupId, sessionId: stat.sessionId }
-    } catch { return null }
-  }
-  try {
-    const [processGroupId, sessionId] = execFileSync('ps', ['-o', 'pgid=', '-o', 'sess=', '-p', String(pid)], { encoding: 'utf8' }).trim().split(/\s+/).map(Number)
-    const startToken = processStartToken(pid, procRoot)
-    return startToken && Number.isFinite(processGroupId) && Number.isFinite(sessionId)
-      ? { pid, startToken, processGroupId, sessionId }
-      : null
-  } catch { return null }
-}
-
 export function processStartToken(pid: number, procRoot = '/proc'): string | null {
   if (platform() === 'linux' || procRoot !== '/proc') {
     try { return parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8')).startToken }
@@ -47,3 +57,118 @@ export function processStartToken(pid: number, procRoot = '/proc'): string | nul
     return started || null
   } catch { return null }
 }
+
+const procField = (pid: number, field: 'processGroupId' | 'sessionId'): number | null => {
+  try {
+    const stat = parseProcStat(readFileSync(join('/proc', String(pid), 'stat'), 'utf8'))
+    return stat[field]
+  } catch { return null }
+}
+
+const psProcessGroupId = (pid: number): number | null => {
+  try {
+    const value = Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim())
+    return Number.isInteger(value) && value > 0 ? value : null
+  } catch { return null }
+}
+
+export const hostProcessAdapter: ProcessAdapter = Object.freeze({
+  platform: platform(),
+  startToken: (pid) => processStartToken(pid),
+  processGroupId: (pid) => platform() === 'linux' ? procField(pid, 'processGroupId') : psProcessGroupId(pid),
+  linuxSessionId: (pid) => platform() === 'linux' ? procField(pid, 'sessionId') : null,
+})
+
+const exactKeys = (value: Record<string, unknown>, expected: string[]) => {
+  const actual = Object.keys(value).sort()
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index])
+}
+
+const parseDetachedLaunchReceipt = (text: string, hostPlatform: NodeJS.Platform): DetachedLaunchReceiptV4 | null => {
+  let value: unknown
+  try { value = JSON.parse(text) } catch { return null }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  const receipt = value as Record<string, unknown>
+  const keys = ['kind', 'pid', 'processGroupId', 'startToken', 'version', ...(hostPlatform === 'linux' ? ['linuxSessionId'] : [])].sort()
+  if (!exactKeys(receipt, keys) || receipt.version !== 4 || receipt.kind !== 'spexcode-detached-runtime' ||
+    !Number.isInteger(receipt.pid) || Number(receipt.pid) <= 0 || typeof receipt.startToken !== 'string' || !receipt.startToken ||
+    !Number.isInteger(receipt.processGroupId) || Number(receipt.processGroupId) <= 0 ||
+    (hostPlatform === 'linux' && (!Number.isInteger(receipt.linuxSessionId) || Number(receipt.linuxSessionId) <= 0))) return null
+  return receipt as DetachedLaunchReceiptV4
+}
+
+const observeDetachedRuntime = (pid: number, adapter: ProcessAdapter): DetachedRuntimeVerification => {
+  if (adapter.platform === 'win32') return { ok: false, reason: 'detached runtime identity is unsupported on win32' }
+  const startBefore = adapter.startToken(pid)
+  if (!startBefore) return { ok: false, reason: `PID ${pid} has no readable process-start identity` }
+  const processGroupId = adapter.processGroupId(pid)
+  if (processGroupId !== pid) return { ok: false, reason: `PID ${pid} is not its own process-group leader (pgrp=${processGroupId ?? 'unknown'})` }
+  let linuxSessionId: number | undefined
+  if (adapter.platform === 'linux') {
+    const sessionId = adapter.linuxSessionId(pid)
+    if (sessionId !== pid) return { ok: false, reason: `Linux PID ${pid} is not its own session leader (session=${sessionId ?? 'unknown'})` }
+    linuxSessionId = sessionId
+  }
+  const startAfter = adapter.startToken(pid)
+  if (!startAfter || startAfter !== startBefore)
+    return { ok: false, reason: `PID ${pid} process-start identity changed during detached-boundary verification` }
+  return {
+    ok: true,
+    identity: Object.freeze({
+      pid,
+      startToken: startAfter,
+      receiptVersion: 4,
+      processGroupId,
+      ...(linuxSessionId === undefined ? {} : { linuxSessionId }),
+    }),
+  }
+}
+
+export function verifyDetachedRuntime(pid: number, receiptFile: string, adapter: ProcessAdapter = hostProcessAdapter): DetachedRuntimeVerification {
+  let text: string
+  try { text = readFileSync(receiptFile, 'utf8') }
+  catch { return { ok: false, reason: 'detached launch receipt is missing or unreadable' } }
+  const receipt = parseDetachedLaunchReceipt(text, adapter.platform)
+  if (!receipt) return { ok: false, reason: 'detached launch receipt has the wrong version or shape' }
+  if (receipt.pid !== pid) return { ok: false, reason: `detached launch receipt names PID ${receipt.pid}, not ${pid}` }
+  if (receipt.processGroupId !== pid)
+    return { ok: false, reason: `detached launch receipt has wrong process group ${receipt.processGroupId} for PID ${pid}` }
+  if (adapter.platform === 'linux' && receipt.linuxSessionId !== pid)
+    return { ok: false, reason: `detached launch receipt has wrong Linux session ${receipt.linuxSessionId ?? 'missing'} for PID ${pid}` }
+  const live = observeDetachedRuntime(pid, adapter)
+  if (!live.ok) return live
+  if (live.identity.startToken !== receipt.startToken)
+    return { ok: false, reason: `PID ${pid} process-start identity does not match its detached launch receipt` }
+  return live
+}
+
+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}`)
+  const receipt: DetachedLaunchReceiptV4 = {
+    version: 4,
+    kind: 'spexcode-detached-runtime',
+    pid,
+    startToken: observed.identity.startToken,
+    processGroupId: observed.identity.processGroupId,
+    ...(observed.identity.linuxSessionId === undefined ? {} : { linuxSessionId: observed.identity.linuxSessionId }),
+  }
+  mkdirSync(dirname(receiptFile), { recursive: true })
+  const tmp = `${receiptFile}.${process.pid}.${randomUUID()}.tmp`
+  let published = false
+  try {
+    writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 })
+    renameSync(tmp, receiptFile)
+    published = true
+    const verified = verifyDetachedRuntime(pid, receiptFile, adapter)
+    if (!verified.ok) throw new Error(`cannot verify detached shared runtime receipt: ${verified.reason}`)
+    return verified.identity
+  } catch (error) {
+    rmSync(tmp, { force: true })
+    if (published) rmSync(receiptFile, { force: true })
+    throw error
+  }
+}
+
+export const detachedRuntimeGenerationToken = (identity: VerifiedDetachedRuntime) =>
+  `detached-v4|${identity.pid}|${identity.startToken}|${identity.processGroupId}|${identity.linuxSessionId ?? '-'}`

package/spec-cli/src/runtime-ownership.ts

@@ -4,7 +4,7 @@ import { closeSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, writeF
 import { dirname, join } from 'node:path'
 import { repoRoot } from './git.js'
 import { readJsonConfig, runtimeRoot } from './layout.js'
-import { processStartToken, processTopology, type ProcessIdentity } from './process-identity.js'
+import { processStartToken, writeDetachedRuntimeReceipt, type ProcessIdentity } from './process-identity.js'
 
 export type BackendInstanceRecord = {
   version: 1
@@ -51,20 +51,11 @@ export function unregisterBackendInstance(instanceId: string, pid = process.pid)
   } catch { /* not ours / already removed */ }
 }
 
-export function writeIsolationStamp(pid: number, file: string): void {
-  const topology = processTopology(pid)
-  if (!topology) throw new Error(`cannot identify shared runtime PID ${pid}`)
-  if (topology.processGroupId !== pid || topology.sessionId !== pid)
-    throw new Error(`shared runtime PID ${pid} is not detached from its launch session (pgrp=${topology.processGroupId}, session=${topology.sessionId})`)
-  mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, `detached-v3 ${pid} ${topology.startToken} ${topology.processGroupId} ${topology.sessionId}\n`, { mode: 0o600 })
-}
-
 export function spawnDetachedRuntime(opts: {
   cwd: string
   logFile: string
   pidFile: string
-  isolationFile: string
+  receiptFile: string
   command: string
   args: string[]
   env?: NodeJS.ProcessEnv
@@ -85,15 +76,13 @@ export function spawnDetachedRuntime(opts: {
   if (!child.pid) throw new Error(`could not spawn detached shared runtime: ${opts.command}`)
   child.unref()
   try {
-    writeIsolationStamp(child.pid, opts.isolationFile)
-    const startToken = processStartToken(child.pid)
-    if (!startToken) throw new Error(`cannot identify detached shared runtime PID ${child.pid}`)
+    const identity = writeDetachedRuntimeReceipt(child.pid, opts.receiptFile)
     writeFileSync(opts.pidFile, `${child.pid}\n`, { mode: 0o600 })
-    return { pid: child.pid, startToken }
+    return { pid: identity.pid, startToken: identity.startToken }
   } catch (error) {
     try { child.kill('SIGTERM') } catch { /* exact just-spawned child already exited */ }
     rmSync(opts.pidFile, { force: true })
-    rmSync(opts.isolationFile, { force: true })
+    rmSync(opts.receiptFile, { force: true })
     throw error
   }
 }

package/spec-cli/src/sessions.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url'
 import { seedWorktreeHostState } from './worktree-sources.js'
 import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, type ReviewDiffFile } from './git.js'
 import { loadConfig, loadSpecs, type ConfigPreset, type SpecLite } from './specs.js'
-import { adapterLoadedReferenceState, defaultHarness, sessionIdentityEnvVars, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rendezvousListening, stampRvSock, type Harness, type HarnessLaunchReadinessFence, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
+import { adapterLoadedReferenceState, defaultHarness, sessionIdentityEnvVars, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rendezvousListening, stampRvSock, type Harness, type HarnessLaunchReadinessFence, type TurnFailure, type FailureSubscription, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js'
 import { materialize } from './materialize.js'
 import { mainBranch, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, rawLaunchReadinessOriginal, readAliasedRawRecord, readRecordEntry, readAliasedRecordEntry, readPublicRecordEntry, envSessionId, isSessionLifecycle, isSessionProposal, type PublicRecordEntry, type RawRecord, type SessionLifecycle, type SessionProposal } from './layout.js'
 import { recordSent, recordStatus, lastHumanSendVia } from './session-timeline.js'
@@ -1651,6 +1651,106 @@ export function superviseQueue(intervalMs = 3000): void {
   void tick()
 }
 
+type TurnFailureObserverState = {
+  fingerprint: string
+  subscription: FailureSubscription | null
+  startedAt: number
+  failures: number
+  retryAt: number
+  lastReason: string | null
+}
+const turnFailureObservers = new Map<string, TurnFailureObserverState>()
+let supervisingTurnFailures = false
+const TURN_FAILURE_OBSERVER_STABLE_MS = 5000
+
+export function turnFailureNote(harness: string, failure: TurnFailure): string {
+  const message = failure.message.replace(/\s+/g, ' ').trim().slice(0, 500) || 'turn failed'
+  const at = failure.completedAt == null ? '' : ` at ${new Date(failure.completedAt * 1000).toISOString()}`
+  return `${harness} turn failed${at}: ${message}`
+}
+
+export function turnFailureRetryDelay(failures: number): number {
+  return Math.min(30_000, 1000 * 2 ** Math.max(0, Math.min(failures - 1, 5)))
+}
+
+function deferTurnFailureObserver(id: string, harness: string, state: TurnFailureObserverState, reason: string): void {
+  state.subscription = null
+  state.failures++
+  const delay = turnFailureRetryDelay(state.failures)
+  state.retryAt = Date.now() + delay
+  if (state.lastReason !== reason)
+    console.warn(`[spex ${harness}] turn failure observer for ${id} disconnected (${reason}); retrying in ${delay}ms`)
+  state.lastReason = reason
+}
+
+// Reconcile one adapter-owned native failure subscription per live governed session. Product code knows only
+// the optional interface capability; Codex owns WebSocket/thread semantics and Claude keeps using StopFailure.
+export function reconcileTurnFailureObservers(): void {
+  const wanted = new Map<string, { rec: SessRec; harness: Harness; fingerprint: string }>()
+  for (const id of listSessionIds()) {
+    let rec: SessRec | null = null
+    try { rec = readRecord(id) } catch { continue }
+    if (!rec?.governed || rec.stopped || rec.archived || !rec.harnessSessionId) continue
+    const harness = harnessById(rec.harness || defaultHarness.id)
+    if (!harness.observeTurnFailures) continue
+    wanted.set(id, { rec, harness, fingerprint: `${harness.id}:${rec.harnessSessionId}:${runtimeRoot()}` })
+  }
+  for (const [id, state] of turnFailureObservers) {
+    if (wanted.get(id)?.fingerprint === state.fingerprint) continue
+    turnFailureObservers.delete(id)
+    state.subscription?.close()
+  }
+  for (const [id, target] of wanted) {
+    const now = Date.now()
+    let state = turnFailureObservers.get(id)
+    if (state?.subscription) {
+      if (state.failures > 0 && now - state.startedAt >= TURN_FAILURE_OBSERVER_STABLE_MS) {
+        state.failures = 0
+        state.retryAt = 0
+        state.lastReason = null
+      }
+      continue
+    }
+    if (state && now < state.retryAt) continue
+    state ??= { fingerprint: target.fingerprint, subscription: null, startedAt: 0, failures: 0, retryAt: 0, lastReason: null }
+    state.startedAt = now
+    turnFailureObservers.set(id, state)
+    try {
+      const subscription = target.harness.observeTurnFailures!({
+        session: id,
+        worktreePath: target.rec.worktreePath,
+        harnessSessionId: target.rec.harnessSessionId,
+        runtimeDir: runtimeRoot(),
+        launchCmd: target.rec.launchCmd,
+      }, (failure) => {
+        if (turnFailureObservers.get(id)?.fingerprint !== target.fingerprint) return
+        try { markTurnFailure(id, turnFailureNote(target.harness.id, failure)) }
+        catch (error) { console.error(`[spex ${target.harness.id}] could not record native turn failure for ${id}: ${error instanceof Error ? error.message : String(error)}`) }
+      })
+      state.subscription = subscription
+      void subscription.closed.then((reason) => {
+        if (turnFailureObservers.get(id) !== state) return
+        if (reason) deferTurnFailureObserver(id, target.harness.id, state, reason)
+        else turnFailureObservers.delete(id)
+      })
+    } catch (error) {
+      deferTurnFailureObserver(id, target.harness.id, state, error instanceof Error ? error.message : String(error))
+    }
+  }
+}
+
+export function superviseTurnFailures(intervalMs = 1000): void {
+  if (supervisingTurnFailures) return
+  supervisingTurnFailures = true
+  const tick = () => {
+    try { reconcileTurnFailureObservers() }
+    catch (error) { console.error(`spex: turn failure reconciliation failed: ${error instanceof Error ? error.message : String(error)}`) }
+    const timer = setTimeout(tick, intervalMs)
+    timer.unref?.()
+  }
+  tick()
+}
+
 // @@@ assertProjectMatch - a WRITE is PROJECT-BOUND, but routing is by URL. A mutating verb's intent is
 // "act on the project my cwd is in", yet the resolved base is a pure URL carrying no project identity —
 // the backend it answers acts on ITS OWN mainRoot, so a stale inherited SPEXCODE_API_URL (pointing at
@@ -2105,19 +2205,23 @@ export function markState(status: Lifecycle, opts: { proposal?: Proposal; note?:
 }
 export const markDone = (proposal: Proposal = 'nothing', sessionId?: string, note?: string) => markState('awaiting', { proposal, note, sessionId })
 export const markError = (sessionId?: string) => markState('error', { sessionId })
-// @@@ headless turn outcome - a harness turn is an ephemeral child, so its non-zero exit is the one external
-// runtime fact that must become visible on the durable board. Compare-and-set only an undeclared active record:
-// a zero exit is never routed here, and a declaration that landed before teardown is authoritative.
-export function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean {
-  if (exitCode === '0') return false
+// @@@ harness turn failure - native adapter failures are external runtime facts that must become visible on
+// the durable board. Compare-and-set only an undeclared active record, so a declaration that landed before a
+// late process close or app-server completion remains authoritative.
+export function markTurnFailure(sessionId: string | undefined, note: string): boolean {
+  if (!sessionId) return false
   return runSessionOperationSync({ op: 'lifecycle-transition', sessionId }, () => withRecordLockSync(sessionId, () => {
     const rec = readLiveRecord(sessionId)
-    if (!rec || rec.status !== 'active') return false
-    const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`
-    writeRecord({ ...rec, status: 'error', proposal: null, note: `${harness} turn exited with ${outcome}` })
+    if (!rec || rec.status !== 'active' || rec.stopped || rec.archived) return false
+    writeRecord({ ...rec, status: 'error', proposal: null, note })
     return true
   }))
 }
+export function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean {
+  if (exitCode === '0') return false
+  const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`
+  return markTurnFailure(sessionId, `${harness} turn exited with ${outcome}`)
+}
 export function markHarnessSessionId(sessionId: string | undefined, harnessSessionId: string | undefined): boolean {
   const id = sessionId || ownSessionId()
   if (!id || !harnessSessionId) return false
@@ -2437,10 +2541,11 @@ async function assertSessionLeafOwned(id: string, rec: SessRec): Promise<LeafIde
   return { pid, startToken, ownerNeedle }
 }
 
-async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = false): Promise<void> {
+async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = false, coldReceipt?: unknown): Promise<void> {
   // The caller resolves one readable owner before entering this seam. An absent/corrupt record never reaches
   // tmux, signals, or adapter cleanup: a bare session id is an address, not ownership authority.
-  const assertOwned = () => assertSessionStopSafe(id, rec ? { ...rec, harness: rec.harness } : null)
+  const assertOwned = () => assertSessionStopSafe(id, rec ? { ...rec, harness: rec.harness } : null,
+    { ...(requireCold && coldReceipt !== undefined ? { coldReceipt } : {}) })
   await assertOwned()
   if (!rec) throw new ResourceConflict(`refusing to stop ${id}: no readable session owner`)
   const harness = harnessById(rec.harness || defaultHarness.id)
@@ -2453,7 +2558,7 @@ async function stopAgentProcess(id: string, rec: SessRec | null, requireCold = f
   launchedAt.delete(id)
   await harness.cleanupRuntime(rec)
   if (requireCold) {
-    const cold = await harness.coldRuntime?.(rec)
+    const cold = await harness.coldRuntime?.(rec, coldReceipt)
     if (cold && !cold.ok) throw new ResourceConflict(`refusing to archive ${id}: ${cold.reason}`)
   }
 }
@@ -2521,7 +2626,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
       if (rootAbsent) return true
       const pre = await h.coldPreflight?.({ ...wt.rec, archived: false, stopped: true })
       if (!pre || pre.ok) {
-        const cold = await h.coldRuntime?.({ ...wt.rec, archived: false, stopped: true })
+        const cold = await h.coldRuntime?.({ ...wt.rec, archived: false, stopped: true }, pre?.ok ? pre.receipt : undefined)
         if (!cold || cold.ok) return true
       }
     }
@@ -2541,8 +2646,8 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     : liveness({ ...wt.rec, archived: false, stopped: false }, snap)
   if (lv === 'unknown' || lv === 'starting')
     throw new ResourceConflict(`refusing to archive ${id}: session liveness is ${lv}; exact leaf ownership is unproven`)
-  // The adapter guard runs BEFORE any tmux/process signal. Active/unknown Codex turns and owned descendants
-  // refuse here, leaving the leaf/shared root/record untouched; coldRuntime is the commit cleanup after this.
+  // The adapter guard runs BEFORE any tmux/process signal. Active/unknown native turns and ambiguous descendant
+  // ownership refuse here; a verified adapter receipt carries an exact subtree through to coldRuntime's commit.
   const preflight = await h.coldPreflight?.({ ...wt.rec, archived: false, stopped: lv === 'offline' })
   if (preflight && !preflight.ok) throw new ResourceConflict(`refusing to archive ${id}: ${preflight.reason}`)
   // Even a proven-offline leaf can leave a stale rendezvous/socket or adapter artifact. Reuse the same exact
@@ -2552,7 +2657,8 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
   let coldAttempted = false
   try {
     coldAttempted = true
-    await stopAgentProcess(id, { ...wt.rec, archived: false, stopped: lv === 'offline' }, true)
+    await stopAgentProcess(id, { ...wt.rec, archived: false, stopped: lv === 'offline' }, true,
+      preflight?.ok ? preflight.receipt : undefined)
     coldCommitted = true
     const latest = readRecord(id)
     if (!latest) throw new ResourceConflict(`refusing to archive ${id}: session record disappeared before filing`)
@@ -2566,7 +2672,7 @@ async function archiveSessionUnlocked(id: string, on = true): Promise<boolean> {
     writeRecord({ ...latest, archived: true, stopped: true, coldProof: coldProofFor(latest) })
   } catch (error) {
     if (coldCommitted) {
-      const restored = await h.restoreRuntime?.(wt.rec)
+      const restored = await h.restoreRuntime?.(wt.rec, preflight?.ok ? preflight.receipt : undefined)
       if (restored && !restored.ok) {
         const current = readRecord(id)
         if (current) writeRecord({ ...current, archived: false, stopped: true, coldProof: null, adapterRecovery: `restore-runtime:${restored.reason}` })

package/spec-cli/templates/hooks/pre-commit

@@ -58,18 +58,12 @@ fi
 # stamp already passed above. Escape hatch for seeding / eager topology: SPEXCODE_ALLOW_MAIN=1 git commit …
 #
 # The trunk is resolved the SAME way the rest of SpexCode resolves it — `spex internal trunk` = layout.ts
-# mainBranch() (config override → the main checkout's current branch → 'main') — so the guard protects
-# whatever the repo's trunk is actually named, NOT a hardcoded 'main' (which gave a `master`/non-`main`
-# trunk zero protection). When the CLI isn't resolvable (advisory mode), fall back to a pure-git
-# auto-detect of the main checkout's current branch, then 'main' — still protecting a non-`main` trunk.
+# mainBranch() (the stable mainBranch project fact stamped at adoption; conventional default 'main') — so
+# the guard protects whatever the repo's trunk is actually named. When the CLI isn't resolvable (advisory
+# mode), only the convention is available: shell does not guess identity from a mutable checkout.
 branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo)
 git_dir=$(git rev-parse --git-dir 2>/dev/null)
 trunk=$(spex_cli internal trunk 2>/dev/null | head -1)
-# Fallback auto-detect: the main checkout's current branch. Strip the hook's exported GIT_DIR/
-# GIT_INDEX_FILE first — otherwise they pin discovery to the COMMITTING worktree and `-C "$main_root"`
-# is ignored, so it would read THIS branch and think every node branch is the trunk. (`spex internal
-# trunk` above is immune: layout.ts mainBranch() resolves through git.ts's env-stripping git().)
-[ -n "$trunk" ] || trunk=$(env -u GIT_DIR -u GIT_INDEX_FILE git -C "$main_root" symbolic-ref --short HEAD 2>/dev/null)
 [ -n "$trunk" ] || trunk=main
 if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCODE_ALLOW_MAIN:-}" ]; then
   echo "✗ SpexCode: direct commits on $trunk (the trunk) are blocked." >&2

package/spec-cli/templates/spec/project/.plugins/core/session-fail/spec.md

@@ -7,7 +7,9 @@ events:
 - StopFailure
 order: 10
 block: false
+code:
+- .spec/project/.plugins/core/session-fail/fail.sh
 ---
 When a turn ends not because the agent declared but because the API itself failed, this hook structurally marks the session `error`. A failed turn is a real outcome the board must show, and without this signal the session would freeze under whatever state it last held — reading as "active" or "awaiting" long after it actually died.
 
-It is non-blocking and unconditional on the failure event: the failure already happened, so the only job is to record it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. By turning an API error into a declared `error` state it keeps the [[stop-gate]] family's invariant intact — a session's displayed state always reflects what is really true of its last turn — for the one stop path the agent cannot narrate itself.
+It is non-blocking on the failure event: the failure already happened, so the only job is to report it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. That machine entry reaches the same live-active compare-and-set as Codex's native failed completion and a headless turn's non-zero exit (harness-adapter): only an undeclared, non-stopped `active` record becomes `error`. A declaration, explicit stop, or archive that landed first remains authoritative; a late native failure never rewrites it. This one writer keeps the [[stop-gate]] family's invariant intact for every harness while each adapter retains only its native failure signal.

package/spec-cli/templates/spec/project/.plugins/core/spec.md

@@ -18,6 +18,6 @@ The body is the contract; update it with code when intent changes.
 2. COMMIT BEFORE YOU DECLARE. Commit the spec and the code it justifies before declaring done or proposing merge.
 Independent intent gets its own sibling node; do not ride it on an assigned node.
 3. THE BODY IS A LIVING CURRENT-STATE DOCUMENT. Rewrite present intent in place; never add a `## vN` changelog.
-4. KEEP THE LOSS SIGNAL HONEST. `spex spec lint` is the blocking correctness gate; `spex eval lint --changed`
-reports measurement gaps. Re-run changed eval scenarios through the real product, commit the verified tree, then
+4. KEEP THE LOSS SIGNAL HONEST. Before declaring, run both: `spex spec lint` is the blocking correctness gate;
+`spex eval lint --changed` reports measurement gaps. Re-run changed eval scenarios through the real product, commit the verified tree, then
 file with `spex eval add`; the reading's `codeSha` must name that commit, and evidence must fit the behavior.