@spexcode/spec-cli 0.7.0-next.0 → 0.7.0-next.10

package/dist/client.js

@@ -132,10 +132,10 @@ const post = (body) => ({ method: 'POST', headers: { 'content-type': 'applicatio
 const seg = (id) => encodeURIComponent(id);
 // A rendezvous liveness probe can displace the real delivery client.
 function cachedStatus(rec) {
-    if (!rec.worktreePath || !existsSync(rec.worktreePath))
-        return 'retired';
     if (rec.archived)
         return 'offline';
+    if (!rec.worktreePath || !existsSync(rec.worktreePath))
+        return 'retired';
     if (rec.status === 'awaiting')
         return displayStatusForProposal(rec.proposal);
     return rec.status === 'active' || rec.status === 'idle' ? 'unknown' : rec.status;
@@ -179,9 +179,11 @@ export function localCachedSessions(includeArchived = false) {
         if (!state)
             continue;
         const lifecycle = state.status;
-        const status = state.status === 'awaiting'
-            ? displayStatusForProposal(state.proposal)
-            : state.status === 'archived' ? 'offline' : state.status;
+        const status = state.status === 'archived'
+            ? 'offline'
+            : state.status === 'awaiting'
+                ? displayStatusForProposal(state.proposal)
+                : state.status;
         rows.push({
             id,
             node: null,

package/dist/codex-runtime-generations.d.ts

@@ -46,6 +46,10 @@ export declare function prepareCodexGenerationClose(root: string, sessionId: str
 export declare function repinCodexGeneration(root: string, sessionId: string, threadId: string, generationId: string): void;
 export declare function resolveCodexGenerationForResume(root: string, sessionId: string, threadId: string, start: (endpoint: CodexGenerationEndpoint) => Promise<void>): Promise<CodexGenerationEndpoint | null>;
 export declare function resolveCodexGenerationForSession(root: string, sessionId: string, threadId: string): CodexGenerationEndpoint | null;
+export declare function resolveCodexGenerationForClose(root: string, sessionId: string, threadId: string): {
+    endpoint: CodexGenerationEndpoint;
+    gone: boolean;
+} | null;
 export declare function codexGenerationBindingForSession(root: string, sessionId: string): CodexGenerationBinding | null;
 export declare function currentCodexGeneration(root: string): CodexGenerationEndpoint | null;
 export declare function codexGenerationEndpoints(root: string): CodexGenerationEndpoint[];

package/dist/codex-runtime-generations.js

@@ -765,6 +765,18 @@ export function resolveCodexGenerationForSession(root, sessionId, threadId) {
     const generation = ledger.generations[binding.generationId];
     return generation && generation.state !== 'reclaimed' ? generation.endpoint : null;
 }
+// Close still needs the immutable endpoint record to recognize a positively retired generation. The
+// endpoint is never used for native I/O in this state; it only identifies the empty control plane.
+export function resolveCodexGenerationForClose(root, sessionId, threadId) {
+    const ledger = readCodexGenerationLedger(root);
+    const binding = ledger.bindings[sessionId];
+    if (!binding || binding.threadId !== threadId)
+        return null;
+    const generation = ledger.generations[binding.generationId];
+    if (!generation)
+        return null;
+    return { endpoint: generation.endpoint, gone: generation.state === 'reclaimed' };
+}
 export function codexGenerationBindingForSession(root, sessionId) {
     return readCodexGenerationLedger(root).bindings[sessionId] ?? null;
 }

package/dist/graphSnapshot.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { loadSpecs, requireGitWorkspace, headSha } from '@spexcode/spec-core';
 import { resolveLayout } from '@spexcode/spec-core';
 import { listSessions } from './sessions.js';
-import { driftIndex, historyIndex, repoRoot } from '@spexcode/spec-core';
+import { driftIndex, historyIndex, pruneHistoryCaches, repoRoot } from '@spexcode/spec-core';
 import { residentForgeRevision, residentForgeState } from '@spexcode/spec-forge/resident';
 import { resolveForgeHost } from '@spexcode/spec-forge/drivers';
 import { boardThreads } from './issues.js';
@@ -56,6 +56,9 @@ export async function boardSnapshot() {
     const root = repoRoot();
     requireGitWorkspace(root);
     const [specs, sessions] = await Promise.all([loadSpecs(), listSessions()]);
+    // Session worktrees are the live-root census for immutable history caches. Reconcile before the snapshot
+    // returns so closing a session releases its full index immediately rather than waiting for an LRU slot.
+    pruneHistoryCaches([root, ...sessions.map((session) => session.path)]);
     const layout = await resolveLayout({ activeSessionIds: sessions.map((session) => session.id) });
     const nodeIds = [...new Set([
             ...specs.map((node) => node.id),

package/dist/harness.d.ts

@@ -206,6 +206,7 @@ export type DispatchResult = {
 };
 export type HarnessDeliveryRecord = {
     session: string;
+    harness?: string;
     stopped?: boolean;
     archived?: boolean;
     worktreePath?: string;

package/dist/harness.js

@@ -18,7 +18,8 @@ import { runtimeRoot, mainCheckout, readConfig, sessionArtifactPath, spexcodeHom
 import { git } from '@spexcode/spec-core';
 import { shQuote } from './sh.js';
 import { detachedRuntimeGenerationToken, migrateLegacyDetachedRuntimeReceipt, processStartToken, verifyDetachedRuntime } from '@spexcode/spec-core';
-import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, resolveCodexGenerationForSession } from './codex-runtime-generations.js';
+import { codexGenerationEndpoints, codexGenerationSocketPath, currentCodexGeneration, legacyCodexGenerationEndpoint, readCodexGenerationLedger, prepareCodexGenerationClose, resolveCodexGenerationForClose, resolveCodexGenerationForResume, resolveCodexGenerationForSession } from './codex-runtime-generations.js';
+import { spawnDetachedRuntime } from './runtime-ownership.js';
 import { writeFileIfChanged } from './file-write.js';
 import { claudeTranscript, codexRolloutPath, codexTranscript, opencodeTranscript, piTranscript, unsupportedTranscript } from '@spexcode/transcript';
 import { harnessIdentity, HARNESS_IDENTITIES } from '@spexcode/spec-core';
@@ -220,12 +221,14 @@ function codexMutationGeneration(dir = runtimeRoot(), endpoint = legacyCodexGene
     return codexRuntimeGeneration(dir, endpoint);
 }
 const codexDescriptorKey = (endpoint) => endpoint.id === 'legacy' ? 'codex-app-server' : `codex-app-server:${endpoint.id}`;
-function codexEndpointForRecord(rec, dir = runtimeRoot()) {
+function codexEndpointForRecord(rec, dir = runtimeRoot(), includeGone = false) {
     if (!rec.harnessSessionId)
         return null;
     const ledger = readCodexGenerationLedger(dir);
     if (ledger.revision === 0 && !ledger.current && !Object.keys(ledger.generations).length)
         return legacyCodexGenerationEndpoint(dir);
+    if (includeGone)
+        return resolveCodexGenerationForClose(dir, rec.session, rec.harnessSessionId)?.endpoint ?? null;
     return resolveCodexGenerationForSession(dir, rec.session, rec.harnessSessionId);
 }
 // the spex launcher (bin/spex.mjs), baked into the codex launch script (mirrors materialize.ts's SPEX) so
@@ -2280,7 +2283,21 @@ async function deliverViaCodexAppServer(rec, text) {
     // the socket is PER-PROJECT (the runtime root), shared by every worktree's thread; the owned thread id on
     // the record picks out THIS session's thread.
     const runtimeDir = rec.runtimeDir ?? runtimeRoot();
-    const endpoint = rec.harnessSessionId ? codexEndpointForRecord(rec, runtimeDir) : currentCodexGeneration(runtimeDir);
+    let endpoint = rec.harnessSessionId ? codexEndpointForRecord(rec, runtimeDir) : currentCodexGeneration(runtimeDir);
+    // A generation may be reclaimed after rotation or a host restart while the session record remains valid.
+    // Repair that stale route at the delivery boundary using the same exact-thread re-pin used by resume, so an
+    // accepted message is not left indefinitely in the queue just because no later human resume was requested.
+    if ((!endpoint || !existsSync(endpoint.socketPath)) && rec.harnessSessionId) {
+        const command = codexBaseCmd(rec.launchCmd || 'codex');
+        const env = { ...process.env };
+        for (const key of sessionIdentityEnvVars())
+            delete env[key];
+        const start = async (candidate) => {
+            await spawnDetachedRuntime({ cwd: runtimeDir, logFile: candidate.logFile, pidFile: candidate.pidFile,
+                receiptFile: candidate.receiptFile, command, args: ['app-server', '--listen', `unix://${candidate.socketPath}`], env });
+        };
+        endpoint = await resolveCodexGenerationForResume(runtimeDir, rec.session, rec.harnessSessionId, start);
+    }
     if (!endpoint)
         return { ok: false, error: `no exact Codex generation binding for session ${rec.session} — immediate poke unavailable` };
     const sock = endpoint.socketPath;
@@ -2295,6 +2312,14 @@ async function deliverViaCodexAppServer(rec, text) {
             return { ok: false, error: `${r.error} — immediate poke unavailable` };
         threadId = r.threadId;
     }
+    const delivered = await sendCodexAppServerTurn(sock, threadId, text, rec.worktreePath, rec.mid);
+    if (delivered.ok || rec.harness !== 'codex-headless' || !/not loaded in the app-server/u.test(delivered.error || ''))
+        return delivered;
+    // Headless Codex has no TUI resume step. An idle thread can be evicted from the shared server's loaded set;
+    // reload the exact rollout, then retry the same turn once. This is idempotent and does not create a new thread.
+    const reopened = await codexReopenThread(sock, threadId);
+    if (!reopened.ok)
+        return { ok: false, error: `${delivered.error}; ${reopened.error}` };
     return sendCodexAppServerTurn(sock, threadId, text, rec.worktreePath, rec.mid);
 }
 // idempotent replace of the content between sentinels; the user's own content above/below is preserved. The
@@ -2784,7 +2809,9 @@ const socketListenerLiveness = (_rec, tmuxAlive, _runtimeDir, _pane, socketLive)
 const socketListenerOrPidAliveLiveness = (_rec, tmuxAlive, _runtimeDir, pane, socketLive) => (tmuxAlive && (!!socketLive || pane?.pidAlive === true) ? 'online' : 'offline');
 const panePidLiveness = (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && pane?.pidAlive === true ? 'online' : 'offline');
 const recordOnline = (rec) => rec.stopped ? 'offline' : 'online';
-const sessionHomeLiveness = (_rec, tmuxAlive) => tmuxAlive ? 'online' : 'offline';
+// Leaf-backed headless sessions are the controller process, not the tmux pane that hosts it. The pane can
+// survive a SIGKILL as a bare shell, so tmux presence without the launch-registered PID is never online.
+const sessionHomeLiveness = (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && pane?.pidAlive === true ? 'online' : 'offline');
 // @@@ unlinkSocks - remove ONLY the transport this teardown PROVED dead. `cleanupRuntime` unlinks *their*
 // socket, and the honest test of "theirs" is that the agent it just killed is GONE. It used to unlink on
 // faith, which is unsound because a socket path is derived from the session id ALONE: it is the one
@@ -2889,6 +2916,7 @@ export const claudeHeadlessHarness = {
     paneTitleIsSelfSummary: false,
     launchCmd: (id, runtimeDir, cmd) => claudeHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), claudeBaseCmd(cmd)),
     launchEnv: noLaunchEnv,
+    // The controller's registered PID is the liveness witness; the tmux home is only the address boundary.
     liveness: sessionHomeLiveness,
     deliveryTransport: unprovenDeliveryTransport,
     deliver: deliverViaClaudeHeadless,
@@ -3025,7 +3053,7 @@ export const codexHarness = {
     interrupt: interruptCodexTurn,
     cleanupRuntime: async () => { },
     targetDescriptorKey: (rec) => {
-        const endpoint = codexEndpointForRecord(rec);
+        const endpoint = codexEndpointForRecord(rec, runtimeRoot(), true);
         return endpoint ? codexDescriptorKey(endpoint) : null;
     },
     coldRetirementPreflight: async (rec) => {
@@ -3049,8 +3077,13 @@ export const codexHarness = {
     coldPreflight: async (rec) => {
         if (!rec.harnessSessionId)
             return { ok: false, reason: 'no exact Codex thread identity is registered' };
-        const endpoint = codexEndpointForRecord(rec);
-        return endpoint ? codexColdPreflight(rec.harnessSessionId, runtimeRoot(), undefined, endpoint)
+        const dir = runtimeRoot();
+        const binding = resolveCodexGenerationForClose(dir, rec.session, rec.harnessSessionId);
+        if (binding?.gone) {
+            return { ok: true, alreadyCold: true };
+        }
+        const endpoint = binding?.endpoint ?? codexEndpointForRecord(rec, dir);
+        return endpoint ? codexColdPreflight(rec.harnessSessionId, dir, undefined, endpoint)
             : { ok: false, reason: 'no exact Codex generation binding is registered for this target' };
     },
     coldRuntime: async (rec, suppliedReceipt) => {
@@ -3058,7 +3091,12 @@ export const codexHarness = {
             return { ok: false, reason: 'no exact Codex thread identity is registered' };
         const threadId = rec.harnessSessionId;
         const dir = runtimeRoot();
-        const endpoint = codexEndpointForRecord(rec, dir);
+        const binding = resolveCodexGenerationForClose(dir, rec.session, threadId);
+        if (binding?.gone) {
+            prepareCodexGenerationClose(dir, rec.session, threadId);
+            return { ok: true };
+        }
+        const endpoint = binding?.endpoint ?? codexEndpointForRecord(rec, dir);
         if (!endpoint)
             return { ok: false, reason: 'no exact Codex generation binding is registered for this target' };
         const sock = endpoint.socketPath;
@@ -3400,6 +3438,7 @@ export const piHeadlessHarness = {
     runtimeOwnership: 'leaf',
     paneTitleIsSelfSummary: false,
     launchCmd: (id, runtimeDir, cmd) => piHeadlessLaunchCommand(id, runtimeDir ?? runtimeRoot(), piBaseCmd(cmd)),
+    // The controller's registered PID is the liveness witness; the tmux home is only the address boundary.
     liveness: sessionHomeLiveness,
     deliver: deliverViaPiHeadless,
     // the controller aborts its own turn child natively and confirms only once that child is gone
@@ -3513,6 +3552,7 @@ export const opencodeHeadlessHarness = {
     runtimeOwnership: 'leaf',
     deliveryTransport: unprovenDeliveryTransport,
     launchCmd: (_id, _runtimeDir, cmd) => opencodeHeadlessLaunchCommand(opencodeBaseCmd(cmd)),
+    // The controller's registered PID is the liveness witness; the tmux home is only the address boundary.
     liveness: sessionHomeLiveness,
     coldRuntime: async (rec) => {
         const result = await opencodeHeadlessColdRuntime(rec);

package/dist/host-resources.js

@@ -145,6 +145,23 @@ const descendants = (root, procs) => {
     }
     return ids;
 };
+// tmux is a shared host for many independent session windows. Its inherited environment is therefore
+// not a launch receipt: a token on the server or one of its panes cannot charge the whole hosted tree.
+const isTmuxServer = (proc) => proc?.command === 'tmux: server';
+const hasTmuxAncestor = (pid, procs) => {
+    const seen = new Set();
+    let next = procs.get(pid)?.ppid;
+    while (next && !seen.has(next)) {
+        seen.add(next);
+        const parent = procs.get(next);
+        if (!parent)
+            return false;
+        if (isTmuxServer(parent))
+            return true;
+        next = parent.ppid;
+    }
+    return false;
+};
 const publicRecordInventory = () => {
     const entries = listSessionIds().map(readPublicRecordEntry);
     const application = configuredSessionApplicationIfCutover();
@@ -216,6 +233,29 @@ const unresolvedHarnessOwners = (recs, budgets, have) => {
     }
     return out;
 };
+// A leaf-backed headless controller is the session's runtime. Keep its durable row visible when the controller
+// disappears before the next resources sweep can attribute a process, and name the status/liveness contradiction
+// explicitly so a supervisor cannot mistake the missing process for a cleanly idle session.
+const missingHeadlessControllerOwners = (recs, procs, budgets, have) => {
+    const out = [];
+    for (const rec of recs) {
+        const harness = harnessByIdOrNull(rec.harness || defaultHarness.id);
+        if (!rec.governed || rec.stopped || rec.archived || rec.status !== 'active' && rec.status !== 'idle'
+            || harness?.runtimeOwnership !== 'leaf' || have(rec.session_id))
+            continue;
+        const pid = runtimePid(join(runtimeRoot(), 'sessions', rec.session_id, 'agent.pid'));
+        if (pid && procs.has(pid))
+            continue;
+        out.push({
+            kind: 'session', id: rec.session_id, label: `session ${rec.session_id.slice(0, 8)}`, status: rec.status, liveness: 'offline',
+            processes: [], rssMiB: 0, pssMiB: null, cpuPercent: 0,
+            budget: { rssMiB: budgets.sessionRssMiB, idleCpuPercent: budgets.idleCpuPercent },
+            findings: [`headless-liveness-contradiction:${rec.status}/offline`],
+            reclaim: { eligible: false, reason: 'headless controller is absent; lifecycle repair must be explicit' },
+        });
+    }
+    return out;
+};
 const sharedDescriptors = (recs, retainRegistry = false) => {
     const out = new Map();
     for (const harness of HARNESSES)
@@ -322,13 +362,13 @@ const buildInventory = (procs, publicRecords = publicRecordInventory()) => {
     for (const p of procs.values()) {
         const acting = actingSession(p);
         const fallback = p.env.SPEXCODE_SESSION_ID;
-        const sid = acting ?? (fallback ? byId.get(fallback) : undefined);
+        const sid = acting ?? (!hasTmuxAncestor(p.pid, procs) && !isTmuxServer(p) && fallback ? byId.get(fallback) : undefined);
         if (sid)
             ownership.set(p.pid, `session:${sid}`);
     }
     for (const rec of activeRecs) {
         const root = runtimePid(join(runtimeRoot(), 'sessions', rec.session_id, 'agent.pid'));
-        if (root && procs.has(root))
+        if (root && procs.has(root) && !isTmuxServer(procs.get(root)))
             for (const pid of descendants(root, procs))
                 if (!ownership.has(pid))
                     ownership.set(pid, `session:${rec.session_id}`);
@@ -368,7 +408,7 @@ const buildInventory = (procs, publicRecords = publicRecordInventory()) => {
     }
     const root = repoRoot();
     for (const p of procs.values()) {
-        if (ownership.has(p.pid) || p.env.SPEXCODE_PROJECT_ROOT !== root)
+        if (ownership.has(p.pid) || p.env.SPEXCODE_PROJECT_ROOT !== root || hasTmuxAncestor(p.pid, procs) || isTmuxServer(p))
             continue;
         const claimed = p.env.SPEXCODE_SESSION_ID;
         if (claimed && !byId.has(claimed))
@@ -448,6 +488,17 @@ const sessionStopBlocker = async (id, harnessId, recs = rawRecords(), knownProbe
         const entryTargetThread = entry.recs.find((rec) => rec.session_id === id)?.harness_session_id;
         if (entryTargetThread && ownerCounts.get(entryTargetThread) !== 1)
             return `${descriptor.label} target thread ${entryTargetThread} has no one exact governed session owner`;
+        // A retired shared generation is positive death, not an unknown control plane. Its residency census is
+        // the only proof needed here; there is no native target left to signal or unload.
+        if (descriptor.residency && entryTargetThread) {
+            let residency = null;
+            try {
+                residency = await descriptor.residency();
+            }
+            catch { /* retain the normal fail-closed path */ }
+            if (residency?.healthy && residency.rootAbsent === true && residency.referenceIds.length === 0)
+                continue;
+        }
         if (!knownProbes && descriptor.mutationGuard) {
             if (!targetThread)
                 return `${descriptor.label} target has no exact governed thread identity`;
@@ -722,6 +773,7 @@ export async function collectResourceReport(opts = {}) {
                 budget: { rssMiB: budgets.sessionRssMiB, idleCpuPercent: budgets.idleCpuPercent },
                 findings: [`session-record-corrupt:${entry.error}`], reclaim: { eligible: false, reason: 'session record is corrupt; ownership and lifecycle are unknown' },
             });
+    owners.push(...missingHeadlessControllerOwners(inv.recs, inv.procs, budgets, (sessionId) => owners.some((owner) => owner.kind === 'session' && owner.id === sessionId)));
     owners.push(...unresolvedHarnessOwners(inv.recs, budgets, (sessionId) => owners.some((owner) => owner.kind === 'session' && owner.id === sessionId)));
     // A referenced shared runtime with no readable process is still operationally important: keep its live or
     // unknown refcount visible instead of silently omitting it from a process-derived report.

package/dist/materialize.js

@@ -1,4 +1,4 @@
-import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, renameSync, rmSync, rmdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, renameSync, rmSync, rmdirSync, copyFileSync, chmodSync } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
@@ -37,6 +37,58 @@ const DISPATCH = join(PKG, 'hooks', 'dispatch.sh');
 // CLI code and keeps the source-workspace mid-merge guard (one line + exit 75), so every hook callback
 // inherits both.
 const SPEX = join(PKG, 'bin', 'spex.mjs');
+const CORE_TEMPLATE = join(PKG, 'templates', 'spec', 'project', '.plugins', 'core');
+// Core hook handlers are shipped executable protocol, not adopter-owned plugin variants. Reconcile only the
+// known `core/` subtree before compiling the manifest so a project seeded by an older toolchain cannot keep
+// invoking a retired lifecycle writer. User plugins live outside this allowlist and are never enumerated.
+function refreshCorePluginHandlers(proj) {
+    if (!existsSync(CORE_TEMPLATE))
+        return [];
+    const specDir = join(proj, '.spec');
+    const roots = existsSync(specDir)
+        ? readdirSync(specDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && existsSync(join(specDir, entry.name, '.plugins', 'core')))
+            .map((entry) => join(specDir, entry.name, '.plugins', 'core'))
+        : [];
+    const handlers = [];
+    const walk = (dir, prefix = '') => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const rel = join(prefix, entry.name);
+            if (entry.isDirectory())
+                walk(join(dir, entry.name), rel);
+            else if (entry.isFile() && entry.name.endsWith('.sh'))
+                handlers.push(rel);
+        }
+    };
+    walk(CORE_TEMPLATE);
+    const refreshed = [];
+    for (const root of roots)
+        for (const rel of handlers) {
+            const source = join(CORE_TEMPLATE, rel);
+            const dest = join(root, rel);
+            let current = null;
+            try {
+                current = readFileSync(dest);
+            }
+            catch { }
+            if (current?.equals(readFileSync(source)))
+                continue;
+            mkdirSync(dirname(dest), { recursive: true });
+            const temp = `${dest}.spexcode-${process.pid}`;
+            try {
+                copyFileSync(source, temp);
+                chmodSync(temp, 0o755);
+                renameSync(temp, dest);
+                refreshed.push(relative(proj, dest));
+            }
+            finally {
+                rmSync(temp, { force: true });
+            }
+        }
+    if (refreshed.length)
+        console.log(`✓ refreshed core plugin handlers (${refreshed.join(', ')})`);
+    return refreshed;
+}
 // the manifest + content-hash marker + plugin-folder ledger land in the materialized TREE's own slot of the
 // GLOBAL per-project store (layout.treeSlotDir — trees/<enc-worktree>), NOT the worktree and NOT one shared
 // per-project file: each is a pure function of ONE tree's .plugins, and the old single slot let the last-
@@ -321,6 +373,7 @@ export function dematerialize(proj = process.cwd(), arts = { skills: [], agents:
 // the whole pay-per-change materialize. proj defaults to cwd. Its receipt is populated at each successful
 // write so callers report the actual selected footprint instead of maintaining a second artifact inventory.
 export function materialize(proj = process.cwd()) {
+    refreshCorePluginHandlers(proj);
     const rt = treeSlotDir(proj); // this tree's slot in the global store, not the worktree
     mkdirSync(rt, { recursive: true });
     const planted = [];

package/dist/session-transcript.d.ts

@@ -30,6 +30,7 @@ export declare function readSessionTranscript(c: Context): Promise<(Response & i
             readonly output?: string | undefined;
             readonly outputLines: number;
             readonly outputBytes: number;
+            readonly outcome?: "failed" | "rejected" | undefined;
         }[] | undefined;
     }[];
     readonly truncated: boolean;

package/dist/sessions.js

@@ -1,4 +1,5 @@
 import { execFile, execFileSync, spawn } from 'node:child_process';
+import { createConnection } from 'node:net';
 import { promisify } from 'node:util';
 import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync, writeFileSync, existsSync, renameSync, linkSync, mkdirSync, rmSync, readdirSync, realpathSync, statSync, unlinkSync } from 'node:fs';
@@ -15,6 +16,7 @@ import { readSessionFiles } from './session-files.js';
 import { readSessionWebs } from './session-web.js';
 import { acquireFreshSessionApplicationForCreate, configuredSessionApplicationIfCutover, initializeFreshSessionApplication, releaseFreshSessionApplicationForCreate, sessionApplicationCutoverState, setSessionApplicationCommitWake } from './session-application.js';
 import { jsonMigrationFencePath } from '@spexcode/session-application';
+import { decodeEventJson } from '@spexcode/session-events';
 import { withDeliveryLocks } from './delivery-lock.js';
 import { withSessionRecordLock, withSessionRecordLockSync as coreWithSessionRecordLockSync } from './session-record-lock.js';
 import { stripRefSigil } from './mentions.js';
@@ -1100,7 +1102,7 @@ export function toSession(rec, status, lv, 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, closedAt: rec.archived ? rec.closedAt : null, 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] } : {}) };
+    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.closedAt ? 'archived' : rec.status, proposal: rec.closedAt ? null : rec.proposal, merges: rec.merges, note: rec.note, status, liveness: lv, archived: rec.archived || !!rec.closedAt, closedAt: rec.closedAt, 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.
@@ -1174,7 +1176,7 @@ export async function listArchivedSessionIndex(probe) {
         if (entry.kind !== 'ok')
             continue;
         const rec = fromRaw(entry.raw);
-        if (!rec.governed || !rec.archived)
+        if (!rec.governed || (!rec.archived && !rec.closedAt))
             continue;
         const parts = {
             id: rec.session, name: rec.name, node: rec.node, title: rec.title, branch: rec.branch,
@@ -1303,7 +1305,11 @@ export async function listSessions(includeArchived = false) {
         // 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 = projectedRecord.archived && !changedDuringCensus.has(id) && hasValidColdProof(projectedRecord) && physical === 'offline' && (!residentRequired || resident?.healthy === true);
-        const projected = projectedRecord.archived && !cleanCold ? { ...projectedRecord, archived: false, stopped: false } : projectedRecord;
+        // A published close is terminal public history even if a later census cannot prove the old adapter fully
+        // unloaded. Only legacy archived rows without closedAt may be exposed as a working hazard for repair.
+        const projected = projectedRecord.archived && !cleanCold && !projectedRecord.closedAt
+            ? { ...projectedRecord, archived: false, stopped: false }
+            : projectedRecord;
         const projectedLv = projected === projectedRecord
             ? sessionHarness.runtimeOwnership === 'adapter'
                 ? adapterResidentLiveness(projectedRecord, resident)
@@ -1704,11 +1710,45 @@ let draining = false; // re-entrancy guard: only one drain pass runs at a time (
 // A native receipt is bound before the readiness fence validates it. Suppress only that immediate wake so
 // queued prompts cannot drain during the candidate window; the successful publication path drains normally.
 const readinessWakeSuppressed = new Set();
+// A readiness timeout is launch-phase evidence only until the session produces another durable event. The
+// first event at/after the readiness marker is the launch transition itself; anything after that proves the
+// worker progressed (including a declaration), so a late diagnostic is moot and must not replace its note.
+function hasLaterLaunchReadinessEvent(rec) {
+    const startedAt = rec.launchReadinessStartedAt;
+    if (!Number.isFinite(startedAt))
+        return false;
+    const application = configuredSessionApplicationIfCutover();
+    if (!application?.readState(rec.session))
+        return false;
+    const events = application.readEvents(rec.session);
+    const statusPayload = (event) => {
+        const payload = decodeEventJson(event.payload);
+        return payload && typeof payload === 'object' && !Array.isArray(payload) && 'status' in payload
+            ? payload : null;
+    };
+    const baseline = events.find((event) => {
+        if (event.occurredAtMs < Number(startedAt))
+            return false;
+        const payload = statusPayload(event);
+        return payload?.status === 'active';
+    });
+    return baseline ? events.some((event) => {
+        if (event.eventSeq <= baseline.eventSeq)
+            return false;
+        const payload = statusPayload(event);
+        if (!payload)
+            return false;
+        const note = payload.note;
+        return !(typeof note === 'string' && /^(?:queued launch readiness failed|launch readiness warning):/.test(note));
+    }) : false;
+}
 function noteQueuedLaunchFailureUnlocked(id, error, terminal = true, label, live = false) {
+    const rec = readRecord(id);
+    if (rec && (terminal || label === 'launch readiness warning') && hasLaterLaunchReadinessEvent(rec))
+        return;
     const reason = error instanceof Error ? error.message : String(error);
     const note = `${label ?? (terminal ? 'queued launch readiness failed' : 'launch readiness warning')}: ${reason}`;
     console.error(`spex: session ${id}: ${note}`);
-    const rec = readRecord(id);
     if (rec && !retirementReason(rec) && (rec.note !== note
         || (terminal && (rec.status !== 'error' || !rec.stopped || rec.launchReadinessStartedAt != null))
         || (!terminal && live && (rec.status === 'error' || rec.stopped)))) {
@@ -1788,12 +1828,16 @@ export function canonicalRecordProjection(rec, canonical) {
     // The application row is the only lifecycle fact after cutover. A JSON status is historical envelope data,
     // so it must not win merely because it says waiting/error/archived while the canonical row says otherwise.
     if (!canonical) {
-        return rec;
+        return ('closedAt' in rec && rec.closedAt
+            ? { ...rec, archived: true }
+            : rec);
     }
+    const closed = 'closedAt' in rec && !!rec.closedAt;
     return {
         ...rec,
-        status: canonical.status,
-        proposal: canonical.proposal,
+        archived: closed ? true : rec.archived,
+        status: (closed ? 'archived' : canonical.status),
+        proposal: (closed ? null : canonical.proposal),
         note: canonical.note,
         parent: canonical.parentSessionId,
     };
@@ -2488,9 +2532,53 @@ function isExplicitConnectionRefused(error) {
         return errors.length > 0 && errors.every(isExplicitConnectionRefused);
     return isExplicitConnectionRefused(error.cause);
 }
+async function establishBackendConnection(target) {
+    const parsed = new URL(target.url);
+    const port = Number(parsed.port) || (parsed.protocol === 'https:' ? 443 : 80);
+    return await new Promise((resolve, reject) => {
+        const socket = createConnection({ host: parsed.hostname, port });
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            fn();
+        };
+        const timer = setTimeout(() => {
+            // The event loop may have been blocked past the wall after the kernel completed the handshake. In that
+            // case Node has not emitted `connect` yet, but `connecting` is already false; acceptance still proves
+            // presence and must not be relabelled as an unavailable backend.
+            if (!socket.connecting || socket.readyState === 'open')
+                return finish(() => resolve(false));
+            finish(() => {
+                const error = new Error(`backend connection was not accepted at ${target.url} within 1500ms`);
+                error.name = 'BackendError';
+                Object.assign(error, { code: 'backend_availability_indeterminate' });
+                reject(error);
+            });
+        }, 1500);
+        timer.unref?.();
+        socket.once('connect', () => finish(() => resolve(false)));
+        socket.once('error', (error) => finish(() => {
+            if (isExplicitConnectionRefused(error))
+                return resolve(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 });
+            reject(failed);
+        }));
+    });
+}
 async function probeSessionCreateAuthority(target) {
+    // TCP acceptance establishes presence. The identity route can be delayed by a busy backend event loop,
+    // so it gets the ordinary create request deadline instead of a short availability deadline.
+    const refused = await establishBackendConnection(target);
+    if (refused)
+        return true;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 1500);
+    const timer = setTimeout(() => controller.abort(new Error('backend authority request timed out')), sessionCreateTimeoutMs() + 5_000);
     timer.unref?.();
     let response;
     try {
@@ -2498,11 +2586,9 @@ async function probeSessionCreateAuthority(target) {
     }
     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})`);
+        const failed = new Error(`backend authority read failed after connection 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 });
+        Object.assign(failed, { code: 'backend_authority_read_failed', cause: error });
         throw failed;
     }
     try {
@@ -2988,7 +3074,7 @@ async function prepareSession(prompt, parent, launcher, name, context) {
                 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 }));
+                    const added = await withGitAbortSignal(signal, () => gitTry(['-C', root, 'worktree', 'add', '--no-track', '-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 });
@@ -4711,12 +4797,25 @@ async function closeOwnedSessionUnlocked(id, wt, _source, unboundStopped = false
         throw new ResourceConflict(`refusing to finish close for ${id}: session record disappeared before publication`);
     writeRecord({
         ...latest,
+        proposal: null,
         archived: true,
         closedAt: latest.closedAt || new Date().toISOString(),
         stopped: true,
         coldProof: latest.coldProof || coldProofFor(latest),
         adapterRecovery: null,
     });
+    // The canonical lifecycle must settle at the same terminal boundary as the durable close fact. `archived`
+    // is an internal terminal marker; public projections render its closed record as `retired`.
+    const application = configuredSessionApplicationIfCutover();
+    if (application?.readState(id)) {
+        application.transitionSession(id, {
+            status: 'archived',
+            proposal: null,
+            note: latest.note,
+            parentSessionId: latest.parent,
+            recipientSessionIds: canonicalWatchRecipients(application, id, 'archived'),
+        });
+    }
     let slot = null;
     try {
         slot = existsSync(wt.path) ? treeSlotDir(wt.path) : null;
@@ -5289,6 +5388,8 @@ export async function drainSession(id) {
                         const removed = application.dequeuePendingMessage(id, msg.messageId);
                         if (!removed || removed.messageId !== msg.messageId)
                             throw new ResourceConflict(`canonical queue head changed while delivering ${id}`);
+                        if (!msg.senderSessionId)
+                            markHumanPromptActive(id);
                     }
                 });
                 return;
@@ -5315,6 +5416,8 @@ export async function drainSession(id) {
                 const removed = application.dequeueForRuntime(id, 'spex-governed', binding.bindingGeneration, msg.messageId);
                 if (!removed || removed.messageId !== msg.messageId)
                     throw new ResourceConflict(`canonical queue head changed while delivering ${id}`);
+                if (!msg.senderSessionId)
+                    markHumanPromptActive(id);
             }
         });
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.7.0-next.0",
+  "version": "0.7.0-next.10",
   "type": "module",
   "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
   "bin": {
@@ -35,12 +35,12 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/session-application": "0.7.0-next.0",
-    "@spexcode/session-selflaunch": "0.7.0-next.0",
-    "@spexcode/spec-core": "0.7.0-next.0",
-    "@spexcode/spec-eval": "0.7.0-next.0",
-    "@spexcode/spec-forge": "0.7.0-next.0",
-    "@spexcode/transcript": "0.7.0-next.0",
+    "@spexcode/session-application": "0.7.0-next.10",
+    "@spexcode/session-selflaunch": "0.7.0-next.10",
+    "@spexcode/spec-core": "0.7.0-next.10",
+    "@spexcode/spec-eval": "0.7.0-next.10",
+    "@spexcode/spec-forge": "0.7.0-next.10",
+    "@spexcode/transcript": "0.7.0-next.10",
     "smol-toml": "^1.8.0"
   },
   "devDependencies": {

package/templates/spec/project/.plugins/skills/merge/spec.md

@@ -19,9 +19,15 @@ Land the current SpexCode session's branch; do not dispatch another merge reques
 3. Immediately before landing, verify
    `git merge-base --is-ancestor <source-head> <session-head>`. If it fails, sync again. A clean textual merge
    is not product proof.
-4. In the source-of-truth checkout, make one `--no-ff` merge of the already-synced session tip. Do not resolve
-   conflicts there. If unrelated dirty work prevents the merge, preserve it byte-for-byte and report the exact
-   overlap rather than forcing, resetting, or committing it.
+4. Land with one `--no-ff` merge of the already-synced session tip, without touching the source checkout's
+   dirty work. Git refuses a merge over a dirty index, so do NOT clear it: add a temporary detached worktree of
+   the source head (`git worktree add --detach <tmp> <source-branch>`), make the `--no-ff` merge there, then
+   fast-forward the source checkout to that commit (`git merge --ff-only <tmp-head>`) and remove the temporary
+   worktree. A fast-forward never rewrites a path the merge did not change, so user-owned dirty files keep
+   their bytes and their staged/unstaged state. Never `git restore`, `reset`, `checkout`, `stash`, or overwrite
+   a user-owned path — an unstaged edit has no blob anywhere, so "save and put back" loses it, and a copy of the
+   same path from another worktree is a different version, not a restoration. Do not resolve conflicts in the
+   source checkout; if the merge genuinely overlaps a user-owned path, stop and report the exact overlap.
 5. Verify the source checkout has no `MERGE_HEAD`, the session tip is its ancestor, unrelated dirty
    fingerprints are unchanged, and the post-merge gates pass. Push the source-of-truth branch only after
    those checks.