spexcode 0.6.0 → 0.6.2

package/spec-cli/src/harness.ts

@@ -1,5 +1,5 @@
 import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, basename } from 'node:path'
 import { homedir, tmpdir } from 'node:os'
 import { createHash, randomBytes } from 'node:crypto'
 import { createConnection, type Socket } from 'node:net'
@@ -18,6 +18,8 @@ import { git } from './git.js'
 import { shQuote } from './sh.js'
 import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime, type VerifiedDetachedRuntime } from './process-identity.js'
 import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, resolveCodexGenerationForSession, type CodexGenerationEndpoint } from './codex-runtime-generations.js'
+import { writeFileIfChanged } from './file-write.js'
+import { codexRolloutPath, noExecutionTrace, readCodexExecutionTrace, readLocalStoreExecutionTrace, readProjectJsonlExecutionTrace, readSessionJsonlExecutionTrace, type ExecutionTrace, type ExecutionTurn } from './execution-trace.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
@@ -31,7 +33,7 @@ import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGenera
 // payload shape. On the TS side the harness is derived from the selected launcher or ALL adapters at once
 // (materialize writes every harness's artifacts).
 
-export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-headless' | 'codex-headless' | 'opencode-headless' | 'pi-headless'
+export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'zcode' | 'claude-headless' | 'codex-headless' | 'opencode-headless' | 'pi-headless'
 export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null; stopped?: boolean; archived?: boolean }
 export type HarnessLaunchReadyRecord = HarnessLivenessRecord & { governed?: boolean; runtimeDir: string }
 export type HarnessLaunchReadinessFence = {
@@ -148,7 +150,7 @@ 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'
+  readonly dispatchId: 'claude' | 'codex' | 'opencode' | 'pi' | 'zcode'
   // 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
@@ -182,6 +184,9 @@ export interface Harness {
   // instead of showing the folder name. This is the ONLY harness branch in the headline path: the capability
   // is data on the adapter, not an `if (codex)` in sessions.ts.
   readonly paneTitleIsSelfSummary: boolean
+  // The adapter-only native transcript reader. Its compact result has no raw envelope, argument, output, or
+  // reasoning data; product surfaces receive only the latest working note and typed tool steps.
+  executionTrace(threadId: string, turn: ExecutionTurn | null): ExecutionTrace | null
   // --- launch / sessionId ---
   // the base agent command. Claude: `claude …`; Codex starts a project-scoped app-server and launches the
   // visible TUI with `--remote` pointed at it. `cmd` is the SESSION's persisted launcher command
@@ -522,7 +527,62 @@ const SPEX = join(PKG, 'bin', 'spex.mjs')
 
 // The timeline is the message's copy, so rendezvous needs no receipt protocol. It writes one idempotent poke
 // carrying the timeline mid and reports only whether that write reached the local transport.
-function replyViaSocket(sock: string, text: string, mid?: string): Promise<DispatchResult> {
+type ClaudeForkTransport = { sock: string; auth: string }
+
+// The backend need not share the agent's config root: an explicitly chosen launcher can point Claude at its
+// own home. A moved source process remains alive by definition, so its one config-dir environment field is the
+// live authority for locating the daemon roster. A stale/reused pid can at worst name a roster with no exact
+// successor; it cannot select one without the moved/session-source checks below.
+function claudeConfigRoots(sourceSessionId: string, runtimeDir?: string): string[] {
+  const roots: string[] = []
+  try {
+    const pidFile = runtimeDir ? join(runtimeDir, 'sessions', sourceSessionId, 'agent.pid') : sessionArtifactPath(sourceSessionId, 'agent.pid')
+    const pid = Number(readFileSync(pidFile, 'utf8').trim())
+    if (Number.isInteger(pid) && pid > 0) {
+      const env = readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0')
+      const config = env.find((entry) => entry.startsWith('CLAUDE_CONFIG_DIR='))?.slice('CLAUDE_CONFIG_DIR='.length)
+      if (config) roots.push(config)
+    }
+  } catch { /* source not available or this platform does not expose procfs */ }
+  if (process.env.CLAUDE_CONFIG_DIR) roots.push(process.env.CLAUDE_CONFIG_DIR)
+  roots.push(join(homedir(), '.claude'))
+  return [...new Set(roots)]
+}
+
+// A moved Claude conversation is a daemon-owned fork. Its launch-time socket still answers, but that process
+// no longer returns to its prompt. A successor hook may have already recorded its exact Claude session id in
+// `moved`; use that durable identity first, then retain the roster's source-transcript relation for deployments
+// without the stamp. The roster remains the sole source of the live socket and current auth token. Keep this
+// lookup Claude-local so other rendezvous adapters cannot adopt a coincidentally matching id.
+function claudeForkTransport(sourceSessionId: string, runtimeDir?: string): ClaudeForkTransport | null {
+  const moved = (() => {
+    try {
+      const stamp = runtimeDir ? join(runtimeDir, 'sessions', sourceSessionId, 'moved') : sessionArtifactPath(sourceSessionId, 'moved')
+      return readFileSync(stamp, 'utf8').trim()
+    } catch {
+      return ''
+    }
+  })()
+  for (const configDir of claudeConfigRoots(sourceSessionId, runtimeDir)) {
+    try {
+      const roster = JSON.parse(readFileSync(join(configDir, 'daemon', 'roster.json'), 'utf8')) as { workers?: Record<string, any> }
+      const workers = Object.values(roster.workers ?? {})
+      const usable = (worker: any) => typeof worker?.rendezvousSock === 'string' && typeof worker.rvAuth === 'string'
+      const recorded = workers.filter((worker) => usable(worker) && moved && worker?.sessionId === moved)
+      const candidates = recorded.length ? recorded : workers.filter((worker) => {
+        const launch = worker?.dispatch?.launch
+        if (launch?.mode !== 'resume' || launch.fork !== true || typeof launch.sessionId !== 'string') return false
+        const source = basename(launch.sessionId).replace(/\.jsonl$/, '')
+        return source === sourceSessionId && usable(worker)
+      })
+      const worker = candidates.sort((a, b) => Number(b.startedAt ?? 0) - Number(a.startedAt ?? 0))[0]
+      if (worker) return { sock: worker.rendezvousSock, auth: worker.rvAuth }
+    } catch { /* this Claude config has no readable daemon roster */ }
+  }
+  return null
+}
+
+function replyViaSocket(sock: string, text: string, mid?: string, auth?: string): Promise<DispatchResult> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection>
@@ -544,7 +604,7 @@ function replyViaSocket(sock: string, text: string, mid?: string): Promise<Dispa
     })
     c.on('close', () => done({ ok: false, error: 'rendezvous connection closed before the poke was written' }))
     c.on('connect', () => c.write(
-      JSON.stringify({ type: 'reply', text, ...(mid ? { mid } : {}) }) + '\n',
+      `${auth ? JSON.stringify({ role: 'controller', auth }) + '\n' : ''}${JSON.stringify({ type: 'reply', text, ...(mid ? { mid } : {}) })}\n`,
       (error) => {
         if (error) return done({ ok: false, error: `rendezvous socket write failed: ${error.message}` })
         c.end()
@@ -554,16 +614,32 @@ function replyViaSocket(sock: string, text: string, mid?: string): Promise<Dispa
   })
 }
 const POKE_ATTEMPTS = 2
-export async function deliverViaRendezvous(id: string, text: string, mid?: string): Promise<DispatchResult> {
-  const sock = rvSock(id)
+async function pokeRendezvous(sock: string, text: string, mid?: string, auth?: string): Promise<DispatchResult> {
   let last: DispatchResult = { ok: false, error: 'not attempted' }
   for (let attempt = 0; attempt < POKE_ATTEMPTS; attempt++) {
-    last = await replyViaSocket(sock, text, mid)
+    last = await replyViaSocket(sock, text, mid, auth)
     if (last.ok) return last
   }
   return { ok: false, error: `rendezvous poke failed after ${POKE_ATTEMPTS} attempts: ${last.error ?? 'unknown error'}` }
 }
 
+export async function deliverViaRendezvous(id: string, text: string, mid?: string): Promise<DispatchResult> {
+  return pokeRendezvous(rvSock(id), text, mid)
+}
+
+export async function deliverViaClaudeRendezvous(id: string, text: string, mid?: string, runtimeDir?: string): Promise<DispatchResult> {
+  const fork = claudeForkTransport(id, runtimeDir)
+  const sourceSock = rvSock(id)
+  if (!fork) return pokeRendezvous(sourceSock, text, mid)
+
+  const forkResult = await pokeRendezvous(fork.sock, text, mid, fork.auth)
+  if (forkResult.ok || fork.sock === sourceSock) return forkResult
+
+  const sourceResult = await pokeRendezvous(sourceSock, text, mid)
+  if (sourceResult.ok) return sourceResult
+  return { ok: false, error: `fork rendezvous failed: ${forkResult.error}; source fallback failed: ${sourceResult.error}` }
+}
+
 export async function deliverViaSocketOrWake(
   id: string,
   text: string,
@@ -702,10 +778,12 @@ export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: s
     // thread/start bypass, so the worktree's hooks stay untrusted and NO lifecycle hooks fire.
     `export SPEXCODE_CODEX_CMD=${shQuote(codexCmd)}`,
     // The runtime command is the single generation-ledger boundary. A new turn receives canonical `current`;
-    // resume resolves its existing session/thread binding and therefore cannot jump an old conversation to a
-    // replacement root. It prints only shell assignments for the exact proven endpoint.
+    // resume resolves its existing session/thread binding, so a LIVE root never has its conversation moved to a
+    // replacement. Both spellings carry the server command because either may be the launch that has to start a
+    // root: after a host restart the bound generation is a corpse, and resume rebuilds one to load the same
+    // on-disk rollout. It prints only shell assignments for the exact proven endpoint.
     'if [ "$1" = "--resume" ]; then',
-    `  eval "$( ${SPEX} internal codex-generation-session "$dir" "$SPEXCODE_SESSION_ID" "$2" )" || exit 1`,
+    `  eval "$( ${SPEX} internal codex-generation-session "$dir" "$SPEXCODE_SESSION_ID" "$2" ${shQuote(server)} )" || exit 1`,
     'else',
     `  eval "$( ${SPEX} internal codex-generation-current "$dir" ${shQuote(server)} )" || exit 1`,
     'fi',
@@ -902,50 +980,61 @@ export function codexTurnFailureObserver(
   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.
+// Protocol-verified cold/restore/control seam. The Codex schema (`codex app-server generate-json-schema --experimental`)
+// defines thread/archive and thread/unarchive with {threadId}, plus turn/interrupt with {threadId, turnId}; no
+// guessed method or process command is used.
 type CodexGenerationFence = { dir: string; endpoint: CodexGenerationEndpoint; generation: string }
-function codexThreadMutation(sock: string, method: 'thread/archive' | 'thread/unarchive', threadId: string, fence?: CodexGenerationFence): Promise<{ ok: true } | { ok: false; error: string }> {
+// A failed mutation says whether the server can still commit it. `refused` means the request never reached the
+// server or the server answered by rejecting it, so the target is provably unchanged and compensation is safe.
+// `unknown` means the request was sent and no verdict came back — the server may still be executing it, so
+// sending anything else down the same connection queues behind that work and fails too.
+type CodexMutationOutcome = { ok: true } | { ok: false; error: string; commit: 'refused' | 'unknown' }
+function codexThreadMutation(sock: string, method: 'thread/archive' | 'thread/unarchive' | 'turn/interrupt', threadId: string, fence?: CodexGenerationFence, turnId?: string, budgetMs = CODEX_MUTATION_BASE_MS): Promise<CodexMutationOutcome> {
   const generationError = () => fence && codexRuntimeGeneration(fence.dir, fence.endpoint) !== fence.generation
     ? `Codex ${method} refused because the shared app-server generation changed`
     : null
   const before = generationError()
-  if (before) return Promise.resolve({ ok: false, error: before })
+  if (before) return Promise.resolve({ ok: false, error: before, commit: 'refused' })
+  if (method === 'turn/interrupt' && !turnId)
+    return Promise.resolve({ ok: false, error: 'Codex turn interrupt needs an exact turn id', commit: 'refused' })
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
-    let upgraded = false, settled = false
-    const done = (r: { ok: true } | { ok: false; error: string }) => {
+    let upgraded = false, settled = false, requested = false
+    const done = (r: CodexMutationOutcome) => {
       if (settled) return
       settled = true
       clearTimeout(timer)
       try { conn.destroy() } catch {}
       resolve(r)
     }
-    // thread/archive may wait up to 10s in shutdown_and_wait before the server commits; keep a margin so a
-    // legitimate late response is not turned into an early timeout race.
-    const timer = setTimeout(() => done({ ok: false, error: generationError() || `Codex ${method} timed out after 15s` }), 15000)
-    conn.on('error', (e) => done({ ok: false, error: generationError() || `Codex ${method} connection failed: ${rpcError(e)}` }))
-    conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during ${method}` }) })
+    // Once the request is on the wire the server owns it, so every unanswered end — timeout, socket error,
+    // early close, a generation swap — leaves the commit unknown rather than refused.
+    const unanswered = (error: string) => done({ ok: false, error, commit: requested ? 'unknown' : 'refused' })
+    const timer = setTimeout(() => unanswered(generationError() || `Codex ${method} did not answer within ${budgetMs}ms`), budgetMs)
+    conn.on('error', (e) => unanswered(generationError() || `Codex ${method} connection failed: ${rpcError(e)}`))
+    conn.on('close', () => { if (!settled) unanswered(`Codex app-server closed during ${method}`) })
     const send = (m: JsonRpc) => conn.write(wsText(JSON.stringify(m)))
     conn.on('connect', () => {
       const changed = generationError()
-      if (changed) return done({ ok: false, error: changed })
+      if (changed) return unanswered(changed)
       conn.write(WS_UPGRADE(randomBytes(16).toString('base64')))
     })
     const handle = (json: string) => {
       let m: JsonRpc
       try { m = JSON.parse(json) } catch { return }
-      if (m.error) return done({ ok: false, error: generationError() || `Codex ${method} failed: ${m.error.message || JSON.stringify(m.error)}` })
+      // The server answered by rejecting, so the target is provably unchanged whether or not we had sent it.
+      if (m.error) return done({ ok: false, error: generationError() || `Codex ${method} failed: ${m.error.message || JSON.stringify(m.error)}`, commit: 'refused' })
       if (m.id === 1 && m.result) {
         const changed = generationError()
-        if (changed) return done({ ok: false, error: changed })
+        if (changed) return unanswered(changed)
         send({ method: 'initialized', params: {} })
-        return send({ id: 2, method, params: { threadId } })
+        requested = true
+        return send({ id: 2, method, params: method === 'turn/interrupt' ? { threadId, turnId } : { threadId } })
       }
       if (m.id === 2 && m.result) {
         const changed = generationError()
-        return changed ? done({ ok: false, error: changed }) : done({ ok: true })
+        return changed ? unanswered(changed) : done({ ok: true })
       }
     }
     conn.on('data', (chunk: Buffer) => {
@@ -954,17 +1043,32 @@ function codexThreadMutation(sock: string, method: 'thread/archive' | 'thread/un
         const i = fs.buf.indexOf('\r\n\r\n')
         if (i < 0) return
         const head = fs.buf.slice(0, i).toString('utf8')
-        if (!/^HTTP\/1\.1 101/.test(head)) return done({ ok: false, error: `Codex app-server refused WebSocket upgrade for ${method}` })
+        if (!/^HTTP\/1\.1 101/.test(head)) return done({ ok: false, error: `Codex app-server refused WebSocket upgrade for ${method}`, commit: 'refused' })
         upgraded = true
         fs.buf = fs.buf.slice(i + 4)
         send(wsInitialize)
       }
-      if (drainWsFrames(fs, conn, handle)) done({ ok: false, error: `Codex app-server closed during ${method}` })
+      if (drainWsFrames(fs, conn, handle)) unanswered(`Codex app-server closed during ${method}`)
     })
   })
 }
 
 type CodexPagedIdsResult = { ok: true; ids: string[] } | { ok: false; error: string }
+// Dashboard/resource probes keep their own short budget; this target-scoped census is only entered by a
+// lifecycle mutation that already holds the session transition lock and must tolerate a busy app-server.
+const CODEX_MUTATION_CENSUS_MS = 15_000
+// A mutation's response budget. `thread/unarchive` and `turn/interrupt` are state flips the server answers at
+// once — measured 36ms to unarchive the very same 279 MB thread that took 47.7s to archive — so they keep the
+// base. `thread/archive` on a LOADED thread differs in kind: the server flushes that thread's whole in-memory
+// rollout inside shutdown_and_wait before it commits, so the wait is proportional to accumulated history
+// (measured 47.7s for 279 MB, ~5.9 MB/s, against ~1.5s for a notLoaded member that flushes nothing). A fixed
+// ceiling therefore never bounds the operation; it only picks the transcript size above which archive stops
+// working, and raising it just moves that size. The scaled term is deliberately pessimistic — a floor rate ~6x
+// under the measured one — because its job is to catch a WEDGED server, not to predict a flush: a machine
+// several times slower still archives, while a hung one still fails loudly.
+const CODEX_MUTATION_BASE_MS = 15_000
+const CODEX_ARCHIVE_FLUSH_FLOOR_BYTES_PER_MS = 1000
+const codexArchiveBudgetMs = (bytes: number) => CODEX_MUTATION_BASE_MS + Math.ceil(bytes / CODEX_ARCHIVE_FLUSH_FLOOR_BYTES_PER_MS)
 // Codex treats an omitted or empty sourceKinds filter as "interactive" defaults. Cold proof must census the
 // entire native thread graph, including subAgent/thread-spawn rows that have no Spex record, so the adapter
 // supplies every protocol source kind explicitly for its thread/list calls.
@@ -979,6 +1083,7 @@ function codexPagedIds(
   extractId: (item: unknown) => string | null,
   label: string,
   onItem?: (item: unknown) => void,
+  timeoutMs = CODEX_MUTATION_CENSUS_MS,
 ): Promise<CodexPagedIdsResult> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
@@ -989,7 +1094,7 @@ function codexPagedIds(
       if (settled) return
       settled = true; clearTimeout(timer); try { conn.destroy() } catch {}; resolve(result)
     }
-    const timer = setTimeout(() => done({ ok: false, error: `Codex ${label} timed out` }), 5000)
+    const timer = setTimeout(() => done({ ok: false, error: `Codex ${label} timed out after ${timeoutMs}ms` }), timeoutMs)
     conn.on('error', (error) => done({ ok: false, error: `Codex ${label} failed: ${rpcError(error)}` }))
     conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during ${label}` }) })
     const send = (message: JsonRpc) => conn.write(wsText(JSON.stringify(message)))
@@ -1038,18 +1143,23 @@ export async function codexLoadedReferenceIds(sock: string): Promise<{ ok: true;
   return result.ok ? { ok: true, referenceIds: result.ids } : result
 }
 
-const CODEX_TARGET_TURN_CENSUS_MS = 15_000
+const CODEX_RUNNING_TURN_READ_MS = 15_000
 
-function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok: true; turnPresence: 'idle' | 'active' | 'unknown' } | { ok: false; error: string }> {
+// @@@ presence vs identity - two different questions, deliberately not one helper.
+// A gate asks "is a turn in flight right now"; thread/list answers that for every thread at once, at a cost
+// that tracks the thread COUNT. Interrupt must additionally name the turn to interrupt, and only a turn read
+// carries the id — a cost that tracks that one thread's persisted HISTORY. So this read stays for interrupt,
+// where the target is by definition active and short-lived, and no gate may be routed back through it.
+function codexRunningTurn(sock: string, threadId: string): Promise<{ ok: true; turnPresence: 'idle' | 'active' | 'unknown'; turnId?: string } | { ok: false; error: string }> {
   return new Promise((resolve) => {
     const conn: Socket = createConnection(sock)
     const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
     let upgraded = false, settled = false
-    const done = (result: { ok: true; turnPresence: 'idle' | 'active' | 'unknown' } | { ok: false; error: string }) => {
+    const done = (result: { ok: true; turnPresence: 'idle' | 'active' | 'unknown'; turnId?: string } | { ok: false; error: string }) => {
       if (settled) return
       settled = true; clearTimeout(timer); try { conn.destroy() } catch {}; resolve(result)
     }
-    const timer = setTimeout(() => done({ ok: false, error: `Codex target thread ${threadId} turn census timed out after ${CODEX_TARGET_TURN_CENSUS_MS}ms` }), CODEX_TARGET_TURN_CENSUS_MS)
+    const timer = setTimeout(() => done({ ok: false, error: `Codex target thread ${threadId} turn census timed out after ${CODEX_RUNNING_TURN_READ_MS}ms` }), CODEX_RUNNING_TURN_READ_MS)
     conn.on('error', (error) => done({ ok: false, error: `Codex target thread ${threadId} turn census failed: ${rpcError(error)}` }))
     conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during target thread ${threadId} turn census` }) })
     const send = (message: JsonRpc) => conn.write(wsText(JSON.stringify(message)))
@@ -1067,7 +1177,12 @@ function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok:
       if (message.id !== 2 || !message.result) return
       const turns = (message.result as { data?: unknown }).data
       if (!Array.isArray(turns)) return done({ ok: true, turnPresence: 'unknown' })
-      return done({ ok: true, turnPresence: turns.some((turn) => turn && typeof turn === 'object' && (turn as { status?: unknown }).status === 'inProgress') ? 'active' : 'idle' })
+      const active = turns.find((turn): turn is { id?: unknown; status?: unknown } =>
+        !!turn && typeof turn === 'object' && (turn as { status?: unknown }).status === 'inProgress')
+      if (!active) return done({ ok: true, turnPresence: 'idle' })
+      return typeof active.id === 'string' && active.id
+        ? done({ ok: true, turnPresence: 'active', turnId: active.id })
+        : done({ ok: true, turnPresence: 'unknown' })
     }
     conn.on('data', (chunk: Buffer) => {
       fs.buf = Buffer.concat([fs.buf, chunk])
@@ -1083,14 +1198,57 @@ function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok:
   })
 }
 
+const CODEX_INTERRUPT_SETTLE_MS = 15_000
+
+async function interruptCodexTurn(rec: HarnessDeliveryRecord): Promise<DispatchResult> {
+  if (!rec.harnessSessionId) return { ok: false, error: 'no exact Codex thread identity is registered' }
+  const threadId = rec.harnessSessionId
+  const dir = rec.runtimeDir || runtimeRoot()
+  const endpoint = codexEndpointForRecord(rec, dir)
+  if (!endpoint) return { ok: false, error: 'no exact Codex generation binding is registered for this target' }
+  const generation = codexRuntimeGeneration(dir, endpoint)
+  if (!generation) return { ok: false, error: 'Codex shared app-server generation is unproven' }
+  const fence = { dir, endpoint, generation }
+  const before = await codexRunningTurn(endpoint.socketPath, threadId)
+  if (!before.ok) return { ok: false, error: before.error }
+  if (codexRuntimeGeneration(dir, endpoint) !== generation)
+    return { ok: false, error: 'shared Codex app-server generation changed during interrupt preflight' }
+  if (before.turnPresence === 'idle') return { ok: true }
+  if (before.turnPresence !== 'active' || !before.turnId)
+    return { ok: false, error: `Codex target thread ${threadId} turn state is unknown` }
+  const interrupted = await codexThreadMutation(endpoint.socketPath, 'turn/interrupt', threadId, fence, before.turnId)
+  if (!interrupted.ok) return { ok: false, error: interrupted.error }
+  const deadline = Date.now() + CODEX_INTERRUPT_SETTLE_MS
+  for (;;) {
+    const after = await codexRunningTurn(endpoint.socketPath, threadId)
+    if (!after.ok) return { ok: false, error: after.error }
+    if (codexRuntimeGeneration(dir, endpoint) !== generation)
+      return { ok: false, error: 'shared Codex app-server generation changed during interrupt settlement' }
+    if (after.turnPresence === 'idle') return { ok: true }
+    if (after.turnPresence === 'unknown') return { ok: false, error: `Codex target thread ${threadId} turn state is unknown after interrupt` }
+    if (Date.now() >= deadline) return { ok: false, error: `Codex target thread ${threadId} remained active after interrupt` }
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+}
+
 // 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)
 }
 
+// Every thread/list row carries the app-server's live turn state for that thread, in the protocol's own
+// three variants. `notLoaded` duplicates what thread/loaded/list reports; `idle`/`active` answer the only
+// question a lifecycle gate asks. Any other shape is `unknown` and fails closed — never derived from
+// something cheaper.
+type CodexThreadStatus = 'notLoaded' | 'idle' | 'active' | 'unknown'
+const codexRowStatus = (row: { status?: unknown }): CodexThreadStatus => {
+  const type = (row.status as { type?: unknown } | null | undefined)?.type
+  return type === 'notLoaded' || type === 'idle' || type === 'active' ? type : 'unknown'
+}
+
 type CodexThreadCollectionResult =
-  | { ok: true; ids: string[]; parentById: Map<string, string | null> }
+  | { ok: true; ids: string[]; parentById: Map<string, string | null>; statusById: Map<string, CodexThreadStatus> }
   | { ok: false; error: string }
 
 function codexThreadCollection(sock: string, params: Record<string, unknown>): Promise<CodexThreadCollectionResult> {
@@ -1098,6 +1256,7 @@ function codexThreadCollection(sock: string, params: Record<string, unknown>): P
     ? params.sourceKinds
     : [...CODEX_THREAD_SOURCE_KINDS]
   const parentById = new Map<string, string | null>()
+  const statusById = new Map<string, CodexThreadStatus>()
   const conflictingParents = new Set<string>()
   return codexPagedIds(sock, 'thread/list', { ...params, sourceKinds, useStateDbOnly: true }, (item) => {
     if (typeof item === 'string') return item
@@ -1105,26 +1264,40 @@ function codexThreadCollection(sock: string, params: Record<string, unknown>): P
     return typeof id === 'string' ? id : null
   }, 'thread/list', (item) => {
     if (!item || typeof item !== 'object') return
-    const row = item as { id?: unknown; parentThreadId?: unknown }
+    const row = item as { id?: unknown; parentThreadId?: unknown; status?: 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)
+    // Parent ownership is a fact about the graph, so a disagreement across pages is a census fault.
+    // Turn state is live, so a mid-drain change is not a fault — it is simply no longer knowable here.
+    const status = codexRowStatus(row)
+    statusById.set(row.id, statusById.has(row.id) && statusById.get(row.id) !== status ? 'unknown' : status)
   }).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 }
+    return { ...result, parentById, statusById }
   })
 }
 
+// The gate's question is about the tip — is a turn in flight right now — and thread/list already answers it
+// for every thread at once, at a cost that tracks how many threads exist. Reading turns instead costs the
+// target's whole persisted history against a fixed budget, so a long-lived session becomes unmutatable.
+const codexPresenceFromStatus = (status: CodexThreadStatus | undefined): SharedRuntimeMutationGuard['targetTurnPresence'] =>
+  status === 'idle' || status === 'active' ? status : 'unknown'
+
 async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)): Promise<SharedRuntimeMutationGuard> {
   const generationBefore = codexMutationGeneration(dir, endpoint)
   if (!generationBefore) return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'Codex shared app-server generation is unproven' }
   const sock = endpoint.socketPath
-  const [loaded, activeDescendants, archivedDescendants] = await Promise.all([
+  // The descendant collections are ancestor-filtered and therefore exclude the target itself, so the
+  // target's own turn state comes from the whole-collection census. These run concurrently with the rest.
+  const [loaded, activeDescendants, archivedDescendants, activeList, archivedList] = await Promise.all([
     codexLoadedReferenceIds(sock),
     codexThreadList(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
     codexThreadList(sock, { ancestorThreadId: threadId, archived: true, sourceKinds: [] }),
+    codexThreadCollection(sock, { archived: false, sourceKinds: [] }),
+    codexThreadCollection(sock, { archived: true, sourceKinds: [] }),
   ])
   const referenceIds = loaded.ok ? loaded.referenceIds : []
   const descendantIds = activeDescendants.ok && archivedDescendants.ok
@@ -1133,12 +1306,11 @@ async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot(), e
   if (!loaded.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: loaded.error }
   if (!activeDescendants.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: activeDescendants.error }
   if (!archivedDescendants.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: archivedDescendants.error }
-  let targetTurnPresence: SharedRuntimeMutationGuard['targetTurnPresence'] = 'none'
-  if (referenceIds.includes(threadId)) {
-    const target = await codexTargetTurnPresence(sock, threadId)
-    if (!target.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: target.error }
-    targetTurnPresence = target.turnPresence
-  }
+  if (!activeList.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: activeList.error }
+  if (!archivedList.ok) return { healthy: false, referenceIds, targetTurnPresence: 'unknown', descendantIds, error: archivedList.error }
+  const targetTurnPresence: SharedRuntimeMutationGuard['targetTurnPresence'] = referenceIds.includes(threadId)
+    ? codexPresenceFromStatus(activeList.statusById.get(threadId) ?? archivedList.statusById.get(threadId))
+    : 'none'
   if (codexRuntimeGeneration(dir, endpoint) !== generationBefore)
     return { healthy: false, referenceIds, targetTurnPresence, descendantIds, error: 'shared Codex app-server generation changed during target guard' }
   return { healthy: true, referenceIds, targetTurnPresence, descendantIds }
@@ -1181,7 +1353,7 @@ function isEndpointLike(value: unknown): value is CodexGenerationEndpoint {
     typeof (value as CodexGenerationEndpoint).socketPath === 'string'
 }
 
-async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string, endpoint = legacyCodexGenerationEndpoint(dir)): Promise<CodexColdPreflight> {
+async function codexColdPreflightOnce(threadId: string, dir = runtimeRoot(), expectedGeneration?: string, endpoint = legacyCodexGenerationEndpoint(dir)): Promise<CodexColdPreflight> {
   const generation = expectedGeneration ?? codexMutationGeneration(dir, endpoint)
   if (!generation || codexRuntimeGeneration(dir, endpoint) !== generation)
     return { ok: false, reason: 'Codex shared app-server generation is unproven or changed before subtree census' }
@@ -1190,8 +1362,8 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
     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: [] }),
+    codexThreadCollection(sock, { archived: true, sourceKinds: [] }),
+    codexThreadCollection(sock, { archived: false, sourceKinds: [] }),
   ])
   if (codexRuntimeGeneration(dir, endpoint) !== generation)
     return { ok: false, reason: 'shared Codex app-server generation changed during subtree census' }
@@ -1243,18 +1415,20 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
     }
   }
 
+  // Every subtree member was just proven to occur in exactly one whole-collection census, so that census
+  // already carries each one's live turn state. No second round of native reads, and therefore no second
+  // generation fence — nothing was read between the fence above and here.
+  const statusById = new Map([...activeList.statusById, ...archivedList.statusById])
   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, endpoint) !== 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` }
+  for (const id of loadedSubtreeIds) {
+    const presence = codexPresenceFromStatus(statusById.get(id))
+    if (presence === 'active') return { ok: false, reason: `Codex subtree member ${id} has an active turn` }
+    if (presence === '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` }
   }
 
+  // Proven, not assumed: a loaded target is one of the members the loop above just cleared.
   const targetTurnPresence: SharedRuntimeMutationGuard['targetTurnPresence'] = loadedSet.has(threadId) ? 'idle' : 'none'
   const guard: SharedRuntimeMutationGuard = {
     healthy: true,
@@ -1283,6 +1457,28 @@ async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expecte
   return { ok: true, ...(activeIds.length ? {} : { alreadyCold: true }), receipt }
 }
 
+// A busy app-server can refuse one WebSocket census while accepting the next. The refusal is transport-local,
+// so retry the complete proof (including generation fencing) within the terminal operation's finite budget;
+// semantic ownership refusals still return immediately and never turn into repeated native reads.
+const CODEX_COLD_PREFLIGHT_MAX_ATTEMPTS = 6
+const CODEX_COLD_PREFLIGHT_RETRY_MS = 250
+const CODEX_COLD_PREFLIGHT_DEADLINE_MS = 30_000
+const isTransientCodexCensusFailure = (reason: string): boolean =>
+  /(?:timed out|connection|closed during|refused .*census|census failed|app-server busy)/i.test(reason)
+
+async function codexColdPreflight(threadId: string, dir = runtimeRoot(), expectedGeneration?: string, endpoint = legacyCodexGenerationEndpoint(dir)): Promise<CodexColdPreflight> {
+  const deadline = Date.now() + CODEX_COLD_PREFLIGHT_DEADLINE_MS
+  for (let attempt = 0; attempt < CODEX_COLD_PREFLIGHT_MAX_ATTEMPTS; attempt++) {
+    const result = await codexColdPreflightOnce(threadId, dir, expectedGeneration, endpoint)
+    if (result.ok || !isTransientCodexCensusFailure(result.reason) || attempt === CODEX_COLD_PREFLIGHT_MAX_ATTEMPTS - 1) return result
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) return result
+    const delay = Math.min(CODEX_COLD_PREFLIGHT_RETRY_MS * 2 ** attempt, remaining)
+    await new Promise((resolve) => setTimeout(resolve, delay))
+  }
+  throw new Error('unreachable Codex cold preflight retry state')
+}
+
 async function codexQuarantineOrphanThread(threadId: string, opts: { excludingSessionId: string }): Promise<HarnessOrphanThreadQuarantine> {
   const dir = runtimeRoot()
   const generation = codexMutationGeneration(dir)
@@ -1312,8 +1508,16 @@ async function codexQuarantineOrphanThread(threadId: string, opts: { excludingSe
     return { ok: false, reason: `Codex native thread ${threadId} is not one exact active orphan` }
   const siblingIds = plan.guard.referenceIds.filter((id) => id !== threadId)
   const legacy = legacyCodexGenerationEndpoint(dir)
-  const archived = await codexThreadMutation(legacy.socketPath, 'thread/archive', threadId, { dir, endpoint: legacy, generation })
-  if (!archived.ok) return { ok: false, reason: `${archived.error} while archiving orphan Codex thread ${threadId}` }
+  // Quarantine archives one exact orphan, so it pays the same flush a subtree member does when that orphan is
+  // loaded; the budget is derived the same way rather than being a second, differently-wrong constant.
+  let orphanBudgetMs = CODEX_MUTATION_BASE_MS
+  if (plan.guard.referenceIds.includes(threadId)) {
+    const rollout = codexRolloutBytes(threadId)
+    if ('unreadable' in rollout) return { ok: false, reason: `Codex native thread ${threadId} is loaded and its rollout exists but cannot be measured, so the archive flush budget is unknown` }
+    orphanBudgetMs = codexArchiveBudgetMs(rollout.bytes)
+  }
+  const archived = await codexThreadMutation(legacy.socketPath, 'thread/archive', threadId, { dir, endpoint: legacy, generation }, undefined, orphanBudgetMs)
+  if (!archived.ok) return { ok: false, reason: `${archived.error} while archiving orphan Codex thread ${threadId}${archived.commit === 'unknown' ? '; commit state is unknown' : ''}` }
   const after = await codexColdPreflight(threadId, dir, generation)
   const failed = (reason: string): HarnessOrphanThreadQuarantine => ({ ok: false, reason })
   if (!after.ok) {
@@ -1742,19 +1946,25 @@ export function codexTurn(sock: string, threadId: string, text: string, cwd?: st
 // thread/start+turn but does NOT persist the rollout for its first ~2-4s (a warm-up window) — the SAME thread's
 // rollout just lands a few seconds LATE (not lost). Handing the id to `resume` before then is the "no rollout
 // found for thread id" failure, so codex-launch WAITS for the rollout to land before it trusts the id.
-const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions')
 // does a rollout file for this thread id exist yet? Rollouts are grouped by date; walk day-dirs newest-first
 // (lexical order = chronological on zero-padded YYYY/MM/DD) and return on first hit — the fresh rollout lives in
 // the newest real dir, so the common case reads one dir. The walk is exhaustive, never capped at "the newest few
 // dirs": future-dated junk under sessions/ (a test once planted 2099/12/* in the real CODEX_HOME) sorts above
 // every real day-dir, and a cap let three such dirs mask ALL real rollouts — every codex launch then failed
 // "persisted no rollout" with the rollout sitting on disk. A full walk is a readdir per day-dir — still cheap.
-export function codexRolloutExists(threadId: string, root = codexSessionsDir()): boolean {
-  const kids = (d: string) => { try { return readdirSync(d).sort().reverse() } catch { return [] as string[] } }
-  for (const y of kids(root)) for (const m of kids(join(root, y))) for (const d of kids(join(root, y, m))) {
-    if (kids(join(root, y, m, d)).some((f) => f.includes(threadId))) return true
-  }
-  return false
+export function codexRolloutExists(threadId: string, root?: string): boolean {
+  return codexRolloutPath(threadId, root) !== null
+}
+// The same day-dir walk, answering how big that rollout is. `thread/archive` on a LOADED thread flushes the
+// thread's in-memory rollout inside the server's shutdown_and_wait before it commits, so this size IS the work
+// an archive asks for; a notLoaded thread flushes nothing and its size is irrelevant. NO rollout file is a real
+// `0`, not an error: a thread that has started but not yet persisted (thread/start alone writes none, and a
+// fresh app-server lags 2-4s) has nothing to flush, so refusing it would be a false refusal. Only a file that
+// exists and cannot be measured is unreadable, and that fails closed rather than passing as small.
+export function codexRolloutBytes(threadId: string, root?: string): { bytes: number } | { unreadable: true } {
+  const path = codexRolloutPath(threadId, root)
+  if (path) { try { return { bytes: statSync(path).size } } catch { return { unreadable: true } } }
+  return { bytes: 0 }
 }
 // poll until the thread's rollout lands (resume-ready) or the budget runs out. Returns false on timeout so the
 // caller can FAIL LOUD instead of handing `resume` / the stored record a non-resumable id. The budget must
@@ -1797,17 +2007,16 @@ async function deliverViaCodexAppServer(rec: HarnessDeliveryRecord, text: string
 // idempotent replace of the content between sentinels; the user's own content above/below is preserved. The
 // comment STYLE is a parameter so ONE primitive serves every managed file — HTML for the md contracts
 // (CLAUDE.md/AGENTS.md), `#` for .gitignore — instead of a per-file-type writer. Default = HTML (the md case).
-export function writeManagedBlock(file: string, body: string, comment: readonly [string, string] = ['<!-- ', ' -->']): void {
+export function writeManagedBlock(file: string, body: string, comment: readonly [string, string] = ['<!-- ', ' -->']): boolean {
   const [open, close] = comment
   const START = `${open}spexcode:start${close}`
   const END = `${open}spexcode:end${close}`
   const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
   const block = `${START}\n${body}\n${END}`
-  let cur = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const cur = existsSync(file) ? readFileSync(file, 'utf8') : ''
   const re = new RegExp(`${esc(START)}[\\s\\S]*?${esc(END)}`)
-  if (re.test(cur)) cur = cur.replace(re, block)
-  else cur = cur.trim() ? `${cur.replace(/\n*$/, '')}\n\n${block}\n` : `${block}\n`
-  writeFileSync(file, cur)
+  const next = re.test(cur) ? cur.replace(re, block) : cur.trim() ? `${cur.replace(/\n*$/, '')}\n\n${block}\n` : `${block}\n`
+  return writeFileIfChanged(file, next)
 }
 
 // the INVERSE of writeManagedBlock: strip the spexcode sentinel block (with the blank space around it),
@@ -1916,7 +2125,7 @@ export function writeCodexTrust(proj: string, events: readonly string[], cmdFor:
   const blk = `# spexcode:trust:${proj} (managed — do not edit)\n${lines.join('\n')}\n# spexcode:trust:end:${proj}`
   const cleaned = stripCodexTrustFor(existsSync(file) ? readFileSync(file, 'utf8') : '', proj, hooksJson)
   if (!existsSync(home)) mkdirSync(home, { recursive: true })
-  writeFileSync(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`)
+  writeFileIfChanged(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`)
   return file
 }
 
@@ -2025,6 +2234,9 @@ const CODEX_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToo
 // agent_settled → Stop). pi has no idle/attention or failed-stop event → no Notification/StopFailure, same
 // real gap as codex.
 const PI_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
+// z-code reads Claude-compatible hooks but has neither the idle Notification nor StopFailure lifecycle event.
+// This is a real harness difference, not a TODO: the existing Claude-only idle state is unavailable.
+const ZCODE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'] as const
 
 // the resolved base launcher command per harness (the wrapper that sets the config-dir env), shared by
 // launchCmd and baseCmd so the two never diverge: the launcher's pinned `cmd` wins. The plain command is only
@@ -2035,6 +2247,7 @@ const claudeBaseCmd = (cmd?: string) => cmd || 'claude'
 const codexBaseCmd = (cmd?: string) => cmd || 'codex'
 const piBaseCmd = (cmd?: string) => cmd || 'pi'   // pi runs tools without permission prompts — no yolo flag exists or is needed
 const opencodeBaseCmd = (cmd?: string) => cmd || 'opencode'
+const zcodeBaseCmd = (cmd?: string) => cmd || 'zcode'
 
 // @@@ opencodeLaunchCommand - the tail-branching launch script (the codex marker pattern, minus any server:
 // opencode is a per-session process like claude). The caller-appended tail ("$@") is EITHER one single-quoted
@@ -2070,6 +2283,9 @@ const socketListenerLiveness: Harness['liveness'] = (_rec, tmuxAlive, _runtimeDi
 const socketListenerOrPidAliveLiveness: Harness['liveness'] = (_rec, tmuxAlive, _runtimeDir, pane, socketLive) =>
   (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline')
 
+const panePidLiveness: Harness['liveness'] = (_rec, tmuxAlive, _runtimeDir, pane) =>
+  (tmuxAlive && pane?.pidAlive === true ? 'online' : 'offline')
+
 const recordOnline: Harness['liveness'] = (rec) => rec.stopped ? 'offline' : 'online'
 
 // @@@ unlinkSocks - remove ONLY the transport this teardown PROVED dead. `cleanupRuntime` unlinks *their*
@@ -2119,6 +2335,7 @@ export const claudeHarness: Harness = {
   events: CLAUDE_EVENTS,
   ownsRendezvous: true,                              // reclaude opens the rendezvous control socket (prompt delivery + liveness)
   paneTitleIsSelfSummary: true,                      // claude writes its live task summary into the OSC pane title → headline derives from it
+  executionTrace: readProjectJsonlExecutionTrace,
   launchCmd: (_id, _rt, cmd) => claudeBaseCmd(cmd),  // claude's full invocation IS its base command (the tail is appended by the caller)
   baseCmd: claudeBaseCmd,
   sessionIdArg: (id) => `--session-id ${id}`,        // the caller chooses the id
@@ -2140,7 +2357,7 @@ export const claudeHarness: Harness = {
   // dead-pane-reads-working bug). See rendezvousListening.
   liveness: socketListenerLiveness,
   leafOwnerNeedle: (rec) => rec.session,
-  deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
+  deliver: (rec, text) => deliverViaClaudeRendezvous(rec.session, text, rec.mid, rec.runtimeDir),
   cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
   coldRuntime: async () => ({ ok: true }),
   // The TUI's sessions panel ("← for agents") swallows an injected reply into PANEL context and never drains it
@@ -2219,6 +2436,7 @@ export const codexHarness: Harness = {
   events: CODEX_EVENTS,
   ownsRendezvous: false,                             // no reclaude daemon — liveness + prompts through the project app-server socket
   paneTitleIsSelfSummary: false,                     // codex's pane title is a spinner + the cwd folder name, NOT a task summary → headline uses the prompt
+  executionTrace: readCodexExecutionTrace,
   launchCmd: (id, runtimeDir, cmd) => codexLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()),   // the full app-server+TUI script BUILT AROUND the resolved base command; ONE app-server per PROJECT
   baseCmd: codexBaseCmd,
   sessionIdArg: () => '',                            // codex assigns its own id (the backend owns it via thread/start)
@@ -2282,6 +2500,7 @@ export const codexHarness: Harness = {
   leafOwnerNeedle: (rec) => rec.harnessSessionId ?? null,
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
   observeTurnFailures: codexTurnFailureObserver,
+  interrupt: interruptCodexTurn,
   cleanupRuntime: async () => { /* project-scoped app-server is shared; no per-session transport to remove */ },
   targetDescriptorKey: (rec) => {
     const endpoint = codexEndpointForRecord(rec)
@@ -2357,9 +2576,24 @@ export const codexHarness: Harness = {
       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 loadedSet = new Set(plan.guard.referenceIds)
     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}`)
+      // Only a loaded member pays the rollout flush, and an unreadable size must not become a small budget,
+      // so it fails closed before the server is asked to mutate anything.
+      let budgetMs = CODEX_MUTATION_BASE_MS
+      if (loadedSet.has(id)) {
+        const rollout = codexRolloutBytes(id)
+        if ('unreadable' in rollout) return compensate(`Codex subtree member ${id} is loaded and its rollout exists but cannot be measured, so the archive flush budget is unknown`)
+        budgetMs = codexArchiveBudgetMs(rollout.bytes)
+      }
+      const archived = await codexThreadMutation(sock, 'thread/archive', id, fence, undefined, budgetMs)
+      if (archived.ok) continue
+      const reason = `${archived.error} while archiving Codex subtree member ${id}`
+      // Compensating an unknown commit is what turns one slow member into a false "compensation failed": the
+      // unarchive queues behind an archive the server is still executing and times out too. Report the unknown
+      // commit instead — that is the recovery token resume already reconciles.
+      if (archived.commit === 'unknown') return { ok: false, reason: `${reason}; commit state is unknown and no compensation was attempted` }
+      return compensate(reason)
     }
     let verified: { ok: true } | { ok: false; reason: string } = { ok: false, reason: 'Codex archive verification timed out' }
     const verifyDeadline = Date.now() + 30_000
@@ -2550,6 +2784,7 @@ export const piHarness: Harness = {
   events: PI_EVENTS,
   ownsRendezvous: true,                              // the generated extension binds rvSock(id) and speaks the reclaude protocol
   paneTitleIsSelfSummary: false,                     // pi's pane title is not an agent-written task summary → headline uses the prompt preview
+  executionTrace: readSessionJsonlExecutionTrace,
   launchCmd: (_id, _rt, cmd) => `${piBaseCmd(cmd)} --approve`,   // --approve = one-run project trust (belt to writeTrust's braces)
   baseCmd: piBaseCmd,
   sessionIdArg: (id) => `--session-id ${id}`,        // caller pins the exact session id, claude-style (created if missing)
@@ -2600,6 +2835,44 @@ export const piHeadlessHarness: Harness = {
   resumeArg: (rec) => `--session ${rec.session}`,
 }
 
+const ZCODE_CONTROL_UNAVAILABLE = 'zcode has no control channel; start a new session instead of delivering to an existing one'
+
+// z-code's app-server is stdin/stdout NDJSON, unlike Codex's Unix-socket WebSocket + thread RPC. This row
+// intentionally covers the one-turn `--prompt` launcher and Claude-compatible hooks only; control operations
+// refuse rather than pretending the incompatible protocol accepted them.
+export const zcodeHarness: Harness = {
+  id: 'zcode',
+  dispatchId: 'zcode',
+  headless: true,
+  launchOneShot: true,
+  events: ZCODE_EVENTS,
+  ownsRendezvous: false,
+  paneTitleIsSelfSummary: false,
+  executionTrace: noExecutionTrace,
+  launchCmd: (_id, _rt, cmd) => `${zcodeBaseCmd(cmd)} --prompt`,
+  baseCmd: zcodeBaseCmd,
+  sessionIdArg: () => '',
+  sessionEnvVar: 'ZCODE_SESSION_ID',
+  launchEnv: noLaunchEnv,
+  shimFile: (proj) => join(proj, '.zcode', 'settings.json'),
+  shimScope: 'tree',
+  worktreeHookAnchor: () => null,
+  contractFiles: (proj) => [join(proj, 'AGENTS.md')],
+  skillDir: (proj) => join(proj, '.zcode', 'skills'),
+  agentDir: (proj) => join(proj, '.zcode', 'agents'),
+  shim: (dispatch, spex) => buildShim('zcode', ZCODE_EVENTS, dispatch, spex),
+  writeTrust: () => [],
+  removeTrust: () => { /* z-code wrote no trust artifact */ },
+  clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject) },
+  slashCommands: () => [],
+  liveness: panePidLiveness,
+  leafOwnerNeedle: (rec) => rec.session,
+  deliver: async () => { throw new Error(ZCODE_CONTROL_UNAVAILABLE) },
+  cleanupRuntime: async () => { /* one-shot z-code owns no SpexCode transport to remove */ },
+  coldRuntime: async () => ({ ok: true }),
+  resumeArg: () => { throw new Error(ZCODE_CONTROL_UNAVAILABLE) },
+}
+
 export const opencodeHarness: Harness = {
   id: 'opencode',
   dispatchId: 'opencode',
@@ -2609,6 +2882,7 @@ export const opencodeHarness: Harness = {
   // socket the launch env hands it, so the shared reply poke and socket-listener liveness are reused verbatim.
   ownsRendezvous: true,
   paneTitleIsSelfSummary: false,                     // opencode's TUI title is not the agent's live task self-summary → headline uses the prompt
+  executionTrace: readLocalStoreExecutionTrace,
   launchCmd: (_id, _rt, cmd) => opencodeLaunchCommand(opencodeBaseCmd(cmd)),   // the tail-branching script (prompt vs --resume/--continue marker)
   baseCmd: opencodeBaseCmd,
   sessionIdArg: () => '',                            // opencode mints its own session id; the plugin's first event reports it back (opencode-capture)
@@ -2672,14 +2946,20 @@ export const opencodeHeadlessHarness: Harness = {
 }
 
 // every adapter — materialize iterates this to write each harness's artifacts in one pass.
-export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness, codexHeadlessHarness]
+export const HARNESSES: readonly Harness[] = [claudeHarness, codexHarness, opencodeHarness, piHarness, zcodeHarness, claudeHeadlessHarness, opencodeHeadlessHarness, piHeadlessHarness, codexHeadlessHarness]
 
 // the legacy/default adapter for old records and config defaults. New launches derive harness from a launcher.
 export const defaultHarness: Harness = claudeHarness
 
+// the registry lookup as DATA. A sweep over records nobody is currently asking about (a removed plugin, a
+// renamed id) must report an unresolvable harness rather than abort, so it resolves through this.
+export function harnessByIdOrNull(id: string): Harness | null {
+  return HARNESSES.find((x) => x.id === id) ?? null
+}
+
 // resolve an adapter by id (the detector). Throws on an unknown id — fail loud, never silently default.
 export function harnessById(id: string): Harness {
-  const h = HARNESSES.find((x) => x.id === id)
+  const h = harnessByIdOrNull(id)
   if (!h) throw new Error(`unknown harness '${id}' (known: ${HARNESSES.map((x) => x.id).join(', ')})`)
   return h
 }