@spexcode/spec-cli 0.7.0-next.3 → 0.7.0-next.5

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.js

@@ -18,7 +18,7 @@ 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, resolveCodexGenerationForSession } from './codex-runtime-generations.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 +220,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
@@ -2784,7 +2786,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 +2893,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 +3030,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 +3054,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 +3068,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 +3415,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 +3529,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

@@ -216,6 +216,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)
@@ -448,6 +471,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 +756,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/sessions.js

@@ -2538,12 +2538,19 @@ async function establishBackendConnection(target) {
             socket.destroy();
             fn();
         };
-        const timer = setTimeout(() => 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);
+        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(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.7.0-next.3",
+  "version": "0.7.0-next.5",
   "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.3",
-    "@spexcode/session-selflaunch": "0.7.0-next.3",
-    "@spexcode/spec-core": "0.7.0-next.3",
-    "@spexcode/spec-eval": "0.7.0-next.3",
-    "@spexcode/spec-forge": "0.7.0-next.3",
-    "@spexcode/transcript": "0.7.0-next.3",
+    "@spexcode/session-application": "0.7.0-next.5",
+    "@spexcode/session-selflaunch": "0.7.0-next.5",
+    "@spexcode/spec-core": "0.7.0-next.5",
+    "@spexcode/spec-eval": "0.7.0-next.5",
+    "@spexcode/spec-forge": "0.7.0-next.5",
+    "@spexcode/transcript": "0.7.0-next.5",
     "smol-toml": "^1.8.0"
   },
   "devDependencies": {