spexcode 0.5.2 → 0.5.3

package/spec-cli/src/harness.ts

@@ -1,5 +1,5 @@
-import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'node:fs'
-import { join } from 'node:path'
+import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
 import { homedir, tmpdir } from 'node:os'
 import { createHash, randomBytes } from 'node:crypto'
 import { createConnection, type Socket } from 'node:net'
@@ -13,8 +13,10 @@ import { claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadle
 import { codexHeadlessLaunchCommand } from './codex-headless.js'
 import { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js'
 import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless } from './pi-headless.js'
-import { runtimeRoot, mainCheckout, readConfig } from './layout.js'
+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'
 
 // @@@ 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
@@ -29,7 +31,12 @@ import { git } from './git.js'
 // (materialize writes every harness's artifacts).
 
 export type HarnessId = 'claude' | 'codex' | 'opencode' | 'pi' | 'claude-headless' | 'codex-headless' | 'opencode-headless' | 'pi-headless'
-export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null }
+export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null; stopped?: boolean; archived?: boolean }
+export type HarnessLaunchReadyRecord = HarnessLivenessRecord & { governed?: boolean; runtimeDir: string }
+export type HarnessLaunchReadinessFence = {
+  readonly proof: Readonly<Record<string, unknown>>
+  validate(current: () => HarnessLaunchReadyRecord | null): Promise<boolean>
+}
 // 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).
