@spexcode/spec-cli 0.6.5 → 0.6.6

package/dist/gateway.js

@@ -178,17 +178,15 @@ export function startGateway(opts) {
     // narrows the public gateway's reach. The gate note keys on LOOPBACK, not on host-being-explicit:
     // an ungated loopback bind is normal, an ungated wide bind is announced — never silent.
     const isLoopback = opts.host === '127.0.0.1' || opts.host === 'localhost' || opts.host === '::1';
-    const onListen = () => {
-        const scheme = secure ? 'https' : 'http';
-        const label = opts.label ?? 'public mode';
-        const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
-        console.log(`[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`);
-        if (!secure && !isLoopback && !opts.host)
-            console.log('[gateway] (TLS off — --http)');
-    };
+    const scheme = secure ? 'https' : 'http';
+    const label = opts.label ?? 'public mode';
+    const gate = isLoopback ? '' : ` — ${gated ? 'password-gated' : 'OPEN (no password)'}`;
+    const ready = [...(opts.readyLines ?? []), `[gateway] ${label} on ${scheme}://${isLoopback ? 'localhost' : (opts.host ?? '0.0.0.0')}:${opts.publicPort}${gate}, proxying /api to :${opts.upstreamPort}`];
+    if (!secure && !isLoopback && !opts.host)
+        ready.push('[gateway] (TLS off — --http)');
     // a busy public port is a hard, loud, non-zero exit — the SAME contract as the supervisor's proxy
     // (see [[spec-cli]] / listen.ts), so `spex serve` and `spex serve ui` fail a port clash identically.
-    listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, onListen });
+    listenOrExit(server, opts.publicPort, { host: opts.host, label: opts.label ?? 'gateway', cleanup: opts.onBindFail, ready });
 }
 // re-serialize an upgrade request's headers for replay against the upstream (exported for the host
 // gateway's per-project WS pipe, which replays the same way).
@@ -223,6 +221,16 @@ function doLogin(req, res, password, setCookie) {
 // and would fight Range requests.
 const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml)|image\/svg)/;
 const wantsGzip = (req) => /\bgzip\b/.test(String(req.headers['accept-encoding'] || ''));
+// zlib's larger default table can be counterproductive for minified text: memLevel 5 both compresses it
+// further and lowers each stream's working memory. One policy drives buffered and streamed gzip.
+const GZIP_OPTIONS = { level: 9, memLevel: 5 };
+function appendVary(current, token) {
+    const values = (Array.isArray(current) ? current : [current ?? ''])
+        .flatMap((value) => value.split(',')).map((value) => value.trim()).filter(Boolean);
+    if (!values.some((value) => value === '*' || value.toLowerCase() === token.toLowerCase()))
+        values.push(token);
+    return values.join(', ');
+}
 // reverse-proxy an /api request to the loopback supervisor (which forwards to the live child) —
 // stream-gzipping compressible bodies (measured: the board JSON rides down at under a third).
 // `path` and `headers` optionally override routing inputs (the host gateway strips its /p/:projectId
@@ -322,16 +330,19 @@ export function proxyHttp(req, res, upstreamPort, path, headers = req.headers, u
         received.once('close', () => { if (!received.complete)
             failFromUpstream(); });
         const type = String(received.headers['content-type'] || '');
-        const skip = !wantsGzip(req) || received.headers['content-encoding'] || !COMPRESSIBLE.test(type) || type.startsWith('text/event-stream');
-        if (skip) {
-            res.writeHead(received.statusCode || 502, received.headers);
+        const eligible = !received.headers['content-encoding'] && COMPRESSIBLE.test(type) && !type.startsWith('text/event-stream');
+        const responseHeaders = eligible
+            ? { ...received.headers, vary: appendVary(received.headers.vary, 'Accept-Encoding') }
+            : received.headers;
+        if (!eligible || !wantsGzip(req)) {
+            res.writeHead(received.statusCode || 502, responseHeaders);
             received.pipe(res);
             return;
         }
-        const headers = { ...received.headers, 'content-encoding': 'gzip', vary: 'Accept-Encoding' };
+        const headers = { ...responseHeaders, 'content-encoding': 'gzip' };
         delete headers['content-length']; // streamed; the encoded length isn't knowable up front
         res.writeHead(received.statusCode || 502, headers);
-        transform = createGzip();
+        transform = createGzip(GZIP_OPTIONS);
         transform.once('error', failFromUpstream);
         received.pipe(transform).pipe(res);
     });
