spexcode 0.5.3 → 0.5.5

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 { processStartToken, processTopology } from './process-identity.js'
+import { detachedRuntimeGenerationToken, 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
@@ -37,6 +37,8 @@ export type HarnessLaunchReadinessFence = {
   readonly proof: Readonly<Record<string, unknown>>
   validate(current: () => HarnessLaunchReadyRecord | null): Promise<boolean>
 }
+export type TurnFailure = { message: string; completedAt: number | null }
+export type FailureSubscription = { close(): void; readonly closed: Promise<string | null> }
 // the per-pane runtime probe the caller snapshots ONCE for the whole session list and hands liveness():
 // the pane's root pid (tmux `#{pane_pid}`), the hot-tier `pidAlive` verdict, and — ONLY on the legacy path —
 // one whole-box pid→(ppid, comm) table (a single `ps` spawn).
@@ -53,13 +55,13 @@ export type SharedRuntimeDescriptor = {
   key: string
   label: string
   pidFile: string
-  isolationFile: string
+  receiptFile: string
   // Lightweight project-wide resident census used by read projections. It must return exact loaded IDs without
   // per-thread reads; the full probe remains the resource/lifecycle surface that also reads turn state.
   residency?: () => Promise<{ healthy: boolean; referenceIds: string[]; error?: string; rootAbsent?: boolean }>
   // Lifecycle mutation guard is deliberately narrower than the full resource projection: census every loaded
   // ID, but read only the exact governed target when it is loaded, plus both target descendant collections.
-  mutationGuard?: (targetReferenceId: string) => Promise<SharedRuntimeMutationGuard>
+  mutationGuard?: (targetReferenceId: string, opts?: { coldReceipt?: unknown }) => Promise<SharedRuntimeMutationGuard>
   probe(): Promise<SharedRuntimeProbe>
 }
 export type SharedRuntimeMutationGuard = {
@@ -67,6 +69,7 @@ export type SharedRuntimeMutationGuard = {
   referenceIds: string[]
   targetTurnPresence: 'none' | 'idle' | 'active' | 'unknown'
   descendantIds: string[]
+  coldTeardownAuthorized?: boolean
   error?: string
 }
 export type SharedRuntimeProbe = {
@@ -79,6 +82,10 @@ export type SharedRuntimeProbe = {
   error?: string
 }
 
+export type HarnessColdPreflight =
+  | { ok: true; alreadyCold?: boolean; receipt?: unknown }
+  | { ok: false; reason: string }
+
 export type AdapterLoadedReferenceState = {
   healthy: boolean
   loaded: boolean
@@ -127,6 +134,8 @@ export async function adapterLoadedReferenceState(
 
 export interface Harness {
   readonly id: HarnessId
+  // the id baked into the materialized shim. Headless variants reuse their native family's shim.
+  readonly dispatchId: 'claude' | 'codex' | 'opencode' | 'pi'
   // whether this harness runs without an interactive TUI. The dashboard launcher picker hides headless
   // adapters by default ([[launcher-visibility]]); CLI launcher resolution never consumes that policy.
   readonly headless: boolean
@@ -187,6 +196,9 @@ export interface Harness {
   // --- materialize: shim + contract + trust ([[harness-delivery]]) ---
   // the auto-discovered hook shim file for this harness (.claude/settings.json vs .codex/hooks.json).
   shimFile(proj: string): string
+  // whether that shim belongs to one checkout or the whole project. This is adapter placement data: Codex
+  // reads one root-checkout hook file for every linked tree; the other harnesses discover their tree-local file.
+  shimScope: 'tree' | 'project'
   // a LINKED WORKTREE's extra shim copy — the worktree-side `.codex` hook file that ANCHORS codex's project
   // config layer, or null when the harness needs none. codex-rs only builds a project config layer (and thus
   // only DISCOVERS a worktree thread's hooks) for a dir in [cwd..project_root] that contains a `.codex/`
@@ -262,6 +274,9 @@ export interface Harness {
   // (mid-turn, not queued for after the agent stops) or `turn/start`s a fresh turn when the thread is idle.
   // Returns ok=false with a reason that propagates to the API.
   deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>
+  // Observe native turn failures that this harness does not expose as a lifecycle hook. The adapter owns the
+  // transport subscription; sessions owns observer reconciliation and the active-only lifecycle CAS.
+  observeTurnFailures?(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription
   // Hard-interrupt the current turn through the harness's native control plane. Optional because a harness
   // without a confirmed native interrupt must refuse rather than emulate one with a signal or PTY key.
   interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>
@@ -273,14 +288,16 @@ export interface Harness {
   cleanupRuntime(rec: HarnessLivenessRecord): Promise<void>
   // Archive preflight runs BEFORE any leaf signal. It may inspect shared references to refuse an active or
   // unknown target turn, but it must not mutate the shared runtime; coldRuntime is the sole commit primitive.
-  coldPreflight?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true; alreadyCold?: boolean } | { ok: false; reason: string }>
+  // Its optional receipt is opaque adapter authority: product code may only pass the same object back to the
+  // stop guard and coldRuntime, never inspect it or synthesize a recursive/archive mode.
+  coldPreflight?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<HarnessColdPreflight>
   // A record that is already archived needs a target-only continuing-cold proof. Unlike mutation preflight,
   // this must not thread/read unrelated loaded siblings merely to retire a target whose runtime is absent.
   coldRetirementPreflight?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true; alreadyCold: true } | { ok: false; reason: string }>
   // Optional cold-storage proof/cleanup. A harness with a per-session loaded reference must remove exactly that
   // reference or return a loud reason; adapters without such a resident reference return {ok:true}.
-  coldRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true } | { ok: false; reason: string }>
-  restoreRuntime?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): Promise<{ ok: true } | { ok: false; reason: string }>
+  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 }>
   // 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[]
@@ -297,7 +314,7 @@ export interface Harness {
   // skill/agent files named in `arts` — never the user's surrounding prose, their other settings, or any .spec
   // data. materialize calls it for every UNSELECTED harness, so dropping a harness from spexcode.json's
   // `harnesses` prunes that harness's products on the next re-materialize.
-  clean(proj: string, arts: HarnessArtifacts): void
+  clean(proj: string, arts: HarnessArtifacts, preserveProject?: boolean): void
   // the inverse of writeTrust: strip THIS project's spexcode trust block from the harness's global config.
   // Codex removes its `~/.codex/config.toml` block; Claude is a no-op (it wrote none).
   removeTrust(proj: string): void
@@ -422,37 +439,26 @@ export const codexAppServerSock = (dir = runtimeRoot()) => {
   return join(base, `spexcode-cx-${createHash('sha1').update(dir).digest('hex').slice(0, 16)}.sock`)
 }
 export const codexAppServerPid = (dir = runtimeRoot()) => join(dir, 'codex-app-server.pid')
-export const codexAppServerIsolation = (dir = runtimeRoot()) => join(dir, 'codex-app-server.scope')
+export const codexAppServerReceipt = (dir = runtimeRoot()) => join(dir, 'codex-app-server.detached.json')
 type CodexRuntimeGenerationProof = Readonly<{
-  pid: number
-  startToken: string
-  processGroupId: number
-  sessionId: number
-  isolation: string
+  identity: VerifiedDetachedRuntime
   socket: Readonly<{ path: string; dev: number; ino: number }>
 }>
 function codexRuntimeGenerationProof(dir = runtimeRoot()): CodexRuntimeGenerationProof | null {
   try {
     const pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim())
-    const start = processStartToken(pid)
-    const scope = readFileSync(codexAppServerIsolation(dir), 'utf8').trim()
-    const topology = processTopology(pid)
+    const detached = verifyDetachedRuntime(pid, codexAppServerReceipt(dir))
     const socketPath = codexAppServerSock(dir)
     const socket = statSync(socketPath)
-    if (!(pid > 0) || !start || !topology || topology.startToken !== start || topology.processGroupId !== pid || topology.sessionId !== pid ||
-      scope !== `detached-v3 ${pid} ${start} ${pid} ${pid}` || !socket.isSocket()) return null
+    if (!(pid > 0) || !detached.ok || !socket.isSocket()) return null
     return Object.freeze({
-      pid,
-      startToken: start,
-      processGroupId: topology.processGroupId,
-      sessionId: topology.sessionId,
-      isolation: scope,
+      identity: detached.identity,
       socket: Object.freeze({ path: socketPath, dev: socket.dev, ino: socket.ino }),
     })
   } catch { return null }
 }
 const codexRuntimeGenerationToken = (proof: CodexRuntimeGenerationProof) =>
-  `${proof.pid}|${proof.startToken}|${proof.processGroupId}|${proof.sessionId}|${proof.isolation}|${proof.socket.path}|${proof.socket.dev}:${proof.socket.ino}`
+  `${detachedRuntimeGenerationToken(proof.identity)}|${proof.socket.path}|${proof.socket.dev}:${proof.socket.ino}`
 function codexRuntimeGeneration(dir = runtimeRoot()): string | null {
   const proof = codexRuntimeGenerationProof(dir)
   return proof ? codexRuntimeGenerationToken(proof) : null
@@ -673,14 +679,14 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
   const tuiBypass = !codexCmd.includes('--dangerously-bypass-hook-trust') && codexSupportsBypassHookTrust(codexBinary(codexCmd)) ? ' --dangerously-bypass-hook-trust' : ''
   const sock = codexAppServerSock(dir)         // short sun_path-safe path in the owned tmp subdir/override — NOT under "$dir"
   const pid = codexAppServerPid(dir)
-  const isolation = codexAppServerIsolation(dir)
+  const receipt = codexAppServerReceipt(dir)
   const log = join(dir, 'codex-app-server.log')
   const lock = join(dir, 'codex-app-server.lock')
   const script = [
     `dir=${shQuote(dir)}`,
     `sock=${shQuote(sock)}`,
     `pid=${shQuote(pid)}`,
-    `isolation=${shQuote(isolation)}`,
+    `receipt=${shQuote(receipt)}`,
     `log=${shQuote(log)}`,
     `lock=${shQuote(lock)}`,
     // codex-launch's bypass-trust gate (and writeTrust's) resolves the codex binary from SPEXCODE_CODEX_CMD;
@@ -724,10 +730,10 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
     // mis-attributes; the id it needs — the ACTING thread's — codex injects per command, so stripping the
     // inherited ones removes a wrong answer without removing a right one ([[harness-adapter]]).
     // The adapter launches its shared control plane in a new OS process group + session. `nohup` alone was not
-    // a boundary: the Codex Node launcher reset signal handling and died with the tmux pane despite a matching
-    // stamp. The internal helper uses child_process detached=true, records PID/start plus the observed pgrp/sid,
-    // and refuses unless the live process is its own session leader. The stop guard re-reads that topology.
-    `  ( unset ${sessionIdentityEnvVars().join(' ')}; ${SPEX} internal shared-runtime-spawn "$dir" "$log" "$pid" "$isolation" ${server} app-server --listen "unix://$sock" ) || { rmdir "$lockd" 2>/dev/null; exit 1; }`,
+    // a boundary: the Codex Node launcher reset signal handling and died with the tmux pane. The internal helper
+    // uses child_process detached=true, then the process adapter publishes a private receipt only after proving
+    // exact PID/start + PGID (and Linux SID). Every consumer re-verifies that same receipt.
+    `  ( unset ${sessionIdentityEnvVars().join(' ')}; ${SPEX} internal shared-runtime-spawn "$dir" "$log" "$pid" "$receipt" ${server} app-server --listen "unix://$sock" ) || { rmdir "$lockd" 2>/dev/null; exit 1; }`,
     '  for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
     'fi',
     'rmdir "$lockd" 2>/dev/null',
@@ -820,6 +826,106 @@ function drainWsFrames(s: FrameState, conn: Socket, onText: (json: string) => vo
 const WS_UPGRADE = (key: string) => `GET /rpc HTTP/1.1\r\nHost: localhost\r\nConnection: Upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: ${key}\r\n\r\n`
 const wsInitialize: JsonRpc = { id: 1, method: 'initialize', params: { clientInfo: { name: 'spexcode', title: 'SpexCode', version: '0.0.0' }, capabilities: { experimentalApi: true, requestAttestation: false } } }
 
+// Codex has no StopFailure hook, but its app-server has the stronger native signal: every subscribed turn ends
+// with turn/completed and a final completed/interrupted/failed status. Rejoin is atomic with subscription, so
+// this observer also survives backend replacement; a thread already in systemError is reconciled from its
+// latest turn before later live notifications take over.
+export function codexTurnFailureObserver(
+  rec: HarnessDeliveryRecord,
+  onFailure: (failure: TurnFailure) => void,
+): FailureSubscription {
+  const threadId = rec.harnessSessionId
+  if (!threadId) return { close: () => {}, closed: Promise.resolve(null) }
+  const sock = codexAppServerSock(rec.runtimeDir || runtimeRoot())
+  const conn: Socket = createConnection(sock)
+  const frames: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
+  let upgraded = false, settled = false
+  let reconciliationTimer: ReturnType<typeof setTimeout> | null = null
+  let resolveClosed!: (reason: string | null) => void
+  const closed = new Promise<string | null>((resolve) => { resolveClosed = resolve })
+  const cancelReconciliation = () => {
+    if (!reconciliationTimer) return
+    clearTimeout(reconciliationTimer)
+    reconciliationTimer = null
+  }
+  const finish = (reason: string | null) => {
+    if (settled) return
+    settled = true
+    clearTimeout(timer)
+    cancelReconciliation()
+    try { conn.destroy() } catch {}
+    resolveClosed(reason)
+  }
+  const timer = setTimeout(() => finish('Codex turn observer did not subscribe within 5000ms'), 5000)
+  timer.unref?.()
+  const send = (message: JsonRpc) => conn.write(wsText(JSON.stringify(message)))
+  const report = (turn: unknown, fallbackMessage?: string) => {
+    const value = turn as { status?: unknown; completedAt?: unknown; error?: { message?: unknown } | null }
+    if (value?.status !== 'failed' && !fallbackMessage) return
+    const nativeMessage = typeof value?.error?.message === 'string' ? value.error.message.trim() : ''
+    onFailure({
+      message: nativeMessage || fallbackMessage || 'Codex turn failed',
+      completedAt: typeof value?.completedAt === 'number' && Number.isFinite(value.completedAt) ? value.completedAt : null,
+    })
+  }
+  conn.on('error', (error) => finish(`Codex turn observer connection failed: ${rpcError(error)}`))
+  conn.on('close', () => finish('Codex turn observer connection closed'))
+  conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))))
+  const handle = (json: string) => {
+    let message: JsonRpc
+    try { message = JSON.parse(json) } catch { return }
+    if (message.error) return finish(`Codex turn observer request failed: ${message.error.message || JSON.stringify(message.error)}`)
+    if (message.id === 1 && message.result) {
+      send({ method: 'initialized', params: {} })
+      return send({
+        id: 2,
+        method: 'thread/resume',
+        params: { threadId, excludeTurns: true, initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } },
+      })
+    }
+    if (message.id === 2 && message.result) {
+      clearTimeout(timer)
+      const result = message.result as { thread?: { status?: { type?: unknown } }; initialTurnsPage?: { data?: unknown } }
+      if (result.thread?.status?.type === 'systemError') {
+        const turns = result.initialTurnsPage?.data
+        const latest = Array.isArray(turns) ? turns[0] : null
+        // Give a concurrently-starting turn's native notification precedence over this historical snapshot.
+        reconciliationTimer = setTimeout(() => {
+          reconciliationTimer = null
+          report(latest, 'Codex thread entered systemError before the turn observer subscribed')
+        }, 100)
+        reconciliationTimer.unref?.()
+      }
+      return
+    }
+    if (message.method === 'turn/started') {
+      const params = message.params as { threadId?: unknown } | undefined
+      if (params?.threadId === threadId) cancelReconciliation()
+    }
+    if (message.method === 'turn/completed') {
+      const params = message.params as { threadId?: unknown; turn?: unknown } | undefined
+      if (params?.threadId === threadId) {
+        cancelReconciliation()
+        report(params.turn)
+      }
+    }
+  }
+  conn.on('data', (chunk: Buffer) => {
+    frames.buf = Buffer.concat([frames.buf, chunk])
+    if (!upgraded) {
+      const split = frames.buf.indexOf('\r\n\r\n')
+      if (split < 0) return
+      const head = frames.buf.slice(0, split).toString('utf8')
+      if (!/^HTTP\/1\.1 101/.test(head)) return finish(`Codex app-server refused turn observer: ${head.split('\r\n')[0]}`)
+      upgraded = true
+      frames.buf = frames.buf.slice(split + 4)
+      send(wsInitialize)
+    }
+    if (drainWsFrames(frames, conn, handle)) finish('Codex app-server closed the turn observer')
+  })
+  return { close: () => finish(null), closed }
+}
+
 // Protocol-verified cold/restore seam. The Codex schema (`codex app-server generate-json-schema --experimental`)
 // defines thread/archive and thread/unarchive with {threadId}; no guessed method or process command is used.
 type CodexGenerationFence = { dir: string; generation: string }
@@ -890,7 +996,14 @@ export const CODEX_THREAD_SOURCE_KINDS = [
   'cli', 'vscode', 'exec', 'appServer', 'subAgent', 'subAgentReview', 'subAgentCompact',
   'subAgentThreadSpawn', 'subAgentOther', 'unknown',
 ] as const
-function codexPagedIds(sock: string, method: 'thread/list' | 'thread/loaded/list', params: Record<string, unknown>, extractId: (item: unknown) => string | null, label: string): Promise<CodexPagedIdsResult> {
+function codexPagedIds(
+  sock: string,
+  method: 'thread/list' | 'thread/loaded/list',
+  params: Record<string, unknown>,
+  extractId: (item: unknown) => string | null,
+  label: string,
+  onItem?: (item: unknown) => void,
+): Promise<CodexPagedIdsResult> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
@@ -914,6 +1027,7 @@ function codexPagedIds(sock: string, method: 'thread/list' | 'thread/loaded/list
       if (message.id !== requestId || !message.result) return
       const page = message.result as { data?: unknown; nextCursor?: unknown }
       if (Array.isArray(page.data)) for (const item of page.data) {
+        onItem?.(item)
         const id = extractId(item)
         if (typeof id === 'string') ids.add(id)
       }
@@ -992,14 +1106,35 @@ function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok:
 // The app-server's loaded/list is cursor-paginated. Archive proof must scan every page; a first page that omits
 // a sibling/descendant is not a cold proof. This helper is also used by the descendant guard below.
 export function codexThreadList(sock: string, params: Record<string, unknown>): Promise<{ ok: true; ids: string[] } | { ok: false; error: string }> {
+  return codexThreadCollection(sock, params).then((result) => result.ok ? { ok: true, ids: result.ids } : result)
+}
+
+type CodexThreadCollectionResult =
+  | { ok: true; ids: string[]; parentById: Map<string, string | null> }
+  | { ok: false; error: string }
+
+function codexThreadCollection(sock: string, params: Record<string, unknown>): Promise<CodexThreadCollectionResult> {
   const sourceKinds = Array.isArray(params.sourceKinds) && params.sourceKinds.length
     ? params.sourceKinds
     : [...CODEX_THREAD_SOURCE_KINDS]
+  const parentById = new Map<string, string | null>()
+  const conflictingParents = new Set<string>()
   return codexPagedIds(sock, 'thread/list', { ...params, sourceKinds, useStateDbOnly: true }, (item) => {
     if (typeof item === 'string') return item
     const id = (item as { id?: unknown } | null)?.id
     return typeof id === 'string' ? id : null
-  }, 'thread/list')
+  }, 'thread/list', (item) => {
+    if (!item || typeof item !== 'object') return
+    const row = item as { id?: unknown; parentThreadId?: unknown }
+    if (typeof row.id !== 'string') return
+    const parent = typeof row.parentThreadId === 'string' ? row.parentThreadId : null
+    if (parentById.has(row.id) && parentById.get(row.id) !== parent) conflictingParents.add(row.id)
+    parentById.set(row.id, parent)
+  }).then((result) => {
+    if (!result.ok) return result
+    if (conflictingParents.size) return { ok: false as const, error: `Codex thread/list returned conflicting parent ownership for ${[...conflictingParents].join(', ')}` }
+    return { ...result, parentById }
+  })
 }
 
 async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()): Promise<SharedRuntimeMutationGuard> {
@@ -1029,28 +1164,194 @@ async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()):
   return { healthy: true, referenceIds, targetTurnPresence, descendantIds }
 }
 
-type CodexColdPreflight = { ok: true; alreadyCold?: boolean; guard: SharedRuntimeMutationGuard } | { ok: false; reason: string }
-async function codexColdPreflight(threadId: string, dir = runtimeRoot()): Promise<CodexColdPreflight> {
+const CODEX_COLD_PLAN = Symbol('codex-cold-plan')
+type CodexColdPlan = Readonly<{
+  [CODEX_COLD_PLAN]: true
+  kind: 'codex-cold-subtree-v1'
+  threadId: string
+  generation: string
+  guard: SharedRuntimeMutationGuard
+  descendantIds: readonly string[]
+  parentEdges: readonly (readonly [string, string])[]
+  subtreeIds: readonly string[]
+  activeIds: readonly string[]
+  archivedIds: readonly string[]
+}>
+type CodexColdPreflight = { ok: true; alreadyCold?: boolean; receipt: CodexColdPlan } | { ok: false; reason: string }
+
+const sameIdSet = (left: readonly string[], right: readonly string[]) =>
+  left.length === right.length && left.every((id) => right.includes(id))
+
+const sameParentEdges = (left: readonly (readonly [string, string])[], right: readonly (readonly [string, string])[]) =>
+  left.length === right.length && left.every(([id, parent]) => right.some(([otherId, otherParent]) => id === otherId && parent === otherParent))
+
+const isCodexColdPlan = (value: unknown): value is CodexColdPlan => {
+  if (!value || typeof value !== 'object') return false
+  const plan = value as Partial<CodexColdPlan>
+  return plan[CODEX_COLD_PLAN] === true && plan.kind === 'codex-cold-subtree-v1' && typeof plan.threadId === 'string' &&
+    typeof plan.generation === 'string' && Array.isArray(plan.descendantIds) &&
+    Array.isArray(plan.parentEdges) && Array.isArray(plan.subtreeIds) &&
+    Array.isArray(plan.activeIds) && Array.isArray(plan.archivedIds) && !!plan.guard
+}
+
+async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string): Promise<CodexColdPreflight> {
+  const generation = expectedGeneration ?? codexRuntimeGeneration(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)
-  const [guard, archivedList, activeList] = await Promise.all([
-    codexTargetMutationGuard(threadId, dir),
+  const [loaded, activeDescendants, archivedDescendants, archivedList, activeList] = await Promise.all([
+    codexLoadedReferenceIds(sock),
+    codexThreadCollection(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
+    codexThreadCollection(sock, { ancestorThreadId: threadId, archived: true, sourceKinds: [] }),
     codexThreadList(sock, { archived: true, sourceKinds: [] }),
     codexThreadList(sock, { archived: false, sourceKinds: [] }),
   ])
-  if (guard.descendantIds.length)
-    return { ok: false, reason: `Codex thread ${threadId} has owned descendants (${guard.descendantIds.join(', ')}); subtree archive is not proven safe` }
-  if (!guard.healthy) return { ok: false, reason: guard.error || `Codex thread ${threadId} target state is unknown` }
+  if (codexRuntimeGeneration(dir) !== generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed during subtree census' }
+  if (!loaded.ok) return { ok: false, reason: loaded.error }
+  if (!activeDescendants.ok) return { ok: false, reason: activeDescendants.error }
+  if (!archivedDescendants.ok) return { ok: false, reason: archivedDescendants.error }
   if (!archivedList.ok) return { ok: false, reason: archivedList.error }
   if (!activeList.ok) return { ok: false, reason: activeList.error }
-  const inArchived = archivedList.ids.includes(threadId)
-  const inActive = activeList.ids.includes(threadId)
-  if (inArchived === inActive) return { ok: false, reason: `Codex thread ${threadId} has ambiguous disk collection state (archived=${inArchived}, active=${inActive})` }
-  if (guard.targetTurnPresence === 'active') return { ok: false, reason: `Codex thread ${threadId} has an active turn; terminal-state confirmation is required before archive` }
-  if (guard.targetTurnPresence === 'unknown') return { ok: false, reason: `Codex thread ${threadId} turn state is unknown; refusing to archive without terminal-state confirmation` }
-  if (guard.targetTurnPresence === 'none')
-    return inArchived ? { ok: true, alreadyCold: true, guard } : { ok: true, guard }
-  if (inArchived) return { ok: false, reason: `Codex thread ${threadId} is archived but remains loaded` }
-  return { ok: true, guard }
+
+  const activeDescendantSet = new Set(activeDescendants.ids)
+  const archivedDescendantSet = new Set(archivedDescendants.ids)
+  const duplicateDescendants = activeDescendants.ids.filter((id) => archivedDescendantSet.has(id))
+  if (duplicateDescendants.length)
+    return { ok: false, reason: `Codex subtree members occur in both active and archived descendant collections (${duplicateDescendants.join(', ')})` }
+  const descendantIds = [...activeDescendants.ids, ...archivedDescendants.ids]
+  if (descendantIds.includes(threadId)) return { ok: false, reason: `Codex target ${threadId} is duplicated in its own descendant closure` }
+
+  const parentById = new Map([...activeDescendants.parentById, ...archivedDescendants.parentById])
+  const depthById = new Map<string, number>()
+  for (const id of descendantIds) {
+    const seen = new Set([id])
+    let cursor = id
+    let depth = 0
+    while (cursor !== threadId) {
+      const next = parentById.get(cursor)
+      if (!next) return { ok: false, reason: `Codex descendant ${id} has no complete parent chain to target ${threadId} (unowned or reassigned)` }
+      if (seen.has(next)) return { ok: false, reason: `Codex descendant ${id} has a cyclic parent chain` }
+      seen.add(next)
+      cursor = next
+      depth++
+    }
+    depthById.set(id, depth)
+  }
+
+  const activeSet = new Set(activeList.ids)
+  const archivedSet = new Set(archivedList.ids)
+  const subtreeIds = [...descendantIds, threadId]
+  for (const id of subtreeIds) {
+    const inActive = activeSet.has(id)
+    const inArchived = archivedSet.has(id)
+    if (!inActive && !inArchived)
+      return { ok: false, reason: `Codex subtree member ${id} is absent from both native collections (unowned or reassigned)` }
+    if (inActive && inArchived)
+      return { ok: false, reason: `Codex subtree member ${id} occurs in both active and archived native collections` }
+    if (id !== threadId) {
+      const expectedActive = activeDescendantSet.has(id)
+      if (inActive !== expectedActive)
+        return { ok: false, reason: `Codex subtree member ${id} changed collection assignment during ownership census` }
+    }
+  }
+
+  const loadedSet = new Set(loaded.referenceIds)
+  const loadedSubtreeIds = subtreeIds.filter((id) => loadedSet.has(id))
+  const turnStates = await Promise.all(loadedSubtreeIds.map(async (id) => ({ id, state: await codexTargetTurnPresence(sock, id) })))
+  if (codexRuntimeGeneration(dir) !== generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed during subtree turn census' }
+  for (const { id, state } of turnStates) {
+    if (!state.ok) return { ok: false, reason: state.error }
+    if (state.turnPresence === 'active') return { ok: false, reason: `Codex subtree member ${id} has an active turn` }
+    if (state.turnPresence === 'unknown') return { ok: false, reason: `Codex subtree member ${id} turn state is unknown` }
+    if (archivedSet.has(id)) return { ok: false, reason: `Codex archived subtree member ${id} remains loaded` }
+  }
+
+  const targetTurnPresence: SharedRuntimeMutationGuard['targetTurnPresence'] = loadedSet.has(threadId) ? 'idle' : 'none'
+  const guard: SharedRuntimeMutationGuard = {
+    healthy: true,
+    referenceIds: [...loaded.referenceIds],
+    targetTurnPresence,
+    descendantIds: [...descendantIds],
+  }
+  const activeIds = [...activeDescendants.ids]
+    .sort((left, right) => (depthById.get(right) ?? 0) - (depthById.get(left) ?? 0))
+    .concat(activeSet.has(threadId) ? [threadId] : [])
+  const archivedIds = [...archivedDescendants.ids, ...(archivedSet.has(threadId) ? [threadId] : [])]
+  const parentEdges = descendantIds.map((id) => [id, parentById.get(id)!] as const)
+  const receipt: CodexColdPlan = Object.freeze({
+    [CODEX_COLD_PLAN]: true as const,
+    kind: 'codex-cold-subtree-v1',
+    threadId,
+    generation,
+    guard,
+    descendantIds: Object.freeze([...descendantIds]),
+    parentEdges: Object.freeze(parentEdges),
+    subtreeIds: Object.freeze([...subtreeIds]),
+    activeIds: Object.freeze(activeIds),
+    archivedIds: Object.freeze(archivedIds),
+  })
+  return { ok: true, ...(activeIds.length ? {} : { alreadyCold: true }), receipt }
+}
+
+async function codexMutationGuard(
+  threadId: string,
+  dir = runtimeRoot(),
+  opts: { coldReceipt?: unknown } = {},
+): Promise<SharedRuntimeMutationGuard> {
+  if (opts.coldReceipt === undefined) return codexTargetMutationGuard(threadId, dir)
+  if (!isCodexColdPlan(opts.coldReceipt) || opts.coldReceipt.threadId !== threadId)
+    return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'adapter cold teardown receipt is invalid' }
+  const current = await codexColdPreflight(threadId, dir, opts.coldReceipt.generation)
+  if (!current.ok) {
+    const guard = await codexTargetMutationGuard(threadId, dir)
+    return { ...guard, healthy: false, coldTeardownAuthorized: false, error: current.reason }
+  }
+  const authorized = sameIdSet(opts.coldReceipt.descendantIds, current.receipt.descendantIds) &&
+    sameParentEdges(opts.coldReceipt.parentEdges, current.receipt.parentEdges) &&
+    sameIdSet(opts.coldReceipt.activeIds, current.receipt.activeIds) &&
+    sameIdSet(opts.coldReceipt.archivedIds, current.receipt.archivedIds)
+  return {
+    ...current.receipt.guard,
+    healthy: authorized,
+    coldTeardownAuthorized: authorized,
+    ...(authorized ? {} : { error: 'adapter cold teardown receipt no longer matches the target subtree' }),
+  }
+}
+
+async function codexRestoreColdPlan(plan: CodexColdPlan, dir = runtimeRoot()): Promise<{ ok: true } | { ok: false; reason: string }> {
+  if (codexRuntimeGeneration(dir) !== plan.generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' }
+  const sock = codexAppServerSock(dir)
+  const [activeBefore, archivedBefore] = await Promise.all([
+    codexThreadList(sock, { archived: false, sourceKinds: [] }),
+    codexThreadList(sock, { archived: true, sourceKinds: [] }),
+  ])
+  if (!activeBefore.ok || !archivedBefore.ok)
+    return { ok: false, reason: 'archive state is unknown and could not be reconciled' }
+  if (codexRuntimeGeneration(dir) !== plan.generation)
+    return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' }
+  const activeSet = new Set(activeBefore.ids)
+  const archivedSet = new Set(archivedBefore.ids)
+  if (plan.archivedIds.some((id) => !archivedSet.has(id) || activeSet.has(id)))
+    return { ok: false, reason: 'an originally-archived Codex subtree member changed collection; compensation was not authorized' }
+  if (plan.activeIds.some((id) => activeSet.has(id) === archivedSet.has(id)))
+    return { ok: false, reason: 'an originally-active Codex subtree member has ambiguous collection state' }
+  const fence = { dir, generation: plan.generation }
+  const restoreIds = [...plan.activeIds].reverse().filter((id) => archivedSet.has(id))
+  for (const id of restoreIds) {
+    const restored = await codexThreadMutation(sock, 'thread/unarchive', id, fence)
+    if (!restored.ok) return { ok: false, reason: `compensation failed for ${id}: ${restored.error}` }
+  }
+  const [activeAfter, archivedAfter] = await Promise.all([
+    codexThreadList(sock, { archived: false, sourceKinds: [] }),
+    codexThreadList(sock, { archived: true, sourceKinds: [] }),
+  ])
+  const restored = activeAfter.ok && archivedAfter.ok && codexRuntimeGeneration(dir) === plan.generation &&
+    plan.activeIds.every((id) => activeAfter.ids.includes(id) && !archivedAfter.ids.includes(id)) &&
+    plan.archivedIds.every((id) => archivedAfter.ids.includes(id) && !activeAfter.ids.includes(id))
+  return restored ? { ok: true } : { ok: false, reason: 'compensation failed or archive state is unknown' }
 }
 
 // Read a loaded thread id off the app-server via `thread/loaded/list`. With the backend now OWNING the thread
@@ -1116,6 +1417,8 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRunt
     const listener = await listenerAt(sock, 800)
     if (!pidLive && listener === 'dead') return { healthy: true, references: [] }
     if (!pidLive || listener !== 'live') return { healthy: false, references: [], error: 'Codex shared root state is unknown (PID/listener identity is not proven)' }
+    const generation = codexRuntimeGeneration(dir)
+    if (!generation) return { healthy: false, references: [], error: 'Codex shared root detached receipt/socket generation is not proven' }
     return new Promise<SharedRuntimeProbe>((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
@@ -1133,7 +1436,9 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRunt
       settled = true
       clearTimeout(timer)
       try { conn.destroy() } catch { /* */ }
-      resolve(result)
+      resolve(result.healthy && codexRuntimeGeneration(dir) !== generation
+        ? { healthy: false, references: result.references, error: 'Codex shared root detached receipt/socket generation changed during ownership probe' }
+        : result)
     }
     const fail = (error: string) => done({ healthy: false, references: [...references.values()], error })
     timer = setTimeout(() => fail('codex app-server ownership probe timed out after 5000ms'), 5000)
@@ -1592,16 +1897,16 @@ function isTrackedFile(proj: string, f: string): boolean {
 // block; the skill/agent files sit at name-scoped paths reconstructed from `arts`. So it removes ONLY our own
 // blocks and our own named products — never a user's CLAUDE.md/AGENTS.md prose, a hand-made settings.json, or
 // a sibling skill/agent the user added, and NEVER any .spec data.
-function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts): void {
+function cleanHarness(h: Harness, proj: string, arts: HarnessArtifacts, preserveProject = false): void {
   // deleteIfEmpty ONLY for an UNTRACKED contract file: a wholly-ours generated file goes; a HOST-TRACKED file
   // that carried nothing but our block (an empty committed CLAUDE.md we folded into) is stripped back to its
   // pristine emptiness but never deleted — deleting a tracked file would surface as a `D` in the host's status.
   for (const f of h.contractFiles(proj)) removeManagedBlock(f, ['<!-- ', ' -->'], !isTrackedFile(proj, f))
   const shim = h.shimFile(proj)
-  if (existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh')) rmSync(shim, { force: true })
+  if ((h.shimScope === 'tree' || !preserveProject) && existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh')) rmSync(shim, { force: true })
   const anchor = h.worktreeHookAnchor(proj)   // the linked-worktree anchor copy, same identity gate as the shim
   if (anchor && existsSync(anchor) && readFileSync(anchor, 'utf8').includes('dispatch.sh')) rmSync(anchor, { force: true })
-  h.removeTrust(proj)
+  if (!preserveProject) h.removeTrust(proj)
   const sd = h.skillDir(proj)
   if (sd) for (const n of arts.skills) rmSync(join(sd, n), { recursive: true, force: true })
   const ad = h.agentDir(proj)
@@ -1758,6 +2063,7 @@ const noLaunchEnv = (): string[] => []
 
 export const claudeHarness: Harness = {
   id: 'claude',
+  dispatchId: 'claude',
   headless: false,
   events: CLAUDE_EVENTS,
   ownsRendezvous: true,                              // reclaude opens the rendezvous control socket (prompt delivery + liveness)
@@ -1768,6 +2074,7 @@ export const claudeHarness: Harness = {
   sessionEnvVar: 'CLAUDE_CODE_SESSION_ID',
   launchEnv: rendezvousLaunchEnv,
   shimFile: (proj) => join(proj, '.claude', 'settings.json'),
+  shimScope: 'tree',
   worktreeHookAnchor: () => null,                    // claude's shim already lives in the worktree (.claude/settings.json) — self-anchors, no root rewrite
   contractFiles: (proj) => [join(proj, 'CLAUDE.md')],
   skillDir: (proj) => join(proj, '.claude', 'skills'),
@@ -1775,7 +2082,7 @@ export const claudeHarness: Harness = {
   shim: (dispatch, spex) => buildShim('claude', CLAUDE_EVENTS, dispatch, spex),
   writeTrust: () => [],                            // Claude relies on folder-trust — no artifact to report
   removeTrust: () => { /* Claude wrote no trust — nothing to strip */ },
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: claudeSlashCommands,
   // online iff the window is up AND a LIVE LISTENER is on the rendezvous socket (`socketLive`, connect-probed by
   // the caller) — NOT the mere existence of a stale socket FILE a crashed claude leaves behind (the 30-min
@@ -1825,6 +2132,7 @@ export const claudeHeadlessHarness: Harness = {
 
 export const codexHarness: Harness = {
   id: 'codex',
+  dispatchId: 'codex',
   headless: false,
   sharedRuntimeSpawn: true,
   events: CODEX_EVENTS,
@@ -1843,6 +2151,7 @@ export const codexHarness: Harness = {
   // per-worktree (codex loads THOSE by walking the thread cwd). dispatch.sh resolves `proj` from the thread
   // cwd, so one shared shim serves every worktree.
   shimFile: (proj) => join(mainCheckout(proj), '.codex', 'hooks.json'),
+  shimScope: 'project',
   // a LINKED worktree also needs its OWN `.codex/hooks.json` so codex-rs anchors the project config layer for
   // the worktree cwd (without a `.codex/` under the worktree root, codex builds no layer, so the rewritten
   // root-checkout hooks are never discovered and NO hooks fire — bypass_hook_trust cannot rescue a layer that
@@ -1875,7 +2184,7 @@ export const codexHarness: Harness = {
   writeTrust: (proj, cmdFor) => [writeCodexTrust(mainCheckout(proj), CODEX_EVENTS, cmdFor)],
   // trust is keyed by the MAIN checkout (where the codex shim materializes) — strip it at the same key.
   removeTrust: (proj) => removeCodexTrust(mainCheckout(proj)),
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: codexSlashCommands,
   // online iff the tmux window is up AND the agent is live. PRIMARY: the launch-registered `agent.pid` hot-tier
   // verdict (`pidAlive`) — a 100ms syscall (kill-0), no ps scan. LEGACY: a pre-registration session has no
@@ -1891,6 +2200,7 @@ export const codexHarness: Harness = {
   },
   leafOwnerNeedle: (rec) => rec.harnessSessionId ?? null,
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
+  observeTurnFailures: codexTurnFailureObserver,
   cleanupRuntime: async () => { /* project-scoped app-server is shared; no per-session transport to remove */ },
   coldRetirementPreflight: async (rec) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
@@ -1898,75 +2208,67 @@ export const codexHarness: Harness = {
     const dir = runtimeRoot()
     const generationBefore = codexRuntimeGeneration(dir)
     if (!generationBefore) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
-    const sock = codexAppServerSock(dir)
-    const [guard, archivedList, activeList] = await Promise.all([
-      codexTargetMutationGuard(threadId, dir),
-      codexThreadList(sock, { archived: true, sourceKinds: [] }),
-      codexThreadList(sock, { archived: false, sourceKinds: [] }),
-    ])
+    const result = await codexColdPreflight(threadId, dir, generationBefore)
     if (codexRuntimeGeneration(dir) !== generationBefore)
       return { ok: false, reason: 'shared Codex app-server generation changed during cold retirement guard' }
-    if (guard.descendantIds.length) return { ok: false, reason: `Codex thread ${threadId} has owned descendants (${guard.descendantIds.join(', ')}); cold retirement is not proven safe` }
-    if (!guard.healthy) return { ok: false, reason: guard.error || `Codex thread ${threadId} target state is unknown` }
-    if (!archivedList.ok) return { ok: false, reason: archivedList.error }
-    if (!activeList.ok) return { ok: false, reason: activeList.error }
-    if (guard.targetTurnPresence !== 'none') return { ok: false, reason: `Codex thread ${threadId} is still loaded` }
-    const inArchived = archivedList.ids.includes(threadId)
-    const inActive = activeList.ids.includes(threadId)
-    if (!inArchived || inActive) return { ok: false, reason: `Codex thread ${threadId} is not uniquely in the archived collection (archived=${inArchived}, active=${inActive})` }
+    if (!result.ok) return result
+    if (!result.alreadyCold)
+      return { ok: false, reason: `Codex target subtree ${result.receipt.activeIds.join(', ')} is not fully archived` }
     return { ok: true, alreadyCold: true }
   },
   coldPreflight: async (rec) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
-    const result = await codexColdPreflight(rec.harnessSessionId)
-    return result.ok ? { ok: true, ...(result.alreadyCold ? { alreadyCold: true } : {}) } : result
+    return codexColdPreflight(rec.harnessSessionId)
   },
-  coldRuntime: async (rec) => {
+  coldRuntime: async (rec, suppliedReceipt) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
     const threadId = rec.harnessSessionId
-    const sock = codexAppServerSock(runtimeRoot())
-    const generationBefore = codexRuntimeGeneration(runtimeRoot())
+    const dir = runtimeRoot()
+    const sock = codexAppServerSock(dir)
+    const generationBefore = codexRuntimeGeneration(dir)
     if (!generationBefore) return { ok: false, reason: 'Codex shared app-server generation is unproven' }
-    const preflight = await codexColdPreflight(threadId)
-    if (preflight && !preflight.ok) return preflight
-    if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore) return { ok: false, reason: 'shared Codex app-server generation changed during target guard' }
-    if (preflight?.ok && preflight.alreadyCold) return { ok: true }
-    const siblingBefore = preflight.guard.referenceIds.filter((referenceId) => referenceId !== threadId)
+    if (suppliedReceipt !== undefined && (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== threadId))
+      return { ok: false, reason: 'Codex cold teardown receipt is missing, malformed, or names a different target' }
+    const frozenPlan = isCodexColdPlan(suppliedReceipt) ? suppliedReceipt : null
+    if (frozenPlan && frozenPlan.generation !== generationBefore)
+      return { ok: false, reason: 'shared Codex app-server generation changed after archive preflight' }
+    const preflight = await codexColdPreflight(threadId, dir, frozenPlan?.generation ?? generationBefore)
+    if (!preflight.ok) return preflight
+    const plan = frozenPlan ?? preflight.receipt
+    if (frozenPlan && (!sameIdSet(frozenPlan.descendantIds, preflight.receipt.descendantIds) ||
+      !sameParentEdges(frozenPlan.parentEdges, preflight.receipt.parentEdges) ||
+      !sameIdSet(frozenPlan.activeIds, preflight.receipt.activeIds) ||
+      !sameIdSet(frozenPlan.archivedIds, preflight.receipt.archivedIds)))
+      return { ok: false, reason: 'Codex target subtree ownership or collection assignment changed after archive preflight' }
+    if (codexRuntimeGeneration(dir) !== plan.generation)
+      return { ok: false, reason: 'shared Codex app-server generation changed during target subtree guard' }
+    if (plan.activeIds.length === 0) return { ok: true }
+    const subtreeSet = new Set(plan.subtreeIds)
+    const siblingBefore = plan.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId))
+    const fence = { dir, generation: plan.generation }
+
+    const compensate = async (reason: string): Promise<{ ok: false; reason: string }> => {
+      const restored = await codexRestoreColdPlan(plan, dir)
+      return { ok: false, reason: restored.ok ? reason : `${reason}; ${restored.reason}` }
+    }
+
     const coldCheck = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
-      const [guard, archivedList, activeList] = await Promise.all([
-        codexTargetMutationGuard(threadId),
-        codexThreadList(sock, { archived: true, sourceKinds: [] }),
-        codexThreadList(sock, { archived: false, sourceKinds: [] }),
-      ])
-      if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore) return { ok: false, reason: 'shared Codex app-server generation changed during archive' }
-      if (guard.descendantIds.length) return { ok: false, reason: `Codex thread ${threadId} acquired owned descendants during archive (${guard.descendantIds.join(', ')})` }
-      if (!guard.healthy) return { ok: false, reason: guard.error || 'Codex post-archive target guard is unhealthy' }
-      if (!archivedList.ok) return { ok: false, reason: archivedList.error }
-      if (!activeList.ok) return { ok: false, reason: activeList.error }
-      if (guard.targetTurnPresence !== 'none') return { ok: false, reason: `Codex thread ${threadId} remains loaded after thread/archive` }
-      if (!archivedList.ids.includes(threadId)) return { ok: false, reason: `Codex thread ${threadId} is absent from both loaded and archived collections` }
-      if (activeList.ids.includes(threadId)) return { ok: false, reason: `Codex thread ${threadId} remains in the non-archived collection` }
-      const afterIds = new Set(guard.referenceIds.filter((referenceId) => referenceId !== threadId))
+      const after = await codexColdPreflight(threadId, dir, plan.generation)
+      if (!after.ok) return after
+      if (codexRuntimeGeneration(dir) !== plan.generation) return { ok: false, reason: 'shared Codex app-server generation changed during archive' }
+      if (!sameIdSet(plan.descendantIds, after.receipt.descendantIds) || !sameParentEdges(plan.parentEdges, after.receipt.parentEdges))
+        return { ok: false, reason: `Codex target descendant closure changed during archive (before=${plan.descendantIds.join(', ')}; after=${after.receipt.descendantIds.join(', ')})` }
+      if (after.receipt.activeIds.length)
+        return { ok: false, reason: `Codex target subtree remains in the active collection (${after.receipt.activeIds.join(', ')})` }
+      if (!sameIdSet(plan.subtreeIds, after.receipt.archivedIds))
+        return { ok: false, reason: 'Codex target subtree is not uniquely archived after cold teardown' }
+      const afterIds = new Set(after.receipt.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId)))
       if (siblingBefore.some((referenceId) => !afterIds.has(referenceId))) return { ok: false, reason: 'a pre-existing shared Codex sibling reference disappeared during archive' }
       return { ok: true }
     }
-    const fence = { dir: runtimeRoot(), generation: generationBefore }
-    const archived = await codexThreadMutation(sock, 'thread/archive', rec.harnessSessionId, fence)
-    if (!archived.ok) {
-      if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore)
-        return { ok: false, reason: `${archived.error}; shared Codex app-server generation changed, so archive state is unknown and no compensation was attempted` }
-      // RPC transport failure is commit-unknown. Reconcile collections before deciding whether compensation is needed.
-      const [archivedList, activeList] = await Promise.all([
-        codexThreadList(sock, { archived: true, sourceKinds: [] }),
-        codexThreadList(sock, { archived: false, sourceKinds: [] }),
-      ])
-      if (archivedList.ok && archivedList.ids.includes(rec.harnessSessionId)) {
-        const restored = await codexThreadMutation(sock, 'thread/unarchive', rec.harnessSessionId, fence)
-        const stillActive = await codexThreadList(sock, { archived: false, sourceKinds: [] })
-        const suffix = restored.ok && stillActive.ok && stillActive.ids.includes(rec.harnessSessionId) ? '' : '; compensation/reconciliation failed'
-        return { ok: false, reason: `${archived.error}${suffix}` }
-      }
-      return { ok: false, reason: archivedList.ok && activeList.ok ? archived.error : `${archived.error}; archive state is unknown and could not be reconciled` }
+    for (const id of plan.activeIds) {
+      const archived = await codexThreadMutation(sock, 'thread/archive', id, fence)
+      if (!archived.ok) return compensate(`${archived.error} while archiving Codex subtree member ${id}`)
     }
     let verified: { ok: true } | { ok: false; reason: string } = { ok: false, reason: 'Codex archive verification timed out' }
     const verifyDeadline = Date.now() + 30_000
@@ -1976,15 +2278,15 @@ export const codexHarness: Harness = {
       if (Date.now() < verifyDeadline) await new Promise((resolve) => setTimeout(resolve, 100))
     }
     if (verified.ok) return verified
-    if (codexRuntimeGeneration(runtimeRoot()) !== generationBefore)
-      return { ok: false, reason: `${verified.reason}; shared Codex app-server generation changed, so no compensation was attempted` }
-    const restored = await codexThreadMutation(sock, 'thread/unarchive', rec.harnessSessionId, fence)
-    const active = await codexThreadList(sock, { archived: false, sourceKinds: [] })
-    const suffix = restored.ok && active.ok && active.ids.includes(rec.harnessSessionId) ? '' : '; compensation failed or archive state is unknown'
-    return { ok: false, reason: `${verified.reason}${suffix}` }
+    return compensate(verified.reason)
   },
-  restoreRuntime: async (rec) => {
+  restoreRuntime: async (rec, suppliedReceipt) => {
     if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
+    if (suppliedReceipt !== undefined) {
+      if (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== rec.harnessSessionId)
+        return { ok: false, reason: 'Codex cold compensation receipt is invalid or names a different target' }
+      return codexRestoreColdPlan(suppliedReceipt)
+    }
     const sock = codexAppServerSock(runtimeRoot())
     const reconcile = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
       const [active, archived] = await Promise.all([
@@ -2006,7 +2308,7 @@ export const codexHarness: Harness = {
     key: 'codex-app-server',
     label: 'Codex app-server',
     pidFile: codexAppServerPid(runtimeDir),
-    isolationFile: codexAppServerIsolation(runtimeDir),
+    receiptFile: codexAppServerReceipt(runtimeDir),
     residency: async () => {
       const sock = codexAppServerSock(runtimeDir)
       let pid = 0
@@ -2021,7 +2323,7 @@ export const codexHarness: Harness = {
       const result = await codexLoadedReferenceIds(sock)
       return result.ok ? { healthy: true, referenceIds: result.referenceIds } : { healthy: false, referenceIds: [], error: result.error }
     },
-    mutationGuard: (targetReferenceId) => codexTargetMutationGuard(targetReferenceId, runtimeDir),
+    mutationGuard: (targetReferenceId, opts) => codexMutationGuard(targetReferenceId, runtimeDir, opts),
     probe: () => codexSharedRuntimeProbe(runtimeDir),
   }],
   // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
@@ -2167,6 +2469,7 @@ export const codexHeadlessHarness: Harness = {
 // one-run defence. See pi-harness.ts for the extension source + trust mechanics.
 export const piHarness: Harness = {
   id: 'pi',
+  dispatchId: 'pi',
   headless: false,
   events: PI_EVENTS,
   ownsRendezvous: true,                              // the generated extension binds rvSock(id) and speaks the reclaude protocol
@@ -2177,6 +2480,7 @@ export const piHarness: Harness = {
   sessionEnvVar: 'PI_SESSION_ID',                    // exported by the generated extension at session_start; tool subprocesses inherit it
   launchEnv: rendezvousLaunchEnv,
   shimFile: (proj) => join(proj, '.pi', 'extensions', 'spexcode.ts'),
+  shimScope: 'tree',
   worktreeHookAnchor: () => null,                    // the extension lives in the worktree and self-anchors, like claude
   contractFiles: (proj) => [join(proj, 'AGENTS.md')],   // pi auto-loads AGENTS.md context files (shared with codex — writeManagedBlock is idempotent)
   skillDir: (proj) => join(proj, '.pi', 'skills'),   // Agent Skills standard dirs, discovered after project trust
@@ -2187,7 +2491,7 @@ export const piHarness: Harness = {
   }),
   writeTrust: (proj) => [writePiTrust(mainCheckout(proj))], // trust keys on the MAIN checkout; nearest-parent lookup covers worktrees
   removeTrust: (proj) => removePiTrust(mainCheckout(proj)),
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: piSlashCommands,
   // claude's exact liveness: the window is up AND a live LISTENER answers on the rendezvous socket — the
   // socket the generated extension binds. socketLive is already probed for every windowed session.
@@ -2222,6 +2526,7 @@ export const piHeadlessHarness: Harness = {
 
 export const opencodeHarness: Harness = {
   id: 'opencode',
+  dispatchId: 'opencode',
   headless: false,
   events: OPENCODE_EVENTS,
   // LITERALLY true: the generated plugin ([[opencode-harness]], opencode.ts) BINDS the per-session rendezvous
@@ -2241,6 +2546,7 @@ export const opencodeHarness: Harness = {
   // the "shim" is a generated opencode PLUGIN in the worktree's own tree — opencode auto-loads project plugins
   // by walking the cwd, so like claude it self-anchors and needs no root-checkout rewrite or worktree anchor.
   shimFile: (proj) => join(proj, '.opencode', 'plugins', 'spexcode.ts'),
+  shimScope: 'tree',
   worktreeHookAnchor: () => null,
   contractFiles: (proj) => [join(proj, 'AGENTS.md')],   // opencode reads AGENTS.md natively (same file codex owns; the managed block is idempotent across writers)
   skillDir: (proj) => join(proj, '.opencode', 'skills'),
@@ -2250,7 +2556,7 @@ export const opencodeHarness: Harness = {
   shim: (dispatch, spex) => ({ content: opencodePluginSource(dispatch, spex), cmd: (e) => `SPEX='${spex}' bash ${dispatch} opencode ${e}` }),
   writeTrust: () => [],                            // permission policy stays with the launcher command; no trust artifact to report
   removeTrust: () => { /* nothing was written */ },
-  clean(proj, arts) { cleanHarness(this, proj, arts) },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
   slashCommands: opencodeSlashCommands,
   // online iff the window is up AND the agent answers on a channel: PREFER the rendezvous socket listener
   // (the plugin is alive), FALL BACK to the launch-registered agent.pid (kill-0) so a plugin that failed to