@@ -42,6 +49,81 @@ export type HarnessLivenessRecord = { session: string; harnessSessionId?: string
 //     tree-walk, so a box with no codex — or all pid-registered launches — never pays for it.
 export type ProcTable = Map<number, { ppid: number; comm: string }>
 export type PaneProbe = { panePid?: number; procs?: ProcTable; pidAlive?: boolean }
+export type SharedRuntimeDescriptor = {
+  key: string
+  label: string
+  pidFile: string
+  isolationFile: 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>
+  probe(): Promise<SharedRuntimeProbe>
+}
+export type SharedRuntimeMutationGuard = {
+  healthy: boolean
+  referenceIds: string[]
+  targetTurnPresence: 'none' | 'idle' | 'active' | 'unknown'
+  descendantIds: string[]
+  error?: string
+}
+export type SharedRuntimeProbe = {
+  healthy: boolean
+  references: Array<{
+    referenceId: string
+    turnPresence: 'idle' | 'active' | 'unknown'
+    turnId?: string
+  }>
+  error?: string
+}
+
+export type AdapterLoadedReferenceState = {
+  healthy: boolean
+  loaded: boolean
+  error?: string
+}
+
+// One project-wide resident-reference census for read projections. A shared app-server descriptor is probed
+// once per call, then its result is joined to every record that names that adapter/thread. Product readers must
+// not turn this into one RPC per row: a loaded thread can be externally reloaded after its cold proof was filed.
+export async function adapterLoadedReferenceState(
+  records: readonly (HarnessLivenessRecord & { harness?: string })[],
+  runtimeDir = runtimeRoot(),
+): Promise<Map<string, AdapterLoadedReferenceState>> {
+  const descriptors = new Map<string, SharedRuntimeDescriptor>()
+  const recordKeys = new Map<string, string[]>()
+  for (const rec of records) {
+    if (!rec.harnessSessionId) continue
+    const keys = (harnessById(rec.harness || defaultHarness.id).sharedRuntimes?.(runtimeDir) ?? []).map((descriptor) => {
+      descriptors.set(descriptor.key, descriptor)
+      return descriptor.key
+    })
+    recordKeys.set(`${rec.harness || defaultHarness.id}:${rec.harnessSessionId}`, keys)
+  }
+  const probes = await Promise.all([...descriptors.entries()].map(async ([key, descriptor]) => {
+    try {
+      const result = descriptor.residency
+        ? await descriptor.residency()
+        : await descriptor.probe().then((probe) => ({ healthy: probe.healthy, referenceIds: probe.references.map((reference) => reference.referenceId), error: probe.error }))
+      return [key, result] as const
+    }
+    catch (error) { return [key, { healthy: false, referenceIds: [] as string[], error: (error as Error).message }] as const }
+  }))
+  const byKey = new Map(probes)
+  const result = new Map<string, AdapterLoadedReferenceState>()
+  for (const [recordKey, keys] of recordKeys) {
+    const refs = keys.map((key) => byKey.get(key)!).filter(Boolean)
+    if (!refs.length) continue
+    const unhealthy = refs.find((probe) => !probe.healthy)
+    const threadId = recordKey.slice(recordKey.indexOf(':') + 1)
+    result.set(recordKey, unhealthy
+      ? { healthy: false, loaded: false, error: unhealthy.error || 'adapter resident-reference census is unhealthy' }
+      : { healthy: true, loaded: refs.some((probe) => probe.referenceIds.includes(threadId)) })
+  }
+  return result
+}
 
 export interface Harness {
   readonly id: HarnessId
@@ -51,9 +133,18 @@ export interface Harness {
   // whether the launch command intentionally exits after its first turn instead of owning a resident process.
   // One-shot adapters must not be mistaken for a failed fast boot and retried with a duplicate prompt.
   readonly launchOneShot?: boolean
-  // whether this harness persists a native event stream that the console may expose as an optional
-  // full-process drill-down ([[message-stream]]). This is adapter data, never a harness-id branch in UI.
-  readonly messageStream: boolean
+  // Adapter-owned runtime shape: headless controllers/shared threads have no interactive TUI leaf to signal.
+  readonly runtimeOwnership?: 'leaf' | 'adapter'
+  // This launch command may create its project-shared control plane through internal shared-runtime-spawn.
+  readonly sharedRuntimeSpawn?: boolean
+  // @@@ fatalLaunchOutput - extended regexes matching THIS harness's own report of a launch failure that
+  // RUNNING IT AGAIN CANNOT FIX: a conversation that does not exist, a rejected credential, a broken config.
+  // A launcher that exits within the boot window tells us only that it exited fast, which is why the transport
+  // retries — but when the harness itself named a settled cause, retrying spends a certain failure two more
+  // times and buries the one line that explains it. So the transport asks the ADAPTER, and the adapter is the
+  // only place a harness's wording is ever matched: product code consumes the verdict (retry / fatal), never
+  // the text. A harness that declares none keeps the plain bounded retry.
+  readonly fatalLaunchOutput?: readonly string[]
   // the lifecycle events this harness fires (drives the shim + the trust hashes). Claude binds the full set;
   // Codex's canonical hook event set (its `HookEventName` enum, codex 0.142.3) has no failed-stop and no
   // idle/attention event, so Codex has NO equivalent of StopFailure / Notification — a real harness difference,
@@ -89,6 +180,9 @@ export interface Harness {
   sessionIdArg(id: string): string
   // the env var the agent's OWN process carries so its `spex …` calls know their session id.
   readonly sessionEnvVar: string
+  // transport bootstrap variables scoped to this launch. Rendezvous adapters own their daemon mode + socket;
+  // product launch code only composes these with generic session/home env.
+  launchEnv(id: string): string[]
 
   // --- materialize: shim + contract + trust ([[harness-delivery]]) ---
   // the auto-discovered hook shim file for this harness (.claude/settings.json vs .codex/hooks.json).
@@ -148,6 +242,17 @@ export interface Harness {
   // to the shell). A missing probe (tmux/ps couldn't report) is not-live. The 'starting' boot
   // grace lives in the caller (sessions.ts liveness), so a still-booting pane reads starting, not offline.
   liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline'
+  // A completed launch command is only transport acceptance. An adapter with stronger runtime ownership may
+  // keep the caller waiting until the launched conversation is genuinely addressable. The lazy record source
+  // lets a one-shot launch publish its native id while readiness is pending. The returned adapter-owned fence
+  // names the facts that established readiness and revalidates those SAME facts across the caller's record
+  // commit. Null at the deadline is a launch failure; adapters without this seam retain the generic bounded
+  // liveness fence.
+  launchReady?(current: () => HarnessLaunchReadyRecord | null, deadline: number): Promise<HarnessLaunchReadinessFence | null>
+  // Exact leaf ownership evidence consumed by lifecycle teardown. The adapter returns the one argv identity
+  // token it registered for this record (session id, harness thread/generation, or null when unprovable);
+  // product lifecycle code never branches on harness names to invent this identity.
+  leafOwnerNeedle?(rec: HarnessLivenessRecord & { harnessSessionId?: string | null }): string | null
   // deliver a follow-up prompt to a LIVE session and report whether it landed. claude: through the rendezvous
   // control socket — an ATOMIC reply+repaint chunk whose `repaint-done` proves the reply was PARSED; a close
   // before it proves a concurrent connect kicked the chunk (the daemon is single-connection) → resend; a wall
@@ -163,7 +268,22 @@ export interface Harness {
   // Remove this harness's ephemeral runtime transport after stop/close. This is the runtime inverse of
   // launch: rendezvous owners unlink rvSock, claude-headless unlinks its control socket, Codex owns no
   // per-session socket. Product teardown calls only this adapter method.
-  cleanupRuntime(rec: HarnessLivenessRecord): void
+  // Async because removal is CONDITIONAL on proof: a transport is only ours to remove once its listener is
+  // proven dead (see unlinkSocks), and that proof is a connect probe.
+  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 }>
+  // 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 }>
+  // 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[]
   // the ONE pane state where this harness SWALLOWS a prompt that its delivery channel confirms (so no
   // socket-side check can see it): given the live pane text, return the loud human-readable refusal (naming
   // the recovery) or null when the pane can take a prompt. sendText captures the pane once and consults this
@@ -214,12 +334,36 @@ export type HarnessArtifacts = { skills: readonly string[]; agents: readonly str
 // sessions.ts starts `claude` with CLAUDE_BG_BACKEND=daemon + CLAUDE_BG_RENDEZVOUS_SOCK=<this path> set ONLY on
 // that one spawned command (env prefix, never global). claude opens a unix socket here; writing one line
 // `{"type":"reply","text":"…"}\n` injects + submits the text as a prompt — no PTY typing, so multi-line input
-// and Enters can't be corrupted the way `tmux send-keys` was. The path is uniquely derived from the session id,
-// so we only ever address OUR OWN sockets (HARD ethics rule: never touch a session outside this product). It
-// lives in tmpdir tied to the claude process, so no extra lifecycle. liveness CONNECTS to it (a live LISTENER,
-// not merely the file — see rendezvousListening); deliver writes to it. Exported because sessions.ts builds the
-// launch env var from it and best-effort sweeps it on close — but the liveness/delivery USE is the adapter's, below.
-export const rvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
+// and Enters can't be corrupted the way `tmux send-keys` was. It lives in tmpdir tied to the claude process, so
+// no extra lifecycle. liveness CONNECTS to it (a live LISTENER, not merely the file — see rendezvousListening);
+// deliver writes to it.
+//
+// The path is a LAUNCH-TIME FACT, recorded — not a formula every consumer re-derives. The id alone was not
+// enough to name it: `SPEXCODE_HOME` scopes the store and `SPEXCODE_TMUX` scopes the tmux server, so two
+// worlds on one box (a fixture, a migration, a copied record) can hold the same session id — and while the
+// path ignored that scoping, they SHARED this socket. That is how an isolated teardown reached out and
+// stranded a live production agent, and delivery would have crossed the same way. So the path a launch hands
+// its agent is derived from the runtime the session belongs to (`runtimeRoot()` — the same identity that
+// scopes its store) and STAMPED beside the record, exactly like `agent.pid`: a launch-time fact, readable by
+// everyone who needs to reach that agent afterwards. Recording it (rather than re-deriving) also means the
+// derivation can change again without stranding anything already running.
+// `legacyRvSock` is the answer for a session launched BEFORE the stamp existed — its agent really did bind
+// the unscoped path — so those keep working untouched, and the fallback retires as they turn over.
+export const legacyRvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
+export const scopedRvSock = (id: string, dir = runtimeRoot()) =>
+  join(tmpdir(), `spexcode-rv-${createHash('sha1').update(dir).digest('hex').slice(0, 12)}-${id}.sock`)
+const rvStamp = (id: string) => sessionArtifactPath(id, 'rv.path')
+export const rvSock = (id: string): string => {
+  try { return readFileSync(rvStamp(id), 'utf8').trim() || legacyRvSock(id) } catch { return legacyRvSock(id) }
+}
+// launch's half: derive this session's socket in ITS runtime and record it, so every later reader (launch env,
+// liveness probe, delivery, teardown) reads the one path the agent actually bound.
+export function stampRvSock(id: string, dir = runtimeRoot()): string {
+  const path = scopedRvSock(id, dir)
+  mkdirSync(dirname(rvStamp(id)), { recursive: true })
+  writeFileSync(rvStamp(id), path)
+  return path
+}
 
 // @@@ rendezvousListening - the LISTENER check that IS claude's liveness truth ([[state]], [[harness-adapter]]).
 // A crashed/killed claude can leave its rvSock FILE on disk (a unix-domain socket path is NOT auto-unlinked on
@@ -237,7 +381,7 @@ export const rvSock = (id: string) => join(tmpdir(), `spexcode-rv-${id}.sock`)
 // wedged/thrashed path. Never throws.
 export type ListenerProbe = 'live' | 'dead' | 'unproven'
 const PROVEN_DEAD = new Set(['ECONNREFUSED', 'ENOENT'])
-export function rendezvousListening(id: string, timeoutMs = 800): Promise<ListenerProbe> {
+export function listenerAt(path: string, timeoutMs = 800): Promise<ListenerProbe> {
   return new Promise((resolve) => {
     let settled = false
     let c: ReturnType<typeof createConnection> | undefined
@@ -249,11 +393,12 @@ export function rendezvousListening(id: string, timeoutMs = 800): Promise<Listen
       resolve(v)
     }
     const timer = setTimeout(() => done('unproven'), timeoutMs)
-    try { c = createConnection({ path: rvSock(id) }) } catch { return done('unproven') }
+    try { c = createConnection({ path }) } catch { return done('unproven') }
     c.on('connect', () => done('live'))
     c.on('error', (e) => done(PROVEN_DEAD.has((e as NodeJS.ErrnoException).code ?? '') ? 'dead' : 'unproven'))
   })
 }
+export const rendezvousListening = (id: string, timeoutMs = 800): Promise<ListenerProbe> => listenerAt(rvSock(id), timeoutMs)
 // The app-server Unix socket MUST live on a SHORT, sun_path-safe path — NOT nested under the project runtime
 // dir. macOS caps `sun_path` at ~104 bytes, and `runtimeRoot()` flattens the ENTIRE project path into one
 // dash-segment (`encodeProject`), so `<runtimeRoot>/codex-app-server.sock` blew past the cap on a deep macOS
@@ -277,9 +422,40 @@ 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')
-
-function shQuote(s: string): string {
-  return `'${s.replace(/'/g, `'\\''`)}'`
+export const codexAppServerIsolation = (dir = runtimeRoot()) => join(dir, 'codex-app-server.scope')
+type CodexRuntimeGenerationProof = Readonly<{
+  pid: number
+  startToken: string
+  processGroupId: number
+  sessionId: number
+  isolation: string
+  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 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
+    return Object.freeze({
+      pid,
+      startToken: start,
+      processGroupId: topology.processGroupId,
+      sessionId: topology.sessionId,
+      isolation: scope,
+      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}`
+function codexRuntimeGeneration(dir = runtimeRoot()): string | null {
+  const proof = codexRuntimeGenerationProof(dir)
+  return proof ? codexRuntimeGenerationToken(proof) : null
 }
 
 // the spex launcher (bin/spex.mjs), baked into the codex launch script (mirrors materialize.ts's SPEX) so
@@ -369,6 +545,18 @@ export async function deliverViaRendezvous(id: string, text: string, wallMs?: nu
   return { ok: false, error: `rendezvous delivery was kicked by concurrent connects ${DELIVER_ATTEMPTS}× — prompt NOT delivered, retry the send` }
 }
 
+export async function deliverViaSocketOrWake(
+  id: string,
+  text: string,
+  coldWake: () => Promise<DispatchResult>,
+  unprovenError: string,
+): Promise<DispatchResult> {
+  const probe = await rendezvousListening(id)
+  if (probe === 'live') return deliverViaRendezvous(id, text)
+  if (probe === 'unproven') return { ok: false, error: unprovenError }
+  return coldWake()
+}
+
 type JsonRpc = { id?: number; method?: string; params?: unknown; result?: unknown; error?: { code?: number; message?: string } }
 
 // The JSON-RPC the delivery handshake speaks, in send order. Method names + param shapes are pinned to codex
@@ -463,10 +651,17 @@ export async function reportHeadlessTurnExit(id: string, harness: string, code:
   }
 }
 
-export function headlessTurnFailureShell(harness: string): string {
-  return `${shQuote(SPEX)} internal session-turn-fail "$SPEXCODE_SESSION_ID" ${shQuote(harness)} "$__spex_rc" || true`
+export function headlessTurnFailureShell(harness: string, swallow = true): string {
+  return `${shQuote(SPEX)} internal session-turn-fail "$SPEXCODE_SESSION_ID" ${shQuote(harness)} "$__spex_rc"${swallow ? ' || true' : ''}`
+}
+// @@@ sessionIdentityEnvVars - every environment variable that names ONE session: the launch-injected record
+// id plus each adapter's own `sessionEnvVar`. Adapter-derived, so a new harness needs no edit here. A
+// per-session process is entitled to carry them; a SHARED, project-scoped daemon must not — see the app-server
+// spawn below.
+export function sessionIdentityEnvVars(): string[] {
+  return [...new Set(['SPEXCODE_SESSION_ID', ...HARNESSES.map((h) => h.sessionEnvVar)])].filter(Boolean)
 }
-export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot(), attachTui = true): string {
+export function codexLaunchCommand(id: string, codexCmd = 'codex', serverCmd?: string, dir = runtimeRoot(), attachTui = true): string {
   const server = process.env.SPEXCODE_CODEX_SERVER_CMD || serverCmd || codexBinary(codexCmd)
   // The bypass flag ONLY reaches a thread's hook trust as a per-request `config` override, NOT as a CLI flag on
   // the shared `app-server` process (the app-server never reads its own `--dangerously-bypass-hook-trust` for a
@@ -478,12 +673,14 @@ export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?:
   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 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)}`,
     `log=${shQuote(log)}`,
     `lock=${shQuote(lock)}`,
     // codex-launch's bypass-trust gate (and writeTrust's) resolves the codex binary from SPEXCODE_CODEX_CMD;
@@ -519,12 +716,25 @@ export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?:
     // removed, the daemon's cwd becomes a DELETED dir, and codex then fails EVERY new thread's config load with
     // `failed to load configuration: No such file or directory` — bricking codex launch for the whole project
     // until the daemon is killed. Running it from "$dir" (which never gets deleted) makes it deletion-proof.
-    // exec so $! is the daemon itself; </dev/null detaches its stdin from the pane so it can't fight the TUI.
-    `  ( cd "$dir" && exec ${server} app-server --listen unix://"$sock" >"$log" 2>&1 </dev/null ) &`,
-    '  echo $! > "$pid"',
+    // For the SAME reason it must carry no session IDENTITY: it is started by whichever session happened to
+    // launch first and then serves every later thread, whose tool shells inherit its env — so a baked
+    // SPEXCODE_SESSION_ID (or any adapter's `sessionEnvVar`) is a stale lie for every session but one, and
+    // still a lie after that session closes and its record is swept (measured: daemons here running for days
+    // under a long-gone session's id). Everything downstream that resolves identity from the env then
+    // 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; }`,
     '  for i in $(seq 1 100); do [ -S "$sock" ] && break; sleep 0.05; done',
     'fi',
     'rmdir "$lockd" 2>/dev/null',
+    // The delegated bearer arrived only through fd 9. The shared-spawn helper consumed it (or the already-live
+    // socket made it unnecessary); close and scrub the channel before the per-session Codex client starts.
+    '[ "${SPEXCODE_MAINTENANCE_DELEGATE_FD:-}" != "9" ] || exec 9<&-',
+    'unset SPEXCODE_MAINTENANCE_DELEGATE_FD SPEXCODE_MAINTENANCE_SESSION_ID',
     // TWO launch modes, on ONE tail channel ("$@"). reopen() hands a `--resume <thread-id>` tail (see
     // codexHarness.resumeArg) to bring the SAME conversation back: resume that OWNED thread DIRECTLY — no new
     // thread, no first-turn prompt. ANY other tail is a NEW launch: BACKEND owns the thread — `codex-launch`
@@ -550,7 +760,11 @@ export function codexLaunchCommand(_id: string, codexCmd = 'codex', serverCmd?:
     ]),
     `fi`,
     `[ -n "$tid" ] || { echo "[spex] codex-launch produced no resumable thread" >&2; exit 1; }`,
-    ...(attachTui ? [`exec ${codexCmd}${tuiBypass} --remote unix://"$sock" resume "$tid"`] : []),
+    // The visible TUI is the OTHER entry point that creates an execution context for this session (a fresh
+    // launch attaches to the thread codex-launch just made; a reopen resumes an existing one), so it injects
+    // the same per-thread identity through codex's own `-c` override. Same rule, both entry points: whoever
+    // creates a context stamps that context's record id, and nothing downstream re-derives it.
+    ...(attachTui ? [`exec ${codexCmd}${tuiBypass} -c ${shQuote(`shell_environment_policy.set.SPEXCODE_SESSION_ID=${id}`)} --remote unix://"$sock" resume "$tid"`] : []),
   ].join('\n')
   return `bash -lc ${shQuote(script)} spexcode-codex`
 }
@@ -606,6 +820,239 @@ 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 } } }
 
+// 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 }
+function codexThreadMutation(sock: string, method: 'thread/archive' | 'thread/unarchive', threadId: string, fence?: CodexGenerationFence): Promise<{ ok: true } | { ok: false; error: string }> {
+  const generationError = () => fence && codexRuntimeGeneration(fence.dir) !== 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 })
+  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 }) => {
+      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 commit-unknown 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}` }) })
+    const send = (m: JsonRpc) => conn.write(wsText(JSON.stringify(m)))
+    conn.on('connect', () => {
+      const changed = generationError()
+      if (changed) return done({ ok: false, error: 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)}` })
+      if (m.id === 1 && m.result) {
+        const changed = generationError()
+        if (changed) return done({ ok: false, error: changed })
+        send({ method: 'initialized', params: {} })
+        return send({ id: 2, method, params: { threadId } })
+      }
+      if (m.id === 2 && m.result) {
+        const changed = generationError()
+        return changed ? done({ ok: false, error: changed }) : done({ ok: true })
+      }
+    }
+    conn.on('data', (chunk: Buffer) => {
+      fs.buf = Buffer.concat([fs.buf, chunk])
+      if (!upgraded) {
+        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}` })
+        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}` })
+    })
+  })
+}
+
+type CodexPagedIdsResult = { ok: true; ids: string[] } | { ok: false; error: string }
+// 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.
+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> {
+  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, requestId = 2, cursor: string | null = null
+    const ids = new Set<string>()
+    const done = (result: CodexPagedIdsResult) => {
+      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)
+    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)))
+    const requestPage = () => send({ id: requestId, method, params: { ...params, ...(cursor ? { cursor } : {}), limit: 100 } })
+    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 done({ ok: false, error: `Codex ${label} failed: ${message.error.message || JSON.stringify(message.error)}` })
+      if (message.id === 1 && message.result) { send({ method: 'initialized', params: {} }); return requestPage() }
+      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) {
+        const id = extractId(item)
+        if (typeof id === 'string') ids.add(id)
+      }
+      cursor = typeof page.nextCursor === 'string' && page.nextCursor ? page.nextCursor : null
+      if (!cursor) return done({ ok: true, ids: [...ids] })
+      requestId++
+      requestPage()
+    }
+    conn.on('data', (chunk: Buffer) => {
+      fs.buf = Buffer.concat([fs.buf, chunk])
+      if (!upgraded) {
+        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 loaded-reference census: ${head.split('\r\n')[0]}` })
+        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 ${label}` })
+    })
+  })
+}
+
+// Lightweight resident census: unlike the full shared-runtime probe, this scans only paginated manager IDs
+// and never issues thread/read includeTurns for each loaded reference.
+export async function codexLoadedReferenceIds(sock: string): Promise<{ ok: true; referenceIds: string[] } | { ok: false; error: string }> {
+  const result = await codexPagedIds(sock, 'thread/loaded/list', {}, (item) => {
+    if (typeof item === 'string') return item
+    const value = item as { id?: unknown; threadId?: unknown } | null
+    return typeof value?.id === 'string' ? value.id : typeof value?.threadId === 'string' ? value.threadId : null
+  }, 'loaded-reference census')
+  return result.ok ? { ok: true, referenceIds: result.ids } : result
+}
+
+function codexTargetTurnPresence(sock: string, threadId: string): Promise<{ ok: true; turnPresence: 'idle' | 'active' | 'unknown' } | { 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 }) => {
+      if (settled) return
+      settled = true; clearTimeout(timer); try { conn.destroy() } catch {}; resolve(result)
+    }
+    const timer = setTimeout(() => done({ ok: false, error: `Codex target thread ${threadId} read timed out after 5000ms` }), 5000)
+    conn.on('error', (error) => done({ ok: false, error: `Codex target thread ${threadId} read failed: ${rpcError(error)}` }))
+    conn.on('close', () => { if (!settled) done({ ok: false, error: `Codex app-server closed during target thread ${threadId} read` }) })
+    const send = (message: JsonRpc) => conn.write(wsText(JSON.stringify(message)))
+    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 done({ ok: false, error: `Codex target thread ${threadId} read failed: ${message.error.message || JSON.stringify(message.error)}` })
+      if (message.id === 1 && message.result) {
+        send({ method: 'initialized', params: {} })
+        return send({ id: 2, method: 'thread/read', params: { threadId, includeTurns: true } })
+      }
+      if (message.id !== 2 || !message.result) return
+      const turns = (message.result as { thread?: { turns?: unknown } }).thread?.turns
+      if (!Array.isArray(turns)) return done({ ok: true, turnPresence: 'unknown' })
+      return done({ ok: true, turnPresence: activeTurnIdFromThread(message.result) ? 'active' : 'idle' })
+    }
+    conn.on('data', (chunk: Buffer) => {
+      fs.buf = Buffer.concat([fs.buf, chunk])
+      if (!upgraded) {
+        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 target thread ${threadId} read: ${head.split('\r\n')[0]}` })
+        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 target thread ${threadId} read` })
+    })
+  })
+}
+
+// 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 }> {
+  const sourceKinds = Array.isArray(params.sourceKinds) && params.sourceKinds.length
+    ? params.sourceKinds
+    : [...CODEX_THREAD_SOURCE_KINDS]
+  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')
+}
+
+async function codexTargetMutationGuard(threadId: string, dir = runtimeRoot()): Promise<SharedRuntimeMutationGuard> {
+  const generationBefore = codexRuntimeGeneration(dir)
+  if (!generationBefore) return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'Codex shared app-server generation is unproven' }
+  const sock = codexAppServerSock(dir)
+  const [loaded, activeDescendants, archivedDescendants] = await Promise.all([
+    codexLoadedReferenceIds(sock),
+    codexThreadList(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
+    codexThreadList(sock, { ancestorThreadId: threadId, archived: true, sourceKinds: [] }),
+  ])
+  const referenceIds = loaded.ok ? loaded.referenceIds : []
+  const descendantIds = activeDescendants.ok && archivedDescendants.ok
+    ? [...new Set([...activeDescendants.ids, ...archivedDescendants.ids])]
+    : []
+  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 (codexRuntimeGeneration(dir) !== generationBefore)
+    return { healthy: false, referenceIds, targetTurnPresence, descendantIds, error: 'shared Codex app-server generation changed during target guard' }
+  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 sock = codexAppServerSock(dir)
+  const [guard, archivedList, activeList] = await Promise.all([
+    codexTargetMutationGuard(threadId, dir),
+    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 (!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 }
+}
+
 // Read a loaded thread id off the app-server via `thread/loaded/list`. With the backend now OWNING the thread
 // id at launch (codexStartThread → stored on the record), this is only the DELIVERY FALLBACK for a pre-existing
 // session whose id was never stored: it returns the first loaded thread. On a shared per-project server several
@@ -654,13 +1101,140 @@ export function codexThreadId(sock: string): Promise<{ ok: true; threadId: strin
   })
 }
 
