@spexcode/spec-cli 0.7.0-next.2 → 0.7.0-next.4

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

@@ -2784,7 +2784,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 +2891,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,
@@ -3400,6 +3403,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 +3517,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)
@@ -722,6 +745,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

@@ -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';
@@ -1704,11 +1706,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)))) {
@@ -2488,9 +2524,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 +2578,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 {

package/package.json

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