@abot-ai/runtime 1.6.0 → 1.7.0

package/dist/src/runtime/request/request-steering.js

@@ -1,4 +1,4 @@
-import { traceDebug } from "../observability/debug-logger.js";
+import { createRequestControlDiagnosticId, traceRequestControl, } from "../observability/request-control-diagnostics.js";
 export const REQUEST_STEERING_FEATURE = "request_steering_v1";
 export const REQUEST_STEERING_MESSAGE_KIND = "runtime_active_request_updates_v1";
 const LOG_SCOPE = "runtime.request_steering";
@@ -30,6 +30,10 @@ export function projectRequestSteeringSnapshot(inbox, version) {
     });
 }
 export function createRequestSteeringInbox(params) {
+    const diagnosticIdentity = {
+        inboxId: params.diagnostics?.inboxId ?? createRequestControlDiagnosticId("inbox"),
+        inboxOrigin: params.diagnostics?.origin ?? "request",
+    };
     const updates = [];
     const bySteerId = new Map();
     let closed = false;
@@ -37,6 +41,10 @@ export function createRequestSteeringInbox(params) {
     let persistenceBound = false;
     let persistUpdate;
     let persistenceTail = Promise.resolve();
+    traceRequestControl(LOG_SCOPE, "inbox.opened", {
+        ...diagnosticIdentity,
+        requestId: params.requestId,
+    });
     function schedulePersistence(update) {
         if (!persistUpdate)
             return;
@@ -44,7 +52,8 @@ export function createRequestSteeringInbox(params) {
         persistenceTail = persistenceTail.then(async () => {
             try {
                 await persist(update);
-                traceDebug(LOG_SCOPE, "update.persisted", {
+                traceRequestControl(LOG_SCOPE, "update.persisted", {
+                    ...diagnosticIdentity,
                     requestId: params.requestId,
                     steerId: update.steerId,
                     sequence: update.sequence,
@@ -52,7 +61,8 @@ export function createRequestSteeringInbox(params) {
                 });
             }
             catch (error) {
-                traceDebug(LOG_SCOPE, "update.persistence_failed", {
+                traceRequestControl(LOG_SCOPE, "update.persistence_failed", {
+                    ...diagnosticIdentity,
                     requestId: params.requestId,
                     steerId: update.steerId,
                     sequence: update.sequence,
@@ -66,8 +76,10 @@ export function createRequestSteeringInbox(params) {
             const steerId = input.steerId.trim();
             const text = input.text.trim();
             if (!steerId || !text) {
-                traceDebug(LOG_SCOPE, "update.rejected", {
+                traceRequestControl(LOG_SCOPE, "update.rejected", {
+                    ...diagnosticIdentity,
                     requestId: params.requestId,
+                    steerId,
                     reason: "invalid_steer_request",
                     steerIdLength: steerId.length,
                     textLength: text.length,
@@ -80,7 +92,8 @@ export function createRequestSteeringInbox(params) {
             const existing = bySteerId.get(steerId);
             if (existing) {
                 if (existing.text !== text) {
-                    traceDebug(LOG_SCOPE, "update.rejected", {
+                    traceRequestControl(LOG_SCOPE, "update.rejected", {
+                        ...diagnosticIdentity,
                         requestId: params.requestId,
                         steerId,
                         reason: "steer_id_conflict",
@@ -90,7 +103,8 @@ export function createRequestSteeringInbox(params) {
                         reason: "steer_id_conflict",
                     });
                 }
-                traceDebug(LOG_SCOPE, "update.duplicate", {
+                traceRequestControl(LOG_SCOPE, "update.duplicate", {
+                    ...diagnosticIdentity,
                     requestId: params.requestId,
                     steerId,
                     sequence: existing.sequence,
@@ -102,7 +116,8 @@ export function createRequestSteeringInbox(params) {
                 });
             }
             if (closed || sealed) {
-                traceDebug(LOG_SCOPE, "update.rejected", {
+                traceRequestControl(LOG_SCOPE, "update.rejected", {
+                    ...diagnosticIdentity,
                     requestId: params.requestId,
                     steerId,
                     reason: "request_not_active",
@@ -122,7 +137,8 @@ export function createRequestSteeringInbox(params) {
             updates.push(update);
             bySteerId.set(steerId, update);
             schedulePersistence(update);
-            traceDebug(LOG_SCOPE, "update.accepted", {
+            traceRequestControl(LOG_SCOPE, "update.accepted", {
+                ...diagnosticIdentity,
                 requestId: params.requestId,
                 steerId,
                 sequence: update.sequence,
@@ -144,7 +160,8 @@ export function createRequestSteeringInbox(params) {
             for (const update of updates) {
                 schedulePersistence(update);
             }
-            traceDebug(LOG_SCOPE, "persistence.bound", {
+            traceRequestControl(LOG_SCOPE, "persistence.bound", {
+                ...diagnosticIdentity,
                 requestId: params.requestId,
                 queuedUpdateCount: updates.length,
             });
@@ -156,8 +173,14 @@ export function createRequestSteeringInbox(params) {
             }
             closed = true;
             sealed = true;
+            traceRequestControl(LOG_SCOPE, "inbox.closing", {
+                ...diagnosticIdentity,
+                requestId: params.requestId,
+                updateCount: updates.length,
+            });
             await persistenceTail;
-            traceDebug(LOG_SCOPE, "inbox.closed", {
+            traceRequestControl(LOG_SCOPE, "inbox.closed", {
+                ...diagnosticIdentity,
                 requestId: params.requestId,
                 updateCount: updates.length,
             });
@@ -167,7 +190,8 @@ export function createRequestSteeringInbox(params) {
         },
         seal(version) {
             if (closed || sealed || updates.length !== version) {
-                traceDebug(LOG_SCOPE, "finalization.rejected", {
+                traceRequestControl(LOG_SCOPE, "finalization.rejected", {
+                    ...diagnosticIdentity,
                     requestId: params.requestId,
                     expectedVersion: version,
                     currentVersion: updates.length,
@@ -177,7 +201,8 @@ export function createRequestSteeringInbox(params) {
                 return false;
             }
             sealed = true;
-            traceDebug(LOG_SCOPE, "finalization.sealed", {
+            traceRequestControl(LOG_SCOPE, "finalization.sealed", {
+                ...diagnosticIdentity,
                 requestId: params.requestId,
                 version,
             });

package/dist/src/runtime/request/worker-capability-composition.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeModelPluginConfig } from "../config/model-plugin-config.js";
 import type { RuntimeFilesystemScope } from "../context/runtime-filesystem-scope.js";
 import type { RuntimeConfig, ToolRegistry } from "../ports.js";
 import type { ToolRequestAttachment } from "../../capabilities/tool-types.js";
@@ -10,6 +11,7 @@ type RequestWorkerCapabilityProviderParams<TRequest> = Readonly<{
     requestWorkingDirectory?: string;
     filesystemScope?: RuntimeFilesystemScope;
     executionPolicyAuthority?: ExecutionPolicyAuthoritySnapshot;
+    modelPlugins?: RuntimeModelPluginConfig;
     requestAttachments?: readonly ToolRequestAttachment[];
     runtimeConfig?: RuntimeConfig;
     toolRegistryOverride?: ToolRegistry;

package/dist/src/runtime/request/worker-capability-composition.js

@@ -16,6 +16,7 @@ export function createRequestWorkerCapabilityProvider(params) {
             request: params.request,
             requestWorkingDirectory: params.requestWorkingDirectory,
             toolPermissionMode: params.request.toolPermissionMode,
+            ...(params.modelPlugins ? { modelPlugins: params.modelPlugins } : {}),
             ...(params.requestAttachments
                 ? { requestAttachments: params.requestAttachments }
                 : {}),
@@ -41,7 +42,9 @@ export function createRequestWorkerCapabilityProvider(params) {
     const provider = createRegisteredToolWorkerCapabilityProvider({
         getRequestToolRegistry,
         requestId: params.request.requestId,
-        ...(params.request.toolResources ? { toolResources: params.request.toolResources } : {}),
+        ...(params.request.toolResources
+            ? { toolResources: params.request.toolResources }
+            : {}),
         sessionId: params.request.sessionId,
         requestContext: Object.freeze({
             agentMode: params.request.agentMode,

package/dist/src/runtime/scheduler/journal-index-state.d.ts

@@ -23,10 +23,10 @@ export declare function encodeJournalIndexState(state: JournalIndexState, genera
     runs: {
         file: string;
         id: string;
-        environmentId: string;
         status: import("./contracts.js").SchedulerRunStatus | "stopping" | "completed_with_skips";
         jobId: string;
         scheduledAt: string;
+        environmentId: string;
         jobRevision: number;
         target?: SchedulerStoredRun["target"];
         sessionId?: string;

package/dist/src/sessions/assistant-initiative-message.d.ts

@@ -0,0 +1,3 @@
+import type { SessionMessage } from "./types.js";
+/** Classification shared by persisted projections and model history. */
+export declare function isAssistantInitiativeMessage(message: SessionMessage): boolean;

package/dist/src/sessions/assistant-initiative-message.js

@@ -0,0 +1,12 @@
+/** Classification shared by persisted projections and model history. */
+export function isAssistantInitiativeMessage(message) {
+    if (message.role !== "assistant")
+        return false;
+    if (message.source !== "co_worker")
+        return false;
+    if (message.initiative?.kind !== "proactive_proposal_v1")
+        return false;
+    if (typeof message.initiative.proposalId !== "string")
+        return false;
+    return message.initiative.proposalId.length > 0;
+}

package/dist/src/sessions/assistant-initiative.d.ts

@@ -1,4 +1,5 @@
-import type { SessionMessage, SessionRecord } from "./types.js";
+import type { SessionRecord } from "./types.js";
+export { isAssistantInitiativeMessage } from "./assistant-initiative-message.js";
 export type AssistantInitiative = Readonly<{
     kind: "proactive_proposal_v1";
     proposalId: string;
@@ -26,5 +27,4 @@ export declare function createAssistantConversationRecord(options: {
     input: CreateAssistantConversationInput;
     now: Date;
 }): Promise<SessionRecord>;
-export declare function isAssistantInitiativeMessage(message: SessionMessage): boolean;
 export declare function assertAssistantInitiative(input: CreateAssistantConversationInput): void;

package/dist/src/sessions/assistant-initiative.js

@@ -1,6 +1,7 @@
 import { assertValidSessionId } from "./record/rules.js";
 import { deleteSessionFile, ensureSessionsDir, loadSessionFile, saveSessionFile } from "./session-store.js";
 import { isSparkHandoffBrief } from "./spark-handoff-brief.js";
+export { isAssistantInitiativeMessage } from "./assistant-initiative-message.js";
 /** Called under the same per-session mutation queue as edits and deletion. */
 export async function createAssistantConversationRecord(options) {
     const { sessionId, input } = options;
@@ -34,13 +35,6 @@ export async function createAssistantConversationRecord(options) {
     }
     return record;
 }
-export function isAssistantInitiativeMessage(message) {
-    if (message.role !== "assistant" || message.source !== "co_worker")
-        return false;
-    if (message.initiative?.kind !== "proactive_proposal_v1")
-        return false;
-    return typeof message.initiative.proposalId === "string" && message.initiative.proposalId.length > 0;
-}
 export function assertAssistantInitiative(input) {
     if (!input.title.trim() || input.title.length > 160)
         throw new Error("assistant_initiative_title_invalid");

package/dist/src/sessions/durable-session-commit.d.ts

@@ -1,4 +1,5 @@
 import type { SessionRecord } from "./types.js";
+import type { SessionMetadataChange } from "./metadata/source-receipt.js";
 export declare class SessionCommitOutcomeUnknownError extends Error {
     readonly sessionId: string;
     readonly code = "session_commit_outcome_unknown";
@@ -6,4 +7,4 @@ export declare class SessionCommitOutcomeUnknownError extends Error {
 }
 export declare function syncSessionDirectory(directory: string): Promise<void>;
 /** Same session file and replacement boundary, with explicit durable-commit errors. */
-export declare function saveDurableSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void): Promise<void>;
+export declare function saveDurableSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void, metadataChange?: SessionMetadataChange): Promise<void>;

package/dist/src/sessions/durable-session-commit.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { open, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
+import { currentSourceStamp, sessionSourceStamp, updateSessionMetadata } from "./metadata/store.js";
 export class SessionCommitOutcomeUnknownError extends Error {
     sessionId;
     code = "session_commit_outcome_unknown";
@@ -24,15 +25,18 @@ export async function syncSessionDirectory(directory) {
     }
 }
 /** Same session file and replacement boundary, with explicit durable-commit errors. */
-export async function saveDurableSessionFile(sessionsDir, session, assertCurrent) {
+export async function saveDurableSessionFile(sessionsDir, session, assertCurrent, metadataChange = "projection") {
     const target = join(sessionsDir, `${session.id}.json`);
+    const previousSource = metadataChange === "request-only" ? await currentSourceStamp(target) : undefined;
     const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
     let replaced = false;
+    let source;
     try {
         const handle = await open(temporary, "wx", 0o600);
         try {
             await handle.writeFile(JSON.stringify(session, null, 2), "utf8");
             await handle.sync();
+            source = sessionSourceStamp(await handle.stat({ bigint: true }));
         }
         finally {
             await handle.close();
@@ -48,4 +52,5 @@ export async function saveDurableSessionFile(sessionsDir, session, assertCurrent
             throw new SessionCommitOutcomeUnknownError(session.id, { cause: error });
         throw error;
     }
+    await updateSessionMetadata(sessionsDir, session, source, previousSource);
 }

package/dist/src/sessions/metadata/projection.d.ts

@@ -0,0 +1,15 @@
+import type { SessionListItem, SessionRecord, SessionSnapshotMessage } from "../types.js";
+export type SessionMessageMetadata = Pick<SessionSnapshotMessage, "id" | "role" | "createdAt">;
+/** Derived data only. User read cursors stay in the Web UI's existing store. */
+export type SessionMetadata = {
+    version: 1;
+    source: string;
+    interactive: boolean;
+    updatedAt: string;
+    summary: SessionListItem;
+    messages: SessionMessageMetadata[];
+};
+export declare function projectSessionMetadata(session: SessionRecord, source: string): SessionMetadata;
+export declare function isCurrentSessionMetadata(value: unknown, sessionId: string, source: string): value is SessionMetadata;
+/** Stable ordering is owned here so future paging need not change callers' storage knowledge. */
+export declare function compareSessionMetadata(left: SessionMetadata, right: SessionMetadata): number;

package/dist/src/sessions/metadata/projection.js

@@ -0,0 +1,55 @@
+import { hasAutomationSessionOrigin } from "../automation-session-origin.js";
+import { clientVisibleMessages, toEpochMs, toMessageIdForUi, toSessionListItem, } from "../record/projection.js";
+export function projectSessionMetadata(session, source) {
+    return {
+        version: 1,
+        source,
+        interactive: !hasAutomationSessionOrigin(session),
+        updatedAt: session.updatedAt,
+        summary: toSessionListItem(session),
+        messages: clientVisibleMessages(session.messages).map((message) => ({
+            id: toMessageIdForUi(message.id),
+            role: message.role,
+            createdAt: toEpochMs(message.createdAt),
+        })),
+    };
+}
+function isMessageMetadata(value) {
+    if (!value)
+        return false;
+    if (typeof value.id !== "string" && typeof value.id !== "number")
+        return false;
+    if (value.role !== "user" && value.role !== "assistant")
+        return false;
+    return Number.isFinite(value.createdAt);
+}
+export function isCurrentSessionMetadata(value, sessionId, source) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    if (record.version !== 1)
+        return false;
+    if (record.source !== source)
+        return false;
+    if (typeof record.interactive !== "boolean")
+        return false;
+    if (typeof record.updatedAt !== "string")
+        return false;
+    if (record.summary?.id !== sessionId)
+        return false;
+    if (typeof record.summary.title !== "string")
+        return false;
+    if (typeof record.summary.lastMessagePreview !== "string")
+        return false;
+    if (!Number.isFinite(record.summary.createdAt))
+        return false;
+    if (!Number.isFinite(record.summary.updatedAt))
+        return false;
+    if (!Array.isArray(record.messages))
+        return false;
+    return record.messages.every(isMessageMetadata);
+}
+/** Stable ordering is owned here so future paging need not change callers' storage knowledge. */
+export function compareSessionMetadata(left, right) {
+    return right.updatedAt.localeCompare(left.updatedAt) || left.summary.id.localeCompare(right.summary.id);
+}

package/dist/src/sessions/metadata/publication.d.ts

@@ -0,0 +1,12 @@
+import type { BigIntStats } from "node:fs";
+export declare function isMissingSessionFile(error: unknown): boolean;
+export declare function sessionSourceStamp(source: BigIntStats): string;
+export declare function currentSourceStamp(path: string): Promise<string | null>;
+export declare function reportMetadataFailure(sessionId: string, error: unknown): void;
+/** Only the derived index is expendable; canonical session read failures still propagate. */
+export declare function readMetadataJson(path: string): Promise<unknown>;
+/** Serialize index publication/deletion by session, never across unrelated sessions. */
+export declare function publishSessionMetadata(path: string, operation: () => Promise<void>): Promise<void>;
+/** List backfills and the Runtime owner may run in different processes. */
+export declare function publishSessionProjection(path: string, operation: () => Promise<void>): Promise<void>;
+export declare function writeMetadataJson(target: string, value: unknown, sourcePath: string, source: string): Promise<boolean>;

package/dist/src/sessions/metadata/publication.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { withFileLock } from "../../runtime/adapters/long-term-memory/file-lock.js";
+const pendingPublications = new Map();
+export function isMissingSessionFile(error) {
+    return error?.code === "ENOENT";
+}
+export function sessionSourceStamp(source) {
+    return `${source.dev}:${source.ino}:${source.size}:${source.mtimeNs}`;
+}
+export async function currentSourceStamp(path) {
+    try {
+        return sessionSourceStamp(await stat(path, { bigint: true }));
+    }
+    catch (error) {
+        if (isMissingSessionFile(error))
+            return null;
+        throw error;
+    }
+}
+export function reportMetadataFailure(sessionId, error) {
+    process.emitWarning(`Session metadata update failed for ${sessionId}: ${String(error)}`, {
+        code: "SESSION_METADATA_WRITE_FAILED",
+    });
+}
+/** Only the derived index is expendable; canonical session read failures still propagate. */
+export async function readMetadataJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isMissingSessionFile(error))
+            return null;
+        if (error instanceof SyntaxError)
+            return null;
+        reportMetadataFailure(path, error);
+        return null;
+    }
+}
+/** Serialize index publication/deletion by session, never across unrelated sessions. */
+export async function publishSessionMetadata(path, operation) {
+    const key = resolve(path);
+    const previous = pendingPublications.get(key) ?? Promise.resolve();
+    const pending = previous.then(operation).catch((error) => reportMetadataFailure(path, error));
+    pendingPublications.set(key, pending);
+    try {
+        await pending;
+    }
+    finally {
+        if (pendingPublications.get(key) === pending)
+            pendingPublications.delete(key);
+    }
+}
+/** List backfills and the Runtime owner may run in different processes. */
+export async function publishSessionProjection(path, operation) {
+    return publishSessionMetadata(path, async () => {
+        await mkdir(dirname(path), { recursive: true });
+        await withFileLock(`${path}.lock`, operation);
+    });
+}
+export async function writeMetadataJson(target, value, sourcePath, source) {
+    if (await currentSourceStamp(sourcePath) !== source)
+        return false;
+    await mkdir(dirname(target), { recursive: true });
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value), { encoding: "utf8", mode: 0o600 });
+        // Validate at publication too: the canonical file may change while writing the temporary.
+        if (await currentSourceStamp(sourcePath) !== source)
+            return false;
+        await rename(temporary, target);
+        return true;
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/src/sessions/metadata/source-receipt.d.ts

@@ -0,0 +1,5 @@
+import type { SessionMetadata } from "./projection.js";
+export type SessionMetadataChange = "projection" | "request-only";
+export declare function writeSourceReceipt(path: string, sourcePath: string, source: string, updatedAt: string, previousSource?: string): Promise<void>;
+/** Bind request-only changes to the exact projection they left unchanged. */
+export declare function applySourceReceipt(path: string, record: SessionMetadata, source: string): Promise<SessionMetadata | null>;

package/dist/src/sessions/metadata/source-receipt.js

@@ -0,0 +1,42 @@
+import { toEpochMs } from "../record/projection.js";
+import { readMetadataJson, writeMetadataJson } from "./publication.js";
+function isSourceReceipt(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const receipt = value;
+    if (receipt.version !== 1)
+        return false;
+    if (typeof receipt.source !== "string")
+        return false;
+    if (typeof receipt.projectionSource !== "string")
+        return false;
+    return typeof receipt.updatedAt === "string";
+}
+async function receiptProjectionSource(path, source, previousSource) {
+    if (previousSource === undefined)
+        return source;
+    const previous = await readMetadataJson(path);
+    if (!isSourceReceipt(previous))
+        return previousSource;
+    if (previous.source !== previousSource)
+        return previousSource;
+    return previous.projectionSource;
+}
+export async function writeSourceReceipt(path, sourcePath, source, updatedAt, previousSource) {
+    const projectionSource = await receiptProjectionSource(path, source, previousSource);
+    await writeMetadataJson(path, { version: 1, source, projectionSource, updatedAt }, sourcePath, source);
+}
+/** Bind request-only changes to the exact projection they left unchanged. */
+export async function applySourceReceipt(path, record, source) {
+    const receipt = await readMetadataJson(path);
+    if (!isSourceReceipt(receipt))
+        return null;
+    if (receipt.source !== source)
+        return null;
+    if (receipt.projectionSource !== record.source)
+        return null;
+    return {
+        ...record, source, updatedAt: receipt.updatedAt,
+        summary: { ...record.summary, updatedAt: toEpochMs(receipt.updatedAt) },
+    };
+}

package/dist/src/sessions/metadata/store.d.ts

@@ -0,0 +1,7 @@
+import type { SessionRecord } from "../types.js";
+import { type SessionMetadata } from "./projection.js";
+export { currentSourceStamp, sessionSourceStamp } from "./publication.js";
+/** The canonical session has already committed. A derived-index failure cannot undo it. */
+export declare function updateSessionMetadata(sessionsDir: string, session: SessionRecord, source: string, previousSource?: string | null): Promise<void>;
+export declare function deleteSessionMetadata(sessionsDir: string, sessionId: string): Promise<void>;
+export declare function listSessionMetadata(sessionsDir: string): Promise<SessionMetadata[]>;

package/dist/src/sessions/metadata/store.js

@@ -0,0 +1,119 @@
+import { mkdir, open, readdir, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { compareSessionMetadata, isCurrentSessionMetadata, projectSessionMetadata, } from "./projection.js";
+import { currentSourceStamp, isMissingSessionFile, publishSessionMetadata, publishSessionProjection, readMetadataJson, reportMetadataFailure, sessionSourceStamp, writeMetadataJson, } from "./publication.js";
+import { applySourceReceipt, writeSourceReceipt } from "./source-receipt.js";
+export { currentSourceStamp, sessionSourceStamp } from "./publication.js";
+const pendingLists = new Map();
+const concurrentMetadataReads = 4;
+function metadataPath(sessionsDir, sessionId) {
+    return join(sessionsDir, ".metadata", `${sessionId}.json`);
+}
+async function writeMetadata(sessionsDir, record) {
+    const target = metadataPath(sessionsDir, record.summary.id);
+    const sourcePath = join(sessionsDir, `${record.summary.id}.json`);
+    await publishSessionProjection(target, async () => {
+        if (!await writeMetadataJson(target, record, sourcePath, record.source))
+            return;
+        // The full projection already carries its source; only request-only changes need a receipt.
+        await rm(`${target}.source`, { force: true });
+    });
+}
+/** The canonical session has already committed. A derived-index failure cannot undo it. */
+export async function updateSessionMetadata(sessionsDir, session, source, previousSource) {
+    if (previousSource) {
+        const target = metadataPath(sessionsDir, session.id);
+        return publishSessionMetadata(target, () => writeSourceReceipt(`${target}.source`, join(sessionsDir, `${session.id}.json`), source, session.updatedAt, previousSource));
+    }
+    try {
+        await writeMetadata(sessionsDir, projectSessionMetadata(session, source));
+    }
+    catch (error) {
+        reportMetadataFailure(session.id, error);
+    }
+}
+export async function deleteSessionMetadata(sessionsDir, sessionId) {
+    const target = metadataPath(sessionsDir, sessionId);
+    await publishSessionProjection(target, async () => {
+        await rm(target, { force: true });
+        await rm(`${target}.source`, { force: true });
+    });
+}
+async function readSourceMetadata(path) {
+    const handle = await open(path, "r").catch((error) => {
+        if (isMissingSessionFile(error))
+            return null;
+        throw error;
+    });
+    if (!handle)
+        return null;
+    try {
+        const source = sessionSourceStamp(await handle.stat({ bigint: true }));
+        const session = JSON.parse(await handle.readFile("utf8"));
+        return projectSessionMetadata(session, source);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readCurrentMetadata(target, sessionId, source) {
+    const stored = await readMetadataJson(target);
+    if (isCurrentSessionMetadata(stored, sessionId, source))
+        return stored;
+    const projectionSource = stored?.source;
+    if (typeof projectionSource !== "string")
+        return null;
+    if (!isCurrentSessionMetadata(stored, sessionId, projectionSource))
+        return null;
+    return applySourceReceipt(`${target}.source`, stored, source);
+}
+async function loadMetadata(sessionsDir, sessionId) {
+    const path = join(sessionsDir, `${sessionId}.json`);
+    const source = await currentSourceStamp(path);
+    if (source === null)
+        return null;
+    const current = await readCurrentMetadata(metadataPath(sessionsDir, sessionId), sessionId, source);
+    if (current)
+        return current;
+    const rebuilt = await readSourceMetadata(path);
+    if (!rebuilt)
+        return null;
+    await writeMetadata(sessionsDir, rebuilt);
+    return rebuilt;
+}
+function settledMetadata(result) {
+    if (result.status === "rejected")
+        throw result.reason;
+    return result.value;
+}
+/**
+ * Each atomically published record completes its own backfill. Restarts reuse
+ * those records; interrupted backfills only rebuild missing/stale entries.
+ * Source stamps also detect older writers and a crash between the two commits.
+ */
+async function readMetadataList(sessionsDir) {
+    await mkdir(sessionsDir, { recursive: true });
+    const names = (await readdir(sessionsDir)).filter((name) => name.endsWith(".json"));
+    const records = [];
+    for (let offset = 0; offset < names.length; offset += concurrentMetadataReads) {
+        // Bound disk fan-out and drain the batch before propagating a canonical read failure.
+        const batch = await Promise.allSettled(names.slice(offset, offset + concurrentMetadataReads)
+            .map((name) => loadMetadata(sessionsDir, name.slice(0, -5))));
+        records.push(...batch.map(settledMetadata).filter((record) => record !== null));
+    }
+    return records.sort(compareSessionMetadata);
+}
+export async function listSessionMetadata(sessionsDir) {
+    const directory = resolve(sessionsDir);
+    const existing = pendingLists.get(directory);
+    if (existing)
+        return existing;
+    const pending = readMetadataList(directory);
+    pendingLists.set(directory, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        pendingLists.delete(directory);
+    }
+}

package/dist/src/sessions/record/projection.d.ts

@@ -7,10 +7,12 @@ export declare function normalizeAfterSeq(afterSeq: number): number;
 export declare function toEpochMs(timestamp: string): number;
 export declare function toClientReplayEvent(event: SessionRuntimeEvent): Record<string, unknown>;
 export declare function getRequestFinalState(request: SessionRequestRecord): SessionRequestReplay["finalState"];
+export declare function toMessageIdForUi(id: string): string | number;
 export declare function isSameMessageId(messageId: string, requestedId: string): boolean;
 export declare function filterMessagesAfter(messages: SessionRecord["messages"], afterMessageId: string | number | null | undefined): SessionRecord["messages"];
 export declare function clientVisibleMessages(messages: SessionRecord["messages"]): SessionRecord["messages"];
-export declare function toSnapshotMessage(sessionId: string, message: SessionRecord["messages"][number], requests: SessionRequestRecord[]): SessionSnapshotMessage;
+export declare function toSnapshotMessage(sessionId: string, message: SessionRecord["messages"][number], requests: SessionRequestRecord[], resolveRequestId?: (message: SessionRecord["messages"][number]) => string | null): SessionSnapshotMessage;
+export declare function createMessageRequestIdResolver(requests: SessionRequestRecord[]): (message: SessionRecord["messages"][number]) => string | null;
 export declare function toSnapshotRequest(request: SessionRequestRecord): SessionSnapshotRequest;
 export declare function normalizeSessionTitle(title: string): string;
 export declare function toSessionListItem(session: SessionRecord): {