@spexcode/spec-cli 0.6.6 → 0.6.8

package/dist/harness.js

@@ -20,6 +20,7 @@ import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, pr
 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 { readClaudeTranscript, readCodexTranscript, unsupportedTranscriptReader } from './transcript-reader.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
@@ -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);
@@ -375,8 +413,8 @@ export async function deliverViaSocketOrWake(id, text, mid, coldWake, unprovenEr
 // 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 +428,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 +443,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 +454,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
@@ -556,7 +609,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 +647,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 +692,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 +701,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 +725,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 +740,10 @@ export function codexTurnFailureObserver(rec, onFailure) {
         if (settled)
             return;
         settled = true;
+        if (!readySettled) {
+            readySettled = true;
+            resolveReady(false);
+        }
         clearTimeout(timer);
         cancelReconciliation();
         try {
@@ -685,7 +752,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 +769,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 +793,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 +816,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 +843,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
@@ -1579,7 +1665,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 +1762,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 +1783,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 +1907,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 +1952,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 +2198,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 +2357,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
@@ -2233,21 +2478,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
@@ -2415,6 +2674,7 @@ export const claudeHarness = {
     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,
+    readTranscript: readClaudeTranscript,
     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 +2683,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 +2764,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) {
@@ -2528,6 +2795,7 @@ export const codexHarness = {
     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,
+    readTranscript: readCodexTranscript,
     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 +2811,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 +3058,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')
@@ -2874,9 +3143,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);
@@ -2917,6 +3192,7 @@ export const piHarness = {
     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,
+    readTranscript: (threadId, range) => unsupportedTranscriptReader('pi', threadId, range),
     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 +3200,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
@@ -2986,6 +3263,7 @@ export const zcodeHarness = {
     ownsRendezvous: false,
     paneTitleIsSelfSummary: false,
     executionTrace: noExecutionTrace,
+    readTranscript: (threadId, range) => unsupportedTranscriptReader('zcode', threadId, range),
     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 +3273,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'),
@@ -3021,6 +3300,7 @@ export const opencodeHarness = {
     ownsRendezvous: true,
     paneTitleIsSelfSummary: false, // opencode's TUI title is not the agent's live task self-summary → headline uses the prompt
     executionTrace: readLocalStoreExecutionTrace,
+    readTranscript: (threadId, range) => unsupportedTranscriptReader('opencode', threadId, range),
     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 +3316,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'),