@spexcode/spec-cli 0.6.5 → 0.6.6

package/dist/help.d.ts

@@ -1,4 +1,9 @@
 export declare function commandHelp(name: string, verb?: string): string | null;
+export type PublicCommand = Readonly<{
+    name: string;
+    text: string;
+}>;
+export declare function publicCommands(): readonly PublicCommand[];
 export type HelpCatalogEntry = Readonly<{
     id: string;
     title: string;

package/dist/help.js

@@ -36,7 +36,7 @@ session to that node. --prompt-file <path>|- carries a long prompt without shell
 reproduced against a frozen commit; a base that names no commit is refused before anything is created.
 The successful receipt names what to read, monitor, and reply on. --ssh uses an existing gateway-to-gateway
 communication tunnel: its full id anchors the remote project, creation stays parentless and remote, and its
-prompt carries a runnable reply path over that same tunnel.`],
+prompt carries a runnable reply path over that same tunnel.`, ['project-bound']],
         ls: [['spex session ls [SEL…] [--children[=<PARENT-SEL>]] [--status a,b] [--all] [--json]', 'spex session ls --ssh <address> <FULL-SESSION-ID> [--children=<PARENT-SEL>] [--status a,b] [--json]'],
             'One-shot table of this project\'s live sessions, with each direct parent beside the row. --children scopes it to the caller\'s direct children; --children=<PARENT-SEL> names another parent without changing positional selector grammar. The heading summarizes the displayed scope by status. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it. An explicit id missing from the session list is diagnosed from terminal-close history: closed is a successful answer, while no live, archived, or closed history is a named miss. --ssh uses an existing gateway-to-gateway communication tunnel; its full id anchors one remote project rather than filtering the table, and archive projection stays unavailable on that peer route.', ['selector']],
         resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
