spexcode 0.6.7 → 0.7.0-next.0

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

@@ -1,4 +1,5 @@
 import { closeSync, openSync, readSync, writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { parse as parseToml } from 'smol-toml';
 import { join, dirname, basename } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
@@ -12,14 +13,14 @@ import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js'
 import { claudeHeadlessColdRuntime, claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
 import { codexHeadlessLaunchCommand } from './codex-headless.js';
 import { opencodeHeadlessColdRuntime, opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
-import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
+import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, interruptPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
 import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath, spexcodeHome } 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 { claudeTranscript, codexRolloutPath, codexTranscript, opencodeTranscript, piTranscript, unsupportedTranscript } from '@spexcode/transcript';
 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
@@ -302,21 +303,38 @@ async function claudeDeliveryTransport(rec) {
     return rendezvousDeliveryTransport(rec);
 }
 const unprovenDeliveryTransport = async () => ({ kind: 'unproven' });
-function replyViaSocket(sock, text, mid, auth) {
+// Claude's rendezvous daemon owns one connection at a time. A liveness probe can therefore destroy a
+// delivery connection after its write has reached the kernel but before the daemon parses the line. Send the
+// reply and an in-order repaint probe in one chunk: repaint-done proves the reply line was parsed first; a
+// close/reset before that proves the whole chunk was discarded and is safe to retry. An open connection that
+// outlives the wall is treated as busy, not lost, preserving the no-false-failure behavior for active turns.
+function replyViaSocket(sock, text, mid, auth, wallMs = 10_000) {
     return new Promise((resolve) => {
         let settled = false;
         let c;
+        let wall;
         const done = (r) => {
             if (settled)
                 return;
             settled = true;
-            if (!r.ok)
+            clearTimeout(wall);
+            if (r.ok) {
+                // A confirmed repaint has already crossed the parser. On a busy timeout, finish the stream cleanly so
+                // the daemon can consume the buffered pair before its FIN; never destroy an unparsed write.
+                try {
+                    c?.end();
+                }
+                catch { /* */ }
+            }
+            else {
                 try {
                     c?.destroy();
                 }
                 catch { /* */ }
+            }
             resolve(r);
         };
+        wall = setTimeout(() => done({ ok: true }), wallMs);
         try {
             c = createConnection({ path: sock });
         }
@@ -326,29 +344,49 @@ function replyViaSocket(sock, text, mid, auth) {
         }
         c.on('error', (e) => {
             const code = e?.code || String(e);
-            done({ ok: false, error: `rendezvous socket error: ${code}` });
+            done({ ok: false, kicked: code === 'ECONNRESET' || code === 'EPIPE', error: `rendezvous socket error: ${code} — prompt NOT delivered` });
+        });
+        c.on('close', () => done({ ok: false, kicked: true, error: 'rendezvous connection closed before the daemon parsed the prompt (kicked by a concurrent connect)' }));
+        c.on('connect', () => c.write(`${auth ? JSON.stringify({ role: 'controller', auth }) + '\n' : ''}${JSON.stringify({ type: 'reply', text, ...(mid ? { mid } : {}) })}\n${JSON.stringify({ type: 'repaint' })}\n`));
+        let buf = '';
+        c.on('data', (chunk) => {
+            buf += chunk.toString('utf8');
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                let type = '';
+                try {
+                    type = JSON.parse(line)?.type ?? '';
+                }
+                catch {
+                    continue;
+                }
+                if (type === 'repaint-done')
+                    return done({ ok: true });
+                if (type === 'reply-rejected' || type === 'auth-rejected')
+                    return done({ ok: false, error: `rendezvous daemon rejected the prompt (${type}) — prompt NOT delivered` });
+                if (type === 'shutting-down')
+                    return done({ ok: false, error: 'agent is shutting down — prompt NOT delivered' });
+            }
         });
-        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) {
+async function pokeRendezvous(sock, text, mid, auth, wallMs) {
     let last = { ok: false, error: 'not attempted' };
     for (let attempt = 0; attempt < POKE_ATTEMPTS; attempt++) {
-        last = await replyViaSocket(sock, text, mid, auth);
+        last = await replyViaSocket(sock, text, mid, auth, wallMs);
         if (last.ok)
             return last;
+        if (!last.kicked)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 60 + Math.random() * 140));
     }
     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 deliverViaRendezvous(id, text, mid, wallMs) {
+    return pokeRendezvous(rvSock(id), text, mid, undefined, wallMs);
 }
 export async function deliverViaClaudeRendezvous(id, text, mid, runtimeDir) {
     const fork = claudeForkTransport(id, runtimeDir);
@@ -371,12 +409,89 @@ export async function deliverViaSocketOrWake(id, text, mid, coldWake, unprovenEr
         return { ok: false, error: unprovenError };
     return coldWake();
 }
+const RENDEZVOUS_INTERRUPT_WALL_MS = 10_000;
+const RENDEZVOUS_INTERRUPT_SETTLE_MS = 15_000;
+// @@@ interruptViaRendezvous - one `interrupt` line to the session's LIVE rendezvous listener, confirmed by the
+// shim's own answer ([[shim-runtime]] runs the host's native abort — pi's ctx.abort(), opencode's
+// session.abort — and writes interrupt-done / interrupt-rejected). Unlike a reply poke, whose durable copy is
+// the timeline, an interrupt has nothing to fall back on: silence is a loud failure, never an optimistic ok.
+// A generative shim serves its socket only while a turn process is alive, so a dead listener means no turn
+// is running — nothing to interrupt — and an unproven probe sends nothing. `settle` additionally waits for
+// that listener to go dead: for a one-turn-per-process adapter the abort ends the process, and confirming
+// only then means a delivery that follows the interrupt wakes cold instead of poking an exiting agent.
+export async function interruptViaRendezvous(id, harness, opts = {}) {
+    const probe = await rendezvousListening(id);
+    if (probe === 'dead')
+        return { ok: false, error: `no ${harness} turn is running for session ${id} - nothing to interrupt` };
+    if (probe === 'unproven')
+        return { ok: false, error: `${harness} rendezvous listener for session ${id} is unproven - interrupt NOT sent` };
+    const answered = await sendRendezvousInterrupt(id, harness);
+    if (!answered.ok || !opts.settle)
+        return answered;
+    const deadline = Date.now() + RENDEZVOUS_INTERRUPT_SETTLE_MS;
+    for (;;) {
+        const state = await rendezvousListening(id);
+        if (state === 'dead')
+            return { ok: true };
+        if (Date.now() >= deadline)
+            return { ok: false, error: `${harness} confirmed the interrupt but its turn process for session ${id} is still ${state === 'live' ? 'serving' : 'unproven'} after ${RENDEZVOUS_INTERRUPT_SETTLE_MS}ms` };
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+}
+function sendRendezvousInterrupt(id, harness) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let c;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(wall);
+            try {
+                c?.destroy();
+            }
+            catch { /* */ }
+            resolve(r);
+        };
+        const wall = setTimeout(() => done({ ok: false, error: `${harness} did not confirm the interrupt for session ${id} within ${RENDEZVOUS_INTERRUPT_WALL_MS}ms (a shim materialized before interrupt support never answers - rerun spex materialize)` }), RENDEZVOUS_INTERRUPT_WALL_MS);
+        try {
+            c = createConnection({ path: rvSock(id) });
+        }
+        catch (e) {
+            done({ ok: false, error: `rendezvous socket connect threw: ${String(e)} - interrupt NOT sent` });
+            return;
+        }
+        c.on('error', (e) => done({ ok: false, error: `rendezvous socket error: ${e?.code || String(e)} - interrupt NOT confirmed` }));
+        c.on('close', () => done({ ok: false, error: `rendezvous connection closed before ${harness} answered the interrupt` }));
+        c.on('connect', () => c.write(`${JSON.stringify({ type: 'interrupt' })}\n`));
+        let buf = '';
+        c.on('data', (chunk) => {
+            buf += chunk.toString('utf8');
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                let msg = {};
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.type === 'interrupt-done')
+                    return done({ ok: true });
+                if (msg.type === 'interrupt-rejected')
+                    return done({ ok: false, error: `${harness} rejected the interrupt: ${msg.error || 'no reason given'}` });
+            }
+        });
+    });
+}
 // 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.