+// Resource ownership asks the adapter for what the shared server actually owns now. Records are joined later;
+// they are never treated as references by themselves. A loaded thread is a control-plane reference and its
+// fresh inProgress turn (the same predicate used by delivery) distinguishes active from addressable-idle.
+export function codexSharedRuntimeProbe(dir = runtimeRoot()): Promise<SharedRuntimeProbe> {
+  const sock = codexAppServerSock(dir)
+  return (async () => {
+    // File presence is not process identity. A dead PID plus a stale socket file is the normal crash residue;
+    // only a live PID and a live listener establish a resident control plane. This keeps a deliberately absent
+    // root a healthy empty census while leaving live-but-ambiguous roots loud and visible.
+    let pid = 0
+    try { pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim()) } catch { /* absent/stale */ }
+    const pidLive = pid > 0 && !!processStartToken(pid)
+    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)' }
+    return new Promise<SharedRuntimeProbe>((resolve) => {
+    const conn: Socket = createConnection(sock)
+    const fs: FrameState = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) }
+    const references = new Map<string, SharedRuntimeProbe['references'][number]>()
+    const requests = new Map<number, string>()
+    const loadedRequests = new Set<number>()
+    const loadedIds = new Set<string>()
+    let loadedRequestId = 2
+    let loadedCursor: string | null = null
+    let upgraded = false
+    let settled = false
+    let timer: NodeJS.Timeout
+    const done = (result: SharedRuntimeProbe) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { conn.destroy() } catch { /* */ }
+      resolve(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)
+    conn.on('error', (e) => fail(`codex app-server ownership probe failed: ${rpcError(e)}`))
+    conn.on('close', () => fail('codex app-server closed during ownership probe'))
+    const send = (m: JsonRpc) => conn.write(wsText(JSON.stringify(m)))
+    conn.on('connect', () => 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) {
+        if (typeof m.id === 'number' && loadedRequests.has(m.id)) return fail(`codex app-server loaded/list failed: ${m.error.message || JSON.stringify(m.error)}`)
+        const request = typeof m.id === 'number' ? requests.get(m.id) : undefined
+        if (request) {
+          requests.delete(m.id!)
+          if (!requests.size) done({ healthy: true, references: [...references.values()] })
+          return
+        }
+        return fail(`codex app-server ownership request ${m.id ?? 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}`)
+      }
+      if (m.id === 1 && m.result) {
+        send({ method: 'initialized', params: {} })
+        loadedRequests.add(loadedRequestId)
+        return send({ id: loadedRequestId, method: 'thread/loaded/list', params: { limit: 100 } })
+      }
+      if (typeof m.id === 'number' && loadedRequests.has(m.id) && m.result) {
+        loadedRequests.delete(m.id)
+        const data = (m.result as { data?: unknown }).data
+        const ids = [...new Set(Array.isArray(data) ? data.flatMap((item) => {
+          if (typeof item === 'string') return [item]
+          const id = (item as { id?: unknown; threadId?: unknown })?.id ?? (item as { threadId?: unknown })?.threadId
+          return typeof id === 'string' ? [id] : []
+        }) : [])]
+        for (const threadId of ids) loadedIds.add(threadId)
+        const next = (m.result as { nextCursor?: unknown }).nextCursor
+        loadedCursor = typeof next === 'string' && next ? next : null
+        if (loadedCursor) {
+          loadedRequestId++
+          loadedRequests.add(loadedRequestId)
+          return send({ id: loadedRequestId, method: 'thread/loaded/list', params: { cursor: loadedCursor, limit: 100 } })
+        }
+        // Continue with the complete paginated set, not just the first manager page.
+        if (!loadedIds.size) return done({ healthy: true, references: [] })
+        loadedIds.forEach((threadId) => {
+          const id = 100 + requests.size
+          references.set(threadId, { referenceId: threadId, turnPresence: 'unknown' })
+          requests.set(id, threadId)
+          send({ id, method: 'thread/read', params: { threadId, includeTurns: true } })
+        })
+        return
+      }
+      if (typeof m.id === 'number' && requests.has(m.id) && m.result) {
+        const threadId = requests.get(m.id)!
+        requests.delete(m.id)
+        const thread = (m.result as { thread?: { turns?: Array<{ id?: string; status?: string }> } }).thread
+        const turnId = activeTurnIdFromThread(m.result)
+        references.set(threadId, {
+          referenceId: threadId,
+          turnPresence: !Array.isArray(thread?.turns) ? 'unknown' : turnId ? 'active' : 'idle',
+          ...(turnId ? { turnId } : {}),
+        })
+        if (!requests.size) done({ healthy: true, references: [...references.values()] })
+      }
+    }
+    conn.on('data', (chunk: Buffer) => {
+      fs.buf = Buffer.concat([fs.buf, chunk])
+      if (!upgraded) {
+        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 fail(`codex app-server refused ownership probe: ${head.split('\r\n')[0]}`)
+        upgraded = true
+        fs.buf = fs.buf.slice(i + 4)
+        send(wsInitialize)
+      }
+      if (drainWsFrames(fs, conn, handle)) fail('codex app-server closed during ownership probe')
+    })
+    })
+  })()
+}
+
 // @@@ codexStartThread - the BACKEND owns the thread. On the shared PER-PROJECT app-server we `thread/start
 // { cwd }` (codex resolves config/hooks/AGENTS.md from that worktree cwd — exactly as claude loads CLAUDE.md
 // per-worktree — so one project-scoped server behaves analogously to a per-worktree launch), and the result
 // carries the new thread id (`result.thread.id`). The launcher stores that id on the governed record and
 // fires the first turn; there is no capture hook and no rollout/cwd scan. Same WS framing as codexThreadId.
 // Never throws.
