spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/harness.js

@@ -0,0 +1,3026 @@
+import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { createHash, randomBytes } from 'node:crypto';
+import { createConnection } from 'node:net';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { claudeSlashCommands, codexSlashCommands, opencodeSlashCommands, piSlashCommands } from './slash-commands.js';
+import { OPENCODE_EVENTS, opencodePluginSource } from './opencode.js';
+import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js';
+import { claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
+import { codexHeadlessLaunchCommand } from './codex-headless.js';
+import { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
+import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
+import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath } from '@spexcode/spec-core';
+import { git } from '@spexcode/spec-core';
+import { shQuote } from './sh.js';
+import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime } from '@spexcode/spec-core';
+import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, resolveCodexGenerationForSession } from './codex-runtime-generations.js';
+import { writeFileIfChanged } from './file-write.js';
+import { codexRolloutPath, noExecutionTrace, readCodexExecutionTrace, readLocalStoreExecutionTrace, readProjectJsonlExecutionTrace, readSessionJsonlExecutionTrace } from './execution-trace.js';
+import { harnessIdentity, HARNESS_IDENTITIES } from '@spexcode/spec-core';
+// 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, runtimeDir = runtimeRoot()) {
+    const descriptors = new Map();
+    const recordKeys = new Map();
+    for (const rec of records) {
+        if (!rec.harnessSessionId)
+            continue;
+        const harness = harnessById(rec.harness || defaultHarness.id);
+        const exactKey = harness.targetDescriptorKey?.(rec) ?? null;
+        const keys = (harness.sharedRuntimes?.(runtimeDir) ?? []).filter((descriptor) => !exactKey || descriptor.key === exactKey).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];
+        }
+        catch (error) {
+            return [key, { healthy: false, referenceIds: [], error: error.message }];
+        }
+    }));
+    const byKey = new Map(probes);
+    const result = new Map();
+    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;
+}
+// @@@ rendezvous control socket - claude's DETERMINISTIC, ONLY input path for PROMPTS to sessions WE launch.
+// 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. 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) => join(tmpdir(), `spexcode-rv-${id}.sock`);
+// @@@ rendezvousSocketBase - macOS's TMPDIR commonly expands to /var/folders/<long-user-path>, leaving a
+// UUID-scoped socket beyond its 104-byte sun_path limit. It can be created and observed by pathname but every
+// connect fails EINVAL, which looks exactly like an unresponsive worker. Use a literal short /tmp spelling
+// (not tmpdir(), whose resolved form is long on macOS) with the same private per-uid directory pattern as the
+// Codex runtime socket. Existing launches retain their stamped old path through rvSock(); only new launches use
+// this base.
+const rendezvousSocketBase = () => {
+    const base = join('/tmp', `spexcode-rv-${process.getuid?.() ?? 0}`);
+    mkdirSync(base, { recursive: true, mode: 0o700 });
+    return base;
+};
+export const scopedRvSock = (id, dir = runtimeRoot()) => join(rendezvousSocketBase(), `spexcode-rv-${createHash('sha1').update(dir).digest('hex').slice(0, 12)}-${id}.sock`);
+const rvStamp = (id) => sessionArtifactPath(id, 'rv.path');
+export const rvSock = (id) => {
+    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, dir = runtimeRoot()) {
+    const path = scopedRvSock(id, dir);
+    mkdirSync(dirname(rvStamp(id)), { recursive: true });
+    writeFileSync(rvStamp(id), path);
+    return path;
+}
+const PROVEN_DEAD = new Set(['ECONNREFUSED', 'ENOENT']);
+export function listenerAt(path, timeoutMs = 800) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let c;
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                c?.destroy();
+            }
+            catch { /* */ }
+            resolve(v);
+        };
+        const timer = setTimeout(() => done('unproven'), timeoutMs);
+        try {
+            c = createConnection({ path });
+        }
+        catch {
+            return done('unproven');
+        }
+        c.on('connect', () => done('live'));
+        c.on('error', (e) => done(PROVEN_DEAD.has(e.code ?? '') ? 'dead' : 'unproven'));
+    });
+}
+export const rendezvousListening = (id, timeoutMs = 800) => 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
+// project (~111 chars) → `path must be shorter than SUN_LEN` + connect EINVAL, and the app-server never bound
+// (Linux's 108 limit + shorter `/root` paths happened to fit; macOS did not). So the socket is
+// `<socketBase>/spexcode-cx-<hash>.sock`, where `<hash>` is a short STABLE digest of the PROJECT identity — the
+// `dir` (runtimeDir) the callers pass — so launch, liveness, and delivery all compute the IDENTICAL sock for a
+// given project (the ONE-app-server-per-project invariant). This is UNCONDITIONAL on every platform (a short
+// hashed path is strictly better everywhere — no darwin branch; platform differences stay at this path seam).
+// `<socketBase>` = the `SPEXCODE_CODEX_SOCKET_DIR` override, else an OWNED per-uid subdir of the platform
+// tmpdir (`spexcode-cx-<uid>`, created 0700) — NEVER bare tmpdir: codex (0.137+ field-confirmed) refuses to
+// bind a unix socket directly in the shared sticky `/tmp` on a host with `fs.protected_regular=2` (EPERM), so
+// the bare-tmpdir default failed every codex launch on a stock hardened Ubuntu out of the box (github#30),
+// while the SAME codex binds fine in any owned subdirectory. Per-uid (not one shared `spexcode-cx`) so a
+// second user on the box never lands in the first user's 0700 dir. The derivation GUARANTEES the dir exists
+// (idempotent mkdir) so every consumer — launch bake, liveness connect, delivery, tests — shares one creation
+// point. The `.pid`/`.log`/`.lock` files carry no sun_path limit and stay in `runtimeRoot`.
+export const codexAppServerSock = (dir = runtimeRoot()) => {
+    return codexGenerationSocketPath(dir);
+};
+export const codexAppServerPid = (dir = runtimeRoot()) => join(dir, 'codex-app-server.pid');
+export const codexAppServerReceipt = (dir = runtimeRoot()) => join(dir, 'codex-app-server.detached.json');
+const codexAppServerLegacyScope = (dir = runtimeRoot()) => join(dir, 'codex-app-server.scope');
+function codexRuntimeGenerationProof(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)) {
+    try {
+        const pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim());
+        const detached = verifyDetachedRuntime(pid, endpoint.receiptFile);
+        const socketPath = endpoint.socketPath;
+        const socket = statSync(socketPath);
+        if (!(pid > 0) || !detached.ok || !socket.isSocket())
+            return null;
+        return Object.freeze({
+            identity: detached.identity,
+            socket: Object.freeze({ path: socketPath, dev: socket.dev, ino: socket.ino }),
+        });
+    }
+    catch {
+        return null;
+    }
+}
+const codexRuntimeGenerationToken = (proof) => `${detachedRuntimeGenerationToken(proof.identity)}|${proof.socket.path}|${proof.socket.dev}:${proof.socket.ino}`;
+function codexRuntimeGeneration(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)) {
+    const proof = codexRuntimeGenerationProof(dir, endpoint);
+    return proof ? codexRuntimeGenerationToken(proof) : null;
+}
+function codexMutationGeneration(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)) {
+    const current = codexRuntimeGeneration(dir, endpoint);
+    if (current)
+        return current;
+    if (endpoint.id !== 'legacy')
+        return null;
+    let pid;
+    try {
+        pid = Number(readFileSync(codexAppServerPid(dir), 'utf8').trim());
+        if (!Number.isInteger(pid) || pid <= 0 || !statSync(codexAppServerSock(dir)).isSocket())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    if (!migrateLegacyDetachedRuntimeReceipt(pid, codexAppServerLegacyScope(dir), codexAppServerReceipt(dir)))
+        return null;
+    return codexRuntimeGeneration(dir, endpoint);
+}
+const codexDescriptorKey = (endpoint) => endpoint.id === 'legacy' ? 'codex-app-server' : `codex-app-server:${endpoint.id}`;
+function codexEndpointForRecord(rec, dir = runtimeRoot()) {
+    if (!rec.harnessSessionId)
+        return null;
+    const ledger = readCodexGenerationLedger(dir);
+    if (ledger.revision === 0 && !ledger.current && !Object.keys(ledger.generations).length)
+        return legacyCodexGenerationEndpoint(dir);
+    return resolveCodexGenerationForSession(dir, rec.session, rec.harnessSessionId);
+}
+// the spex launcher (bin/spex.mjs), baked into the codex launch script (mirrors materialize.ts's SPEX) so
+// the launch shell can call back into `spex codex-launch` to own the thread + fire the first turn before it
+// exec's the visible TUI. The launcher, never a raw source entry: it runs the compiled CLI and keeps the
+// source-workspace mid-merge guard (conflicted source -> one line + exit 75, not a stacktrace).
+const PKG = fileURLToPath(new URL('..', import.meta.url));
+const SPEX = join(PKG, 'bin', 'spex.mjs');
+// 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, runtimeDir) {
+    const roots = [];
+    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, runtimeDir) {
+    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'));
+            const workers = Object.values(roster.workers ?? {});
+            const usable = (worker) => 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, text, mid, auth) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let c;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            if (!r.ok)
+                try {
+                    c?.destroy();
+                }
+                catch { /* */ }
+            resolve(r);
+        };
+        try {
+            c = createConnection({ path: sock });
+        }
+        catch (e) {
+            done({ ok: false, error: `rendezvous socket connect threw: ${String(e)}` });
+            return;
+        }
+        c.on('error', (e) => {
+            const code = e?.code || String(e);
+            done({ ok: false, error: `rendezvous socket error: ${code}` });
+        });
+        c.on('close', () => done({ ok: false, error: 'rendezvous connection closed before the poke was written' }));
+        c.on('connect', () => c.write(`${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();
+            done({ ok: true });
+        }));
+    });
+}
+const POKE_ATTEMPTS = 2;
+async function pokeRendezvous(sock, text, mid, auth) {
+    let last = { ok: false, error: 'not attempted' };
+    for (let attempt = 0; attempt < POKE_ATTEMPTS; attempt++) {
+        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, text, mid) {
+    return pokeRendezvous(rvSock(id), text, mid);
+}
+export async function deliverViaClaudeRendezvous(id, text, mid, runtimeDir) {
+    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, text, mid, coldWake, unprovenError) {
+    const probe = await rendezvousListening(id);
+    if (probe === 'live')
+        return deliverViaRendezvous(id, text, mid);
+    if (probe === 'unproven')
+        return { ok: false, error: unprovenError };
+    return coldWake();
+}
+// The JSON-RPC the delivery handshake speaks, in send order. Method names + param shapes are pinned to codex
+// 0.142.3 (`codex app-server generate-ts` → ClientRequest.ts / v2/*Params.ts): the visible TUI is launched with
+// `codex --remote unix://<sock>`, so its thread is ALREADY loaded in this server — we must NOT `thread/resume`
+// it (that re-loads a thread the live TUI already owns). Instead `thread/loaded/list` PROVES the captured thread
+// is the one the pane is showing, then `thread/read{includeTurns}` reveals whether a turn is in progress (and
+// its id). The 4th, injecting message is CHOSEN from that read — see codexInjectMessage.
+const codexTextInput = (text) => [{ type: 'text', text, text_elements: [] }];
+export function codexHandshakeMessages(threadId) {
+    return [
+        {
+            id: 1,
+            method: 'initialize',
+            params: {
+                clientInfo: { name: 'spexcode', title: 'SpexCode', version: '0.0.0' },
+                capabilities: { experimentalApi: true, requestAttestation: false },
+            },
+        },
+        { method: 'initialized', params: {} },
+        { id: 2, method: 'thread/loaded/list', params: {} },
+        { id: 3, method: 'thread/read', params: { threadId, includeTurns: true } },
+    ];
+}
+// the message that injects `text`. STEER (turn/steer) when an active turn id is known — codex processes it
+// WITHOUT waiting for the current turn to end (the human's "工具调用完就插入": injected the moment the running
+// tool call returns), so a busy agent reacts mid-turn instead of queuing the message for after it stops.
+// `TurnSteerParams` REQUIRES the live turn id as `expectedTurnId` (the server rejects a stale one) — so this is
+// only sent with a turnId read live from the thread, never from SpexCode's session status. When the thread is
+// idle (no active turn id), START a fresh turn (turn/start). `id` is parameterized so a steer that loses the
+// expectedTurnId race (turn ended in the read→steer window) can retry as a turn/start with id 5.
+export function codexInjectMessage(threadId, text, cwd, activeTurnId, id = 4, clientUserMessageId) {
+    const marker = clientUserMessageId ? { clientUserMessageId } : {};
+    if (activeTurnId)
+        return { id, method: 'turn/steer', params: { threadId, input: codexTextInput(text), expectedTurnId: activeTurnId, ...marker } };
+    return { id, method: 'turn/start', params: { threadId, input: codexTextInput(text), ...(cwd ? { cwd } : {}), ...marker } };
+}
+// the in-progress turn id from a `thread/read{includeTurns}` result, or null when the thread is idle. With
+// includeTurns the Thread carries its turns, each with a TurnStatus ("completed"|"interrupted"|"failed"|
+// "inProgress"); the live turn is the `inProgress` one and its id is exactly what turn/steer's precondition needs.
+export function activeTurnIdFromThread(readResult) {
+    const thread = readResult?.thread;
+    const turns = Array.isArray(thread?.turns) ? thread.turns : [];
+    const active = turns.find((t) => t?.status === 'inProgress');
+    return active?.id ?? null;
+}
+// The app-server and the visible `--remote … resume` TUI share ONE socket, so they MUST be the SAME codex
+// install — a version split across that socket breaks the thread/start→resume handoff (an app-server on one
+// version creates a thread a differently-versioned resume can't find; an old-enough app-server can't serve
+// `--remote unix://` at all). So `serverCmd` is DERIVED from the in-effect `codexCmd`'s binary (its first shell
+// token, dropping args like `--yolo`) whenever it isn't explicitly forced: `<bin> app-server` then runs the
+// SAME install as `<bin> --remote … resume`. Bare `codex` is NOT the default anymore — on a multi-install host
+// (e.g. homebrew codex shadowing an nvm codex) a bare `codex` resolves via the login-shell PATH to a DIFFERENT
+// binary than the launcher's, which is exactly the version-skew bug. `SPEXCODE_CODEX_SERVER_CMD` stays the
+// explicit escape hatch (highest precedence). Caveat: if `codexCmd`'s first token is a WRAPPER script rather
+// than codex itself, the derived `<wrapper> app-server` only works if the wrapper forwards to codex — the
+// common direct-binary case (`codex …`, `/abs/codex --yolo`) is what this fixes.
+export function codexBinary(codexCmd) {
+    return codexCmd.trim().split(/\s+/)[0] || 'codex';
+}
+const regexEscape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const codexOptionValue = (command, flags, values) => {
+    const flagPattern = flags.map(regexEscape).join('|');
+    const valuePattern = values.map(regexEscape).join('|');
+    const matcher = new RegExp(`(?:^|\\s)(?:${flagPattern})(?:=|\\s+)[\"']?(${valuePattern})[\"']?(?=$|\\s)`, 'g');
+    let found;
+    for (const match of command.matchAll(matcher))
+        found = match[1];
+    return found;
+};
+// The backend creates the thread before the visible remote TUI, so translate launcher autonomy flags at this
+// adapter boundary. A flag on the later resume command cannot change an already-created thread.
+export function codexLauncherThreadPolicy(command) {
+    if (/(?:^|\s)(?:--yolo|--dangerously-bypass-approvals-and-sandbox)(?=$|\s)/.test(command)) {
+        return { approvalPolicy: 'never', sandbox: 'danger-full-access' };
+    }
+    const approvalPolicy = codexOptionValue(command, ['--ask-for-approval', '-a'], ['untrusted', 'on-request', 'never']);
+    const sandbox = codexOptionValue(command, ['--sandbox', '-s'], ['read-only', 'workspace-write', 'danger-full-access']);
+    return { ...(approvalPolicy ? { approvalPolicy } : {}), ...(sandbox ? { sandbox } : {}) };
+}
+// codex >=0.142 adds `--dangerously-bypass-hook-trust` — run our OWN (vetted) dispatch hooks without a persisted
+// trusted_hash. We PREFER it over reverse-engineering codexHookHash: that hash is pinned to one codex version's
+// format and silently breaks on a bump (codex then skips ALL our hooks -> no Stop gate, no mark-active, sessions
+// die undeclared). The flag is version-robust. But an OLDER codex HARD-ERRORS on the unknown flag (the whole
+// app-server fails to boot), so we CAPABILITY-PROBE the binary once (`--help` grep) and only pass it when
+// present; otherwise the writeCodexTrust hash path still stands in. Memoized — a per-binary constant.
+const bypassProbe = new Map();
+export function codexSupportsBypassHookTrust(binary) {
+    // explicit escape hatch (also what makes this deterministic in tests): force the capability on/off regardless
+    // of the binary — e.g. if the `--help` probe is unreliable on a wrapper, or to pin behaviour.
+    const env = process.env.SPEXCODE_CODEX_BYPASS_HOOK_TRUST;
+    if (env !== undefined)
+        return env === '1' || env === 'true';
+    const hit = bypassProbe.get(binary);
+    if (hit !== undefined)
+        return hit;
+    let ok = false;
+    try {
+        ok = execFileSync(binary, ['--help'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).includes('--dangerously-bypass-hook-trust');
+    }
+    catch {
+        ok = false;
+    }
+    bypassProbe.set(binary, ok);
+    return ok;
+}
+// Headless adapters all feed non-zero ephemeral turn exits through one state writer. Keep this reporter at the
+// adapter seam: controllers may call it directly, while shell-homed turns use headlessTurnFailureShell below.
+export async function reportHeadlessTurnExit(id, harness, code, cwd = process.cwd()) {
+    if (code === 0)
+        return;
+    const exitCode = code === null ? 'signal' : String(code);
+    try {
+        await pexec(SPEX, ['internal', 'session-turn-fail', id, harness, exitCode], { cwd, env: process.env });
+    }
+    catch (error) {
+        console.error(`[spex ${harness}] could not record turn failure for ${id}: ${error.message}`);
+    }
+}
+export function headlessTurnFailureShell(harness, swallow = true) {
+    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() {
+    return [...new Set(['SPEXCODE_SESSION_ID', ...HARNESS_IDENTITIES.map((h) => h.sessionEnvVar)])].filter(Boolean);
+}
+export function codexLaunchCommand(id, codexCmd = 'codex', serverCmd, dir = runtimeRoot(), attachTui = true) {
+    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
+    // thread — it was INERT there, the bug). Two thread paths carry it: (1) the BACKEND-owned `thread/start` sends
+    // `config.bypass_hook_trust` from codex-launch ([[harness-adapter]]); (2) the visible `--remote … resume` TUI,
+    // where codex's OWN client forwards this flag into its thread/start+thread/resume config — so a reopen in a
+    // fresh app-server (where codex-launch never runs) still trusts our hooks. Hence the flag lives on the resume
+    // TUI, never on the app-server invocation. Guarded against a double-flag when an env override already carries it.
+    const tuiBypass = !codexCmd.includes('--dangerously-bypass-hook-trust') && codexSupportsBypassHookTrust(codexBinary(codexCmd)) ? ' --dangerously-bypass-hook-trust' : '';
+    const script = [
+        `dir=${shQuote(dir)}`,
+        // codex-launch's bypass-trust gate (and writeTrust's) resolves the codex binary from SPEXCODE_CODEX_CMD;
+        // WE already hold the launcher's real cmd here (it drives the app-server + resume TUI + tuiBypass above), so
+        // pin it into the environment the codex-launch child inherits. Without this the child falls back to a bare
+        // `codex`, which on a multi-install box (e.g. an old Homebrew codex on PATH beside the launcher's newer one)
+        // probes the WRONG binary — deciding "no --dangerously-bypass-hook-trust support" and silently dropping the
+        // 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, 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" ${shQuote(server)} )" || exit 1`,
+        'else',
+        `  eval "$( ${SPEX} internal codex-generation-current "$dir" ${shQuote(server)} )" || exit 1`,
+        'fi',
+        // 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`
+        // does thread/start { cwd = this worktree } on the shared per-project app-server, stores the new id on the
+        // governed record (SPEXCODE_SESSION_ID), and fires the tail as the FIRST turn, materializing the rollout.
+        // Either way it ends with a thread id, which the visible TUI then RESUMES (the rollout persists on disk),
+        // rendering it natively. A new launch's tail is always ONE single-quoted prompt arg, so it can never be the
+        // literal "--resume" marker — the discriminator is unambiguous. codex-launch only prints an id once its
+        // rollout has landed (resume-ready), so a fail-loud (empty output / non-zero) must ABORT — never `resume ""`.
+        `if [ "$1" = "--resume" ]; then`,
+        `  tid=$2`,
+        ...(attachTui ? [] : [
+            // A headless forced reopen has no TUI to attach and the shared app-server already owns the thread. Keep it
+            // a no-op instead of calling codex-launch without a prompt (which would mint an unrelated empty thread).
+            `elif [ "$#" -eq 0 ]; then`,
+            `  exit 0`,
+        ]),
+        `else`,
+        `  tid=$(${SPEX} internal codex-launch "$sock" "$PWD" "$@")`,
+        `  __spex_rc=$?`,
+        ...(attachTui ? [`  [ "$__spex_rc" -eq 0 ] || exit 1`] : [
+            `  if [ "$__spex_rc" -ne 0 ]; then ${headlessTurnFailureShell('codex-headless')}; exit "$__spex_rc"; fi`,
+        ]),
+        `fi`,
+        `[ -n "$tid" ] || { echo "[spex] codex-launch produced no resumable thread" >&2; exit 1; }`,
+        // 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`;
+}
+function rpcError(e) {
+    return String(e?.message || e);
+}
+// --- minimal RFC6455 client framing ------------------------------------------------------------------------
+// The codex app-server `--listen unix://<sock>` transport is a WebSocket endpoint at path `/rpc` (the visible
+// `codex --remote` TUI upgrades the very same way). So we speak WebSocket over the Unix socket — NOT a raw byte
+// stream, and NOT `codex app-server proxy` (a dumb byte relay that performs no HTTP upgrade, so the server
+// rejects its bytes as an invalid upgrade and closes — the old 502). One JSON-RPC message = one masked text
+// frame; the server's frames come back unmasked. We only ever exchange small frames, so this is deliberately
+// small: text + the control frames (ping→pong, close) we must honor, plus continuation reassembly for safety.
+function encodeWsFrame(opcode, payload) {
+    const len = payload.length;
+    const mask = randomBytes(4);
+    let header;
+    if (len < 126)
+        header = Buffer.from([0x80 | opcode, 0x80 | len]);
+    else if (len < 65536)
+        header = Buffer.from([0x80 | opcode, 0x80 | 126, (len >> 8) & 0xff, len & 0xff]);
+    else {
+        header = Buffer.alloc(10);
+        header[0] = 0x80 | opcode;
+        header[1] = 0x80 | 127;
+        header.writeBigUInt64BE(BigInt(len), 2);
+    }
+    const masked = Buffer.alloc(len);
+    for (let i = 0; i < len; i++)
+        masked[i] = payload[i] ^ mask[i % 4];
+    return Buffer.concat([header, mask, masked]);
+}
+const wsText = (s) => encodeWsFrame(0x1, Buffer.from(s, 'utf8'));
+function drainWsFrames(s, conn, onText) {
+    for (;;) {
+        if (s.buf.length < 2)
+            return false;
+        const b0 = s.buf[0], b1 = s.buf[1], op = b0 & 0x0f, fin = (b0 & 0x80) !== 0, masked = (b1 & 0x80) !== 0;
+        let len = b1 & 0x7f, off = 2;
+        if (len === 126) {
+            if (s.buf.length < 4)
+                return false;
+            len = s.buf.readUInt16BE(2);
+            off = 4;
+        }
+        else if (len === 127) {
+            if (s.buf.length < 10)
+                return false;
+            len = Number(s.buf.readBigUInt64BE(2));
+            off = 10;
+        }
+        const dataStart = off + (masked ? 4 : 0);
+        if (s.buf.length < dataStart + len)
+            return false;
+        let payload = s.buf.slice(dataStart, dataStart + len);
+        if (masked) {
+            const mk = s.buf.slice(off, off + 4);
+            const u = Buffer.alloc(len);
+            for (let i = 0; i < len; i++)
+                u[i] = payload[i] ^ mk[i % 4];
+            payload = u;
+        }
+        s.buf = s.buf.slice(dataStart + len);
+        if (op === 0x8)
+            return true; // close
+        if (op === 0x9) {
+            conn.write(encodeWsFrame(0xa, payload));
+            continue;
+        } // ping → pong
+        if (op === 0xa)
+            continue; // pong
+        if (op === 0x0)
+            s.fragBuf = Buffer.concat([s.fragBuf, payload]); // continuation
+        else {
+            s.fragOp = op;
+            s.fragBuf = payload;
+        }
+        if (fin) {
+            if (s.fragOp === 0x1)
+                onText(s.fragBuf.toString('utf8'));
+            s.fragBuf = Buffer.alloc(0);
+            s.fragOp = 0;
+        }
+    }
+}
+const WS_UPGRADE = (key) => `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 = { id: 1, method: 'initialize', params: { clientInfo: { name: 'spexcode', title: 'SpexCode', version: '0.0.0' }, capabilities: { experimentalApi: true, requestAttestation: false } } };
+// Codex has no StopFailure hook, but its app-server has the stronger native signal: every subscribed turn ends
+// with turn/completed and a final completed/interrupted/failed status. Rejoin is atomic with subscription, so
+// this observer also survives backend replacement; a thread already in systemError is reconciled from its
+// latest turn before later live notifications take over.
+export function codexTurnFailureObserver(rec, onFailure) {
+    const threadId = rec.harnessSessionId;
+    if (!threadId)
+        return { close: () => { }, closed: Promise.resolve(null) };
+    const runtimeDir = rec.runtimeDir || runtimeRoot();
+    const endpoint = codexEndpointForRecord(rec, runtimeDir);
+    if (!endpoint) {
+        return {
+            close: () => { },
+            closed: Promise.resolve(`Codex turn observer refused: no exact generation binding for session ${rec.session}`),
+        };
+    }
+    const sock = endpoint.socketPath;
+    const conn = createConnection(sock);
+    const frames = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+    let upgraded = false, settled = false;
+    let reconciliationTimer = null;
+    let resolveClosed;
+    const closed = new Promise((resolve) => { resolveClosed = resolve; });
+    const cancelReconciliation = () => {
+        if (!reconciliationTimer)
+            return;
+        clearTimeout(reconciliationTimer);
+        reconciliationTimer = null;
+    };
+    const finish = (reason) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        cancelReconciliation();
+        try {
+            conn.destroy();
+        }
+        catch { }
+        resolveClosed(reason);
+    };
+    const timer = setTimeout(() => finish('Codex turn observer did not subscribe within 5000ms'), 5000);
+    timer.unref?.();
+    const send = (message) => conn.write(wsText(JSON.stringify(message)));
+    const report = (turn, fallbackMessage) => {
+        const value = turn;
+        if (value?.status !== 'failed' && !fallbackMessage)
+            return;
+        const nativeMessage = typeof value?.error?.message === 'string' ? value.error.message.trim() : '';
+        onFailure({
+            message: nativeMessage || fallbackMessage || 'Codex turn failed',
+            completedAt: typeof value?.completedAt === 'number' && Number.isFinite(value.completedAt) ? value.completedAt : null,
+        });
+    };
+    conn.on('error', (error) => finish(`Codex turn observer connection failed: ${rpcError(error)}`));
+    conn.on('close', () => finish('Codex turn observer connection closed'));
+    conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
+    const handle = (json) => {
+        let message;
+        try {
+            message = JSON.parse(json);
+        }
+        catch {
+            return;
+        }
+        if (message.error)
+            return finish(`Codex turn observer request failed: ${message.error.message || JSON.stringify(message.error)}`);
+        if (message.id === 1 && message.result) {
+            send({ method: 'initialized', params: {} });
+            return send({
+                id: 2,
+                method: 'thread/resume',
+                params: { threadId, excludeTurns: true, initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } },
+            });
+        }
+        if (message.id === 2 && message.result) {
+            clearTimeout(timer);
+            const result = message.result;
+            if (result.thread?.status?.type === 'systemError') {
+                const turns = result.initialTurnsPage?.data;
+                const latest = Array.isArray(turns) ? turns[0] : null;
+                // Give a concurrently-starting turn's native notification precedence over this historical snapshot.
+                reconciliationTimer = setTimeout(() => {
+                    reconciliationTimer = null;
+                    report(latest, 'Codex thread entered systemError before the turn observer subscribed');
+                }, 100);
+                reconciliationTimer.unref?.();
+            }
+            return;
+        }
+        if (message.method === 'turn/started') {
+            const params = message.params;
+            if (params?.threadId === threadId)
+                cancelReconciliation();
+        }
+        if (message.method === 'turn/completed') {
+            const params = message.params;
+            if (params?.threadId === threadId) {
+                cancelReconciliation();
+                report(params.turn);
+            }
+        }
+    };
+    conn.on('data', (chunk) => {
+        frames.buf = Buffer.concat([frames.buf, chunk]);
+        if (!upgraded) {
+            const split = frames.buf.indexOf('\r\n\r\n');
+            if (split < 0)
+                return;
+            const head = frames.buf.slice(0, split).toString('utf8');
+            if (!/^HTTP\/1\.1 101/.test(head))
+                return finish(`Codex app-server refused turn observer: ${head.split('\r\n')[0]}`);
+            upgraded = true;
+            frames.buf = frames.buf.slice(split + 4);
+            send(wsInitialize);
+        }
+        if (drainWsFrames(frames, conn, handle))
+            finish('Codex app-server closed the turn observer');
+    });
+    return { close: () => finish(null), closed };
+}
+function codexThreadMutation(sock, method, threadId, fence, turnId, budgetMs = CODEX_MUTATION_BASE_MS) {
+    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, 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 = createConnection(sock);
+        const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+        let upgraded = false, settled = false, requested = false;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { }
+            resolve(r);
+        };
+        // 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) => 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) => conn.write(wsText(JSON.stringify(m)));
+        conn.on('connect', () => {
+            const changed = generationError();
+            if (changed)
+                return unanswered(changed);
+            conn.write(WS_UPGRADE(randomBytes(16).toString('base64')));
+        });
+        const handle = (json) => {
+            let m;
+            try {
+                m = JSON.parse(json);
+            }
+            catch {
+                return;
+            }
+            // 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 unanswered(changed);
+                send({ method: 'initialized', params: {} });
+                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 ? unanswered(changed) : done({ ok: true });
+            }
+        };
+        conn.on('data', (chunk) => {
+            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}`, commit: 'refused' });
+                upgraded = true;
+                fs.buf = fs.buf.slice(i + 4);
+                send(wsInitialize);
+            }
+            if (drainWsFrames(fs, conn, handle))
+                unanswered(`Codex app-server closed during ${method}`);
+        });
+    });
+}
+// 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) => 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.
+export const CODEX_THREAD_SOURCE_KINDS = [
+    'cli', 'vscode', 'exec', 'appServer', 'subAgent', 'subAgentReview', 'subAgentCompact',
+    'subAgentThreadSpawn', 'subAgentOther', 'unknown',
+];
+function codexPagedIds(sock, method, params, extractId, label, onItem, timeoutMs = CODEX_MUTATION_CENSUS_MS) {
+    return new Promise((resolve) => {
+        const conn = createConnection(sock);
+        const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+        let upgraded = false, settled = false, requestId = 2, cursor = null;
+        const ids = new Set();
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { }
+            ;
+            resolve(result);
+        };
+        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) => 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) => {
+            let message;
+            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;
+            if (Array.isArray(page.data))
+                for (const item of page.data) {
+                    onItem?.(item);
+                    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) => {
+            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) {
+    const result = await codexPagedIds(sock, 'thread/loaded/list', {}, (item) => {
+        if (typeof item === 'string')
+            return item;
+        const value = item;
+        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;
+}
+const CODEX_RUNNING_TURN_READ_MS = 15_000;
+const CODEX_COLD_PREFLIGHT_MAX_ATTEMPTS = 6;
+const CODEX_COLD_PREFLIGHT_RETRY_MS = 250;
+const CODEX_COLD_PREFLIGHT_DEADLINE_MS = 30_000;
+async function waitForCodexGeneration(dir, endpoint) {
+    const deadline = Date.now() + CODEX_COLD_PREFLIGHT_DEADLINE_MS;
+    for (let attempt = 0; attempt < CODEX_COLD_PREFLIGHT_MAX_ATTEMPTS; attempt++) {
+        const generation = codexRuntimeGeneration(dir, endpoint);
+        if (generation)
+            return generation;
+        if (attempt === CODEX_COLD_PREFLIGHT_MAX_ATTEMPTS - 1 || Date.now() >= deadline)
+            break;
+        const delay = Math.min(CODEX_COLD_PREFLIGHT_RETRY_MS * 2 ** attempt, deadline - Date.now());
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+    return null;
+}
+function codexRunningTurn(sock, threadId) {
+    return new Promise((resolve) => {
+        const conn = createConnection(sock);
+        const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+        let upgraded = false, settled = false;
+        const done = (result) => {
+            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_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) => conn.write(wsText(JSON.stringify(message)));
+        conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
+        const handle = (json) => {
+            let message;
+            try {
+                message = JSON.parse(json);
+            }
+            catch {
+                return;
+            }
+            if (message.error) {
+                const error = message.error.message || JSON.stringify(message.error);
+                if (isCodexUnmaterializedThreadError(threadId, error))
+                    return done({ ok: true, turnPresence: 'idle', unmaterialized: true });
+                return done({ ok: false, error: `Codex target thread ${threadId} turn census failed: ${error}` });
+            }
+            if (message.id === 1 && message.result) {
+                send({ method: 'initialized', params: {} });
+                // The guard needs only the current turn. `thread/read {includeTurns:true}` materializes the
+                // entire persisted history, so an old but otherwise healthy thread can time out before close.
+                return send({ id: 2, method: 'thread/turns/list', params: { threadId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } });
+            }
+            if (message.id !== 2 || !message.result)
+                return;
+            const turns = message.result.data;
+            if (!Array.isArray(turns))
+                return done({ ok: true, turnPresence: 'unknown' });
+            const active = turns.find((turn) => !!turn && typeof turn === 'object' && turn.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) => {
+            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} turn 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 target thread ${threadId} turn census` });
+        });
+    });
+}
+const CODEX_INTERRUPT_SETTLE_MS = 15_000;
+// Codex can report an exact pre-materialization refusal, or that a previously loaded id is no longer loaded.
+// Both are positive no-turn facts for terminal close; every transport or ownership ambiguity remains fail-closed.
+const isCodexUnmaterializedThreadError = (threadId, error) => (error.includes(threadId) && error.includes('is not materialized yet') &&
+    error.includes('thread/turns/list is unavailable before first user message')) ||
+    error.includes(`thread not loaded: ${threadId}`);
+async function interruptCodexTurn(rec) {
+    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 = await waitForCodexGeneration(dir, endpoint);
+    if (!generation)
+        return { ok: false, error: 'Codex shared app-server generation remained unproven while waiting to interrupt' };
+    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, params) {
+    return codexThreadCollection(sock, params).then((result) => result.ok ? { ok: true, ids: result.ids } : result);
+}
+const codexRowStatus = (row) => {
+    const type = row.status?.type;
+    return type === 'notLoaded' || type === 'idle' || type === 'active' ? type : 'unknown';
+};
+function codexThreadCollection(sock, params) {
+    const sourceKinds = Array.isArray(params.sourceKinds) && params.sourceKinds.length
+        ? params.sourceKinds
+        : [...CODEX_THREAD_SOURCE_KINDS];
+    const parentById = new Map();
+    const statusById = new Map();
+    const conflictingParents = new Set();
+    return codexPagedIds(sock, 'thread/list', { ...params, sourceKinds, useStateDbOnly: true }, (item) => {
+        if (typeof item === 'string')
+            return item;
+        const id = item?.id;
+        return typeof id === 'string' ? id : null;
+    }, 'thread/list', (item) => {
+        if (!item || typeof item !== 'object')
+            return;
+        const row = item;
+        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, error: `Codex thread/list returned conflicting parent ownership for ${[...conflictingParents].join(', ')}` };
+        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) => status === 'idle' || status === 'active' ? status : 'unknown';
+async function codexTargetMutationGuard(threadId, dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir)) {
+    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;
+    // 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
+        ? [...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 };
+    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 = 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 };
+}
+const CODEX_COLD_PLAN = Symbol('codex-cold-plan');
+const sameIdSet = (left, right) => left.length === right.length && left.every((id) => right.includes(id));
+const sameParentEdges = (left, right) => left.length === right.length && left.every(([id, parent]) => right.some(([otherId, otherParent]) => id === otherId && parent === otherParent));
+const isCodexColdPlan = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const plan = value;
+    return plan[CODEX_COLD_PLAN] === true && plan.kind === 'codex-cold-subtree-v1' && typeof plan.threadId === 'string' &&
+        typeof plan.generation === 'string' && isEndpointLike(plan.endpoint) && Array.isArray(plan.descendantIds) &&
+        Array.isArray(plan.parentEdges) && Array.isArray(plan.subtreeIds) &&
+        Array.isArray(plan.activeIds) && Array.isArray(plan.archivedIds) && !!plan.guard;
+};
+function isEndpointLike(value) {
+    return !!value && typeof value === 'object' && typeof value.id === 'string' &&
+        typeof value.pidFile === 'string' && typeof value.receiptFile === 'string' &&
+        typeof value.socketPath === 'string';
+}
+function makeCodexColdPlan(input) {
+    return Object.freeze({
+        [CODEX_COLD_PLAN]: true,
+        kind: 'codex-cold-subtree-v1',
+        ...(input.unmaterialized ? { unmaterialized: true } : {}),
+        threadId: input.threadId,
+        generation: input.generation,
+        endpoint: input.endpoint,
+        guard: input.guard,
+        descendantIds: Object.freeze([...input.descendantIds]),
+        parentEdges: Object.freeze([...input.parentEdges]),
+        subtreeIds: Object.freeze([...input.subtreeIds]),
+        activeIds: Object.freeze([...input.activeIds]),
+        archivedIds: Object.freeze([...input.archivedIds]),
+    });
+}
+async function codexColdPreflightOnce(threadId, dir = runtimeRoot(), expectedGeneration, endpoint = legacyCodexGenerationEndpoint(dir)) {
+    const generation = expectedGeneration ?? codexMutationGeneration(dir, endpoint);
+    if (!generation)
+        return { ok: false, reason: 'Codex shared app-server generation is temporarily unproven before subtree census' };
+    if (codexRuntimeGeneration(dir, endpoint) !== generation)
+        return { ok: false, reason: 'Codex shared app-server generation changed before subtree census' };
+    const sock = endpoint.socketPath;
+    const [loaded, activeDescendants, archivedDescendants, archivedList, activeList] = await Promise.all([
+        codexLoadedReferenceIds(sock),
+        codexThreadCollection(sock, { ancestorThreadId: threadId, archived: false, sourceKinds: [] }),
+        codexThreadCollection(sock, { ancestorThreadId: threadId, archived: true, sourceKinds: [] }),
+        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' };
+    if (!loaded.ok)
+        return { ok: false, reason: loaded.error };
+    if (!activeDescendants.ok)
+        return { ok: false, reason: activeDescendants.error };
+    if (!archivedDescendants.ok)
+        return { ok: false, reason: archivedDescendants.error };
+    if (!archivedList.ok)
+        return { ok: false, reason: archivedList.error };
+    if (!activeList.ok)
+        return { ok: false, reason: activeList.error };
+    const activeDescendantSet = new Set(activeDescendants.ids);
+    const archivedDescendantSet = new Set(archivedDescendants.ids);
+    const duplicateDescendants = activeDescendants.ids.filter((id) => archivedDescendantSet.has(id));
+    if (duplicateDescendants.length)
+        return { ok: false, reason: `Codex subtree members occur in both active and archived descendant collections (${duplicateDescendants.join(', ')})` };
+    const descendantIds = [...activeDescendants.ids, ...archivedDescendants.ids];
+    if (descendantIds.includes(threadId))
+        return { ok: false, reason: `Codex target ${threadId} is duplicated in its own descendant closure` };
+    const activeSet = new Set(activeList.ids);
+    const archivedSet = new Set(archivedList.ids);
+    if (!activeSet.has(threadId) && !archivedSet.has(threadId) && descendantIds.length === 0) {
+        // A Codex thread id can be registered before the server materializes its first user message. The exact
+        // protocol refusal is the only proof that this absent native target is that startup window, rather than
+        // an unowned/reassigned record that must stay fail-closed.
+        const turn = await codexRunningTurn(sock, threadId);
+        if (!turn.ok)
+            return { ok: false, reason: turn.error };
+        if (codexRuntimeGeneration(dir, endpoint) !== generation)
+            return { ok: false, reason: 'shared Codex app-server generation changed while confirming an unmaterialized thread' };
+        if (turn.unmaterialized) {
+            const loadedTarget = loaded.referenceIds.includes(threadId);
+            const guard = {
+                healthy: true,
+                referenceIds: [...loaded.referenceIds],
+                targetTurnPresence: 'none',
+                descendantIds: [],
+            };
+            return {
+                ok: true,
+                ...(loadedTarget ? {} : { alreadyCold: true }),
+                receipt: makeCodexColdPlan({
+                    threadId,
+                    generation,
+                    endpoint,
+                    guard,
+                    descendantIds: [],
+                    parentEdges: [],
+                    subtreeIds: [threadId],
+                    activeIds: loadedTarget ? [threadId] : [],
+                    archivedIds: [],
+                    unmaterialized: true,
+                }),
+            };
+        }
+    }
+    const parentById = new Map([...activeDescendants.parentById, ...archivedDescendants.parentById]);
+    const depthById = new Map();
+    for (const id of descendantIds) {
+        const seen = new Set([id]);
+        let cursor = id;
+        let depth = 0;
+        while (cursor !== threadId) {
+            const next = parentById.get(cursor);
+            if (!next)
+                return { ok: false, reason: `Codex descendant ${id} has no complete parent chain to target ${threadId} (unowned or reassigned)` };
+            if (seen.has(next))
+                return { ok: false, reason: `Codex descendant ${id} has a cyclic parent chain` };
+            seen.add(next);
+            cursor = next;
+            depth++;
+        }
+        depthById.set(id, depth);
+    }
+    const subtreeIds = [...descendantIds, threadId];
+    for (const id of subtreeIds) {
+        const inActive = activeSet.has(id);
+        const inArchived = archivedSet.has(id);
+        if (!inActive && !inArchived)
+            return { ok: false, reason: `Codex subtree member ${id} is absent from both native collections (unowned or reassigned)` };
+        if (inActive && inArchived)
+            return { ok: false, reason: `Codex subtree member ${id} occurs in both active and archived native collections` };
+        if (id !== threadId) {
+            const expectedActive = activeDescendantSet.has(id);
+            if (inActive !== expectedActive)
+                return { ok: false, reason: `Codex subtree member ${id} changed collection assignment during ownership census` };
+        }
+    }
+    // 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));
+    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 = loadedSet.has(threadId) ? 'idle' : 'none';
+    const guard = {
+        healthy: true,
+        referenceIds: [...loaded.referenceIds],
+        targetTurnPresence,
+        descendantIds: [...descendantIds],
+    };
+    const activeIds = [...activeDescendants.ids]
+        .sort((left, right) => (depthById.get(right) ?? 0) - (depthById.get(left) ?? 0))
+        .concat(activeSet.has(threadId) ? [threadId] : []);
+    const archivedIds = [...archivedDescendants.ids, ...(archivedSet.has(threadId) ? [threadId] : [])];
+    const parentEdges = descendantIds.map((id) => [id, parentById.get(id)]);
+    const receipt = makeCodexColdPlan({ threadId, generation, endpoint, guard, descendantIds, parentEdges, subtreeIds, activeIds, archivedIds });
+    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 isTransientCodexCensusFailure = (reason) => /(?:temporarily unproven|timed out|connection|closed during|refused .*census|census failed|app-server busy)/i.test(reason);
+async function codexColdPreflight(threadId, dir = runtimeRoot(), expectedGeneration, endpoint = legacyCodexGenerationEndpoint(dir)) {
+    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, opts) {
+    const dir = runtimeRoot();
+    const generation = codexMutationGeneration(dir);
+    if (!generation)
+        return { ok: false, reason: 'Codex shared app-server generation is unproven' };
+    const owners = governedSharedRuntimeOwners(dir, 'codex-app-server', threadId, opts.excludingSessionId);
+    if (owners === null)
+        return { ok: false, reason: 'governed Codex thread-owner census is unreadable' };
+    if (owners.length)
+        return { ok: false, reason: `Codex native thread ${threadId} has governed owner(s) ${owners.join(', ')}` };
+    const before = await codexColdPreflight(threadId, dir, generation);
+    if (!before.ok)
+        return before;
+    const plan = before.receipt;
+    if (plan.descendantIds.length || plan.guard.descendantIds.length)
+        return { ok: false, reason: `Codex native thread ${threadId} has descendants (${[...new Set([...plan.descendantIds, ...plan.guard.descendantIds])].join(', ')})` };
+    if (plan.guard.targetTurnPresence === 'active' || plan.guard.targetTurnPresence === 'unknown')
+        return { ok: false, reason: `Codex native thread ${threadId} is ${plan.guard.targetTurnPresence === 'active' ? 'active' : 'unknown'}` };
+    if (plan.subtreeIds.length !== 1 || plan.subtreeIds[0] !== threadId)
+        return { ok: false, reason: `Codex native thread ${threadId} has an ambiguous ownership closure` };
+    const unchangedOwners = () => governedSharedRuntimeOwners(dir, 'codex-app-server', threadId, opts.excludingSessionId);
+    const rollback = () => codexRestoreColdPlan(plan, dir);
+    if (plan.activeIds.length === 0) {
+        if (plan.archivedIds.length !== 1 || plan.archivedIds[0] !== threadId || plan.guard.referenceIds.includes(threadId))
+            return { ok: false, reason: `Codex native thread ${threadId} is not uniquely archived and unloaded` };
+        const afterOwners = unchangedOwners();
+        if (afterOwners === null || afterOwners.length)
+            return { ok: false, reason: 'governed Codex thread-owner census changed during quarantine verification' };
+        return { ok: true, audit: { adapter: 'codex', threadId, action: 'already-unloaded' }, compensate: async () => ({ ok: true }) };
+    }
+    if (plan.activeIds.length !== 1 || plan.activeIds[0] !== threadId || plan.archivedIds.length)
+        return { ok: false, reason: `Codex native thread ${threadId} is not one exact active orphan` };
+    const siblingIds = plan.guard.referenceIds.filter((id) => id !== threadId);
+    const legacy = legacyCodexGenerationEndpoint(dir);
+    // 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) => ({ ok: false, reason });
+    if (!after.ok) {
+        const restored = await rollback();
+        return failed(restored.ok ? after.reason : `${after.reason}; ${restored.reason}`);
+    }
+    const afterOwners = unchangedOwners();
+    const afterPlan = after.receipt;
+    const valid = afterPlan.descendantIds.length === 0 && afterPlan.subtreeIds.length === 1 && afterPlan.subtreeIds[0] === threadId &&
+        afterPlan.activeIds.length === 0 && afterPlan.archivedIds.length === 1 && afterPlan.archivedIds[0] === threadId &&
+        !afterPlan.guard.referenceIds.includes(threadId) && siblingIds.every((id) => afterPlan.guard.referenceIds.includes(id)) &&
+        afterOwners !== null && afterOwners.length === 0;
+    if (!valid) {
+        const restored = await rollback();
+        return failed(restored.ok ? `Codex orphan thread ${threadId} changed during archive verification` : `Codex orphan thread ${threadId} changed during archive verification; ${restored.reason}`);
+    }
+    return { ok: true, audit: { adapter: 'codex', threadId, action: 'archived' }, compensate: rollback };
+}
+async function codexMutationGuard(threadId, dir = runtimeRoot(), opts = {}, endpoint = legacyCodexGenerationEndpoint(dir)) {
+    if (opts.coldReceipt === undefined)
+        return codexTargetMutationGuard(threadId, dir, endpoint);
+    if (!isCodexColdPlan(opts.coldReceipt) || opts.coldReceipt.threadId !== threadId)
+        return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'adapter cold teardown receipt is invalid' };
+    if (opts.coldReceipt.endpoint.id !== endpoint.id)
+        return { healthy: false, referenceIds: [], targetTurnPresence: 'unknown', descendantIds: [], error: 'adapter cold teardown receipt names a different generation' };
+    const current = await codexColdPreflight(threadId, dir, opts.coldReceipt.generation, endpoint);
+    if (!current.ok) {
+        const guard = await codexTargetMutationGuard(threadId, dir, endpoint);
+        return { ...guard, healthy: false, coldTeardownAuthorized: false, error: current.reason };
+    }
+    const authorized = sameIdSet(opts.coldReceipt.descendantIds, current.receipt.descendantIds) &&
+        sameParentEdges(opts.coldReceipt.parentEdges, current.receipt.parentEdges) &&
+        sameIdSet(opts.coldReceipt.activeIds, current.receipt.activeIds) &&
+        sameIdSet(opts.coldReceipt.archivedIds, current.receipt.archivedIds);
+    return {
+        ...current.receipt.guard,
+        healthy: authorized,
+        coldTeardownAuthorized: authorized,
+        ...(authorized ? {} : { error: 'adapter cold teardown receipt no longer matches the target subtree' }),
+    };
+}
+async function codexRestoreColdPlan(plan, dir = runtimeRoot()) {
+    if (codexRuntimeGeneration(dir, plan.endpoint) !== plan.generation)
+        return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' };
+    const sock = plan.endpoint.socketPath;
+    const [activeBefore, archivedBefore] = await Promise.all([
+        codexThreadList(sock, { archived: false, sourceKinds: [] }),
+        codexThreadList(sock, { archived: true, sourceKinds: [] }),
+    ]);
+    if (!activeBefore.ok || !archivedBefore.ok)
+        return { ok: false, reason: 'archive state is unknown and could not be reconciled' };
+    if (codexRuntimeGeneration(dir, plan.endpoint) !== plan.generation)
+        return { ok: false, reason: 'shared Codex app-server generation changed, so no compensation was attempted' };
+    const activeSet = new Set(activeBefore.ids);
+    const archivedSet = new Set(archivedBefore.ids);
+    if (plan.archivedIds.some((id) => !archivedSet.has(id) || activeSet.has(id)))
+        return { ok: false, reason: 'an originally-archived Codex subtree member changed collection; compensation was not authorized' };
+    if (plan.activeIds.some((id) => activeSet.has(id) === archivedSet.has(id)))
+        return { ok: false, reason: 'an originally-active Codex subtree member has ambiguous collection state' };
+    const fence = { dir, endpoint: plan.endpoint, generation: plan.generation };
+    const restoreIds = [...plan.activeIds].reverse().filter((id) => archivedSet.has(id));
+    for (const id of restoreIds) {
+        const restored = await codexThreadMutation(sock, 'thread/unarchive', id, fence);
+        if (!restored.ok)
+            return { ok: false, reason: `compensation failed for ${id}: ${restored.error}` };
+    }
+    const [activeAfter, archivedAfter] = await Promise.all([
+        codexThreadList(sock, { archived: false, sourceKinds: [] }),
+        codexThreadList(sock, { archived: true, sourceKinds: [] }),
+    ]);
+    const restored = activeAfter.ok && archivedAfter.ok && codexRuntimeGeneration(dir, plan.endpoint) === plan.generation &&
+        plan.activeIds.every((id) => activeAfter.ids.includes(id) && !archivedAfter.ids.includes(id)) &&
+        plan.archivedIds.every((id) => archivedAfter.ids.includes(id) && !activeAfter.ids.includes(id));
+    return restored ? { ok: true } : { ok: false, reason: 'compensation failed or archive state is unknown' };
+}
+// Read a loaded thread id off the app-server via `thread/loaded/list`. With the backend now OWNING the thread
+// 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
+// threads may be loaded, so it is no longer the deterministic capture path — the stored id is. Never throws.
+export function codexThreadId(sock) {
+    return new Promise((resolve) => {
+        const conn = createConnection(sock);
+        const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+        let upgraded = false, settled = false;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { /* */ }
+            resolve(r);
+        };
+        const timer = setTimeout(() => done({ ok: false, error: 'codex app-server did not list threads within 5000ms' }), 5000);
+        conn.on('error', (e) => done({ ok: false, error: `codex app-server connection failed: ${rpcError(e)}` }));
+        conn.on('close', () => done({ ok: false, error: 'codex app-server closed before thread/loaded/list was answered' }));
+        const send = (m) => conn.write(wsText(JSON.stringify(m)));
+        conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
+        const handle = (json) => {
+            let m;
+            try {
+                m = JSON.parse(json);
+            }
+            catch {
+                return;
+            }
+            if (m.error)
+                return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` });
+            if (m.id === 1 && m.result) {
+                send({ method: 'initialized', params: {} });
+                return send({ id: 2, method: 'thread/loaded/list', params: {} });
+            }
+            if (m.id === 2 && m.result) {
+                const data = m.result.data;
+                const ids = Array.isArray(data) ? data.filter((x) => typeof x === 'string') : [];
+                return ids.length ? done({ ok: true, threadId: ids[0] }) : done({ ok: false, error: 'no loaded thread on the app-server socket yet (TUI still booting?)' });
+            }
+        };
+        conn.on('data', (chunk) => {
+            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 the WebSocket upgrade: ${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 sent a WebSocket close before thread/loaded/list was confirmed' });
+        });
+    });
+}
+// 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(), endpoint = legacyCodexGenerationEndpoint(dir)) {
+    const sock = endpoint.socketPath;
+    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(endpoint.pidFile, '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)' };
+        const generation = codexRuntimeGeneration(dir, endpoint);
+        if (!generation)
+            return { healthy: false, references: [], error: 'Codex shared root detached receipt/socket generation is not proven' };
+        return new Promise((resolve) => {
+            const conn = createConnection(sock);
+            const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+            const references = new Map();
+            const requests = new Map();
+            const loadedRequests = new Set();
+            const loadedIds = new Set();
+            let loadedRequestId = 2;
+            let loadedCursor = null;
+            let upgraded = false;
+            let settled = false;
+            let timer;
+            const done = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                try {
+                    conn.destroy();
+                }
+                catch { /* */ }
+                resolve(result.healthy && codexRuntimeGeneration(dir, endpoint) !== generation
+                    ? { healthy: false, references: result.references, error: 'Codex shared root detached receipt/socket generation changed during ownership probe' }
+                    : result);
+            };
+            const fail = (error) => 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) => conn.write(wsText(JSON.stringify(m)));
+            conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
+            const handle = (json) => {
+                let m;
+                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.data;
+                    const ids = [...new Set(Array.isArray(data) ? data.flatMap((item) => {
+                            if (typeof item === 'string')
+                                return [item];
+                            const id = item?.id ?? item?.threadId;
+                            return typeof id === 'string' ? [id] : [];
+                        }) : [])];
+                    for (const threadId of ids)
+                        loadedIds.add(threadId);
+                    const next = m.result.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.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) => {
+                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.
+// @@@ codexStartThreadParams - what a BACKEND-owned thread is created with. `config` is the per-request
+// override map carrying `bypass_hook_trust` so our hooks run and `shell_environment_policy.set` so every
+// command this thread spawns carries the governed record id. Typed approval/sandbox fields carry the pinned
+// launcher's autonomy policy; putting those flags only on the later remote TUI cannot change this thread.
+export function codexStartThreadParams(cwd, bypassHookTrust = false, shellEnv, policy = {}) {
+    const config = {
+        ...(bypassHookTrust ? { bypass_hook_trust: true } : {}),
+        ...(shellEnv && Object.keys(shellEnv).length ? { shell_environment_policy: { set: shellEnv } } : {}),
+    };
+    return { ...(cwd ? { cwd } : {}), ...policy, ...(Object.keys(config).length ? { config } : {}) };
+}
+export function codexStartThread(sock, cwd, bypassHookTrust = false, shellEnv, policy = {}) {
+    return new Promise((resolve) => {
+        const conn = createConnection(sock);
+        const fs = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
+        let upgraded = false, settled = false;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { /* */ }
+            resolve(r);
+        };
+        const timer = setTimeout(() => done({ ok: false, error: 'codex app-server did not start a thread within 15000ms' }), 15000);
+        conn.on('error', (e) => done({ ok: false, error: `codex app-server connection failed: ${rpcError(e)}` }));
+        conn.on('close', () => done({ ok: false, error: 'codex app-server closed before thread/start was answered' }));
+        const send = (m) => conn.write(wsText(JSON.stringify(m)));
+        conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
+        const handle = (json) => {
+            let m;
+            try {
+                m = JSON.parse(json);
+            }
+            catch {
+                return;
+            }
+            if (m.error)
+                return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` });
+            if (m.id === 1 && m.result) {
+                send({ method: 'initialized', params: {} });
+                // thread/start's `config` is the per-request override map the app-server reads (config_manager reads
+                // `request_overrides["bypass_hook_trust"]`) — the ONLY channel that reaches the thread config; the
+                // `--dangerously-bypass-hook-trust` flag on the `codex app-server` invocation is INERT (the app-server
+                // never reads it for a thread), so a BACKEND-owned thread must carry the bypass here, exactly as codex's
+                // 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).
+                // 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, policy) });
+            }
+            if (m.id === 2 && m.result) {
+                const tid = m.result?.thread?.id;
+                return tid ? done({ ok: true, threadId: tid }) : done({ ok: false, error: 'codex thread/start returned no thread id' });
+            }
+        };
+        conn.on('data', (chunk) => {
+            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 the WebSocket upgrade: ${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 sent a WebSocket close before thread/start was confirmed' });
+        });
+    });
+}
+const codexTurnConfirmMs = () => {
+    const configured = Number(process.env.SPEXCODE_CODEX_TURN_CONFIRM_MS);
+    return Number.isFinite(configured) && configured >= 100 ? configured : 15_000;
+};
+function sendCodexAppServerTurn(sock, threadId, text, cwd, clientUserMessageId) {
+    return new Promise((resolve) => {
+        const conn = createConnection(sock);
+        const hs = codexHandshakeMessages(threadId); // [initialize(1), initialized, thread/loaded/list(2), thread/read(3)]
+        let buf = Buffer.alloc(0), upgraded = false, settled = false;
+        let fragOp = 0, fragBuf = Buffer.alloc(0);
+        let steering = false; // the id-4 message we sent was a steer → an expectedTurnId race may retry as start(5)
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { /* */ }
+            resolve(r);
+        };
+        const unresolved = (error) => done({ ok: false, error });
+        const timer = setTimeout(() => unresolved(`codex app-server did not confirm the turn within ${codexTurnConfirmMs()}ms`), codexTurnConfirmMs());
+        conn.on('error', (e) => unresolved(`codex app-server connection failed: ${rpcError(e)}`));
+        conn.on('close', () => unresolved('codex app-server closed the connection before the turn was confirmed'));
+        const send = (m) => conn.write(wsText(JSON.stringify(m)));
+        conn.on('connect', () => {
+            const key = randomBytes(16).toString('base64');
+            conn.write(`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 handle = (json) => {
+            let m;
+            try {
+                m = JSON.parse(json);
+            }
+            catch {
+                return;
+            }
+            if (m.error) {
+                if (m.id === 4 && steering) // active turn ended in the read→steer window → just start a fresh turn
+                    return send(codexInjectMessage(threadId, text, cwd, null, 5, clientUserMessageId));
+                if (m.id === 3) // thread not readable yet (a freshly-started thread is "not materialized
+                    return send(codexInjectMessage(threadId, text, cwd, null, 5, clientUserMessageId)); // before its first user message") → just turn/start
+                return done({ ok: false, error: `codex app-server ${m.id ? `request ${m.id}` : 'notification'} failed: ${m.error.message || JSON.stringify(m.error)}` });
+            }
+            // JSON-RPC initialization is ordered. Under a quiet server the premature notification happened to win;
+            // under shared app-server load it was ignored and every later turn waited until the old 5s wall expired.
+            if (m.id === 1 && m.result) {
+                send(hs[1]);
+                return send(hs[2]);
+            } // initialize ack → initialized → ask which threads are loaded
+            if (m.id === 2 && m.result) { // loaded-thread list → confirm OUR thread is live, then read it
+                const loaded = m.result?.data;
+                if (Array.isArray(loaded) && !loaded.includes(threadId))
+                    return done({ ok: false, error: `Codex thread ${threadId} is not loaded in the app-server (loaded: ${loaded.join(', ') || 'none'}) — immediate poke not accepted` });
+                return send(hs[3]); // thread is live → read it to decide steer-vs-start
+            }
+            if (m.id === 3 && m.result) { // thread read → in-progress turn? steer into it; else start a new one
+                const turnId = activeTurnIdFromThread(m.result);
+                steering = !!turnId;
+                return send(codexInjectMessage(threadId, text, cwd, turnId, 4, clientUserMessageId)); // id 4: turn/steer the live turn, or turn/start
+            }
+            if ((m.id === 4 || m.id === 5) && m.result)
+                return done({ ok: true }); // steer/start accepted → the model has the message
+        };
+        const drainFrames = () => {
+            for (;;) {
+                if (buf.length < 2)
+                    return;
+                const b0 = buf[0], b1 = buf[1], op = b0 & 0x0f, fin = (b0 & 0x80) !== 0, masked = (b1 & 0x80) !== 0;
+                let len = b1 & 0x7f, off = 2;
+                if (len === 126) {
+                    if (buf.length < 4)
+                        return;
+                    len = buf.readUInt16BE(2);
+                    off = 4;
+                }
+                else if (len === 127) {
+                    if (buf.length < 10)
+                        return;
+                    len = Number(buf.readBigUInt64BE(2));
+                    off = 10;
+                }
+                const dataStart = off + (masked ? 4 : 0);
+                if (buf.length < dataStart + len)
+                    return;
+                let payload = buf.slice(dataStart, dataStart + len);
+                if (masked) {
+                    const mk = buf.slice(off, off + 4);
+                    const u = Buffer.alloc(len);
+                    for (let i = 0; i < len; i++)
+                        u[i] = payload[i] ^ mk[i % 4];
+                    payload = u;
+                }
+                buf = buf.slice(dataStart + len);
+                if (op === 0x8)
+                    return unresolved('codex app-server sent a WebSocket close before turn/start was confirmed');
+                if (op === 0x9) {
+                    conn.write(encodeWsFrame(0xa, payload));
+                    continue;
+                } // ping → pong
+                if (op === 0xa)
+                    continue; // pong
+                if (op === 0x0)
+                    fragBuf = Buffer.concat([fragBuf, payload]); // continuation
+                else {
+                    fragOp = op;
+                    fragBuf = payload;
+                }
+                if (fin) {
+                    if (fragOp === 0x1)
+                        handle(fragBuf.toString('utf8'));
+                    fragBuf = Buffer.alloc(0);
+                    fragOp = 0;
+                }
+            }
+        };
+        conn.on('data', (chunk) => {
+            buf = Buffer.concat([buf, chunk]);
+            if (!upgraded) {
+                const i = buf.indexOf('\r\n\r\n');
+                if (i < 0)
+                    return;
+                const head = buf.slice(0, i).toString('utf8');
+                if (!/^HTTP\/1\.1 101/.test(head))
+                    return done({ ok: false, error: `codex app-server refused the WebSocket upgrade: ${head.split('\r\n')[0]}` });
+                upgraded = true;
+                buf = buf.slice(i + 4);
+                send(hs[0]); // wait for initialize before its required initialized notification
+            }
+            drainFrames();
+        });
+    });
+}
+// fire a turn on an owned thread over the per-project socket — the same steer-vs-start delivery the live UI
+// uses. The launcher calls this to materialize a freshly-started thread's rollout (the first turn = the launch
+// prompt), and delivery reuses it for follow-ups. Exported so the CLI's `codex-launch` can fire the first turn.
+export function codexTurn(sock, threadId, text, cwd, clientUserMessageId) {
+    return sendCodexAppServerTurn(sock, threadId, text, cwd, clientUserMessageId);
+}
+// @@@ codex rollout on disk - the visible TUI resumes a thread via `codex --remote resume <tid>`, which reads
+// the thread's ROLLOUT FILE (`<CODEX_HOME>/sessions/YYYY/MM/DD/rollout-<ts>-<tid>.jsonl`) — so a thread the
+// TUI can render is exactly one whose rollout exists on disk. VERIFIED live (real codex 0.142.5): `thread/start`
+// ALONE writes NO rollout — only the first fired turn materializes it; and a FRESHLY-spawned app-server accepts
+// 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.
+// 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, root) {
+    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, root) {
+    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
+// exceed launch.sh's fast-fail threshold so a genuine failure exits PAST it — the retry loop then treats it as a
+// real end, not a daemon race, and never sprays fresh (duplicate-prompt) threads.
+export async function waitForCodexRollout(threadId, timeoutMs = 20000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (codexRolloutExists(threadId))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+// codex's immediate poke uses the app-server JSON-RPC channel that also powers rich clients, never TUI typing.
+// The visible TUI is launched against the same project app-server Unix socket, so this injects into the same
+// thread the pane is showing — steering an in-progress turn or starting one if idle. A missing captured thread
+// id or socket makes this poke fail; there is no tmux send-keys fallback because that reports "typed", not "accepted".
+const pexec = promisify(execFile);
+const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode';
+async function deliverViaCodexAppServer(rec, text) {
+    // the socket is PER-PROJECT (the runtime root), shared by every worktree's thread; the owned thread id on
+    // the record picks out THIS session's thread.
+    const runtimeDir = rec.runtimeDir ?? runtimeRoot();
+    const endpoint = rec.harnessSessionId ? codexEndpointForRecord(rec, runtimeDir) : currentCodexGeneration(runtimeDir);
+    if (!endpoint)
+        return { ok: false, error: `no exact Codex generation binding for session ${rec.session} — immediate poke unavailable` };
+    const sock = endpoint.socketPath;
+    if (!existsSync(sock))
+        return { ok: false, error: `no Codex app-server socket for this project — immediate poke unavailable` };
+    // use the backend-owned thread id stored at launch; fall back to reading the one loaded thread only if it's
+    // empty (a pre-existing session from before the id was stored).
+    let threadId = rec.harnessSessionId;
+    if (!threadId) {
+        const r = await codexThreadId(sock);
+        if (!r.ok)
+            return { ok: false, error: `${r.error} — immediate poke unavailable` };
+        threadId = r.threadId;
+    }
+    return sendCodexAppServerTurn(sock, threadId, text, rec.worktreePath, rec.mid);
+}
+// 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, body, comment = ['<!-- ', ' -->']) {
+    const [open, close] = comment;
+    const START = `${open}spexcode:start${close}`;
+    const END = `${open}spexcode:end${close}`;
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const block = `${START}\n${body}\n${END}`;
+    const cur = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const re = new RegExp(`${esc(START)}[\\s\\S]*?${esc(END)}`);
+    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),
+// leaving every other byte of the user's file intact. When deleteIfEmpty and nothing but whitespace remains,
+// remove the file — it was WHOLLY ours (e.g. a CLAUDE.md that carried only the generated contract block). Same
+// comment-style parameter so ONE primitive un-writes every managed file. No-op when the file/block is absent.
+export function removeManagedBlock(file, comment = ['<!-- ', ' -->'], deleteIfEmpty = false) {
+    if (!existsSync(file))
+        return;
+    const [open, close] = comment;
+    const START = `${open}spexcode:start${close}`;
+    const END = `${open}spexcode:end${close}`;
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`\\n*${esc(START)}[\\s\\S]*?${esc(END)}\\n*`);
+    const cur = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    if (!re.test(cur))
+        return;
+    // remove ONLY our block plus the blank lines writeManagedBlock inserted around it; do NOT normalize the
+    // user's OWN whitespace elsewhere — this must leave every other byte intact so it is a faithful INVERSE of
+    // writeManagedBlock's append. A global `\n{3,}→\n\n` collapse used to sit here and mutated pre-existing
+    // blank-line runs in the user's file, which broke the policy round-trip ([[residence]]): a mode flip
+    // and back left a spurious one-line diff on a .gitignore that had internal blank lines. The leading-newline
+    // strip is GUARDED the same way: it exists only for a block sitting at the TOP of the file (whose '\n'
+    // replacement would otherwise become a leading blank) — a host file that BEGINS with its own blank lines
+    // keeps them ([[content-filter]]'s invariant, same bug class as the shim's old unconditional strip).
+    const atTop = (re.exec(cur)?.index ?? -1) === 0;
+    const replaced = cur.replace(re, '\n');
+    const out = atTop ? replaced.replace(/^\n+/, '') : replaced;
+    if (deleteIfEmpty && !out.trim()) {
+        rmSync(file, { force: true });
+        return;
+    }
+    writeFileSync(file, out);
+}
+// the shim for one harness: every event → `SPEX='…' bash <dispatch> <harnessId> <Event>`. The harness id is
+// baked in so dispatch.sh can export SPEXCODE_HARNESS (the detector for the shell side). SPEX is inherited by
+// the cli-needing handlers.
+function buildShim(id, events, dispatch, spex) {
+    const cmd = (e) => `SPEX='${spex}' bash ${dispatch} ${id} ${e}`;
+    const hooks = {};
+    for (const e of events)
+        hooks[e] = [{ hooks: [{ type: 'command', command: cmd(e) }] }];
+    return { content: JSON.stringify({ hooks }, null, 2), cmd };
+}
+// ---------------------------------------------------------------------------------------------------------
+// Codex trust — the codex-rs trusted_hash, reverse-engineered + pinned. Lives in the Codex adapter (it is a
+// codex-only fact); Claude has no analog.
+// Codex trust keys + the hash use snake_case event labels (codex hook_event_key_label).
+const SNAKE = {
+    SessionStart: 'session_start', UserPromptSubmit: 'user_prompt_submit', PreToolUse: 'pre_tool_use',
+    PostToolUse: 'post_tool_use', Stop: 'stop',
+};
+// @@@ codexHookHash - the trusted_hash codex computes (from codex-rs: command_hook_hash + version_for_toml):
+// sha256 of the canonical (recursively key-sorted, compact) JSON of {event_name, hooks:[{type,command,timeout,
+// async}]}; None fields omitted. Verified against live codex 0.142.3 samples.
+export function codexHookHash(snakeEvent, command, timeout = 600, asyncFlag = false) {
+    const canon = (v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])]))
+        : Array.isArray(v) ? v.map(canon) : v;
+    const obj = { event_name: snakeEvent, hooks: [{ type: 'command', command, timeout, async: asyncFlag }] };
+    return 'sha256:' + createHash('sha256').update(JSON.stringify(canon(obj))).digest('hex');
+}
+// @@@ stripCodexTrustFor - remove EVERY prior definition of THIS project's codex trust from a config.toml body,
+// in ANY form: our own sentinel block (whatever past format its comments used), a BARE `[projects."<proj>"]`
+// table (codex AUTO-writes one the moment it trusts a folder interactively/`exec` — NOT sentinel-wrapped), and
+// any `[hooks.state."<hooksJson>:…"]` tables. This is what makes the UNCONDITIONAL write duplicate-SAFE and
+// SELF-HEALING: codex REFUSES to load a config.toml with a duplicate key ("duplicate key"), so a sentinel-only
+// replace (the old behaviour) that missed a pre-existing bare/old block APPENDED a second `[projects."<proj>"]`
+// and took codex fully OFFLINE (the real cause of the public-vps outage). It is TABLE-scoped and STRING-compared
+// (no regex escaping of the path), so other projects' trust, the shared parent tables (`[projects]`,
+// `[hooks.state]`), and every other config key are untouched; a skipped table's body ends at the next header,
+// blank, or comment, so a user comment attached to a following table is preserved.
+function stripCodexTrustFor(cur, proj, hooksJson) {
+    const projHeader = `[projects."${proj}"]`;
+    const hooksPrefix = `[hooks.state."${hooksJson}:`;
+    const out = [];
+    let skip = false;
+    for (const line of cur.split('\n')) {
+        const t = line.trim();
+        const isHeader = /^\[\[?/.test(t); // a TOML table / array-of-tables header
+        if (skip) {
+            if (t === '' || t.startsWith('#') || isHeader)
+                skip = false;
+            else
+                continue;
+        } // end THIS table's body
+        if (isHeader && (t === projHeader || t.startsWith(hooksPrefix))) {
+            skip = true;
+            continue;
+        }
+        if (t === `# spexcode:trust:${proj} (managed — do not edit)` || t === `# spexcode:trust:end:${proj}`)
+            continue;
+        out.push(line);
+    }
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '');
+}
+// additively stamp PROJECT trust (`[projects."<proj>"] trust_level = "trusted"`) AND the per-hook
+// `trusted_hash` blocks for each event into the user's GLOBAL ~/.codex/config.toml, so a dispatched or
+// self-launched codex trusts THIS project's config layer (enabling hook discovery) AND treats each hook as
+// already-reviewed (no "Hooks need review" prompt on a persistent resume — see writeTrust). ALL prior
+// definitions of this project's trust (ours, bare, or old-format) are STRIPPED first, so the write can never
+// leave a DUPLICATE key (which breaks codex config loading) and self-heals a config that already carried one.
+// Scoped to THIS project path; never touches the user's other config. CODEX_HOME respected for testability.
+// (`events` may be empty for a trust-only stamp in tests.)
+export function writeCodexTrust(proj, events, cmdFor) {
+    const home = process.env.CODEX_HOME || join(homedir(), '.codex');
+    const file = join(home, 'config.toml');
+    const hooksJson = join(proj, '.codex', 'hooks.json');
+    const lines = [`[projects."${proj}"]`, 'trust_level = "trusted"'];
+    for (const e of events) {
+        const snake = SNAKE[e];
+        lines.push(`[hooks.state."${hooksJson}:${snake}:0:0"]`, `trusted_hash = "${codexHookHash(snake, cmdFor(e))}"`);
+    }
+    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 });
+    writeFileIfChanged(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`);
+    return file;
+}
+// the inverse of writeCodexTrust: strip THIS project's codex trust from the GLOBAL config.toml — the SAME
+// removal writeCodexTrust does before it writes, so uninstall fully clears our trust (sentinel, bare, and
+// hooks.state) and can never leave a half-block. No-op when the file/nothing-of-ours is absent (so it never
+// rewrites/normalizes a config that carries none of our trust). CODEX_HOME respected for testability.
+function removeCodexTrust(proj) {
+    const home = process.env.CODEX_HOME || join(homedir(), '.codex');
+    const file = join(home, 'config.toml');
+    if (!existsSync(file))
+        return;
+    const hooksJson = join(proj, '.codex', 'hooks.json');
+    const cur = readFileSync(file, 'utf8');
+    if (!cur.includes(`[projects."${proj}"]`) && !cur.includes(`[hooks.state."${hooksJson}:`) &&
+        !cur.includes(`# spexcode:trust:${proj} `) && !cur.includes(`# spexcode:trust:end:${proj}`))
+        return;
+    const cleaned = stripCodexTrustFor(cur, proj, hooksJson);
+    writeFileSync(file, cleaned ? `${cleaned}\n` : '');
+}
+// is this file git-tracked in proj? (guards cleanHarness's deleteIfEmpty; env-stripped git, never throws)
+function isTrackedFile(proj, f) {
+    try {
+        git(['-C', proj, 'ls-files', '--error-unmatch', f]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// @@@ cleanHarness - the shared clean: the inverse of materialize's per-harness write, expressed PURELY
+// through the adapter's own path methods so it can never drift from what write put there. Each step is
+// surgical, gated on a SpexCode identity stamp: the contract files carry the managed-block sentinels; the shim
+// is a generated file whose command line names our `dispatch.sh`; the trust is a sentinel-delimited config
+// block; the skill/agent files sit at name-scoped paths reconstructed from `arts`. So it removes ONLY our own
+// blocks and our own named products — never a user's CLAUDE.md/AGENTS.md prose, a hand-made settings.json, or
+// a sibling skill/agent the user added, and NEVER any .spec data.
+function cleanHarness(h, proj, arts, preserveProject = false) {
+    // deleteIfEmpty ONLY for an UNTRACKED contract file: a wholly-ours generated file goes; a HOST-TRACKED file
+    // that carried nothing but our block (an empty committed CLAUDE.md we folded into) is stripped back to its
+    // pristine emptiness but never deleted — deleting a tracked file would surface as a `D` in the host's status.
+    for (const f of h.contractFiles(proj))
+        removeManagedBlock(f, ['<!-- ', ' -->'], !isTrackedFile(proj, f));
+    const shim = h.shimFile(proj);
+    if ((h.shimScope === 'tree' || !preserveProject) && existsSync(shim) && readFileSync(shim, 'utf8').includes('dispatch.sh'))
+        rmSync(shim, { force: true });
+    const anchor = h.worktreeHookAnchor(proj); // the linked-worktree anchor copy, same identity gate as the shim
+    if (anchor && existsSync(anchor) && readFileSync(anchor, 'utf8').includes('dispatch.sh'))
+        rmSync(anchor, { force: true });
+    if (!preserveProject)
+        h.removeTrust(proj);
+    const sd = h.skillDir(proj);
+    if (sd)
+        for (const n of arts.skills)
+            rmSync(join(sd, n), { recursive: true, force: true });
+    const ad = h.agentDir(proj);
+    if (ad)
+        for (const n of arts.agents)
+            rmSync(join(ad, `${n}.md`), { force: true });
+}
+// ---------------------------------------------------------------------------------------------------------
+// codex per-session liveness signal — a codex process live in the pane's DESCENDANT tree, NOT the pane's
+// foreground command name, and NOT the shared app-server socket.
+// @@@ paneTreeRunsCodex - the codex TUI is alive iff a codex-ish process is live SOMEWHERE in the launch
+// pane's descendant process tree. The pane's FOREGROUND name is NOT the signal: the pane runs
+// `bash <launch.sh>` → `bash -lc <codex script>` → node (the codex CLI) → the vendored `codex` binary, and
+// tmux's `pane_current_command` reports the OUTERMOST of those — `bash` — for the entire life of a healthy,
+// rendering TUI (field-confirmed on macmini and Linux). So "foreground == codex" false-read every live codex
+// as offline, and the earlier sock-presence check false-read a dead one as online (the SHARED per-project
+// app-server socket survives a failed `--remote resume`). The honest shape test: HEALTHY = codex (by whatever
+// name — `codex`, the vendored musl binary, or the `node` its CLI runs under) exists among the pane pid's
+// descendants; FAILED = the launch script's bounded retries exhausted, everything under the pane exited, and
+// the pane sits at the bare shell — no codex/node anywhere below it. The walk is over ONE whole-box
+// pid→(ppid, comm) snapshot the caller took (a single `ps` for the whole session list); missing probe data
+// (tmux/ps couldn't report) is not-live, and the caller's boot grace still shows a fresh launch — whose tree
+// may not yet contain codex — as 'starting', not 'offline'.
+const CODEXISH = /^(codex|node)/i; // the vendored binary ('codex', 'codex-x86_64…') or the CLI's node runtime
+// the shared descendant-tree walk: does a process matching `re` live BELOW the pane pid? (The pane pid itself
+// is the shell, so descendants only.) Pure over the caller's one ps snapshot.
+function paneTreeRuns(pane, re) {
+    if (!pane?.panePid || !pane.procs?.size)
+        return false;
+    const kids = new Map();
+    for (const [pid, p] of pane.procs) {
+        const arr = kids.get(p.ppid);
+        if (arr)
+            arr.push(pid);
+        else
+            kids.set(p.ppid, [pid]);
+    }
+    const stack = [...(kids.get(pane.panePid) ?? [])]; // descendants only — the pane pid itself is the shell
+    while (stack.length) {
+        const pid = stack.pop();
+        const comm = pane.procs.get(pid)?.comm ?? '';
+        if (re.test(comm.slice(comm.lastIndexOf('/') + 1)))
+            return true; // basename — macOS ps comm is a full path
+        const c = kids.get(pid);
+        if (c)
+            stack.push(...c);
+    }
+    return false;
+}
+export function paneTreeRunsCodex(pane) { return paneTreeRuns(pane, CODEXISH); }
+// ONE whole-box pid→(ppid, comm) snapshot (a single `ps` spawn) — the table paneTreeRuns walks. Owned here
+// (beside its consumers) and shared with sessions.ts's liveSnapshot, so the two probe layers can never parse
+// ps differently. A failed/timed-out ps returns an empty table: the callers read that as not-provably-running.
+export async function procSnapshot(timeoutMs = 4000) {
+    const t = new Map();
+    let out = '';
+    try {
+        ({ stdout: out } = await pexec('ps', ['-eo', 'pid=,ppid=,comm='], { timeout: timeoutMs, killSignal: 'SIGKILL' }));
+    }
+    catch {
+        return t;
+    }
+    for (const line of out.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (m)
+            t.set(Number(m[1]), { ppid: Number(m[2]), comm: m[3].trim() });
+    }
+    return t;
+}
+// ---------------------------------------------------------------------------------------------------------
+// the two implementations.
+const CLAUDE_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'];
+const CODEX_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'];
+// the five claude-shaped events pi's generated extension SYNTHESIZES from its own lifecycle (session_start →
+// SessionStart, input → UserPromptSubmit, tool_call → PreToolUse, tool_result → PostToolUse, agent_end +
+// 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'];
+// 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'];
+// 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
+// the fallback for a truly-old record with NO pinned cmd and NO launcher name — compatibility must preserve
+// the harness's normal permission model, never silently introduce an automatic-permission flag. There is no
+// env/config-field resolution because launchers are ordinary named config entries ([[launcher-select]]).
+const claudeBaseCmd = (cmd) => cmd || 'claude';
+const codexBaseCmd = (cmd) => cmd || 'codex';
+const piBaseCmd = (cmd) => cmd || 'pi'; // pi runs tools without permission prompts — no yolo flag exists or is needed
+const opencodeBaseCmd = (cmd) => cmd || 'opencode';
+const zcodeBaseCmd = (cmd) => 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
+// prompt arg (a NEW launch → `--prompt`), or a resume marker from opencodeHarness.resumeArg: `--resume <id>`
+// re-attaches the owned opencode session (`--session <id>`, the SAME conversation), `--continue` re-attaches
+// the worktree's last session when no id was ever captured (the plugin failed before its first event). A new
+// launch's tail can never BE a literal marker (it's one quoted prompt), so the branch is unambiguous.
+export function opencodeLaunchCommand(opencodeCmd = 'opencode') {
+    const script = [
+        `if [ "\${1:-}" = "--resume" ]; then`,
+        // the marker carries the owned session id — export it so the plugin can seed rootSession at load: a
+        // resumed session re-fires NO bus event until poked, so without this the rendezvous daemon rejects
+        // every delivery (resume-continuity A-side: continuity ✓, steerability ✗).
+        `  export SPEXCODE_OPENCODE_RESUME_ID="$2"`,
+        `  exec ${opencodeCmd} --session "$2"`,
+        `elif [ "\${1:-}" = "--continue" ]; then`,
+        // no owned id to seed — mark the continue-resume so the plugin knows to ask the SDK for the
+        // reattached session (scoped to this marker so a FRESH launch can never adopt a stale session).
+        `  export SPEXCODE_OPENCODE_CONTINUE=1`,
+        `  exec ${opencodeCmd} --continue`,
+        `elif [ -n "\${1:-}" ]; then`,
+        `  exec ${opencodeCmd} --prompt "$1"`,
+        `else`,
+        `  exec ${opencodeCmd}`,
+        `fi`,
+    ].join('\n');
+    return `bash -lc ${shQuote(script)} spexcode-opencode`;
+}
+const socketListenerLiveness = (_rec, tmuxAlive, _runtimeDir, _pane, socketLive) => (tmuxAlive && !!socketLive ? 'online' : 'offline');
+const socketListenerOrPidAliveLiveness = (_rec, tmuxAlive, _runtimeDir, pane, socketLive) => (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline');
+const panePidLiveness = (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && pane?.pidAlive === true ? 'online' : 'offline');
+const recordOnline = (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) => {
+    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) => [
+    'CLAUDE_BG_BACKEND=daemon',
+    `CLAUDE_BG_RENDEZVOUS_SOCK=${rvSock(id)}`,
+];
+const noLaunchEnv = () => [];
+export const claudeHarness = {
+    id: 'claude',
+    dispatchId: 'claude',
+    headless: 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
+    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,
+    oneShotTurn: (prompt, cmd) => ({ command: `${claudeBaseCmd(cmd)} -p`, stdin: prompt }), // --print reads the prompt from stdin
+    sessionIdArg: (id) => `--session-id ${id}`, // the caller chooses the id
+    sessionEnvVar: harnessIdentity('claude').sessionEnvVar,
+    launchEnv: rendezvousLaunchEnv,
+    shimFile: (proj) => join(proj, '.claude', 'settings.json'),
+    shimScope: 'tree',
+    worktreeHookAnchor: () => null, // claude's shim already lives in the worktree (.claude/settings.json) — self-anchors, no root rewrite
+    contractFiles: (proj) => [join(proj, 'CLAUDE.md')],
+    skillDir: (proj) => join(proj, '.claude', 'skills'),
+    agentDir: (proj) => join(proj, '.claude', 'agents'),
+    shim: (dispatch, spex) => buildShim('claude', CLAUDE_EVENTS, dispatch, spex),
+    writeTrust: () => [], // Claude relies on folder-trust — no artifact to report
+    removeTrust: () => { },
+    clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject); },
+    slashCommands: claudeSlashCommands,
+    // online iff the window is up AND a LIVE LISTENER is on the rendezvous socket (`socketLive`, connect-probed by
+    // the caller) — NOT the mere existence of a stale socket FILE a crashed claude leaves behind (the 30-min
+    // dead-pane-reads-working bug). See rendezvousListening.
+    liveness: socketListenerLiveness,
+    leafOwnerNeedle: (rec) => rec.session,
+    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
+    // (verified live: `queue-operation: enqueue` with no dequeue, no turn, daemon silent), so skip this courtesy
+    // poke and leave the timeline reader to show the message. Matched on the panel's own
+    // strings — the new-session composer placeholder, or its footer key hints together (either alone could drift
+    // across claude versions; requiring the footer PAIR keeps a prose false-positive unlikely).
+    deliveryBlockedBy: (paneText) => paneText.includes('describe a task for a new session') || (paneText.includes('enter to return') && paneText.includes('space to reply'))
+        ? '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
+// reused by object composition; the whole runtime half is replaced by the stream-json controller.
+export const claudeHeadlessHarness = {
+    ...claudeHarness,
+    id: 'claude-headless',
+    sessionEnvVar: harnessIdentity('claude-headless').sessionEnvVar,
+    headless: true,
+    runtimeOwnership: 'adapter',
+    ownsRendezvous: false,
+    paneTitleIsSelfSummary: false,
+    launchCmd: (id, runtimeDir, cmd) => claudeHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), claudeBaseCmd(cmd)),
+    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) => unlinkSocks(claudeHeadlessSock(rec.session)),
+    coldRuntime: async () => ({ ok: false, reason: 'claude-headless has no exact resident unload verification' }),
+    deliveryBlockedBy: undefined,
+};
+function codexRuntimeDescriptor(endpoint, runtimeDir) {
+    return {
+        key: codexDescriptorKey(endpoint),
+        label: endpoint.id === 'legacy' ? 'Codex app-server' : `Codex app-server ${endpoint.id.slice(0, 18)}`,
+        pidFile: endpoint.pidFile,
+        receiptFile: endpoint.receiptFile,
+        residency: async () => {
+            let pid = 0;
+            try {
+                pid = Number(readFileSync(endpoint.pidFile, 'utf8').trim());
+            }
+            catch { /* stale/missing pid */ }
+            const pidLive = pid > 0 && !!processStartToken(pid);
+            const listener = await listenerAt(endpoint.socketPath, 800);
+            if (!pidLive && listener === 'dead')
+                return { healthy: true, referenceIds: [], rootAbsent: true };
+            if (pidLive && (!codexRuntimeGeneration(runtimeDir, endpoint) || 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(endpoint.socketPath);
+            return result.ok ? { healthy: true, referenceIds: result.referenceIds } : { healthy: false, referenceIds: [], error: result.error };
+        },
+        mutationGuard: (targetReferenceId, opts) => codexMutationGuard(targetReferenceId, runtimeDir, opts, endpoint),
+        probe: () => codexSharedRuntimeProbe(runtimeDir, endpoint),
+    };
+}
+function codexRuntimeDescriptors(runtimeDir) {
+    const endpoints = codexGenerationEndpoints(runtimeDir);
+    return (endpoints.length ? endpoints : [legacyCodexGenerationEndpoint(runtimeDir)])
+        .map((endpoint) => codexRuntimeDescriptor(endpoint, runtimeDir));
+}
+export const codexHarness = {
+    id: 'codex',
+    dispatchId: 'codex',
+    headless: 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
+    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,
+    oneShotTurn: (prompt, cmd) => ({ command: `${codexBaseCmd(cmd)} exec -`, stdin: prompt }), // `exec -` reads the prompt from stdin
+    sessionIdArg: () => '', // codex assigns its own id (the backend owns it via thread/start)
+    sessionEnvVar: harnessIdentity('codex').sessionEnvVar,
+    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
+    // <mainCheckout>/.codex/hooks.json — so the codex hooks shim + its trust materialize at the MAIN checkout
+    // (one per project, mirroring the per-project runtime tier), while the AGENTS.md contract + skills stay
+    // per-worktree (codex loads THOSE by walking the thread cwd). dispatch.sh resolves `proj` from the thread
+    // cwd, so one shared shim serves every worktree.
+    shimFile: (proj) => join(mainCheckout(proj), '.codex', 'hooks.json'),
+    shimScope: 'project',
+    // a LINKED worktree also needs its OWN `.codex/hooks.json` so codex-rs anchors the project config layer for
+    // the worktree cwd (without a `.codex/` under the worktree root, codex builds no layer, so the rewritten
+    // root-checkout hooks are never discovered and NO hooks fire — bypass_hook_trust cannot rescue a layer that
+    // was never built). Its content is ignored (the rewrite reads the root's shim above), so it is a pure anchor.
+    // Only for a genuine worktree: on the main checkout, shimFile already wrote `.codex/hooks.json` there.
+    worktreeHookAnchor: (proj) => (mainCheckout(proj) === proj ? null : join(proj, '.codex', 'hooks.json')),
+    contractFiles: (proj) => [join(proj, 'AGENTS.md')],
+    skillDir: (proj) => join(proj, '.codex', 'skills'),
+    agentDir: () => null, // codex has no file-discovered agent-definition primitive — materialize skips it
+    shim: (dispatch, spex) => buildShim('codex', CODEX_EVENTS, dispatch, spex),
+    // Write the FULL codex trust — BOTH tiers, UNCONDITIONALLY — because `bypass_hook_trust` covers neither on
+    // the dispatched-worker path:
+    //   (1) PROJECT trust (`[projects."<mainCheckout>"] trust_level = "trusted"`) ENABLES the project config
+    //       layer — the precondition for codex to DISCOVER our hooks AT ALL. codex-rs `get_layers` drops a
+    //       disabled (untrusted) project layer BEFORE hook discovery runs, and bypass_hook_trust is read only
+    //       AFTER, per-handler — so it can NEVER enable a layer. A dispatched worker's app-server does NOT
+    //       auto-trust the project (only the interactive TUI / `codex exec` approval flow does), so without this
+    //       an untrusted worktree thread fires ZERO hooks ("Project-local config, hooks … are disabled until the
+    //       project is trusted").
+    //   (2) per-HOOK trust (the reverse-engineered `trusted_hash` blocks — codexHookHash) marks each hook Trusted
+    //       so it is NOT "new or changed". This is REQUIRED even though the launch carries
+    //       `--dangerously-bypass-hook-trust`: our visible TUI attaches to the backend-owned thread via `codex …
+    //       resume <tid>`, and codex-rs FORCES the startup hook-review prompt on a PERSISTENT RESUME regardless of
+    //       the flag (`bypass_hook_trust_for_startup_review = config.bypass_hook_trust && !is_persistent_resume`,
+    //       tui/src/lib.rs) — an untrusted/modified hook (no matching hash) leaves the worker WEDGED at an
+    //       interactive "Hooks need review" menu. Matching hashes make review_needed_count == 0, so codex skips
+    //       the prompt and the worker runs unattended. bypass_hook_trust stays on `thread/start` + the resume flag
+    //       as DEFENCE for the non-resume paths (and if a version bump makes a hash mismatch, the app-server
+    //       thread still runs the hooks); it does not REPLACE the hashes here.
+    writeTrust: (proj, cmdFor) => [writeCodexTrust(mainCheckout(proj), CODEX_EVENTS, cmdFor)],
+    // trust is keyed by the MAIN checkout (where the codex shim materializes) — strip it at the same key.
+    removeTrust: (proj) => removeCodexTrust(mainCheckout(proj)),
+    clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject); },
+    slashCommands: codexSlashCommands,
+    // online iff the tmux window is up AND the agent is live. PRIMARY: the launch-registered `agent.pid` hot-tier
+    // verdict (`pidAlive`) — a 100ms syscall (kill-0), no ps scan. LEGACY: a pre-registration session has no
+    // agent.pid (`pidAlive` undefined) → fall back to the whole-box ps DESCENDANT-tree walk (paneTreeRunsCodex):
+    // a codex-ish process live below the pane pid, NOT the pane's foreground command (that is `bash`, the launch
+    // wrapper, even while the TUI renders — the field-confirmed false-OFFLINE) and NOT the app-server socket
+    // (SHARED per-project, it survives a failed `--remote resume` — the earlier false-ONLINE). The legacy path
+    // self-extinguishes as pre-registration sessions close.
+    liveness: (_rec, tmuxAlive, _runtimeDir, pane) => {
+        if (!tmuxAlive)
+            return 'offline';
+        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),
+    observeTurnFailures: codexTurnFailureObserver,
+    interrupt: interruptCodexTurn,
+    cleanupRuntime: async () => { },
+    targetDescriptorKey: (rec) => {
+        const endpoint = codexEndpointForRecord(rec);
+        return endpoint ? codexDescriptorKey(endpoint) : null;
+    },
+    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 endpoint = codexEndpointForRecord(rec, dir);
+        if (!endpoint)
+            return { ok: false, reason: 'no exact Codex generation binding is registered for this target' };
+        const result = await codexColdPreflight(threadId, dir, undefined, endpoint);
+        if (!result.ok)
+            return result;
+        const generationBefore = result.receipt.generation;
+        if (codexRuntimeGeneration(dir, endpoint) !== generationBefore)
+            return { ok: false, reason: 'shared Codex app-server generation changed during cold retirement guard' };
+        if (!result.alreadyCold)
+            return { ok: false, reason: `Codex target subtree ${result.receipt.activeIds.join(', ')} is not fully archived` };
+        return { ok: true, alreadyCold: true };
+    },
+    coldPreflight: async (rec) => {
+        if (!rec.harnessSessionId)
+            return { ok: false, reason: 'no exact Codex thread identity is registered' };
+        const endpoint = codexEndpointForRecord(rec);
+        return endpoint ? codexColdPreflight(rec.harnessSessionId, runtimeRoot(), undefined, endpoint)
+            : { ok: false, reason: 'no exact Codex generation binding is registered for this target' };
+    },
+    coldRuntime: async (rec, suppliedReceipt) => {
+        if (!rec.harnessSessionId)
+            return { ok: false, reason: 'no exact Codex thread identity is registered' };
+        const threadId = rec.harnessSessionId;
+        const dir = runtimeRoot();
+        const endpoint = codexEndpointForRecord(rec, dir);
+        if (!endpoint)
+            return { ok: false, reason: 'no exact Codex generation binding is registered for this target' };
+        const sock = endpoint.socketPath;
+        if (suppliedReceipt !== undefined && (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== threadId))
+            return { ok: false, reason: 'Codex cold teardown receipt is missing, malformed, or names a different target' };
+        const frozenPlan = isCodexColdPlan(suppliedReceipt) ? suppliedReceipt : null;
+        if (frozenPlan && (frozenPlan.endpoint.id !== endpoint.id || codexRuntimeGeneration(dir, endpoint) !== frozenPlan.generation))
+            return { ok: false, reason: 'shared Codex app-server generation changed after archive preflight' };
+        const preflight = await codexColdPreflight(threadId, dir, frozenPlan?.generation, endpoint);
+        if (!preflight.ok)
+            return preflight;
+        const plan = frozenPlan ?? preflight.receipt;
+        if (frozenPlan && (!sameIdSet(frozenPlan.descendantIds, preflight.receipt.descendantIds) ||
+            !sameParentEdges(frozenPlan.parentEdges, preflight.receipt.parentEdges) ||
+            !sameIdSet(frozenPlan.activeIds, preflight.receipt.activeIds) ||
+            !sameIdSet(frozenPlan.archivedIds, preflight.receipt.archivedIds)))
+            return { ok: false, reason: 'Codex target subtree ownership or collection assignment changed after archive preflight' };
+        if (codexRuntimeGeneration(dir, endpoint) !== plan.generation)
+            return { ok: false, reason: 'shared Codex app-server generation changed during target subtree guard' };
+        if (plan.activeIds.length === 0)
+            return { ok: true };
+        const subtreeSet = new Set(plan.subtreeIds);
+        const siblingBefore = plan.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId));
+        const fence = { dir, endpoint, generation: plan.generation };
+        const compensate = async (reason) => {
+            const restored = await codexRestoreColdPlan(plan, dir);
+            return { ok: false, reason: restored.ok ? reason : `${reason}; ${restored.reason}` };
+        };
+        const coldCheck = async () => {
+            const after = await codexColdPreflight(threadId, dir, plan.generation, endpoint);
+            if (!after.ok)
+                return after;
+            if (codexRuntimeGeneration(dir, endpoint) !== plan.generation)
+                return { ok: false, reason: 'shared Codex app-server generation changed during archive' };
+            if (!sameIdSet(plan.descendantIds, after.receipt.descendantIds) || !sameParentEdges(plan.parentEdges, after.receipt.parentEdges))
+                return { ok: false, reason: `Codex target descendant closure changed during archive (before=${plan.descendantIds.join(', ')}; after=${after.receipt.descendantIds.join(', ')})` };
+            if (after.receipt.activeIds.length)
+                return { ok: false, reason: `Codex target subtree remains in the active collection (${after.receipt.activeIds.join(', ')})` };
+            if (plan.unmaterialized) {
+                if (after.receipt.archivedIds.length || after.receipt.guard.referenceIds.includes(threadId))
+                    return { ok: false, reason: 'unmaterialized Codex target remains in native state after delete' };
+                return { ok: true };
+            }
+            if (!sameIdSet(plan.subtreeIds, after.receipt.archivedIds))
+                return { ok: false, reason: 'Codex target subtree is not uniquely archived after cold teardown' };
+            const afterIds = new Set(after.receipt.guard.referenceIds.filter((referenceId) => !subtreeSet.has(referenceId)));
+            if (siblingBefore.some((referenceId) => !afterIds.has(referenceId)))
+                return { ok: false, reason: 'a pre-existing shared Codex sibling reference disappeared during archive' };
+            return { ok: true };
+        };
+        const loadedSet = new Set(plan.guard.referenceIds);
+        for (const id of plan.activeIds) {
+            // 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) && !plan.unmaterialized) {
+                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, plan.unmaterialized ? 'thread/delete' : 'thread/archive', id, fence, undefined, budgetMs);
+            if (archived.ok)
+                continue;
+            const action = plan.unmaterialized ? 'deleting' : 'archiving';
+            const reason = `${archived.error} while ${action} 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: 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;
+        return compensate(verified.reason);
+    },
+    quarantineOrphanThread: codexQuarantineOrphanThread,
+    restoreRuntime: async (rec, suppliedReceipt) => {
+        if (!rec.harnessSessionId)
+            return { ok: false, reason: 'no exact Codex thread identity is registered' };
+        if (suppliedReceipt !== undefined) {
+            if (!isCodexColdPlan(suppliedReceipt) || suppliedReceipt.threadId !== rec.harnessSessionId)
+                return { ok: false, reason: 'Codex cold compensation receipt is invalid or names a different target' };
+            if (suppliedReceipt.unmaterialized)
+                return { ok: true };
+            return codexRestoreColdPlan(suppliedReceipt);
+        }
+        const endpoint = codexEndpointForRecord(rec);
+        if (!endpoint)
+            return { ok: false, reason: 'no exact Codex generation binding is registered for this target' };
+        const sock = endpoint.socketPath;
+        const reconcile = async () => {
+            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: codexRuntimeDescriptors,
+    // 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'],
+};
+const sameCodexHeadlessReadinessProof = (left, right) => 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, descriptorKey, threadId, excludingSessionId) => {
+    const root = join(runtimeDir, 'sessions');
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? [] : null;
+    }
+    const owners = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === excludingSessionId)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(root, entry.name, 'session.json'), 'utf8'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            return null;
+        }
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const record = parsed;
+        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) {
+    const record = current();
+    if (!record?.governed || record.stopped || record.archived || !record.harnessSessionId)
+        return null;
+    const endpoint = codexEndpointForRecord(record, record.runtimeDir);
+    if (!endpoint)
+        return null;
+    const descriptor = codexHeadlessHarness.sharedRuntimes?.(record.runtimeDir)
+        .find((candidate) => candidate.key === codexDescriptorKey(endpoint));
+    if (!descriptor?.residency)
+        return null;
+    const generationBefore = codexRuntimeGenerationProof(record.runtimeDir, endpoint);
+    if (!generationBefore)
+        return null;
+    let resident;
+    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, endpoint);
+    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,
+// while launch only runs the backend-owned thread/start + first turn. There is no TUI to attach after that turn;
+// the shared project app-server keeps the thread addressable and idle sends use the inherited JSON-RPC channel.
+export const codexHeadlessHarness = {
+    ...codexHarness,
+    id: 'codex-headless',
+    sessionEnvVar: harnessIdentity('codex-headless').sessionEnvVar,
+    headless: true,
+    runtimeOwnership: 'adapter',
+    launchOneShot: true,
+    launchCmd: (id, runtimeDir, cmd) => codexHeadlessLaunchCommand(id, codexBaseCmd(cmd), undefined, runtimeDir ?? runtimeRoot()),
+    // 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: () => '',
+};
+// @@@ piHarness - the pi adapter (@earendil-works/pi-coding-agent). pi is the CLOSEST to claude of the four:
+// the caller pins the session id at launch (`--session-id <id>`, creating the session if missing), the shim
+// 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 (the adapter's launchEnv exports
+// CLAUDE_BG_RENDEZVOUS_SOCK) speaking the reclaude line protocol — so
+// deliverViaRendezvous and the socket-listener liveness work through the same adapter seam. 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
+// one-run defence. See pi-harness.ts for the extension source + trust mechanics.
+export const piHarness = {
+    id: 'pi',
+    dispatchId: 'pi',
+    headless: 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
+    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)
+    sessionEnvVar: harnessIdentity('pi').sessionEnvVar, // exported by the generated extension at session_start; tool subprocesses inherit it
+    launchEnv: rendezvousLaunchEnv,
+    shimFile: (proj) => join(proj, '.pi', 'extensions', 'spexcode.ts'),
+    shimScope: 'tree',
+    worktreeHookAnchor: () => null, // the extension lives in the worktree and self-anchors, like claude
+    contractFiles: (proj) => [join(proj, 'AGENTS.md')], // pi auto-loads AGENTS.md context files (shared with codex — writeManagedBlock is idempotent)
+    skillDir: (proj) => join(proj, '.pi', 'skills'), // Agent Skills standard dirs, discovered after project trust
+    agentDir: () => null, // pi has no file-discovered sub-agent primitive — materialize skips it
+    shim: (dispatch, spex) => ({
+        content: piExtensionSource(dispatch, spex),
+        cmd: (e) => `SPEX='${spex}' bash ${dispatch} pi ${e}`, // what the extension actually spawns, for parity with buildShim
+    }),
+    writeTrust: (proj) => [writePiTrust(mainCheckout(proj))], // trust keys on the MAIN checkout; nearest-parent lookup covers worktrees
+    removeTrust: (proj) => removePiTrust(mainCheckout(proj)),
+    clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject); },
+    slashCommands: piSlashCommands,
+    // claude's exact liveness: the window is up AND a live LISTENER answers on the rendezvous socket — the
+    // socket the generated extension binds. socketLive is already probed for every windowed session.
+    liveness: socketListenerLiveness,
+    leafOwnerNeedle: (rec) => rec.session,
+    deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
+    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}`,
+};
+// pi-headless is an independent harness: its materialization surface is literally pi's, while a resident
+// controller owns non-interactive text-mode turns. Active turns steer through pi's rendezvous extension;
+// idle delivery cold-wakes the exact saved session with `--session` (never `--session-id`, which would create a
+// new conversation). The controller deliberately reports record-backed liveness, matching Claude headless.
+export const piHeadlessHarness = {
+    ...piHarness,
+    id: 'pi-headless',
+    sessionEnvVar: harnessIdentity('pi-headless').sessionEnvVar,
+    headless: true,
+    // The controller is a per-session process launched in the target tmux pane. Its launch-registered PID
+    // and argv session id are exact leaf ownership evidence; record-backed liveness does not make it shared.
+    runtimeOwnership: 'leaf',
+    paneTitleIsSelfSummary: false,
+    launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
+    liveness: recordOnline,
+    deliver: deliverViaPiHeadless,
+    cleanupRuntime: (rec) => unlinkSocks(piHeadlessSock(rec.session), rvSock(rec.session)),
+    coldRuntime: async (rec) => {
+        const result = await piHeadlessColdRuntime(rec);
+        return result.ok ? { ok: true } : { ok: false, reason: result.error || 'pi-headless runtime remains unproven' };
+    },
+    deliveryBlockedBy: undefined,
+    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 = {
+    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,
+    // z-code's one-turn launcher already IS the non-interactive shape; it takes the prompt as an argument.
+    oneShotTurn: (prompt, cmd) => ({ command: `${zcodeBaseCmd(cmd)} --prompt ${shQuote(prompt)}`, stdin: '' }),
+    sessionIdArg: () => '',
+    sessionEnvVar: harnessIdentity('zcode').sessionEnvVar,
+    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: () => { },
+    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 () => { },
+    coldRuntime: async () => ({ ok: true }),
+    resumeArg: () => { throw new Error(ZCODE_CONTROL_UNAVAILABLE); },
+};
+export const opencodeHarness = {
+    id: 'opencode',
+    dispatchId: 'opencode',
+    headless: false,
+    events: OPENCODE_EVENTS,
+    // LITERALLY true: the generated plugin ([[opencode-harness]], opencode.ts) BINDS the per-session rendezvous
+    // 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,
+    // `opencode run` takes the message positionally; it documents no stdin form, so the prompt is an argument.
+    oneShotTurn: (prompt, cmd) => ({ command: `${opencodeBaseCmd(cmd)} run ${shQuote(prompt)}`, stdin: '' }),
+    sessionIdArg: () => '', // opencode mints its own session id; the plugin's first event reports it back (opencode-capture)
+    // opencode exports NO per-session env var to its tool subprocesses (probed, 1.18.3). Identity flows through
+    // the launch-injected SPEXCODE_SESSION_ID — honest here because each opencode TUI is a per-session process
+    // (no codex-style shared-server contamination). This var is therefore never set; envSessionId's
+    // SPEXCODE_SESSION_ID tier resolves the record.
+    sessionEnvVar: harnessIdentity('opencode').sessionEnvVar,
+    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'),
+    shimScope: 'tree',
+    worktreeHookAnchor: () => null,
+    contractFiles: (proj) => [join(proj, 'AGENTS.md')], // opencode reads AGENTS.md natively (same file codex owns; the managed block is idempotent across writers)
+    skillDir: (proj) => join(proj, '.opencode', 'skills'),
+    agentDir: (proj) => join(proj, '.opencode', 'agents'),
+    // content = the plugin source; cmd = the SAME per-event command the plugin bakes into dispatch calls, so
+    // any consumer that hashes/inspects commands sees one truth (trust is a no-op here regardless).
+    shim: (dispatch, spex) => ({ content: opencodePluginSource(dispatch, spex), cmd: (e) => `SPEX='${spex}' bash ${dispatch} opencode ${e}` }),
+    writeTrust: () => [], // permission policy stays with the launcher command; no trust artifact to report
+    removeTrust: () => { },
+    clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject); },
+    slashCommands: opencodeSlashCommands,
+    // online iff the window is up AND the agent answers on a channel: PREFER the rendezvous socket listener
+    // (the plugin is alive), FALL BACK to the launch-registered agent.pid (kill-0) so a plugin that failed to
+    // load still reads honestly from the process signal instead of a false offline.
+    liveness: socketListenerOrPidAliveLiveness,
+    leafOwnerNeedle: (rec) => rec.session,
+    deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
+    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
+    // is: a NEW launch's tail is always ONE single-quoted prompt arg, never a literal marker.
+    resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : '--continue'),
+};
+// OpenCode headless is a separate harness, not an opencode mode. Its materialize half is exactly
+// opencodeHarness; only the one-turn runtime and its capability row differ.
+export const opencodeHeadlessHarness = {
+    ...opencodeHarness,
+    id: 'opencode-headless',
+    sessionEnvVar: harnessIdentity('opencode-headless').sessionEnvVar,
+    headless: true,
+    runtimeOwnership: 'adapter',
+    launchCmd: (_id, _runtimeDir, cmd) => opencodeHeadlessLaunchCommand(opencodeBaseCmd(cmd)),
+    // 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) => {
+        return deliverViaSocketOrWake(rec.session, text, rec.mid, () => 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`);
+    },
+};
+// every adapter — materialize iterates this to write each harness's artifacts in one pass.
+export const HARNESSES = [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 = 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) {
+    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) {
+    const h = harnessByIdOrNull(id);
+    if (!h)
+        throw new Error(`unknown harness '${id}' (known: ${HARNESSES.map((x) => x.id).join(', ')})`);
+    return h;
+}
+// the complete configured named launchers from spexcode.json, as a stable name-sorted list (for CLI/session
+// resolution and downstream projections). Picking a launcher is the ONLY launch choice; the old separate
+// harness pick is gone.
+export function launcherList(root = mainCheckout()) {
+    const m = readConfig(root).sessions?.launchers || {};
+    return Object.keys(m)
+        .map((name) => {
+        const harness = harnessById(m[name].harness || defaultHarness.id);
+        return { name, harness: harness.id, cmd: m[name].cmd, headless: harness.headless };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+// The dashboard's visibility projection. It never removes a launcher from the complete config/CLI path;
+// it only narrows GET /api/settings for the New Session picker ([[launcher-visibility]]).
+export function dashboardLauncherList(root = mainCheckout()) {
+    const showHeadless = readConfig(root).dashboard?.showHeadlessLaunchers === true;
+    return launcherList(root).filter((launcher) => showHeadless || !launcher.headless);
+}
+export const MISSING_DEFAULT_LAUNCHER_ERROR = 'sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {"sessions":{"defaultLauncher":"claude"}})';
+// the configured default launcher NAME ([[launcher-select]]) — the profile `spex session new`/a dropdown pick with no
+// explicit choice resolves. Missing config is a fail-loud setup error, never an implicit fallthrough to a
+// `claude` launcher (which `spex init` seeds by name, so a default can point at it explicitly).
+export function defaultLauncher(root = mainCheckout()) {
+    const name = readConfig(root).sessions?.defaultLauncher?.trim();
+    if (!name)
+        throw new Error(MISSING_DEFAULT_LAUNCHER_ERROR);
+    return name;
+}
+export function launcherDefault(root = mainCheckout()) {
+    try {
+        const name = defaultLauncher(root);
+        resolveLauncher(name, root);
+        return { default: name, error: null };
+    }
+    catch (e) {
+        return { default: null, error: String(e.message || e) };
+    }
+}
+export function resolveLauncher(name, root = mainCheckout()) {
+    const l = readConfig(root).sessions?.launchers?.[name];
+    if (!l)
+        throw new Error(`unknown launcher '${name}' (configured: ${launcherList(root).map((x) => x.name).join(', ') || 'none'})`);
+    if (!l.cmd)
+        throw new Error(`launcher '${name}' is missing cmd`);
+    const harness = harnessById(l.harness || defaultHarness.id); // validate the harness id fail-loud
+    return { name, harness: harness.id, cmd: l.cmd, headless: harness.headless };
+}