spexcode 0.6.6 → 0.6.8

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

@@ -1,286 +0,0 @@
-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');
-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 pendingFor(receipt, mid) {
-    return {
-        mid,
-        text: receipt.delivery.text,
-        from: receipt.delivery.from,
-        dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
-    };
-}
-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 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}`);
-            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 },
-            };
-            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-cursors.d.ts

@@ -1,14 +0,0 @@
-import type { TimelineEvent } from './session-timeline.js';
-export type Cursors = {
-    version: 1;
-    follows: Record<string, number>;
-};
-export declare function readCursors(id: string): Cursors;
-export declare const followCursor: (id: string, target: string) => number | null;
-export declare function advanceFollow(id: string, target: string, to: number): void;
-export declare const followedSessions: (id: string) => string[];
-export declare function unreadSince(events: TimelineEvent[], from: number): {
-    events: TimelineEvent[];
-    at: number[];
-    next: number;
-};

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

@@ -1,82 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
-const cursorsPath = (id) => sessionArtifactPath(id, 'cursors.json');
-const at = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0);
-// Never throws: a missing, empty, or unparseable file reads as "nothing consumed", because re-showing a
-// message is the honest recovery for a lost position and skipping one is not. Followed entries whose target
-// store dir is gone are dropped here — expiry is this read, and the next write persists it.
-export function readCursors(id) {
-    let raw = null;
-    try {
-        raw = JSON.parse(readFileSync(cursorsPath(id), 'utf8'));
-    }
-    catch { /* no cursors yet */ }
-    const follows = {};
-    const stored = raw?.follows;
-    if (stored && typeof stored === 'object') {
-        for (const [target, pos] of Object.entries(stored)) {
-            if (!target || !existsSync(sessionStoreDir(target)))
-                continue;
-            follows[target] = at(pos);
-        }
-    }
-    return { version: 1, follows };
-}
-// Written whole and atomically, one field per line — the same shape as the session record, so a position stays
-// readable by an exact whole-line match where a value regex would not be.
-function writeCursors(id, cursors) {
-    const dir = sessionStoreDir(id);
-    mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.cursors.json.${process.pid}.tmp`);
-    writeFileSync(tmp, JSON.stringify(cursors, null, 2) + '\n');
-    renameSync(tmp, cursorsPath(id));
-}
-export const followCursor = (id, target) => {
-    const stored = readCursors(id).follows[target];
-    return stored === undefined ? null : stored;
-};
-// Start or advance a follow. Following IS this entry existing, so the first call registers the relationship.
-// Monotonic: a stale read can leave a position too low (an event read twice), never too high (one lost).
-export function advanceFollow(id, target, to) {
-    const cursors = readCursors(id);
-    const stored = cursors.follows[target];
-    if (stored !== undefined && to <= stored)
-        return;
-    writeCursors(id, { ...cursors, follows: { ...cursors.follows, [target]: Math.max(0, Math.floor(to)) } });
-}
-export const followedSessions = (id) => Object.keys(readCursors(id).follows);
-const sameStatus = (a, b) => a.kind === 'status' && b.kind === 'status' && a.status === b.status
-    && (a.proposal ?? null) === (b.proposal ?? null) && (a.note ?? null) === (b.note ?? null);
-// @@@ edges, not lines - what a reader has not yet seen, with repeated status lines dropped. X→X IS NOT A
-// TRANSITION: the log is append-only and already holds runs of identical status lines from before the
-// timeline observer was deleted (every stray `spex serve` process ran an fs.watch over the same store and
-// re-recorded each real move, so ONE transition landed as up to 6 lines within ~200ms). Those bytes are
-// history and stay. Any consumer that decides "did it move?" must therefore compare VALUES, never adjacency,
-// and must compare against the last status the reader ALREADY saw — otherwise a duplicate straddling the
-// cursor boundary reads as a fresh move on the very next tick. `next` is where the cursor goes after consuming
-// the WHOLE slice: the full length, because a dropped duplicate is still consumed. `at[i]` is the absolute
-// index of `events[i]`, which is what lets a reader that STOPS on one event ([[session-follow]]'s take-one
-// wait) advance to exactly `at[i] + 1` and leave the lines behind it unread for the next reader.
-export function unreadSince(events, from) {
-    const start = Math.min(Math.max(0, Math.floor(from)), events.length);
-    let prev = null;
-    for (let i = start - 1; i >= 0; i--)
-        if (events[i].kind === 'status') {
-            prev = events[i];
-            break;
-        }
-    const out = [];
-    const at = [];
-    for (let i = start; i < events.length; i++) {
-        const e = events[i];
-        if (e.kind === 'status') {
-            if (prev && sameStatus(prev, e))
-                continue;
-            prev = e;
-        }
-        out.push(e);
-        at.push(i);
-    }
-    return { events: out, at, next: events.length };
-}

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

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

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

@@ -1,216 +0,0 @@
-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;
-    });
-}