spexcode 0.6.5 → 0.6.6

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

@@ -3,7 +3,7 @@ export type PendingMessage = {
     text: string;
     from: string | null;
     dispatch?: {
-        operation: 'merge';
+        operation: string;
         requestDigest: string;
     };
 };

package/node_modules/@spexcode/{spec-cli → session-core}/dist/delivery-queue.js

@@ -1,6 +1,7 @@
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
 import { join } from 'node:path';
 import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from '@spexcode/spec-core';
+import { sentDispatchReceipt, settleSentDispatch } from './session-timeline.js';
 const queuePath = (id) => sessionArtifactPath(id, 'pending.json');
 const revokedSenderRoot = () => join(runtimeRoot(), '.revoked-senders');
 const revokedSenderPath = (id) => join(revokedSenderRoot(), id);
@@ -63,7 +64,7 @@ function read(id) {
             && typeof m.mid === 'string'
             && typeof m.text === 'string'
             && (m.dispatch === undefined
-                || (m.dispatch?.operation === 'merge'
+                || (typeof m.dispatch?.operation === 'string'
                     && typeof m.dispatch?.requestDigest === 'string')));
     }
     catch {
@@ -160,7 +161,22 @@ export async function drain(id, insert, timeoutMs = 5_000) {
             }
             let ok = false;
             try {
-                ok = await insert(queued[0]);
+                const head = queued[0];
+                if (head.dispatch) {
+                    const receipt = sentDispatchReceipt(id, head.dispatch.operation, head.dispatch.requestDigest);
+                    if (!receipt || receipt.mid !== head.mid || !receipt.delivery
+                        || receipt.delivery.text !== head.text || receipt.delivery.from !== head.from)
+                        return { delivered, remaining: queued.length };
+                    if (receipt.delivered)
+                        ok = true;
+                    else {
+                        ok = await insert(head);
+                        if (ok)
+                            settleSentDispatch(id, head.mid);
+                    }
+                }
+                else
+                    ok = await insert(head);
             }
             catch {
                 ok = false;

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

@@ -0,0 +1,5 @@
+export { acceptMessage, MessageKeyConflict, type AcceptMessageOptions, type MessageIdempotency, type PreparedMessage } from './message.js';
+export { drain, owesDelivery, pendingMessages, type PendingMessage } from './delivery-queue.js';
+export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionChildren, RuntimeSessionConflict, type RuntimeSessionRecord, type RuntimeSessionRegistration, type RuntimeSessionState, } from './runtime-session.js';
+export { advanceFollow, followedSessions, followCursor, readCursors, unreadSince, type Cursors } from './session-cursors.js';
+export { currentHumanTurn, lastHumanSendVia, recordStatus, timelineEvents, timelineStamp, timelineTail, type SessionTurn, type TimelineEvent, } from './session-timeline.js';

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

@@ -0,0 +1,5 @@
+export { acceptMessage, MessageKeyConflict } from './message.js';
+export { drain, owesDelivery, pendingMessages } from './delivery-queue.js';
+export { publishRuntimeSessionState, readRuntimeSession, registerRuntimeSession, runtimeSessionChildren, RuntimeSessionConflict, } from './runtime-session.js';
+export { advanceFollow, followedSessions, followCursor, readCursors, unreadSince } from './session-cursors.js';
+export { currentHumanTurn, lastHumanSendVia, recordStatus, timelineEvents, timelineStamp, timelineTail, } from './session-timeline.js';

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

@@ -0,0 +1,3 @@
+export { enqueue, ensurePendingWhileLocked, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, } from './delivery-queue.js';
+export { appendSent, sentDispatchReceipt, settleSentDispatch, type SentDispatchReceipt, type SentDispatchState, } from './session-timeline.js';
+export { trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLocks, withSessionRecordLockSync, } from './record-lock.js';

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

@@ -0,0 +1,3 @@
+export { enqueue, ensurePendingWhileLocked, pendingSnapshot, replacePendingWhileLocked, revokePendingFromWhileLocked, revokeSenderDelivery, senderDeliveryRevoked, withDeliveryLocks, } from './delivery-queue.js';
+export { appendSent, sentDispatchReceipt, settleSentDispatch, } from './session-timeline.js';
+export { trySessionRecordLockSync, withSessionRecordLock, withSessionRecordLocks, withSessionRecordLockSync, } from './record-lock.js';

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

@@ -0,0 +1,22 @@
+import { type SentDispatchReceipt } from './session-timeline.js';
+export type MessageIdempotency = SentDispatchReceipt;
+export type PreparedMessage = {
+    text: string;
+    replyVia?: 'note';
+};
+export type AcceptMessageOptions = {
+    target: string;
+    text: string;
+    from?: string;
+    idempotency?: MessageIdempotency;
+    validate?: () => Promise<void>;
+    prepare: () => Promise<PreparedMessage>;
+};
+export declare class MessageKeyConflict extends Error {
+    readonly code = "dispatch_key_reused";
+    constructor(operation: string);
+}
+export declare function acceptMessage(options: AcceptMessageOptions): Promise<{
+    mid: string;
+    replayed: boolean;
+}>;

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

@@ -0,0 +1,52 @@
+import { ensurePendingWhileLocked, enqueue, senderDeliveryRevoked, withDeliveryLocks } from './delivery-queue.js';
+import { appendSent, sentDispatchReceipt } from './session-timeline.js';
+import { withSessionRecordLocks } from './record-lock.js';
+export class MessageKeyConflict extends Error {
+    code = 'dispatch_key_reused';
+    constructor(operation) {
+        super(`idempotency key is already bound to another ${operation} payload`);
+        this.name = 'MessageKeyConflict';
+    }
+}
+const keyedPending = (receipt, mid, delivery) => ({
+    mid,
+    text: delivery.text,
+    from: delivery.from,
+    dispatch: { operation: receipt.operation, requestDigest: receipt.requestDigest },
+});
+// The durable acceptance boundary. Product validation and prompt composition run while the record fence is
+// held, but the package alone owns append + debt publication and keyed crash recovery.
+export async function acceptMessage(options) {
+    const from = options.from ?? null;
+    let result = null;
+    await withSessionRecordLocks([options.target, ...(from ? [from] : [])], async () => {
+        if (from && senderDeliveryRevoked(from))
+            throw new Error(`sender session ${from} is closed; prompt NOT delivered`);
+        await options.validate?.();
+        const accept = async () => {
+            if (options.idempotency) {
+                const prior = sentDispatchReceipt(options.target, options.idempotency.operation, options.idempotency.requestDigest);
+                if (prior) {
+                    if (prior.payloadHash !== options.idempotency.payloadHash)
+                        throw new MessageKeyConflict(options.idempotency.operation);
+                    if (prior.delivery && !prior.delivered)
+                        ensurePendingWhileLocked(options.target, keyedPending(options.idempotency, prior.mid, prior.delivery));
+                    result = { mid: prior.mid, replayed: true };
+                    return;
+                }
+            }
+            const prepared = await options.prepare();
+            const receipt = options.idempotency
+                ? { ...options.idempotency, delivery: { text: prepared.text, from } }
+                : undefined;
+            const { mid } = appendSent(options.target, options.text, from, prepared.replyVia, receipt);
+            enqueue(options.target, receipt ? keyedPending(receipt, mid, receipt.delivery) : { mid, text: prepared.text, from });
+            result = { mid, replayed: false };
+        };
+        if (options.idempotency)
+            await withDeliveryLocks([options.target], accept);
+        else
+            await accept();
+    });
+    return result;
+}

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

@@ -0,0 +1,7 @@
+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/session-core/dist/record-lock.js

@@ -0,0 +1,152 @@
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { runtimeRoot } from '@spexcode/spec-core';
+const lockRoot = () => join(runtimeRoot(), '.session-locks');
+const lockPath = (id) => join(lockRoot(), `${id}.lock`);
+const syncPause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+export class SessionRecordLockTimeout extends Error {
+    constructor(id) {
+        super(`session ${id}: lifecycle transition lock timed out; refusing a stale write`);
+        this.name = 'SessionRecordLockTimeout';
+    }
+}
+function acquireSync(id, timeoutMs = 30_000) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* another recovery already removed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new SessionRecordLockTimeout(id);
+            syncPause(10);
+        }
+    }
+}
+const aborted = (signal) => signal.reason instanceof Error
+    ? signal.reason
+    : Object.assign(new Error('The operation was aborted'), { name: 'AbortError', code: 'ABORT_ERR' });
+async function pause(signal) {
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        return;
+    }
+    if (signal.aborted)
+        throw aborted(signal);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(done, 10);
+        const abort = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); reject(aborted(signal)); };
+        function done() { signal.removeEventListener('abort', abort); resolve(); }
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}
+async function acquire(id, timeoutMs = 30_000, signal) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id), deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (signal?.aborted)
+            throw aborted(signal);
+        try {
+            const fd = openSync(path, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                unlinkSync(path);
+            }
+            catch { /* another recovery already removed it */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner = 0;
+            try {
+                owner = Number(readFileSync(path, 'utf8').trim()) || 0;
+            }
+            catch { /* race */ }
+            if (owner && owner !== process.pid) {
+                try {
+                    process.kill(owner, 0);
+                }
+                catch {
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch { /* race */ }
+                    ;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new SessionRecordLockTimeout(id);
+            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 = acquireSync(id);
+    try {
+        return body();
+    }
+    finally {
+        release();
+    }
+}
+export function trySessionRecordLockSync(id) {
+    mkdirSync(lockRoot(), { recursive: true });
+    const path = lockPath(id);
+    try {
+        const fd = openSync(path, 'wx');
+        writeSync(fd, String(process.pid));
+        closeSync(fd);
+        return () => { try {
+            unlinkSync(path);
+        }
+        catch { /* another recovery already removed it */ } };
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return null;
+        throw error;
+    }
+}
+export async function withSessionRecordLocks(rawIds, body, index = 0, ids = [...new Set(rawIds)].sort()) {
+    if (index >= ids.length)
+        return body();
+    return withSessionRecordLock(ids[index], () => withSessionRecordLocks(ids, body, index + 1, ids));
+}

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

@@ -0,0 +1,50 @@
+import { type SessionLifecycle, type SessionProposal } from '@spexcode/spec-core';
+export type RuntimeSessionRegistration = {
+    sessionId: string;
+    runtimeOwner: string;
+    worktreePath: string;
+    branch: string | null;
+    parentSessionId?: string | null;
+    title?: string | null;
+    node?: string | null;
+    runtimeMetadata?: Record<string, string>;
+    createdAt?: number;
+};
+export type RuntimeSessionState = {
+    sessionId: string;
+    runtimeOwner: string;
+    revision: string;
+    runtimeState: string;
+    lifecycle: SessionLifecycle;
+    proposal?: SessionProposal | null;
+    note?: string | null;
+};
+export type RuntimeSessionRecord = {
+    sessionId: string;
+    runtimeOwner: string;
+    runtimeState: string | null;
+    revision: string | null;
+    worktreePath: string;
+    branch: string | null;
+    parentSessionId: string | null;
+    title: string | null;
+    node: string | null;
+    runtimeMetadata: Record<string, string>;
+    lifecycle: SessionLifecycle;
+    proposal: SessionProposal | null;
+    note: string | null;
+    createdAt: number;
+};
+export declare class RuntimeSessionConflict extends Error {
+    readonly code = "runtime_session_conflict";
+    constructor(message: string);
+}
+export declare function registerRuntimeSession(input: RuntimeSessionRegistration): Promise<{
+    replayed: boolean;
+}>;
+export declare function publishRuntimeSessionState(input: RuntimeSessionState): Promise<{
+    notified: string[];
+    replayed: boolean;
+}>;
+export declare function readRuntimeSession(sessionId: string): RuntimeSessionRecord | null;
+export declare function runtimeSessionChildren(parentSessionId: string, runtimeOwner?: string): RuntimeSessionRecord[];

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

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