spexcode 0.6.5 → 0.6.6

package/node_modules/@spexcode/session-core/dist/session-timeline.d.ts

@@ -0,0 +1,46 @@
+import type { SessionLifecycle, SessionProposal } from '@spexcode/spec-core';
+export type TimelineEvent = {
+    ts: string;
+    kind: 'status';
+    status: SessionLifecycle;
+    proposal: SessionProposal | null;
+    note: string | null;
+    display?: string;
+} | {
+    ts: string;
+    kind: 'sent';
+    mid: string;
+    text: string;
+    from: string | null;
+    replyVia?: 'note';
+};
+export type SentDispatchReceipt = {
+    operation: string;
+    requestDigest: string;
+    payloadHash: string;
+    delivery?: {
+        text: string;
+        from: string | null;
+    };
+};
+export declare function recordStatus(id: string, status: SessionLifecycle, proposal: SessionProposal | null, note: string | null): void;
+export declare function appendSent(id: string, text: string, from: string | null, replyVia?: 'note', dispatchReceipt?: SentDispatchReceipt): {
+    mid: string;
+};
+export type SentDispatchState = {
+    mid: string;
+    payloadHash: string;
+    delivery: SentDispatchReceipt['delivery'] | null;
+    delivered: boolean;
+};
+export declare function sentDispatchReceipt(id: string, operation: SentDispatchReceipt['operation'], requestDigest: string): SentDispatchState | null;
+export declare function settleSentDispatch(id: string, mid: string): void;
+export declare function timelineEvents(id: string): TimelineEvent[];
+export declare function timelineStamp(id: string): string | null;
+export declare function lastHumanSendVia(id: string): 'note' | null;
+export type SessionTurn = Readonly<{
+    token: string;
+    acceptedAt: string;
+}>;
+export declare function currentHumanTurn(id: string): SessionTurn | null;
+export declare function timelineTail(id: string, limit?: number): TimelineEvent[];

package/node_modules/@spexcode/session-core/dist/session-timeline.js

