spexcode 0.6.7 → 0.7.0-next.0

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

@@ -71,7 +71,19 @@ export function listSessionFiles(id) {
     requireSession(id);
     return readSessionFiles(id);
 }
-// Session projections already hold a parsed record; re-checking session.json here would make an in-memory
+export function inspectSessionFiles(id) {
+    requireSession(id);
+    return readFiles(id).map((path) => {
+        try {
+            currentFile(path);
+            return { path, valid: true };
+        }
+        catch (error) {
+            return { path, valid: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    });
+}
+// Session projections already hold a parsed runtime envelope; re-checking it here would make an in-memory
 // projection depend on the public route's existence guard. The route-facing list keeps that guard above.
 export function readSessionFiles(id) {
     return readFiles(id);

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

@@ -1,13 +1,9 @@
-import { existsSync } from 'node:fs';
-import { sessionStoreDir } from '@spexcode/spec-core';
-import { advanceFollow, followCursor, unreadSince } from '@spexcode/session-core';
+import { configuredSessionApplicationIfCutover } from './session-application.js';
 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
-// costs ONE stat per target: if timeline.ndjson has not grown, nothing is opened and nothing is parsed. No
-// call here reaches the backend, a rendezvous socket, or tmux, which is the whole point — M followers over N
-// sessions cost the control plane zero, where the old poll cost one board build (a connect + a tmux spawn per
-// live session) per follower per interval.
+// @@@ session-follow - supervision follows canonical SQLite events past an application-owned cursor, never a
+// derived board. The bounded observation tick reads the event sequence and cursor only; it never opens a backend,
+// rendezvous socket, or tmux. M followers over N sessions therefore cost the control plane zero native probes.
 // Actionable = a state whose arrival means "a human/supervisor must now act". `offline` is deliberately ABSENT
 // where the old poll had it: liveness is a present-tense probe derivation, never authored, so it can never
 // appear on a log ([[state]]). A follower learns what a session DECLARED and never that it died.
@@ -51,11 +47,19 @@ export async function followSessions(emit, opts) {
                 return f.path;
         return [];
     };
-    const readCursor = (id) => (self ? followCursor(self, id) : memo.get(id) ?? null);
-    const writeCursor = (id, to) => { if (self)
-        advanceFollow(self, id, to);
-    else
-        memo.set(id, to); };
+    const application = configuredSessionApplicationIfCutover();
+    const canonicalSelf = self && application?.readState(self) ? self : null;
+    const readCursor = (id) => {
+        if (!self)
+            return memo.get(id) ?? null;
+        return canonicalSelf ? application.readFollowCursor(canonicalSelf, id) : null;
+    };
+    const writeCursor = (id, to) => {
+        if (!self)
+            memo.set(id, to);
+        else if (canonicalSelf)
+            application.advanceFollowCursor(canonicalSelf, id, to);
+    };
     const line = (id, st, note, first) => {
         const s = row?.(id, st, note);
         if (!s)
@@ -74,7 +78,7 @@ export async function followSessions(emit, opts) {
             if (id === self)
                 continue; // the follower's own log is its INBOX, followed below on its own cursor rule
             seen.add(id);
-            if (!existsSync(sessionStoreDir(id))) {
+            if (!application?.readState(id)) {
                 if (state.delete(id))
                     emit(`${tag}[spex] closed · removed  [id ${id}]`);
                 if (take)
@@ -111,7 +115,12 @@ export async function followSessions(emit, opts) {
                 continue; // THE cheap tick: nothing appended, nothing parsed
             f.stamp = stamp;
             const evs = timelineEvents(id);
-            const slice = unreadSince(evs, f.pos);
+            const unread = evs.slice(f.pos);
+            const slice = {
+                events: unread,
+                at: unread.map((_, index) => f.pos + index),
+                next: evs.length,
+            };
             let hit = null;
             for (let k = 0; k < slice.events.length && !hit; k++) {
                 const e = slice.events[k];
@@ -151,18 +160,26 @@ export async function followSessions(emit, opts) {
             state.delete(id);
             emit(`${tag}[spex] closed · removed  [id ${id}]`);
         }
-        // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own entry in `cursors.json`. It is
-        // a WATCH, not a delivery: a message reaches the agent as a prompt through the adapter ([[delivery-queue]]),
-        // so this position only decides what THIS process has already reported and can never make an agent miss
-        // mail. Never advanced here in take mode — the waiter stops on the event and the next wait resumes on it.
-        if (self && existsSync(sessionStoreDir(self))) {
-            const mine = unreadSince(timelineEvents(self), followCursor(self, self) ?? 0);
+        // THE FOLLOWER'S OWN LOG — watched exactly like any other target, on its own canonical cursor row. In take
+        // mode the returned message is this wait's consumed result, so advance past it before returning; otherwise
+        // an empty cursor returns the same oldest inbox message forever. A turn-boundary delivery may still present
+        // the message through the adapter, but it does not own this read cursor.
+        if (self && application?.readState(self)) {
+            const ownEvents = timelineEvents(self);
+            const ownStart = readCursor(self) ?? 0;
+            const ownUnread = ownEvents.slice(ownStart);
+            const mine = {
+                events: ownUnread,
+                at: ownUnread.map((_, index) => ownStart + index),
+            };
             for (let k = 0; k < mine.events.length; k++) {
                 const e = mine.events[k];
                 if (e.kind !== 'sent')
                     continue;
-                if (take)
+                if (take) {
+                    writeCursor(self, mine.at[k] + 1);
                     return { mail: { from: e.from, text: e.text } };
+                }
                 // a stream has no turn boundary to advance that cursor, so its own high-water mark — process-local,
                 // never written — is what keeps an unread line from being re-printed on every tick.
                 if (mine.at[k] <= shown)

package/node_modules/@spexcode/{session-core/dist/record-lock.d.ts → spec-cli/dist/session-record-lock.d.ts}

@@ -1,7 +1,3 @@
-export declare class SessionRecordLockTimeout extends Error {
-    constructor(id: string);
-}
 export declare function withSessionRecordLock<T>(id: string, body: () => Promise<T>, signal?: AbortSignal): Promise<T>;
 export declare function withSessionRecordLockSync<T>(id: string, body: () => T): T;
 export declare function trySessionRecordLockSync(id: string): (() => void) | null;
-export declare function withSessionRecordLocks<T>(rawIds: string[], body: () => Promise<T>, index?: number, ids?: string[]): Promise<T>;

package/node_modules/@spexcode/spec-cli/dist/session-record-lock.js

@@ -0,0 +1,94 @@
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '@spexcode/spec-core';
+const root = () => join(runtimeRoot(), '.session-record-locks');
+const pathFor = (id) => join(root(), `${id}.lock`);
+const pause = (signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' }));
+        return;
+    }
+    const timer = setTimeout(resolve, 10);
+    if (signal)
+        signal.addEventListener('abort', () => { clearTimeout(timer); reject(Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' })); }, { once: true });
+});
+async function acquire(id, timeoutMs = 30_000, signal) {
+    mkdirSync(root(), { recursive: true });
+    const path = pathFor(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (signal?.aborted)
+            throw Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' });
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* dead-owner recovery may have removed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* creator/releaser race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`session record ${id}: timed out waiting for transaction lock`);
+            await pause(signal);
+        }
+    }
+}
+export async function withSessionRecordLock(id, body, signal) {
+    const release = await acquire(id, 30_000, signal);
+    try {
+        return await body();
+    }
+    finally {
+        release();
+    }
+}
+export function withSessionRecordLockSync(id, body) {
+    const release = trySessionRecordLockSync(id);
+    if (!release)
+        throw new Error(`session record ${id}: transaction lock is busy`);
+    try {
+        return body();
+    }
+    finally {
+        release();
+    }
+}
+export function trySessionRecordLockSync(id) {
+    mkdirSync(root(), { recursive: true });
+    const path = pathFor(id);
+    try {
+        const fd = openSync(path, 'wx');
+        writeSync(fd, String(process.pid));
+        closeSync(fd);
+        return () => { try {
+            unlinkSync(path);
+        }
+        catch { /* dead-owner recovery may have removed it */ } };
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return null;
+        throw error;
+    }
+}

package/node_modules/@spexcode/spec-cli/dist/session-runtime-adapter.d.ts

@@ -0,0 +1,44 @@
+export interface GovernedRuntimeIdentity {
+    protocolSessionId: string;
+    harnessId: string;
+    harnessSessionId: string;
+    nativeStartToken: string;
+    metadata?: Record<string, unknown>;
+}
+export interface GovernedRuntimeBindingOptions {
+    expectedGeneration?: number;
+    now?: number;
+}
+export interface GovernedRuntimeBinding {
+    namespace: string;
+    protocolSessionId: string;
+    runtimeKind: string;
+    nativeSessionId: string;
+    nativeStartToken: string;
+    bindingGeneration: number;
+    status: 'bound' | 'unbound';
+    boundAtMs: number;
+    unboundAtMs: number | null;
+    metadata: Record<string, unknown>;
+}
+export interface GovernedProtocolTransactionHost<Transaction = unknown> {
+    withTransaction<T>(body: (transaction: Transaction) => T): T;
+}
+export interface GovernedRuntimeBindingStore<Transaction = unknown> {
+    bind(transaction: Transaction, protocolSessionId: string, identity: {
+        namespace: string;
+        runtimeKind: string;
+        nativeSessionId: string;
+        nativeStartToken: string;
+        metadata?: Record<string, unknown>;
+    }, options?: GovernedRuntimeBindingOptions): GovernedRuntimeBinding;
+    resolve(namespace: string, protocolSessionId: string, transaction?: Transaction): GovernedRuntimeBinding | null;
+    unbind(transaction: Transaction, namespace: string, protocolSessionId: string, options?: GovernedRuntimeBindingOptions): GovernedRuntimeBinding;
+}
+/**
+ * Bind an identity whose storage and native start token were already established by Spex composition.
+ * Database placement, locality, launch, and legacy record publication deliberately remain outside this seam.
+ */
+export declare function bindSpexGovernedRuntime<Transaction>(protocol: GovernedProtocolTransactionHost<Transaction>, bindings: GovernedRuntimeBindingStore<Transaction>, identity: GovernedRuntimeIdentity, options?: GovernedRuntimeBindingOptions): GovernedRuntimeBinding;
+export declare function resolveSpexGovernedRuntime<Transaction>(bindings: GovernedRuntimeBindingStore<Transaction>, protocolSessionId: string, transaction?: Transaction): GovernedRuntimeBinding | null;
+export declare function unbindSpexGovernedRuntime<Transaction>(protocol: GovernedProtocolTransactionHost<Transaction>, bindings: GovernedRuntimeBindingStore<Transaction>, protocolSessionId: string, options?: GovernedRuntimeBindingOptions): GovernedRuntimeBinding;

package/node_modules/@spexcode/spec-cli/dist/session-runtime-adapter.js

@@ -0,0 +1,37 @@
+const SPEX_GOVERNED_NAMESPACE = 'spex-governed';
+function requireNonempty(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Spex governed runtime binding requires ${field}`);
+    }
+}
+/**
+ * Bind an identity whose storage and native start token were already established by Spex composition.
+ * Database placement, locality, launch, and legacy record publication deliberately remain outside this seam.
+ */
+export function bindSpexGovernedRuntime(protocol, bindings, identity, options = {}) {
+    requireNonempty(identity.protocolSessionId, 'protocolSessionId');
+    requireNonempty(identity.harnessId, 'harnessId');
+    requireNonempty(identity.harnessSessionId, 'harnessSessionId');
+    requireNonempty(identity.nativeStartToken, 'nativeStartToken');
+    if (!protocol || typeof protocol.withTransaction !== 'function') {
+        throw new TypeError('Spex governed runtime binding requires an open protocol transaction host');
+    }
+    if (!bindings || typeof bindings.bind !== 'function') {
+        throw new TypeError('Spex governed runtime binding requires an open runtime binding store');
+    }
+    return protocol.withTransaction(transaction => bindings.bind(transaction, identity.protocolSessionId, {
+        namespace: SPEX_GOVERNED_NAMESPACE,
+        runtimeKind: identity.harnessId,
+        nativeSessionId: identity.harnessSessionId,
+        nativeStartToken: identity.nativeStartToken,
+        metadata: identity.metadata,
+    }, options));
+}
+export function resolveSpexGovernedRuntime(bindings, protocolSessionId, transaction) {
+    requireNonempty(protocolSessionId, 'protocolSessionId');
+    return bindings.resolve(SPEX_GOVERNED_NAMESPACE, protocolSessionId, transaction);
+}
+export function unbindSpexGovernedRuntime(protocol, bindings, protocolSessionId, options = {}) {
+    requireNonempty(protocolSessionId, 'protocolSessionId');
+    return protocol.withTransaction(transaction => bindings.unbind(transaction, SPEX_GOVERNED_NAMESPACE, protocolSessionId, options));
+}

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

@@ -1,6 +1,28 @@
 import { type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
-import { type TimelineEvent } from '@spexcode/session-core';
-export * from '@spexcode/session-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 declare const timelineEvents: (id: string) => TimelineEvent[];
+export declare const timelineStamp: (id: string) => string | null;
+export declare const timelineTail: (id: string, limit?: number) => TimelineEvent[];
+export declare const lastHumanSendVia: (id: string) => "note" | null;
+export declare const currentHumanTurn: (id: string) => {
+    token: string;
+    acceptedAt: string;
+} | null;
+export declare const recordStatus: (id: string, status: SessionLifecycle, proposal: SessionProposal | null, note: string | null) => void;
 type DisplayWord = 'working' | 'idle' | 'review' | 'done' | 'close-pending' | 'parked' | 'error' | 'asking' | 'queued';
 export declare const timelineDisplay: (event: {
     status: SessionLifecycle;
@@ -9,3 +31,4 @@ export declare const timelineDisplay: (event: {
 export declare function readTimeline(id: string, limit?: number): {
     events: TimelineEvent[];
 } | null;
+export {};

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

@@ -1,20 +1,77 @@
 import { readAliasedRawRecord } from '@spexcode/spec-core';
-import { timelineTail } from '@spexcode/session-core';
-export * from '@spexcode/session-core';
+import { decodeEventJson } from '@spexcode/session-events';
+import { MIGRATED_MESSAGE_EVENT, MIGRATED_STATE_EVENT } from '@spexcode/session-application';
+import { configuredSessionApplicationIfCutover } from './session-application.js';
+// The timeline is a history: events read in occurrence order (sequence breaks ties). Migrated legacy history
+// lands after the live events in sequence but before them in time, and it is shown where it happened.
+const canonicalSessionId = (id) => readAliasedRawRecord(id)?.session_id ?? id;
+const canonicalTimelineEvents = (id) => {
+    const canonicalId = canonicalSessionId(id);
+    const application = configuredSessionApplicationIfCutover();
+    if (!application || !application.readState(canonicalId))
+        return null;
+    const ordered = [...application.readEvents(canonicalId)].sort((a, b) => a.occurredAtMs - b.occurredAtMs || a.eventSeq - b.eventSeq);
+    return ordered.flatMap((event) => {
+        const decoded = decodeEventJson(event.payload);
+        if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded))
+            return [];
+        const payload = decoded;
+        if (event.type === 'session.state.changed.v1' || event.type === MIGRATED_STATE_EVENT)
+            return [{
+                    ts: new Date(event.occurredAtMs).toISOString(),
+                    kind: 'status',
+                    status: String(payload.status),
+                    proposal: payload.proposal === null || payload.proposal === undefined ? null : String(payload.proposal),
+                    note: payload.note === null || payload.note === undefined ? null : String(payload.note),
+                }];
+        if (event.type === 'session.message.sent.v1' || event.type === MIGRATED_MESSAGE_EVENT)
+            return [{
+                    ts: new Date(event.occurredAtMs).toISOString(),
+                    kind: 'sent',
+                    mid: String(payload.messageId),
+                    text: String(payload.text),
+                    from: payload.from === null || payload.from === undefined ? null : String(payload.from),
+                    ...(payload.replyVia === 'note' ? { replyVia: 'note' } : {}),
+                }];
+        return [];
+    });
+};
+export const timelineEvents = (id) => canonicalTimelineEvents(id) ?? [];
+export const timelineStamp = (id) => {
+    const canonicalId = canonicalSessionId(id);
+    const application = configuredSessionApplicationIfCutover();
+    if (application?.readState(canonicalId)) {
+        const events = application.readEvents(canonicalId);
+        return events.length === 0 ? null : String(events.at(-1).eventSeq);
+    }
+    return null;
+};
+export const timelineTail = (id, limit = 500) => timelineEvents(id).slice(-Math.max(1, limit));
+export const lastHumanSendVia = (id) => {
+    const events = timelineEvents(id);
+    const sent = [...events].reverse().find((event) => event.kind === 'sent' && event.from === null);
+    return sent?.replyVia ?? null;
+};
+export const currentHumanTurn = (id) => {
+    const sent = [...timelineEvents(id)].reverse().find((event) => event.kind === 'sent' && event.from === null);
+    return sent ? { token: sent.mid, acceptedAt: sent.ts } : null;
+};
+export const recordStatus = (id, status, proposal, note) => {
+    const application = configuredSessionApplicationIfCutover();
+    if (!application?.readState(id))
+        throw new Error(`cannot record status for unknown canonical session ${id}`);
+    application.transitionSession(id, { status, proposal, note, reason: 'cli-status' });
+};
 const PROPOSAL_DISPLAY = { merge: 'review', nothing: 'done', close: 'close-pending' };
 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 {
-        raw = readAliasedRawRecord(id);
+    const application = configuredSessionApplicationIfCutover();
+    const canonicalId = canonicalSessionId(id);
+    if (application && application.readState(canonicalId)) {
+        return { events: canonicalTimelineEvents(id).slice(-Math.max(1, limit)).map((event) => event.kind === 'status' ? { ...event, display: timelineDisplay(event) } : event) };
     }
-    catch {
-        return null;
-    }
-    if (!raw || !raw.governed)
-        return null;
-    return { events: timelineTail(raw.session_id, limit).map((event) => event.kind === 'status' ? { ...event, display: timelineDisplay(event) } : event) };
+    return null;
 }

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

@@ -0,0 +1,57 @@
+import type { Context } from 'hono';
+import { type Harness } from './harness.js';
+type Target = {
+    ok: true;
+    harness: Harness;
+    threadId: string;
+} | {
+    ok: false;
+    status: 404 | 409 | 500;
+    error: string;
+};
+export declare function resolveTranscriptTarget(id: string): Target;
+export declare function readSessionTranscript(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 500 | 404 | 409, "json">) | (Response & import("hono").TypedResponse<{
+    readonly revision: string;
+    readonly from: number;
+    readonly to: number;
+    readonly turns: readonly {
+        readonly id: string;
+        readonly at: number;
+        readonly role: "user" | "assistant";
+        readonly text?: string | undefined;
+        readonly tools?: readonly {
+            readonly id: string;
+            readonly name: string;
+            readonly input?: string | undefined;
+            readonly output?: string | undefined;
+            readonly outputLines: number;
+            readonly outputBytes: number;
+        }[] | undefined;
+    }[];
+    readonly truncated: boolean;
+    readonly omittedTurns: number;
+    readonly omittedBytes: number;
+    readonly outOfOrderEvents: number;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    reason: string;
+}, 409 | 422 | 501, "json">)>;
+export declare function readSessionTranscriptTool(c: Context): Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+    reason: string;
+}, 409 | 422 | 501, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 500 | 404 | 409, "json">) | (Response & import("hono").TypedResponse<{
+    id: string;
+    output: string | null;
+    outputLines: number;
+    outputBytes: number;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function sessionTranscriptStream(c: Context): Promise<Response>;
+export {};

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

@@ -0,0 +1,137 @@
+import { streamSSE } from 'hono/streaming';
+import { readAliasedRawRecord } from '@spexcode/spec-core';
+import { defaultHarness, harnessById } from './harness.js';
+import { TranscriptReadError, openFrameStream } from '@spexcode/transcript';
+export function resolveTranscriptTarget(id) {
+    let raw;
+    try {
+        raw = readAliasedRawRecord(id);
+    }
+    catch (error) {
+        return { ok: false, status: 500, error: `session ${id} record is unreadable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (!raw || !raw.governed)
+        return { ok: false, status: 404, error: `session ${id} does not exist` };
+    let harness;
+    try {
+        harness = harnessById(typeof raw.harness === 'string' && raw.harness ? raw.harness : defaultHarness.id);
+    }
+    catch (error) {
+        return { ok: false, status: 500, error: error instanceof Error ? error.message : String(error) };
+    }
+    const threadId = harness.exactNativeTargetId({
+        session: raw.session_id,
+        harnessSessionId: typeof raw.harness_session_id === 'string' ? raw.harness_session_id : null,
+        stopped: !!raw.stopped,
+        archived: !!raw.archived,
+    });
+    if (!threadId)
+        return { ok: false, status: 409, error: `session ${id} transcript is unavailable: native harness identity is missing` };
+    return { ok: true, harness, threadId };
+}
+const epoch = (value) => {
+    if (value == null || value === '')
+        return null;
+    const number = Number(value);
+    return Number.isFinite(number) && Number.isInteger(number) ? number : null;
+};
+const failure = (error) => {
+    if (!(error instanceof TranscriptReadError))
+        throw error;
+    return { body: { error: error.message, reason: error.reason }, status: error.reason === 'unsupported' ? 501 : error.reason === 'invalid' ? 422 : 409 };
+};
+// GET /api/sessions/:id/transcript?from=<ms>&to=<ms> — a closed interval, both bounds explicit so the route
+// never guesses which stretch the caller meant.
+export async function readSessionTranscript(c) {
+    const id = c.req.param('id') || '';
+    const fromRaw = c.req.query('from');
+    const toRaw = c.req.query('to');
+    if (fromRaw == null || toRaw == null || fromRaw === '' || toRaw === '')
+        return c.json({ error: 'transcript needs both from and to epoch milliseconds' }, 400);
+    const from = epoch(fromRaw);
+    const to = epoch(toRaw);
+    if (from === null || to === null || from >= to)
+        return c.json({ error: 'transcript interval is invalid: from and to must be integer epoch milliseconds with from < to' }, 400);
+    const target = resolveTranscriptTarget(id);
+    if (!target.ok)
+        return c.json({ error: target.error }, target.status);
+    try {
+        return c.json(await target.harness.transcript.read(target.threadId, { from, to }));
+    }
+    catch (error) {
+        const { body, status } = failure(error);
+        return c.json(body, status);
+    }
+}
+// GET /api/sessions/:id/transcript/tool/:toolId?from=<ms> — one call's recorded output, read when a person
+// opens it. The live stream withholds output bodies (below), so this is where a body comes from; the interval
+// is `[from, now]`, the same stretch the stream reads, and a call outside it is a 404.
+export async function readSessionTranscriptTool(c) {
+    const id = c.req.param('id') || '';
+    const toolId = c.req.param('toolId') || '';
+    const from = epoch(c.req.query('from'));
+    if (from === null || !toolId)
+        return c.json({ error: 'transcript tool needs a tool id and from as integer epoch milliseconds' }, 400);
+    const target = resolveTranscriptTarget(id);
+    if (!target.ok)
+        return c.json({ error: target.error }, target.status);
+    try {
+        const read = await target.harness.transcript.read(target.threadId, { from, to: Math.max(from + 1, Date.now()) });
+        for (const turn of read.turns)
+            for (const tool of turn.tools ?? []) {
+                if (tool.id !== toolId)
+                    continue;
+                return c.json({ id: tool.id, output: tool.output ?? null, outputLines: tool.outputLines, outputBytes: tool.outputBytes });
+            }
+        return c.json({ error: `tool ${toolId} is not in this interval` }, 404);
+    }
+    catch (error) {
+        const { body, status } = failure(error);
+        return c.json(body, status);
+    }
+}
+const TICK_MS = 500;
+const HEARTBEAT_TICKS = 20;
+// GET /api/sessions/:id/transcript/stream?from=<ms> — the open interval [from, now], carried over SSE. What a
+// frame holds, when one is worth sending, and how a subscriber merges it are [[transcript-frames]]'
+// `openFrameStream`, shared with every other transport; this route owns only the carriage: a tick that asks
+// the stream to publish, one `transcript` SSE event per frame it yields, and periodic `ping` heartbeats so the
+// browser's dead-man can reopen a silent stream. Reading happens only while a client is subscribed and stops
+// on abort, closing the cursor.
+export async function sessionTranscriptStream(c) {
+    const id = c.req.param('id') || '';
+    const from = epoch(c.req.query('from'));
+    if (from === null)
+        return c.json({ error: 'transcript stream needs from as integer epoch milliseconds' }, 400);
+    const target = resolveTranscriptTarget(id);
+    if (!target.ok)
+        return c.json({ error: target.error }, target.status);
+    const frames = openFrameStream(target.harness.transcript, target.threadId, from);
+    return streamSSE(c, async (stream) => {
+        let aborted = false;
+        let ticks = 0;
+        const publish = async () => {
+            const frame = await frames.publish();
+            if (frame)
+                await stream.writeSSE({ event: 'transcript', data: JSON.stringify(frame) });
+        };
+        stream.onAbort(() => { aborted = true; frames.close(); });
+        try {
+            await publish();
+            while (!aborted) {
+                await stream.sleep(TICK_MS);
+                if (aborted)
+                    break;
+                await publish();
+                if (++ticks % HEARTBEAT_TICKS === 0)
+                    await stream.writeSSE({ event: 'ping', data: 'x' });
+            }
+        }
+        catch {
+            // EventSource reconnects a dropped stream; a native read must never take the session server down.
+        }
+        finally {
+            frames.close();
+        }
+    });
+}

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

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { readRecordEntry, sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
+import { readRecordEntry, sessionArtifactPath, sessionRecordPath } from '@spexcode/spec-core';
 import { projectRuntimeRoot } from '@spexcode/spec-core';
 export class SessionWebError extends Error {
     status;
@@ -15,8 +15,8 @@ const webPath = (id, projectRoot) => projectRoot
     ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'web.json')
     : sessionArtifactPath(id, 'web.json');
 const recordPath = (id, projectRoot) => projectRoot
-    ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'session.json')
-    : join(sessionStoreDir(id), 'session.json');
+    ? join(projectRuntimeRoot(join(projectRoot, '.git')), 'sessions', id, 'runtime.json')
+    : sessionRecordPath(id);
 function validSessionId(id) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id);
 }
@@ -104,7 +104,7 @@ export function listSessionWebs(id, projectRoot) {
     requireSession(id, projectRoot);
     return readSessionWebs(id, projectRoot);
 }
-// Session projections already hold a parsed record; re-checking session.json here would make an in-memory
+// Session projections already hold a parsed runtime envelope; re-checking it here would make an in-memory
 // projection depend on the public route's existence guard. The route-facing list keeps that guard above.
 export function readSessionWebs(id, projectRoot) {
     return readWebs(id, projectRoot).map(toWeb);