spexcode 0.6.5 → 0.6.7

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

@@ -0,0 +1,326 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isSessionLifecycle, isSessionProposal, listSessionIds, readRecordEntry, sessionArtifactPath, sessionRecordPath, sessionStoreDir, } from '@spexcode/spec-core';
+import { enqueue, ensurePendingWhileLocked, withDeliveryLocks } from './delivery-queue.js';
+import { withSessionRecordLocks } from './record-lock.js';
+import { appendSent, recordStatus, sentDispatchReceipt } from './session-timeline.js';
+export class RuntimeSessionConflict extends Error {
+    code = 'runtime_session_conflict';
+    constructor(message) {
+        super(message);
+        this.name = 'RuntimeSessionConflict';
+    }
+}
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const watchPath = (target) => sessionArtifactPath(target, 'watchers.json');
+const RUNTIME_NOTIFICATION_KIND = 'spex.runtime-state.v1';
+function scalar(value, field) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new RuntimeSessionConflict(`${field} must be a non-empty string`);
+    return normalized;
+}
+function metadata(value) {
+    if (!value)
+        return {};
+    const entries = Object.entries(value).map(([rawKey, rawValue]) => {
+        const key = scalar(rawKey, 'runtimeMetadata key');
+        if (typeof rawValue !== 'string')
+            throw new RuntimeSessionConflict(`runtimeMetadata.${key} must be a string`);
+        return [key, rawValue];
+    }).sort(([left], [right]) => left.localeCompare(right));
+    if (new Set(entries.map(([key]) => key)).size !== entries.length)
+        throw new RuntimeSessionConflict('runtimeMetadata keys must be unique after normalization');
+    return Object.fromEntries(entries);
+}
+function metadataKey(value) {
+    return JSON.stringify(metadata(value));
+}
+function readRaw(id) {
+    const entry = readRecordEntry(id);
+    if (entry.kind === 'absent')
+        return null;
+    if (entry.kind === 'corrupt')
+        throw new RuntimeSessionConflict(`session ${id} record is corrupt: ${entry.error}`);
+    return entry.raw;
+}
+function runtimeRecord(raw) {
+    const runtimeOwner = raw.runtime_owner?.trim();
+    if (!runtimeOwner)
+        throw new RuntimeSessionConflict(`session ${raw.session_id} is not owned by an external runtime`);
+    if (!isSessionLifecycle(raw.status))
+        throw new RuntimeSessionConflict(`session ${raw.session_id} has invalid lifecycle ${JSON.stringify(raw.status)}`);
+    if (!(raw.proposal == null || raw.proposal === '' || isSessionProposal(raw.proposal)))
+        throw new RuntimeSessionConflict(`session ${raw.session_id} has invalid proposal ${JSON.stringify(raw.proposal)}`);
+    return {
+        sessionId: raw.session_id,
+        runtimeOwner,
+        runtimeState: raw.runtime_state?.trim() || null,
+        revision: raw.runtime_revision?.trim() || null,
+        worktreePath: raw.worktree_path,
+        branch: raw.branch || null,
+        parentSessionId: raw.parent || null,
+        title: raw.title || null,
+        node: raw.node || null,
+        runtimeMetadata: metadata(raw.runtime_metadata),
+        lifecycle: raw.status,
+        proposal: isSessionProposal(raw.proposal) ? raw.proposal : null,
+        note: raw.note || null,
+        createdAt: Number(raw.createdAt) || 0,
+    };
+}
+function writeRaw(raw) {
+    const dir = sessionStoreDir(raw.session_id);
+    mkdirSync(dir, { recursive: true });
+    const path = sessionRecordPath(raw.session_id);
+    const tmp = join(dir, `.session.json.${process.pid}.${randomUUID()}.tmp`);
+    writeFileSync(tmp, JSON.stringify(raw, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+function readWatches(target) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(watchPath(target), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new RuntimeSessionConflict(`session ${target} watch record is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new RuntimeSessionConflict(`session ${target} watch record is not an array`);
+    return parsed.map((candidate, index) => {
+        if (!candidate || typeof candidate !== 'object')
+            throw new RuntimeSessionConflict(`session ${target} watch row ${index} is invalid`);
+        const row = candidate;
+        if (typeof row.watcher !== 'string' || typeof row.createdAt !== 'string' || !Array.isArray(row.sources)
+            || row.sources.some((source) => source !== 'manual' && source !== 'parent')
+            || (row.snapshotPending !== undefined && typeof row.snapshotPending !== 'string'))
+            throw new RuntimeSessionConflict(`session ${target} watch row ${index} is invalid`);
+        return row;
+    });
+}
+function writeWatches(target, entries) {
+    const dir = sessionStoreDir(target);
+    mkdirSync(dir, { recursive: true });
+    const path = watchPath(target);
+    const tmp = join(dir, `.watchers.json.${process.pid}.${randomUUID()}.tmp`);
+    writeFileSync(tmp, JSON.stringify(entries, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+function registrationRaw(input) {
+    const sessionId = scalar(input.sessionId, 'sessionId');
+    const runtimeOwner = scalar(input.runtimeOwner, 'runtimeOwner');
+    return {
+        session_id: sessionId,
+        governed: false,
+        worktree_path: scalar(input.worktreePath, 'worktreePath'),
+        branch: input.branch ?? '',
+        node: input.node?.trim() || '',
+        title: input.title?.trim() || '',
+        name: '',
+        parent: input.parentSessionId?.trim() || '',
+        status: 'active',
+        proposal: '',
+        merges: 0,
+        note: '',
+        sortkey: null,
+        createdAt: input.createdAt ?? Date.now(),
+        harness: runtimeOwner,
+        harness_session_id: sessionId,
+        stopped: false,
+        archived: false,
+        cold_proof: '',
+        adapter_recovery: '',
+        launcher: '',
+        launch_cmd: '',
+        create_request_id: '',
+        create_payload_hash: '',
+        runtime_owner: runtimeOwner,
+        runtime_state: 'registered',
+        runtime_revision: '',
+        runtime_metadata: metadata(input.runtimeMetadata),
+        launch_readiness_pending: '',
+    };
+}
+function sameRegistration(raw, input) {
+    return raw.runtime_owner === input.runtimeOwner.trim()
+        && raw.worktree_path === input.worktreePath.trim()
+        && (raw.branch || null) === (input.branch || null)
+        && (raw.parent || null) === (input.parentSessionId?.trim() || null)
+        && metadataKey(raw.runtime_metadata) === metadataKey(input.runtimeMetadata);
+}
+export async function registerRuntimeSession(input) {
+    const id = scalar(input.sessionId, 'sessionId');
+    const parent = input.parentSessionId?.trim() || null;
+    return withSessionRecordLocks([id, ...(parent ? [parent] : [])], async () => {
+        if (parent) {
+            const parentRaw = readRaw(parent);
+            if (!parentRaw)
+                throw new RuntimeSessionConflict(`parent runtime session ${parent} is not registered`);
+            if (parentRaw.runtime_owner !== input.runtimeOwner.trim())
+                throw new RuntimeSessionConflict(`parent runtime session ${parent} belongs to another runtime`);
+        }
+        const existing = readRaw(id);
+        if (existing) {
+            if (!sameRegistration(existing, input))
+                throw new RuntimeSessionConflict(`session ${id} is already registered with different runtime coordinates`);
+            return { replayed: true };
+        }
+        writeRaw(registrationRaw(input));
+        if (parent)
+            writeWatches(id, [{
+                    watcher: parent,
+                    createdAt: new Date().toISOString(),
+                    sources: ['parent'],
+                    snapshotPending: randomUUID(),
+                }]);
+        return { replayed: false };
+    });
+}
+function stateMessage(record) {
+    const proposal = record.lifecycle === 'awaiting' && record.proposal ? `/${record.proposal}` : '';
+    const note = record.note ? ` — ${record.note}` : '';
+    return `[spex watch] ${record.sessionId} is ${record.runtimeState ?? record.lifecycle}${proposal}${note}`;
+}
+function notificationAttributes(record) {
+    if (!record.revision || !record.runtimeState)
+        throw new RuntimeSessionConflict(`runtime session ${record.sessionId} has no publishable state revision`);
+    return {
+        kind: RUNTIME_NOTIFICATION_KIND,
+        runtimeOwner: record.runtimeOwner,
+        runtimeState: record.runtimeState,
+        revision: record.revision,
+        lifecycle: record.lifecycle,
+        proposal: record.proposal ?? '',
+        note: record.note ?? '',
+    };
+}
+function pendingFor(receipt, mid) {
+    return {
+        mid,
+        text: receipt.delivery.text,
+        from: receipt.delivery.from,
+        ...(receipt.delivery.attributes ? { attributes: receipt.delivery.attributes } : {}),
+        dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
+    };
+}
+export function runtimeSessionNotification(parentSessionId, message) {
+    const parent = scalar(parentSessionId, 'parentSessionId');
+    const child = message.from?.trim();
+    const attributes = message.attributes;
+    if (!child || !attributes || attributes.kind !== RUNTIME_NOTIFICATION_KIND)
+        return null;
+    const record = readRuntimeSession(child);
+    if (!record || record.parentSessionId !== parent || record.runtimeOwner !== attributes.runtimeOwner)
+        return null;
+    if (!attributes.revision || !attributes.runtimeState || !isSessionLifecycle(attributes.lifecycle))
+        return null;
+    if (attributes.proposal && !isSessionProposal(attributes.proposal))
+        return null;
+    return {
+        childSessionId: child,
+        runtimeOwner: attributes.runtimeOwner,
+        runtimeState: attributes.runtimeState,
+        revision: attributes.revision,
+        lifecycle: attributes.lifecycle,
+        proposal: isSessionProposal(attributes.proposal) ? attributes.proposal : null,
+        note: attributes.note || null,
+        runtimeMetadata: record.runtimeMetadata,
+    };
+}
+export async function publishRuntimeSessionState(input) {
+    const id = scalar(input.sessionId, 'sessionId');
+    const owner = scalar(input.runtimeOwner, 'runtimeOwner');
+    const revision = scalar(input.revision, 'revision');
+    const runtimeState = scalar(input.runtimeState, 'runtimeState');
+    const initial = readRaw(id);
+    if (!initial)
+        throw new RuntimeSessionConflict(`runtime session ${id} is not registered`);
+    const watchers = readWatches(id).map((entry) => entry.watcher);
+    return withSessionRecordLocks([id, ...watchers], async () => withDeliveryLocks(watchers, async () => {
+        const raw = readRaw(id);
+        if (!raw)
+            throw new RuntimeSessionConflict(`runtime session ${id} disappeared during publication`);
+        if (raw.runtime_owner !== owner)
+            throw new RuntimeSessionConflict(`runtime session ${id} belongs to ${raw.runtime_owner || 'no external runtime'}, not ${owner}`);
+        const proposal = input.proposal ?? null;
+        const note = input.note ?? null;
+        const sameRevision = raw.runtime_revision === revision;
+        const sameState = raw.runtime_state === runtimeState && raw.status === input.lifecycle
+            && (raw.proposal || null) === proposal && (raw.note || null) === note;
+        if (sameRevision && !sameState)
+            throw new RuntimeSessionConflict(`runtime revision ${revision} for session ${id} is already bound to another state`);
+        const candidate = runtimeRecord({
+            ...raw,
+            status: input.lifecycle,
+            proposal: proposal ?? '',
+            note: note ?? '',
+            runtime_state: runtimeState,
+            runtime_revision: revision,
+        });
+        const message = stateMessage(candidate);
+        const attributes = notificationAttributes(candidate);
+        const historical = watchers.map((watcher) => {
+            const operation = `runtime-state:${id}`;
+            const requestDigest = digest(`${id}\0${watcher}\0${revision}`);
+            const payloadHash = digest(`${operation}\0${requestDigest}\0${message}\0${JSON.stringify(attributes)}`);
+            const prior = sentDispatchReceipt(watcher, operation, requestDigest);
+            if (prior && prior.payloadHash !== payloadHash)
+                throw new RuntimeSessionConflict(`runtime revision ${revision} notification is already bound to different bytes`);
+            return { watcher, operation, requestDigest, payloadHash, prior };
+        });
+        const historicalReplay = !sameRevision && historical.length > 0 && historical.every(({ prior }) => prior);
+        const replayed = sameRevision || historicalReplay;
+        if (!sameRevision) {
+            if (!historicalReplay) {
+                writeRaw({
+                    ...raw,
+                    status: input.lifecycle,
+                    proposal: proposal ?? '',
+                    note: note ?? '',
+                    runtime_state: runtimeState,
+                    runtime_revision: revision,
+                });
+                recordStatus(id, input.lifecycle, proposal, note);
+            }
+        }
+        const notified = [];
+        for (const { watcher, operation, requestDigest, payloadHash, prior } of historical) {
+            const receipt = {
+                operation,
+                requestDigest,
+                payloadHash,
+                delivery: { text: message, from: id, attributes },
+            };
+            if (prior) {
+                if (!prior.delivered)
+                    ensurePendingWhileLocked(watcher, pendingFor(receipt, prior.mid));
+            }
+            else {
+                const { mid } = appendSent(watcher, message, id, undefined, receipt);
+                enqueue(watcher, pendingFor(receipt, mid));
+            }
+            notified.push(watcher);
+        }
+        const entries = readWatches(id);
+        if (entries.some((entry) => entry.snapshotPending)) {
+            writeWatches(id, entries.map(({ snapshotPending: _pending, ...entry }) => entry));
+        }
+        return { notified, replayed };
+    }));
+}
+export function readRuntimeSession(sessionId) {
+    const raw = readRaw(scalar(sessionId, 'sessionId'));
+    return raw?.runtime_owner ? runtimeRecord(raw) : null;
+}
+export function runtimeSessionChildren(parentSessionId, runtimeOwner) {
+    const parent = scalar(parentSessionId, 'parentSessionId');
+    return listSessionIds().flatMap((id) => {
+        const record = readRuntimeSession(id);
+        if (!record || record.parentSessionId !== parent || (runtimeOwner && record.runtimeOwner !== runtimeOwner))
+            return [];
+        return [record];
+    }).sort((left, right) => left.createdAt - right.createdAt || left.sessionId.localeCompare(right.sessionId));
+}

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

@@ -0,0 +1,47 @@
+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;
+        attributes?: Record<string, string>;
+    };
+};
+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.7",
+  "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.7"
+  },
+  "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;