@@ -0,0 +1,216 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, appendFileSync, mkdirSync, statSync, readdirSync, openSync, closeSync, readSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { sessionStoreDir, sessionArtifactPath } from '@spexcode/spec-core';
+const timelinePath = (id) => sessionArtifactPath(id, 'timeline.ndjson');
+const segmentsDir = (id) => sessionArtifactPath(id, 'timeline');
+const SEGMENT = /^(\d+)\.ndjson$/;
+const SEGMENT_NAME_WIDTH = 12;
+const TAIL_BLOCK_BYTES = 64 * 1024;
+// One logical timeline is legacy timeline.ndjson followed by immutable numbered segments. The directory
+// listing is its only index: numbering is append order, so there is no mutable manifest to repair.
+function segmentFiles(id) {
+    try {
+        const dir = segmentsDir(id);
+        const names = readdirSync(dir).filter((name) => SEGMENT.test(name)).sort((a, b) => {
+            const an = BigInt(SEGMENT.exec(a)[1]), bn = BigInt(SEGMENT.exec(b)[1]);
+            return an < bn ? -1 : an > bn ? 1 : 0;
+        });
+        return names.map((name) => join(dir, name));
+    }
+    catch { /* no numbered segments yet */ }
+    return [];
+}
+function timelineFiles(id) {
+    const files = [];
+    const legacy = timelinePath(id);
+    if (existsSync(legacy))
+        files.push(legacy);
+    files.push(...segmentFiles(id));
+    return files;
+}
+const segmentLimit = () => {
+    const configured = Number(process.env.SPEXCODE_TIMELINE_SEGMENT_BYTES);
+    return Number.isFinite(configured) ? Math.max(1024, Math.floor(configured)) : 4 * 1024 * 1024;
+};
+function activeSegment(id, bytes) {
+    const dir = segmentsDir(id);
+    mkdirSync(dir, { recursive: true });
+    const segments = segmentFiles(id);
+    const current = segments.at(-1);
+    if (!current)
+        return join(dir, `${String(1).padStart(SEGMENT_NAME_WIDTH, '0')}.ndjson`);
+    try {
+        if (statSync(current).size === 0 || statSync(current).size + bytes <= segmentLimit())
+            return current;
+    }
+    catch { /* a vanished active segment is recreated under its next number */ }
+    const n = BigInt(SEGMENT.exec(basename(current))[1]) + 1n;
+    return join(dir, `${String(n).padStart(SEGMENT_NAME_WIDTH, '0')}.ndjson`);
+}
+function append(id, ev) {
+    mkdirSync(sessionStoreDir(id), { recursive: true });
+    const line = JSON.stringify(ev) + '\n';
+    appendFileSync(activeSegment(id, Buffer.byteLength(line)), line);
+}
+function parseLines(lines) {
+    return lines.map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    }).filter((e) => e != null && (e.kind === 'status' || e.kind === 'sent' || e.kind === 'dispatch-settled'));
+}
+function tailPublicEvents(path, limit) {
+    let fd = null;
+    try {
+        const size = statSync(path).size;
+        fd = openSync(path, 'r');
+        let start = size;
+        let text = '';
+        while (start > 0) {
+            const next = Math.max(0, start - TAIL_BLOCK_BYTES);
+            const buf = Buffer.alloc(start - next);
+            readSync(fd, buf, 0, buf.length, next);
+            text = buf.toString('utf8') + text;
+            const publicCount = parseLines(text.split('\n').filter(Boolean)).filter((event) => event.kind !== 'dispatch-settled').length;
+            if (publicCount >= limit || next === 0)
+                break;
+            start = next;
+        }
+        return parseLines(text.split('\n').filter(Boolean))
+            .filter((event) => event.kind !== 'dispatch-settled')
+            .slice(-limit);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+// Record a lifecycle value that has already landed in session.json. TypeScript state writers call this
+// synchronously before returning, so a later write cannot erase an intermediate declaration note from the
+// conversation. Best-effort: history is an accessory to the state machine, and failing to write it must never
+// break the transition that already happened.
+export function recordStatus(id, status, proposal, note) {
+    try {
+        append(id, { ts: new Date().toISOString(), kind: 'status', status, proposal, note });
+    }
+    catch { /* the record already moved; the history line is the only loss */ }
+}
+// The DELIVERY ([[dispatch]]): appending this line IS the send, so unlike a status line it must fail LOUD —
+// the caller reports the throw rather than a false success. `text` is the message BEFORE any mechanism insert
+// (hints are transport, not conversation); `replyVia` is the effective channel the prompt seam chose. Returns
+// the new line's `mid`, which a best-effort poke carries.
+export function appendSent(id, text, from, replyVia, dispatchReceipt) {
+    const mid = randomUUID();
+    append(id, { ts: new Date().toISOString(), kind: 'sent', mid, text, from, ...(replyVia ? { replyVia } : {}), ...(dispatchReceipt ? { dispatchReceipt } : {}) });
+    return { mid };
+}
+export function sentDispatchReceipt(id, operation, requestDigest) {
+    let found = null;
+    const settled = new Set();
+    for (const path of timelineFiles(id)) {
+        for (const event of parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean))) {
+            if (event.kind === 'sent' && !found && event.dispatchReceipt?.operation === operation && event.dispatchReceipt.requestDigest === requestDigest) {
+                found = { mid: event.mid, payloadHash: event.dispatchReceipt.payloadHash, delivery: event.dispatchReceipt.delivery ?? null };
+            }
+            else if (event.kind === 'dispatch-settled' && event.operation === operation && event.requestDigest === requestDigest) {
+                settled.add(event.mid);
+            }
+        }
+    }
+    return found ? { ...found, delivered: settled.has(found.mid) } : null;
+}
+export function settleSentDispatch(id, mid) {
+    let receipt = null;
+    let settled = false;
+    for (const path of timelineFiles(id)) {
+        for (const event of parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean))) {
+            if (event.kind === 'sent' && event.mid === mid && event.dispatchReceipt?.delivery)
+                receipt = event.dispatchReceipt;
+            if (event.kind === 'dispatch-settled' && event.mid === mid)
+                settled = true;
+        }
+    }
+    if (!receipt || settled)
+        return;
+    append(id, { ts: new Date().toISOString(), kind: 'dispatch-settled', operation: receipt.operation, requestDigest: receipt.requestDigest, mid });
+}
+// The unowned read: any process may take it with nothing but filesystem access, and taking it perturbs
+// nothing. Index = event position, which is what a cursor names ([[session-cursors]]).
+export function timelineEvents(id) {
+    try {
+        return timelineFiles(id).flatMap((path) => parseLines(readFileSync(path, 'utf8').split('\n').filter(Boolean)))
+            .flatMap((stored) => {
+            if (stored.kind === 'dispatch-settled')
+                return [];
+            if (stored.kind === 'status')
+                return [stored];
+            const { dispatchReceipt: _receipt, ...event } = stored;
+            return [event];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+// the same L0 read taken as CHEAPLY as it can be: a follower ([[session-follow]]) ticks over many logs, so it
+// stats first and parses only what grew. null = no log yet (a session that has authored nothing).
+export function timelineStamp(id) {
+    try {
+        const path = timelineFiles(id).at(-1);
+        if (!path)
+            return null;
+        const s = statSync(path);
+        return `${path}:${s.size}:${s.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+}
+// the channel of the LAST HUMAN send (from == null): 'note' when the note-reply hint rode along, else null.
+// This is what makes the reply-channel hints SYMMETRIC ([[session-timeline]]): a human send with no note flag
+// arriving after a note-send is the "back at a terminal" transition, and the delivery gets the counter-insert.
+// Derived from the durable log — no new state, and it survives a server restart. Agent senders (`from` set)
+// say nothing about where the HUMAN is reading, so they neither set nor clear it.
+export function lastHumanSendVia(id) {
+    const evs = timelineEvents(id);
+    for (let i = evs.length - 1; i >= 0; i--) {
+        const e = evs[i];
+        if (e.kind === 'sent' && e.from == null)
+            return e.replyVia === 'note' ? 'note' : null;
+    }
+    return null;
+}
+export function currentHumanTurn(id) {
+    const evs = timelineEvents(id);
+    for (let i = evs.length - 1; i >= 0; i--) {
+        const e = evs[i];
+        if (e.kind === 'sent' && e.from == null)
+            return { token: e.mid, acceptedAt: e.ts };
+    }
+    return null;
+}
+// Durable tail read with no board/governance policy. A runtime that owns a compatible session directory can
+// consume the same protocol; product surfaces decide separately whether that id is visible to them.
+export function timelineTail(id, limit = 500) {
+    const wanted = Math.max(1, limit);
+    const tail = [];
+    for (const path of timelineFiles(id).reverse()) {
+        const remaining = wanted - tail.length;
+        if (remaining <= 0)
+            break;
+        tail.unshift(...tailPublicEvents(path, remaining));
+    }
+    return tail.map((e) => {
+        if (e.kind === 'status')
+            return e;
+        const { dispatchReceipt: _receipt, ...event } = e;
+        return event;
+    });
+}

package/node_modules/@spexcode/session-core/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@spexcode/session-core",
+  "version": "0.6.6",
+  "type": "module",
+  "description": "SpexCode's durable file-based session communication protocol.",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./internal": "./dist/internal.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts && node --test scripts/public-boundary.test.mjs"
+  },
+  "dependencies": {
+    "@spexcode/spec-core": "0.6.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/spec-cli/bin/spex.mjs

@@ -16,7 +16,7 @@ const workspace = join(pkg, '..')
 // carry unresolved conflict markers, so hooks keep the retryable exit-75 contract during a merge.
 const sourceRoot = join(pkg, 'src')
 if (existsSync(sourceRoot)) {
-  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
+  const srcRoots = [sourceRoot, join(pkg, '..', 'packages', 'spec-core', 'src'), join(pkg, '..', 'packages', 'session-core', 'src'), join(pkg, '..', 'spec-eval', 'src'), join(pkg, '..', 'spec-forge', 'src')]
   const conflicted = srcRoots.flatMap((root) => {
     if (!existsSync(root)) return []
     return readdirSync(root, { recursive: true })
@@ -39,6 +39,7 @@ if (existsSync(sourceRoot)) {
   const runtimeEntries = [
     cli,
     join(workspace, 'packages', 'spec-core', 'dist', 'index.js'),
+    join(workspace, 'packages', 'session-core', 'dist', 'index.js'),
     join(workspace, 'spec-eval', 'dist', 'index.js'),
     join(workspace, 'spec-forge', 'dist', 'index.js'),
   ]

package/node_modules/@spexcode/spec-cli/dist/claude-headless.d.ts

@@ -5,7 +5,10 @@ type ClaudeHeadlessDeliveryRecord = HarnessDeliveryRecord & {
 export declare const claudeHeadlessSock: (id: string) => string;
 export declare function claudeHeadlessLaunchCommand(id: string, runtimeDir: string, claudeCmd: string): string;
 export declare const deliverViaClaudeHeadless: (rec: ClaudeHeadlessDeliveryRecord, text: string) => Promise<DispatchResult>;
-export declare const interruptClaudeHeadless: (rec: HarnessDeliveryRecord) => Promise<DispatchResult>;
+export declare const interruptClaudeHeadless: (rec: HarnessDeliveryRecord) => Promise<{
+    ok: boolean;
+}>;
+export declare function claudeHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
 export declare class ClaudeHeadlessController {
     private readonly id;
     private readonly claudeCmd;

package/node_modules/@spexcode/spec-cli/dist/claude-headless.js

@@ -28,10 +28,19 @@ export const deliverViaClaudeHeadless = (rec, text) => controlRequest(claudeHead
     name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
     rejected: 'claude-headless control rejected the request',
 });
-export const interruptClaudeHeadless = (rec) => controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
-    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
-    rejected: 'claude-headless control rejected the request',
-});
+export const interruptClaudeHeadless = (rec) => rec.stopped || rec.archived
+    ? Promise.resolve({ ok: true })
+    : controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
+        name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+        rejected: 'claude-headless control rejected the request',
+    });
+export async function claudeHeadlessColdRuntime(rec) {
+    const { listenerAt } = await import('./harness.js');
+    const probe = await listenerAt(claudeHeadlessSock(rec.session));
+    return probe === 'dead'
+        ? { ok: true }
+        : { ok: false, error: `claude-headless controller is still ${probe === 'live' ? 'live' : 'unproven'}` };
+}
 export class ClaudeHeadlessController {
     id;
     claudeCmd;

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

@@ -6,6 +6,34 @@ import { installEvalHost } from './eval-host.js';
 installEvalHost();
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 const cmd = process.argv[2];
+function levenshtein(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        let previous = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const current = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+            previous = current;
+        }
+    }
+    return row[b.length];
+}
+function nearestPublicCommand(input, commands) {
+    const query = input.toLowerCase();
+    if (!/^[a-z0-9-]+$/.test(query))
+        return null;
+    const similarity = (a, b) => 1 - levenshtein(a, b) / Math.max(a.length, b.length);
+    const words = (text) => text.toLowerCase().match(/[a-z0-9-]+/g) ?? [];
+    let best = null;
+    for (const command of commands) {
+        const [headline = '', ...detail] = command.text.split('\n');
+        const score = Math.max(similarity(query, command.name), ...words(headline).map((word) => similarity(query, word)), ...words(detail.join('\n')).map((word) => similarity(query, word) * 0.8));
+        if (!best || score > best.score)
+            best = { name: command.name, score };
+    }
+    return best && best.score >= 0.8 ? best.name : null;
+}
 if (cmd === '--version' || cmd === '-v') {
     const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
     console.log(manifest.version);
@@ -31,14 +59,15 @@ async function assertDaemonDependencies(command) {
     process.exit(1);
 }
 // Registered before any await so a fatal top-level error lands here. Errors we OWN — BackendError, the
-// loud malformed-config ConfigError, the --api/--port UsageError, the write-guard GuardError — are
+// loud malformed-config ConfigError, the --api/--port UsageError, the write-guard GuardError, and a
+// GitWorkspaceError that teaches a fresh directory how to continue — are
 // matched BY NAME (to avoid importing them) and rendered as a one-line `spex: <message>` (a user's
 // config typo or a refused cross-project write must read as their situation, not a SpexCode stack dump);
 // anything else prints in full so a real bug keeps its trace. A synchronous throw inside an awaited call
 // (loadConfig on a malformed spexcode.json) surfaces as uncaughtException, not unhandledRejection, so BOTH
 // paths route through the same printer.
 function fatal(e) {
-    if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError', 'DashboardAssetError'].includes(e.name))
+    if (e instanceof Error && ['BackendError', 'ConfigError', 'UsageError', 'GuardError', 'DashboardAssetError', 'GitWorkspaceError'].includes(e.name))
         console.error(`spex: ${e.message}`);
     else
         console.error(e);
@@ -68,6 +97,13 @@ function flushExit(code = 0) {
 const has = (name) => process.argv.includes(`--${name}`);
 // bare positionals after argv index `from`, skipping flags and their values (selectors for ls/watch).
 const VALUE_FLAGS = new Set(['--status', '--as', '--interval', '--propose', '--note', '--node', '--prompt', '--prompt-file', '--timeout', '--reason', '--out', '--content-dir', '--password', '--tls-cert', '--tls-key', '--harness', '--launcher', '--harness-session', '--port', '--api', '--api-port', '--host', '--preset', '--limit', '--session', '--depth', '--focus', '--keys', '--ssh', '--allow-stop', '--allow-resume', '--ttl-ms', '--wait-ms', '--adapter', '--thread', '--tmux', '--worktree', '--branch', '--to', '--name', '--base', '--path', '--owner', '--details', '--variant', '--cli', '--count', '--ids']);
+const EXPLICIT_BACKEND_ROUTE_FLAGS = ['api', 'port', 'password', 'insecure'];
+const EXPLICIT_BACKEND_VALUE_FLAGS = EXPLICIT_BACKEND_ROUTE_FLAGS
+    .filter((name) => VALUE_FLAGS.has(`--${name}`))
+    .map((name) => `--${name}`);
+const EXPLICIT_BACKEND_BARE_FLAGS = EXPLICIT_BACKEND_ROUTE_FLAGS
+    .filter((name) => !VALUE_FLAGS.has(`--${name}`))
+    .map((name) => `--${name}`);
 function positionals(from) {
     const out = [];
     for (let i = from; i < process.argv.length; i++) {
@@ -81,7 +117,7 @@ function positionals(from) {
     }
     return out;
 }
-function rejectUnknownFlags(command, from, allowed, attached = []) {
+function rejectFlags(command, from, allowed, attached = []) {
     const known = new Set(allowed.map((name) => `--${name}`));
     for (let i = from; i < process.argv.length; i++) {
         const token = process.argv[i];
@@ -97,6 +133,12 @@ function rejectUnknownFlags(command, from, allowed, attached = []) {
             i++;
     }
 }
+function rejectUnknownFlags(command, from, allowed, attached = []) {
+    rejectFlags(command, from, allowed, attached);
+}
+function rejectUnknownBackendFlags(command, from, allowed, attached = []) {
+    rejectFlags(command, from, [...allowed, ...EXPLICIT_BACKEND_ROUTE_FLAGS], attached);
+}
 // `--children` deliberately has an optional value only in its attached form. A separated following token
 // remains a normal ls selector, so the long-standing `ls --children <child-SEL>` grammar keeps its meaning.
 function childrenScopeOption() {
@@ -125,8 +167,8 @@ function sessionSendUsage(detail, keys = false) {
     process.exit(2);
 }
 function parseSessionSendArgs(args) {
-    const valueFlags = new Set(['--api', '--port', '--keys', '--password', '--ssh']);
-    const bareFlags = new Set(['--insecure']);
+    const valueFlags = new Set([...EXPLICIT_BACKEND_VALUE_FLAGS, '--keys', '--ssh']);
+    const bareFlags = new Set(EXPLICIT_BACKEND_BARE_FLAGS);
     const values = new Map();
     const positionals = [];
     let endOfOptions = false;
@@ -210,8 +252,8 @@ function sessionTargetUsage(verb, detail) {
 }
 function parseSessionTargetArgs(verb, args) {
     const values = new Map();
-    const valueFlags = new Set(['--api', '--port', '--password', '--ssh']);
-    const bareFlags = new Set(verb === 'show' ? ['--capture', '--json', '--insecure'] : ['--insecure']);
+    const valueFlags = new Set([...EXPLICIT_BACKEND_VALUE_FLAGS, '--ssh']);
+    const bareFlags = new Set([...EXPLICIT_BACKEND_BARE_FLAGS, ...(verb === 'show' ? ['--capture', '--json'] : [])]);
     const positionals = [];
     for (let i = 0; i < args.length; i++) {
         const token = args[i];
@@ -253,6 +295,7 @@ const SIGNPOSTS = {
     blob: 'spex evidence put|get',
     issues: 'spex issue — ls (was: bare issues) · show · open · reply · close · promote; on|off|status → the `issues.enabled` key in spexcode.json; `issues nudge` → spex internal nudge',
     forge: 'spex issue links [--pending] [--store <host>]  (--host is now --store)',
+    runtime: 'spex doctor repair app-server',
     new: 'spex session new',
     ls: 'spex session ls',
     watch: 'spex session watch',
@@ -395,7 +438,7 @@ async function stateKit() {
 // reach here — the signpost table above already exited.)
 if (cmd && cmd !== 'help' && (has('help') || process.argv.includes('-h'))) {
     const { commandHelp, overviewHelp } = await import('./help.js');
-    console.log(commandHelp(cmd, cmd === 'session' ? process.argv[3] : undefined) ?? overviewHelp());
+    console.log(commandHelp(cmd, cmd === 'session' || cmd === 'doctor' ? process.argv[3] : undefined) ?? overviewHelp());
     process.exit(0);
 }
 if (cmd === 'serve') {
@@ -955,7 +998,7 @@ else if (cmd === 'session') {
         }
         const newPositionals = positionals(4);
         const peerAnchor = parseSessionPeerAnchor('new', newPositionals);
-        rejectUnknownFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'name', 'base', 'api', 'port', 'ssh']);
+        rejectUnknownBackendFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'name', 'base', 'ssh']);
         if (peerAnchor && newPositionals.length > 2)
             sessionPeerAnchorUsage('new', '--ssh accepts one full-id anchor and one inline prompt at most');
         const { createSession, ownSessionId, withPeerSenderHint } = await import('./sessions.js');
@@ -1023,7 +1066,7 @@ else if (cmd === 'session') {
         // The backend's default projection excludes cold archives. --all and an explicit selector request the
         // history projection so an operator can still inspect or unarchive one deliberately.
         const selectors = positionals(4);
-        rejectUnknownFlags('spex session ls', 4, ['status', 'all', 'json', 'api', 'port', 'ssh', 'children'], ['children']);
+        rejectUnknownBackendFlags('spex session ls', 4, ['status', 'all', 'json', 'ssh', 'children'], ['children']);
         const peerAnchor = parseSessionPeerAnchor('ls', selectors);
         const children = childrenScopeOption();
         if (peerAnchor && selectors.length !== 1)
@@ -1089,7 +1132,7 @@ else if (cmd === 'session') {
         }
     }
     else if (sub === 'resources') {
-        rejectUnknownFlags('spex session resources', 4, ['json', 'api', 'port']);
+        rejectUnknownBackendFlags('spex session resources', 4, ['json']);
         const { clientResources } = await import('./client.js');
         const report = await clientResources();
         if (has('json'))
@@ -1368,7 +1411,7 @@ else if (cmd === 'session') {
             console.log(`closed ${full}`);
         }
         else if (sub === 'quarantine') {
-            rejectUnknownFlags('spex session quarantine', 4, ['adapter', 'thread', 'tmux', 'worktree', 'branch', 'restore', 'api', 'port']);
+            rejectUnknownBackendFlags('spex session quarantine', 4, ['adapter', 'thread', 'tmux', 'worktree', 'branch', 'restore']);
             if (!id) {
                 console.error('usage: spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <session-id> --worktree <absent-path> --branch <absent-branch> (--thread is adapter-native; omit it for Claude)');
                 process.exit(2);
@@ -1390,7 +1433,7 @@ else if (cmd === 'session') {
             }
         }
         else if (sub === 'reparent') {
-            rejectUnknownFlags('spex session reparent', 4, ['to', 'api', 'port']);
+            rejectUnknownBackendFlags('spex session reparent', 4, ['to']);
             const children = positionals(4);
             const to = flag('to');
             if (!children.length || !to) {
@@ -1425,8 +1468,8 @@ else if (cmd === 'session') {
                 console.error(`spex session send --keys: nothing delivered to ${full} (offline, unknown session, or no valid key token)`);
                 process.exit(1);
             }
-            // The backend decides send success at the timeline append. A dead adapter poke only delays context
-            // injection, while a refused record write prints the reason and exits non-zero.
+            // A send is accepted at its timeline append, except a proven-unreachable transport attached to a live
+            // registered agent: that stranded combination refuses before it can add unclaimable queue debt.
             // BIDIRECTIONAL: stamp the SENDER (this send process's OWN session — the only process that knows it, via
             // ownSessionId from CLAUDE_CODE_SESSION_ID) + a one-line reply hint into the delivered
             // message, so the recipient can reply over the SAME send. The sender's row (hence its display label) is
@@ -1455,8 +1498,12 @@ else if (cmd === 'session') {
             const r = sendArgs.sshAddress
                 ? await c.clientSendThroughPeer(sendArgs.sshAddress, full, text, from)
                 : await c.clientSend(full, text, from);
-            console.log(r.ok ? 'sent' : `dispatch failed: ${r.error}`);
-            process.exit(r.ok ? 0 : 1);
+            if (r.ok) {
+                console.log('sent');
+                process.exit(0);
+            }
+            console.error(`dispatch failed: ${r.error}`);
+            process.exit(1);
         }
         else if (sub === 'show') {
             // the session RECORD as one per-id read (status · node · branch · launcher · the full originating
@@ -1637,11 +1684,11 @@ else if (cmd === 'internal') {
     }
     else if (sub === 'codex-launch') {
         // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
-        // (codex loads that worktree's config/hooks/AGENTS.md), store the new id on the governed record (keyed by
-        // SPEXCODE_SESSION_ID), fire the launch prompt as the FIRST turn — materializing the rollout — and print the
-        // thread id. The launch script then `resume`s it in the visible TUI.
+        // (codex loads that worktree's config/hooks/AGENTS.md), fire the launch prompt as the FIRST turn —
+        // materializing the rollout — then stage the id + exact-payload proof for the session lifecycle owner and
+        // print the thread id. The launch script then `resume`s it in the visible TUI.
         const { codexStartThread, codexTurn, waitForCodexRollout, codexBinary, codexSupportsBypassHookTrust, codexLauncherThreadPolicy } = await import('./harness.js');
-        const { markHarnessSessionId } = await import('./sessions.js');
+        const { stageHarnessLaunchProof } = await import('./sessions.js');
         const sock = process.argv[4], cwd = process.argv[5];
         const prompt = process.argv.slice(6).join(' ');
         if (!sock || !cwd) {
@@ -1680,7 +1727,7 @@ else if (cmd === 'internal') {
         }
         const sid = process.env.SPEXCODE_SESSION_ID;
         if (sid)
-            markHarnessSessionId(sid, r.threadId);
+            stageHarnessLaunchProof(sid, r.threadId, prompt);
         console.log(r.threadId);
     }
     else if (sub === 'opencode-capture') {
@@ -1854,6 +1901,8 @@ else if (cmd === 'internal') {
     }
 }
 else {
-    console.error(`spex: unknown command '${cmd}' (try: spex help)`);
+    const { publicCommands } = await import('./help.js');
+    const suggestion = nearestPublicCommand(cmd, publicCommands());
+    console.error(`spex: unknown command '${cmd}'${suggestion ? ` — try: spex ${suggestion}` : ''} (try: spex help)`);
     process.exit(2);
 }

package/node_modules/@spexcode/spec-cli/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { type CockpitReview } from './cockpit.js';
+import type { SessionEvalRevision } from '@spexcode/spec-eval/sessioneval';
 import { type Session, type SessionClosure, type Resolved, type DispatchResult } from './sessions.js';
 export declare class BackendError extends Error {
     readonly status?: number | undefined;
@@ -48,7 +49,7 @@ type SessionEvalPage = {
     unknown: number;
     revision: string;
     summary?: any;
-    evalRevision?: any;
+    evalRevision?: SessionEvalRevision;
 };
 export type EvalsResult = {
     ok: true;

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

@@ -259,7 +259,7 @@ export async function clientCapture(id) {
     return { ok: false, status: r.status, reason: (await r.text().catch(() => '')) || `status ${r.status}` };
 }
 // POST /api/sessions/:id/input {kind:"text"} appends the prompt to the durable timeline, then best-effort
-// pokes the resolved adapter. HTTP failure means the append itself was refused.
+// pokes the resolved adapter. HTTP failure means the append was refused, including a proven stranded transport.
 export async function clientSend(id, text, from) {
     await guarded('session send');
     // `from` = the sending agent's own session id; the recipient's log records the sender ([[session-timeline]]) only when
@@ -331,30 +331,35 @@ export async function clientEvalExport(id) {
         return { ok: true, body: await r.text() };
     return { ok: false, status: r.status };
 }
+const evalRevisionKey = (revision) => JSON.stringify([revision.epoch, revision.generation, revision.content]);
+const formatEvalRevision = (revision) => revision ? `${revision.epoch}@${revision.generation} (${revision.content})` : 'missing';
 export async function clientEvals(id) {
     const q = encodeURIComponent(`is:eval scope:${id}`);
+    const drifts = [];
     for (let attempt = 0; attempt < 2; attempt++) {
         const items = [];
         let first = null;
-        let changed = false;
+        let snapshot = null;
         for (let page = 1;; page++) {
             const r = await apiFetch(`/api/evals?q=${q}&page=${page}`);
             if (!r.ok)
                 return { ok: false, status: r.status };
             const current = await r.json();
             first ??= current;
-            if (current.revision !== first.revision) {
-                changed = true;
+            if (current.pageCount > 1 && !current.evalRevision) {
+                throw new BackendError(`session eval page ${page}/${current.pageCount} for ${id} has no evalRevision; cannot assemble a consistent snapshot`);
+            }
+            snapshot ??= current.evalRevision ?? null;
+            if (current.evalRevision && snapshot && evalRevisionKey(current.evalRevision) !== evalRevisionKey(snapshot)) {
+                drifts.push(`attempt ${attempt + 1}: ${formatEvalRevision(snapshot)} -> ${formatEvalRevision(current.evalRevision)} at page ${page}`);
                 break;
             }
             items.push(...current.items);
             if (page >= current.pageCount)
-                break;
+                return { ok: true, model: { ...first, id, items } };
         }
-        if (!changed)
-            return { ok: true, model: { ...first, id, items } };
     }
-    throw new BackendError(`session eval pages changed while fetching ${id}; retry the command`);
+    throw new BackendError(`session eval snapshot changed during both fetch attempts for ${id} (${drifts.join('; ')}); retry the command`);
 }
 // POST /api/sessions/:id/merge — a human merge intent dispatched to the session's own agent.
 export async function clientMerge(id) {