@@ -473,17 +484,21 @@ export function serveStatic(req, res, distDir, urlPath) {
     const type = MIME[extname(file)] || 'application/octet-stream';
     const cacheControl = /[\\/]assets[\\/]/.test(file) ? 'public, max-age=31536000, immutable' : 'no-cache';
     const raw = readFileSync(file);
-    if (wantsGzip(req) && COMPRESSIBLE.test(type)) {
+    const compressible = COMPRESSIBLE.test(type);
+    const headers = { 'Content-Type': type, 'Cache-Control': cacheControl };
+    if (compressible)
+        headers.Vary = appendVary(undefined, 'Accept-Encoding');
+    if (wantsGzip(req) && compressible) {
         const mtime = statSync(file).mtimeMs;
         let hit = gzMemo.get(file);
         if (!hit || hit.mtime !== mtime) {
-            hit = { mtime, gz: gzipSync(raw) };
+            hit = { mtime, gz: gzipSync(raw, GZIP_OPTIONS) };
             gzMemo.set(file, hit);
         }
-        res.writeHead(200, { 'Content-Type': type, 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding', 'Cache-Control': cacheControl });
+        res.writeHead(200, { ...headers, 'Content-Encoding': 'gzip' });
         return res.end(hit.gz);
     }
-    res.writeHead(200, { 'Content-Type': type, 'Cache-Control': cacheControl });
+    res.writeHead(200, headers);
     res.end(raw);
 }
 function sendHtml(res, status, html) {
@@ -498,6 +513,15 @@ function sendHtml(res, status, html) {
 // installed user has no source tree for). See [[packaging]].
 export function serveDashboardLocal(opts) {
     const distDir = resolveDistDir();
-    console.log(`[dashboard] serving ${distDir}, /api → backend :${opts.apiPort}`);
-    startGateway({ host: opts.host ?? '127.0.0.1', publicPort: opts.port, upstreamPort: opts.apiPort, password: '', tls: null, distDir, label: 'dashboard', projectRoot: opts.projectRoot });
+    startGateway({
+        host: opts.host ?? '127.0.0.1',
+        publicPort: opts.port,
+        upstreamPort: opts.apiPort,
+        password: '',
+        tls: null,
+        distDir,
+        label: 'dashboard',
+        projectRoot: opts.projectRoot,
+        readyLines: [`[dashboard] serving ${distDir}, /api → backend :${opts.apiPort}`],
+    });
 }

package/dist/graphCache.js

@@ -3,7 +3,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { rebasePublishedSessions } from '@spexcode/spec-core';
 import { buildBoard, spliceSessions } from './graphSnapshot.js';
-import { headSha, repoRoot, withGitAbortSignal } from '@spexcode/spec-core';
+import { headSha, repoRoot, requireGitWorkspace, withGitAbortSignal } from '@spexcode/spec-core';
 import { listSessionIds, mainBranch, mainCheckout, readPublicRecordEntry, sessionArtifactPath, sessionRecordPath } from '@spexcode/spec-core';
 import { boardThreads } from './issues.js';
 import { resolveForgeHost } from '@spexcode/spec-forge/drivers';
@@ -162,6 +162,7 @@ function sessionInputRevision() {
 }
 function boardInputRevision(board) {
     const root = repoRoot();
+    requireGitWorkspace(root);
     const session = sessionInputRevision();
     // Durable active records are the current root set; a cached ordinary row may be stale and must not replace
     // them. The one projection-only addition is explicit: listSessions republishes an archived-runtime hazard

package/dist/graphSnapshot.js

@@ -1,4 +1,4 @@
-import { loadSpecs } from '@spexcode/spec-core';
+import { loadSpecs, requireGitWorkspace } from '@spexcode/spec-core';
 import { resolveLayout } from '@spexcode/spec-core';
 import { listSessions } from './sessions.js';
 import { driftIndex, historyIndex, repoRoot } from '@spexcode/spec-core';
@@ -12,6 +12,7 @@ import { sessionEvalProjections } from '@spexcode/spec-eval/sessioneval';
 // The application adapter is the sole reader of runtime/forge state. graph.ts only receives this result.
 export async function boardSnapshot() {
     const root = repoRoot();
+    requireGitWorkspace(root);
     const [specs, sessions] = await Promise.all([loadSpecs(), listSessions()]);
     const layout = await resolveLayout({ activeSessionIds: sessions.map((session) => session.id) });
     const nodeIds = [...new Set([

package/dist/harness.d.ts

@@ -24,6 +24,14 @@ export type FailureSubscription = {
     close(): void;
     readonly closed: Promise<string | null>;
 };
+export type DeliveryTransportState = {
+    kind: 'reachable';
+} | {
+    kind: 'unproven';
+} | {
+    kind: 'unreachable';
+    reason: string;
+};
 export type ProcTable = Map<number, {
     ppid: number;
     comm: string;
@@ -137,10 +145,12 @@ export interface Harness {
     slashCommands(): SlashCommand[];
     liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline';
     launchReady?(current: () => HarnessLaunchReadyRecord | null, deadline: number): Promise<HarnessLaunchReadinessFence | null>;
-    leafOwnerNeedle?(rec: HarnessLivenessRecord & {
+    launchPayloadProof?: true;
+    exactNativeTargetId(rec: HarnessLivenessRecord & {
         harnessSessionId?: string | null;
     }): string | null;
     deliver(rec: HarnessDeliveryRecord, text: string): Promise<DispatchResult>;
+    deliveryTransport?(rec: HarnessDeliveryRecord): Promise<DeliveryTransportState>;
     observeTurnFailures?(rec: HarnessDeliveryRecord, onFailure: (failure: TurnFailure) => void): FailureSubscription;
     interrupt?(rec: HarnessDeliveryRecord): Promise<DispatchResult>;
     cleanupRuntime(rec: HarnessLivenessRecord): Promise<void>;
@@ -185,7 +195,7 @@ export interface Harness {
     resumeArg(rec: {
         session: string;
         harnessSessionId?: string | null;
-    }): string;
+    }, pendingLaunchPayload?: string | null): string;
 }
 export type DispatchResult = {
     ok: boolean;
@@ -193,6 +203,8 @@ export type DispatchResult = {
 };
 export type HarnessDeliveryRecord = {
     session: string;
+    stopped?: boolean;
+    archived?: boolean;
     worktreePath?: string;
     harnessSessionId?: string | null;
     runtimeDir?: string;
@@ -205,6 +217,7 @@ export type HarnessArtifacts = {
 };
 export declare const legacyRvSock: (id: string) => string;
 export declare const scopedRvSock: (id: string, dir?: string) => string;
+export declare function assertRvSockPath(id: string, dir?: string): string;
 export declare const rvSock: (id: string) => string;
 export declare function stampRvSock(id: string, dir?: string): string;
 export type ListenerProbe = 'live' | 'dead' | 'unproven';

package/dist/harness.js

@@ -1,4 +1,4 @@
-import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { closeSync, openSync, readSync, writeFileSync, readFileSync, existsSync, mkdirSync, rmSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
@@ -9,11 +9,11 @@ import { fileURLToPath } from 'node:url';
 import { claudeSlashCommands, codexSlashCommands, opencodeSlashCommands, piSlashCommands } from './slash-commands.js';
 import { OPENCODE_EVENTS, opencodePluginSource } from './opencode.js';
 import { piExtensionSource, writePiTrust, removePiTrust } from './pi-harness.js';
-import { claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
+import { claudeHeadlessColdRuntime, claudeHeadlessLaunchCommand, claudeHeadlessSock, deliverViaClaudeHeadless, interruptClaudeHeadless } from './claude-headless.js';
 import { codexHeadlessLaunchCommand } from './codex-headless.js';
-import { opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
+import { opencodeHeadlessColdRuntime, opencodeHeadlessLaunchCommand, spawnOpenCodeHeadlessTurn } from './opencode-headless.js';
 import { piHeadlessLaunchCommand, piHeadlessSock, deliverViaPiHeadless, piHeadlessColdRuntime } from './pi-headless.js';
-import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath } from '@spexcode/spec-core';
+import { 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';
@@ -67,9 +67,9 @@ export async function adapterLoadedReferenceState(records, runtimeDir = runtimeR
 // sessions.ts starts `claude` with CLAUDE_BG_BACKEND=daemon + CLAUDE_BG_RENDEZVOUS_SOCK=<this path> set ONLY on
 // that one spawned command (env prefix, never global). claude opens a unix socket here; writing one line
 // `{"type":"reply","text":"…"}\n` injects + submits the text as a prompt — no PTY typing, so multi-line input
-// and Enters can't be corrupted the way `tmux send-keys` was. It lives in tmpdir tied to the claude process, so
-// no extra lifecycle. liveness CONNECTS to it (a live LISTENER, not merely the file — see rendezvousListening);
-// deliver writes to it.
+// and Enters can't be corrupted the way `tmux send-keys` was. It lives in SpexCode's own durable store, and
+// its launch-time stamp still gives it no independent lifecycle. liveness CONNECTS to it (a live LISTENER, not
+// merely the file — see rendezvousListening); deliver writes to it.
 //
 // The path is a LAUNCH-TIME FACT, recorded — not a formula every consumer re-derives. The id alone was not
 // enough to name it: `SPEXCODE_HOME` scopes the store and `SPEXCODE_TMUX` scopes the tmux server, so two
@@ -83,18 +83,22 @@ export async function adapterLoadedReferenceState(records, runtimeDir = runtimeR
 // `legacyRvSock` is the answer for a session launched BEFORE the stamp existed — its agent really did bind
 // the unscoped path — so those keep working untouched, and the fallback retires as they turn over.
 export const legacyRvSock = (id) => join(tmpdir(), `spexcode-rv-${id}.sock`);
-// @@@ rendezvousSocketBase - macOS's TMPDIR commonly expands to /var/folders/<long-user-path>, leaving a
-// UUID-scoped socket beyond its 104-byte sun_path limit. It can be created and observed by pathname but every
-// connect fails EINVAL, which looks exactly like an unresponsive worker. Use a literal short /tmp spelling
-// (not tmpdir(), whose resolved form is long on macOS) with the same private per-uid directory pattern as the
-// Codex runtime socket. Existing launches retain their stamped old path through rvSock(); only new launches use
-// this base.
-const rendezvousSocketBase = () => {
-    const base = join('/tmp', `spexcode-rv-${process.getuid?.() ?? 0}`);
-    mkdirSync(base, { recursive: true, mode: 0o700 });
-    return base;
-};
-export const scopedRvSock = (id, dir = runtimeRoot()) => join(rendezvousSocketBase(), `spexcode-rv-${createHash('sha1').update(dir).digest('hex').slice(0, 12)}-${id}.sock`);
+// @@@ scoped rendezvous path - a rendezvous endpoint IS this session's address, so it needs a durable home and
+// a bounded name. `<SPEXCODE_HOME>/s/<16hex>/c` is both: the store is SpexCode-owned (normally ~/.spexcode),
+// while one fixed digest of runtime scope + session identity gives every world/session its own short directory
+// without carrying either raw value in the pathname. This is deliberately NOT the Codex app-server rule: that
+// endpoint routes project-shared threads; this one names a session-owned listener. Existing launches retain
+// their stamped old path through rvSock(); only a new stamp uses this derivation.
+const RENDEZVOUS_SUN_PATH_LIMIT = 104;
+export const scopedRvSock = (id, dir = runtimeRoot()) => join(spexcodeHome(), 's', createHash('sha1').update(`${dir}\0${id}`).digest('hex').slice(0, 16), 'c');
+export function assertRvSockPath(id, dir = runtimeRoot()) {
+    const path = scopedRvSock(id, dir);
+    const bytes = Buffer.byteLength(path);
+    if (bytes >= RENDEZVOUS_SUN_PATH_LIMIT) {
+        throw new Error(`rendezvous socket path is ${bytes} bytes (must be < ${RENDEZVOUS_SUN_PATH_LIMIT}): ${path}; shorten SPEXCODE_HOME before creating this session`);
+    }
+    return path;
+}
 const rvStamp = (id) => sessionArtifactPath(id, 'rv.path');
 export const rvSock = (id) => {
     try {
@@ -107,7 +111,8 @@ export const rvSock = (id) => {
 // launch's half: derive this session's socket in ITS runtime and record it, so every later reader (launch env,
 // liveness probe, delivery, teardown) reads the one path the agent actually bound.
 export function stampRvSock(id, dir = runtimeRoot()) {
-    const path = scopedRvSock(id, dir);
+    const path = assertRvSockPath(id, dir);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     mkdirSync(dirname(rvStamp(id)), { recursive: true });
     writeFileSync(rvStamp(id), path);
     return path;
@@ -140,6 +145,15 @@ export function listenerAt(path, timeoutMs = 800) {
     });
 }
 export const rendezvousListening = (id, timeoutMs = 800) => listenerAt(rvSock(id), timeoutMs);
+const rendezvousDeliveryTransportAt = async (path) => {
+    const probe = await listenerAt(path);
+    if (probe === 'live')
+        return { kind: 'reachable' };
+    if (probe === 'unproven')
+        return { kind: 'unproven' };
+    return { kind: 'unreachable', reason: 'its launch-time rendezvous listener is absent or refusing connections' };
+};
+const rendezvousDeliveryTransport = (rec) => rendezvousDeliveryTransportAt(rvSock(rec.session));
 // The app-server Unix socket MUST live on a SHORT, sun_path-safe path — NOT nested under the project runtime
 // dir. macOS caps `sun_path` at ~104 bytes, and `runtimeRoot()` flattens the ENTIRE project path into one
 // dash-segment (`encodeProject`), so `<runtimeRoot>/codex-app-server.sock` blew past the cap on a deep macOS
@@ -277,6 +291,17 @@ function claudeForkTransport(sourceSessionId, runtimeDir) {
     }
     return null;
 }
+async function claudeDeliveryTransport(rec) {
+    const fork = claudeForkTransport(rec.session, rec.runtimeDir);
+    if (!fork)
+        return rendezvousDeliveryTransport(rec);
+    const forkState = await rendezvousDeliveryTransportAt(fork.sock);
+    if (forkState.kind !== 'unreachable' || fork.sock === rvSock(rec.session))
+        return forkState;
+    // A stale roster row must not strand a source worker whose stamped launch transport is still reachable.
+    return rendezvousDeliveryTransport(rec);
+}
+const unprovenDeliveryTransport = async () => ({ kind: 'unproven' });
 function replyViaSocket(sock, text, mid, auth) {
     return new Promise((resolve) => {
         let settled = false;
@@ -505,8 +530,8 @@ export function codexLaunchCommand(id, codexCmd = 'codex', serverCmd, dir = runt
         // TWO launch modes, on ONE tail channel ("$@"). reopen() hands a `--resume <thread-id>` tail (see
         // codexHarness.resumeArg) to bring the SAME conversation back: resume that OWNED thread DIRECTLY — no new
         // thread, no first-turn prompt. ANY other tail is a NEW launch: BACKEND owns the thread — `codex-launch`
-        // does thread/start { cwd = this worktree } on the shared per-project app-server, stores the new id on the
-        // governed record (SPEXCODE_SESSION_ID), and fires the tail as the FIRST turn, materializing the rollout.
+        // does thread/start { cwd = this worktree } on the shared per-project app-server, fires the tail as the
+        // FIRST turn, materializes the rollout, and stages the new id + payload proof for the lifecycle owner.
         // Either way it ends with a thread id, which the visible TUI then RESUMES (the rollout persists on disk),
         // rendering it natively. A new launch's tail is always ONE single-quoted prompt arg, so it can never be the
         // literal "--resume" marker — the discriminator is unambiguous. codex-launch only prints an id once its
@@ -1290,8 +1315,15 @@ async function codexColdPreflightOnce(threadId, dir = runtimeRoot(), expectedGen
         const presence = codexPresenceFromStatus(statusById.get(id));
         if (presence === 'active')
             return { ok: false, reason: `Codex subtree member ${id} has an active turn` };
-        if (presence === 'unknown')
-            return { ok: false, reason: `Codex subtree member ${id} turn state is unknown` };
+        if (presence === 'unknown') {
+            const rollout = codexRolloutTurnSettlement(id);
+            if (!rollout.settled) {
+                return {
+                    ok: false,
+                    reason: `Codex subtree member ${id} turn state is unknown: live Codex client did not report a determinate turn state; ${rollout.reason}`,
+                };
+            }
+        }
         if (archivedSet.has(id))
             return { ok: false, reason: `Codex archived subtree member ${id} remains loaded` };
     }
@@ -1329,17 +1361,49 @@ async function codexColdPreflight(threadId, dir = runtimeRoot(), expectedGenerat
     }
     throw new Error('unreachable Codex cold preflight retry state');
 }
+// A corrupt record has no binding we can trust. Locate its one materialized native thread before cold proof;
+// choosing current or legacy would redirect a destructive operation across a generation boundary.
+async function codexEndpointForOrphanThread(threadId, dir = runtimeRoot()) {
+    const tracked = codexGenerationEndpoints(dir);
+    const endpoints = tracked.length ? tracked : [legacyCodexGenerationEndpoint(dir)];
+    const scans = await Promise.all(endpoints.map(async (endpoint) => {
+        const generation = codexMutationGeneration(dir, endpoint);
+        if (!generation)
+            return { endpoint, reason: 'Codex shared app-server generation is unproven' };
+        const [active, archived] = await Promise.all([
+            codexThreadList(endpoint.socketPath, { archived: false, sourceKinds: [] }),
+            codexThreadList(endpoint.socketPath, { archived: true, sourceKinds: [] }),
+        ]);
+        if (codexRuntimeGeneration(dir, endpoint) !== generation)
+            return { endpoint, reason: 'Codex shared app-server generation changed during orphan location' };
+        if (!active.ok)
+            return { endpoint, reason: active.error };
+        if (!archived.ok)
+            return { endpoint, reason: archived.error };
+        return { endpoint, generation, containsTarget: active.ids.includes(threadId) || archived.ids.includes(threadId) };
+    }));
+    const failed = scans.find((scan) => 'reason' in scan);
+    if (failed)
+        return { ok: false, reason: `${failed.reason} while locating orphan Codex thread ${threadId} on generation ${failed.endpoint.id}` };
+    const matches = scans.filter((scan) => 'containsTarget' in scan && scan.containsTarget);
+    if (matches.length !== 1) {
+        const detail = matches.length ? matches.map((scan) => scan.endpoint.id).join(', ') : 'none';
+        return { ok: false, reason: `Codex orphan thread ${threadId} has ${matches.length === 0 ? 'no materialized' : 'ambiguous'} generation location (${detail})` };
+    }
+    return { ok: true, endpoint: matches[0].endpoint, generation: matches[0].generation };
+}
 async function codexQuarantineOrphanThread(threadId, opts) {
     const dir = runtimeRoot();
-    const generation = codexMutationGeneration(dir);
-    if (!generation)
-        return { ok: false, reason: 'Codex shared app-server generation is unproven' };
     const owners = governedSharedRuntimeOwners(dir, 'codex-app-server', threadId, opts.excludingSessionId);
     if (owners === null)
         return { ok: false, reason: 'governed Codex thread-owner census is unreadable' };
     if (owners.length)
         return { ok: false, reason: `Codex native thread ${threadId} has governed owner(s) ${owners.join(', ')}` };
-    const before = await codexColdPreflight(threadId, dir, generation);
+    const location = await codexEndpointForOrphanThread(threadId, dir);
+    if (!location.ok)
+        return location;
+    const { endpoint, generation } = location;
+    const before = await codexColdPreflight(threadId, dir, generation, endpoint);
     if (!before.ok)
         return before;
     const plan = before.receipt;
@@ -1362,7 +1426,6 @@ async function codexQuarantineOrphanThread(threadId, opts) {
     if (plan.activeIds.length !== 1 || plan.activeIds[0] !== threadId || plan.archivedIds.length)
         return { ok: false, reason: `Codex native thread ${threadId} is not one exact active orphan` };
     const siblingIds = plan.guard.referenceIds.filter((id) => id !== threadId);
-    const legacy = legacyCodexGenerationEndpoint(dir);
     // Quarantine archives one exact orphan, so it pays the same flush a subtree member does when that orphan is
     // loaded; the budget is derived the same way rather than being a second, differently-wrong constant.
     let orphanBudgetMs = CODEX_MUTATION_BASE_MS;
@@ -1372,10 +1435,10 @@ async function codexQuarantineOrphanThread(threadId, opts) {
             return { ok: false, reason: `Codex native thread ${threadId} is loaded and its rollout exists but cannot be measured, so the archive flush budget is unknown` };
         orphanBudgetMs = codexArchiveBudgetMs(rollout.bytes);
     }
-    const archived = await codexThreadMutation(legacy.socketPath, 'thread/archive', threadId, { dir, endpoint: legacy, generation }, undefined, orphanBudgetMs);
+    const archived = await codexThreadMutation(endpoint.socketPath, 'thread/archive', threadId, { dir, endpoint, generation }, undefined, orphanBudgetMs);
     if (!archived.ok)
         return { ok: false, reason: `${archived.error} while archiving orphan Codex thread ${threadId}${archived.commit === 'unknown' ? '; commit state is unknown' : ''}` };
-    const after = await codexColdPreflight(threadId, dir, generation);
+    const after = await codexColdPreflight(threadId, dir, generation, endpoint);
     const failed = (reason) => ({ ok: false, reason });
     if (!after.ok) {
         const restored = await rollback();
@@ -1917,6 +1980,45 @@ export function codexRolloutBytes(threadId, root) {
     }
     return { bytes: 0 };
 }
+const CODEX_ROLLOUT_TAIL_BYTES = 64 * 1024;
+const CODEX_ROLLOUT_TERMINAL_EVENTS = new Set(['task_complete', 'task_completed', 'turn_complete', 'turn_completed']);
+function codexRolloutTurnSettlement(threadId, root) {
+    const path = codexRolloutPath(threadId, root);
+    if (!path)
+        return { settled: false, reason: 'rollout is missing' };
+    let fd = null;
+    try {
+        const size = statSync(path).size;
+        if (size === 0)
+            return { settled: false, reason: 'rollout has no terminal record' };
+        const length = Math.min(size, CODEX_ROLLOUT_TAIL_BYTES);
+        const tail = Buffer.allocUnsafe(length);
+        fd = openSync(path, 'r');
+        if (readSync(fd, tail, 0, length, size - length) !== length)
+            return { settled: false, reason: 'rollout tail is unreadable' };
+        const line = tail.toString('utf8').split('\n').reverse().find((value) => value.trim());
+        if (!line)
+            return { settled: false, reason: 'rollout has no terminal record' };
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return { settled: false, reason: 'rollout tail is incomplete or malformed' };
+        }
+        const payload = event && typeof event === 'object' ? event.payload : null;
+        const terminal = event && typeof event === 'object' && event.type === 'event_msg' &&
+            payload && typeof payload === 'object' && CODEX_ROLLOUT_TERMINAL_EVENTS.has(String(payload.type || ''));
+        return terminal ? { settled: true } : { settled: false, reason: 'rollout has no terminal record' };
+    }
+    catch {
+        return { settled: false, reason: 'rollout tail is unreadable' };
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
 // poll until the thread's rollout lands (resume-ready) or the budget runs out. Returns false on timeout so the
 // caller can FAIL LOUD instead of handing `resume` / the stored record a non-resumable id. The budget must
 // exceed launch.sh's fast-fail threshold so a genuine failure exits PAST it — the retry loop then treats it as a
@@ -2262,6 +2364,7 @@ const socketListenerLiveness = (_rec, tmuxAlive, _runtimeDir, _pane, socketLive)
 const socketListenerOrPidAliveLiveness = (_rec, tmuxAlive, _runtimeDir, pane, socketLive) => (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline');
 const panePidLiveness = (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && pane?.pidAlive === true ? 'online' : 'offline');
 const recordOnline = (rec) => rec.stopped ? 'offline' : 'online';
+const sessionHomeLiveness = (_rec, tmuxAlive) => tmuxAlive ? 'online' : 'offline';
 // @@@ unlinkSocks - remove ONLY the transport this teardown PROVED dead. `cleanupRuntime` unlinks *their*
 // socket, and the honest test of "theirs" is that the agent it just killed is GONE. It used to unlink on
 // faith, which is unsound because a socket path is derived from the session id ALONE: it is the one
@@ -2333,7 +2436,8 @@ export const claudeHarness = {
     // the caller) — NOT the mere existence of a stale socket FILE a crashed claude leaves behind (the 30-min
     // dead-pane-reads-working bug). See rendezvousListening.
     liveness: socketListenerLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: (rec) => rec.session,
+    deliveryTransport: claudeDeliveryTransport,
     deliver: (rec, text) => deliverViaClaudeRendezvous(rec.session, text, rec.mid, rec.runtimeDir),
     cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
     coldRuntime: async () => ({ ok: true }),
@@ -2359,18 +2463,20 @@ export const claudeHeadlessHarness = {
     id: 'claude-headless',
     sessionEnvVar: harnessIdentity('claude-headless').sessionEnvVar,
     headless: true,
-    runtimeOwnership: 'adapter',
+    runtimeOwnership: 'leaf',
     ownsRendezvous: false,
     paneTitleIsSelfSummary: false,
     launchCmd: (id, runtimeDir, cmd) => claudeHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), claudeBaseCmd(cmd)),
     launchEnv: noLaunchEnv,
-    // Liveness is the intact, non-stopped record's property. A missing controller/child fails loudly at control
-    // time rather than turning an idle (no child) session into a speculative offline row.
-    liveness: recordOnline,
+    liveness: sessionHomeLiveness,
+    deliveryTransport: unprovenDeliveryTransport,
     deliver: deliverViaClaudeHeadless,
     interrupt: interruptClaudeHeadless,
     cleanupRuntime: (rec) => unlinkSocks(claudeHeadlessSock(rec.session)),
-    coldRuntime: async () => ({ ok: false, reason: 'claude-headless has no exact resident unload verification' }),
+    coldRuntime: async (rec) => {
+        const result = await claudeHeadlessColdRuntime(rec);
+        return result.ok ? { ok: true } : { ok: false, reason: result.error || 'claude-headless runtime remains unproven' };
+    },
     deliveryBlockedBy: undefined,
 };
 function codexRuntimeDescriptor(endpoint, runtimeDir) {
@@ -2405,8 +2511,16 @@ function codexRuntimeDescriptors(runtimeDir) {
     return (endpoints.length ? endpoints : [legacyCodexGenerationEndpoint(runtimeDir)])
         .map((endpoint) => codexRuntimeDescriptor(endpoint, runtimeDir));
 }
+function codexResumeArg(rec, pendingLaunchPayload) {
+    if (rec.harnessSessionId)
+        return `--resume ${rec.harnessSessionId}`;
+    if (pendingLaunchPayload == null)
+        throw new Error(`session ${rec.session}: native identity is absent and the authoritative resolved launch payload is missing; refusing to create an empty thread`);
+    return shQuote(pendingLaunchPayload);
+}
 export const codexHarness = {
     id: 'codex',
+    launchPayloadProof: true,
     dispatchId: 'codex',
     headless: false,
     sharedRuntimeSpawn: true,
@@ -2477,7 +2591,7 @@ export const codexHarness = {
             return pane.pidAlive ? 'online' : 'offline';
         return paneTreeRunsCodex(pane) ? 'online' : 'offline';
     },
-    leafOwnerNeedle: (rec) => rec.harnessSessionId ?? null,
+    exactNativeTargetId: (rec) => rec.harnessSessionId || null,
     deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
     observeTurnFailures: codexTurnFailureObserver,
     interrupt: interruptCodexTurn,
@@ -2641,8 +2755,8 @@ export const codexHarness = {
     sharedRuntimes: codexRuntimeDescriptors,
     // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
     // a tail handed to a bare `codex` — the script's final `codex … resume "$tid"` performs codex's own resume on
-    // the owned id, the SAME conversation); none → empty tail → relaunch a FRESH thread on the same worktree/record.
-    resumeArg: (rec) => (rec.harnessSessionId ? `--resume ${rec.harnessSessionId}` : ''),
+    // the owned id, the SAME conversation); no identity → replay the authoritative resolved launch payload.
+    resumeArg: codexResumeArg,
     // codex's own settled failure: a thread id whose rollout is not on disk can never be resumed, so the launch
     // that says so has already decided. (Its transient sibling — the rollout still being written — is handled
     // BEFORE launch by waitForCodexRollout, so what reaches here is the permanent case.)
@@ -2754,6 +2868,7 @@ async function codexHeadlessReadinessProof(current) {
 export const codexHeadlessHarness = {
     ...codexHarness,
     id: 'codex-headless',
+    launchPayloadProof: true,
     sessionEnvVar: harnessIdentity('codex-headless').sessionEnvVar,
     headless: true,
     runtimeOwnership: 'adapter',
@@ -2779,9 +2894,9 @@ export const codexHeadlessHarness = {
             await new Promise((resolve) => setTimeout(resolve, Math.min(200, remaining)));
         }
     },
-    // There is no TUI to restart and the project app-server keeps the thread addressable. A forced reopen therefore
-    // runs the headless launch's empty-tail no-op; normal resume remains guarded by record-backed online liveness.
-    resumeArg: () => '',
+    // There is no TUI to restart and the project app-server keeps an identified thread addressable. A pre-identity
+    // recovery still replays the authoritative resolved launch payload through codex-launch.
+    resumeArg: codexResumeArg,
 };
 // @@@ piHarness - the pi adapter (@earendil-works/pi-coding-agent). pi is the CLOSEST to claude of the four:
 // the caller pins the session id at launch (`--session-id <id>`, creating the session if missing), the shim
@@ -2824,7 +2939,8 @@ export const piHarness = {
     // claude's exact liveness: the window is up AND a live LISTENER answers on the rendezvous socket — the
     // socket the generated extension binds. socketLive is already probed for every windowed session.
     liveness: socketListenerLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: (rec) => rec.session,
+    deliveryTransport: rendezvousDeliveryTransport,
     deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
     cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
     coldRuntime: async () => ({ ok: true }),
@@ -2835,18 +2951,19 @@ export const piHarness = {
 // pi-headless is an independent harness: its materialization surface is literally pi's, while a resident
 // controller owns non-interactive text-mode turns. Active turns steer through pi's rendezvous extension;
 // idle delivery cold-wakes the exact saved session with `--session` (never `--session-id`, which would create a
-// new conversation). The controller deliberately reports record-backed liveness, matching Claude headless.
+// new conversation). The exact tmux home is its public addressability and physical-cold boundary.
 export const piHeadlessHarness = {
     ...piHarness,
     id: 'pi-headless',
     sessionEnvVar: harnessIdentity('pi-headless').sessionEnvVar,
     headless: true,
+    deliveryTransport: unprovenDeliveryTransport,
     // The controller is a per-session process launched in the target tmux pane. Its launch-registered PID
-    // and argv session id are exact leaf ownership evidence; record-backed liveness does not make it shared.
+    // and argv session id are exact leaf ownership evidence.
     runtimeOwnership: 'leaf',
     paneTitleIsSelfSummary: false,
     launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
-    liveness: recordOnline,
+    liveness: sessionHomeLiveness,
     deliver: deliverViaPiHeadless,
     cleanupRuntime: (rec) => unlinkSocks(piHeadlessSock(rec.session), rvSock(rec.session)),
     coldRuntime: async (rec) => {
@@ -2888,7 +3005,7 @@ export const zcodeHarness = {
     clean(proj, arts, preserveProject) { cleanHarness(this, proj, arts, preserveProject); },
     slashCommands: () => [],
     liveness: panePidLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: () => null,
     deliver: async () => { throw new Error(ZCODE_CONTROL_UNAVAILABLE); },
     cleanupRuntime: async () => { },
     coldRuntime: async () => ({ ok: true }),
@@ -2934,7 +3051,8 @@ export const opencodeHarness = {
     // (the plugin is alive), FALL BACK to the launch-registered agent.pid (kill-0) so a plugin that failed to
     // load still reads honestly from the process signal instead of a false offline.
     liveness: socketListenerOrPidAliveLiveness,
-    leafOwnerNeedle: (rec) => rec.session,
+    exactNativeTargetId: (rec) => rec.harnessSessionId || null,
+    deliveryTransport: rendezvousDeliveryTransport,
     deliver: (rec, text) => deliverViaRendezvous(rec.session, text, rec.mid),
     cleanupRuntime: (rec) => unlinkSocks(rvSock(rec.session)),
     coldRuntime: async () => ({ ok: true }),
@@ -2951,12 +3069,14 @@ export const opencodeHeadlessHarness = {
     id: 'opencode-headless',
     sessionEnvVar: harnessIdentity('opencode-headless').sessionEnvVar,
     headless: true,
-    runtimeOwnership: 'adapter',
+    runtimeOwnership: 'leaf',
+    deliveryTransport: unprovenDeliveryTransport,
     launchCmd: (_id, _runtimeDir, cmd) => opencodeHeadlessLaunchCommand(opencodeBaseCmd(cmd)),
-    // A sleeping native conversation is still addressable by its non-stopped record. Transport breakage belongs
-    // to the next delivery, where the live rendezvous or pane wake reports it loudly.
-    liveness: recordOnline,
-    coldRuntime: async () => ({ ok: false, reason: 'opencode-headless has no exact resident unload verification' }),
+    liveness: sessionHomeLiveness,
+    coldRuntime: async (rec) => {
+        const result = await opencodeHeadlessColdRuntime(rec);
+        return result.ok ? { ok: true } : { ok: false, reason: result.error || 'opencode-headless runtime remains unproven' };
+    },
     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`);
     },