-export function codexStartThread(sock: string, cwd?: string, bypassHookTrust = false): Promise<{ ok: true; threadId: string } | { ok: false; error: string }> {
+// @@@ codexStartThreadParams - what a BACKEND-owned thread is created with. `config` is the per-request
+// override map (the only channel that reaches a thread): `bypass_hook_trust` so our hooks run, and
+// `shell_environment_policy.set` so every command this thread spawns carries the governed record id. The
+// latter is codex's answer to a structural fact — a codex tool shell descends from the SHARED app-server, so
+// it must inherit no identity and be given its own instead (verified live: the shell reports exactly the
+// injected id, and the launcher's env leaks nothing).
+export function codexStartThreadParams(cwd?: string, bypassHookTrust = false, shellEnv?: Record<string, string>): Record<string, unknown> {
+  const config = {
+    ...(bypassHookTrust ? { bypass_hook_trust: true } : {}),
+    ...(shellEnv && Object.keys(shellEnv).length ? { shell_environment_policy: { set: shellEnv } } : {}),
+  }
+  return { ...(cwd ? { cwd } : {}), ...(Object.keys(config).length ? { config } : {}) }
+}
+export function codexStartThread(sock: string, cwd?: string, bypassHookTrust = false, shellEnv?: Record<string, string>): Promise<{ ok: true; threadId: 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) }
@@ -690,8 +1264,13 @@ export function codexStartThread(sock: string, cwd?: string, bypassHookTrust = f
         // own `--remote resume` TUI client injects it. Without it the worktree's UNtrusted `.codex` config layer
         // stays disabled → no local hooks discovered → no Stop gate. Only on the bypass path (older codex without
         // the flag uses writeCodexTrust's hash and never sees this key).
-        const params = { ...(cwd ? { cwd } : {}), ...(bypassHookTrust ? { config: { bypass_hook_trust: true } } : {}) }
-        return send({ id: 2, method: 'thread/start', params })
+        // The same override map carries the thread's IDENTITY. A codex tool shell is spawned by the SHARED
+        // app-server, so it can inherit no session id — and must not, that leak was github#76. Codex's own
+        // `shell_environment_policy.set` injects vars into every command THIS thread spawns, so the backend
+        // stamps the governed record id there at thread creation, the same moment and the same knowledge with
+        // which a claude launch bakes it into its agent's env. Identity then arrives per-thread, needing no
+        // alias, no store lookup, and no cwd anywhere downstream.
+        return send({ id: 2, method: 'thread/start', params: codexStartThreadParams(cwd, bypassHookTrust, shellEnv) })
       }
       if (m.id === 2 && m.result) {
         const tid = (m.result as { thread?: { id?: string } })?.thread?.id
@@ -1129,10 +1708,57 @@ export function opencodeLaunchCommand(opencodeCmd = 'opencode'): string {
   return `bash -lc ${shQuote(script)} spexcode-opencode`
 }
 
+const socketListenerLiveness: Harness['liveness'] = (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) =>
+  (tmuxAlive && !!socketLive ? 'online' : 'offline')
+
+const socketListenerOrPidAliveLiveness: Harness['liveness'] = (_rec, tmuxAlive, _runtimeDir, pane, socketLive) =>
+  (tmuxAlive && (!!socketLive || 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*
+// socket, and the honest test of "theirs" is that the agent it just killed is GONE. It used to unlink on
+// faith, which is unsound because a socket path is derived from the session id ALONE: it is the one
+// per-session resource NOT scoped by the store (`SPEXCODE_HOME`) or the tmux server (`SPEXCODE_TMUX`), so an
+// isolated instance closing an id that also names a LIVE session elsewhere had its `kill-session` miss (that
+// IS namespaced) while this unlink landed (it is not) — deleting a working agent's socket out from under it.
+// The damage is invisible and permanent: the listener stays bound to an unlinked path, so nothing can ever
+// connect again (delivery fails its existsSync gate) and every probe ENOENTs, which the liveness axis reads as
+// PROVEN death — a live worker reading `offline`, which in turn disarms the relaunch guard.
+// So: poll until death is proven, then unlink. A listener still answering past the wall is somebody's live
+// agent — mine that failed to die, or one that was never mine — and either way it is not ours to remove: leave
+// it and say so. `unproven` is not proof either, so it is left too. The asymmetry is deliberate: a dead-but-
+// unlinked file is harmless residue the next teardown reaps, while a wrong unlink strands a working agent.
+const SOCK_DEATH_WALL_MS = 2000   // a killed agent releases its listener in well under this; the wall only bounds the wrong case
+const SOCK_DEATH_POLL_MS = 100
+export const unlinkSocks = async (...paths: string[]): Promise<void> => {
+  for (const path of paths) {
+    if (!existsSync(path)) continue
+    const deadline = Date.now() + SOCK_DEATH_WALL_MS
+    let probe = await listenerAt(path)
+    while (probe !== 'dead' && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, SOCK_DEATH_POLL_MS))
+      probe = await listenerAt(path)
+    }
+    if (probe !== 'dead') {
+      console.warn(`spex: left ${path} in place — ${probe === 'live'
+        ? 'a listener is still answering it, so it belongs to a running agent (this teardown did not kill it, or it was never ours)'
+        : 'the listener probe could not conclude, and death was never proven'}`)
+      continue
+    }
+    try { rmSync(path, { force: true }) } catch { /* already gone */ }
+  }
+}
+
+const rendezvousLaunchEnv = (id: string): string[] => [
+  'CLAUDE_BG_BACKEND=daemon',
+  `CLAUDE_BG_RENDEZVOUS_SOCK=${rvSock(id)}`,
+]
+const noLaunchEnv = (): string[] => []
+
 export const claudeHarness: Harness = {
   id: 'claude',
   headless: false,
-  messageStream: false,
   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
@@ -1140,6 +1766,7 @@ export const claudeHarness: Harness = {
   baseCmd: claudeBaseCmd,
   sessionIdArg: (id) => `--session-id ${id}`,        // the caller chooses the id
   sessionEnvVar: 'CLAUDE_CODE_SESSION_ID',
+  launchEnv: rendezvousLaunchEnv,
   shimFile: (proj) => join(proj, '.claude', 'settings.json'),
   worktreeHookAnchor: () => null,                    // claude's shim already lives in the worktree (.claude/settings.json) — self-anchors, no root rewrite
   contractFiles: (proj) => [join(proj, 'CLAUDE.md')],
@@ -1153,9 +1780,11 @@ export const claudeHarness: Harness = {
   // 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
   // dead-pane-reads-working bug). See rendezvousListening.
-  liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
+  liveness: socketListenerLiveness,
+  leafOwnerNeedle: (rec) => rec.session,
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
-  cleanupRuntime: (rec) => { try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ } },
+  cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
+  coldRuntime: async () => ({ ok: true }),
   // the TUI's sessions panel ("← for agents"): a reply injected here is parsed + enqueued to the PANEL context
   // and never drained (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so
   // the parse-confirmed delivery above would still report a false success into it. Matched on the panel's own
@@ -1166,6 +1795,11 @@ export const claudeHarness: Harness = {
       ? 'the claude TUI is focused on its sessions panel ("← for agents"), which silently swallows injected prompts — press Enter in the session terminal to return to the composer, then resend'
       : null,
   resumeArg: (rec) => `--resume ${rec.session}`,
+  // claude's settled launch failures, in its own words: a `--resume` id it has no conversation for (the id was
+  // never claude's, or its transcript is gone), and a rejected credential. Both are the same command failing
+  // the same way every time — the human must repair the conversation or the login, so the transport stops at
+  // one attempt and shows this line instead of burying it under two more identical failures.
+  fatalLaunchOutput: ['No conversation found with session ID', 'Invalid API key', 'Please run /login'],
 }
 
 // Claude headless is a separate harness, not a claude mode. Its materialize half is exactly Claude's and is
@@ -1174,23 +1808,25 @@ export const claudeHeadlessHarness: Harness = {
   ...claudeHarness,
   id: 'claude-headless',
   headless: true,
-  messageStream: true,
+  runtimeOwnership: 'adapter',
   ownsRendezvous: false,
   paneTitleIsSelfSummary: false,
   launchCmd: (id, runtimeDir, cmd) => claudeHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), claudeBaseCmd(cmd)),
-  // Liveness is the intact record's property. A missing controller/child fails loudly at control time rather
-  // than turning an idle (no child) session into a speculative offline row.
-  liveness: () => 'online',
+  launchEnv: noLaunchEnv,
+  // Liveness is the intact, non-stopped record's property. A missing controller/child fails loudly at control
+  // time rather than turning an idle (no child) session into a speculative offline row.
+  liveness: recordOnline,
   deliver: deliverViaClaudeHeadless,
   interrupt: interruptClaudeHeadless,
-  cleanupRuntime: (rec) => { try { rmSync(claudeHeadlessSock(rec.session), { force: true }) } catch { /* already gone */ } },
+  cleanupRuntime: (rec) => unlinkSocks(claudeHeadlessSock(rec.session)),
+  coldRuntime: async () => ({ ok: false, reason: 'claude-headless has no exact resident unload verification' }),
   deliveryBlockedBy: undefined,
 }
 
 export const codexHarness: Harness = {
   id: 'codex',
   headless: false,
-  messageStream: false,
+  sharedRuntimeSpawn: true,
   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
@@ -1198,6 +1834,7 @@ export const codexHarness: Harness = {
   baseCmd: codexBaseCmd,
   sessionIdArg: () => '',                            // codex assigns its own id (the backend owns it via thread/start)
   sessionEnvVar: 'CODEX_THREAD_ID',
+  launchEnv: noLaunchEnv,
   // Codex discovers a LINKED worktree's PROJECT hooks from the ROOT CHECKOUT's `.codex`, NOT the worktree's
   // (codex-rs `root_checkout_hooks_folder_for_dir` rewrites the hooks-config folder to <repo_root>/<rel>/.codex
   // for any linked worktree). Every worktree's thread (cwd = worktree root) therefore reads the SAME
@@ -1252,12 +1889,236 @@ export const codexHarness: Harness = {
     if (pane?.pidAlive !== undefined) return pane.pidAlive ? 'online' : 'offline'
     return paneTreeRunsCodex(pane) ? 'online' : 'offline'
   },
+  leafOwnerNeedle: (rec) => rec.harnessSessionId ?? null,
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
-  cleanupRuntime: () => { /* project-scoped app-server is shared; no per-session transport to remove */ },
+  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' }
+    const threadId = rec.harnessSessionId
+    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: [] }),
+    ])
+    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})` }
+    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
+  },
+  coldRuntime: async (rec) => {
+    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())
+    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)
+    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))
+      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` }
+    }
+    let verified: { ok: true } | { ok: false; reason: string } = { ok: false, reason: 'Codex archive verification timed out' }
+    const verifyDeadline = Date.now() + 30_000
+    for (let attempt = 0; attempt < 6 && Date.now() < verifyDeadline; attempt++) {
+      verified = await coldCheck()
+      if (verified.ok) break
+      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}` }
+  },
+  restoreRuntime: async (rec) => {
+    if (!rec.harnessSessionId) return { ok: false, reason: 'no exact Codex thread identity is registered' }
+    const sock = codexAppServerSock(runtimeRoot())
+    const reconcile = async (): Promise<{ ok: true } | { ok: false; reason: string }> => {
+      const [active, archived] = await Promise.all([
+        codexThreadList(sock, { archived: false, sourceKinds: [] }),
+        codexThreadList(sock, { archived: true, sourceKinds: [] }),
+      ])
+      if (!active.ok || !archived.ok) return { ok: false, reason: 'Codex restore state could not be reconciled' }
+      const inActive = active.ids.includes(rec.harnessSessionId!)
+      const inArchived = archived.ids.includes(rec.harnessSessionId!)
+      if (inActive && !inArchived) return { ok: true }
+      if (inArchived && !inActive) return { ok: false, reason: 'Codex thread remains archived; restore can be retried' }
+      return { ok: false, reason: 'Codex restore state is ambiguous (thread in both or neither collection)' }
+    }
+    const restored = await codexThreadMutation(sock, 'thread/unarchive', rec.harnessSessionId)
+    if (!restored.ok) return reconcile()
+    return reconcile()
+  },
+  sharedRuntimes: (runtimeDir) => [{
+    key: 'codex-app-server',
+    label: 'Codex app-server',
+    pidFile: codexAppServerPid(runtimeDir),
+    isolationFile: codexAppServerIsolation(runtimeDir),
+    residency: async () => {
+      const sock = codexAppServerSock(runtimeDir)
+      let pid = 0
+      try { pid = Number(readFileSync(codexAppServerPid(runtimeDir), 'utf8').trim()) } catch { /* stale/missing pid */ }
+      const pidLive = pid > 0 && !!processStartToken(pid)
+      const listener = await listenerAt(sock, 800)
+      if (!pidLive && listener === 'dead') return { healthy: true, referenceIds: [], rootAbsent: true }
+      if (pidLive && (!codexRuntimeGeneration(runtimeDir) || listener !== 'live'))
+        return { healthy: false, referenceIds: [], error: 'Codex shared root identity/socket generation is not proven' }
+      if (!pidLive || listener !== 'live')
+        return { healthy: false, referenceIds: [], error: 'Codex shared root state is unknown' }
+      const result = await codexLoadedReferenceIds(sock)
+      return result.ok ? { healthy: true, referenceIds: result.referenceIds } : { healthy: false, referenceIds: [], error: result.error }
+    },
+    mutationGuard: (targetReferenceId) => codexTargetMutationGuard(targetReferenceId, runtimeDir),
+    probe: () => codexSharedRuntimeProbe(runtimeDir),
+  }],
   // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
   // a tail handed to a bare `codex` — the script's final `codex … resume "$tid"` performs codex's own resume on
   // the owned id, the SAME conversation); none → empty tail → relaunch a FRESH thread on the same worktree/record.
   resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
+  // codex's own settled failure: a thread id whose rollout is not on disk can never be resumed, so the launch
+  // that says so has already decided. (Its transient sibling — the rollout still being written — is handled
+  // BEFORE launch by waitForCodexRollout, so what reaches here is the permanent case.)
+  fatalLaunchOutput: ['no rollout found for thread id'],
+}
+
+type CodexHeadlessLaunchReadinessProof = Readonly<{
+  kind: 'codex-headless-shared-runtime'
+  descriptorKey: string
+  generation: CodexRuntimeGenerationProof
+  target: Readonly<{
+    sessionId: string
+    threadId: string
+    ownerSessionId: string
+    ownerCount: 1
+    ownerState: 'governed'
+    referenceState: 'loaded'
+    protectsControlPlane: true
+  }>
+}>
+
+const sameCodexHeadlessReadinessProof = (left: CodexHeadlessLaunchReadinessProof, right: CodexHeadlessLaunchReadinessProof) =>
+  left.kind === right.kind &&
+  left.descriptorKey === right.descriptorKey &&
+  codexRuntimeGenerationToken(left.generation) === codexRuntimeGenerationToken(right.generation) &&
+  left.target.sessionId === right.target.sessionId &&
+  left.target.threadId === right.target.threadId &&
+  left.target.ownerSessionId === right.target.ownerSessionId &&
+  left.target.ownerCount === right.target.ownerCount &&
+  left.target.ownerState === right.target.ownerState &&
+  left.target.referenceState === right.target.referenceState &&
+  left.target.protectsControlPlane === right.target.protectsControlPlane
+
+const governedSharedRuntimeOwners = (runtimeDir: string, descriptorKey: string, threadId: string): string[] | null => {
+  const root = join(runtimeDir, 'sessions')
+  let entries
+  try { entries = readdirSync(root, { withFileTypes: true }) }
+  catch (error) { return (error as NodeJS.ErrnoException).code === 'ENOENT' ? [] : null }
+  const owners: string[] = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    let parsed: unknown
+    try { parsed = JSON.parse(readFileSync(join(root, entry.name, 'session.json'), 'utf8')) }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
+      return null
+    }
+    if (!parsed || typeof parsed !== 'object') return null
+    const record = parsed as { session_id?: unknown; governed?: unknown; harness?: unknown; harness_session_id?: unknown }
+    if (typeof record.session_id !== 'string') return null
+    if (record.governed !== true) continue
+    const harnessId = typeof record.harness === 'string' && record.harness ? record.harness : defaultHarness.id
+    let sharesDescriptor = false
+    try { sharesDescriptor = (harnessById(harnessId).sharedRuntimes?.(runtimeDir) ?? []).some((descriptor) => descriptor.key === descriptorKey) }
+    catch { return null }
+    if (sharesDescriptor && record.harness_session_id === threadId) owners.push(record.session_id)
+  }
+  return owners
+}
+
+async function codexHeadlessReadinessProof(current: () => HarnessLaunchReadyRecord | null): Promise<CodexHeadlessLaunchReadinessProof | null> {
+  const record = current()
+  if (!record?.governed || record.stopped || record.archived || !record.harnessSessionId) return null
+  const descriptor = codexHeadlessHarness.sharedRuntimes?.(record.runtimeDir)
+    .find((candidate) => candidate.key === 'codex-app-server')
+  if (!descriptor?.residency) return null
+  const generationBefore = codexRuntimeGenerationProof(record.runtimeDir)
+  if (!generationBefore) return null
+  let resident: Awaited<ReturnType<NonNullable<SharedRuntimeDescriptor['residency']>>>
+  try { resident = await descriptor.residency() }
+  catch { return null }
+  if (!resident.healthy) return null
+  if (!resident.referenceIds.includes(record.harnessSessionId)) return null
+  const owners = governedSharedRuntimeOwners(record.runtimeDir, descriptor.key, record.harnessSessionId)
+  if (!owners || owners.length !== 1 || owners[0] !== record.session) return null
+  const generationAfter = codexRuntimeGenerationProof(record.runtimeDir)
+  if (!generationAfter || codexRuntimeGenerationToken(generationBefore) !== codexRuntimeGenerationToken(generationAfter)) return null
+  return Object.freeze({
+    kind: 'codex-headless-shared-runtime',
+    descriptorKey: descriptor.key,
+    generation: generationAfter,
+    target: Object.freeze({
+      sessionId: record.session,
+      threadId: record.harnessSessionId,
+      ownerSessionId: owners[0],
+      ownerCount: 1,
+      ownerState: 'governed',
+      referenceState: 'loaded',
+      protectsControlPlane: true,
+    }),
+  })
 }
 
 // Codex headless is an independent adapter: its materialization and app-server delivery are exactly Codex's,
@@ -1267,12 +2128,27 @@ export const codexHeadlessHarness: Harness = {
   ...codexHarness,
   id: 'codex-headless',
   headless: true,
+  runtimeOwnership: 'adapter',
   launchOneShot: true,
-  messageStream: false,
   launchCmd: (id, runtimeDir, cmd) => codexHeadlessLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()),
-  // Record-backed liveness is the family contract for sleeping headless threads. A broken app-server or missing
-  // thread is surfaced by the inherited delivery call rather than converted into a speculative offline state.
-  liveness: () => 'online',
+  // Record-backed liveness is the family contract for sleeping headless threads. An explicit stop is the one
+  // offline marker; other app-server/thread failures surface through delivery rather than speculative liveness.
+  liveness: recordOnline,
+  launchReady: async (current, deadline) => {
+    for (;;) {
+      const proof = await codexHeadlessReadinessProof(current)
+      if (proof) return {
+        proof,
+        validate: async (latest) => {
+          const currentProof = await codexHeadlessReadinessProof(latest)
+          return !!currentProof && sameCodexHeadlessReadinessProof(proof, currentProof)
+        },
+      }
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) return null
+      await new Promise((resolve) => setTimeout(resolve, Math.min(200, remaining)))
+    }
+  },
   // There is no TUI to restart and the project app-server keeps the thread addressable. A forced reopen therefore
   // runs the headless launch's empty-tail no-op; normal resume remains guarded by record-backed online liveness.
   resumeArg: () => '',
@@ -1283,8 +2159,8 @@ export const codexHeadlessHarness: Harness = {
 // lives IN the worktree, and the rendezvous prompt/liveness channel is REUSED wholesale — pi has no external
 // hook binding (its lifecycle surface is the in-process extension API), so the shim is a GENERATED TypeScript
 // extension (.pi/extensions/spexcode.ts, run natively by pi) that forwards five claude-shaped events to
-// dispatch.sh AND binds this session's rendezvous socket itself (sessions.ts already exports
-// CLAUDE_BG_RENDEZVOUS_SOCK to every ownsRendezvous launch) speaking the reclaude line protocol — so
+// dispatch.sh AND binds this session's rendezvous socket itself (the adapter's launchEnv exports
+// CLAUDE_BG_RENDEZVOUS_SOCK) speaking the reclaude line protocol — so
 // deliverViaRendezvous and the socket-listener liveness work UNCHANGED. Trust: pi gates project-local
 // extensions behind saved per-directory trust (~/.pi/agent/trust.json), so writeTrust stamps the main
 // checkout there (the nearest-parent lookup covers nested worktrees) and the launch carries `--approve` as
@@ -1292,7 +2168,6 @@ export const codexHeadlessHarness: Harness = {
 export const piHarness: Harness = {
   id: 'pi',
   headless: false,
-  messageStream: false,
   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
@@ -1300,6 +2175,7 @@ export const piHarness: Harness = {
   baseCmd: piBaseCmd,
   sessionIdArg: (id) => `--session-id ${id}`,        // caller pins the exact session id, claude-style (created if missing)
   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'),
   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)
@@ -1315,9 +2191,11 @@ export const piHarness: Harness = {
   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.
-  liveness: (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline'),
+  liveness: socketListenerLiveness,
+  leafOwnerNeedle: (rec) => rec.session,
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
-  cleanupRuntime: (rec) => { try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ } },
+  cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
+  coldRuntime: async () => ({ ok: true }),
   // reopen the SAME conversation: `--session <id>` resumes the exact session we pinned at launch and FAILS
   // LOUD when its file is gone (unlike `--session-id`, which would silently mint a fresh empty session).
   resumeArg: (rec) => `--session ${rec.session}`,
@@ -1331,15 +2209,13 @@ export const piHeadlessHarness: Harness = {
   ...piHarness,
   id: 'pi-headless',
   headless: true,
-  messageStream: false,
+  runtimeOwnership: 'adapter',
   paneTitleIsSelfSummary: false,
   launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
-  liveness: () => 'online',
+  liveness: recordOnline,
   deliver: deliverViaPiHeadless,
-  cleanupRuntime: (rec) => {
-    try { rmSync(piHeadlessSock(rec.session), { force: true }) } catch { /* already gone */ }
-    try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ }
-  },
+  cleanupRuntime: (rec) => unlinkSocks(piHeadlessSock(rec.session), rvSock(rec.session)),
+  coldRuntime: async () => ({ ok: false, reason: 'pi-headless has no exact resident unload verification' }),
   deliveryBlockedBy: undefined,
   resumeArg: (rec) => `--session ${rec.session}`,
 }
@@ -1347,7 +2223,6 @@ export const piHeadlessHarness: Harness = {
 export const opencodeHarness: Harness = {
   id: 'opencode',
   headless: false,
-  messageStream: false,
   events: OPENCODE_EVENTS,
   // LITERALLY true: the generated plugin ([[opencode-harness]], opencode.ts) BINDS the per-session rendezvous
   // socket the launch env hands it and speaks the reply/repaint mini-protocol, so claude's deliver (atomic
@@ -1362,6 +2237,7 @@ export const opencodeHarness: Harness = {
   // (no codex-style shared-server contamination). This var is therefore never set; envSessionId's
   // SPEXCODE_SESSION_ID tier resolves the record.
   sessionEnvVar: 'OPENCODE_SESSION_ID',
+  launchEnv: rendezvousLaunchEnv,
   // 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'),
@@ -1379,10 +2255,11 @@ export const opencodeHarness: Harness = {
   // 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
   // load still reads honestly from the process signal instead of a false offline.
-  liveness: (_rec, tmuxAlive, _runtimeDir, pane, socketLive) =>
-    (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline'),
+  liveness: socketListenerOrPidAliveLiveness,
+  leafOwnerNeedle: (rec) => rec.session,
   deliver: (rec, text) => deliverViaRendezvous(rec.session, text),
-  cleanupRuntime: (rec) => { try { rmSync(rvSock(rec.session), { force: true }) } catch { /* already gone */ } },
+  cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
+  coldRuntime: async () => ({ ok: true }),
   // owned opencode session id → `--resume <id>` marker (the launch script re-attaches `--session <id>`, the
   // SAME conversation); never captured → `--continue` marker (opencode's own "last session in this directory",
   // which in a dedicated worktree is this worker's). The discriminator is sound for the same reason codex's
@@ -1396,21 +2273,19 @@ export const opencodeHeadlessHarness: Harness = {
   ...opencodeHarness,
   id: 'opencode-headless',
   headless: true,
-  messageStream: false,
+  runtimeOwnership: 'adapter',
   launchCmd: (_id, _runtimeDir, cmd) => opencodeHeadlessLaunchCommand(opencodeBaseCmd(cmd)),
-  // A sleeping native conversation is still addressable by its record. Transport breakage belongs to the
-  // next delivery, where the live rendezvous or pane wake reports it loudly.
-  liveness: () => 'online',
+  // A sleeping native conversation is still addressable by its non-stopped record. Transport breakage belongs
+  // to the next delivery, where the live rendezvous or pane wake reports it loudly.
+  liveness: recordOnline,
+  coldRuntime: async () => ({ ok: false, reason: 'opencode-headless has no exact resident unload verification' }),
   deliver: async (rec, text) => {
-    const probe = await rendezvousListening(rec.session)
-    if (probe === 'live') return deliverViaRendezvous(rec.session, text)
-    if (probe === 'unproven') {
-      return {
-        ok: false,
-        error: `opencode-headless rendezvous probe was inconclusive for session ${rec.session} - refusing to start a possibly duplicate turn`,
-      }
-    }
-    return spawnOpenCodeHeadlessTurn(rec, text, opencodeBaseCmd(rec.launchCmd ?? undefined), rvSock(rec.session))
+    return deliverViaSocketOrWake(
+      rec.session,
+      text,
+      () => spawnOpenCodeHeadlessTurn(rec, text, opencodeBaseCmd(rec.launchCmd ?? undefined), rvSock(rec.session)),
+      `opencode-headless rendezvous probe was inconclusive for session ${rec.session} - refusing to start a possibly duplicate turn`,
+    )
   },
 }