@@ -96,8 +96,8 @@ const SESSION_HELP_GROUPS = [
     { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask', 'files', 'web'] },
     { title: 'Human escape hatch', verbs: ['attach'] },
 ];
-const SESSION_WRITE_NOTE = `Manager verbs that WRITE (send/interrupt/rename/resume/stop/close/merge/reparent) are PROJECT-BOUND: a backend serving
-another project's repo refuses loudly — name the target with --api <url> to drive it on purpose.`;
+const SESSION_WRITE_NOTE = `PROJECT-BOUND WRITES loudly refuse a backend serving another project's repo —
+name the target with --api <url> to drive it on purpose.`;
 function indent(text, spaces) {
     const prefix = ' '.repeat(spaces);
     return text.split('\n').map((line) => `${prefix}${line}`).join('\n');
@@ -127,7 +127,7 @@ function sessionVerbHelp(verb) {
 const ENTRIES = {
     // ── project verbs (implicit object = this project) ────────────────────────
     graph: {
-        line: 'graph                 the assembled view: bare = readable tree · --json = full payload · --public = static graph snapshot',
+        line: 'graph                 list the assembled spec nodes: bare = readable tree · --json = full payload · --public = static graph snapshot',
         body: `Usage: spex graph [--focus <id>] [--depth N] [--json] | spex graph --public [--out <path>] [--content-dir <path>]
 
 The normal assembled view is merged spec tree + worktree overlay + sessions. Bare it renders the
@@ -170,15 +170,22 @@ hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arriv
         see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
     },
     doctor: {
-        line: 'doctor                diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]',
+        line: 'doctor                diagnose project health; repair app-server only on explicit request  [--contract|--conflicts]',
         body: `Usage: spex doctor                spec-health findings + delivery report: preconditions · git-hook floor ·
                                   contract · hooks + handler existence · backend · footprint
        spex doctor --contract     print the composed surface:system text any agent here reads
        spex doctor --conflicts    detect double-delivery (loose artifacts beside the managed ones)
+       spex doctor repair app-server [--launcher <name>]
+                                  prove a fresh app-server, then switch new sessions to it
 
 Bare doctor is the opt-in, read-only health surface: it reports altitude and breadth findings without
 putting them in the lint gate, then audits workflow delivery. Run it directly or let the tidy workflow
-consume the same visible diagnosis.`,
+consume the same visible diagnosis.
+
+Use repair app-server only when new sessions cannot be accepted and existing work must stay connected.
+It proves a fresh app-server before routing future Codex sessions there. Existing sessions stay on the
+previous server while it drains; the command does not kill or move them. --launcher selects a configured
+Codex launcher, or the configured default is used when it is one.`,
         see: 'spex spec lint (deterministic graph/contract gate) · spex materialize (repair delivery artifacts)',
     },
     flat: {
@@ -495,6 +502,14 @@ export function commandHelp(name, verb) {
         if (exact)
             return `${exact}\n\nsee also: spex session (the complete drawer)\n\nmap: spex help · skills: spex guide`;
     }
+    if (name === 'doctor' && verb === 'repair') {
+        return `Usage: spex doctor repair app-server [--launcher <name>]
+
+Use this explicit repair when new sessions cannot be accepted but existing work must stay connected.
+It proves a fresh app-server, then routes future Codex sessions there. Existing sessions stay bound to
+the prior server while it drains; this command never kills or moves them. --launcher must name a
+configured Codex launcher.\n\nsee also: spex doctor (the complete command) · spex session resources\n\nmap: spex help · skills: spex guide`;
+    }
     const e = ENTRIES[name];
     if (!e)
         return null;
@@ -502,6 +517,11 @@ export function commandHelp(name, verb) {
     const header = oneLiner ? `spex ${name} — ${oneLiner}\n\n` : ''; // unlisted entries (internal, help) lead with their own Usage
     return `${header}${e.body}${e.see ? `\n\nsee also: ${e.see}` : ''}\n\nmap: spex help · skills: spex guide`;
 }
+export function publicCommands() {
+    return Object.entries(ENTRIES)
+        .filter(([name]) => name !== 'internal')
+        .map(([name, entry]) => ({ name, text: `${entry.line}\n${entry.body}` }));
+}
 // The guidance catalog consumes this registry projection rather than copying help prose or maintaining a
 // second command list. Each returned text is exactly what the corresponding public help probe prints.
 export function helpCatalogEntries() {

package/dist/index.js

@@ -751,8 +751,9 @@ app.get('/api/sessions/:id/socket', upgradeWebSocket((c) => {
 }));
 // ONE input route, `kind` the discriminator — the transport split is an implementation fact, not API surface.
 // kind:"text" (`spex session send`, the server-side merge dispatch) appends the prompt to the
-// target timeline, then best-effort pokes its adapter. A dead channel delays context injection but does not
-// change the successful append response; 502 means the record rejected the write.
+// target timeline, then best-effort pokes its adapter. A proven-unreachable transport joined to a live
+// registered agent is stranded and refuses before append; an unproven/dead-restartable channel stays queued.
+// 502 means the record rejected the write.
 // kind:"keys" is the LAST-RESORT raw face (`spex session send --keys`): an ORDERED BATCH of
 // nav-mode key tokens over tmux send-keys, delivered in array order so tap order survives
 // ([[nav-mode-key-ordering]]); unstable by nature — callers try a plain text send first. An unknown kind is a
@@ -878,7 +879,6 @@ superviseBridges(); // restore visible helpers after failure; their viewer subsc
 superviseQueue(); // launch queued sessions as slots free (catches agent-authored proposals/crashes the server never sees directly)
 superviseTurnFailures(); // reconcile adapter-owned native failure subscriptions across backend replacement
 superviseDelivery(); // hand over messages an earlier pass could not ([[delivery-queue]]): the retry half of dispatch
-console.log(`spec-cli serving .spec (from git) on http://localhost:${port}`);
 let graphWatchersClosed = false;
 const closeGraphWatchers = () => {
     if (graphWatchersClosed)

package/dist/listen.d.ts

@@ -3,5 +3,6 @@ export declare function listenOrExit(server: Server, port: number, opts: {
     host?: string;
     label: string;
     cleanup?: () => void;
-    onListen: () => void;
+    onListen?: () => void;
+    ready: string | string[];
 }): void;

package/dist/listen.js

@@ -1,11 +1,6 @@
-// @@@ listenOrExit - the shared "I own this port; if I cannot bind it, I have failed" contract for the two
-// public-port listeners: the supervisor's raw-TCP proxy (supervise.ts) and the dashboard/public gateway
-// (gateway.ts). A bind failure is the ONE thing neither may survive — it is the opposite of the keep-serving
-// process guard, which rides out transient throws once the port is already held. So instead of leaving the
-// listen error unhandled (under `serve` the supervisor's uncaughtException guard would SWALLOW it into a
-// portless zombie on a random child port; under `dashboard`, with no guard, it would crash with a raw stack),
-// we attach one handler that fails loudly the same way on both surfaces: name the busy port and the repair,
-// reap any child booted for this bind so none is orphaned, and exit non-zero.
+// @@@ listenOrExit ([[listener-readiness]]) - the one public-listener transition: before `listening`, a bind
+// failure is loud and fatal; after it, publication side effects and user-visible ready lines may run. Keeping
+// both halves here prevents a private child or pre-bind caller from announcing a surface it does not own.
 //
 // http.Server / https.Server both extend net.Server, so this one signature covers every caller.
 export function listenOrExit(server, port, opts) {
@@ -17,8 +12,13 @@ export function listenOrExit(server, port, opts) {
         console.error(`spec-cli: ${opts.label} cannot bind — ${why}. Free :${port} (e.g. lsof -i :${port}) or pick another port, then retry.`);
         process.exit(1);
     });
+    const publishReady = () => {
+        opts.onListen?.();
+        for (const line of Array.isArray(opts.ready) ? opts.ready : [opts.ready])
+            console.log(line);
+    };
     if (opts.host)
-        server.listen(port, opts.host, opts.onListen);
+        server.listen(port, opts.host, publishReady);
     else
-        server.listen(port, opts.onListen);
+        server.listen(port, publishReady);
 }

package/dist/opencode-headless.d.ts

@@ -1,4 +1,5 @@
 import { type DispatchResult, type HarnessDeliveryRecord } from './harness.js';
 export declare function opencodeHeadlessLaunchCommand(opencodeCmd?: string): string;
 export declare function opencodeHeadlessWakeCommand(opencodeCmd: string, harnessSessionId: string | null | undefined, text: string, outcomePath?: string): string;
+export declare function opencodeHeadlessColdRuntime(rec: Pick<HarnessDeliveryRecord, 'session'>): Promise<DispatchResult>;
 export declare function spawnOpenCodeHeadlessTurn(rec: HarnessDeliveryRecord, text: string, opencodeCmd: string, socketPath: string): Promise<DispatchResult>;

package/dist/opencode-headless.js

@@ -97,6 +97,13 @@ export function opencodeHeadlessWakeCommand(opencodeCmd, harnessSessionId, text,
     ];
     return turnHome([...runPrelude(opencodeCmd), ...resume].join('\n'), outcomePath);
 }
+export async function opencodeHeadlessColdRuntime(rec) {
+    const { rendezvousListening } = await import('./harness.js');
+    const probe = await rendezvousListening(rec.session);
+    return probe === 'dead'
+        ? { ok: true }
+        : { ok: false, error: `opencode-headless rendezvous is still ${probe === 'live' ? 'live' : 'unproven'}` };
+}
 function readTurnOutcome(path) {
     let value;
     try {

package/dist/runtime-rotate.d.ts

@@ -0,0 +1 @@
+export declare function runDoctorRepairAppServer(args: string[]): Promise<number>;

package/dist/runtime-rotate.js

@@ -0,0 +1,58 @@
+import { mainCheckout, runtimeRoot } from '@spexcode/spec-core';
+import { rotateCodexCurrentGeneration } from './codex-runtime-generations.js';
+import { codexBinary, defaultLauncher, resolveLauncher, sessionIdentityEnvVars } from './harness.js';
+import { spawnDetachedRuntime } from './runtime-ownership.js';
+function usageError(message) {
+    console.error(`spex doctor repair app-server: ${message}`);
+    console.error('usage: spex doctor repair app-server [--launcher <name>]');
+    process.exit(2);
+}
+function parseAppServerRepairArgs(args) {
+    const positionals = [];
+    let launcher = null;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === '--launcher') {
+            const value = args[++index];
+            if (!value || value.startsWith('--'))
+                usageError('--launcher requires a configured launcher name');
+            if (launcher !== null)
+                usageError('--launcher may appear only once');
+            launcher = value;
+        }
+        else if (arg.startsWith('--'))
+            usageError(`unknown flag ${arg}`);
+        else
+            positionals.push(arg);
+    }
+    if (positionals.length !== 2 || positionals[0] !== 'repair' || positionals[1] !== 'app-server')
+        usageError('expected repair app-server');
+    return { launcher };
+}
+export async function runDoctorRepairAppServer(args) {
+    const parsed = parseAppServerRepairArgs(args);
+    const project = mainCheckout();
+    const root = runtimeRoot();
+    const launcherName = parsed.launcher ?? defaultLauncher(project);
+    const launcher = resolveLauncher(launcherName, project);
+    if (launcher.harness !== 'codex' && launcher.harness !== 'codex-headless') {
+        usageError(`launcher '${launcher.name}' does not provide a switchable app-server; select a configured Codex launcher with --launcher`);
+    }
+    const command = process.env.SPEXCODE_CODEX_SERVER_CMD || codexBinary(launcher.cmd);
+    const env = { ...process.env };
+    for (const key of sessionIdentityEnvVars())
+        delete env[key];
+    const rotation = await rotateCodexCurrentGeneration(root, async (candidate) => {
+        await spawnDetachedRuntime({
+            cwd: root,
+            logFile: candidate.logFile,
+            pidFile: candidate.pidFile,
+            receiptFile: candidate.receiptFile,
+            command,
+            args: ['app-server', '--listen', `unix://${candidate.socketPath}`],
+            env,
+        });
+    });
+    console.log(`switched app-server ${rotation.previous.id} -> ${rotation.current.id} (launcher ${launcher.name})`);
+    return 0;
+}

package/dist/session-follow.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { sessionStoreDir } from '@spexcode/spec-core';
-import { advanceFollow, followCursor, unreadSince } from './session-cursors.js';
+import { advanceFollow, followCursor, unreadSince } from '@spexcode/session-core';
 import { timelineDisplay, timelineEvents, timelineStamp } from './session-timeline.js';
 import { sessionTitle } from './sessions.js';
 // @@@ session-follow - supervision is FOLLOWING a log past a cursor, never polling a derived board. One tick

package/dist/session-timeline.d.ts

@@ -1,51 +1,11 @@
-import type { Lifecycle, Proposal } from './sessions.js';
-import type { ExecutionTurn } from './execution-trace.js';
-export type TimelineEvent = {
-    ts: string;
-    kind: 'status';
-    status: Lifecycle;
-    proposal: Proposal | null;
-    note: string | null;
-    display?: string;
-} | {
-    ts: string;
-    kind: 'sent';
-    mid: string;
-    text: string;
-    from: string | null;
-    replyVia?: 'note';
-};
-export type SentDispatchReceipt = {
-    operation: 'merge';
-    requestDigest: string;
-    payloadHash: string;
-    delivery?: {
-        text: string;
-        from: string | null;
-    };
-};
-export declare function recordStatus(id: string, status: Lifecycle, proposal: Proposal | 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;
+import { type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
+import { type TimelineEvent } from '@spexcode/session-core';
+export * from '@spexcode/session-core';
 type DisplayWord = 'working' | 'idle' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued';
-export declare const timelineDisplay: (e: {
-    status: Lifecycle;
-    proposal: Proposal | null;
+export declare const timelineDisplay: (event: {
+    status: SessionLifecycle;
+    proposal: SessionProposal | null;
 }) => DisplayWord;
-export declare function lastHumanSendVia(id: string): 'note' | null;
-export declare function currentHumanTurn(id: string): ExecutionTurn | null;
 export declare function readTimeline(id: string, limit?: number): {
     events: TimelineEvent[];
 } | null;
-export {};

package/dist/session-timeline.js

@@ -1,211 +1,11 @@
-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, readAliasedRawRecord } 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 display word for an authored state — the SAME vocabulary every other surface speaks (awaiting → its
-// proposal's label, active → working), duplicated here as a tiny read-time map rather than importing the state
-// machine (sessions.ts imports THIS module for appendSent; a value import back would be a cycle — the
-// Lifecycle/Proposal imports above are type-only, erased at runtime).
+import { readAliasedRawRecord } from '@spexcode/spec-core';
+import { timelineTail } from '@spexcode/session-core';
+export * from '@spexcode/session-core';
 const PROPOSAL_DISPLAY = { merge: 'review', nothing: 'done', close: 'close-pending' };
-export const timelineDisplay = (e) => e.status === 'awaiting' ? (PROPOSAL_DISPLAY[e.proposal ?? 'nothing'] ?? 'done')
-    : e.status === 'active' ? 'working' : e.status;
-// 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;
-}
-// The current human turn is a durable fact from the accepted-message log, not a backend-local generation.
-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;
-}
-// the read surface behind GET /api/sessions/:id/timeline: the last `limit` events, oldest first, each status
-// event carrying its composed display word. null = no such session (the route 404s).
+export const timelineDisplay = (event) => event.status === 'awaiting' ? (PROPOSAL_DISPLAY[event.proposal ?? 'nothing'] ?? 'done')
+    : event.status === 'active' ? 'working' : event.status;
+// The HTTP projection remains a SpexCode concern: it resolves aliases, hides unmanaged records, and adds the
+// board's display vocabulary. The package beneath it only reads the durable file protocol.
 export function readTimeline(id, limit = 500) {
     let raw;
     try {
@@ -216,18 +16,5 @@ export function readTimeline(id, limit = 500) {
     }
     if (!raw || !raw.governed)
         return null;
-    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 { events: tail.map((e) => {
-            if (e.kind === 'status')
-                return { ...e, display: timelineDisplay(e) };
-            const { dispatchReceipt: _receipt, ...event } = e;
-            return event;
-        }) };
+    return { events: timelineTail(raw.session_id, limit).map((event) => event.kind === 'status' ? { ...event, display: timelineDisplay(event) } : event) };
 }

package/dist/sessions.d.ts

@@ -1,9 +1,9 @@
 import { type ReviewDiffFile } from '@spexcode/spec-core';
 import { type ConfigPreset, type SpecLite } from '@spexcode/spec-core';
-import { type Harness, type TurnFailure, type DispatchResult, type PaneProbe } from './harness.js';
+import { type Harness, type TurnFailure, type DispatchResult, type PaneProbe, type ProcTable } from './harness.js';
 import { envSessionId, type RawRecord, type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
 import { type SessionWeb } from './session-web.js';
-import { type SentDispatchReceipt } from './session-timeline.js';
+import { type MessageIdempotency } from '@spexcode/session-core';
 export declare const TMUX_SOCK: string;
 export type { DispatchResult };
 export type Lifecycle = SessionLifecycle;
@@ -129,7 +129,7 @@ export declare function backendLaunchAuthority(env?: {
     PORT?: string;
 }): string;
 export declare function rawLifecycleStatus(rec: Pick<SessRec, 'status' | 'launchOwner'>): string;
-export declare function canDrainQueued(rec: Pick<SessRec, 'status' | 'launchOwner'>, authority?: string): boolean;
+export declare function canDrainQueued(rec: Pick<SessRec, 'status' | 'launchOwner' | 'stopped'>, authority?: string): boolean;
 export declare class SessionRecordUnusable extends Error {
     readonly code: 'corrupt' | 'retired';
     readonly session: string;
@@ -296,6 +296,7 @@ export declare const markDone: (proposal?: Proposal, sessionId?: string, note?:
 export declare const markError: (sessionId?: string) => boolean;
 export declare function markTurnFailure(sessionId: string | undefined, note: string): boolean;
 export declare function markHeadlessTurnFailure(sessionId: string, harness: string, exitCode: string): boolean;
+export declare function stageHarnessLaunchProof(sessionId: string | undefined, harnessSessionId: string | undefined, launchPayload: string): boolean;
 export declare function markHarnessSessionId(sessionId: string | undefined, harnessSessionId: string | undefined): boolean;
 export declare function markIdle(sessionId?: string): boolean;
 export declare function mergeReadiness(proposal?: 'merge' | 'nothing'): {
@@ -344,6 +345,26 @@ export type MergeSessionResult = {
     status?: 409;
 };
 export declare function mergeSession(id: string): Promise<MergeSessionResult>;
+export type SessionLeafReceipt = {
+    version: 1;
+    kind: 'session-leaf';
+    sessionId: string;
+    pid: number;
+    startToken: string;
+};
+type SessionLeafReceiptCandidate = {
+    ok: boolean;
+    receipt?: SessionLeafReceipt;
+    reason?: string;
+};
+export declare function parseSessionLeafReceipt(raw: string, sessionId: string): SessionLeafReceipt | null;
+export declare function sessionLeafReceiptCandidate(sessionId: string, pid: number, panePid: number | null, procs: ProcTable | null, startBefore: string | null, startAfter: string | null): SessionLeafReceiptCandidate;
+export declare function sessionLeafReceiptIdentityState(receipt: SessionLeafReceipt, registeredPid: number | null, currentStartToken: string | null, liveness: 'alive' | 'dead' | 'unknown'): 'same-live' | 'gone' | 'pid-reused' | 'unknown' | 'registration-changed' | 'registration-missing';
+export type SessionLeafProcessProbe = Readonly<{
+    startToken(pid: number): string | null;
+    liveness(pid: number): 'alive' | 'dead' | 'unknown';
+}>;
+export declare function installSessionLeafProcessProbeForTest(probe: SessionLeafProcessProbe): () => void;
 export declare const stopSession: (id: string) => Promise<boolean>;
 export declare const archiveSession: (id: string, on?: boolean) => Promise<boolean>;
 export declare const closeSession: (id: string, rawSource?: unknown) => Promise<boolean>;
@@ -394,7 +415,7 @@ export type SessionTableScope = {
     parent: string;
 };
 export declare function formatTable(sessions: Session[], color?: boolean, scope?: SessionTableScope): string;
-type DispatchIdempotency = SentDispatchReceipt;
+type DispatchIdempotency = MessageIdempotency;
 type DispatchAcceptCode = 'dispatch_key_reused' | 'session_merge_not_proposed';
 type AcceptedDispatch = DispatchResult & {
     replayed?: boolean;