+// is the one the pane is showing. The failure observer owns the active native turn id from app-server
+// notifications; delivery does not read the thread or replay its history — see codexInjectMessage.
 const codexTextInput = (text) => [{ type: 'text', text, text_elements: [] }];
 export function codexHandshakeMessages(threadId) {
     return [
@@ -390,7 +505,6 @@ export function codexHandshakeMessages(threadId) {
         },
         { 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
@@ -406,7 +520,9 @@ export function codexInjectMessage(threadId, text, cwd, activeTurnId, id = 4, cl
         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
+// the in-progress turn id from a `thread/read{includeTurns}` result, or null when the thread is idle. This is
+// retained for ownership/replay probes; delivery uses codexObservedActiveTurnId because it must not request the
+// full history. 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) {
@@ -415,6 +531,20 @@ export function activeTurnIdFromThread(readResult) {
     const active = turns.find((t) => t?.status === 'inProgress');
     return active?.id ?? null;
 }
+// The app-server's lightweight thread/read intentionally omits the turn list. Keep the native active id
+// observed by the failure subscription so a send can steer without replaying the whole conversation.
+const codexActiveTurns = new Map();
+export function codexObservedActiveTurnId(threadId) {
+    return codexActiveTurns.get(threadId) || null;
+}
+function rememberCodexActiveTurn(threadId, turnId) {
+    if (typeof turnId === 'string' && turnId)
+        codexActiveTurns.set(threadId, turnId);
+}
+function forgetCodexActiveTurn(threadId, turnId) {
+    if (turnId === undefined || codexActiveTurns.get(threadId) === turnId)
+        codexActiveTurns.delete(threadId);
+}
 // 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
@@ -539,8 +669,13 @@ export function codexLaunchCommand(id, codexCmd = 'codex', serverCmd, dir = runt
         `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).
+            // A headless resume has no TUI to reload the thread. The shared app-server evicts an idle thread from its
+            // loaded set, and headless readiness proves online only for a RESIDENT thread, so resume must reopen it
+            // here — the load the visible TUI's `resume "$tid"` would have done — or readiness times out for a thread
+            // that is fine on disk. codex-generation-session above already ensured the app-server, so `$sock` is live.
+            `  ${SPEX} internal codex-reopen "$sock" "$tid" || exit 1`,
+            // A headless forced reopen with NO thread id and no prompt has nothing to attach and nothing to launch.
+            // Keep it a no-op instead of calling codex-launch without a prompt (which would mint an unrelated thread).
             `elif [ "$#" -eq 0 ]; then`,
             `  exit 0`,
         ]),
@@ -556,7 +691,11 @@ export function codexLaunchCommand(id, codexCmd = 'codex', serverCmd, dir = runt
         // 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"`] : []),
+        // A remote Codex TUI cannot inherit the launch shell's cwd: when `tui.resume_cwd = "current"` is
+        // configured, Codex requires an explicit workspace root for every `--remote` invocation. Keep the
+        // directory tied to the generated script's actual pane cwd so linked worktrees with spaces remain one
+        // argument and the resumed thread loads the same project context as thread/start above.
+        ...(attachTui ? [`exec ${codexCmd}${tuiBypass} -c ${shQuote(`shell_environment_policy.set.SPEXCODE_SESSION_ID=${id}`)} --cd "$PWD" --remote unix://"$sock" resume "$tid"`] : []),
     ].join('\n');
     return `bash -lc ${shQuote(script)} spexcode-codex`;
 }
@@ -590,7 +729,7 @@ function encodeWsFrame(opcode, payload) {
     return Buffer.concat([header, mask, masked]);
 }
 const wsText = (s) => encodeWsFrame(0x1, Buffer.from(s, 'utf8'));
-function drainWsFrames(s, conn, onText) {
+function drainWsFrames(s, conn, onText, acceptPayload = () => true) {
     for (;;) {
         if (s.buf.length < 2)
             return false;
@@ -635,7 +774,7 @@ function drainWsFrames(s, conn, onText) {
             s.fragBuf = payload;
         }
         if (fin) {
-            if (s.fragOp === 0x1)
+            if (s.fragOp === 0x1 && acceptPayload(s.fragBuf))
                 onText(s.fragBuf.toString('utf8'));
             s.fragBuf = Buffer.alloc(0);
             s.fragOp = 0;
@@ -644,6 +783,9 @@ function drainWsFrames(s, conn, onText) {
 }
 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 } } };
+// Native Codex can take 15-17s to answer thread/resume under a loaded app-server. A shorter
+// deadline creates a retry storm in the session reconciler, not a useful failure signal.
+export const CODEX_TURN_OBSERVER_SUBSCRIBE_MS = 30_000;
 // 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
@@ -665,6 +807,9 @@ export function codexTurnFailureObserver(rec, onFailure) {
     const frames = { buf: Buffer.alloc(0), fragOp: 0, fragBuf: Buffer.alloc(0) };
     let upgraded = false, settled = false;
     let reconciliationTimer = null;
+    let readySettled = false;
+    let resolveReady;
+    const ready = new Promise((resolve) => { resolveReady = resolve; });
     let resolveClosed;
     const closed = new Promise((resolve) => { resolveClosed = resolve; });
     const cancelReconciliation = () => {
@@ -677,6 +822,10 @@ export function codexTurnFailureObserver(rec, onFailure) {
         if (settled)
             return;
         settled = true;
+        if (!readySettled) {
+            readySettled = true;
+            resolveReady(false);
+        }
         clearTimeout(timer);
         cancelReconciliation();
         try {
@@ -685,7 +834,7 @@ export function codexTurnFailureObserver(rec, onFailure) {
         catch { }
         resolveClosed(reason);
     };
-    const timer = setTimeout(() => finish('Codex turn observer did not subscribe within 5000ms'), 5000);
+    const timer = setTimeout(() => finish(`Codex turn observer did not subscribe within ${CODEX_TURN_OBSERVER_SUBSCRIBE_MS}ms`), CODEX_TURN_OBSERVER_SUBSCRIBE_MS);
     timer.unref?.();
     const send = (message) => conn.write(wsText(JSON.stringify(message)));
     const report = (turn, fallbackMessage) => {
@@ -702,6 +851,11 @@ export function codexTurnFailureObserver(rec, onFailure) {
     conn.on('close', () => finish('Codex turn observer connection closed'));
     conn.on('connect', () => conn.write(WS_UPGRADE(randomBytes(16).toString('base64'))));
     const handle = (json) => {
+        // A resumed Codex thread can stream large goal/progress notifications while the turn runs. They are
+        // irrelevant to this failure observer; avoid JSON.parse on those payloads so one active turn cannot make
+        // the backend spend its memory and CPU re-materializing a transcript it does not use.
+        if (json.includes('"method"') && !json.includes('"method":"turn/started"') && !json.includes('"method":"turn/completed"'))
+            return;
         let message;
         try {
             message = JSON.parse(json);
@@ -721,10 +875,18 @@ export function codexTurnFailureObserver(rec, onFailure) {
         }
         if (message.id === 2 && message.result) {
             clearTimeout(timer);
+            if (!readySettled) {
+                readySettled = true;
+                resolveReady(true);
+            }
             const result = message.result;
+            const initialTurns = result.initialTurnsPage?.data;
+            const initialActive = Array.isArray(initialTurns)
+                ? initialTurns.find((turn) => turn?.status === 'inProgress')
+                : null;
+            rememberCodexActiveTurn(threadId, initialActive?.id);
             if (result.thread?.status?.type === 'systemError') {
-                const turns = result.initialTurnsPage?.data;
-                const latest = Array.isArray(turns) ? turns[0] : null;
+                const latest = Array.isArray(initialTurns) ? initialTurns[0] : null;
                 // Give a concurrently-starting turn's native notification precedence over this historical snapshot.
                 reconciliationTimer = setTimeout(() => {
                     reconciliationTimer = null;
@@ -736,12 +898,15 @@ export function codexTurnFailureObserver(rec, onFailure) {
         }
         if (message.method === 'turn/started') {
             const params = message.params;
-            if (params?.threadId === threadId)
+            if (params?.threadId === threadId) {
+                rememberCodexActiveTurn(threadId, params.turn?.id);
                 cancelReconciliation();
+            }
         }
         if (message.method === 'turn/completed') {
             const params = message.params;
             if (params?.threadId === threadId) {
+                forgetCodexActiveTurn(threadId, params.turn?.id);
                 cancelReconciliation();
                 report(params.turn);
             }
@@ -760,10 +925,13 @@ export function codexTurnFailureObserver(rec, onFailure) {
             frames.buf = frames.buf.slice(split + 4);
             send(wsInitialize);
         }
-        if (drainWsFrames(frames, conn, handle))
+        if (drainWsFrames(frames, conn, handle, (payload) => {
+            const method = Buffer.from('"method"');
+            return !payload.includes(method) || payload.includes(Buffer.from('"turn/started"')) || payload.includes(Buffer.from('"turn/completed"'));
+        }))
             finish('Codex app-server closed the turn observer');
     });
-    return { close: () => finish(null), closed };
+    return { close: () => finish(null), closed, ready };
 }
 function codexThreadMutation(sock, method, threadId, fence, turnId, budgetMs = CODEX_MUTATION_BASE_MS) {
     const generationError = () => fence && codexRuntimeGeneration(fence.dir, fence.endpoint) !== fence.generation
@@ -860,6 +1028,69 @@ const CODEX_MUTATION_CENSUS_MS = 15_000;
 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);
+// @@@ codexReopenThread - load an evicted thread back into the shared app-server WITHOUT running a turn. The
+// app-server evicts an idle thread from its in-memory loaded set, and codex-headless readiness/liveness proves
+// online only when the thread is resident (thread/loaded/list). A visible-TUI resume reloads it implicitly via
+// `resume "$tid"`; headless has no TUI, so its resume must issue this `thread/resume` itself or readiness times
+// out for a thread that is perfectly fine on disk. `excludeTurns` + a one-row page keeps a huge rollout from
+// streaming back — we only need the load, not the history. Idempotent: reopening an already-loaded thread is a
+// no-op the server answers at once.
+export function codexReopenThread(sock, threadId, budgetMs = 20_000) {
+    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 reopen thread ${threadId} within ${budgetMs}ms` }), budgetMs);
+        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/resume 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/resume', params: { threadId, excludeTurns: true, initialTurnsPage: { limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' } } });
+            }
+            if (m.id === 2 && m.result)
+                return 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 thread/resume' });
+                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 thread/resume' });
+        });
+    });
+}
 // 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.
@@ -1579,7 +1810,7 @@ export function codexThreadId(sock) {
 // 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)) {
+export function codexSharedRuntimeProbe(dir = runtimeRoot(), endpoint = legacyCodexGenerationEndpoint(dir), referenceIds) {
     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;
@@ -1676,11 +1907,19 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot(), endpoint = legacyCo
                     // Continue with the complete paginated set, not just the first manager page.
                     if (!loadedIds.size)
                         return done({ healthy: true, references: [] });
-                    loadedIds.forEach((threadId) => {
+                    const wanted = referenceIds === undefined ? [...loadedIds] : [...loadedIds].filter((threadId) => referenceIds.includes(threadId));
+                    loadedIds.forEach((threadId) => references.set(threadId, { referenceId: threadId, turnPresence: 'unknown' }));
+                    // A draining generation deliberately has no native turn reads. Complete the census after recording
+                    // loaded ownership; leaving the request map empty would otherwise wait for the global timeout forever.
+                    if (!wanted.length)
+                        return done({ healthy: true, references: [...references.values()] });
+                    wanted.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 } });
+                        // Ownership sampling only needs the native status, never the persisted turn history. The old
+                        // includeTurns:true request made a periodic resource report replay every loaded conversation and
+                        // was the direct source of 5s probe timeouts on the draining generation.
+                        send({ id, method: 'thread/read', params: { threadId, includeTurns: false } });
                     });
                     return;
                 }
@@ -1689,9 +1928,10 @@ export function codexSharedRuntimeProbe(dir = runtimeRoot(), endpoint = legacyCo
                     requests.delete(m.id);
                     const thread = m.result.thread;
                     const turnId = activeTurnIdFromThread(m.result);
+                    const nativeStatus = typeof thread?.status === 'string' ? thread.status : thread?.status?.type;
                     references.set(threadId, {
                         referenceId: threadId,
-                        turnPresence: !Array.isArray(thread?.turns) ? 'unknown' : turnId ? 'active' : 'idle',
+                        turnPresence: turnId || nativeStatus === 'active' ? 'active' : nativeStatus === 'idle' ? 'idle' : 'unknown',
                         ...(turnId ? { turnId } : {}),
                     });
                     if (!requests.size)
@@ -1812,7 +2052,7 @@ const codexTurnConfirmMs = () => {
 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)]
+        const hs = codexHandshakeMessages(threadId); // [initialize(1), initialized, thread/loaded/list(2)]
         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)
@@ -1857,14 +2097,11 @@ function sendCodexAppServerTurn(sock, threadId, text, cwd, clientUserMessageId)
                 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
+            if (m.id === 2 && m.result) { // loaded-thread list → confirm OUR thread is live, then inject
                 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);
+                const turnId = codexObservedActiveTurnId(threadId);
                 steering = !!turnId;
                 return send(codexInjectMessage(threadId, text, cwd, turnId, 4, clientUserMessageId)); // id 4: turn/steer the live turn, or turn/start
             }
@@ -2106,6 +2343,157 @@ export function removeManagedBlock(file, comment = ['<!-- ', ' -->'], deleteIfEm
     }
     writeFileSync(file, out);
 }
+// @@@ managed-json-hooks - the JSON counterpart of writeManagedBlock/removeManagedBlock, for a shim file the
+// host agent SHARES with the user. `.claude/settings.json` (and `.codex/hooks.json`, `.zcode/settings.json`)
+// is the user's project config — permissions, env, statusLine, their own hooks — that merely HAPPENS to be
+// where the harness also discovers ours. A whole-file write there is silent data loss, and a whole-file
+// delete on uninstall makes it permanent for an untracked (gitignored) file. JSON has no comment syntax, so
+// the sentinel that scopes ownership is the hook COMMAND itself: every entry we write invokes `dispatch.sh`,
+// and ONLY such entries are ever removed. Everything else round-trips — other keys, other events, foreign
+// hook groups, and the user's half of a group that mixes both.
+const isOurHookEntry = (entry) => !!entry && typeof entry === 'object' && typeof entry.command === 'string'
+    && entry.command.includes('dispatch.sh');
+// drop OUR entries from one event's group list, keeping every foreign group byte-for-byte and keeping the
+// user's half of a mixed group. A group whose entries were all ours disappears with it.
+function stripOurHookGroups(list) {
+    if (!Array.isArray(list))
+        return Array.isArray(list) ? list : [];
+    const kept = [];
+    for (const group of list) {
+        const inner = group?.hooks;
+        if (!group || typeof group !== 'object' || !Array.isArray(inner)) {
+            kept.push(group);
+            continue;
+        }
+        const rest = inner.filter((e) => !isOurHookEntry(e));
+        if (rest.length === inner.length)
+            kept.push(group); // nothing of ours in here
+        else if (rest.length)
+            kept.push({ ...group, hooks: rest }); // mixed group — keep their half
+    }
+    return kept;
+}
+// read a shared shim file as JSON. Absent → {} (we are about to create it). UNPARSEABLE → throw: the file is
+// the user's, and overwriting prose we cannot read is exactly the data loss this primitive exists to prevent
+// (the harness itself cannot read it either, so the repair is the same one they already need).
+function readSharedShim(file) {
+    if (!existsSync(file))
+        return {};
+    const raw = readFileSync(file, 'utf8');
+    if (!raw.trim())
+        return {};
+    // (re-serialization NORMALIZES the host's formatting — 2-space, one member per line. Their CONTENT all
+    // round-trips; their layout does not, because no JSON writer can reproduce hand-compacted objects. The one
+    // byte-level convention we DO honor is the trailing newline, below.)
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('not a JSON object');
+        return parsed;
+    }
+    catch (e) {
+        throw new Error(`it is not readable JSON (${e.message}). SpexCode co-owns only its own hook entries in this file and will not overwrite content it cannot parse — fix the JSON (your harness cannot read it either), then re-run \`spex materialize\`.`);
+    }
+}
+// does this file end with a newline today? A host file keeps its own convention; a file we are about to
+// create gets the POSIX one. (Absent → true, so a fresh shim is newline-terminated.)
+function trailingNewline(file) {
+    if (!existsSync(file))
+        return true;
+    try {
+        return /\n$/.test(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return true;
+    }
+}
+const hostHooksOf = (host) => {
+    const h = host.hooks;
+    return h && typeof h === 'object' && !Array.isArray(h) ? h : {};
+};
+// MERGE our per-event hook groups into a shared shim file: our previous entries are stripped first (so a
+// changed dispatch path or event set self-heals instead of accumulating), then re-appended AFTER the user's
+// groups for that event. Every other key keeps its value and its position.
+export function writeManagedJsonHooks(file, hooks) {
+    const eol = trailingNewline(file) ? '\n' : '';
+    const host = readSharedShim(file);
+    const merged = {};
+    for (const [event, list] of Object.entries(hostHooksOf(host))) {
+        const kept = stripOurHookGroups(list);
+        if (kept.length)
+            merged[event] = kept;
+    }
+    for (const [event, groups] of Object.entries(hooks))
+        merged[event] = [...(merged[event] ?? []), ...groups];
+    return writeFileIfChanged(file, JSON.stringify({ ...host, hooks: merged }, null, 2) + eol);
+}
+// the INVERSE: strip our entries, leave every other byte of meaning intact. The file is REMOVED only when
+// nothing of the user's remains ({} after our entries go) — the same deleteIfEmpty rule removeManagedBlock
+// applies to a wholly-ours CLAUDE.md, and safe here only because the write half no longer clobbers.
+export function removeManagedJsonHooks(file) {
+    if (!existsSync(file))
+        return;
+    const eol = trailingNewline(file) ? '\n' : '';
+    let host;
+    try {
+        host = readSharedShim(file);
+    }
+    catch {
+        return;
+    } // unparseable → not provably ours, leave it alone
+    const rest = { ...host };
+    const merged = {};
+    for (const [event, list] of Object.entries(hostHooksOf(host))) {
+        const kept = stripOurHookGroups(list);
+        if (kept.length)
+            merged[event] = kept;
+    }
+    if (Object.keys(merged).length)
+        rest.hooks = merged;
+    else
+        delete rest.hooks;
+    if (!Object.keys(rest).length) {
+        rmSync(file, { force: true });
+        return;
+    }
+    writeFileIfChanged(file, JSON.stringify(rest, null, 2) + eol);
+}
+// does anything of the USER's survive in this shared shim file — the JSON analogue of the contract files'
+// host-content test ([[residence]])? Everything except our identity-stamped hook entries counts. This is what
+// decides the file's residence: wholly ours → hidden by the tree's ignore block exactly like any other machine
+// fact; carrying their content → left visible, because hiding a file the user owns is data-loss shaped.
+export function sharedShimHasHostContent(file) {
+    if (!existsSync(file))
+        return false;
+    let host;
+    try {
+        host = readSharedShim(file);
+    }
+    catch {
+        return true;
+    } // unreadable → assume theirs
+    const rest = { ...host };
+    delete rest.hooks;
+    if (Object.keys(rest).length)
+        return true;
+    return Object.values(hostHooksOf(host)).some((list) => stripOurHookGroups(list).length > 0);
+}
+// the identity stamp on every generated skill/agent file. It is what lets BOTH halves of the pass tell our
+// artifact from a same-named file the user wrote: the erase phase refuses to delete an unstamped file, and
+// the write phase refuses to overwrite one ([[harness-delivery]]).
+export const GENERATED_MARK = '<!-- spexcode:generated -->';
+// is this path ours to replace or remove? An absent file is (nothing to lose); a present one only when it
+// carries the stamp. Unreadable → not provably ours.
+export function isGeneratedArtifact(file) {
+    if (!existsSync(file))
+        return true;
+    try {
+        return readFileSync(file, 'utf8').includes(GENERATED_MARK);
+    }
+    catch {
+        return false;
+    }
+}
 // 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.
@@ -2114,7 +2502,9 @@ function buildShim(id, events, dispatch, spex) {
     const hooks = {};
     for (const e of events)
         hooks[e] = [{ hooks: [{ type: 'command', command: cmd(e) }] }];
-    return { content: JSON.stringify({ hooks }, null, 2), cmd };
+    // `content` stays the standalone rendering (what a shim file that is wholly ours would hold); `hooks` is
+    // what the merge writer folds into the user's shared config file. Every buildShim harness is 'shared-json'.
+    return { content: JSON.stringify({ hooks }, null, 2), hooks, cmd };
 }
 // ---------------------------------------------------------------------------------------------------------
 // Codex trust — the codex-rs trusted_hash, reverse-engineered + pinned. Lives in the Codex adapter (it is a
@@ -2168,6 +2558,18 @@ function stripCodexTrustFor(cur, proj, hooksJson) {
     }
     return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '').replace(/\n*$/, '');
 }
+// @@@ assertCodexConfigParses - ~/.codex/config.toml has TWO uncoordinated writers, codex itself and this adapter,
+// and neither rewrite is something the other waits for. A body read mid-write (a line cut short) or one already
+// broken must never be written back: codex refuses the whole file, and every dispatched thread then dies at
+// config load. The check is on the bytes about to land, so stripping this project's own duplicate still heals.
+function assertCodexConfigParses(file, body) {
+    try {
+        parseToml(body);
+    }
+    catch (error) {
+        throw new Error(`refusing to rewrite ${file}: it does not parse as TOML (${error instanceof Error ? error.message : String(error)}); the file is broken or another writer is mid-write — repair it, then rerun`);
+    }
+}
 // 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
@@ -2187,9 +2589,11 @@ export function writeCodexTrust(proj, events, cmdFor) {
     }
     const blk = `# spexcode:trust:${proj} (managed — do not edit)\n${lines.join('\n')}\n# spexcode:trust:end:${proj}`;
     const cleaned = stripCodexTrustFor(existsSync(file) ? readFileSync(file, 'utf8') : '', proj, hooksJson);
+    const next = cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`;
+    assertCodexConfigParses(file, next);
     if (!existsSync(home))
         mkdirSync(home, { recursive: true });
-    writeFileIfChanged(file, cleaned ? `${cleaned}\n\n${blk}\n` : `${blk}\n`);
+    writeFileIfChanged(file, next);
     return file;
 }
 // the inverse of writeCodexTrust: strip THIS project's codex trust from the GLOBAL config.toml — the SAME
@@ -2207,7 +2611,9 @@ function removeCodexTrust(proj) {
         !cur.includes(`# spexcode:trust:${proj} `) && !cur.includes(`# spexcode:trust:end:${proj}`))
         return;
     const cleaned = stripCodexTrustFor(cur, proj, hooksJson);
-    writeFileSync(file, cleaned ? `${cleaned}\n` : '');
+    const next = cleaned ? `${cleaned}\n` : '';
+    assertCodexConfigParses(file, next);
+    writeFileIfChanged(file, next);
 }
 // is this file git-tracked in proj? (guards cleanHarness's deleteIfEmpty; env-stripped git, never throws)
 function isTrackedFile(proj, f) {
@@ -2233,21 +2639,35 @@ function cleanHarness(h, proj, arts, preserveProject = false) {
     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 });
+    // a SHARED config file is un-written entry by entry (and disappears only if nothing of the user's is left);
+    // a file wholly ours goes whole, gated on its own dispatch.sh stamp.
+    if (h.shimScope === 'tree' || !preserveProject) {
+        if (h.shimOwnership === 'shared-json')
+            removeManagedJsonHooks(shim);
+        else if (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);
+    // the name sweep is identity-gated exactly like the stamp sweep: a live spec node named `distill` says
+    // WHICH path to look at, never that the file sitting there is ours. A user's same-named skill (the write
+    // half now refuses to overwrite it) must survive our uninstall.
     const sd = h.skillDir(proj);
+    const stamped = (f) => existsSync(f) && isGeneratedArtifact(f);
     if (sd)
-        for (const n of arts.skills)
-            rmSync(join(sd, n), { recursive: true, force: true });
+        for (const n of arts.skills) {
+            if (stamped(join(sd, n, 'SKILL.md')))
+                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 });
+        for (const n of arts.agents) {
+            if (stamped(join(ad, `${n}.md`)))
+                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
@@ -2412,9 +2832,9 @@ export const claudeHarness = {
     dispatchId: 'claude',
     headless: false,
     events: CLAUDE_EVENTS,
-    ownsRendezvous: true, // reclaude opens the rendezvous control socket (prompt delivery + liveness)
+    ownsRendezvous: true, // claude's background daemon 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,
+    transcript: claudeTranscript,
     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
@@ -2423,6 +2843,7 @@ export const claudeHarness = {
     launchEnv: rendezvousLaunchEnv,
     shimFile: (proj) => join(proj, '.claude', 'settings.json'),
     shimScope: 'tree',
+    shimOwnership: 'shared-json',
     worktreeHookAnchor: () => null, // claude's shim already lives in the worktree (.claude/settings.json) — self-anchors, no root rewrite
     contractFiles: (proj) => [join(proj, 'CLAUDE.md')],
     skillDir: (proj) => join(proj, '.claude', 'skills'),
@@ -2503,7 +2924,13 @@ function codexRuntimeDescriptor(endpoint, runtimeDir) {
             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),
+        probe: (referenceIds) => {
+            // A draining generation keeps serving its bound sessions but is no longer a control-plane candidate.
+            // Listing loaded ids preserves ownership evidence; reading native turn state on that old server only
+            // adds load and can time out while the current generation is healthy.
+            const generation = readCodexGenerationLedger(runtimeDir).generations[endpoint.id];
+            return codexSharedRuntimeProbe(runtimeDir, endpoint, generation?.state === 'draining' ? [] : referenceIds);
+        },
     };
 }
 function codexRuntimeDescriptors(runtimeDir) {
@@ -2525,9 +2952,9 @@ export const codexHarness = {
     headless: false,
     sharedRuntimeSpawn: true,
     events: CODEX_EVENTS,
-    ownsRendezvous: false, // no reclaude daemon — liveness + prompts through the project app-server socket
+    ownsRendezvous: false, // no rendezvous 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,
+    transcript: codexTranscript,
     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
@@ -2543,6 +2970,7 @@ export const codexHarness = {
     // cwd, so one shared shim serves every worktree.
     shimFile: (proj) => join(mainCheckout(proj), '.codex', 'hooks.json'),
     shimScope: 'project',
+    shimOwnership: 'shared-json',
     // 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
@@ -2789,7 +3217,7 @@ const governedSharedRuntimeOwners = (runtimeDir, descriptorKey, threadId, exclud
             continue;
         let parsed;
         try {
-            parsed = JSON.parse(readFileSync(join(root, entry.name, 'session.json'), 'utf8'));
+            parsed = JSON.parse(readFileSync(join(root, entry.name, 'runtime.json'), 'utf8'));
         }
         catch (error) {
             if (error.code === 'ENOENT')
@@ -2825,11 +3253,13 @@ async function codexHeadlessReadinessProof(current) {
         return null;
     const descriptor = codexHeadlessHarness.sharedRuntimes?.(record.runtimeDir)
         .find((candidate) => candidate.key === codexDescriptorKey(endpoint));
-    if (!descriptor?.residency)
+    if (!descriptor)
         return null;
     const generationBefore = codexRuntimeGenerationProof(record.runtimeDir, endpoint);
     if (!generationBefore)
         return null;
+    if (!descriptor.residency)
+        return null;
     let resident;
     try {
         resident = await descriptor.residency();
@@ -2874,9 +3304,15 @@ export const codexHeadlessHarness = {
     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,
+    // A headless thread has no pane to witness it. The shared app-server generation is therefore the adapter's
+    // minimum liveness witness: a stale session record must not keep a dead project runtime online forever. The
+    // session layer adds the one exact loaded-reference census before publishing this reading on the board.
+    liveness: (rec, _tmuxAlive, runtimeDir) => {
+        if (rec.stopped || rec.archived || !rec.harnessSessionId)
+            return 'offline';
+        const endpoint = codexEndpointForRecord(rec, runtimeDir ?? runtimeRoot());
+        return endpoint && codexRuntimeGenerationProof(runtimeDir ?? runtimeRoot(), endpoint) ? 'online' : 'offline';
+    },
     launchReady: async (current, deadline) => {
         for (;;) {
             const proof = await codexHeadlessReadinessProof(current);
@@ -2904,7 +3340,7 @@ export const codexHeadlessHarness = {
 // 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
+// CLAUDE_BG_RENDEZVOUS_SOCK) speaking claude's rendezvous 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
@@ -2914,9 +3350,9 @@ export const piHarness = {
     dispatchId: 'pi',
     headless: false,
     events: PI_EVENTS,
-    ownsRendezvous: true, // the generated extension binds rvSock(id) and speaks the reclaude protocol
+    ownsRendezvous: true, // the generated extension binds rvSock(id) and speaks claude's rendezvous protocol
     paneTitleIsSelfSummary: false, // pi's pane title is not an agent-written task summary → headline uses the prompt preview
-    executionTrace: readSessionJsonlExecutionTrace,
+    transcript: piTranscript,
     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)
@@ -2924,6 +3360,7 @@ export const piHarness = {
     launchEnv: rendezvousLaunchEnv,
     shimFile: (proj) => join(proj, '.pi', 'extensions', 'spexcode.ts'),
     shimScope: 'tree',
+    shimOwnership: 'exclusive',
     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
@@ -2965,6 +3402,8 @@ export const piHeadlessHarness = {
     launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
     liveness: sessionHomeLiveness,
     deliver: deliverViaPiHeadless,
+    // the controller aborts its own turn child natively and confirms only once that child is gone
+    interrupt: interruptPiHeadless,
     cleanupRuntime: (rec) => unlinkSocks(piHeadlessSock(rec.session), rvSock(rec.session)),
     coldRuntime: async (rec) => {
         const result = await piHeadlessColdRuntime(rec);
@@ -2985,7 +3424,7 @@ export const zcodeHarness = {
     events: ZCODE_EVENTS,
     ownsRendezvous: false,
     paneTitleIsSelfSummary: false,
-    executionTrace: noExecutionTrace,
+    transcript: unsupportedTranscript('zcode'),
     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.
@@ -2995,6 +3434,7 @@ export const zcodeHarness = {
     launchEnv: noLaunchEnv,
     shimFile: (proj) => join(proj, '.zcode', 'settings.json'),
     shimScope: 'tree',
+    shimOwnership: 'shared-json',
     worktreeHookAnchor: () => null,
     contractFiles: (proj) => [join(proj, 'AGENTS.md')],
     skillDir: (proj) => join(proj, '.zcode', 'skills'),
@@ -3020,7 +3460,7 @@ export const opencodeHarness = {
     // 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,
+    transcript: opencodeTranscript,
     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.
@@ -3036,6 +3476,7 @@ export const opencodeHarness = {
     // 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',
+    shimOwnership: 'exclusive',
     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'),
@@ -3080,6 +3521,9 @@ export const opencodeHeadlessHarness = {
     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`);
     },
+    // `opencode run` serves the rendezvous socket only for the turn it runs, so the plugin's session abort IS the
+    // interrupt, and the listener going dead is the turn's exit — confirmed only then, so the next delivery wakes cold
+    interrupt: (rec) => interruptViaRendezvous(rec.session, 'opencode-headless', { settle: true }),
 };
 // 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];
@@ -3109,12 +3553,6 @@ export function launcherList(root = mainCheckout()) {
     })
         .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