spexcode 0.6.2 → 0.6.6

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

@@ -0,0 +1,4667 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, appendFileSync, existsSync, renameSync, linkSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync, unlinkSync } from 'node:fs';
+import { join, dirname, isAbsolute, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { seedWorktreeHostState } from './worktree-sources.js';
+import { git, gitA, gitTry, repoRoot, mergeBaseDiff, mergeConflicts, withGitAbortSignal, isGitObjectId } from '@spexcode/spec-core';
+import { loadConfig, loadSpecs, loadSpecsLite } from '@spexcode/spec-core';
+import { adapterLoadedReferenceState, assertRvSockPath, defaultHarness, HARNESSES, sessionIdentityEnvVars, defaultLauncher, harnessById, procSnapshot, resolveLauncher, rendezvousListening, stampRvSock } from './harness.js';
+import { materialize } from './materialize.js';
+import { mainBranch, mainRoot, gitCommonDir, readConfig, runtimeRoot, treeSlotDir, sessionStoreDir, sessionRecordPath, sessionArtifactPath, listSessionIds, rawLaunchReadinessOriginal, readRecordEntry, readAliasedRecordEntry, readPublicRecordEntry, envSessionId, isSessionLifecycle, isSessionProposal } from '@spexcode/spec-core';
+import { readSessionFiles } from './session-files.js';
+import { readSessionWebs } from './session-web.js';
+import { acceptMessage, drain, recordStatus, lastHumanSendVia, owesDelivery, pendingMessages } from '@spexcode/session-core';
+import { pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, withDeliveryLocks, trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLockSync as coreWithSessionRecordLockSync } from '@spexcode/session-core/internal';
+import { stripRefSigil } from './mentions.js';
+import { shQuote } from './sh.js';
+import { assertSessionOwnerSafe, assertSessionStopSafe, ResourceConflict } from './host-resources.js';
+import { processStartToken } from '@spexcode/spec-core';
+import { bindCodexGeneration, codexGenerationBindingForSession, commitCodexGenerationRegistration, prepareCodexGenerationClose, prepareCodexGenerationRegistration, readCodexGenerationLedger } from './codex-runtime-generations.js';
+import { cliEntrypointArgs } from './tsx-bin.js';
+const pexec = promisify(execFile);
+export const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode';
+const DEFER_FOOTPRINT_REFRESH = { SPEXCODE_DEFER_FOOTPRINT_REFRESH: 'session-create' };
+const HARNESS = defaultHarness;
+const COLS = 120, ROWS = 32;
+const DEFAULT_MAX_ACTIVE = 8;
+function maxActive() {
+    let v;
+    try {
+        const fromJson = readConfig(mainRoot()).sessions?.maxActive;
+        if (typeof fromJson === 'number' && Number.isFinite(fromJson))
+            v = fromJson;
+    }
+    catch { /* config unreadable — fall through to env/default */ }
+    if (v === undefined) {
+        const e = Number(process.env.SPEXCODE_MAX_ACTIVE);
+        if (Number.isFinite(e) && e > 0)
+            v = e;
+    }
+    return Math.max(1, Math.floor(v ?? DEFAULT_MAX_ACTIVE));
+}
+// The adapter owns any transport bootstrap env (rendezvous daemon + socket); product launch only composes it
+// with the governed session id and home vars. This env prefix also ensures hooks + materialize write to the
+// SAME store the backend uses. SPEXCODE_HOME/CODEX_HOME are
+// propagated when set, because the session inherits the tmux SERVER's env (not the backend's), so without this
+// an overridden home would silently leak the session's hook-state + codex-trust to the default ~/.spexcode /
+// ~/.codex. Deterministic: the session's store = the backend's store, never the ambient env's.
+const rvEnv = (id, harness = HARNESS) => {
+    // SPEXCODE_SESSION_ID is the governed record id, and it is the SESSION'S OWN — so the launch STRIPS every
+    // session-identity variable it may have inherited (the pane inherits the tmux SERVER's env, which may carry
+    // a foreign session's ids from whoever started it) before setting this one. Identity is established HERE,
+    // once, at the boundary; nothing downstream re-verifies it, because after this a session-identity variable
+    // exists in a process only if that process belongs to that session — either set right here, or stamped by
+    // the harness itself for its own acting conversation ([[harness-adapter]]). The same strip runs on the one
+    // other process we own that is NOT a session's own — codex's shared app-server, whose leaked inherited id
+    // was github#76.
+    const scrub = sessionIdentityEnvVars().map((v) => `-u ${v}`);
+    const homeVars = ['SPEXCODE_HOME', 'CODEX_HOME'].flatMap((v) => {
+        const value = process.env[v];
+        return value ? [`${v}=${value}`] : [];
+    });
+    return [...scrub,
+        `SPEXCODE_SESSION_ID=${id}`,
+        `SPEXCODE_SESSION_IDENTITY_VARS=${shQuote(sessionIdentityEnvVars().join(','))}`,
+        `SPEXCODE_PROJECT_ROOT=${shQuote(mainRoot())}`,
+        ...harness.launchEnv(id), ...homeVars].join(' ');
+};
+const PROPOSAL_STATUS = { merge: 'review', nothing: 'done', close: 'close-pending' };
+function normalizeCloseSource(raw) {
+    if (raw == null)
+        return { kind: 'user' };
+    if (!raw || typeof raw !== 'object')
+        throw new ResourceConflict('refusing session close: source must be user or an unverified session claim');
+    const source = raw;
+    if (source.kind === 'user')
+        return { kind: 'user' };
+    if (source.kind === 'unverified-session-claim' && typeof source.id === 'string' && source.id.trim())
+        return { kind: 'unverified-session-claim', id: source.id.trim() };
+    throw new ResourceConflict('refusing session close: source must be user or an unverified session claim');
+}
+function appendCloseLedger(id, rec, source) {
+    const path = join(runtimeRoot(), 'session-close-ledger.ndjson');
+    const event = {
+        version: 1,
+        action: 'close-authorized',
+        at: new Date().toISOString(),
+        source,
+        target: {
+            id,
+            harness: rec.harness,
+            thread: rec.harnessSessionId,
+            worktree: rec.worktreePath,
+            branch: rec.branch,
+        },
+    };
+    appendFileSync(path, `${JSON.stringify(event)}\n`);
+}
+export function findSessionClosure(selector) {
+    const query = stripRefSigil(selector).trim();
+    if (!query)
+        return null;
+    const path = join(runtimeRoot(), 'session-close-ledger.ndjson');
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const matches = new Map();
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            throw new ResourceConflict('session close history is unreadable');
+        }
+        if (!event || typeof event !== 'object' || event.action !== 'close-authorized')
+            continue;
+        const target = event.target;
+        const id = target && typeof target === 'object' ? target.id : undefined;
+        const closedAt = event.at;
+        if (typeof id !== 'string' || !id || typeof closedAt !== 'string' || !closedAt)
+            throw new ResourceConflict('session close history is malformed');
+        if (id === query || id.startsWith(query))
+            matches.set(id, { id, closedAt });
+    }
+    if (!matches.size)
+        return null;
+    if (matches.size > 1)
+        throw new ResourceConflict(`close history for ${query} is ambiguous: ${[...matches.keys()].map((id) => id.slice(0, 8)).join(', ')}`);
+    return [...matches.values()][0];
+}
+function storeDir(id) { const d = sessionStoreDir(id); mkdirSync(d, { recursive: true }); return d; }
+function writePromptFile(id, prompt) {
+    try {
+        writeFileSync(join(storeDir(id), 'prompt'), prompt);
+    }
+    catch { /* best-effort; must never block the launch */ }
+}
+function readPromptFile(id) {
+    try {
+        const p = sessionArtifactPath(id, 'prompt');
+        if (!existsSync(p))
+            return null;
+        const s = readFileSync(p, 'utf8');
+        return s.trim() ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The resolved first-turn payload is authoritative across queue drain and recovery. Adapters that mint native
+// identity keep it until they prove identity + first-turn durability; other adapters consume on submission.
+function writeLaunchFile(id, prompt) {
+    writeFileSync(join(storeDir(id), 'launch'), prompt);
+}
+function readLaunchFile(id) {
+    try {
+        const p = sessionArtifactPath(id, 'launch');
+        return existsSync(p) ? readFileSync(p, 'utf8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function removeLaunchFile(id) {
+    try {
+        rmSync(sessionArtifactPath(id, 'launch'), { force: true });
+    }
+    catch { /* best-effort */ }
+}
+// One line, bounded — the launch prompt's shape when it enters a compact headline.
+export const HEADLINE_PREVIEW_COLUMNS = 60;
+function isBareUrl(text) {
+    return /^(?:https?|git|ssh):\/\/\S+$/i.test(text);
+}
+function oneLinePreview(text, n = HEADLINE_PREVIEW_COLUMNS) {
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    const first = lines.find((line) => !isBareUrl(line)) || lines[0] || '';
+    return first.length > n ? first.slice(0, n - 1) + '…' : first;
+}
+export const deriveLabel = (r) => r.name || r.node || r.title || r.branch || r.id;
+export const deriveTitle = (r) => r.name || r.activity || (r.note ? oneLinePreview(r.note) : '') || (r.promptPreview ? oneLinePreview(r.promptPreview) : '') || r.node || r.title || r.branch || r.id;
+// Compatibility for package consumers that still import the old name.
+export const deriveHeadline = deriveTitle;
+export const sessionLabel = (s) => s.label;
+export const sessionTitle = (s) => s.title;
+// Compatibility for older callers; all visible surfaces now resolve through `title`.
+export const sessionHeadline = sessionTitle;
+// @@@ tmux probe timeout - under load (the incident: load ~30 + swap thrash) a bare `tmux list-sessions` can
+// HANG, and with no bound the whole board assembly hung behind it — the dashboard froze / dropped rows, which
+// the human read as "sessions disappeared". So the liveness/title probes pass a bounded timeout; on expiry
+// execFile SIGKILLs the child and rejects with `killed:true`, which liveSnapshot tells apart from a clean
+// "no server" exit (see probeTimedOut) so a timeout renders `unknown`, not a false `offline`.
+const TMUX_PROBE_TIMEOUT_MS = 4000;
+// A destructive close already names one target, so it can afford the longer bounded probe without making
+// every dashboard refresh wait behind an overloaded tmux server.
+const TARGET_PROBE_TIMEOUT_MS = 15000;
+const TARGET_TMUX_CLOSE_SETTLE_MS = 3000;
+async function tmux(args, timeoutMs) {
+    const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, ...args], { encoding: 'utf8', ...(timeoutMs ? { timeout: timeoutMs, killSignal: 'SIGKILL' } : {}) });
+    return stdout;
+}
+// a rejected pexec whose child we KILLED (timeout) vs one that exited cleanly non-zero (e.g. tmux "no server
+// running" when there are genuinely no sessions). Only the former is a PROBE FAILURE (→ unknown); a clean
+// non-zero exit is authoritative (→ everything offline). node sets `killed`/`signal` when it SIGKILLs on timeout.
+function probeTimedOut(e) {
+    const err = e;
+    return err?.killed === true || err?.signal === 'SIGKILL' || err?.code === 'ETIMEDOUT';
+}
+async function tmuxOk(args) { try {
+    await tmux(args);
+    return true;
+}
+catch {
+    return false;
+} }
+export async function alive(id) { return tmuxOk(['has-session', '-t', id]); }
+function pkgRoot() {
+    return fileURLToPath(new URL('..', import.meta.url));
+}
+export const OWNED_QUEUE_RAW_STATUS = 'launch-queued';
+export function backendLaunchAuthority(env = process.env) {
+    const raw = env.SPEXCODE_API_URL?.trim() || `http://127.0.0.1:${env.PORT?.trim() || '8787'}`;
+    const url = new URL(raw);
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    url.pathname = url.pathname.replace(/\/+$/, '') || '/';
+    return url.toString().replace(/\/$/, '');
+}
+export function rawLifecycleStatus(rec) {
+    return rec.status === 'queued' && rec.launchOwner ? OWNED_QUEUE_RAW_STATUS : rec.status;
+}
+export function canDrainQueued(rec, authority = backendLaunchAuthority()) {
+    return rec.status === 'queued' && !rec.stopped && (rec.launchOwner === null || rec.launchOwner === authority);
+}
+// typed read of a session's record from the global store (null if it has none — a self-launched session that
+// only ever wrote spec-discipline sentinels has a store dir but no session.json). Goes through layout's
+// readAliasedRawRecord (the seam that owns the path + the codex-thread-id alias), then validates the loose
+// on-disk fields into the typed shape — so a codex hook resolving by its thread id reaches the real record.
+function readRecord(id) {
+    const entry = readAliasedRecordEntry(id);
+    if (entry.kind === 'absent')
+        return null;
+    if (entry.kind === 'corrupt')
+        throw new SessionRecordUnusable('corrupt', id, corruptReason(entry));
+    try {
+        return fromRaw(entry.raw);
+    }
+    catch (error) {
+        throw new SessionRecordUnusable('corrupt', id, `session record is unreadable: ${sessionRecordPath(id)} — ${error instanceof Error ? error.message : String(error)}. The file is kept as-is; nothing will rewrite it.`);
+    }
+}
+export class SessionRecordUnusable extends Error {
+    code;
+    session;
+    constructor(code, session, message) {
+        super(message);
+        this.code = code;
+        this.session = session;
+        this.name = 'SessionRecordUnusable';
+    }
+}
+const corruptReason = (e) => `session record is unreadable: ${e.path} — ${e.error}. The file is kept as-is; nothing will rewrite it. A close attempt quarantines the bytes and reports the preserved runtime/worktree/branch residue, but cannot signal or delete without an exact owner.`;
+function retirementReason(rec) {
+    if (!rec.worktreePath || existsSync(rec.worktreePath))
+        return null;
+    return `session ${rec.session.slice(0, 8)} is retired: its worktree ${rec.worktreePath} no longer exists, so it cannot work, be marked active/idle, or be relaunched. Close it (\`spex session close <id>\`) to drop the record.`;
+}
+function readLiveRecord(id) {
+    const rec = readRecord(id);
+    if (!rec)
+        return null;
+    const retired = retirementReason(rec);
+    if (retired)
+        throw new SessionRecordUnusable('retired', rec.session, retired);
+    return rec;
+}
+const withRecordLock = withSessionRecordLock;
+export function withSessionRecordLockSync(id, body) {
+    return coreWithSessionRecordLockSync(id, body);
+}
+const withRecordLockSync = withSessionRecordLockSync;
+// Synchronous terminal input is another product turn-entry path. The PTY bridge uses this narrow seam to
+// enqueue input while holding the same durable record lock as archive, so an archive preflight cannot pass idle
+// and then race a just-queued TUI turn.
+export function withSessionInputLock(id, body) {
+    // PTY input is synchronous. A single non-blocking open is the only safe barrier: EEXIST rejects this input
+    // regardless of owner PID, so a same-process async archive can never be frozen behind Atomics.wait.
+    const release = trySessionRecordLockSync(id);
+    if (!release)
+        return null;
+    try {
+        return body();
+    }
+    finally {
+        release();
+    }
+}
+const COLD_PROOF_VERSION = 'cold-v1';
+function coldProofFor(rec) {
+    const adapter = harnessById(rec.harness || defaultHarness.id).id;
+    const exact = rec.harnessSessionId ? `thread:${rec.harnessSessionId}` : 'no-resident-ref';
+    return `${COLD_PROOF_VERSION}|${adapter}|${rec.session}|${exact}`;
+}
+function hasValidColdProof(rec) {
+    return !!rec.coldProof && rec.coldProof === coldProofFor(rec);
+}
+// the loose on-disk fields validated into the typed shape. Exported so the old-record defaults (harness →
+// claude, absent pin → null) are unit-auditable without a store on disk.
+export function fromRaw(raw) {
+    const ownedQueue = raw.status === OWNED_QUEUE_RAW_STATUS;
+    const status = ownedQueue ? 'queued' : isSessionLifecycle(raw.status) ? raw.status : 'active';
+    const launchOwner = ownedQueue ? raw.launch_owner?.trim() : null;
+    if (ownedQueue && !launchOwner)
+        throw new Error(`owned queue record '${raw.session_id}' has no launch_owner`);
+    const proposal = isSessionProposal(raw.proposal) ? raw.proposal : null;
+    const sk = raw.sortkey;
+    const sortKey = typeof sk === 'number' && Number.isFinite(sk) ? sk : null;
+    const pendingRaw = rawLaunchReadinessOriginal(raw);
+    const pendingStatus = pendingRaw && isSessionLifecycle(pendingRaw.status) ? pendingRaw.status : null;
+    if (pendingRaw && !pendingStatus)
+        throw new Error(`session '${raw.session_id}' launch readiness original has invalid lifecycle '${pendingRaw.status}'`);
+    const pendingProposal = pendingRaw && isSessionProposal(pendingRaw.proposal) ? pendingRaw.proposal : null;
+    if (pendingRaw?.proposal && !pendingProposal)
+        throw new Error(`session '${raw.session_id}' launch readiness original has invalid proposal '${pendingRaw.proposal}'`);
+    const zcodeChildSessionIds = raw.zcode_child_session_ids ?? [];
+    if (!Array.isArray(zcodeChildSessionIds)
+        || zcodeChildSessionIds.some((id) => typeof id !== 'string' || !id || id.trim() !== id)
+        || new Set(zcodeChildSessionIds).size !== zcodeChildSessionIds.length)
+        throw new Error(`session '${raw.session_id}' has invalid zcode_child_session_ids`);
+    return {
+        session: raw.session_id, governed: !!raw.governed, worktreePath: raw.worktree_path || '', branch: raw.branch || null,
+        node: raw.node || null, title: raw.title || null, name: raw.name || null, parent: raw.parent || null,
+        status, proposal, merges: Number(raw.merges) || 0,
+        note: raw.note || null, sortKey, createdAt: Number(raw.createdAt) || 0,
+        harness: raw.harness || 'claude', // records written before the harness field default to claude
+        harnessSessionId: raw.harness_session_id || null,
+        stopped: !!raw.stopped, // records written before explicit stop tracking were not stopped
+        archived: !!raw.archived, // records written before archive → absent → not shelved
+        coldProof: raw.cold_proof || null, // legacy archived rows have no proof and remain visible until re-archived
+        adapterRecovery: raw.adapter_recovery || null,
+        launcher: raw.launcher || null, // records written before launchers → null → old-record fallback
+        launchCmd: raw.launch_cmd || null, // records written before the pin → null → fall back to launcher name / ambient
+        launchOwner: launchOwner || null,
+        createRequestId: raw.create_request_id || null,
+        createPayloadHash: raw.create_payload_hash || null,
+        zcodeChildSessionIds: [...zcodeChildSessionIds],
+        base: raw.base || null, // records written before pinned bases → null → the source-of-truth branch
+        launchReadinessPending: pendingRaw ? {
+            version: 1,
+            startedAt: raw.launch_readiness_pending.startedAt,
+            original: {
+                status: pendingStatus, proposal: pendingProposal, note: pendingRaw.note || null,
+                stopped: pendingRaw.stopped, archived: pendingRaw.archived,
+                coldProof: pendingRaw.cold_proof || null, adapterRecovery: pendingRaw.adapter_recovery || null,
+            },
+        } : null,
+    };
+}
+function publicRecord(rec) {
+    const original = rec.launchReadinessPending?.original;
+    return original ? { ...rec, ...original } : rec;
+}
+function launchReadinessPending(original) {
+    return {
+        version: 1,
+        startedAt: Date.now(),
+        original: {
+            status: original.status,
+            proposal: original.proposal,
+            note: original.note,
+            stopped: original.stopped,
+            archived: original.archived,
+            coldProof: original.coldProof ?? null,
+            adapterRecovery: original.adapterRecovery ?? null,
+        },
+    };
+}
+function restoreLaunchReadinessOriginal(rec) {
+    const original = rec.launchReadinessPending?.original;
+    return original ? { ...rec, ...original, launchReadinessPending: null } : rec;
+}
+// Rebuild the full disk projection so retired keys disappear on the next write.
+function writeRecord(rec) {
+    let previous = null;
+    try {
+        previous = readRecord(rec.session);
+    }
+    catch { /* a new or damaged record has no prior transition */ }
+    const obj = {
+        session_id: rec.session,
+        governed: rec.governed,
+        worktree_path: rec.worktreePath,
+        branch: rec.branch ?? '',
+        node: rec.node ?? '',
+        title: rec.title ?? '',
+        name: rec.name ?? '',
+        parent: rec.parent ?? '',
+        status: rawLifecycleStatus(rec),
+        proposal: rec.proposal ?? '',
+        merges: rec.merges,
+        note: rec.note ?? '',
+        sortkey: rec.sortKey ?? '',
+        createdAt: rec.createdAt,
+        harness: rec.harness || 'claude',
+        harness_session_id: rec.harnessSessionId ?? '',
+        stopped: rec.stopped,
+        archived: rec.archived,
+        cold_proof: rec.coldProof ?? '',
+        adapter_recovery: rec.adapterRecovery ?? '',
+        launcher: rec.launcher ?? '',
+        launch_cmd: rec.launchCmd ?? '',
+        launch_owner: rec.status === 'queued' ? rec.launchOwner ?? '' : '',
+        create_request_id: rec.createRequestId ?? '',
+        create_payload_hash: rec.createPayloadHash ?? '',
+        ...(rec.zcodeChildSessionIds?.length ? { zcode_child_session_ids: rec.zcodeChildSessionIds } : {}),
+        // Written only when the creator pinned one: an unpinned record keeps its exact legacy bytes, so a
+        // restore-the-frozen-record path stays byte-identical instead of silently gaining a key.
+        ...(rec.base ? { base: rec.base } : {}),
+        launch_readiness_pending: rec.launchReadinessPending ? {
+            version: 1,
+            startedAt: rec.launchReadinessPending.startedAt,
+            original: {
+                status: rec.launchReadinessPending.original.status,
+                proposal: rec.launchReadinessPending.original.proposal ?? '',
+                note: rec.launchReadinessPending.original.note ?? '',
+                stopped: rec.launchReadinessPending.original.stopped,
+                archived: rec.launchReadinessPending.original.archived,
+                cold_proof: rec.launchReadinessPending.original.coldProof ?? '',
+                adapter_recovery: rec.launchReadinessPending.original.adapterRecovery ?? '',
+            },
+        } : '',
+    };
+    const dir = sessionStoreDir(rec.session);
+    mkdirSync(dir, { recursive: true });
+    const path = sessionRecordPath(rec.session);
+    const tmp = join(dir, `.session.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n');
+    renameSync(tmp, path); // atomic within the dir: a concurrent reader sees the old record or the new one
+    const previousPublic = previous ? publicRecord(previous) : null;
+    const nextPublic = publicRecord(rec);
+    if (rec.governed && previousPublic && (previousPublic.status !== nextPublic.status
+        || previousPublic.proposal !== nextPublic.proposal || previousPublic.note !== nextPublic.note)) {
+        recordStatus(rec.session, nextPublic.status, nextPublic.proposal, nextPublic.note);
+        scheduleWatchNotifications(rec);
+    }
+}
+const watchPath = (target) => sessionArtifactPath(target, 'watchers.json');
+function readWatchEntries(target) {
+    try {
+        const raw = JSON.parse(readFileSync(watchPath(target), 'utf8'));
+        if (!Array.isArray(raw))
+            return [];
+        const parent = readRecord(target)?.parent ?? '';
+        const seen = new Set();
+        return raw.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return [];
+            const watcher = entry.watcher;
+            const createdAt = entry.createdAt;
+            if (!watcher || typeof watcher !== 'string' || typeof createdAt !== 'string' || seen.has(watcher))
+                return [];
+            seen.add(watcher);
+            const rawSources = entry.sources;
+            const sources = Array.isArray(rawSources)
+                ? [...new Set(rawSources.filter((source) => source === 'manual' || source === 'parent'))]
+                // The former one-source format cannot name an origin. Its child pointer is the only durable witness
+                // that this watcher was installed for parent supervision; every other legacy row is a manual watch.
+                : [watcher === parent ? 'parent' : 'manual'];
+            const snapshotPending = entry.snapshotPending;
+            return sources.length ? [{ watcher, createdAt, sources,
+                    ...(sources.includes('parent') && typeof snapshotPending === 'string' && snapshotPending ? { snapshotPending } : {}),
+                }] : [];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function writeWatchEntries(target, entries) {
+    const path = watchPath(target);
+    if (!entries.length) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* already absent */ }
+        ;
+        return;
+    }
+    const dir = sessionStoreDir(target);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.watchers.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(entries, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+function addWatchSource(entries, watcher, source, deferInitialSnapshot = false) {
+    const existing = entries.find((entry) => entry.watcher === watcher);
+    const snapshotPending = deferInitialSnapshot && !existing?.sources.includes('manual') ? randomUUID() : undefined;
+    if (!existing)
+        return { entries: [...entries, {
+                    watcher, createdAt: new Date().toISOString(), sources: [source], ...(snapshotPending ? { snapshotPending } : {}),
+                }], added: true };
+    if (existing.sources.includes(source))
+        return { entries, added: false };
+    return {
+        entries: entries.map((entry) => entry === existing ? {
+            ...entry, sources: [...entry.sources, source], ...(snapshotPending ? { snapshotPending } : {}),
+        } : entry),
+        added: true,
+    };
+}
+function removeWatchSource(entries, watcher, source) {
+    let removed = false;
+    const next = entries.flatMap((entry) => {
+        if (entry.watcher !== watcher || !entry.sources.includes(source))
+            return [entry];
+        removed = true;
+        const sources = entry.sources.filter((candidate) => candidate !== source);
+        if (!sources.length)
+            return [];
+        if (source !== 'parent')
+            return [{ ...entry, sources }];
+        const { snapshotPending: _pending, ...withoutParentDebt } = entry;
+        return [{ ...withoutParentDebt, sources }];
+    });
+    return { entries: next, removed };
+}
+function managedWatchRecord(id) {
+    const rec = readRecord(id);
+    if (!rec?.governed)
+        throw new ResourceConflict(`session ${id} is not a governed session and cannot participate in a durable watch`);
+    return rec;
+}
+function watchMessage(target) {
+    const status = target.status === 'awaiting'
+        ? PROPOSAL_STATUS[target.proposal ?? 'nothing']
+        : target.status === 'active' ? 'working' : target.status;
+    const note = target.note ? ` — ${target.note}` : '';
+    return `[spex watch] ${target.session} is ${status}${note}`;
+}
+function shouldDeliverWatchTransition(target, sources) {
+    // @@@watch-delivery-policy - Relationship setup sends current state; manual opts into working changes.
+    return target.status !== 'active' || sources.includes('manual');
+}
+function scheduleWatchNotifications(target) {
+    const watchers = readWatchEntries(target.session)
+        .filter((entry) => !entry.snapshotPending && shouldDeliverWatchTransition(target, entry.sources))
+        .map((entry) => entry.watcher);
+    if (!watchers.length)
+        return;
+    queueMicrotask(() => {
+        for (const watcher of watchers) {
+            void sendText(watcher, watchMessage(target), target.session).then((result) => {
+                if (!result.ok)
+                    console.error(`spex session watch: could not deliver ${target.session} state to ${watcher}: ${result.error}`);
+            });
+        }
+    });
+}
+const watchSnapshotState = (target) => JSON.stringify([target.status, target.proposal, target.note]);
+async function deliverPendingWatchSnapshots(targetId, forceCurrent = true) {
+    const pending = readWatchEntries(targetId).filter((entry) => entry.snapshotPending);
+    for (const original of pending) {
+        const token = original.snapshotPending;
+        let force = forceCurrent;
+        for (;;) {
+            const target = readRecord(targetId);
+            const entry = readWatchEntries(targetId)
+                .find((candidate) => candidate.watcher === original.watcher && candidate.snapshotPending === token);
+            if (!target || !entry)
+                break;
+            const state = watchSnapshotState(target);
+            const shouldDeliver = force || shouldDeliverWatchTransition(target, entry.sources);
+            if (!shouldDeliver) {
+                let settled = false;
+                await withRecordLock(targetId, async () => {
+                    const current = readRecord(targetId);
+                    const entries = readWatchEntries(targetId);
+                    const pendingEntry = entries.find((candidate) => candidate.watcher === original.watcher && candidate.snapshotPending === token);
+                    if (!current || !pendingEntry || watchSnapshotState(current) !== state)
+                        return;
+                    const next = entries.map((candidate) => {
+                        if (candidate !== pendingEntry)
+                            return candidate;
+                        const { snapshotPending: _pending, ...cleared } = candidate;
+                        return cleared;
+                    });
+                    writeWatchEntries(targetId, next);
+                    settled = true;
+                });
+                if (settled)
+                    break;
+                force = false;
+                continue;
+            }
+            const identity = `${targetId}\0${entry.watcher}\0${token}\0${state}`;
+            const delivered = await sendText(entry.watcher, watchMessage(target), targetId, {
+                idempotency: {
+                    operation: 'watch-initial-snapshot',
+                    requestDigest: digest(identity),
+                    payloadHash: digest(`watch-initial-snapshot\0${identity}\0${watchMessage(target)}`),
+                },
+                acceptGuard: async () => {
+                    const current = readRecord(targetId);
+                    const stillPending = readWatchEntries(targetId)
+                        .some((candidate) => candidate.watcher === entry.watcher && candidate.snapshotPending === token);
+                    if (!current || !stillPending || watchSnapshotState(current) !== state)
+                        throw new ResourceConflict('watch initial snapshot changed before acceptance');
+                },
+            });
+            if (!delivered.ok) {
+                if (delivered.error?.includes('watch initial snapshot changed before acceptance'))
+                    continue;
+                console.error(`spex session watch: could not deliver initial ${targetId} state to ${entry.watcher}: ${delivered.error}`);
+                break;
+            }
+            force = false;
+            let settled = false;
+            await withRecordLock(targetId, async () => {
+                const current = readRecord(targetId);
+                const entries = readWatchEntries(targetId);
+                const pendingEntry = entries.find((candidate) => candidate.watcher === entry.watcher && candidate.snapshotPending === token);
+                if (!current || !pendingEntry) {
+                    settled = true;
+                    return;
+                }
+                const currentState = watchSnapshotState(current);
+                if (currentState !== state && shouldDeliverWatchTransition(current, pendingEntry.sources))
+                    return;
+                const next = entries.map((candidate) => {
+                    if (candidate !== pendingEntry)
+                        return candidate;
+                    const { snapshotPending: _pending, ...cleared } = candidate;
+                    return cleared;
+                });
+                writeWatchEntries(targetId, next);
+                settled = true;
+            });
+            if (settled)
+                break;
+        }
+    }
+}
+async function clearPendingWatchSnapshots(targetId) {
+    await withRecordLock(targetId, async () => {
+        const entries = readWatchEntries(targetId);
+        const next = entries.map((entry) => {
+            if (!entry.snapshotPending)
+                return entry;
+            const { snapshotPending: _pending, ...settled } = entry;
+            return settled;
+        });
+        if (next.some((entry, index) => entry !== entries[index]))
+            writeWatchEntries(targetId, next);
+    });
+}
+export async function subscribeSessionWatch(watcher, targets, source = 'manual') {
+    managedWatchRecord(watcher);
+    const watched = [];
+    for (const target of [...new Set(targets)]) {
+        if (target === watcher)
+            throw new ResourceConflict('a session cannot watch itself');
+        let targetRecord = null;
+        let added = false;
+        let pending = false;
+        withRecordLockSync(target, () => {
+            targetRecord = managedWatchRecord(target);
+            const entries = readWatchEntries(target);
+            const next = addWatchSource(entries, watcher, source, source === 'parent' && targetRecord.status === 'queued');
+            if (next.added)
+                writeWatchEntries(target, next.entries);
+            added = next.added;
+            pending = next.entries.some((entry) => entry.watcher === watcher && !!entry.snapshotPending);
+        });
+        if (pending) {
+            if (source === 'manual')
+                await deliverPendingWatchSnapshots(target);
+        }
+        else if (source === 'manual' || added) {
+            const delivered = await sendText(watcher, watchMessage(targetRecord), target);
+            if (!delivered.ok)
+                throw new ResourceConflict(`watch established but could not queue ${target}'s current state for ${watcher}: ${delivered.error}`);
+        }
+        watched.push(target);
+    }
+    return { watched };
+}
+export function listSessionWatches(watcher) {
+    managedWatchRecord(watcher);
+    const watches = [];
+    for (const target of listSessionIds()) {
+        const entries = readWatchEntries(target);
+        const active = entries.filter((entry) => {
+            try {
+                return !!readRecord(entry.watcher)?.governed;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (active.length !== entries.length)
+            writeWatchEntries(target, active);
+        for (const entry of active)
+            if (entry.watcher === watcher)
+                watches.push({ target, createdAt: entry.createdAt });
+    }
+    return watches.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.target.localeCompare(b.target));
+}
+export function cancelSessionWatch(watcher, targets) {
+    managedWatchRecord(watcher);
+    let cancelled = 0;
+    for (const target of [...new Set(targets)]) {
+        withRecordLockSync(target, () => {
+            const entries = readWatchEntries(target);
+            const next = removeWatchSource(entries, watcher, 'manual');
+            if (next.removed) {
+                writeWatchEntries(target, next.entries);
+                cancelled++;
+            }
+        });
+    }
+    return cancelled;
+}
+async function withRecordLocks(ids, body, index = 0) {
+    if (index >= ids.length)
+        return body();
+    return withRecordLock(ids[index], () => withRecordLocks(ids, body, index + 1));
+}
+function assertReparentable(children, parent, records) {
+    if (!children.length)
+        throw new ResourceConflict('reparent needs at least one child session');
+    if (parent)
+        managedWatchRecord(parent);
+    for (const id of children) {
+        const child = records.get(id);
+        if (!child?.governed)
+            throw new ResourceConflict(`session ${id} is not a governed child session`);
+        if (id === parent)
+            throw new ResourceConflict('a session cannot be its own parent');
+    }
+    const childIds = new Set(children);
+    const seen = new Set();
+    for (let current = parent; current;) {
+        if (childIds.has(current))
+            throw new ResourceConflict(`reparent would create a parent cycle through ${current}`);
+        if (seen.has(current))
+            throw new ResourceConflict(`cannot reparent through malformed parent cycle at ${current}`);
+        seen.add(current);
+        current = readRecord(current)?.parent ?? null;
+    }
+}
+export async function reparentSessionRecords(rawChildren, parent) {
+    const children = [...new Set(rawChildren)].sort();
+    const notify = [];
+    await withRecordLock('session-reparent-transaction', async () => {
+        // Read former supervisors only after the transaction fence: a concurrent reparent may change exactly
+        // this relation, and its real sender lock is part of the next transaction's outgoing-message boundary.
+        const before = new Map(children.map((id) => [id, managedWatchRecord(id)]));
+        assertReparentable(children, parent, before);
+        const formerParents = [...new Set([...before.values()].flatMap((record) => record.parent ? [record.parent] : []))];
+        await withRecordLocks([...children, ...formerParents].sort(), () => withDeliveryLocks(children, async () => {
+            const current = new Map(children.map((id) => [id, managedWatchRecord(id)]));
+            assertReparentable(children, parent, current);
+            const snapshots = children.map((id) => ({ id, record: current.get(id), watchers: readWatchEntries(id), pending: pendingSnapshot(id) }));
+            try {
+                for (const snapshot of snapshots) {
+                    const { record, watchers } = snapshot;
+                    const hadNewParent = !!parent && watchers.some((entry) => entry.watcher === parent && entry.sources.includes('parent'));
+                    const withoutFormerParent = record.parent
+                        ? removeWatchSource(watchers, record.parent, 'parent').entries
+                        : watchers;
+                    const nextWatchers = parent
+                        ? addWatchSource(withoutFormerParent, parent, 'parent').entries
+                        : withoutFormerParent;
+                    if (nextWatchers !== watchers)
+                        writeWatchEntries(snapshot.id, nextWatchers);
+                    if (record.parent !== parent)
+                        writeRecord({ ...record, parent });
+                    if (parent && (record.parent !== parent || !hadNewParent))
+                        notify.push({ ...record, parent });
+                }
+                for (const snapshot of snapshots) {
+                    if (snapshot.record.parent && snapshot.record.parent !== parent)
+                        revokePendingFromWhileLocked(snapshot.id, snapshot.record.parent);
+                }
+            }
+            catch (error) {
+                let rollbackFailure = null;
+                for (const snapshot of [...snapshots].reverse()) {
+                    try {
+                        replacePendingWhileLocked(snapshot.id, snapshot.pending);
+                        writeWatchEntries(snapshot.id, snapshot.watchers);
+                        writeRecord(snapshot.record);
+                    }
+                    catch (rollback) {
+                        rollbackFailure ??= rollback;
+                    }
+                }
+                const detail = error instanceof Error ? error.message : String(error);
+                const rollbackDetail = rollbackFailure instanceof Error ? `; rollback also failed: ${rollbackFailure.message}` : '';
+                throw new ResourceConflict(`reparent did not commit: ${detail}${rollbackDetail}`);
+            }
+        }));
+    });
+    const notified = [];
+    if (parent)
+        for (const child of notify) {
+            const delivered = await sendText(parent, watchMessage(child), child.session);
+            if (!delivered.ok)
+                throw new ResourceConflict(`reparent committed but could not queue ${child.session}'s current state for ${parent}: ${delivered.error}`);
+            notified.push(child.session);
+        }
+    return { children, parent, notified };
+}
+// tmux rewrites CONTROL characters in a format string before printing them — 3.6a turns both a tab and a raw
+// 0x1f into `_`, while 3.4 turns a raw 0x1f into the printable escape `\037`. So the field separator is ASKED
+// FOR as that printable text, which every supported version passes through untouched, and the format is built
+// from the same constant the parser splits on: the two can no longer disagree about what tmux actually emits.
+const TMUX_PANE_SEPARATOR = '\\037';
+export const TMUX_PANE_FORMAT = `#{session_name}${TMUX_PANE_SEPARATOR}#{pane_pid}${TMUX_PANE_SEPARATOR}#{pane_title}`;
+// First pane per session wins; split only twice so titles may contain the field separator.
+export function parseLivePanes(out) {
+    const m = new Map();
+    for (const line of out.split('\n')) {
+        if (!line)
+            continue;
+        // Accept the former tab shape for callers replaying old snapshots; tmux itself emits TMUX_PANE_SEPARATOR.
+        const separator = line.includes(TMUX_PANE_SEPARATOR) ? TMUX_PANE_SEPARATOR : '\t';
+        const t1 = line.indexOf(separator);
+        const name = (t1 < 0 ? line : line.slice(0, t1)).trim();
+        if (!name || m.has(name))
+            continue; // first pane per session wins
+        if (t1 < 0) {
+            m.set(name, {});
+            continue;
+        }
+        const rest = line.slice(t1 + separator.length);
+        const t2 = rest.indexOf(separator);
+        const pid = Number((t2 < 0 ? rest : rest.slice(0, t2)).trim());
+        const title = t2 < 0 ? '' : rest.slice(t2 + separator.length);
+        m.set(name, { panePid: Number.isFinite(pid) && pid > 0 ? pid : undefined, title: title || undefined });
+    }
+    return m;
+}
+const pidRegistry = new Map();
+function readAgentPid(p) { try {
+    return Number(readFileSync(p, 'utf8').trim());
+}
+catch {
+    return NaN;
+} }
+function agentAlive(id) {
+    const pidPath = sessionArtifactPath(id, 'agent.pid');
+    let mtimeMs;
+    try {
+        mtimeMs = statSync(pidPath).mtimeMs;
+    }
+    catch {
+        pidRegistry.delete(id);
+        return undefined;
+    } // no pid file → pre-registration
+    let e = pidRegistry.get(id);
+    if (!e || e.mtimeMs !== mtimeMs) {
+        e = { mtimeMs, pid: readAgentPid(pidPath), deadLatched: false };
+        pidRegistry.set(id, e);
+    }
+    if (e.deadLatched)
+        return false; // latched dead stays dead until a new write (fresh mtime)
+    if (!Number.isFinite(e.pid) || e.pid <= 0)
+        return false;
+    try {
+        process.kill(e.pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EPERM')
+            return true; // alive but not ours to signal
+        e.deadLatched = true; // ESRCH → proven dead, latch it permanently
+        return false;
+    }
+}
+// Only pre-agent.pid Codex sessions need the legacy whole-process scan.
+export function needsCodexProcScan(windowed) {
+    return windowed.some((w) => (w.harness || 'claude') === 'codex' && !w.hasPid);
+}
+async function liveSnapshot(targetId) {
+    const windows = new Map();
+    const titles = new Map();
+    let out;
+    try {
+        // ONE merged spawn replaces the old two (list-sessions + list-panes): window presence + pane pid + title.
+        // A target-scoped close probe avoids unrelated panes turning a safe close into a global timeout.
+        const args = targetId
+            ? ['list-panes', '-t', targetId, '-F', TMUX_PANE_FORMAT]
+            : ['list-panes', '-a', '-F', TMUX_PANE_FORMAT];
+        out = await tmux(args, targetId ? TARGET_PROBE_TIMEOUT_MS : TMUX_PROBE_TIMEOUT_MS);
+    }
+    catch (e) {
+        // a TIMEOUT/kill is a probe FAILURE (we can't tell who's alive → unknown, never a false graveyard). A clean
+        // non-zero exit ("no server running" — genuinely zero sessions) is authoritative → the empty map = offline.
+        return { probeFailed: probeTimedOut(e), windows, titles, sockets: new Set(), unproven: new Set() };
+    }
+    // the hot-tier pid verdict per windowed session (latch-consistent with hotSignature) + the legacy-scan gate.
+    const legacy = [];
+    for (const [id, p] of parseLivePanes(out)) {
+        windows.set(id, { panePid: p.panePid, pidAlive: agentAlive(id) });
+        if (p.title)
+            titles.set(id, p.title);
+        if (windows.get(id).pidAlive === undefined) {
+            // A corrupt row has no trustworthy harness to scan and renders liveness=unknown on its own. Letting this
+            // optional legacy enrichment throw would turn one diagnosable row into a 409 for the entire board.
+            try {
+                const rec = readRecord(id);
+                if (rec)
+                    legacy.push({ harness: rec.harness, hasPid: false });
+            }
+            catch (e) {
+                if (!(e instanceof SessionRecordUnusable))
+                    throw e;
+            }
+        }
+    }
+    // the whole-box ps table is gathered ONCE, and ONLY for the legacy pid-less-codex fallback (paneTreeRunsCodex).
+    if (needsCodexProcScan(legacy)) {
+        const procs = await procSnapshot().catch(() => undefined); // codex-only, auxiliary; its failure isn't a liveness failure
+        if (procs)
+            for (const probe of windows.values())
+                probe.procs = procs;
+    }
+    // LISTENER probe for every windowed session, once, in parallel (a live listener, not a lingering socket
+    // file). A codex session has no rvSock → instant ENOENT → proven dead for the socket axis (codex ignores it).
+    // The tri-state matters: 'unproven' (timeout/EAGAIN — a wedged or thrashed but possibly-alive listener) lands
+    // in `unproven`, never silently not-live, so liveness() renders `unknown` not a false `offline` (issue #40).
+    const ids = [...windows.keys()];
+    // A burst of simultaneous Unix-socket connects can fill a Claude listener's accept backlog on macOS and
+    // turn every healthy socket into `unproven`. Keep the probe bounded while preserving the tri-state result.
+    const listening = [];
+    for (let start = 0; start < ids.length; start += 2) {
+        listening.push(...await Promise.all(ids.slice(start, start + 2).map((id) => rendezvousListening(id))));
+    }
+    const sockets = new Set();
+    const unproven = new Set();
+    ids.forEach((id, i) => {
+        if (listening[i] === 'live')
+            sockets.add(id);
+        else if (listening[i] === 'unproven')
+            unproven.add(id);
+    });
+    return { probeFailed: false, windows, titles, sockets, unproven };
+}
+async function assertTargetTmuxAbsent(id, phase) {
+    const deadline = Date.now() + TARGET_TMUX_CLOSE_SETTLE_MS;
+    let probeFailed = false;
+    do {
+        const snap = await liveSnapshot(id);
+        if (!snap.probeFailed && !snap.windows.has(id))
+            return;
+        probeFailed ||= snap.probeFailed;
+        if (Date.now() >= deadline)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    } while (true);
+    throw new ResourceConflict(probeFailed
+        ? `refusing to stop ${id}: target tmux absence is unproven ${phase}`
+        : `refusing to stop ${id}: target tmux session remains ${phase}`);
+}
+// Avoid process spawns on the hot path; old sessions without agent.pid remain warm-tier only.
+let hotIds = [];
+let hotIdsAt = 0;
+export async function hotSignature() {
+    const now = Date.now();
+    if (now - hotIdsAt >= 1000) {
+        hotIds = listSessionIds();
+        hotIdsAt = now;
+    }
+    const pairs = [];
+    const present = [];
+    for (const id of hotIds) {
+        const alive = agentAlive(id);
+        if (alive === undefined)
+            continue; // no agent.pid → the warm tier's concern, not the hot death detector
+        present.push(id);
+        pairs.push(`${id}:${alive ? 1 : 0}`);
+    }
+    // prune latch entries for ids no longer registered (closed sessions), keeping the registry bounded.
+    const live = new Set(hotIds);
+    for (const k of [...pidRegistry.keys()])
+        if (!live.has(k))
+            pidRegistry.delete(k);
+    return pairs.sort().join(',') + '|' + present.sort().join(',');
+}
+// Include listener and title changes so watchers refresh without another store read.
+export async function warmSignature() {
+    const snap = await liveSnapshot();
+    return (snap.probeFailed ? 'PROBEFAIL|' : '') + [...snap.windows.keys()].sort().join(',') + '#' +
+        [...snap.sockets].sort().join(',') + '~' + [...snap.unproven].sort().join(',') + '|' +
+        [...snap.titles].sort().map(([k, v]) => `${k}=${v}`).join(',');
+}
+// @@@ paneActivity - the harness-aware live self-summary: the SINGLE place a raw pane title becomes (or does
+// NOT become) a session's headline activity. The board headline derives from the pane title ONLY for a
+// harness whose pane title is its own task self-summary (`paneTitleIsSelfSummary`, an adapter capability —
+// [[harness-adapter]]). claude qualifies (it writes its task summary into the OSC title), so we parse it with
+// selfSummary (glyph-gated). codex does NOT — its pane title is a spinner glyph + the cwd FOLDER name, so
+// returning it would headline the worktree folder, not the task; we refuse it (→ null) and sessionHeadline
+// falls through to promptPreview (the launch prompt). The ONLY harness branch is the capability read here —
+// no `if (codex)`, no glyph special-case; selfSummary stays the pure claude-title parser.
+export function paneActivity(harness, paneTitle) {
+    if (paneTitle == null || !harness.paneTitleIsSelfSummary)
+        return null;
+    return selfSummary(paneTitle);
+}
+// @@@ selfSummary - the agent's OWN live one-line description, parsed from its tmux pane title — the SINGLE
+// place the "is this the agent speaking?" rule lives, exported so it is unit-auditable. Claude Code sets that
+// title via an OSC escape and ALWAYS leads it with a status glyph: ✳ (and its ✶✻✽✢ blink frames) when idle, a
+// braille spinner frame (U+2800–U+28FF) while working. That leading glyph is the only reliable proof the
+// title is the agent and not tmux's default — which, from pane birth until the first turn, is the HOST NAME
+// (e.g. `ser581555022561`) or a bare `Claude Code` splash. So the glyph is REQUIRED: no leading glyph → null,
+// and the caller keeps showing the launch-prompt placeholder instead of flickering through the host name and
+// splash. The leading glyph run (with the spaces/`·` between and after) is stripped — the dashboard draws its
+// own status dot, a frozen spinner frame is just noise — leaving only the summary text (null if it is empty).
+// ONE regex is the single source of the glyph rule: it gates (requires ≥1 glyph) and strips in one match.
+// The glyph gate alone is not enough: Claude Code emits a glyph-led SPLASH of its own app name (`✳ Claude
+// Code`) between pane birth and its first real task summary — it CLEARS the glyph gate yet is the app naming
+// itself, not the task. GENERIC_SUMMARY rejects that stripped splash too, so the row keeps its launch-prompt
+// placeholder instead of flashing "Claude Code" for a tick (the glyph-LESS `Claude Code` splash was already
+// rejected by the gate; this catches its glyph-led twin).
+const GENERIC_SUMMARY = /^claude code$/i;
+export function selfSummary(paneTitle) {
+    const m = /^[\s·]*(?:[✳✶✻✽✢⠀-⣿][\s·]*)+(.*)$/u.exec(paneTitle);
+    if (!m)
+        return null;
+    const text = m[1].trim();
+    return text && !GENERIC_SUMMARY.test(text) ? text : null;
+}
+// @@@ launchedAt - when we last started a tmux window for an id (set in launch()). claude needs ~15-20s
+// after the window appears to recreate its rendezvous socket; in that window the socket is absent but the
+// session is booting, NOT dead. reconcile consults this to report 'starting' (a distinct transient state)
+// instead of 'offline' for BOOT_GRACE_MS after launch — so 'offline' only ever means genuinely dead. In-
+// memory in the single server process (lost on restart, which is fine: a restart has nothing in flight).
+const launchedAt = new Map();
+export const BOOT_GRACE_MS = 45000; // > SOCKET_READY_TIMEOUT_MS, and spans launchScript's bounded fast-fail retry
+// window (~3 attempts) so a relaunching session reads 'starting', not 'offline'
+const LAUNCH_FAST_FAIL_S = 12; // launchScript retries the agent command when it exits faster than this: fast
+// exit before readiness is retryable, but it is not proof of one specific cause
+export function liveness(rec, snap) {
+    if (!rec.session || rec.stopped || rec.archived)
+        return 'offline';
+    // Ask the resolved ADAPTER ([[harness-adapter]]): claude/pi/opencode prove their rendezvous listener;
+    // codex proves its launch-registered pid (with the legacy descendant-tree fallback). The 'starting' grace
+    // stays here: a just-launched agent whose online signal has not appeared yet reads 'starting', only past it
+    // 'offline'.
+    const h = harnessById(rec.harness || defaultHarness.id);
+    if (h.liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online')
+        return 'online';
+    if (snap.probeFailed)
+        return 'unknown'; // the probe failed — we can't tell, and MUST NOT guess offline
+    // not provably online — but if this session's LISTENER probe couldn't conclude (timeout under load / EAGAIN
+    // off a full-but-alive backlog), death is UNPROVEN: `unknown`, never a false `offline` a supervisor would
+    // act on (issue #40 — a wedged-but-alive worker must not read as an actionable corpse).
+    if (snap.unproven.has(rec.session))
+        return 'unknown';
+    const at = launchedAt.get(rec.session);
+    if (at && Date.now() - at < BOOT_GRACE_MS)
+        return 'starting';
+    // A dead TRANSPORT is not a dead AGENT. The socket path is keyed by session id alone, so a foreign teardown
+    // (or a stray rm) can unlink it out from under its own live listener: the agent keeps working, unreachable,
+    // and every path-connect ENOENTs — which the adapter axis above reports as proven death. The registered
+    // agent.pid is a SECOND, independent witness, and while it still answers, death is UNPROVEN: `unknown`, not
+    // the `offline` that disarms the relaunch guard and invites a human to kill a working agent. Same rule as
+    // the probe-failure branch (issue #40), one layer down: only a corpse both witnesses agree on is actionable.
+    if (agentAlive(rec.session) === true)
+        return 'unknown';
+    return 'offline';
+}
+function reconcile(rec, snap) {
+    // record integrity outranks both axes: a session whose worktree is gone has no work to be in any state
+    // about. It reads `retired` — a terminal, human-closable row, never a lifecycle a hook can write back over.
+    if (retirementReason(rec))
+        return 'retired';
+    if (rec.archived)
+        return 'offline';
+    if (rec.status === 'awaiting')
+        return PROPOSAL_STATUS[rec.proposal || 'nothing'];
+    if (rec.status !== 'active' && rec.status !== 'idle')
+        return rec.status; // parked | error | asking | queued (no tmux yet)
+    const lv = liveness(rec, snap);
+    if (lv !== 'online')
+        return lv; // 'offline' | 'starting' | 'unknown'
+    return rec.status === 'idle' ? 'idle' : 'working';
+}
+// resolve a session id to its record + worktree. Now a DIRECT store read (the record carries worktree_path),
+// not a scan of every worktree reading its `.session` — O(1) and exact. null when the id has no governed-or-not
+// record. Shape kept ({path, branch, rec}) so the many callers (rename/propose/resume/merge/close/…) are unchanged.
+async function findWorktree(id) {
+    const rec = readRecord(id);
+    if (!rec)
+        return null;
+    return { path: rec.worktreePath, branch: rec.branch, rec };
+}
+export function reviewIdentity(id) {
+    const rec = readRecord(id);
+    if (!rec)
+        return null;
+    return {
+        id,
+        node: rec.node,
+        branch: rec.branch,
+        label: deriveLabel({ id, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch }),
+    };
+}
+function corruptSession(id, entry) {
+    const label = `${id.slice(0, 8)} (unreadable record)`;
+    return {
+        id, node: null, branch: null, path: '', label, title: label, raw: { name: null, title: null },
+        parent: null, harness: defaultHarness.id, capabilities: { headless: false }, launcher: null,
+        lifecycle: 'active', proposal: null, merges: 0, status: 'corrupt', liveness: 'unknown',
+        note: corruptReason(entry), archived: false, prompt: null, promptPreview: null, created: 0,
+        activity: null, sortKey: null, archiveHazard: null, files: [], web: [],
+    };
+}
+export function toSession(rec, status, lv, activity = null) {
+    const prompt = readPromptFile(rec.session); // the originating ask, captured at launch (store artifact; null for old sessions)
+    // activity is the LIVE pane title; it only means anything while the worker is genuinely up — a
+    // dead/booting session would show a stale or absent title, so it's suppressed unless liveness is online.
+    const showActivity = lv === 'online';
+    const act = showActivity ? activity : null;
+    const pp = prompt ? oneLinePreview(prompt) : null;
+    const parts = { id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch, activity: act, note: rec.note, promptPreview: pp };
+    const harness = harnessById(rec.harness || defaultHarness.id);
+    return { id: rec.session, node: rec.node, branch: rec.branch, label: deriveLabel(parts), title: deriveTitle(parts), raw: { name: rec.name, title: rec.title }, path: rec.worktreePath, parent: rec.parent, harness: harness.id, capabilities: { headless: harness.headless }, launcher: rec.launcher, lifecycle: rec.status, proposal: rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, archived: rec.archived, archiveHazard: null, prompt, promptPreview: pp, created: rec.createdAt, activity: act, sortKey: rec.sortKey, files: readSessionFiles(rec.session), web: readSessionWebs(rec.session), ...(rec.zcodeChildSessionIds?.length ? { zcodeChildSessionIds: [...rec.zcodeChildSessionIds] } : {}) };
+}
+// @@@zcode child identity - ZCode owns the child id and SpexCode owns the session record. The writer accepts
+// only their exact declared pair; names, worktrees, branches, and timestamps are deliberately not candidates.
+// One hash-derived lock serializes every claim for one opaque child id across all records, while the target's
+// ordinary record lock preserves its lifecycle write discipline. Closing the target removes this field with
+// its record, so the association lasts exactly as long as the SpexCode session/eval projection it names.
+export async function linkZCodeChildSession(sessionId, childSessionId) {
+    if (typeof childSessionId !== 'string' || !childSessionId || childSessionId.trim() !== childSessionId)
+        throw new ResourceConflict('z-code child session link needs a non-empty, whitespace-free childSessionId');
+    const child = childSessionId;
+    const childLock = `zcode-child-link-${createHash('sha256').update(child).digest('hex')}`;
+    return withRecordLock(childLock, () => withRecordLock(sessionId, async () => {
+        const target = readRecord(sessionId);
+        if (!target || !target.governed)
+            return null;
+        for (const id of listSessionIds()) {
+            const candidate = readRecord(id);
+            if (!candidate?.zcodeChildSessionIds?.includes(child))
+                continue;
+            if (candidate.session !== target.session)
+                throw new ResourceConflict(`z-code child session ${child} is already linked to SpexCode session ${candidate.session}`);
+            return { sessionId: target.session, childSessionId: child, alreadyLinked: true };
+        }
+        writeRecord({ ...target, zcodeChildSessionIds: [...(target.zcodeChildSessionIds ?? []), child] });
+        return { sessionId: target.session, childSessionId: child, alreadyLinked: false };
+    }));
+}
+export async function renameSession(id, name) {
+    return withRecordLock(id, async () => {
+        const wt = await findWorktree(id);
+        if (!wt)
+            return false;
+        writeRecord({ ...wt.rec, name: name.trim() || null });
+        return true;
+    });
+}
+export async function setSessionSort(id, key) {
+    return withRecordLock(id, async () => {
+        const wt = await findWorktree(id);
+        if (!wt)
+            return false;
+        writeRecord({ ...wt.rec, sortKey: key != null && Number.isFinite(key) ? key : null });
+        return true;
+    });
+}
+// the session's full ORIGINATING prompt (what it was asked to do), or null if none was recorded. A record we
+// cannot read simply has no prompt to report — a READ accessor must not turn an unreadable record into an
+// error for the surface asking about it; the row itself already carries the diagnosis.
+export async function sessionPrompt(id) {
+    try {
+        return readRecord(id) ? readPromptFile(id) : null;
+    }
+    catch (e) {
+        if (e instanceof SessionRecordUnusable)
+            return null;
+        throw e;
+    }
+}
+// Preserve rows through a transient record-read failure; prune after the store entry disappears.
+const lastKnownSession = new Map();
+// A BOARD row carries the launch ask only as its one-line preview. The full text is served by the
+// id-addressed record detail, which reads the stored prompt itself and overrides this field — so the list
+// never had a reader for it. Shipping it made the body grow with total ask LENGTH instead of session count
+// (measured on the adopter-a board: 2192 KB of a 2218 KB default body, 27 KB of which was actual board data)
+// and pinned the same bytes in `lastKnownSession` for the life of the process. The CREATE response keeps the
+// full text: it is a receipt for one ask the caller just made, not a row in a list of many.
+const boardRow = (s) => { s.prompt = null; return s; };
+export async function listSessions(includeArchived = false) {
+    // ONE store enumeration + ONE tmux snapshot (windows + pane pids + titles, merged) for the whole list, then
+    // every session reconciles by a pure set lookup + one existsSync — no per-session tmux spawn.
+    const [ids, snap] = await Promise.all([
+        Promise.resolve(listSessionIds()), liveSnapshot(),
+    ]);
+    // Freeze one record snapshot for both the census join and row projection. A second full read after an awaited
+    // probe could pair record A with thread identity B and accidentally treat a missing census entry as clean.
+    const snapshots = new Map();
+    for (const id of ids) {
+        try {
+            const entry = readPublicRecordEntry(id);
+            snapshots.set(id, { entry, rec: entry.kind === 'ok' ? fromRaw(entry.raw) : null });
+        }
+        catch { /* guardSession below preserves the last-known row for a transient read failure */ }
+    }
+    // Only archived adapter records need the resident-ID join. If there are none, this read path performs zero
+    // control-plane probes; resources still owns the full turn/read probe for its detailed report.
+    const censusRecords = [...snapshots.values()].flatMap(({ entry, rec }) => entry.kind === 'ok' && entry.liveness === null && rec && rec.governed && rec.archived && rec.harnessSessionId
+        ? [{ ...rec, harness: rec.harness || defaultHarness.id }]
+        : []);
+    const residentCensus = censusRecords.length ? await adapterLoadedReferenceState(censusRecords) : new Map();
+    // A record can change while the one census is in flight. Mark such rows conservatively; never let the stale
+    // proof hide them. This is a bounded storage read, not another adapter RPC.
+    const changedDuringCensus = new Set();
+    for (const rec of censusRecords) {
+        try {
+            const current = readPublicRecordEntry(rec.session);
+            const before = snapshots.get(rec.session)?.entry;
+            if (current.kind !== 'ok' || before?.kind !== 'ok' || JSON.stringify(current.raw) !== JSON.stringify(before.raw))
+                changedDuringCensus.add(rec.session);
+        }
+        catch {
+            changedDuringCensus.add(rec.session);
+        }
+    }
+    const rows = ids.map((id) => guardSession(id, () => {
+        // a record we cannot READ still has a row: it is a session that exists and whose state is unknowable, which
+        // is a thing to act on, not a thing to hide. It carries its own status and names the file, so the human can
+        // see the file and close it — the alternative (dropping it) is what made a live session read as gone.
+        const snapshot = snapshots.get(id);
+        if (!snapshot)
+            throw new Error(`session ${id} record snapshot unavailable`);
+        const { entry } = snapshot;
+        // The corrupt row becomes the LAST-KNOWN row, never a deletion. Dropping it would mean the next poll that
+        // hits a transient read failure has nothing to fall back on and the row vanishes — re-opening the exact
+        // hole this branch closes, one poll later. `corrupt` is a true reading, so it is worth remembering.
+        if (entry.kind === 'corrupt') {
+            const c = corruptSession(id, entry);
+            lastKnownSession.set(id, c);
+            return c;
+        }
+        const rec = snapshot.rec;
+        if (!rec || !rec.governed) {
+            lastKnownSession.delete(id);
+            return null;
+        } // no record, or a self-launched (non-board) one
+        // A forced public liveness comes only from the shared record projection. Do not let live process/thread
+        // evidence punch through it (including archive hazard repair).
+        if (entry.kind === 'ok' && entry.liveness === 'offline') {
+            const pending = boardRow(toSession(rec, 'offline', 'offline'));
+            lastKnownSession.set(id, pending);
+            return pending;
+        }
+        // the pane title → headline activity, gated by THIS session's harness ([[harness-adapter]]): claude's title
+        // is its task self-summary (used); codex's is the cwd folder name (refused → headline falls to the prompt).
+        const activity = paneActivity(harnessById(rec.harness || defaultHarness.id), snap.titles.get(id));
+        const sessionHarness = harnessById(rec.harness || defaultHarness.id);
+        const resident = rec.harnessSessionId
+            ? residentCensus.get(`${rec.harness || defaultHarness.id}:${rec.harnessSessionId}`)
+            : undefined;
+        const residentRequired = sessionHarness.runtimeOwnership === 'adapter' && !!rec.harnessSessionId && !!sessionHarness.sharedRuntimes?.(runtimeRoot()).length;
+        const physical = rec.archived
+            ? (sessionHarness.runtimeOwnership === 'adapter'
+                ? (resident && !resident.healthy ? 'unknown' : resident?.loaded ? 'online' : snap.windows.has(id) ? 'online' : 'offline')
+                : liveness({ ...rec, archived: false, stopped: false }, snap))
+            : null;
+        // Only a physically-offline record projects as archived. A legacy archived+live/unknown record is exposed
+        // as ordinary working-set state with its real liveness/status and one backend-owned hazard marker. A
+        // missing durable cold proof is also legacy: leaf liveness alone cannot prove a Codex loaded thread was
+        // unloaded, so it remains visible until an explicit archive repair.
+        const cleanCold = rec.archived && !changedDuringCensus.has(id) && hasValidColdProof(rec) && physical === 'offline' && (!residentRequired || resident?.healthy === true);
+        const projected = rec.archived && !cleanCold ? { ...rec, archived: false, stopped: false } : rec;
+        const projectedLv = projected === rec ? liveness(rec, snap) : physical;
+        const s = boardRow(toSession(projected, reconcile(projected, snap), projectedLv, activity));
+        if (projected !== rec)
+            s.archiveHazard = changedDuringCensus.has(id)
+                ? 'archived runtime hazard: record changed while adapter residency was being reconciled; retry exact archive'
+                : hasValidColdProof(rec)
+                    ? residentRequired && !resident
+                        ? 'archived runtime hazard: adapter resident-reference census missing; exact unload is unproven'
+                        : resident && !resident.healthy
+                            ? `archived runtime hazard: adapter resident-reference census is unknown (${resident.error || 'probe failed'})`
+                            : resident?.loaded
+                                ? 'archived runtime hazard: target adapter thread is still loaded'
+                                : `archived runtime hazard: record says archived but physical liveness is ${physical}`
+                    : 'archived runtime hazard: record has no durable cold witness; exact adapter unload is unproven';
+        if (rec.adapterRecovery)
+            s.archiveHazard = `archive adapter recovery required: ${rec.adapterRecovery}`;
+        lastKnownSession.set(id, s);
+        return s;
+    }, () => {
+        // DEGRADED: the record dir still exists but reading session.json failed transiently. NEVER drop a live
+        // session — serve its last-known row. (No last-known means a first sighting raced a failure; nothing to
+        // show yet, and it reappears on the next build.)
+        return lastKnownSession.get(id) ?? null;
+    }));
+    // prune last-known entries for ids that no longer appear at all (genuinely removed), keeping it bounded.
+    const liveIds = new Set(ids);
+    for (const k of [...lastKnownSession.keys()])
+        if (!liveIds.has(k))
+            lastKnownSession.delete(k);
+    return rows.filter((s) => s != null && (includeArchived || !s.archived))
+        .sort((a, b) => (a.sortKey ?? a.created) - (b.sortKey ?? b.created) || a.id.localeCompare(b.id));
+}
+// a per-session read guard mirroring resilience.guardWorktree but keyed on the store record (not a worktree
+// path): run `primary`; if it throws AND the record dir still exists, the failure is transient → serve the
+// `degraded` fallback; if the dir is gone (a genuine close), return null (omit). No async git, so it's sync.
+function guardSession(id, primary, degraded) {
+    try {
+        return primary();
+    }
+    catch {
+        return existsSync(sessionStoreDir(id)) ? degraded() : null;
+    }
+}
+const usageError = (msg) => { const e = new Error(msg); e.name = 'UsageError'; return e; };
+export function optionArgv(argv = process.argv) {
+    const delimiter = argv.indexOf('--');
+    return delimiter < 0 ? argv : argv.slice(0, delimiter);
+}
+// the explicit routing flag, read from THIS process's argv (never the environment — that's the point).
+// `--port` doubles as a BIND port for serve/dashboard, so the sugar is skipped for those verbs.
+function explicitApiFlag() {
+    const argv = optionArgv();
+    const ai = argv.indexOf('--api');
+    if (ai >= 0) {
+        const v = argv[ai + 1];
+        if (!v || v.startsWith('--'))
+            throw usageError('--api expects a URL (e.g. --api http://127.0.0.1:8901)');
+        const withScheme = v.includes('://') ? v : `http://${v}`;
+        try {
+            new URL(withScheme);
+        }
+        catch {
+            throw usageError(`--api: not a URL: ${v}`);
+        }
+        return withScheme.replace(/\/+$/, '');
+    }
+    if (argv[2] === 'serve' || argv[2] === 'dashboard')
+        return null; // their --port is a bind port, not routing
+    const pi = argv.indexOf('--port');
+    if (pi >= 0) {
+        const v = argv[pi + 1];
+        if (!v || !Number.isInteger(Number(v)))
+            throw usageError('--port expects an integer (localhost sugar for --api http://127.0.0.1:<n>)');
+        return `http://127.0.0.1:${v}`;
+    }
+    return null;
+}
+// the cwd project's recorded backend ({url,pid}, written by `spex serve` at bind time into the per-project
+// runtime tier), trusted only after a live /health probe — a stale record must never swallow a command.
+async function liveRecordUrl() {
+    let file;
+    try {
+        file = join(runtimeRoot(), 'backend.json');
+    }
+    catch {
+        return null;
+    } // cwd not in a git repo → nothing to discover
+    let url = '';
+    try {
+        const rec = JSON.parse(readFileSync(file, 'utf8'));
+        if (typeof rec?.url === 'string')
+            url = rec.url.trim();
+    }
+    catch {
+        return null;
+    }
+    if (!url)
+        return null;
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 600);
+    try {
+        return (await fetch(`${url}/health`, { signal: ctrl.signal })).ok ? url : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+async function resolveApiBase() {
+    const flag = explicitApiFlag();
+    if (flag)
+        return { url: flag, source: 'flag' };
+    const env = process.env.SPEXCODE_API_URL?.trim() || null;
+    if (process.env.SPEXCODE_SESSION_ID?.trim()) {
+        if (env)
+            return { url: env, source: 'worker-env' };
+        const rec = await liveRecordUrl();
+        if (rec)
+            return { url: rec, source: 'record' };
+    }
+    else {
+        const rec = await liveRecordUrl();
+        if (rec)
+            return { url: rec, source: 'record' };
+        if (env)
+            return { url: env, source: 'env-fallback' };
+    }
+    return { url: `http://127.0.0.1:${process.env.PORT || 8787}`, source: 'default' };
+}
+let apiBaseMemo = null;
+export const apiBaseInfo = () => (apiBaseMemo ??= resolveApiBase());
+export const apiBase = async () => (await apiBaseInfo()).url;
+export const ownSessionId = envSessionId;
+export function withSenderHint(text, sender) {
+    if (!sender)
+        return text;
+    const who = sender.label && sender.label !== sender.id ? `session "${sender.label}" (${sender.id})` : `session ${sender.id}`;
+    return `${text}\n\n— from ${who}. To reply: spex session send ${sender.id} "<your reply>"`;
+}
+export function withPeerSenderHint(text, sender, sshAddress, machineId) {
+    if (!sender)
+        return text;
+    const who = sender.label && sender.label !== sender.id ? `session "${sender.label}" (${sender.id})` : `session ${sender.id}`;
+    return `${text}\n\n— from ${who} on machine ${machineId}. To reply: spex session send --ssh ${sshAddress} ${sender.id} "<your reply>"`;
+}
+export const withNoteReplyHint = (text) => `${text}\n\n— REQUIRED REPLY TRANSPORT (PER-MESSAGE): this terminal-free sender CANNOT see normal assistant/final output. Do not stop after only printing the answer. As your FINAL action, put your COMPLETE reply to this message in the truthful declaration's --note. For an answered exploratory question or simple answer awaiting the sender's follow-up, run \`spex session ask --note "<complete reply>"\`; if the true state is done or parked, put the same complete reply in that declaration's --note instead. This declaration command is reply transport, not part of the requested work, and remains REQUIRED even when the message says to use no tools, make no tool calls, or only print/reply. A later message arriving WITHOUT this notice means the sender is back at a terminal and reads your normal output again.`;
+export const withTerminalReplyHint = (text) => `${text}\n\n— sent from a terminal-attached client: the sender now reads your terminal output directly. Reply in your normal conversation output from here on — stop putting replies in declaration --notes (the earlier terminal-free notices no longer apply; a --note can go back to being a short status line).`;
+export const slugify = (s) => (s || 'session').normalize('NFC').replace(/[^\p{L}\p{N}_-]+/gu, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'session';
+const MENTION = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/u;
+export const nodeFromPrompt = (prompt) => prompt.match(MENTION)?.[1] ?? null;
+export function composeCommandPrompt(raw, presets, specs) {
+    const match = raw.match(/^\/(\S+)\s*([\s\S]*)$/);
+    if (!match)
+        return raw;
+    const preset = presets.find((p) => p.name === match[1]);
+    if (!preset)
+        return raw;
+    const ids = [];
+    const allMentions = new RegExp(MENTION.source, 'gu');
+    const free = match[2].replace(allMentions, (_, id) => { ids.push(id); return ''; }).trim();
+    const targets = ids.length
+        ? ids.map((id) => {
+            const spec = specs.find((s) => s.id === id);
+            const path = spec?.path.replace(/^\.spec\//, '').replace(/\/spec\.md$/, '');
+            return path ? `- [[${id}]] — ${path}` : `- [[${id}]]`;
+        }).join('\n')
+        : '(No target was mentioned. If the prompt names the scope, use it; otherwise ask the human to define the scope before proceeding — unless this task needs no scope, in which case proceed.)';
+    const body = preset.body.includes('{{targets}}')
+        ? preset.body.replace('{{targets}}', targets)
+        : ids.length ? `${preset.body}\n\n${targets}` : preset.body;
+    return free ? `${body}\n\n${free}` : body;
+}
+// Load only the one live preset named by the raw invocation. Both session creation and sendText call this seam, so
+// launch and an existing session's inbox resolve identical plugin data with identical target semantics.
+export async function resolveCommandPrompt(raw, loadedSpecs) {
+    const commandName = raw.match(/^\/(\S+)/)?.[1];
+    const preset = commandName ? loadConfig().find((p) => p.name === commandName) : undefined;
+    if (!preset)
+        return raw;
+    const specs = loadedSpecs ?? (nodeFromPrompt(raw) ? await loadSpecs() : []);
+    return composeCommandPrompt(raw, [preset], specs);
+}
+// @@@ composeSessionPrompt - the ONE prompt-delivery seam: raw caller text + target session become the
+// exact text handed to an adapter. Launch, ordinary input, CLI send, issue dispatch, watch greetings, and
+// merge all enter here (directly or through sendText). `replyVia` is target readability: an explicit note
+// request wins; otherwise a headless adapter defaults to note. This function alone decides and appends the
+// note/terminal inserts, so clients never own the policy or duplicate the phrase.
+export async function composeSessionPrompt(raw, target, opts = {}) {
+    const resolved = await resolveCommandPrompt(raw, opts.loadedSpecs);
+    const prompt = opts.suffix ? `${resolved}${opts.suffix}` : resolved;
+    const h = harnessById(target.harness || defaultHarness.id);
+    const replyVia = opts.replyVia ?? (h.headless ? 'note' : undefined);
+    const text = replyVia === 'note' ? withNoteReplyHint(prompt)
+        : !opts.from && lastHumanSendVia(target.session) === 'note' ? withTerminalReplyHint(prompt) : prompt;
+    return { text: optionSafe(text), ...(replyVia ? { replyVia } : {}) };
+}
+const optionSafe = (text) => text.startsWith('-') ? ` ${text}` : text;
+const UUID_TOKEN = /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g;
+const stripIdentityTokens = (s) => s.replace(/(^|\s)@[\p{L}\p{N}_-]+/gu, '$1').replace(UUID_TOKEN, ' ');
+export function titleFromPrompt(prompt) {
+    const first = stripIdentityTokens(prompt || '').split('\n').map((l) => l.trim()).find(Boolean) || '';
+    const words = first.split(/\s+/).filter(Boolean).slice(0, 7).join(' ');
+    if (!words)
+        return null;
+    return words.length > 50 ? words.slice(0, 49).trimEnd() + '…' : words;
+}
+// @@@ launchScript - the WHOLE launch invocation (rendezvous env prefix + harness command + the human prompt)
+// is written to an ephemeral `launch.sh` in the session's GLOBAL store and
+// run via `bash <file>`, NOT typed inline. Inline send-keys TRUNCATES past ~2KB (the launch-prompt-limit trap),
+// and a long human prompt + spec pointer can exceed it; a file has no length limit
+// and the only thing send-keys types is the short `bash <file>` line. It's the SAME command the inline path
+// ran (env prefix exports the rendezvous vars to the claude child), just relocated to a file. Liveness no
+// longer cares what the pane's foreground command is: claude runs as a child of bash (and, via the
+// `reclaude` wrapper, a grandchild), so the pane command is the wrapper/shell — reconcile reads claude's
+// rendezvous socket instead (present while claude is alive, gone once it exits). The file lives OUTSIDE the
+// worktree (in the store, keyed by session_id), so it never pollutes the spec/code work.
+// the launch command for THIS session ([[launcher-select]] resume-launcher-pin): the RESOLVED base command
+// PINNED on the record at creation wins — so a (re)launch replays the EXACT launcher that made the conversation
+// (and its config-dir env), never re-resolving against a since-changed default that would send `--resume` to the
+// wrong config dir and lose the transcript. Fall back to the named-launcher resolution (an old record with a
+// launcher name but no pinned cmd; fail-loud on a since-removed launcher), then undefined (truly old record →
+// the harness adapter's ambient resolution, best-effort).
+export function launcherCmd(rec) {
+    if (rec.launchCmd)
+        return rec.launchCmd;
+    return rec.launcher ? resolveLauncher(rec.launcher).cmd : undefined;
+}
+// does this ref resolve to a commit? Through git.ts's git() so a hook's exported GIT_DIR can't misdirect
+// discovery. `--verify --quiet` answers a MISSING ref with a bare non-zero exit and no stderr, while a broken
+// repo/timeout writes stderr — so only the silent failure is read as absence. A probe that could not answer
+// reads as "exists": the preflight refuses on a PROVEN absence, never on a failed probe ([[state]]'s board
+// honesty rule applied to launch).
+function refExists(cwd, ref) {
+    try {
+        return !!git(['-C', cwd, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).trim();
+    }
+    catch (e) {
+        return String(e?.stderr ?? '').trim() !== '';
+    }
+}
+export function launchPreflight(rec) {
+    if (!rec.worktreePath || !existsSync(rec.worktreePath))
+        return { code: 'no-worktree', message: `session ${rec.session.slice(0, 8)}: its worktree ${rec.worktreePath || '(unrecorded)'} does not exist — there is nothing to launch in. If the work merged and the worktree was removed, close the session; otherwise restore the worktree first.` };
+    if (rec.branch && !refExists(rec.worktreePath, rec.branch))
+        return { code: 'no-branch', message: `session ${rec.session.slice(0, 8)}: its branch ${rec.branch} no longer exists — a relaunch would put the agent on a detached or wrong ref. Restore the branch, or close the session.` };
+    let cmd;
+    try {
+        cmd = launcherCmd(rec);
+    }
+    catch (e) {
+        return { code: 'no-launcher', message: `session ${rec.session.slice(0, 8)}: its launcher cannot be resolved — ${e instanceof Error ? e.message : e}` };
+    }
+    // only an ABSOLUTE command is checkable here; a bare name is the shell's PATH lookup at launch time, and
+    // guessing at it would refuse launches that work. Certainty is the whole point of a preflight.
+    const bin = (cmd ?? '').trim().split(/\s+/)[0];
+    if (bin && isAbsolute(bin) && !existsSync(bin))
+        return { code: 'no-launcher', message: `session ${rec.session.slice(0, 8)}: its pinned launcher command ${bin} is not on this machine — every launch of it will fail until the path is restored or the session is re-dispatched under a launcher that exists.` };
+    return null;
+}
+// @@@ launch quoting - single-quote a string for a POSIX shell, `'` → `'\''`. Used to nest the whole agent
+// invocation inside the birth-registration `sh -c '…'` wrapper without any segment double-expanding.
+export function launchScript(id, tail, harness = HARNESS, cmd) {
+    const file = join(storeDir(id), 'launch.sh');
+    // NO --append-system-prompt / --settings: the contract + hooks are materialized into the worktree at
+    // createSession ([[harness-delivery]]) and the agent auto-discovers them — the SAME path as a self-launched
+    // agent. The launch line is just the rendezvous env + the harness command + the session-id/spec-pointer/prompt tail.
+    // `cmd` is the session's persisted launcher command ([[launcher-select]]); when set it OVERRIDES the harness's
+    // ambient default so resume reuses the same auth. Undefined is only for old records before launch_cmd existed.
+    const invocation = `${rvEnv(id, harness)} ${harness.launchCmd(id, runtimeRoot(), cmd)} ${tail}`;
+    // @@@ birth registration - record the AGENT's real pid BEFORE exec, the anchor of the 100ms hot death tier
+    // ([[state]]). Each attempt runs `sh -c '<pid-write>; exec env <invocation>'`: the sh writes its own `$$` to
+    // agent.pid, then `exec env` REPLACES that sh in place — so the pid persists down the whole command chain
+    // (claude: env→(reclaude→)claude; codex: env→bash -lc <script> whose last line is `exec codex … resume`), and
+    // `$$` therefore IS the launched agent's pid. `env` carries the leading `VAR=val` assignments (an env prefix
+    // can't lead an `exec`), and the whole payload is single-quoted for the outer shell (shQuote) so the
+    // invocation's own single-quoted segments — the codex `$@`/`$tid` script, the prompt — reach sh verbatim,
+    // parsed exactly ONCE, never double-expanded. Each retry attempt rewrites agent.pid with a fresh `$$`.
+    const pidPath = join(storeDir(id), 'agent.pid');
+    const receiptPath = join(storeDir(id), 'agent.identity.json');
+    const born = `sh -c ${shQuote(`rm -f ${shQuote(receiptPath)}; printf %s "$$" > ${shQuote(pidPath)}; exec env ${invocation}`)}`;
+    // Bounded relaunch on a FAST exit: the agent launcher can exit within seconds before the rendezvous socket
+    // ever appears. That is enough evidence to retry, but not enough evidence to name the cause. Once the agent
+    // has run past LAUNCH_FAST_FAIL_S it has genuinely started; its eventual (much later) exit is a normal
+    // session end and is NEVER retried — the loop exits. BOOT_GRACE_MS and SOCKET_READY_TIMEOUT_MS both span this
+    // retry window, so liveness stays 'starting' and waitForReady keeps holding the slot across retries. This
+    // only closes startup unready failures — it adds no fallback and never masks a genuinely dead agent (3
+    // attempts, then give up).
+    // A one-shot adapter (currently codex-headless) deliberately exits after its first turn while the shared
+    // app-server stays alive. Retrying that successful fast exit would mint a duplicate thread/prompt, so the
+    // retry loop is a runtime capability rather than a harness-id branch.
+    // @@@ retry only what retrying can fix - a fast exit says the launcher stopped before readiness, which is
+    // reason enough to try again but never a diagnosis. So after a fast exit the script reads what the harness
+    // actually SAID and matches it against the ADAPTER's own settled-failure patterns ([[harness-adapter]]
+    // fatalLaunchOutput). A match means this command cannot succeed however many times we run it: stop at one
+    // attempt and let the harness's own line be the last thing on the pane, instead of spending a certain failure
+    // three times and burying the reason. No match keeps the plain bounded retry.
+    //
+    // It reads the PANE, not the agent's streams. Capturing stderr through a pipe missed the answer entirely —
+    // measured against real reclaude, "No conversation found with session ID" arrives on STDOUT, so a
+    // stderr-only capture classified nothing and retried a certain failure three times (the unit test passed
+    // only because its stub printed to the stream the implementation happened to watch). Redirecting stdout too
+    // would be worse: a TUI that finds stdout is not a terminal stops being a TUI. The pane already holds both
+    // streams exactly as the human sees them, and the script runs inside that pane — so it just asks tmux.
+    const fatal = (harness.fatalLaunchOutput ?? []).join('|');
+    const launchBody = harness.launchOneShot ? [born, ''] : [
+        `for __spex_try in 1 2 3; do`,
+        `  __spex_t0=$SECONDS`,
+        // @@@ classify THIS attempt only - the pane is a scrollback, so it also holds every earlier attempt and
+        // every earlier launch that ever ran in this window. Matching the whole capture would let a stale
+        // settled-failure line from minutes ago condemn an unrelated fast exit and cut a launch that retrying
+        // WOULD have recovered — the exact mirror of the miss this classifier exists to fix. So each attempt
+        // stamps a line unique to (this run, this attempt) and the match starts after it. The run's pid is what
+        // makes it unique across relaunches, which reuse the session id.
+        `  __spex_mark="attempt $__spex_try start $$"`,
+        `  printf '[spex launch] %s\\n' "$__spex_mark"`,
+        `  ${born}`,
+        `  __spex_rc=$?`,
+        `  [ $(( SECONDS - __spex_t0 )) -ge ${LAUNCH_FAST_FAIL_S} ] && exit $__spex_rc`,
+        ...(fatal ? [
+            // -t "$TMUX_PANE" names THIS pane explicitly (tmux still resolves the server from $TMUX), so the capture
+            // can never land on a neighbouring pane; run outside tmux the call fails, nothing matches, and the plain
+            // bounded retry stands.
+            `  if tmux capture-pane -p -S -400 -t "\${TMUX_PANE:-}" 2>/dev/null | sed -n "/$__spex_mark/,\\$p" | grep -Eq ${shQuote(fatal)}; then`,
+            `    printf '[spex launch] attempt %s exited in %ss (rc=%s) - the launcher reported a failure retrying cannot fix (see above); not retrying\\n' "$__spex_try" "$(( SECONDS - __spex_t0 ))" "$__spex_rc" >&2`,
+            `    exit $__spex_rc`,
+            `  fi`,
+        ] : []),
+        `  printf '[spex launch] attempt %s exited in %ss (rc=%s) - fast launcher exit before readiness; retrying\\n' "$__spex_try" "$(( SECONDS - __spex_t0 ))" "$__spex_rc" >&2`,
+        `  sleep 2`,
+        `done`,
+        `exit $__spex_rc`,
+        ``,
+    ];
+    writeFileSync(file, launchBody.join('\n'));
+    return file;
+}
+async function launch(id, path, tail, harness = HARNESS, cmd) {
+    // record the transport path THIS runtime hands the agent, before anything reads it (launchScript bakes it
+    // into the launch env). Same kind of launch-time fact as agent.pid, and the reason a session's socket is
+    // reachable only from the world it belongs to ([[harness-adapter]] rendezvous socket).
+    if (harness.ownsRendezvous)
+        stampRvSock(id);
+    await tmux(['new-session', '-d', '-s', id, '-x', String(COLS), '-y', String(ROWS), '-c', path]);
+    await tmux(['send-keys', '-t', id, '-l', '--', `bash ${launchScript(id, tail, harness, cmd)}`]);
+    await tmux(['send-keys', '-t', id, 'Enter']);
+    launchedAt.set(id, Date.now()); // stamp the boot window so reconcile reads 'starting', not 'offline', until the socket is up
+}
+const OCCUPIES_SLOT = new Set(['working', 'parked', 'starting']); // starting's boot window is also held via `launching`
+function isOccupying(s, snap) {
+    if (!OCCUPIES_SLOT.has(s.status))
+        return false; // waiting-on-human / proposed / queued / dead → free
+    const rec = readRecord(s.id);
+    if (!rec)
+        return false;
+    return harnessById(rec.harness || defaultHarness.id).liveness(rec, snap.windows.has(rec.session), runtimeRoot(), snap.windows.get(rec.session), snap.sockets.has(rec.session)) === 'online';
+}
+// sessions we've JUST launched whose agent hasn't come online yet. During that boot window reconcile reads them
+// `offline` (the adapter's online-signal not up yet) and isOccupying would miss them, so the drainer would
+// over-launch and blow past the cap. We hold the slot here from launch until the agent is online (waitForReady)
+// or it times out.
+// In-memory in the single server process (the only drainer) — lost on restart, which is fine: a restart drains
+// the durable `queued` worktrees fresh with nothing in flight.
+const launching = new Set();
+// A queued launch and a cold archive must not cross between their final read and record write. This is a
+// narrow per-session intent latch, not a second cleanup primitive; the launch path simply leaves an archiving id
+// alone and the archive path re-probes before filing.
+const archiving = new Set();
+const transitionTails = new Map();
+async function withSessionTransition(id, body) {
+    const previous = transitionTails.get(id) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => { release = resolve; });
+    transitionTails.set(id, current);
+    await previous;
+    try {
+        return await body();
+    }
+    finally {
+        release();
+        if (transitionTails.get(id) === current)
+            transitionTails.delete(id);
+    }
+}
+let draining = false; // re-entrancy guard: only one drain pass runs at a time (no double-launch)
+function noteQueuedLaunchFailureUnlocked(id, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    const note = `queued launch readiness failed: ${reason}`;
+    console.error(`spex: session ${id}: ${note}`);
+    const rec = readRecord(id);
+    if (rec && rec.note !== note)
+        writeRecord({ ...rec, note });
+}
+function observeQueuedLaunchReadiness(id, harness) {
+    void waitForReady(id, harness)
+        .then(async (readiness) => {
+        if (!readiness) {
+            const committed = !!readRecord(id)?.harnessSessionId;
+            throw new ResourceConflict(harness.launchPayloadProof
+                ? committed
+                    ? 'post-proof adapter liveness did not become ready before launch readiness timed out'
+                    : 'native identity and first-turn rollout proof did not arrive before launch readiness timed out'
+                : 'adapter liveness did not become ready before launch readiness timed out');
+        }
+        let readyToPublish = false;
+        await withRecordLock(id, async () => {
+            const candidate = readRecord(id);
+            if (!candidate)
+                return;
+            const stillReady = await readiness.validate(() => {
+                const current = readRecord(id);
+                return current ? { ...current, runtimeDir: runtimeRoot() } : null;
+            });
+            if (!stillReady)
+                throw new ResourceConflict('launch readiness changed before queued publication');
+            const current = readRecord(id);
+            if (!current)
+                return;
+            if (current.status === 'queued')
+                writeRecord({ ...current, status: 'active', proposal: null, note: null, launchOwner: null });
+            readyToPublish = true;
+        });
+        if (!readyToPublish)
+            return;
+        await deliverPendingWatchSnapshots(id);
+        await drainSession(id);
+    })
+        .catch(async (error) => {
+        try {
+            await withRecordLock(id, async () => noteQueuedLaunchFailureUnlocked(id, error));
+        }
+        catch (recordError) {
+            console.error(`spex: session ${id}: queued launch failure could not be recorded: ${recordError instanceof Error ? recordError.message : String(recordError)}; original failure: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        await clearPendingWatchSnapshots(id);
+    })
+        .finally(() => launching.delete(id));
+}
+// Launch a prepared `queued` worktree. Deterministic blockers retire its creation snapshot debt; a transport
+// attempt that may succeed on the next drain keeps that durable debt for the eventual real outcome.
+async function startQueuedUnlocked(id) {
+    if (archiving.has(id))
+        return 'retryable';
+    const wt = await findWorktree(id);
+    if (!wt)
+        return 'blocked';
+    if (archiving.has(id))
+        return 'retryable';
+    if (wt.rec.archived)
+        return 'blocked';
+    if (!canDrainQueued(wt.rec))
+        return 'retryable';
+    const h = harnessById(wt.rec.harness || defaultHarness.id);
+    if (h.launchPayloadProof && existsSync(sessionArtifactPath(id, 'launch.proof'))) {
+        launching.add(id);
+        let readinessOwnsSlot = false;
+        try {
+            try {
+                consumeHarnessLaunchProofUnlocked(id);
+            }
+            catch (error) {
+                noteQueuedLaunchFailureUnlocked(id, error);
+                throw error;
+            }
+            const recovered = readRecord(id) || wt.rec;
+            writeRecord({ ...recovered, status: 'active', proposal: null, note: null, launchOwner: null });
+            observeQueuedLaunchReadiness(id, h);
+            readinessOwnsSlot = true;
+            return 'started';
+        }
+        finally {
+            if (!readinessOwnsSlot)
+                launching.delete(id);
+        }
+    }
+    const launchPrompt = readLaunchFile(id);
+    if (launchPrompt == null) {
+        const message = `authoritative resolved launch payload is missing for queued session ${id}; refusing to create an empty thread`;
+        if (wt.rec.note !== message) {
+            console.error(`spex: ${message}`);
+            writeRecord({ ...wt.rec, note: message });
+        }
+        return 'blocked';
+    }
+    // a queued worktree can go missing while it waits (a human cleaned up, a disk moved). Draining it would open
+    // a window that fast-exits and burn the retry budget every tick, so refuse ONCE, loudly, and stamp the reason
+    // on the record — the drainer then leaves it alone instead of spinning on a launch that cannot work.
+    const blocked = launchPreflight(wt.rec);
+    if (blocked) {
+        if (wt.rec.note !== blocked.message) {
+            console.error(`spex: not launching queued session ${id}: ${blocked.message}`);
+            writeRecord({ ...wt.rec, note: blocked.message });
+        }
+        return 'blocked';
+    }
+    launching.add(id); // hold the slot across the boot window BEFORE we launch, so a concurrent count can't race us
+    let readinessOwnsSlot = false;
+    try {
+        try {
+            const sq = shQuote(launchPrompt);
+            await launch(id, wt.path, `${h.sessionIdArg(id)} ${sq}`.trim(), h, launcherCmd(wt.rec));
+        }
+        catch {
+            return 'retryable'; // launch failed → stays `queued`, with its initial debt, for the next drain tick
+        }
+        // the note this record may carry is the QUEUED state's word (a launch-blocker message stamped above); the
+        // launch just succeeded, so it is spent. Clearing it with the transition is what keeps "a stored note
+        // belongs to the state currently declared" true for every writer — the invariant [[session-label]]'s
+        // headline precedence stands on.
+        const launched = readRecord(id) || wt.rec;
+        writeRecord({ ...launched, status: 'active', proposal: null, note: null, launchOwner: null });
+        if (!h.launchPayloadProof)
+            removeLaunchFile(id);
+        // release the boot-window hold once the socket is up (then isOccupying takes over) or after the bounded
+        // wait — so a launch that never booted reads offline and the drainer reclaims the slot instead of pinning it.
+        observeQueuedLaunchReadiness(id, h);
+        readinessOwnsSlot = true;
+        return 'started';
+    }
+    finally {
+        if (!readinessOwnsSlot)
+            launching.delete(id);
+    }
+}
+const startQueued = (id) => withSessionTransition(id, () => withRecordLock(id, () => startQueuedUnlocked(id)));
+async function drainQueueUnlocked() {
+    if (draining)
+        return;
+    draining = true;
+    try {
+        const cap = maxActive(); // read once per drain pass (spexcode.json → env → default); won't shift mid-burst
+        for (;;) {
+            const [sessions, snap] = await Promise.all([listSessions(), liveSnapshot()]);
+            for (const session of sessions) {
+                const rec = readRecord(session.id);
+                if (!rec || launching.has(session.id) || !readWatchEntries(session.id).some((entry) => entry.snapshotPending))
+                    continue;
+                if (rec.status === 'queued')
+                    continue;
+                if (rec.status === 'active' && !rec.stopped && !rec.archived) {
+                    launching.add(session.id);
+                    observeQueuedLaunchReadiness(session.id, harnessById(rec.harness || defaultHarness.id));
+                    continue;
+                }
+                await deliverPendingWatchSnapshots(session.id, false);
+            }
+            // if the liveness probe FAILED (tmux timing out — the overload condition), occupancy is UNKNOWABLE: every
+            // session would read window-less and isOccupying would undercount, so the drainer would OVER-launch and pile
+            // MORE compute onto an already-thrashing box. Under load, do the safe thing — launch nothing this pass and
+            // let the next tick re-drain once the probe recovers ([[state]] board honesty applied to the cap).
+            if (snap.probeFailed)
+                break;
+            const occupied = sessions.reduce((n, s) => n + (launching.has(s.id) || isOccupying(s, snap) ? 1 : 0), 0);
+            if (occupied >= cap) {
+                const authority = backendLaunchAuthority();
+                await Promise.all(sessions.filter((session) => {
+                    if (session.status !== 'queued')
+                        return false;
+                    const rec = readRecord(session.id);
+                    return !!rec && canDrainQueued(rec, authority);
+                }).map((session) => deliverPendingWatchSnapshots(session.id)));
+                break;
+            }
+            const authority = backendLaunchAuthority();
+            const next = sessions.find((s) => {
+                if (s.status !== 'queued' || launching.has(s.id))
+                    return false;
+                const rec = readRecord(s.id);
+                return !!rec && canDrainQueued(rec, authority);
+            });
+            if (!next)
+                break;
+            const started = await startQueued(next.id);
+            if (started !== 'started') {
+                if (started === 'blocked')
+                    await clearPendingWatchSnapshots(next.id);
+                break; // launch failed → stop this pass; a later tick retries
+            }
+        }
+    }
+    finally {
+        draining = false;
+    }
+}
+export const drainQueue = () => drainQueueUnlocked();
+const requestQueueDrain = () => {
+    void drainQueue().catch((error) => {
+        console.error(`spex: queue drain failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+};
+let supervisingQueue = false;
+export function superviseQueue(intervalMs = 3000) {
+    if (supervisingQueue)
+        return;
+    supervisingQueue = true;
+    const tick = async () => {
+        try {
+            await drainQueue();
+        }
+        catch { /* transient git/tmux hiccup; next tick retries */ }
+        setTimeout(tick, intervalMs);
+    };
+    void tick();
+}
+let supervisingDelivery = false;
+// @@@ superviseDelivery - the RETRY half of [[delivery-queue]]. `sendText` hands over in its own process, which
+// covers the live case; this covers everything that could not be handed over then — a harness mid-restart, a
+// pane in the one state that swallows prompts, a session that was offline when the message arrived. Owned by
+// the serve that serves this project root, so a message owed to a worker is delivered when the worker can take
+// it rather than when it happens to run a tool. A tick with nothing owed is one existsSync per session, and
+// concurrent serves are harmless: the queue's lock, not the process, is what makes a handover exactly-once.
+export function superviseDelivery(intervalMs = 2000) {
+    if (supervisingDelivery)
+        return;
+    supervisingDelivery = true;
+    const tick = async () => {
+        try {
+            for (const id of listSessionIds()) {
+                if (!owesDelivery(id))
+                    continue;
+                try {
+                    await drainSession(id);
+                }
+                catch { /* an adapter that refused stays owed; next tick retries */ }
+            }
+        }
+        catch { /* transient store read; next tick retries */ }
+        setTimeout(tick, intervalMs).unref();
+    };
+    void tick();
+}
+const turnFailureObservers = new Map();
+let supervisingTurnFailures = false;
+const TURN_FAILURE_OBSERVER_STABLE_MS = 5000;
+export function turnFailureNote(harness, failure) {
+    const message = failure.message.replace(/\s+/g, ' ').trim().slice(0, 500) || 'turn failed';
+    const at = failure.completedAt == null ? '' : ` at ${new Date(failure.completedAt * 1000).toISOString()}`;
+    return `${harness} turn failed${at}: ${message}`;
+}
+export function turnFailureRetryDelay(failures) {
+    return Math.min(30_000, 1000 * 2 ** Math.max(0, Math.min(failures - 1, 5)));
+}
+function deferTurnFailureObserver(id, harness, state, reason) {
+    state.subscription = null;
+    state.failures++;
+    const delay = turnFailureRetryDelay(state.failures);
+    state.retryAt = Date.now() + delay;
+    if (state.lastReason !== reason)
+        console.warn(`[spex ${harness}] turn failure observer for ${id} disconnected (${reason}); retrying in ${delay}ms`);
+    state.lastReason = reason;
+}
+// Reconcile one adapter-owned native failure subscription per live governed session. Product code knows only
+// the optional interface capability; Codex owns WebSocket/thread semantics and Claude keeps using StopFailure.
+export function reconcileTurnFailureObservers() {
+    const wanted = new Map();
+    for (const id of listSessionIds()) {
+        let rec = null;
+        try {
+            rec = readRecord(id);
+        }
+        catch {
+            continue;
+        }
+        if (!rec?.governed || rec.stopped || rec.archived || !rec.harnessSessionId)
+            continue;
+        const harness = harnessById(rec.harness || defaultHarness.id);
+        if (!harness.observeTurnFailures)
+            continue;
+        wanted.set(id, { rec, harness, fingerprint: `${harness.id}:${rec.harnessSessionId}:${runtimeRoot()}` });
+    }
+    for (const [id, state] of turnFailureObservers) {
+        if (wanted.get(id)?.fingerprint === state.fingerprint)
+            continue;
+        turnFailureObservers.delete(id);
+        state.subscription?.close();
+    }
+    for (const [id, target] of wanted) {
+        const now = Date.now();
+        let state = turnFailureObservers.get(id);
+        if (state?.subscription) {
+            if (state.failures > 0 && now - state.startedAt >= TURN_FAILURE_OBSERVER_STABLE_MS) {
+                state.failures = 0;
+                state.retryAt = 0;
+                state.lastReason = null;
+            }
+            continue;
+        }
+        if (state && now < state.retryAt)
+            continue;
+        state ??= { fingerprint: target.fingerprint, subscription: null, startedAt: 0, failures: 0, retryAt: 0, lastReason: null };
+        state.startedAt = now;
+        turnFailureObservers.set(id, state);
+        try {
+            const subscription = target.harness.observeTurnFailures({
+                session: id,
+                worktreePath: target.rec.worktreePath,
+                harnessSessionId: target.rec.harnessSessionId,
+                runtimeDir: runtimeRoot(),
+                launchCmd: target.rec.launchCmd,
+            }, (failure) => {
+                if (turnFailureObservers.get(id)?.fingerprint !== target.fingerprint)
+                    return;
+                try {
+                    markTurnFailure(id, turnFailureNote(target.harness.id, failure));
+                }
+                catch (error) {
+                    console.error(`[spex ${target.harness.id}] could not record native turn failure for ${id}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            });
+            state.subscription = subscription;
+            void subscription.closed.then((reason) => {
+                if (turnFailureObservers.get(id) !== state)
+                    return;
+                if (reason)
+                    deferTurnFailureObserver(id, target.harness.id, state, reason);
+                else
+                    turnFailureObservers.delete(id);
+            });
+        }
+        catch (error) {
+            deferTurnFailureObserver(id, target.harness.id, state, error instanceof Error ? error.message : String(error));
+        }
+    }
+}
+export function superviseTurnFailures(intervalMs = 1000) {
+    if (supervisingTurnFailures)
+        return;
+    supervisingTurnFailures = true;
+    const tick = () => {
+        try {
+            reconcileTurnFailureObservers();
+        }
+        catch (error) {
+            console.error(`spex: turn failure reconciliation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const timer = setTimeout(tick, intervalMs);
+        timer.unref?.();
+    };
+    tick();
+}
+function assertProjectRootMatch(verb, target, servedRoot) {
+    const { url, source } = target;
+    if (source === 'flag')
+        return; // explicitly routed — the caller named the target
+    let localMain;
+    try {
+        localMain = realpathSync(mainRoot());
+    }
+    catch {
+        return;
+    } // caller not in a repo → can't prove a mismatch
+    if (!servedRoot || !isAbsolute(servedRoot))
+        return; // unknown / config-aliased root → don't risk a false refusal
+    let backendMain;
+    try {
+        backendMain = realpathSync(servedRoot);
+    }
+    catch {
+        return;
+    } // backend root not a local path → a remote backend, allow
+    if (backendMain !== localMain) {
+        const e = new Error(`${verb}: refusing WRITE — cwd is in ${localMain} but the backend at ${url} serves ${backendMain}.\n` +
+            `Name the target explicitly (--api <url> / --port <n>) to write cross-project on purpose,\n` +
+            `or run this project's own backend:  cd ${localMain} && spex serve.  (Reads stay unguarded.)`);
+        e.name = 'GuardError';
+        throw e;
+    }
+}
+function assertProjectSettingsMatch(verb, target, settings) {
+    assertProjectRootMatch(verb, target, settings?.layout?.main ?? null);
+}
+function assertProjectInstanceMatch(verb, target, instance) {
+    const root = instance?.root;
+    if (typeof root !== 'string' || !isAbsolute(root))
+        return;
+    let servedMain;
+    try {
+        servedMain = mainRoot(root);
+    }
+    catch {
+        return;
+    }
+    assertProjectRootMatch(verb, target, servedMain);
+}
+export async function assertProjectMatch(verb) {
+    const target = await apiBaseInfo();
+    if (target.source === 'flag')
+        return;
+    let settings = null;
+    try {
+        const r = await fetch(`${target.url}/api/settings`);
+        if (r.ok)
+            settings = await r.json();
+    }
+    catch {
+        return;
+    } // backend unreachable → the write itself surfaces it (fail-loud there)
+    assertProjectSettingsMatch(verb, target, settings);
+}
+export class SessionCreateError extends Error {
+    code;
+    phase;
+    status;
+    constructor(code, phase, message, status) {
+        super(message);
+        this.code = code;
+        this.phase = phase;
+        this.status = status;
+        this.name = 'SessionCreateError';
+    }
+}
+const DEFAULT_CREATE_TIMEOUT_MS = 30_000;
+export function sessionCreateTimeoutMs(env = process.env) {
+    const configured = Number(env.SPEXCODE_SESSION_CREATE_TIMEOUT_MS);
+    return Number.isFinite(configured) ? Math.max(250, Math.min(120_000, Math.floor(configured))) : DEFAULT_CREATE_TIMEOUT_MS;
+}
+function normalizeCreateKey(raw) {
+    const key = raw?.trim() || randomUUID();
+    if (key.length > 128 || !/^[\x21-\x7e]+$/.test(key)) {
+        throw new SessionCreateError('session_create_failed', 'request', 'Idempotency-Key must be 1-128 visible ASCII characters', 400);
+    }
+    return key;
+}
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+export function sessionIdForCreateKey(key) {
+    const hex = digest(`spexcode-session-create\0${key}`);
+    const uuid = `${hex.slice(0, 12)}4${hex.slice(13, 16)}${((parseInt(hex[16], 16) & 3) | 8).toString(16)}${hex.slice(17)}`;
+    return `${uuid.slice(0, 8)}-${uuid.slice(8, 12)}-${uuid.slice(12, 16)}-${uuid.slice(16, 20)}-${uuid.slice(20, 32)}`;
+}
+function traceSessionCreate(id, requestDigest, phase, event, detail) {
+    console.error(`spex session-create ${JSON.stringify({ ts: new Date().toISOString(), request: requestDigest.slice(0, 12), session: id, phase, event, ...(detail ? { detail } : {}) })}`);
+}
+function createAbortError(signal, phase) {
+    const timedOut = signal.reason instanceof SessionCreateError && signal.reason.code === 'session_create_timeout';
+    return new SessionCreateError(timedOut ? 'session_create_timeout' : 'session_create_cancelled', phase, timedOut ? `session creation timed out during ${phase}` : `session creation was cancelled during ${phase}`, timedOut ? 504 : 408);
+}
+function throwIfCreateAborted(signal, phase) {
+    if (signal.aborted)
+        throw createAbortError(signal, phase);
+}
+// The API create boundary accepts one small, closed object shape. Unknown fields fail through this generic
+// contract before any worktree is made; removed or misspelled inputs never disappear into defaults.
+export async function sessionCreateRequest(body, options = {}) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return { status: 400, error: 'body must be a JSON object' };
+    const input = body;
+    const unknown = Object.keys(input).filter((key) => !['prompt', 'parent', 'launcher', 'name', 'base'].includes(key)).sort();
+    if (unknown.length)
+        return { status: 400, error: `unknown session-create field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}` };
+    const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+    if (!prompt.trim())
+        return { status: 400, error: 'empty prompt' };
+    const launcher = typeof input.launcher === 'string' && input.launcher.trim() ? input.launcher.trim() : undefined;
+    const parent = typeof input.parent === 'string' && input.parent.trim() ? input.parent.trim() : null;
+    if (input.name !== undefined && typeof input.name !== 'string')
+        return { status: 400, error: 'session-create name must be a string' };
+    const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : null;
+    if (input.base !== undefined && typeof input.base !== 'string')
+        return { status: 400, error: 'session-create base must be a string' };
+    const base = typeof input.base === 'string' && input.base.trim() ? input.base.trim() : null;
+    let key;
+    try {
+        key = normalizeCreateKey(options.requestKey);
+    }
+    catch (error) {
+        const failure = error;
+        return { status: failure.status, error: failure.message, code: failure.code, phase: failure.phase };
+    }
+    const requestDigest = digest(key);
+    const id = sessionIdForCreateKey(key);
+    // Keep no-name retries byte-compatible with pre-name receipts; an explicit non-empty name is one more
+    // immutable creation input because it publishes the record's existing display override. `base` joins them
+    // for the same reason and with the same shape: absent, it must not perturb an existing receipt's bytes.
+    const payloadHash = digest(JSON.stringify({ prompt, parent, launcher: launcher ?? null, ...(name ? { name } : {}), ...(base ? { base } : {}) }));
+    const controller = new AbortController();
+    const cancel = () => controller.abort(new SessionCreateError('session_create_cancelled', 'request', 'session creation caller disconnected', 408));
+    if (options.signal?.aborted)
+        cancel();
+    else
+        options.signal?.addEventListener('abort', cancel, { once: true });
+    const timer = setTimeout(() => controller.abort(new SessionCreateError('session_create_timeout', 'request', 'session creation exceeded its deadline', 504)), options.timeoutMs ?? sessionCreateTimeoutMs());
+    timer.unref?.();
+    traceSessionCreate(id, requestDigest, 'request', 'start');
+    try {
+        try {
+            const session = await prepareSession(prompt, parent, launcher, name, { id, requestDigest, payloadHash, base, signal: controller.signal });
+            traceSessionCreate(id, requestDigest, 'request', 'finish');
+            return { status: 201, session };
+        }
+        catch (error) {
+            const failure = error instanceof SessionCreateError
+                ? error
+                : controller.signal.aborted
+                    ? createAbortError(controller.signal, 'request')
+                    : new SessionCreateError('session_create_failed', 'request', String(error.message || error), 400);
+            return { status: failure.status, error: failure.message, code: failure.code, phase: failure.phase };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}
+function isExplicitConnectionRefused(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    if (error.code === 'ECONNREFUSED')
+        return true;
+    const errors = error.errors;
+    if (Array.isArray(errors))
+        return errors.length > 0 && errors.every(isExplicitConnectionRefused);
+    return isExplicitConnectionRefused(error.cause);
+}
+async function probeSessionCreateAuthority(target) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    timer.unref?.();
+    let response;
+    try {
+        response = await fetch(`${target.url}/api/instance`, { signal: controller.signal });
+    }
+    catch (error) {
+        clearTimeout(timer);
+        if (isExplicitConnectionRefused(error))
+            return true;
+        const failed = new Error(`backend availability is indeterminate at ${target.url}; refusing in-process session creation (${error instanceof Error ? error.message : error})`);
+        failed.name = 'BackendError';
+        Object.assign(failed, { code: 'backend_availability_indeterminate', cause: error });
+        throw failed;
+    }
+    try {
+        let instance = null;
+        if (response.ok) {
+            try {
+                instance = await response.json();
+            }
+            catch { /* an HTTP response already established backend authority */ }
+        }
+        assertProjectInstanceMatch('spex session new', target, instance);
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function createSession(prompt, launcher, name, base) {
+    const parent = ownSessionId();
+    const requestKey = randomUUID();
+    const body = { prompt, parent, launcher, ...(name !== undefined ? { name } : {}), ...(base !== undefined ? { base } : {}) };
+    const target = await apiBaseInfo();
+    const apiUrl = target.url;
+    const refused = await probeSessionCreateAuthority(target);
+    if (refused) {
+        console.error('spex: no backend reachable — launching in-process (caller env owns auth, no concurrency cap)');
+        const fallback = await sessionCreateRequest(body, { requestKey });
+        if (fallback.status === 201)
+            return fallback.session;
+        const error = new Error(`${fallback.code || 'session_create_failed'}: ${fallback.error}`);
+        error.name = 'BackendError';
+        throw error;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('backend session-create request timed out')), sessionCreateTimeoutMs() + 5_000);
+    timer.unref?.();
+    let res;
+    try {
+        res = await fetch(`${apiUrl}/api/sessions`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'Idempotency-Key': requestKey },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        const failed = new Error(`backend session create failed without fallback after admission began: ${error instanceof Error ? error.message : error}`);
+        failed.name = 'BackendError';
+        throw failed;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        let msg = text;
+        try {
+            msg = JSON.parse(text).error || text;
+        }
+        catch { }
+        const err = new Error(`backend rejected session (${res.status}): ${msg}`);
+        err.name = 'BackendError';
+        throw err;
+    }
+    return await res.json();
+}
+export function spawnerClause(p) {
+    if (!p?.worktreePath)
+        return '';
+    const who = p.name || p.title;
+    return `\n\nYou were created by session \`${p.session.slice(0, 8)}\`${who ? ` (${who})` : ''}, whose worktree is ${p.worktreePath}` +
+        `${p.branch ? ` on branch \`${p.branch}\`` : ''}. Your own worktree is branched from \`${mainBranch()}\`, so it does NOT contain that ` +
+        `session's uncommitted or unmerged work — a spec node it just created, an edit it hasn't landed. If your task needs anything of theirs, ` +
+        `read it there directly. Read only: never write into another session's worktree.`;
+}
+function sessionCreateFailureRecord(rec, error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(`spex: materialize failed for worktree ${rec.worktreePath} — hooks/contract not materialized, worker launches UNGOVERNED: ${msg}`);
+    return { ...rec, note: `materialize failed at creation — worker ungoverned (no hooks/contract): ${msg}` };
+}
+// A materialize failure can leave a tracked contract or .gitignore half-written. Until publication this is
+// still creation-owned preparation: no worker can have authored work here, so restore HEAD and remove its
+// untracked artifacts rather than publish a queued record that close must preserve as possibly-user-dirty.
+// Disable checkout hooks: recovery is not another anchor that may recreate the failed materialization.
+async function resetFailedMaterializeCandidate(rec, signal) {
+    throwIfCreateAborted(signal, 'materialize');
+    const reset = await gitTry(['-C', rec.worktreePath, '-c', 'core.hooksPath=/dev/null', 'reset', '--hard', '--quiet', 'HEAD']);
+    if (!reset.ok) {
+        const detail = (reset.stderr || reset.stdout || 'git reset failed without diagnostic').trim();
+        throw new SessionCreateError('session_create_failed', 'materialize', `materialize failed and its prepared worktree could not be restored: ${detail}`, 500);
+    }
+    const clean = await gitTry(['-C', rec.worktreePath, '-c', 'core.hooksPath=/dev/null', 'clean', '-fd', '-e', 'spexcode.local.json']);
+    if (clean.ok)
+        return;
+    const detail = (clean.stderr || clean.stdout || 'git clean failed without diagnostic').trim();
+    throw new SessionCreateError('session_create_failed', 'materialize', `materialize failed and its prepared worktree could not be restored: ${detail}`, 500);
+}
+async function materializeSessionCandidate(rec, signal) {
+    throwIfCreateAborted(signal, 'materialize');
+    try {
+        await new Promise((resolvePromise, reject) => {
+            const child = spawn(process.execPath, [...cliEntrypointArgs(pkgRoot(), dirname(fileURLToPath(import.meta.url))), 'materialize'], {
+                cwd: rec.worktreePath,
+                env: process.env,
+                detached: true,
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+            let stderr = '', settled = false;
+            const killTree = () => {
+                if (!child.pid)
+                    return;
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* process group already gone */ }
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* child already gone */ }
+            };
+            const abort = () => killTree();
+            signal.addEventListener('abort', abort, { once: true });
+            child.stderr.setEncoding('utf8').on('data', (chunk) => { if (stderr.length < 64 * 1024)
+                stderr += chunk; });
+            child.once('error', (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener('abort', abort);
+                reject(error);
+            });
+            child.once('close', (code, childSignal) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener('abort', abort);
+                if (signal.aborted) {
+                    reject(createAbortError(signal, 'materialize'));
+                    return;
+                }
+                if (code === 0) {
+                    resolvePromise();
+                    return;
+                }
+                reject(new Error(`materialize exited ${childSignal || code}${stderr.trim() ? `: ${stderr.trim()}` : ''}`));
+            });
+            if (signal.aborted)
+                abort();
+        });
+        return rec;
+    }
+    catch (error) {
+        if (signal.aborted || error instanceof SessionCreateError)
+            throw createAbortError(signal, 'materialize');
+        const failed = sessionCreateFailureRecord(rec, error);
+        await resetFailedMaterializeCandidate(rec, signal);
+        return failed;
+    }
+}
+const sessionCandidateReceiptDir = () => join(runtimeRoot(), '.session-create-candidates');
+const sessionCandidateReceiptPath = (id) => join(sessionCandidateReceiptDir(), `${id}.json`);
+const sessionCandidateLockId = (path, branch) => `create-resource-${digest(`${path}\0${branch}`)}`;
+// The graph watcher uses this private fence to avoid rebuilding the full board while Git is still
+// registering a session candidate. The receipt is written before `git worktree add` and retired only
+// after publication or bounded cleanup, so the path names exactly the transaction-owned worktree.
+export function pendingSessionCreateWorktreePaths() {
+    const paths = new Set();
+    let entries;
+    try {
+        entries = readdirSync(sessionCandidateReceiptDir(), { withFileTypes: true });
+    }
+    catch {
+        return paths;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        try {
+            const value = JSON.parse(readFileSync(join(sessionCandidateReceiptDir(), entry.name), 'utf8'));
+            if (typeof value.path === 'string' && value.path && typeof value.stage === 'string')
+                paths.add(resolve(value.path));
+        }
+        catch { /* an in-flight atomic replace is not a candidate path */ }
+    }
+    return paths;
+}
+function readSessionCandidateReceipt(id) {
+    const path = sessionCandidateReceiptPath(id);
+    if (!existsSync(path))
+        return { kind: 'absent' };
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        const prestate = value.prestate;
+        if (value.version !== 1 || typeof value.requestDigest !== 'string' || typeof value.payloadHash !== 'string'
+            || typeof value.root !== 'string' || typeof value.path !== 'string' || typeof value.branch !== 'string'
+            || !prestate || prestate.store !== false || prestate.path !== false || prestate.worktree !== false || prestate.branch !== false
+            || !['prepared', 'git-created', 'store-created'].includes(value.stage)) {
+            return { kind: 'invalid', error: `invalid private candidate receipt at ${path}` };
+        }
+        return { kind: 'valid', receipt: value };
+    }
+    catch (error) {
+        return { kind: 'invalid', error: `invalid private candidate receipt at ${path}: ${error instanceof Error ? error.message : error}` };
+    }
+}
+function writeSessionCandidateReceipt(id, receipt) {
+    const dir = sessionCandidateReceiptDir();
+    mkdirSync(dir, { recursive: true });
+    const path = sessionCandidateReceiptPath(id);
+    const tmp = join(dir, `.${id}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tmp, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    finally {
+        rmSync(tmp, { force: true });
+    }
+}
+function retireSessionCandidateReceipt(id) {
+    try {
+        rmSync(sessionCandidateReceiptPath(id), { force: true });
+    }
+    catch {
+        return false;
+    }
+    return !existsSync(sessionCandidateReceiptPath(id));
+}
+function sessionCandidateReceiptMatches(receipt, context, root, path, branch) {
+    return receipt.requestDigest === context.requestDigest && receipt.payloadHash === context.payloadHash
+        && receipt.root === root && receipt.path === path && receipt.branch === branch;
+}
+function publishedSessionCandidateReceiptRetirementFailure(rec, root) {
+    const durable = readSessionCandidateReceipt(rec.session);
+    if (durable.kind === 'absent')
+        return null;
+    if (durable.kind === 'invalid')
+        return durable.error;
+    if (!rec.createRequestId || !rec.createPayloadHash || !rec.branch || !rec.worktreePath
+        || durable.receipt.requestDigest !== rec.createRequestId || durable.receipt.payloadHash !== rec.createPayloadHash
+        || durable.receipt.root !== root || durable.receipt.path !== rec.worktreePath || durable.receipt.branch !== rec.branch) {
+        return `private candidate receipt at ${sessionCandidateReceiptPath(rec.session)} does not match the published record`;
+    }
+    if (!retireSessionCandidateReceipt(rec.session))
+        return `private candidate receipt remains at ${sessionCandidateReceiptPath(rec.session)}`;
+    return readSessionCandidateReceipt(rec.session).kind === 'absent'
+        ? null
+        : `private candidate receipt retirement is unproven at ${sessionCandidateReceiptPath(rec.session)}`;
+}
+async function retirePublishedSessionCandidateReceipt(rec, context) {
+    if (!rec.branch || !rec.worktreePath)
+        return;
+    if (readSessionCandidateReceipt(rec.session).kind === 'absent')
+        return;
+    const root = mainRoot(), path = rec.worktreePath, branch = rec.branch;
+    await withRecordLock(sessionCandidateLockId(path, branch), async () => {
+        const failure = publishedSessionCandidateReceiptRetirementFailure(rec, root);
+        if (failure)
+            console.error(`spex: published session ${rec.session.slice(0, 8)} remains the fence for its candidate receipt: ${failure}`);
+    }, context.signal);
+}
+async function sessionCandidateState(root, path, branch, signal) {
+    const [listed, ref] = await withGitAbortSignal(signal, () => Promise.all([
+        gitTry(['-C', root, 'worktree', 'list', '--porcelain', '-z']),
+        gitTry(['-C', root, 'show-ref', '--verify', '--quiet', `refs/heads/${branch}`]),
+    ]));
+    if (!listed.ok)
+        throw new SessionCreateError('session_create_failed', 'git-worktree', `cannot read worktree registry: ${listed.stderr.trim() || listed.failure}`, 500);
+    if (!ref.ok && ref.failure !== 'exit')
+        throw new SessionCreateError('session_create_failed', 'git-worktree', `cannot read candidate branch: ${ref.stderr.trim() || ref.failure}`, 500);
+    return { path: existsSync(path), worktree: listed.stdout.split('\0').includes(`worktree ${path}`), branch: ref.ok };
+}
+async function cleanupSessionCandidate(root, id, path, branch, owned) {
+    const residues = [];
+    if (owned.store) {
+        try {
+            rmSync(sessionStoreDir(id), { recursive: true, force: true });
+        }
+        catch { /* verified below */ }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    timer.unref?.();
+    try {
+        await withGitAbortSignal(controller.signal, async () => {
+            if (owned.worktree) {
+                const removed = await gitTry(['-C', root, 'worktree', 'remove', '--force', path]);
+                if (!removed.ok)
+                    residues.push(`worktree remove failed: ${removed.stderr.trim() || removed.failure}`);
+            }
+            const afterRemove = await sessionCandidateState(root, path, branch, controller.signal);
+            if (owned.path && afterRemove.path && !afterRemove.worktree) {
+                try {
+                    rmSync(path, { recursive: true, force: true });
+                }
+                catch { /* verified below */ }
+            }
+            const ref = `refs/heads/${branch}`;
+            if (owned.branch) {
+                const deleted = await gitTry(['-C', root, 'branch', '-D', branch]);
+                if (!deleted.ok)
+                    residues.push(`branch delete failed: ${deleted.stderr.trim() || deleted.failure}`);
+            }
+            const state = await sessionCandidateState(root, path, branch, controller.signal);
+            if ((owned.path && state.path) || (owned.worktree && state.worktree))
+                residues.push(`owned worktree remains at ${path}`);
+            if (owned.branch && state.branch)
+                residues.push(`owned branch remains at ${ref}`);
+            if ((!owned.path && state.path) || (!owned.worktree && state.worktree))
+                residues.push(`unowned candidate worktree preserved at ${path}`);
+            if (!owned.branch && state.branch)
+                residues.push(`unowned candidate branch preserved at ${ref}`);
+        });
+    }
+    catch (error) {
+        residues.push(`Git cleanup did not settle: ${error instanceof Error ? error.message : error}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (owned.store && existsSync(sessionStoreDir(id)))
+        residues.push(`owned session store remains at ${sessionStoreDir(id)}`);
+    return residues;
+}
+function existingCreateReceipt(rec) {
+    const h = harnessById(rec.harness || defaultHarness.id);
+    if (rec.status === 'queued')
+        return toSession(rec, 'queued', 'offline');
+    const status = rec.status === 'active' ? 'working' : rec.status === 'awaiting' ? PROPOSAL_STATUS[rec.proposal ?? 'nothing'] : rec.status;
+    return toSession(rec, status, rec.stopped ? 'offline' : h.headless ? 'online' : 'starting');
+}
+async function proveSessionCandidate(path, branch, signal) {
+    const [top, checkedOut, ref] = await withGitAbortSignal(signal, () => Promise.all([
+        gitTry(['-C', path, 'rev-parse', '--show-toplevel']),
+        gitTry(['-C', path, 'symbolic-ref', '--quiet', '--short', 'HEAD']),
+        gitTry(['-C', mainRoot(), 'show-ref', '--verify', '--quiet', `refs/heads/${branch}`]),
+    ]));
+    if (!top.ok || !checkedOut.ok || !ref.ok)
+        return [top.stderr, checkedOut.stderr, ref.stderr].map((value) => value.trim()).filter(Boolean).join('; ') || 'Git identity validation failed';
+    let actualTop = top.stdout.trim();
+    try {
+        actualTop = realpathSync(actualTop);
+    }
+    catch { /* missing path is reported by the comparison */ }
+    let expectedTop = path;
+    try {
+        expectedTop = realpathSync(path);
+    }
+    catch { /* missing path is reported by the comparison */ }
+    if (actualTop !== expectedTop)
+        return `worktree top-level is ${actualTop}, expected ${expectedTop}`;
+    if (checkedOut.stdout.trim() !== branch)
+        return `worktree checked out ${checkedOut.stdout.trim() || '(detached)'}, expected ${branch}`;
+    return null;
+}
+async function prepareSession(prompt, parent, launcher, name, context) {
+    const { id, requestDigest, payloadHash, base, signal } = context;
+    let phase = 'creation-lock';
+    let shouldDrain = false;
+    traceSessionCreate(id, requestDigest, phase, 'start');
+    try {
+        const receipt = await withRecordLock(id, async () => {
+            const existing = readRecord(id);
+            if (existing) {
+                if (existing.createRequestId !== requestDigest || existing.createPayloadHash !== payloadHash) {
+                    throw new SessionCreateError('session_create_key_reused', 'creation-lock', 'Idempotency-Key is already bound to another session-create payload', 409);
+                }
+                await retirePublishedSessionCandidateReceipt(existing, context);
+                return existingCreateReceipt(existing);
+            }
+            phase = 'launcher-resolution';
+            traceSessionCreate(id, requestDigest, phase, 'start');
+            let chosen;
+            let h;
+            let pinned;
+            try {
+                const lname = launcher ?? defaultLauncher(mainRoot());
+                chosen = resolveLauncher(lname);
+                h = harnessById(chosen.harness);
+                pinned = h.baseCmd(chosen.cmd);
+                if (h.ownsRendezvous)
+                    assertRvSockPath(id);
+            }
+            catch (error) {
+                throw new SessionCreateError('session_create_failed', phase, error instanceof Error ? error.message : String(error), 400);
+            }
+            traceSessionCreate(id, requestDigest, phase, 'finish');
+            phase = 'target-resolution';
+            traceSessionCreate(id, requestDigest, phase, 'start');
+            throwIfCreateAborted(signal, phase);
+            const rawPrompt = prompt;
+            const ref = nodeFromPrompt(rawPrompt);
+            const launchSpecs = ref ? loadSpecsLite() : null;
+            const title = ref ? null : titleFromPrompt(rawPrompt);
+            const slug = `${slugify(ref || title)}-${id.slice(0, 4)}`;
+            const root = mainRoot();
+            // An explicit base pins the fork point so a run is reproducible against a frozen commit instead of
+            // whatever the source-of-truth branch has drifted to. Resolve it here, before any git mutation: an
+            // unknown ref must fail the create request outright, never leave a half-made worktree behind.
+            const startPoint = base ?? mainBranch();
+            if (base) {
+                const resolved = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'rev-parse', '--verify', '--quiet', `${base}^{commit}`]));
+                if (!resolved.ok || !resolved.stdout.trim()) {
+                    throw new SessionCreateError('session_create_failed', phase, `session-create base does not name a commit: ${base}`, 400);
+                }
+            }
+            const branch = `${readConfig(dirname(gitCommonDir())).branchPrefix ?? 'node/'}${slug}`;
+            const path = join(root, '.worktrees', slug);
+            const spec = ref ? launchSpecs?.find((node) => node.id === ref) : undefined;
+            const suffix = (spec ? `\n\nThe spec node \`${ref}\` is your ground truth — read its spec at ${join(path, spec.path)}.` : '')
+                + spawnerClause(parent ? readRecord(parent) : null);
+            let launchPrompt;
+            try {
+                launchPrompt = (await composeSessionPrompt(rawPrompt, { session: id, harness: h.id }, {
+                    loadedSpecs: launchSpecs ?? undefined,
+                    suffix: suffix || undefined,
+                })).text;
+            }
+            catch (error) {
+                throw new SessionCreateError('session_create_failed', phase, error instanceof Error ? error.message : String(error), 400);
+            }
+            traceSessionCreate(id, requestDigest, phase, 'finish');
+            phase = 'git-worktree';
+            traceSessionCreate(id, requestDigest, phase, 'start');
+            const resourceLock = sessionCandidateLockId(path, branch);
+            return await withRecordLock(resourceLock, async () => {
+                throwIfCreateAborted(signal, phase);
+                traceSessionCreate(id, requestDigest, phase, 'start', 'candidate-state');
+                let before = await sessionCandidateState(root, path, branch, signal);
+                traceSessionCreate(id, requestDigest, phase, 'finish', 'candidate-state');
+                let storePresent = existsSync(sessionStoreDir(id));
+                const durable = readSessionCandidateReceipt(id);
+                if (durable.kind === 'invalid')
+                    throw new SessionCreateError('session_create_failed', phase, durable.error, 409);
+                if (durable.kind === 'valid') {
+                    if (!sessionCandidateReceiptMatches(durable.receipt, context, root, path, branch)) {
+                        throw new SessionCreateError('session_create_failed', phase, 'private candidate receipt does not match this create request; preserving candidate resources', 409);
+                    }
+                    phase = 'cleanup';
+                    traceSessionCreate(id, requestDigest, phase, 'start', `recover-${durable.receipt.stage}`);
+                    const recovered = await cleanupSessionCandidate(root, id, path, branch, {
+                        store: storePresent, path: before.path, worktree: before.worktree, branch: before.branch,
+                    });
+                    traceSessionCreate(id, requestDigest, phase, recovered.length ? 'abort' : 'finish', recovered.join('; ') || undefined);
+                    if (recovered.length)
+                        throw new SessionCreateError('session_create_cleanup_failed', phase, `matching candidate recovery left residue: ${recovered.join('; ')}`, 500);
+                    before = { path: false, worktree: false, branch: false };
+                    storePresent = false;
+                    phase = 'git-worktree';
+                }
+                else if (storePresent || before.path || before.worktree || before.branch) {
+                    const occupied = [storePresent ? `session store ${sessionStoreDir(id)}` : '', before.path ? `path ${path}` : '', before.worktree ? `registered worktree ${path}` : '', before.branch ? `branch ${branch}` : ''].filter(Boolean).join(', ');
+                    throw new SessionCreateError('session_create_failed', phase, `session target is already occupied: ${occupied}`, 409);
+                }
+                let candidateReceipt = {
+                    version: 1, requestDigest, payloadHash, root, path, branch,
+                    prestate: { store: false, path: false, worktree: false, branch: false }, stage: 'prepared',
+                };
+                writeSessionCandidateReceipt(id, candidateReceipt);
+                const owned = { store: false, path: false, worktree: false, branch: false };
+                let gitMutationStarted = false;
+                let published = false;
+                try {
+                    gitMutationStarted = true;
+                    traceSessionCreate(id, requestDigest, phase, 'start', 'worktree-add');
+                    const added = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'worktree', 'add', '-b', branch, path, startPoint], { extraEnv: DEFER_FOOTPRINT_REFRESH }));
+                    traceSessionCreate(id, requestDigest, phase, 'finish', 'worktree-add');
+                    if (added.ok)
+                        Object.assign(owned, { path: true, worktree: true, branch: true });
+                    if (!added.ok || !existsSync(path)) {
+                        throw new SessionCreateError('session_create_failed', phase, `git worktree add failed: ${added.stderr.trim() || added.failure || 'worktree missing after success'}`, 500);
+                    }
+                    candidateReceipt = { ...candidateReceipt, stage: 'git-created' };
+                    writeSessionCandidateReceipt(id, candidateReceipt);
+                    traceSessionCreate(id, requestDigest, phase, 'finish');
+                    traceSessionCreate(id, requestDigest, phase, 'start', 'seed-worktree-host-state');
+                    seedWorktreeHostState(root, path);
+                    traceSessionCreate(id, requestDigest, phase, 'finish', 'seed-worktree-host-state');
+                    let rec = {
+                        session: id, governed: true, worktreePath: path, branch,
+                        node: ref || null, title, name, parent: parent && parent !== id ? parent : null,
+                        status: 'queued', proposal: null, merges: 0, note: null, sortKey: null, createdAt: Date.now(),
+                        harness: h.id, harnessSessionId: null, stopped: false, archived: false, coldProof: null, adapterRecovery: null, launcher: chosen.name,
+                        launchCmd: pinned, launchOwner: backendLaunchAuthority(), createRequestId: requestDigest, createPayloadHash: payloadHash,
+                        ...(base ? { base } : {}),
+                    };
+                    owned.store = true;
+                    const dir = storeDir(id);
+                    writeFileSync(join(dir, 'prompt'), rawPrompt);
+                    writeFileSync(join(dir, 'launch'), launchPrompt);
+                    candidateReceipt = { ...candidateReceipt, stage: 'store-created' };
+                    writeSessionCandidateReceipt(id, candidateReceipt);
+                    phase = 'materialize';
+                    traceSessionCreate(id, requestDigest, phase, 'start');
+                    rec = await materializeSessionCandidate(rec, signal);
+                    traceSessionCreate(id, requestDigest, phase, 'finish');
+                    phase = 'record-write';
+                    traceSessionCreate(id, requestDigest, phase, 'start');
+                    throwIfCreateAborted(signal, phase);
+                    const gitMismatch = await proveSessionCandidate(path, branch, signal);
+                    if (gitMismatch)
+                        throw new SessionCreateError('session_create_failed', phase, `refusing session publication: ${gitMismatch}`, 500);
+                    throwIfCreateAborted(signal, phase);
+                    writeRecord(rec);
+                    if (rec.parent && readRecord(rec.parent)?.governed) {
+                        const watchers = readWatchEntries(id);
+                        const next = addWatchSource(watchers, rec.parent, 'parent', true);
+                        if (next.added)
+                            writeWatchEntries(id, next.entries);
+                    }
+                    published = true;
+                    const receiptFailure = publishedSessionCandidateReceiptRetirementFailure(rec, root);
+                    if (receiptFailure)
+                        console.error(`spex: published session ${id.slice(0, 8)} remains the fence for its candidate receipt: ${receiptFailure}`);
+                    shouldDrain = true;
+                    traceSessionCreate(id, requestDigest, phase, 'publish');
+                    return toSession(rec, 'queued', 'offline');
+                }
+                catch (error) {
+                    if (published)
+                        throw error;
+                    const failurePhase = error instanceof SessionCreateError ? error.phase : phase;
+                    let ownershipFailure = null;
+                    if (gitMutationStarted && !(owned.path && owned.worktree && owned.branch)) {
+                        const inspection = new AbortController();
+                        const timer = setTimeout(() => inspection.abort(), 10_000);
+                        timer.unref?.();
+                        try {
+                            const after = await sessionCandidateState(root, path, branch, inspection.signal);
+                            owned.path ||= !before.path && after.path;
+                            owned.worktree ||= !before.worktree && after.worktree;
+                            owned.branch ||= !before.branch && after.branch;
+                        }
+                        catch (inspectionError) {
+                            ownershipFailure = `candidate ownership inspection failed: ${inspectionError instanceof Error ? inspectionError.message : inspectionError}`;
+                        }
+                        finally {
+                            clearTimeout(timer);
+                        }
+                    }
+                    phase = 'cleanup';
+                    traceSessionCreate(id, requestDigest, phase, 'start');
+                    const residues = await cleanupSessionCandidate(root, id, path, branch, owned);
+                    if (ownershipFailure)
+                        residues.unshift(ownershipFailure);
+                    if (!residues.length && !retireSessionCandidateReceipt(id))
+                        residues.push(`private candidate receipt remains at ${sessionCandidateReceiptPath(id)}`);
+                    traceSessionCreate(id, requestDigest, phase, residues.length ? 'abort' : 'finish', residues.join('; ') || undefined);
+                    if (residues.length)
+                        throw new SessionCreateError('session_create_cleanup_failed', phase, `session creation failed and cleanup left residue: ${residues.join('; ')}`, 500);
+                    if (signal.aborted) {
+                        phase = failurePhase;
+                        throw createAbortError(signal, failurePhase);
+                    }
+                    throw error instanceof SessionCreateError
+                        ? error
+                        : new SessionCreateError('session_create_failed', failurePhase, error instanceof Error ? error.message : String(error), 500);
+                }
+            }, signal);
+        }, signal);
+        traceSessionCreate(id, requestDigest, 'creation-lock', 'finish');
+        if (shouldDrain) {
+            phase = 'launcher-queue';
+            traceSessionCreate(id, requestDigest, phase, 'start');
+            requestQueueDrain();
+            traceSessionCreate(id, requestDigest, phase, 'finish');
+        }
+        return receipt;
+    }
+    catch (error) {
+        const failure = signal.aborted
+            ? createAbortError(signal, phase)
+            : error instanceof SessionCreateError
+                ? error
+                : new SessionCreateError('session_create_failed', phase, error instanceof Error ? error.message : String(error), 500);
+        traceSessionCreate(id, requestDigest, failure.phase, 'abort', failure.code);
+        throw failure;
+    }
+}
+export function bootstrapMaterialize(rec, doMaterialize = materialize) {
+    try {
+        doMaterialize(rec.worktreePath);
+    }
+    catch (e) {
+        writeRecord(sessionCreateFailureRecord(rec, e));
+    }
+}
+const SOCKET_READY_TIMEOUT_MS = 30000; // spans launchScript's bounded fast-fail relaunch window, so
+// waitForReady (slot-hold + resume) waits through a daemon-race retry
+// instead of returning before a recovering socket
+const SOCKET_POLL_MS = 200;
+async function waitForReady(id, harness, pending, timeoutMs = SOCKET_READY_TIMEOUT_MS, recordLockHeld = false) {
+    const current = () => {
+        const stored = readRecord(id);
+        const rec = stored && pending
+            ? { ...pending, ...stored, stopped: pending.stopped, archived: pending.archived }
+            : stored || pending;
+        return rec ? { ...rec, runtimeDir: runtimeRoot() } : null;
+    };
+    const deadline = Date.now() + timeoutMs;
+    if (harness.launchPayloadProof && !current()?.harnessSessionId) {
+        for (;;) {
+            if (existsSync(sessionArtifactPath(id, 'launch.proof'))) {
+                if (recordLockHeld)
+                    consumeHarnessLaunchProofUnlocked(id);
+                else
+                    await withRecordLock(id, async () => consumeHarnessLaunchProofUnlocked(id));
+                break;
+            }
+            if (Date.now() >= deadline)
+                return null;
+            await new Promise((r) => setTimeout(r, SOCKET_POLL_MS));
+        }
+    }
+    if (harness.launchReady)
+        return harness.launchReady(current, deadline);
+    const genericFence = () => ({
+        proof: Object.freeze({ kind: 'adapter-liveness', harnessId: harness.id, sessionId: id }),
+        validate: async (latest) => {
+            const rec = latest();
+            const snap = await liveSnapshot();
+            return !!rec && harness.liveness(rec, snap.windows.has(id), runtimeRoot(), snap.windows.get(id), snap.sockets.has(id)) === 'online';
+        },
+    });
+    for (;;) {
+        const rec = current();
+        const snap = await liveSnapshot(); // window + pane probe + live-listener set in one snapshot — all the adapter needs
+        if (rec && harness.liveness(rec, snap.windows.has(id), runtimeRoot(), snap.windows.get(id), snap.sockets.has(id)) === 'online')
+            return genericFence();
+        if (Date.now() >= deadline)
+            return null;
+        await new Promise((r) => setTimeout(r, SOCKET_POLL_MS));
+    }
+}
+const restingLifecycle = (status) => status === 'active' || status === 'queued' ? 'idle' : status;
+async function resumeSessionUnlocked(id, opts = {}) {
+    const { force = false, guard = true } = opts;
+    let wt;
+    try {
+        wt = await findWorktree(id);
+    }
+    catch (e) {
+        if (e instanceof SessionRecordUnusable)
+            return { ok: false, refused: true, error: e.message };
+        throw e;
+    }
+    if (!wt)
+        return { ok: false, error: `no such session ${id}` };
+    // A process that died while validating left an internal candidate behind. This record lock proves no live
+    // resume still owns it. Restore the frozen public original before doing any transport work and require an
+    // explicit retry; stale runtime evidence is never adopted into a fresh launch attempt.
+    if (wt.rec.launchReadinessPending) {
+        writeRecord(restoreLaunchReadinessOriginal(wt.rec));
+        return {
+            ok: false,
+            refused: true,
+            error: `session ${id}: stale launch readiness pending was recovered fail-closed; the exact stopped/offline record was retained. Retry resume.`,
+        };
+    }
+    const preResume = wt.rec;
+    // a retired session (its worktree gone) is terminal, not offline: say so in its own words rather than in the
+    // preflight's, since `close` — not a repair — is what it needs.
+    const retired = retirementReason(wt.rec);
+    if (retired)
+        return { ok: false, refused: true, error: retired };
+    // everything else the transport can settle before opening a window: no branch, no launcher. A launch that
+    // cannot succeed must not be attempted, retried, or given a regenerated launch script.
+    const blocked = launchPreflight(wt.rec);
+    if (blocked)
+        return { ok: false, refused: true, error: blocked.message };
+    const h = harnessById(wt.rec.harness || defaultHarness.id);
+    // A prior adapter process may have proven identity + first-turn durability just before its session owner
+    // died. Consume that receipt before choosing a recovery tail, so retry resumes the proven thread instead of
+    // creating another one with the same first prompt.
+    if (h.launchPayloadProof && existsSync(sessionArtifactPath(id, 'launch.proof'))) {
+        consumeHarnessLaunchProofUnlocked(id);
+        wt = await findWorktree(id);
+        if (!wt)
+            return { ok: false, error: `session ${id} disappeared while recovering native launch proof` };
+    }
+    // An archived record is expected to be stopped, but the guard must still inspect physical liveness in case
+    // it is a legacy/invariant-violating row. Ignore filing and stale stop metadata for this one safety probe so
+    // resume can never kill a live leaf merely because the record was hidden.
+    const probeRec = wt.rec.archived ? { ...wt.rec, archived: false, stopped: false } : wt.rec;
+    const resumeSnap = await liveSnapshot();
+    const lv = h.runtimeOwnership === 'adapter'
+        ? (resumeSnap.windows.has(id) ? 'online' : 'offline')
+        : liveness(probeRec, resumeSnap); // FRESH, honest liveness (listener-verified)
+    if (guard && !force && lv === 'online')
+        return { ok: false, refused: true, error: `session ${id} is ALIVE — refusing to relaunch, which would kill a live worker mid-work. To steer it, send it a message; use force only for a genuinely wedged (but alive) process.` };
+    if (guard && !force && lv === 'unknown')
+        return { ok: false, refused: true, error: `session ${id}: the liveness probe failed (the box is likely overloaded) — refusing to relaunch since a live worker can't be ruled out. Retry in a moment, or use force to override.` };
+    const wasArchived = wt.rec.archived;
+    if (!wasArchived && wt.rec.adapterRecovery) {
+        const recovery = await h.restoreRuntime?.(wt.rec);
+        if (recovery && !recovery.ok)
+            return { ok: false, refused: true, error: `session ${id}: recovery required before resume — ${recovery.reason}` };
+        writeRecord({ ...(readRecord(id) || wt.rec), adapterRecovery: null, coldProof: null, archived: false, stopped: true });
+        wt = await findWorktree(id);
+        if (!wt)
+            return { ok: false, error: `session ${id} disappeared during adapter recovery` };
+    }
+    if (wasArchived && (force || lv === 'offline')) {
+        // Make the durable row visible/offline before any adapter unarchive or launch RPC. Any later failure leaves
+        // a retryable unarchived record rather than archived:true with a newly loaded target thread.
+        const pendingRecovery = wt.rec.adapterRecovery || 'restore-runtime-pending';
+        writeRecord({ ...wt.rec, archived: false, stopped: true, coldProof: wt.rec.coldProof, adapterRecovery: pendingRecovery });
+        const visible = readRecord(id) || { ...wt.rec, archived: false, stopped: true, coldProof: wt.rec.coldProof, adapterRecovery: pendingRecovery };
+        const restored = await h.restoreRuntime?.(visible);
+        if (restored && !restored.ok)
+            return { ok: false, refused: true, error: `session ${id}: ${restored.reason}` };
+        writeRecord({ ...(readRecord(id) || visible), adapterRecovery: null, coldProof: null });
+    }
+    // proceeding: settle the RESTING lifecycle (a resumed working agent is now idle), then relaunch iff the agent
+    // is CONFIRMED offline (or force — the wedged-but-alive escape). Clear the explicit-stop marker only after
+    // launch has accepted the relaunch; a thrown launch leaves the record truthfully stopped. `starting`/`unknown`
+    // fall through to a metadata-only no-op.
+    // Archived sessions have no runtime by invariant. Resume first leaves cold storage, then the normal
+    // starting -> online launch path recreates the same conversation.
+    const current = wasArchived ? (readRecord(id) || { ...wt.rec, archived: false, stopped: true, coldProof: null }) : wt.rec;
+    const resumed = { ...current, archived: false, coldProof: null, status: restingLifecycle(current.status), stopped: false };
+    if (force || lv === 'offline') {
+        let resumeTail;
+        try {
+            resumeTail = h.resumeArg(wt.rec, readLaunchFile(id)).trim();
+        }
+        catch (error) {
+            return { ok: false, refused: true, error: error instanceof Error ? error.message : String(error) };
+        }
+        await tmuxOk(['kill-session', '-t', id]); // drop a dead/offline pane (or a force-killed live one)
+        await launch(id, wt.path, resumeTail, h, launcherCmd(wt.rec));
+        let readiness = null;
+        let readinessError = '';
+        try {
+            readiness = await waitForReady(id, h, resumed, SOCKET_READY_TIMEOUT_MS, true);
+        }
+        catch (error) {
+            readinessError = error instanceof Error ? error.message : String(error);
+        }
+        if (!readiness) {
+            const failed = readRecord(id) || current;
+            writeRecord({ ...failed, ...preResume, harnessSessionId: failed.harnessSessionId, launchReadinessPending: null });
+            return {
+                ok: false,
+                refused: true,
+                error: `session ${id}: launch did not become ready${readinessError ? ` - ${readinessError}` : ''}; the session remains stopped and can be retried`,
+            };
+        }
+        const latest = readRecord(id) || resumed;
+        const candidate = {
+            ...latest,
+            archived: false,
+            coldProof: null,
+            status: restingLifecycle(latest.status),
+            stopped: false,
+            launchReadinessPending: launchReadinessPending(preResume),
+        };
+        writeRecord(candidate);
+        let stillReady = false;
+        try {
+            stillReady = await readiness.validate(() => {
+                const stored = readRecord(id);
+                return stored ? { ...stored, runtimeDir: runtimeRoot() } : null;
+            });
+        }
+        catch (error) {
+            readinessError = error instanceof Error ? error.message : String(error);
+        }
+        if (!stillReady) {
+            const failed = readRecord(id) || candidate;
+            writeRecord(restoreLaunchReadinessOriginal(failed));
+            return {
+                ok: false,
+                refused: true,
+                error: `session ${id}: launch readiness changed across the pending publication${readinessError ? ` - ${readinessError}` : ''}; the session remains stopped and can be retried`,
+            };
+        }
+        const published = readRecord(id) || candidate;
+        writeRecord({ ...published, launchReadinessPending: null });
+    }
+    else
+        writeRecord(resumed);
+    return { ok: true };
+}
+export const resumeSession = (id, opts = {}) => withSessionTransition(id, async () => {
+    const result = await withRecordLock(id, () => resumeSessionUnlocked(id, opts));
+    if (result.ok)
+        await drainSession(id);
+    return result;
+});
+export function markState(status, opts = {}) {
+    const id = opts.sessionId || ownSessionId();
+    if (!id)
+        return false;
+    return withRecordLockSync(id, () => {
+        const rec = readLiveRecord(id);
+        if (!rec)
+            return false;
+        const proposal = status === 'awaiting' ? (opts.proposal ?? 'nothing') : null;
+        writeRecord({
+            ...rec, status,
+            proposal,
+            note: opts.note ?? null,
+        });
+        return true;
+    });
+}
+export const markDone = (proposal = 'nothing', sessionId, note) => markState('awaiting', { proposal, note, sessionId });
+export const markError = (sessionId) => markState('error', { sessionId });
+export function markTurnFailure(sessionId, note) {
+    if (!sessionId)
+        return false;
+    return withRecordLockSync(sessionId, () => {
+        const rec = readLiveRecord(sessionId);
+        if (!rec || rec.status !== 'active' || rec.stopped || rec.archived)
+            return false;
+        writeRecord({ ...rec, status: 'error', proposal: null, note });
+        return true;
+    });
+}
+export function markHeadlessTurnFailure(sessionId, harness, exitCode) {
+    if (exitCode === '0')
+        return false;
+    const outcome = /^\d+$/.test(exitCode) ? `exit code ${exitCode}` : `signal ${exitCode}`;
+    return markTurnFailure(sessionId, `${harness} turn exited with ${outcome}`);
+}
+function bindHarnessSessionIdUnlocked(rec, harnessSessionId, generationId = process.env.SPEXCODE_CODEX_GENERATION?.trim()) {
+    const id = rec.session;
+    if (rec.harnessSessionId && rec.harnessSessionId !== harnessSessionId)
+        throw new ResourceConflict(`refusing to replace exact harness thread identity for ${id}; create a new governed session instead`);
+    const codex = rec.harness === 'codex' || rec.harness === 'codex-headless';
+    const root = runtimeRoot();
+    let priorBinding = null;
+    let registrationPrepared = false;
+    if (codex) {
+        const ledger = readCodexGenerationLedger(root);
+        if (ledger.revision > 0 && !generationId)
+            throw new ResourceConflict(`refusing to bind Codex thread ${harnessSessionId}: launch did not provide an exact generation id`);
+        priorBinding = codexGenerationBindingForSession(root, id);
+        if (priorBinding && (!generationId || priorBinding.generationId !== generationId || priorBinding.threadId !== harnessSessionId))
+            throw new ResourceConflict(`refusing to replace exact Codex generation binding for ${id}`);
+        if (generationId && !priorBinding) {
+            prepareCodexGenerationRegistration(root, id, harnessSessionId, generationId);
+            registrationPrepared = true;
+        }
+    }
+    try {
+        writeRecord({ ...rec, harnessSessionId, coldProof: null, adapterRecovery: null });
+    }
+    catch (error) {
+        if (codex && generationId && registrationPrepared) {
+            try {
+                bindCodexGeneration(root, id, harnessSessionId, null);
+            }
+            catch (rollback) {
+                throw new ResourceConflict(`Codex generation binding persisted but session ${id} record write failed and rollback failed: ${rollback instanceof Error ? rollback.message : String(rollback)}`);
+            }
+        }
+        throw error;
+    }
+    if (codex && generationId)
+        commitCodexGenerationRegistration(root, id, harnessSessionId, generationId);
+}
+function readHarnessLaunchProof(id) {
+    try {
+        const proof = JSON.parse(readFileSync(sessionArtifactPath(id, 'launch.proof'), 'utf8'));
+        if (!proof || proof.version !== 1 || typeof proof.sessionId !== 'string'
+            || typeof proof.harnessId !== 'string' || typeof proof.harnessSessionId !== 'string' || !proof.harnessSessionId
+            || typeof proof.launchPayloadHash !== 'string'
+            || (proof.generationId !== null && typeof proof.generationId !== 'string'))
+            throw new Error('invalid receipt shape');
+        return proof;
+    }
+    catch (error) {
+        throw new ResourceConflict(`native launch proof for ${id} is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function sameHarnessLaunchProof(left, right) {
+    return left.version === right.version && left.sessionId === right.sessionId && left.harnessId === right.harnessId
+        && left.harnessSessionId === right.harnessSessionId && left.launchPayloadHash === right.launchPayloadHash
+        && left.generationId === right.generationId;
+}
+export function stageHarnessLaunchProof(sessionId, harnessSessionId, launchPayload) {
+    const id = sessionId || ownSessionId();
+    if (!id || !harnessSessionId)
+        return false;
+    const rec = readLiveRecord(id);
+    if (!rec)
+        return false;
+    const harness = harnessById(rec.harness || defaultHarness.id);
+    if (!harness.launchPayloadProof)
+        throw new ResourceConflict(`harness ${harness.id} does not use native launch-payload proof`);
+    const pending = readLaunchFile(id);
+    if (pending == null)
+        throw new ResourceConflict(`refusing native launch proof for ${id}: authoritative resolved launch payload is missing`);
+    if (pending !== launchPayload)
+        throw new ResourceConflict(`refusing native launch proof for ${id}: first-turn payload differs from the authoritative resolved launch payload`);
+    const generationId = process.env.SPEXCODE_CODEX_GENERATION?.trim() || null;
+    if (rec.harness === 'codex' || rec.harness === 'codex-headless') {
+        const ledger = readCodexGenerationLedger(runtimeRoot());
+        if (ledger.revision > 0 && !generationId)
+            throw new ResourceConflict(`refusing native launch proof for ${id}: launch did not provide an exact Codex generation id`);
+        if (generationId && (!ledger.generations[generationId] || ledger.generations[generationId].state === 'reclaimed'))
+            throw new ResourceConflict(`refusing to bind Codex thread ${harnessSessionId}: generation ${generationId} is absent or reclaimed`);
+    }
+    const proof = {
+        version: 1,
+        sessionId: id,
+        harnessId: harness.id,
+        harnessSessionId,
+        launchPayloadHash: createHash('sha256').update(launchPayload).digest('hex'),
+        generationId,
+    };
+    const path = sessionArtifactPath(id, 'launch.proof');
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(proof, null, 2)}\n`, { mode: 0o600 });
+    try {
+        linkSync(temp, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const staged = readHarnessLaunchProof(id);
+        if (sameHarnessLaunchProof(staged, proof))
+            return true;
+        throw new ResourceConflict(`refusing to replace native launch proof for ${id}: the staged session, thread, payload, or generation differs`);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+function consumeHarnessLaunchProofUnlocked(id) {
+    const rec = readLiveRecord(id);
+    if (!rec)
+        return false;
+    const harness = harnessById(rec.harness || defaultHarness.id);
+    const proof = readHarnessLaunchProof(id);
+    if (proof.sessionId !== id || proof.harnessId !== harness.id)
+        throw new ResourceConflict(`native launch proof for ${id} does not match the governed adapter identity`);
+    const pending = readLaunchFile(id);
+    if (pending == null && rec.harnessSessionId !== proof.harnessSessionId)
+        throw new ResourceConflict(`refusing native launch proof for ${id}: authoritative resolved launch payload is missing`);
+    if (pending != null && proof.launchPayloadHash !== createHash('sha256').update(pending).digest('hex'))
+        throw new ResourceConflict(`native launch proof for ${id} does not match the authoritative resolved launch payload`);
+    bindHarnessSessionIdUnlocked(rec, proof.harnessSessionId, proof.generationId || undefined);
+    if (pending != null) {
+        try {
+            rmSync(sessionArtifactPath(id, 'launch'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.error(`spex: native launch proof committed for ${id}, but launch could not be consumed: ${error instanceof Error ? error.message : String(error)}`);
+                return true;
+            }
+        }
+    }
+    try {
+        rmSync(sessionArtifactPath(id, 'launch.proof'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            console.error(`spex: native launch proof committed for ${id}, but launch.proof could not be consumed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return true;
+}
+export function markHarnessSessionId(sessionId, harnessSessionId) {
+    const id = sessionId || ownSessionId();
+    if (!id || !harnessSessionId)
+        return false;
+    return withRecordLockSync(id, () => {
+        const rec = readLiveRecord(id);
+        if (!rec)
+            return false;
+        const harness = harnessById(rec.harness || defaultHarness.id);
+        if (harness.launchPayloadProof)
+            throw new ResourceConflict(`harness ${harness.id} must stage native identity together with authoritative first-turn payload proof`);
+        bindHarnessSessionIdUnlocked(rec, harnessSessionId);
+        return true;
+    });
+}
+export function markIdle(sessionId) {
+    const id = sessionId || ownSessionId();
+    if (!id)
+        return false;
+    return withRecordLockSync(id, () => {
+        const rec = readLiveRecord(id);
+        if (!rec || rec.status !== 'active')
+            return false; // active-only: never clobber a declaration
+        writeRecord({ ...rec, status: 'idle' });
+        return true;
+    });
+}
+export function mergeReadiness(proposal = 'merge') {
+    let dirty = [];
+    try {
+        dirty = git(['status', '--porcelain', '--untracked-files=all']).split('\n').filter(Boolean).map(porcelainPath);
+    }
+    catch { /* git status failed — fall through to the ahead check, still a real guard */ }
+    if (dirty.length) {
+        const shown = dirty.slice(0, 8).join(', ') + (dirty.length > 8 ? ', …' : '');
+        return { ready: false, reason: `uncommitted changes on your node branch (${shown}) — commit your spec+code first` };
+    }
+    // a `nothing` proposal makes no claim about having something to land, so the clean tree is the whole gate.
+    if (proposal === 'nothing')
+        return { ready: true };
+    let ahead = 0;
+    const base = mainBranch();
+    try {
+        ahead = Number(git(['rev-list', '--count', `${base}..HEAD`]).trim()) || 0;
+    }
+    catch {
+        ahead = 0;
+    }
+    if (ahead === 0)
+        return { ready: false, reason: `your node branch is 0 commits ahead of ${base} — nothing is committed to merge (declaring \`done --propose nothing\` needs no commits ahead; use it to pause for the human)` };
+    return { ready: true };
+}
+// the path a `git status --porcelain` line refers to: strip the `XY ` status, and for a rename keep the
+// NEW path (after ` -> `). Shared by the dirty-file counters (mergeReadiness above, reviewPayload below).
+function porcelainPath(line) {
+    let p = line.slice(3);
+    const arrow = p.indexOf(' -> ');
+    if (arrow >= 0)
+        p = p.slice(arrow + 4);
+    return p;
+}
+async function reviewHeadPair(root, branch, base) {
+    const branchRef = `refs/heads/${branch}`, baseRef = `refs/heads/${base}`;
+    const output = await gitA(['-C', root, 'for-each-ref', '--sort=refname', '--format=%(refname)%00%(objectname)', branchRef, baseRef]);
+    const refs = new Map();
+    for (const line of output.split('\n')) {
+        const at = line.indexOf('\0');
+        if (at > 0)
+            refs.set(line.slice(0, at), line.slice(at + 1).trim());
+    }
+    const branchHead = refs.get(branchRef), baseHead = refs.get(baseRef);
+    if (!branchHead || !baseHead || !isGitObjectId(root, branchHead) || !isGitObjectId(root, baseHead)) {
+        throw new ResourceConflict(`review head pair is unproven: ${branchRef} or ${baseRef} is missing or not a native Git object id`);
+    }
+    return { branchHead, baseHead };
+}
+// @@@ lintGate - the spec↔code graph lint is a LOCATION gate: a function of the backend checkout's tree ALONE
+// (its .spec graph + governed files), not of which session is reviewed, and it costs a few seconds. Re-running
+// it on every reviewPayload — i.e. on every [[session-eval]] Proof-tab open, and once per session — is
+// wasteful, so memoize it on a whole-repo fingerprint: `rev-parse HEAD` + `status --porcelain` + the mtimes of
+// the changed paths (covers committed state, the dirty SET, and dirty-file CONTENT). An identical fingerprint
+// reuses the last (in-flight) result — a re-open or a second session's proof is instant — while any commit or
+// working-tree edit moves the fingerprint and recomputes. A rejected run is not cached.
+let gateCache = null;
+async function lintGate() {
+    const root = repoRoot();
+    const [head, status] = await Promise.all([
+        gitA(['-C', root, 'rev-parse', 'HEAD']),
+        gitA(['-C', root, 'status', '--porcelain', '--untracked-files=all']),
+    ]);
+    // `status --porcelain` gives the SET of changed paths + status letters but is CONTENT-BLIND: re-editing an
+    // already-listed (dirty or untracked) file leaves the string byte-identical, so HEAD+status alone would
+    // freeze the gate after a file first goes dirty. `--untracked-files=all` stops an untracked dir from
+    // collapsing to one line (which hides a newly-added file); then fold each listed path's mtime in, so a
+    // content edit to a dirty file also moves the fingerprint. HEAD covers committed state, this covers the
+    // working tree. (Residual, accepted: the fingerprint is snapshot just before the compute, so a change
+    // landing mid-compute is labelled with the pre-change fp — rare, and the gate is advisory, re-verified at merge.)
+    const mtimes = status.split('\n').filter(Boolean).map(porcelainPath)
+        .map((p) => { try {
+        return statSync(join(root, p)).mtimeMs;
+    }
+    catch {
+        return 0;
+    } }).join(',');
+    const fp = head.trim() + '\n' + status + '\n' + mtimes;
+    if (gateCache?.fp === fp)
+        return gateCache.p;
+    const p = (async () => {
+        const { specLint } = await import('./lint.js');
+        const findings = await specLint();
+        return {
+            errorCount: findings.filter((f) => f.level === 'error').length,
+            warningCount: findings.filter((f) => f.level === 'warn').length,
+        };
+    })();
+    p.catch(() => { if (gateCache?.p === p)
+        gateCache = null; }); // don't pin a failed run
+    gateCache = { fp, p };
+    return p;
+}
+// @@@ reviewPayload - assemble the cockpit review for one session. The four session-specific reads
+// (ahead / dirty / diff / conflict gate) plus the one location gate (lint) are all independent, so they run
+// in parallel. The lint gate goes through lintGate(), which memoizes it on the checkout's tree fingerprint —
+// so an unchanged tree doesn't re-run the lint on each review / Proof-tab open, while any commit or edit
+// invalidates and recomputes.
+export async function reviewPayload(id) {
+    const wt = await findWorktree(id);
+    if (!wt)
+        return null;
+    if (!wt.rec.governed || !wt.branch)
+        throw new ResourceConflict(`session ${id} has no governed branch to review`);
+    const base = mainBranch();
+    const { branchHead, baseHead } = await reviewHeadPair(wt.path, wt.branch, base);
+    const [aheadOut, statusOut, diff, conflictsWithMain, lint] = await Promise.all([
+        gitA(['-C', wt.path, 'rev-list', '--count', `${baseHead}..${branchHead}`]),
+        gitA(['-C', wt.path, 'status', '--porcelain', '--untracked-files=all']),
+        mergeBaseDiff(wt.path, baseHead, branchHead),
+        mergeConflicts(wt.path, baseHead, branchHead),
+        lintGate(), // lint — memoized on the checkout fingerprint, not re-run per session/open
+    ]);
+    const settledPair = await reviewHeadPair(wt.path, wt.branch, base);
+    if (settledPair.branchHead !== branchHead || settledPair.baseHead !== baseHead) {
+        throw new ResourceConflict(`review head pair changed while assembling: started branch ${branchHead} / base ${baseHead}, ended branch ${settledPair.branchHead} / base ${settledPair.baseHead}`, 'session_review_head_changed');
+    }
+    // the worktree carries no SpexCode runtime files any more (the store lives in ~/.spexcode), so every dirty
+    // path is genuine work — this is just the total uncommitted count.
+    const dirtyNonRuntime = statusOut.split('\n').filter(Boolean).map(porcelainPath).length;
+    return {
+        id, node: wt.rec.node, branch: wt.branch,
+        label: deriveLabel({ id, name: wt.rec.name, node: wt.rec.node, title: wt.rec.title, branch: wt.branch }),
+        ahead: Number(aheadOut.trim()) || 0,
+        dirtyNonRuntime, diff,
+        gates: { conflictsWithMain, lint },
+        proposal: { kind: wt.rec.proposal, note: wt.rec.note },
+    };
+}
+const MERGE_PROMPT = `Merge your branch into main, then settle the session honestly.
+
+1. In your own worktree, merge the latest main into your branch. Resolve any conflicts there and re-run the tests.
+2. Atomic landing: main only receives the completed branch as one no-ff merge. Never resolve conflicts in the shared main checkout.
+3. Verify main advanced cleanly with no merge left in progress. If this task is settled, run \`spex session done --propose close\` as your FINAL action; otherwise declare the state that is true.`;
+export async function mergeSession(id) {
+    const wt = await findWorktree(id);
+    if (!wt?.branch)
+        return { dispatched: false, reason: 'no such mergeable session' };
+    const r = await sendText(id, MERGE_PROMPT, undefined, {
+        deferDrain: true,
+        acceptGuard: async (rec) => {
+            if (!rec.governed || rec.status !== 'awaiting' || rec.proposal !== 'merge') {
+                const error = new ResourceConflict(`session ${id} is not a governed awaiting merge proposal`);
+                Object.assign(error, { code: 'session_merge_not_proposed' });
+                throw error;
+            }
+        },
+    });
+    if (r.code === 'session_merge_not_proposed')
+        return { dispatched: false, reason: r.error || 'merge dispatch refused', code: r.code, status: 409 };
+    if (!r.ok)
+        return { dispatched: false, reason: r.error || 'could not dispatch merge prompt' };
+    await resumeSession(id, { guard: false });
+    await drainSession(id);
+    return { dispatched: true };
+}
+// @@@ killAgentProcess - the pane is the agent's HOME, not its LEASH. `kill-session` SIGHUPs the pane's
+// process group, and an idle agent goes with it (measured: ~0.8s) — but one mid-turn can outlive the whole
+// tmux server and keep running, orphaned, still holding its rendezvous socket (measured: pane gone, server
+// gone, agent still answering). Close promises ZERO residue including the process tree, so the teardown
+// escalates on the pid launch registered for exactly this purpose: give the SIGHUP its moment, then SIGTERM,
+// then SIGKILL, each bounded. This is also what lets the socket sweep run at all — a still-answering listener
+// is never ours to unlink, so an un-killed agent would otherwise strand its own socket forever.
+// The escalation is IDENTITY-GUARDED: a recorded pid can have been recycled by an unrelated process, so we
+// signal only the immutable pid/start instance whose ownership was witnessed in the exact tmux pane closure.
+// Unidentifiable → we signal nothing and let the adapter's proof-of-death rule leave the transport alone.
+const AGENT_EXIT_GRACE_MS = 3000;
+const SESSION_LEAF_RECEIPT_VERSION = 1;
+const SESSION_LEAF_RECEIPT_KIND = 'session-leaf';
+export function parseSessionLeafReceipt(raw, sessionId) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const row = value;
+    const keys = Object.keys(row).sort();
+    if (keys.join(',') !== 'kind,pid,sessionId,startToken,version')
+        return null;
+    if (row.version !== SESSION_LEAF_RECEIPT_VERSION || row.kind !== SESSION_LEAF_RECEIPT_KIND || row.sessionId !== sessionId)
+        return null;
+    if (!Number.isSafeInteger(row.pid) || row.pid <= 0 || typeof row.startToken !== 'string' || !row.startToken)
+        return null;
+    return row;
+}
+function pidInPaneClosure(pid, panePid, procs) {
+    const seen = new Set();
+    for (let current = pid; current > 0 && !seen.has(current);) {
+        if (current === panePid)
+            return true;
+        seen.add(current);
+        const row = procs.get(current);
+        if (!row || row.ppid === current)
+            return false;
+        current = row.ppid;
+    }
+    return false;
+}
+export function sessionLeafReceiptCandidate(sessionId, pid, panePid, procs, startBefore, startAfter) {
+    if (!panePid)
+        return { ok: false, reason: 'exact target pane PID is unavailable' };
+    if (!procs)
+        return { ok: false, reason: 'process snapshot is unavailable' };
+    if (!startBefore || !startAfter)
+        return { ok: false, reason: 'leaf process-start identity is unreadable' };
+    if (startBefore !== startAfter)
+        return { ok: false, reason: 'leaf process-start identity changed during ancestry observation' };
+    if (!pidInPaneClosure(pid, panePid, procs))
+        return { ok: false, reason: `registered leaf PID ${pid} is not in exact target pane ${panePid} descendant closure` };
+    return {
+        ok: true,
+        receipt: { version: SESSION_LEAF_RECEIPT_VERSION, kind: SESSION_LEAF_RECEIPT_KIND, sessionId, pid, startToken: startAfter },
+    };
+}
+export function sessionLeafReceiptIdentityState(receipt, registeredPid, currentStartToken, liveness) {
+    if (registeredPid == null)
+        return 'registration-missing';
+    if (registeredPid !== receipt.pid)
+        return 'registration-changed';
+    if (liveness === 'unknown')
+        return 'unknown';
+    if (liveness === 'dead')
+        return currentStartToken ? 'unknown' : 'gone';
+    if (!currentStartToken)
+        return 'unknown';
+    return currentStartToken === receipt.startToken ? 'same-live' : 'pid-reused';
+}
+const sessionLeafReceiptPath = (id) => sessionArtifactPath(id, 'agent.identity.json');
+function readSessionLeafReceipt(id) {
+    const path = sessionLeafReceiptPath(id);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { state: 'missing' };
+        return { state: 'invalid', reason: `leaf birth receipt is unreadable (${error instanceof Error ? error.message : String(error)})` };
+    }
+    const receipt = parseSessionLeafReceipt(raw, id);
+    return receipt ? { state: 'valid', receipt } : { state: 'invalid', reason: 'leaf birth receipt is malformed or names a different session' };
+}
+function writeSessionLeafReceipt(id, receipt) {
+    const path = sessionLeafReceiptPath(id);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+function clearSessionLeafArtifacts(id) {
+    rmSync(sessionArtifactPath(id, 'agent.pid'), { force: true });
+    pidRegistry.delete(id);
+    rmSync(sessionLeafReceiptPath(id), { force: true });
+}
+const sameSessionLeafReceipt = (left, right) => left.version === right.version && left.kind === right.kind && left.sessionId === right.sessionId
+    && left.pid === right.pid && left.startToken === right.startToken;
+async function killAgentProcess(id, beforeSignal, leaf) {
+    const pid = leaf.pid;
+    const startToken = leaf.startToken;
+    const alive = () => leafAlive(pid);
+    const identityState = () => {
+        const stored = readSessionLeafReceipt(id);
+        if (stored.state !== 'valid' || !sameSessionLeafReceipt(stored.receipt, leaf.receipt))
+            return 'changed';
+        const registered = readAgentPid(sessionArtifactPath(id, 'agent.pid'));
+        const liveness = leafProcessLiveness(pid);
+        const currentStartToken = sessionLeafStartToken(pid);
+        const state = sessionLeafReceiptIdentityState(stored.receipt, Number.isSafeInteger(registered) ? registered : null, currentStartToken, liveness);
+        return state === 'same-live' ? 'same' : state === 'gone' ? 'gone' : 'changed';
+    };
+    const initialState = identityState();
+    if (initialState === 'gone')
+        return;
+    if (initialState === 'changed')
+        throw new ResourceConflict(`refusing to stop ${id}: session leaf identity changed before signal`);
+    const gone = async (ms) => {
+        for (const end = Date.now() + ms; Date.now() < end;) {
+            if (!alive())
+                return true;
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        return !alive();
+    };
+    if (await gone(AGENT_EXIT_GRACE_MS))
+        return; // the pane's SIGHUP took it — the normal path
+    for (const sig of ['SIGTERM', 'SIGKILL']) {
+        await beforeSignal();
+        const state = identityState();
+        if (state === 'gone')
+            return;
+        if (state === 'changed')
+            throw new ResourceConflict(`refusing to stop ${id}: session leaf identity changed during escalation`);
+        try {
+            process.kill(pid, sig);
+        }
+        catch {
+            return;
+        } // vanished between checks
+        if (await gone(sig === 'SIGTERM' ? AGENT_EXIT_GRACE_MS : 1000))
+            return;
+    }
+    throw new ResourceConflict(`refusing to stop ${id}: exact leaf PID ${pid}@${startToken} remains live after escalation`);
+}
+const hostLeafProcessLiveness = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ESRCH')
+            return 'dead';
+        if (code === 'EPERM')
+            return 'alive';
+        return 'unknown';
+    }
+};
+let sessionLeafProcessProbe = {
+    startToken: processStartToken,
+    liveness: hostLeafProcessLiveness,
+};
+export function installSessionLeafProcessProbeForTest(probe) {
+    const previous = sessionLeafProcessProbe;
+    sessionLeafProcessProbe = probe;
+    return () => { sessionLeafProcessProbe = previous; };
+}
+const sessionLeafStartToken = (pid) => sessionLeafProcessProbe.startToken(pid);
+const leafProcessLiveness = (pid) => sessionLeafProcessProbe.liveness(pid);
+const leafAlive = (pid) => leafProcessLiveness(pid) !== 'dead';
+// A retained leaf can mint durable ownership only while its registered PID is in the exact target pane's process
+// closure. The receipt then binds that one immutable process instance across tmux reparenting and crash retry.
+async function inspectSessionLeafIdentity(id, rec) {
+    if (harnessById(rec.harness || defaultHarness.id).runtimeOwnership === 'adapter')
+        return { state: 'missing' };
+    const path = sessionArtifactPath(id, 'agent.pid');
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            const stored = readSessionLeafReceipt(id);
+            if (stored.state === 'invalid')
+                return { state: 'unknown', reason: stored.reason };
+            if (stored.state === 'missing')
+                return { state: 'missing' };
+            const liveness = leafProcessLiveness(stored.receipt.pid);
+            const current = sessionLeafStartToken(stored.receipt.pid);
+            const state = sessionLeafReceiptIdentityState(stored.receipt, stored.receipt.pid, current, liveness);
+            if (state === 'same-live')
+                return { state: 'unknown', pid: stored.receipt.pid, reason: 'leaf birth receipt remains live but agent.pid registration is missing' };
+            if (state === 'unknown')
+                return { state: 'unknown', pid: stored.receipt.pid, reason: 'leaf birth receipt PID is live but its process-start identity is unreadable' };
+            if (state !== 'gone' && state !== 'pid-reused')
+                return { state: 'unknown', pid: stored.receipt.pid, reason: `leaf birth receipt cannot reconcile a missing registration (${state})` };
+            rmSync(sessionLeafReceiptPath(id), { force: true });
+            return { state: 'dead', pid: stored.receipt.pid };
+        }
+        return { state: 'unknown', reason: `leaf PID artifact is unreadable (${error instanceof Error ? error.message : String(error)})` };
+    }
+    const pid = Number(raw.trim());
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return { state: 'unknown', reason: 'leaf PID artifact is malformed' };
+    const stored = readSessionLeafReceipt(id);
+    if (stored.state === 'invalid')
+        return { state: 'unknown', pid, reason: stored.reason };
+    if (stored.state === 'valid') {
+        const liveness = leafProcessLiveness(pid);
+        const current = sessionLeafStartToken(pid);
+        const state = sessionLeafReceiptIdentityState(stored.receipt, pid, current, liveness);
+        if (state === 'same-live')
+            return { state: 'owned', identity: { pid, startToken: current, receipt: stored.receipt } };
+        if (state === 'gone') {
+            clearSessionLeafArtifacts(id);
+            return { state: 'dead', pid };
+        }
+        if (state === 'pid-reused') {
+            const snap = await liveSnapshot(id);
+            if (snap.probeFailed)
+                return { state: 'unknown', pid, reason: 'target pane state is unreadable while reconciling a retired leaf receipt' };
+            if (snap.windows.has(id))
+                return { state: 'unknown', pid, reason: `leaf birth receipt no longer matches PID ${pid} while the exact target pane remains live` };
+            clearSessionLeafArtifacts(id);
+            return { state: 'dead', pid };
+        }
+        if (state === 'unknown')
+            return { state: 'unknown', pid, reason: `leaf PID ${pid} is live but its process-start identity is unreadable` };
+        return { state: 'unknown', pid, reason: 'leaf birth receipt and agent.pid registration disagree' };
+    }
+    const snap = await liveSnapshot(id);
+    if (snap.probeFailed)
+        return { state: 'unknown', pid, reason: 'exact target pane is unreadable; leaf birth receipt cannot be minted' };
+    const panePid = snap.windows.get(id)?.panePid ?? null;
+    const startBefore = sessionLeafStartToken(pid);
+    if (!startBefore) {
+        const live = leafProcessLiveness(pid);
+        if (live !== 'dead')
+            return { state: 'unknown', pid, reason: `leaf PID ${pid} process-start identity is unreadable while liveness is ${live}` };
+        clearSessionLeafArtifacts(id);
+        return { state: 'dead', pid };
+    }
+    let procs = null;
+    try {
+        procs = await procSnapshot();
+    }
+    catch { /* fail closed below */ }
+    const startAfter = sessionLeafStartToken(pid);
+    const candidate = sessionLeafReceiptCandidate(id, pid, panePid, procs, startBefore, startAfter);
+    if (!candidate.ok || !candidate.receipt)
+        return { state: 'unknown', pid, reason: candidate.reason || 'leaf birth receipt proof failed' };
+    if (readAgentPid(path) !== pid || sessionLeafStartToken(pid) !== candidate.receipt.startToken)
+        return { state: 'unknown', pid, reason: `leaf PID ${pid} identity changed before receipt commit` };
+    writeSessionLeafReceipt(id, candidate.receipt);
+    const committed = readSessionLeafReceipt(id);
+    if (committed.state !== 'valid' || !sameSessionLeafReceipt(committed.receipt, candidate.receipt)
+        || readAgentPid(path) !== pid || sessionLeafStartToken(pid) !== candidate.receipt.startToken)
+        return { state: 'unknown', pid, reason: `leaf PID ${pid} identity changed while receipt committed` };
+    return { state: 'owned', identity: { pid, startToken: candidate.receipt.startToken, receipt: candidate.receipt } };
+}
+async function assertSessionLeafOwned(id, rec) {
+    if (harnessById(rec.harness || defaultHarness.id).runtimeOwnership === 'adapter')
+        return null;
+    const observed = await inspectSessionLeafIdentity(id, rec);
+    if (observed.state === 'missing') {
+        if (rec.stopped || rec.status === 'queued')
+            return null;
+        throw new ResourceConflict(`refusing to stop ${id}: no readable session-owned leaf PID`);
+    }
+    if (observed.state === 'dead')
+        return null;
+    if (observed.state === 'owned')
+        return observed.identity;
+    throw new ResourceConflict(`refusing to stop ${id}: ${observed.reason}`);
+}
+async function stopAgentProcess(id, rec, requireCold = false, coldReceipt) {
+    // The caller resolves one readable owner before entering this seam. An absent/corrupt record never reaches
+    // tmux, signals, or adapter cleanup: a bare session id is an address, not ownership authority.
+    const assertOwned = () => assertSessionStopSafe(id, rec ? { ...rec, harness: rec.harness } : null, { ...(requireCold && coldReceipt !== undefined ? { coldReceipt } : {}) });
+    await assertOwned();
+    if (!rec)
+        throw new ResourceConflict(`refusing to stop ${id}: no readable session owner`);
+    const harness = harnessById(rec.harness || defaultHarness.id);
+    const leaf = await assertSessionLeafOwned(id, rec);
+    // Adapter-owned headless sessions may have no live leaf PID, but launch still created an exact tmux session
+    // wrapper. Kill that session-id unconditionally; runtimeOwnership only changes the leaf receipt proof, never the
+    // exact tmux teardown.
+    await tmuxOk(['kill-session', '-t', id]);
+    await assertTargetTmuxAbsent(id, 'after kill');
+    if (leaf) {
+        await killAgentProcess(id, assertOwned, leaf);
+        const registered = readAgentPid(sessionArtifactPath(id, 'agent.pid'));
+        const liveness = leafProcessLiveness(leaf.pid);
+        const currentStartToken = sessionLeafStartToken(leaf.pid);
+        const finalState = sessionLeafReceiptIdentityState(leaf.receipt, Number.isSafeInteger(registered) ? registered : null, currentStartToken, liveness);
+        if (finalState !== 'gone' && finalState !== 'pid-reused')
+            throw new ResourceConflict(`refusing to stop ${id}: exact leaf teardown remains ${finalState}`);
+        clearSessionLeafArtifacts(id);
+    }
+    launchedAt.delete(id);
+    await harness.cleanupRuntime(rec);
+    if (requireCold) {
+        const cold = await harness.coldRuntime?.(rec, coldReceipt);
+        if (cold && !cold.ok)
+            throw new ResourceConflict(`refusing to archive ${id}: ${cold.reason}`);
+    }
+}
+async function stopSessionUnlocked(id) {
+    let wt;
+    try {
+        wt = await findWorktree(id);
+    }
+    catch (e) {
+        if (!(e instanceof SessionRecordUnusable) || e.code !== 'corrupt')
+            throw e;
+        await stopAgentProcess(id, null);
+        throw e;
+    }
+    if (!wt)
+        return false;
+    await stopAgentProcess(id, wt.rec);
+    const rec = readRecord(id);
+    if (rec)
+        writeRecord({ ...rec, stopped: true });
+    if (wt.rec.status !== 'queued')
+        requestQueueDrain(); // a live stop frees a slot; a prepared queue never held one
+    return !!wt;
+}
+export const stopSession = (id) => withSessionTransition(id, () => withRecordLock(id, () => stopSessionUnlocked(id)));
+async function archiveSessionUnlocked(id, on = true) {
+    let wt;
+    try {
+        wt = await findWorktree(id);
+    }
+    catch (e) {
+        if (e instanceof SessionRecordUnusable)
+            throw new ResourceConflict(`refusing to archive ${id}: ${e.message}`);
+        throw e;
+    }
+    if (!wt)
+        return false;
+    if (!on)
+        throw new ResourceConflict('unarchive is not a record-only transition; use resume to restore the runtime');
+    if (wt.rec.status === 'queued')
+        throw new ResourceConflict(`refusing to archive ${id}: queued sessions have only a prepared launch prompt; resume/startQueued is their lifecycle`);
+    const retired = retirementReason(wt.rec);
+    if (retired)
+        throw new ResourceConflict(`refusing to archive ${id}: ${retired}`);
+    archiving.add(id);
+    try {
+        const h = harnessById(wt.rec.harness || defaultHarness.id);
+        const settleArchiveRecovery = () => {
+            const current = readRecord(id);
+            if (current?.adapterRecovery)
+                writeRecord({ ...current, adapterRecovery: null });
+        };
+        // A proven cold record is already archived; never clear it and issue a second thread/archive RPC. Verify the
+        // adapter's exact resident reference first so an externally respawned thread is repaired rather than hidden.
+        if (wt.rec.archived && hasValidColdProof(wt.rec)) {
+            const proofSnap = await liveSnapshot(id);
+            if (proofSnap.probeFailed)
+                throw new ResourceConflict(`refusing to re-archive ${id}: liveness probe failed; the exact leaf may have respawned`);
+            const proofLv = h.runtimeOwnership === 'adapter'
+                ? (proofSnap.windows.has(id) ? 'online' : 'offline')
+                : liveness({ ...wt.rec, archived: false, stopped: false }, proofSnap);
+            if (proofLv === 'unknown' || proofLv === 'starting')
+                throw new ResourceConflict(`refusing to re-archive ${id}: session liveness is ${proofLv}; exact cold state is unproven`);
+            if (proofLv === 'offline') {
+                // A deliberately stopped shared control plane is a valid empty resident census. A durable proof plus
+                // an adapter-owned root-absent fact is the only idempotent short-circuit; a live root still has to prove
+                // the thread's archived/non-archived disk collection before we can claim it is already cold.
+                const rootAbsent = await Promise.all((h.sharedRuntimes?.(runtimeRoot()) ?? []).map(async (descriptor) => {
+                    if (!descriptor.residency)
+                        return false;
+                    const state = await descriptor.residency();
+                    return state.healthy && state.rootAbsent === true && state.referenceIds.length === 0;
+                })).then((states) => states.some(Boolean));
+                if (rootAbsent) {
+                    settleArchiveRecovery();
+                    return true;
+                }
+                const pre = await h.coldPreflight?.({ ...wt.rec, archived: false, stopped: true });
+                if (!pre || pre.ok) {
+                    const cold = await h.coldRuntime?.({ ...wt.rec, archived: false, stopped: true }, pre?.ok ? pre.receipt : undefined);
+                    if (!cold || cold.ok) {
+                        settleArchiveRecovery();
+                        return true;
+                    }
+                }
+            }
+        }
+        // Legacy/respawned archives are made visible before repair. Any refusal below therefore leaves an unarchived
+        // row instead of relying on a hidden bit while a runtime proof is missing.
+        if (wt.rec.archived) {
+            writeRecord({ ...wt.rec, archived: false, coldProof: null });
+            wt = await findWorktree(id);
+            if (!wt)
+                return false;
+        }
+        const snap = await liveSnapshot(id);
+        if (snap.probeFailed)
+            throw new ResourceConflict(`refusing to archive ${id}: liveness probe failed; the leaf may still be live`);
+        const lv = h.runtimeOwnership === 'adapter'
+            ? 'offline'
+            : liveness({ ...wt.rec, archived: false, stopped: false }, snap);
+        if (lv === 'unknown' || lv === 'starting')
+            throw new ResourceConflict(`refusing to archive ${id}: session liveness is ${lv}; exact leaf ownership is unproven`);
+        // The adapter guard runs BEFORE any tmux/process signal. Active/unknown native turns and ambiguous descendant
+        // ownership refuse here; a verified adapter receipt carries an exact subtree through to coldRuntime's commit.
+        assertSessionOwnerSafe(id, h.id);
+        const preflight = await h.coldPreflight?.({ ...wt.rec, archived: false, stopped: lv === 'offline' });
+        if (preflight && !preflight.ok)
+            throw new ResourceConflict(`refusing to archive ${id}: ${preflight.reason}`);
+        // Even a proven-offline leaf can leave a stale rendezvous/socket or adapter artifact. Reuse the same exact
+        // teardown seam with the explicit stopped marker so cleanupRuntime gets its ownership check and no second
+        // cleanup primitive is invented.
+        let coldCommitted = false;
+        let coldAttempted = false;
+        try {
+            coldAttempted = true;
+            await stopAgentProcess(id, { ...wt.rec, archived: false, stopped: lv === 'offline' }, true, preflight?.ok ? preflight.receipt : undefined);
+            coldCommitted = true;
+            const latest = readRecord(id);
+            if (!latest)
+                throw new ResourceConflict(`refusing to archive ${id}: session record disappeared before filing`);
+            // The leaf identity kill and adapter cold proof established process/transport absence. Record-backed
+            // adapters intentionally project online until the archive write, so display liveness is not physical
+            // evidence here. A target pane appearing after the stop proof is the remaining shared runtime witness.
+            await assertTargetTmuxAbsent(id, 'before archive filing');
+            writeRecord({ ...latest, archived: true, stopped: true, coldProof: coldProofFor(latest), adapterRecovery: null });
+        }
+        catch (error) {
+            if (coldCommitted) {
+                const restored = await h.restoreRuntime?.(wt.rec, preflight?.ok ? preflight.receipt : undefined);
+                if (restored && !restored.ok) {
+                    const current = readRecord(id);
+                    if (current)
+                        writeRecord({ ...current, archived: false, stopped: true, coldProof: null, adapterRecovery: `restore-runtime:${restored.reason}` });
+                    console.error(`spex: archive compensation for ${id} failed: ${restored.reason}`);
+                }
+            }
+            else if (coldAttempted && error instanceof Error && /compensation failed|state is unknown|reconciliation failed/i.test(error.message)) {
+                const current = readRecord(id);
+                if (current)
+                    writeRecord({ ...current, archived: false, stopped: true, coldProof: coldProofFor(current), adapterRecovery: `restore-runtime:${error.message}` });
+            }
+            throw error;
+        }
+        requestQueueDrain();
+        return true;
+    }
+    finally {
+        archiving.delete(id);
+    }
+}
+export const archiveSession = (id, on = true) => {
+    if (!on)
+        return archiveSessionUnarchive(id);
+    return withSessionTransition(id, () => withRecordLock(id, () => archiveSessionUnlocked(id, on)));
+};
+async function archiveSessionUnarchive(id) {
+    const wt = await findWorktree(id);
+    if (!wt)
+        return false;
+    if (!wt.rec.archived)
+        return true;
+    const resumed = await resumeSession(id);
+    if (!resumed.ok)
+        throw new ResourceConflict(resumed.error || `refusing to resume ${id}`);
+    return true;
+}
+// @@@ cold retirement - archive already returned the target's runtime, so closing a proven-cold row must not
+// re-enter the live stop guard and make unrelated shared-root references prove ownership again. Verify only
+// that the target-bound cold proof is still current and that no target PID/window/socket/thread has reappeared.
+// This is read-only: no signal, adapter mutation, or shared-root cleanup belongs on the cold path.
+async function assertColdRetirementSafe(id, rec) {
+    if (!rec.archived || !rec.stopped || !hasValidColdProof(rec))
+        throw new ResourceConflict(`refusing to close archived session ${id}: target-bound cold witness is missing or stale`);
+    if (rec.adapterRecovery)
+        throw new ResourceConflict(`refusing to close archived session ${id}: adapter recovery is pending (${rec.adapterRecovery})`);
+    const [snap, socket] = await Promise.all([liveSnapshot(id), rendezvousListening(id)]);
+    if (snap.probeFailed)
+        throw new ResourceConflict(`refusing to close archived session ${id}: liveness probe failed; target runtime absence is unproven`);
+    if (snap.windows.has(id))
+        throw new ResourceConflict(`refusing to close archived session ${id}: target tmux window has reappeared`);
+    if (socket === 'live')
+        throw new ResourceConflict(`refusing to close archived session ${id}: target rendezvous transport has reappeared`);
+    if (socket === 'unproven')
+        throw new ResourceConflict(`refusing to close archived session ${id}: target rendezvous state is ambiguous`);
+    const leaf = await inspectSessionLeafIdentity(id, rec);
+    if (leaf.state === 'owned')
+        throw new ResourceConflict(`refusing to close archived session ${id}: target leaf PID ${leaf.identity.pid} is live or recycled; ownership is ambiguous`);
+    if (leaf.state === 'unknown')
+        throw new ResourceConflict(`refusing to close archived session ${id}: ${leaf.reason}; ownership is ambiguous`);
+    const harness = harnessById(rec.harness || defaultHarness.id);
+    if (harness.coldRetirementPreflight) {
+        const proof = await harness.coldRetirementPreflight(rec);
+        if (!proof.ok)
+            throw new ResourceConflict(`refusing to close archived session ${id}: ${proof.reason}`);
+        return;
+    }
+    const descriptors = harness.sharedRuntimes?.(runtimeRoot()) ?? [];
+    let everySharedRootAbsent = descriptors.length > 0;
+    for (const descriptor of descriptors) {
+        const resident = descriptor.residency
+            ? await descriptor.residency()
+            : await descriptor.probe().then((probe) => ({ healthy: probe.healthy, referenceIds: probe.references.map((reference) => reference.referenceId), error: probe.error }));
+        if (!resident.healthy)
+            throw new ResourceConflict(`refusing to close archived session ${id}: ${resident.error || `${descriptor.label} resident census is unhealthy`}`);
+        if (rec.harnessSessionId && resident.referenceIds.includes(rec.harnessSessionId))
+            throw new ResourceConflict(`refusing to close archived session ${id}: target adapter thread ${rec.harnessSessionId} is loaded`);
+        everySharedRootAbsent = everySharedRootAbsent && resident.rootAbsent === true;
+    }
+    if (harness.coldPreflight && !everySharedRootAbsent) {
+        const proof = await harness.coldPreflight(rec);
+        if (!proof.ok)
+            throw new ResourceConflict(`refusing to close archived session ${id}: ${proof.reason}`);
+        if (!proof.alreadyCold)
+            throw new ResourceConflict(`refusing to close archived session ${id}: target adapter collection is not proven cold`);
+    }
+}
+async function assertDiscardableWorktree(id, path, branch, kind) {
+    if (existsSync(path)) {
+        const status = await gitTry(['-C', path, 'status', '--porcelain', '--untracked-files=all']);
+        if (!status.ok)
+            throw new ResourceConflict(`refusing to close ${kind} session ${id}: ${kind} worktree status is unreadable`);
+        if (status.stdout.trim())
+            throw new ResourceConflict(`refusing to close ${kind} session ${id}: ${kind} worktree has dirty work`);
+    }
+    if (branch) {
+        const resolved = await gitTry(['-C', mainRoot(), 'rev-parse', '--verify', `${branch}^{commit}`]);
+        if (resolved.ok) {
+            const count = await gitTry(['-C', mainRoot(), 'rev-list', '--count', `${mainBranch()}..${branch}`]);
+            if (!count.ok)
+                throw new ResourceConflict(`refusing to close ${kind} session ${id}: ${kind} branch ancestry is unreadable`);
+            const ahead = Number(count.stdout.trim());
+            if (!Number.isFinite(ahead) || ahead !== 0)
+                throw new ResourceConflict(`refusing to close ${kind} session ${id}: ${kind} branch is ${Number.isFinite(ahead) ? ahead : 'an unknown number of'} commit(s) ahead`);
+        }
+        else if (resolved.failure !== 'exit') {
+            throw new ResourceConflict(`refusing to close ${kind} session ${id}: ${kind} branch identity is unreadable`);
+        }
+        else if (existsSync(path)) {
+            throw new ResourceConflict(`refusing to close ${kind} session ${id}: ${kind} worktree exists but branch ${branch} is missing`);
+        }
+    }
+}
+// A never-launched queue owns only prepared disk state. The transition/record locks around close serialize
+// this check with startQueued: whichever wins decides whether the record is still a queue or has become live.
+// No shared-runtime probe belongs here because a valid prepared row has no adapter thread to look up.
+async function assertQueuedRetirementSafe(id, rec, path, branch) {
+    if (rec.status !== 'queued' || rec.harnessSessionId)
+        throw new ResourceConflict(`refusing to close queued session ${id}: the record has a target thread or is no longer queued`);
+    if (rec.adapterRecovery || launching.has(id))
+        throw new ResourceConflict(`refusing to close queued session ${id}: target launch/recovery is already in progress`);
+    const [snap, socket] = await Promise.all([liveSnapshot(id), rendezvousListening(id)]);
+    if (snap.probeFailed)
+        throw new ResourceConflict(`refusing to close queued session ${id}: liveness probe failed; target runtime absence is unproven`);
+    if (snap.windows.has(id))
+        throw new ResourceConflict(`refusing to close queued session ${id}: target tmux window already exists`);
+    if (socket === 'live')
+        throw new ResourceConflict(`refusing to close queued session ${id}: target rendezvous transport already exists`);
+    if (socket === 'unproven')
+        throw new ResourceConflict(`refusing to close queued session ${id}: target rendezvous state is ambiguous`);
+    const pidPath = sessionArtifactPath(id, 'agent.pid');
+    if (existsSync(pidPath)) {
+        const pid = readAgentPid(pidPath);
+        throw new ResourceConflict(`refusing to close queued session ${id}: target leaf PID artifact ${Number.isFinite(pid) && pid > 0 ? pid : 'is unreadable'}; never-launched ownership is ambiguous`);
+    }
+    await assertDiscardableWorktree(id, path, branch, 'prepared');
+}
+// A launch may leave its row active before Codex publishes the native thread binding. This close path owns
+// only the record's dead local launch residue; an unbound app-server peer stays unowned and untouched.
+async function assertUnboundRetirementSafe(id, rec, path, branch) {
+    if (harnessById(rec.harness || defaultHarness.id).exactNativeTargetId(rec) || rec.status === 'queued' || rec.archived)
+        throw new ResourceConflict(`refusing to close unbound session ${id}: it is not an unbound live-record residue`);
+    if (rec.adapterRecovery || rec.launchReadinessPending || launching.has(id) || existsSync(sessionArtifactPath(id, 'launch')))
+        throw new ResourceConflict(`refusing to close unbound session ${id}: launch or recovery is still in progress`);
+    const [snap, socket] = await Promise.all([liveSnapshot(id), rendezvousListening(id)]);
+    if (snap.probeFailed)
+        throw new ResourceConflict(`refusing to close unbound session ${id}: liveness probe failed; local worker absence is unproven`);
+    const harness = harnessById(rec.harness || defaultHarness.id);
+    if (harness.liveness(rec, snap.windows.has(id), runtimeRoot(), snap.windows.get(id), snap.sockets.has(id)) === 'online')
+        throw new ResourceConflict(`refusing to close unbound session ${id}: its adapter still reports a live worker`);
+    if (socket === 'live')
+        throw new ResourceConflict(`refusing to close unbound session ${id}: target rendezvous transport already exists`);
+    if (socket === 'unproven')
+        throw new ResourceConflict(`refusing to close unbound session ${id}: target rendezvous state is ambiguous`);
+    const leaf = await inspectSessionLeafIdentity(id, rec);
+    if (leaf.state !== 'missing' && leaf.state !== 'dead')
+        throw new ResourceConflict(`refusing to close unbound session ${id}: ${leaf.state === 'unknown' ? leaf.reason : 'target leaf identity is live or ambiguous'}`);
+    await assertDiscardableWorktree(id, path, branch, 'unbound');
+}
+async function closeOwnedSessionUnlocked(id, wt, source, unboundRetired = false) {
+    const root = mainRoot();
+    const receiptFailure = publishedSessionCandidateReceiptRetirementFailure(wt.rec, root);
+    if (receiptFailure)
+        throw new ResourceConflict(`refusing destructive close for ${id}: ${receiptFailure}; public record and resources remain the authority fence`);
+    const closesCodexBinding = (wt.rec.harness === 'codex' || wt.rec.harness === 'codex-headless') && !!wt.rec.harnessSessionId;
+    const retired = !wt.rec.archived && !!retirementReason(wt.rec);
+    // A retired row has already lost its worktree; close is its explicit record-only terminal cleanup.
+    if (!retired) {
+        if (wt.rec.archived)
+            await assertColdRetirementSafe(id, wt.rec);
+        else if (wt.rec.status === 'queued')
+            await assertQueuedRetirementSafe(id, wt.rec, wt.path, wt.branch);
+        else if (!unboundRetired)
+            throw new ResourceConflict(`refusing to close ${id}: target runtime was not cold-retired first`);
+    }
+    // The marker protects only the destructive half. A failed cold proof must leave a normal, resumable binding.
+    if (closesCodexBinding)
+        prepareCodexGenerationClose(runtimeRoot(), id, wt.rec.harnessSessionId);
+    appendCloseLedger(id, wt.rec, source);
+    let slot = null;
+    try {
+        slot = treeSlotDir(wt.path);
+    }
+    catch { /* tree already unresolvable — nothing to key the slot by */ }
+    // a retired session's worktree/branch are already gone; removing them is a no-op to skip, not a failure.
+    if (existsSync(wt.path)) {
+        const removed = await gitTry(['-C', root, 'worktree', 'remove', '--force', wt.path]);
+        if (!removed.ok)
+            throw new ResourceConflict(`refusing to finish close for ${id}: worktree removal failed`);
+        if (existsSync(wt.path))
+            throw new ResourceConflict(`refusing to finish close for ${id}: worktree remains after removal`);
+    }
+    if (wt.branch) {
+        const branchRef = `refs/heads/${wt.branch}`;
+        const present = await gitTry(['-C', root, 'rev-parse', '--verify', '--quiet', branchRef]);
+        if (present.ok) {
+            const removed = await gitTry(['-C', root, 'branch', '-D', wt.branch]);
+            if (!removed.ok)
+                throw new ResourceConflict(`refusing to finish close for ${id}: branch removal failed`);
+            const remaining = await gitTry(['-C', root, 'rev-parse', '--verify', '--quiet', branchRef]);
+            if (remaining.ok || remaining.failure !== 'exit')
+                throw new ResourceConflict(`refusing to finish close for ${id}: branch remains or its removal is unproven`);
+        }
+        else if (present.failure !== 'exit') {
+            throw new ResourceConflict(`refusing to finish close for ${id}: branch presence is unreadable`);
+        }
+    }
+    if (slot) {
+        try {
+            rmSync(slot, { recursive: true, force: true });
+        }
+        catch { /* best-effort GC */ }
+    }
+    try {
+        rmSync(sessionStoreDir(id), { recursive: true, force: true });
+    }
+    catch (error) {
+        throw new ResourceConflict(`refusing to finish close for ${id}: session record/prompt removal failed (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (existsSync(sessionStoreDir(id)))
+        throw new ResourceConflict(`refusing to finish close for ${id}: session record removal failed`);
+    // The close still owns this sender's record lock. Marking after its store is gone lets any send already
+    // admitted finish before close returns, while every later send and every retry sweep sees terminal output.
+    revokeSenderDelivery(id);
+    if (closesCodexBinding && wt.rec.harnessSessionId) {
+        bindCodexGeneration(runtimeRoot(), id, wt.rec.harnessSessionId, null);
+    }
+    requestQueueDrain(); // a close frees a slot — start the next queued session if any
+    return true;
+}
+async function closeSessionUnlocked(id, source) {
+    let wt = null;
+    try {
+        wt = await findWorktree(id);
+    }
+    catch (e) {
+        if (!(e instanceof SessionRecordUnusable) || e.code !== 'corrupt')
+            throw e;
+        const quarantined = quarantineRecord(id);
+        const runtime = sessionStoreDir(id);
+        const evidence = quarantined
+            ? `Original bytes were copied to ${quarantined}`
+            : `Original bytes remain at ${join(runtime, 'session.json')}; no quarantine copy could be made`;
+        let guard = 'no readable session record proves the adapter or leaf owner';
+        try {
+            await stopAgentProcess(id, null);
+        }
+        catch (error) {
+            guard = error instanceof Error ? error.message : String(error);
+        }
+        throw new SessionRecordUnusable('corrupt', id, `refusing destructive close for ${id}: the unreadable record proves no adapter, leaf, worktree, or branch owner (${guard}). ${evidence}. Runtime remains at ${runtime}; worktree and branch ownership is unknown and was not touched; no process signal or deletion was attempted.`);
+    }
+    if (!wt)
+        return false;
+    let unboundRetired = false;
+    if (!retirementReason(wt.rec) && !wt.rec.archived && wt.rec.status !== 'queued') {
+        const harness = harnessById(wt.rec.harness || defaultHarness.id);
+        if (!harness.exactNativeTargetId(wt.rec)) {
+            await assertUnboundRetirementSafe(id, wt.rec, wt.path, wt.branch);
+            await tmuxOk(['kill-session', '-t', id]);
+            await assertTargetTmuxAbsent(id, 'after unbound residue retirement');
+            await harness.cleanupRuntime(wt.rec);
+            unboundRetired = true;
+        }
+        else {
+            // A confirmed terminal close may end an exact native turn before cold proof. Ordinary archive deliberately
+            // remains non-destructive while a turn is active; close already means discard this session's work.
+            assertSessionOwnerSafe(id, harness.id);
+            const interrupt = harness.interrupt;
+            if (interrupt) {
+                const result = await interrupt({ ...wt.rec, runtimeDir: runtimeRoot() });
+                if (!result.ok)
+                    throw new ResourceConflict(`refusing to close ${id}: native interrupt failed (${result.error || 'unknown error'})`);
+            }
+            const archived = await archiveSessionUnlocked(id);
+            if (!archived)
+                return false;
+            wt = await findWorktree(id);
+            if (!wt)
+                return false;
+        }
+    }
+    const target = wt;
+    return target.branch
+        ? withRecordLock(sessionCandidateLockId(target.path, target.branch), () => closeOwnedSessionUnlocked(id, target, source, unboundRetired))
+        : closeOwnedSessionUnlocked(id, target, source, unboundRetired);
+}
+export const closeSession = (id, rawSource) => {
+    const source = normalizeCloseSource(rawSource);
+    return withSessionTransition(id, () => withRecordLock(id, () => closeSessionUnlocked(id, source)));
+};
+const quarantineRoot = (id) => join(runtimeRoot(), 'corrupt', id);
+const recordSha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function normalizeQuarantineWitness(id, raw) {
+    if (!raw || typeof raw !== 'object')
+        throw new ResourceConflict(`refusing to quarantine ${id}: an exact adapter/thread/tmux/worktree/branch witness is required`);
+    const value = raw;
+    const text = (key) => typeof value[key] === 'string' ? value[key].trim() : '';
+    const adapter = text('adapter');
+    const tmux = text('tmux');
+    const worktree = text('worktree');
+    const branch = text('branch');
+    if (!Object.prototype.hasOwnProperty.call(value, 'thread'))
+        throw new ResourceConflict(`refusing to quarantine ${id}: thread witness must be explicit (a string or null)`);
+    const threadValue = value.thread;
+    const thread = typeof threadValue === 'string' && threadValue.trim() ? threadValue.trim() : threadValue == null || threadValue === '' ? null : null;
+    if (!adapter || !HARNESSES.some((h) => h.id === adapter))
+        throw new ResourceConflict(`refusing to quarantine ${id}: adapter must name one registered harness`);
+    if (tmux !== id)
+        throw new ResourceConflict(`refusing to quarantine ${id}: tmux witness must be the exact session id ${id}`);
+    if (!worktree || !isAbsolute(worktree))
+        throw new ResourceConflict(`refusing to quarantine ${id}: worktree witness must be an absolute path`);
+    if (!branch || branch.startsWith('-') || branch.startsWith('refs/'))
+        throw new ResourceConflict(`refusing to quarantine ${id}: branch witness must be one local branch name`);
+    if (threadValue !== undefined && threadValue !== null && typeof threadValue !== 'string')
+        throw new ResourceConflict(`refusing to quarantine ${id}: thread witness must be a string or null`);
+    return { adapter, thread, tmux, worktree: resolve(worktree), branch };
+}
+async function proveQuarantineTmuxAbsent(id) {
+    try {
+        await tmux(['has-session', '-t', id], TMUX_PROBE_TIMEOUT_MS);
+    }
+    catch (error) {
+        if (probeTimedOut(error))
+            throw new ResourceConflict(`refusing to quarantine ${id}: tmux absence is unknown (probe timed out)`);
+        if (typeof error.code === 'number')
+            return { state: 'absent' };
+        throw new ResourceConflict(`refusing to quarantine ${id}: tmux absence is unknown (${error instanceof Error ? error.message : String(error)})`);
+    }
+    throw new ResourceConflict(`refusing to quarantine ${id}: exact tmux session ${id} is live`);
+}
+async function proveQuarantineGitAbsent(id, witness) {
+    if (existsSync(witness.worktree))
+        throw new ResourceConflict(`refusing to quarantine ${id}: witnessed worktree ${witness.worktree} is live`);
+    const root = mainRoot();
+    const listed = await gitTry(['-C', root, 'worktree', 'list', '--porcelain']);
+    if (!listed.ok)
+        throw new ResourceConflict(`refusing to quarantine ${id}: worktree registry is unknown`);
+    const registered = listed.stdout.split('\n').filter((line) => line.startsWith('worktree ')).map((line) => resolve(line.slice('worktree '.length)));
+    if (registered.includes(witness.worktree))
+        throw new ResourceConflict(`refusing to quarantine ${id}: witnessed worktree ${witness.worktree} remains registered`);
+    const branch = await gitTry(['-C', root, 'show-ref', '--verify', '--quiet', `refs/heads/${witness.branch}`]);
+    if (branch.ok)
+        throw new ResourceConflict(`refusing to quarantine ${id}: witnessed branch ${witness.branch} is live`);
+    if (branch.failure !== 'exit')
+        throw new ResourceConflict(`refusing to quarantine ${id}: branch absence is unknown`);
+    return { worktree: { state: 'absent' }, branch: { state: 'absent' } };
+}
+function proveQuarantineLeafAbsent(id) {
+    const path = sessionArtifactPath(id, 'agent.pid');
+    let text;
+    try {
+        text = readFileSync(path, 'utf8').trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { state: 'absent', artifact: 'missing' };
+        throw new ResourceConflict(`refusing to quarantine ${id}: leaf PID artifact is unreadable`);
+    }
+    const pid = Number(text);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new ResourceConflict(`refusing to quarantine ${id}: leaf PID artifact is malformed`);
+    const start = processStartToken(pid);
+    if (start)
+        throw new ResourceConflict(`refusing to quarantine ${id}: registered agent process ${pid}@${start} is live or recycled`);
+    return { state: 'absent', artifact: `stale:${pid}` };
+}
+async function proveQuarantineAdapter(id, witness) {
+    const harness = harnessById(witness.adapter);
+    if (harness.ownsRendezvous) {
+        const socket = await rendezvousListening(id);
+        if (socket === 'live')
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${harness.id} rendezvous transport is live`);
+        if (socket === 'unproven')
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${harness.id} rendezvous transport absence is unknown`);
+    }
+    if (witness.thread) {
+        if (!harness.quarantineOrphanThread)
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${harness.id} has no archivable native thread; omit --thread (a SpexCode session id is not an adapter thread)`);
+        const native = await harness.quarantineOrphanThread(witness.thread, { excludingSessionId: id });
+        if (!native.ok)
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${native.reason}`);
+        return { adapter: native.audit.adapter, thread: native.audit.threadId, action: native.audit.action, compensate: native.compensate };
+    }
+    const descriptors = harness.sharedRuntimes?.(runtimeRoot()) ?? [];
+    for (const descriptor of descriptors) {
+        if (!descriptor.residency)
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${descriptor.label} has no exact absence census`);
+        let residency;
+        try {
+            residency = await descriptor.residency();
+        }
+        catch (error) {
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${descriptor.label} absence is unknown (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (!residency.healthy)
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${descriptor.label} absence is unknown (${residency.error || 'unhealthy census'})`);
+        if (!residency.rootAbsent || residency.referenceIds.length)
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${descriptor.label} is live; supply its exact native thread instead of claiming absence`);
+    }
+    return { adapter: harness.id, thread: null, action: 'absent', compensate: async () => ({ ok: true }) };
+}
+export async function quarantineCorruptRecord(id, rawWitness) {
+    return withSessionTransition(id, () => withRecordLock(id, async () => {
+        const entry = readRecordEntry(id);
+        if (entry.kind === 'absent')
+            throw new ResourceConflict(`refusing to quarantine ${id}: no active session record exists`);
+        if (entry.kind === 'ok')
+            throw new ResourceConflict(`refusing to quarantine ${id}: record is readable; use its ordinary lifecycle control`);
+        const witness = normalizeQuarantineWitness(id, rawWitness);
+        const original = readFileSync(entry.path);
+        const sha256 = recordSha256(original);
+        const observedAt = new Date().toISOString();
+        const leaf = proveQuarantineLeafAbsent(id);
+        const tmux = await proveQuarantineTmuxAbsent(id);
+        const git = await proveQuarantineGitAbsent(id, witness);
+        const adapter = await proveQuarantineAdapter(id, witness);
+        const bundle = join(quarantineRoot(id), `${observedAt.replace(/[:.]/g, '-')}-${randomUUID()}`);
+        const stored = join(bundle, 'session.json');
+        const provenance = join(bundle, 'provenance.json');
+        const audit = {
+            version: 1,
+            sessionId: id,
+            observedAt,
+            record: { activePath: entry.path, sha256, bytes: original.length },
+            witness,
+            observed: { leaf, tmux, ...git, adapter: { adapter: adapter.adapter, thread: adapter.thread, action: adapter.action } },
+        };
+        try {
+            mkdirSync(bundle, { recursive: true, mode: 0o700 });
+            const temp = `${provenance}.${process.pid}.${randomUUID()}.tmp`;
+            writeFileSync(temp, `${JSON.stringify(audit, null, 2)}\n`, { mode: 0o600 });
+            renameSync(temp, provenance);
+            const current = readRecordEntry(id);
+            if (current.kind !== 'corrupt' || current.path !== entry.path)
+                throw new ResourceConflict(`refusing to quarantine ${id}: active record changed during absence verification`);
+            const currentBytes = readFileSync(current.path);
+            if (recordSha256(currentBytes) !== sha256)
+                throw new ResourceConflict(`refusing to quarantine ${id}: opaque record changed during absence verification`);
+            renameSync(current.path, stored);
+            if (recordSha256(readFileSync(stored)) !== sha256) {
+                renameSync(stored, current.path);
+                throw new ResourceConflict(`refusing to quarantine ${id}: moved record failed byte-exact verification`);
+            }
+        }
+        catch (error) {
+            const restored = await adapter.compensate();
+            const suffix = restored.ok ? '' : `; native orphan compensation failed: ${restored.reason}`;
+            if (error instanceof ResourceConflict)
+                throw new ResourceConflict(`${error.message}${suffix}`);
+            throw new ResourceConflict(`refusing to quarantine ${id}: ${error instanceof Error ? error.message : String(error)}${suffix}`);
+        }
+        return { id, bundle, sha256, observedAt };
+    }));
+}
+export async function restoreQuarantinedRecord(id) {
+    return withSessionTransition(id, () => withRecordLock(id, async () => {
+        if (readRecordEntry(id).kind !== 'absent')
+            throw new ResourceConflict(`refusing to restore ${id}: an active session record already exists`);
+        let bundles;
+        try {
+            bundles = readdirSync(quarantineRoot(id), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort().reverse();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new ResourceConflict(`refusing to restore ${id}: no quarantine bundle exists`);
+            throw new ResourceConflict(`refusing to restore ${id}: quarantine bundle inventory is unreadable`);
+        }
+        const bundle = bundles.map((name) => join(quarantineRoot(id), name)).find((path) => existsSync(join(path, 'session.json')) && existsSync(join(path, 'provenance.json')));
+        if (!bundle)
+            throw new ResourceConflict(`refusing to restore ${id}: no complete quarantine bundle exists`);
+        const stored = join(bundle, 'session.json');
+        let provenance;
+        try {
+            provenance = JSON.parse(readFileSync(join(bundle, 'provenance.json'), 'utf8'));
+        }
+        catch {
+            throw new ResourceConflict(`refusing to restore ${id}: quarantine provenance is unreadable`);
+        }
+        const bytes = readFileSync(stored);
+        if (provenance.sessionId !== id || typeof provenance.record?.sha256 !== 'string' || provenance.record.sha256 !== recordSha256(bytes))
+            throw new ResourceConflict(`refusing to restore ${id}: quarantine payload/provenance binding is invalid`);
+        const active = sessionRecordPath(id);
+        mkdirSync(dirname(active), { recursive: true });
+        try {
+            renameSync(stored, active);
+        }
+        catch (error) {
+            throw new ResourceConflict(`refusing to restore ${id}: opaque record move failed (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (recordSha256(readFileSync(active)) !== provenance.record.sha256) {
+            renameSync(active, stored);
+            throw new ResourceConflict(`refusing to restore ${id}: restored record failed byte-exact verification`);
+        }
+        return { id, bundle, sha256: provenance.record.sha256, observedAt: new Date().toISOString() };
+    }));
+}
+function quarantineRecord(id) {
+    let entry;
+    try {
+        entry = readRecordEntry(id);
+    }
+    catch {
+        return null;
+    } // unreadable for another reason (permissions) — leave it
+    if (entry.kind !== 'corrupt')
+        return null;
+    try {
+        const shelf = join(runtimeRoot(), 'corrupt');
+        mkdirSync(shelf, { recursive: true });
+        const dest = join(shelf, `${id}-${new Date().toISOString().replace(/[:.]/g, '-')}.json`);
+        writeFileSync(dest, readFileSync(entry.path));
+        console.error(`spex: session ${id.slice(0, 8)} had an unreadable record; its original bytes are preserved at ${dest}`);
+        return dest;
+    }
+    catch (e) {
+        console.error(`spex: could not quarantine the unreadable record for ${id}: ${e instanceof Error ? e.message : e}`);
+        return null;
+    }
+}
+export async function captureSessionResult(id) {
+    if (!(await alive(id))) {
+        const known = (await listSessions(true)).some((s) => s.id === id);
+        return { ok: false, reason: known ? 'offline' : 'unknown' };
+    }
+    try {
+        return { ok: true, pane: await tmux(['capture-pane', '-e', '-p', '-t', id]) };
+    }
+    catch {
+        return { ok: false, reason: 'capture-failed' };
+    }
+}
+// @@@ watch - the event source for Claude Code's Monitor tool (first-class managing-agent support).
+// Polls the session list and emits the COMPLETE session lifecycle so it's a true "subscribe to all
+// session changes" feed: a LAUNCH (first sighting of an id, even though it enters at 'working', which is
+// not actionable — emitted ONCE per id so a manager learns a new session started), each ACTIONABLE state
+// transition — review / done / close-pending (agent proposals), offline (process died), error — and the
+// removal. Per Monitor's "silence is not success" rule a vanished session pings too. Net feed:
+// launched → [actionable transitions] → closed. Each line names the suggested next action(s). Drop into Monitor:
+//   Monitor({ command: 'spex session watch', persistent: true, description: 'session state changes' })
+// @@@ presentation + selection - shared by `spex session ls` (pretty), `spex session watch` (events) and the API.
+export const STATUS_GLYPH = {
+    working: '\u25cf', idle: '\u25cb', offline: '\u23fb', starting: '\u25d4', review: '\u25c6', done: '\u2713',
+    'close-pending': '\u2715', parked: '\u29d6', error: '\u2717', asking: '\u2370', queued: '\u25cc', unknown: '\u2047',
+    corrupt: '\u26a0', retired: '\u2691',
+};
+const ANSI = {
+    working: '33', idle: '90', offline: '90', starting: '36', review: '35', done: '34', 'close-pending': '31', parked: '36', error: '31', asking: '93', queued: '90', unknown: '93',
+    corrupt: '31', retired: '90',
+};
+// @@@ session selectors - the ONE matcher every session command shares (see [[session-selectors]]). A
+// selector matches a session iff it is the session's full id, an id-PREFIX, its node, its branch, or `.` for
+// the caller's own launched session. This is
+// the single predicate; selectSessions (MANY) and resolveSession (ONE) both call it, so id-prefix/node/branch
+// resolution can never drift between "which sessions ls/watch/wait/graph show" and "which session
+// review/merge/send/close act on".
+export function matchesSelector(s, q, own = ownSessionId(), cwd = process.cwd()) {
+    // a selector may be a comma-separated list (the same convention as `--status a,b`): it matches iff ANY part
+    // names the session, so `watch a,b` and `watch a b` are equivalent. A single name is the one-part case. This
+    // is what stops a comma-joined selector from silently matching nothing — an id/node/branch never holds a
+    // comma, so without the split `a,b` would be one literal selector that matches no session and streams in
+    // silence forever. Each part sheds an optional reference sigil (stripRefSigil): `@<sel>` / `[[<sel>]]` name
+    // the same session as the bare token, so the dashboard's mention grammar is tolerated in every CLI selector.
+    const sessionPath = s.path ? resolve(s.path) : null;
+    const callerPath = resolve(cwd);
+    const self = Boolean(own) && s.id === own
+        || Boolean(sessionPath) && (callerPath === sessionPath || callerPath.startsWith(`${sessionPath}${sep}`));
+    return q.split(',').map((p) => stripRefSigil(p.trim())).filter(Boolean)
+        .some((p) => p === '.' ? self : s.id === p || s.id.startsWith(p) || s.node === p || s.branch === p);
+}
+// no selectors (or '@all') = everything. Optional status filter on top. This IS the ls/watch subscription.
+export function selectSessions(all, selectors, statuses, own = ownSessionId(), cwd = process.cwd()) {
+    let out = all;
+    const sel = selectors.filter((x) => x && x !== '@all');
+    if (sel.length)
+        out = out.filter((s) => sel.some((q) => matchesSelector(s, q, own, cwd)));
+    if (statuses && statuses.length)
+        out = out.filter((s) => statuses.includes(s.status));
+    return out;
+}
+// Parentage is a durable direct pointer, even when that parent was terminally closed and no longer has a row.
+// The CLI's child scope must keep that fact visible rather than requiring callers to reverse-engineer prompts.
+export function selectChildren(all, parent) {
+    return all.filter((session) => session.parent === parent);
+}
+export function resolveSession(selector, sessions, own = ownSessionId(), cwd = process.cwd()) {
+    // the exact-id check sheds the optional sigil too, so `@<full-id>` keeps the exact-wins-over-prefix rule
+    const exact = sessions.find((s) => s.id === stripRefSigil(selector));
+    if (exact)
+        return { ok: exact };
+    const hits = sessions.filter((s) => matchesSelector(s, selector, own, cwd));
+    if (hits.length === 1)
+        return { ok: hits[0] };
+    return hits.length ? { ambiguous: hits } : { none: true };
+}
+// @@@ display width - the table aligns by TERMINAL CELLS, not code units. CJK/fullwidth glyphs render
+// two cells wide, so `slice`/`padEnd` (which count code units) shear a wide glyph mid-cut and under-pad
+// the column, misaligning everything after it. A small wcwidth-style range check covers the wide blocks
+// that actually reach session labels/prompts \u2014 no dependency needed.
+const isWideCp = (cp) => (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) || // CJK radicals \u2026 kana \u2026 CJK ideographs \u2026 Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+    (cp >= 0xff00 && cp <= 0xff60) || // fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) || // fullwidth signs
+    (cp >= 0x1f300 && cp <= 0x1faff) || // emoji
+    (cp >= 0x20000 && cp <= 0x3fffd); // CJK extensions B+
+export function displayWidth(s) {
+    let w = 0;
+    for (const ch of s)
+        w += isWideCp(ch.codePointAt(0)) ? 2 : 1;
+    return w;
+}
+// truncate to a display width (the ellipsis occupies its own cell); never cuts a wide glyph in half.
+export function truncWidth(s, max) {
+    if (displayWidth(s) <= max)
+        return s;
+    let w = 0;
+    let out = '';
+    for (const ch of s) {
+        const cw = isWideCp(ch.codePointAt(0)) ? 2 : 1;
+        if (w + cw > max - 1)
+            break;
+        out += ch;
+        w += cw;
+    }
+    return out + '\u2026';
+}
+// pad to a display width \u2014 `padEnd` would count a double-cell glyph as one and under-pad the column.
+export const padWidth = (s, w) => s + ' '.repeat(Math.max(0, w - displayWidth(s)));
+const trunc = truncWidth;
+// the board table's NOTE display cap \u2014 exported so the declaration echo (cli.ts) can tell an author
+// exactly where their note gets cut, instead of the cap living as an anonymous magic number here.
+export const NOTE_BOARD_LIMIT = 50;
+// short display label per status (only close-pending differs from the status name) \u2014 used by the legend.
+const SHORT = { 'close-pending': 'close' };
+// @@@ statusLegend - one-line glyph\u2192meaning key, BUILT from STATUS_GLYPH so it can never drift from
+// the glyphs the table actually prints. Shown under `spex session ls` so the symbols are self-explanatory.
+export function statusLegend(color = true) {
+    const c = (code, t) => (color ? `\x1b[${code}m${t}\x1b[0m` : t);
+    const parts = Object.keys(STATUS_GLYPH).map((k) => `${c(ANSI[k], STATUS_GLYPH[k])} ${SHORT[k] || k}`);
+    return c('90', '  key: ') + parts.join('  ');
+}
+function statusSummary(sessions) {
+    const counts = new Map();
+    for (const session of sessions)
+        counts.set(session.status, (counts.get(session.status) || 0) + 1);
+    return Object.keys(STATUS_GLYPH)
+        .flatMap((status) => {
+        const count = counts.get(status);
+        return count ? [`${count} ${SHORT[status] || status}`] : [];
+    })
+        .join(' · ');
+}
+export function formatTable(sessions, color = true, scope = { kind: 'sessions' }) {
+    const c = (code, t) => (color ? `\x1b[${code}m${t}\x1b[0m` : t);
+    const label = scope.kind === 'children' ? `children of ${scope.parent.slice(0, 8)}` : 'sessions';
+    const heading = c('1', `SpexCode ${label} (${sessions.length}${sessions.length ? `; ${statusSummary(sessions)}` : ''})`);
+    if (!sessions.length)
+        return [heading, c('90', `  no ${scope.kind === 'children' ? 'children' : 'living sessions'}`)].join('\n');
+    const header = c('90', `    ${'STATUS'.padEnd(13)} ${'TITLE'.padEnd(22)} ${'ID'.padEnd(8)} ${'PARENT'.padEnd(8)} ${'\u00d7'.padEnd(4)}${'PROMPT'.padEnd(42)}NOTE`);
+    const rows = sessions.map((s) => {
+        const g = STATUS_GLYPH[s.status] ?? '\u00b7';
+        const code = ANSI[s.status] ?? '0';
+        const title = padWidth(truncWidth(sessionTitle(s), 22), 22);
+        const st = s.status.padEnd(13);
+        const parent = c('90', (s.parent || '-').slice(0, 8).padEnd(8));
+        const merges = (s.merges ? `\u00d7${s.merges}` : '').padEnd(4);
+        const prompt = c('90', padWidth(s.promptPreview ? trunc(s.promptPreview, 40) : '', 42)); // what it was asked to do
+        const note = s.note ? c('90', trunc(s.note, NOTE_BOARD_LIMIT)) : '';
+        return `  ${c(code, g)} ${c(code, st)} ${title} ${c('90', s.id.slice(0, 8))} ${parent} ${merges}${prompt}${note}`;
+    });
+    return [heading, header, ...rows, statusLegend(color)].join('\n');
+}
+class StrandedDeliveryError extends Error {
+}
+async function strandedDeliveryError(rec) {
+    const h = harnessById(rec.harness || defaultHarness.id);
+    if (!h.deliveryTransport)
+        return null;
+    const transport = await h.deliveryTransport({ ...rec, runtimeDir: runtimeRoot() });
+    if (transport.kind !== 'unreachable' || agentAlive(rec.session) !== true)
+        return null;
+    const queued = pendingMessages(rec.session).length;
+    const noun = queued === 1 ? 'message is' : 'messages are';
+    return new StrandedDeliveryError(`session ${rec.session} is stranded: ${transport.reason} while its registered agent process is still alive; ${queued} queued ${noun} waiting with no transport to claim them. Use \`spex session send ${rec.session} --keys "<keys>"\` to steer the live tmux pane, then repair the control transport before sending text.`);
+}
+export async function sendText(id, text, from, opts = {}) {
+    if (!text)
+        return { ok: false, error: 'empty prompt — nothing to dispatch' };
+    let replayed = false;
+    try {
+        // Taking a declared sender's record lock makes close a real outgoing fence even across backend processes:
+        // a send either appends before close obtains the fence (and close's revocation voids its debt), or sees
+        // the terminal marker before it records anything. Arbitrary legacy `from` values keep working; they just
+        // name an otherwise-unused lock until a matching session is closed.
+        let rec = null;
+        const accepted = await acceptMessage({
+            target: id,
+            text,
+            from,
+            idempotency: opts.idempotency,
+            validate: async () => {
+                rec = readRecord(id);
+                if (!rec)
+                    throw new ResourceConflict(`no session record for ${id} — prompt NOT delivered`);
+            },
+            prepare: async () => {
+                await opts.acceptGuard?.(rec);
+                const stranded = await strandedDeliveryError(rec);
+                if (stranded)
+                    throw stranded;
+                // Composed at ACCEPT time, once: the log keeps the raw conversational text plus the effective reply channel,
+                // the queue keeps the transport form. Composing again at handover would let a later send change the hints on
+                // a message that was already accepted.
+                const prompt = await composeSessionPrompt(text, rec, { from, replyVia: opts.replyVia });
+                return { text: prompt.text, ...(prompt.replyVia ? { replyVia: prompt.replyVia } : {}) };
+            },
+        });
+        replayed = accepted.replayed;
+    }
+    catch (error) {
+        const code = error?.code;
+        const detail = error instanceof StrandedDeliveryError
+            ? error.message
+            : `could not append the message to session ${id}'s log: ${error instanceof Error ? error.message : String(error)} — prompt NOT delivered`;
+        return {
+            ok: false,
+            error: detail,
+            ...(code ? { code } : {}),
+        };
+    }
+    // Awaited, not fire-and-forget: an unawaited insert can lose its race with a short-lived caller's exit,
+    // costing that send its same-turn arrival. Draining HERE rather than leaving it to the sweep is what puts
+    // the text in a live agent's current turn instead of up to one tick later.
+    if (!opts.deferDrain)
+        await drainSession(id);
+    return { ok: true, ...(opts.idempotency ? { replayed } : {}) };
+}
+// @@@ drainSession - hand over what this session is owed, as ordinary prompts. Safe to call from anywhere and
+// at any time: the queue's own lock serializes concurrent passes, and an empty queue costs one existsSync.
+// The retry sweep in `serve` calls this for the sessions whose queues an earlier pass could not empty.
+export async function drainSession(id) {
+    if (!owesDelivery(id))
+        return;
+    const rec = readRecord(id);
+    if (!rec)
+        return;
+    const h = harnessById(rec.harness || defaultHarness.id);
+    if (h.launchPayloadProof && !rec.harnessSessionId)
+        return;
+    await drain(id, async (msg) => {
+        // the pane guard ([[harness-adapter]] deliveryBlockedBy): the ONE pane state where the harness swallows a
+        // prompt its channel confirms (claude's sessions panel), checkable only from the pane. Treated as a REFUSAL
+        // rather than a skip — the message stays owed and the sweep hands it over once the pane leaves that state.
+        if (h.deliveryBlockedBy) {
+            try {
+                if (h.deliveryBlockedBy(await tmux(['capture-pane', '-p', '-t', rec.session], TMUX_PROBE_TIMEOUT_MS)))
+                    return false;
+            }
+            catch { /* no pane to consult — let the insert itself decide */ }
+        }
+        const delivered = await h.deliver({ ...rec, runtimeDir: runtimeRoot(), mid: msg.mid }, msg.text);
+        return delivered.ok;
+    });
+}
+// Hard interrupt is adapter-native control, distinct from stop's process teardown. A harness without a
+// confirmed native primitive refuses loudly; there is no signal/PTY fallback that could target the wrong turn.
+export async function interruptSession(id) {
+    return withRecordLock(id, async () => {
+        const rec = readRecord(id);
+        if (!rec)
+            return { ok: false, error: `no session record for ${id} - nothing to interrupt` };
+        const h = harnessById(rec.harness || defaultHarness.id);
+        if (!h.interrupt)
+            return { ok: false, error: `harness ${h.id} has no native hard-interrupt control` };
+        return h.interrupt({ ...rec, runtimeDir: runtimeRoot() });
+    });
+}
+// @@@ rawKey - the RAW-KEYSTROKE nav path, kept DELIBERATELY on `tmux send-keys` and NEVER the rendezvous
+// socket. Two channels, two jobs: the socket INJECTS a whole prompt (text + submit), which can drive the
+// agent's normal prompt but CANNOT navigate an interactive TUI select menu (e.g. `/model`'s list — ↑/↓ to
+// move, ←/→ to adjust, Enter to set, `s` for this-session, Esc to cancel). When the agent is in that
+// keystroke-navigation state its input box is replaced by the menu, so the CLI raw-key fallback forwards
+// each key here in real time. send-keys is exactly right for single raw keys: named keys map to tmux's own
+// key names; a single printable char is sent literally (`-l`) so tmux doesn't reinterpret it. The dashboard
+// also drives the agent with MODIFIER COMBOS — a terminal's three modifiers carried as a `C-`/`M-`/`S-`
+// prefix on the token (e.g. `C-r`, `M-b`, `S-Tab`, `C-M-x`); those are passed to tmux UNescaped so it parses
+// the combo. One key per call, no socket and no Enter-synthesis — this IS the send-keys channel. False if
+// the tmux session is gone, or if the token isn't a known base after its prefixes (defends the send-keys arg).
+const TMUX_KEY = {
+    Up: 'Up', Down: 'Down', Left: 'Left', Right: 'Right',
+    Enter: 'Enter', Escape: 'Escape', Tab: 'Tab', Space: 'Space', Backspace: 'BSpace',
+    Home: 'Home', End: 'End', Delete: 'DC',
+};
+// tmux honours an `S-` (shift) modifier ONLY on these named keys; on Enter/Space/BSpace it would send the
+// literal text "S-Enter" etc. (and shift is a no-op there anyway), so a stray S- is dropped. Shift+Tab is
+// the named exception: tmux spells it `BTab` (back-tab → ESC[Z, what Claude Code's mode-cycle reads).
+const SHIFTABLE = new Set(['Up', 'Down', 'Left', 'Right', 'Home', 'End', 'DC']);
+// resolve ONE frontend token to the `tmux send-keys` args for it, or null if it isn't a known base after its
+// prefixes (defends the send-keys arg). Pure — the batch loop below sequences the actual sends.
+function rawKeyArgs(id, key) {
+    // peel the optional C-/M-/S- modifier prefixes (each at most once, in any order) off the front; the
+    // remainder is the BASE key. The frontend only ever sends {C-,M-,S-} prefixes + a named key or one char.
+    let rest = key, prefix = '';
+    const seen = new Set();
+    while (rest.length >= 2 && (rest[0] === 'C' || rest[0] === 'M' || rest[0] === 'S') && rest[1] === '-' && !seen.has(rest[0])) {
+        seen.add(rest[0]);
+        prefix += rest.slice(0, 2);
+        rest = rest.slice(2);
+    }
+    const named = TMUX_KEY[rest];
+    if (named) {
+        const noShift = prefix.replace('S-', ''); // C-/M- without the shift bit
+        let token;
+        if (prefix.includes('S-') && named === 'Tab')
+            token = noShift + 'BTab'; // Shift+Tab → back-tab
+        else if (prefix.includes('S-') && !SHIFTABLE.has(named))
+            token = noShift + named; // tmux can't carry S- here
+        else
+            token = prefix + named;
+        return ['send-keys', '-t', id, token];
+    }
+    if ([...rest].length === 1) {
+        // a single printable char: bare → literal (`-l`, so tmux never reinterprets it as a key name);
+        // modified → hand tmux the `C-`/`M-`/`S-` combo to parse (e.g. `C-a`), which `-l` would defeat.
+        if (prefix)
+            return ['send-keys', '-t', id, prefix + rest];
+        return ['send-keys', '-t', id, '-l', '--', rest];
+    }
+    return null;
+}
+// One call carries a BATCH of tokens (or one) — the client coalesces fast typing into an ordered array. Order
+// is the whole point ([[nav-mode-key-ordering]]): the keys are sent by ONE awaited `send-keys` each, IN ARRAY
+// ORDER, so they reach the pane in exactly the order they were struck. Concurrent per-key POSTs used to race
+// (browser + server + send-keys all parallel) and scramble the sequence; a single serialised batch cannot.
+// An unknown token is skipped without dropping the rest; false only if the tmux session is gone or nothing sent.
+export async function rawKey(id, key) {
+    return withRecordLock(id, async () => {
+        const list = (Array.isArray(key) ? key : [key]).filter((k) => typeof k === 'string' && k.length > 0);
+        if (list.length === 0 || !(await alive(id)))
+            return false;
+        let sent = false;
+        for (const k of list) {
+            const args = rawKeyArgs(id, k);
+            if (!args)
+                continue;
+            await tmux(args);
+            sent = true;
+        }
+        return sent;
+    });
+}