@jini-ai/daemon 0.6.8 → 0.6.9

package/dist/delegated-tool-bridge.js

@@ -1,3 +1,12 @@
+/**
+ * `DelegatedToolBridge` — the execution path for agents/protocols that ask
+ * Jini to run a registered tool on their behalf. It is deliberately separate
+ * from ACP's `session/request_permission`: ACP authorizes an agent's *native*
+ * tool loop, whereas this bridge invokes Jini's `ToolExecutor` and therefore
+ * enforces Jini's registry policy, confirmation, timeout, cancellation, and
+ * audit trail before any registered handler runs.
+ */
+import { batchOutcomeFor } from '@jini-ai/core';
 import { extractResultMedia } from './tool-result-media.js';
 import { splitToolResultSurfaces } from './tool-result-surfaces.js';
 /**
@@ -64,6 +73,147 @@ export function resultContent({ result }) {
             return result.error ?? 'Tool execution failed.';
     }
 }
+/**
+ * Builds the abort controller handed to `ToolExecutor`, aborted by either a run cancellation or the
+ * invocation's own transport signal. `dispose()` detaches both listeners once the call settles.
+ */
+function linkCancellation({ lifecycle, runId }, { signal }) {
+    const controller = new AbortController();
+    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => controller.abort() });
+    const abortFromTransport = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener('abort', abortFromTransport, { once: true });
+    return {
+        controller,
+        dispose: () => {
+            unsubscribeCancel();
+            signal?.removeEventListener('abort', abortFromTransport);
+        },
+    };
+}
+/**
+ * The seam a handler needs in order to show something it then WAITS on.
+ *
+ * Surfaces normally ride out in the return value and are split out below — which is useless to a
+ * handler that cannot return until the human has answered the very thing it wants to display.
+ * Emitting through here reaches the same run event stream, so a message pushed mid-call is
+ * indistinguishable to a renderer from one carried by the result.
+ *
+ * **Channel-neutral by construction.** The handler names its own channel, and this only injects
+ * correlation. That is what lets one seam drive `mcp-ui`, A2UI's multi-turn envelope
+ * (`createSurface` → `updateComponents` → …), the protocol's own `surface_request`/
+ * `surface_response` pair, or a channel invented later — none of which this file needs to know
+ * the shape of, matching `@jini-ai/protocol`'s own posture of typing each channel's body
+ * `unknown` and validating where the concrete type is known.
+ *
+ * Callable any number of times before the call settles; refused after. A handler that stashed
+ * this emitter could otherwise paint a surface onto a run whose `tool_result` is already on
+ * screen, with no call left to answer it.
+ */
+function createSurfaceSeam({ lifecycle, runId, toolUseId }) {
+    let settled = false;
+    // A handler emits a surface mid-call because it is about to WAIT on the human (a form, a card).
+    // Nothing reaches the run's event stream while they answer, so the slow-run watchdog would read
+    // that silence as a stall and post "Still working…" over an open form — which then reappears
+    // once the form is answered. Suspended from the first surface until the call settles (the
+    // `finally` below); the watchdog re-arms then, so a genuine stall afterwards is still caught.
+    let slowRunSuspended = false;
+    const emitSurface = async (emission) => {
+        if (settled)
+            throw new Error(`emitSurface: tool call ${toolUseId} has already completed`);
+        if (!slowRunSuspended) {
+            slowRunSuspended = true;
+            lifecycle.suspendSlowRunNotice({ runId: runId });
+        }
+        // Cast because `RunAgentPayload` is a closed union and `channel` is deliberately an open
+        // string — a seam that only accepts channels this file already knows about is not a
+        // channel-neutral seam. This mirrors `@jini-ai/protocol`'s own posture of typing each
+        // channel's BODY `unknown` and validating where the concrete type is known, applied one level
+        // up to the channel name itself.
+        //
+        // Blast radius of a bogus channel is bounded and worth stating: this path is human-only, so
+        // the failure mode is an event no renderer subscribes to — nothing rendered. It cannot put
+        // anything into model context, which is the property that would actually matter.
+        //
+        // That bound holds only for an UNKNOWN channel, which is why the spread order below matters.
+        // `payload` used to be spread LAST, so a handler could set `type` to a channel this bridge
+        // does know — `tool_result`, `mcp-ui` — and set `toolUseId` to a DIFFERENT call's, producing
+        // a well-formed forged event correlated against someone else's tool call. The cast is what
+        // let it past the closed `RunAgentPayload` union unnoticed. `SurfaceEmission.payload` is
+        // documented as "the channel's own fields, merged into the emitted event BESIDE `type`" —
+        // beside, not over — so both reserved keys are stripped rather than merely out-ordered.
+        // Stripping, not reordering: `correlationFor` returns `{}` for a channel that carries no
+        // `toolUseId`, so spread order alone would still let a payload smuggle one onto those.
+        const safePayload = { ...emission.payload };
+        delete safePayload['type'];
+        delete safePayload['toolUseId'];
+        const data = {
+            ...safePayload,
+            type: emission.channel,
+            ...correlationFor(emission.channel, toolUseId),
+        };
+        await lifecycle.emit({ runId: runId, input: { event: 'agent', data } });
+    };
+    /** Refuses every later emission: the call has a result. */
+    const settle = () => {
+        settled = true;
+    };
+    /** Re-arms the slow-run notice if a surface suspended it — run last, once the call's events are out. */
+    const release = () => {
+        if (slowRunSuspended)
+            lifecycle.resumeSlowRunNotice({ runId: runId });
+    };
+    return { emitSurface, settle, release };
+}
+/** Splits human-only surfaces out of an executed result, emits them, then the matching `tool_result`. */
+async function emitExecutedResult({ lifecycle, runId, toolUseId }, { executed }) {
+    // Recognized media blocks (images) are collected here purely to populate the sibling
+    // `media` field the `tool_result` event carries below, for a UI that wants to render one
+    // inline without re-parsing `content` (`ToolCard`'s `<img>`, per `assistant_demo_image`'s
+    // own doc). This does NOT remove the image block from `executed.output` — `image` is one
+    // of `tool-result-surfaces.ts`'s own `MODEL_VISIBLE_BLOCK_TYPES`, so the split below already
+    // keeps it in `modelOutput` on its own. An image reaching the model IS the point
+    // (`assistant_demo_image`/`admin.capture_screenshot` exist to prove exactly that round
+    // trip) — unlike an `mcp-ui` resource, which is genuinely human-only and must never survive
+    // into `modelOutput`. (Earlier this extraction fed its own de-imaged `remainder` into the
+    // surfaces split below and discarded the image from `output` entirely, on the assumption
+    // that the sibling `media` field was the only channel a caller needed — true for a UI
+    // reading the run's event stream, false for `@jini-ai/mcp`'s `execute_delegated_tool`, which
+    // hands the bridge's RETURN VALUE to the model with no access to that event stream at all.)
+    const { media } = extractResultMedia({ output: executed.output });
+    // THE MODEL/HUMAN FORK. A tool call's return value is definitionally what the model
+    // receives, so a UI resource left inside it is model-visible context no matter what any
+    // downstream layer does — `@jini-ai/mcp`'s `okResult()` JSON.stringifies the whole result
+    // into a single text block. This is the only point holding BOTH the raw result and the
+    // run's event stream, which is why the split happens here rather than later.
+    //
+    // Whitelist, not blacklist: only block types known to be model-safe survive into `output`;
+    // everything else is withheld and emitted for the human. See `tool-result-surfaces.ts` for
+    // why that direction is load-bearing.
+    const { modelOutput, surfaces } = splitToolResultSurfaces({ output: executed.output });
+    const result = surfaces.length === 0 ? executed : { ...executed, output: modelOutput };
+    // Emitted BEFORE `tool_result` so the surface is on screen by the time the transcript shows
+    // the call completing — otherwise the human is asked to confirm something not yet visible.
+    for (const surface of surfaces) {
+        await lifecycle.emit({ runId: runId, input: {
+                event: 'agent',
+                data: { type: MCP_UI_EVENT_TYPE, toolUseId, resource: surface },
+            } });
+    }
+    await lifecycle.emit({ runId: runId, input: {
+            event: 'agent',
+            data: {
+                type: 'tool_result',
+                toolUseId,
+                content: resultContent({ result }),
+                ...(result.status === 'completed' && (batchOutcomeFor({ output: result.output }) ?? 'completed') === 'completed' ? {} : { isError: true }),
+                ...(media.length > 0 ? { media } : {}),
+            },
+        } });
+    return result;
+}
 /**
  * Creates the transport-neutral bridge used by future ACP-delegate, MCP, or
  * other host protocols. This module does not invent a server transport: a
@@ -73,135 +223,26 @@ export function resultContent({ result }) {
 export function createDelegatedToolBridge(options) {
     const { lifecycle, toolExecutor } = options;
     async function execute(requiredArgs, optionalArgs = {}) {
+        // Merged rather than read from `optionalArgs` alone: a caller may hand `signal` in the first
+        // object (the delegated-tools HTTP route does), and it must still be honoured.
         const invocation = { ...requiredArgs, ...optionalArgs };
         const { runId, toolUseId, toolId, principal, input } = invocation;
+        const call = { lifecycle, runId, toolUseId };
         await lifecycle.emit({ runId: runId, input: {
                 event: 'agent',
                 data: { type: 'tool_use', id: toolUseId, name: toolId, input },
             } });
-        const controller = new AbortController();
-        const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => controller.abort() });
-        const abortFromTransport = () => controller.abort();
-        if (invocation.signal) {
-            if (invocation.signal.aborted)
-                controller.abort();
-            else
-                invocation.signal.addEventListener('abort', abortFromTransport, { once: true });
-        }
+        const cancellation = linkCancellation(call, invocation);
+        const seam = createSurfaceSeam(call);
         const run = { id: runId };
-        /**
-         * The seam a handler needs in order to show something it then WAITS on.
-         *
-         * Surfaces normally ride out in the return value and are split out below — which is useless to a
-         * handler that cannot return until the human has answered the very thing it wants to display.
-         * Emitting through here reaches the same run event stream, so a message pushed mid-call is
-         * indistinguishable to a renderer from one carried by the result.
-         *
-         * **Channel-neutral by construction.** The handler names its own channel, and this only injects
-         * correlation. That is what lets one seam drive `mcp-ui`, A2UI's multi-turn envelope
-         * (`createSurface` → `updateComponents` → …), the protocol's own `surface_request`/
-         * `surface_response` pair, or a channel invented later — none of which this file needs to know
-         * the shape of, matching `@jini-ai/protocol`'s own posture of typing each channel's body
-         * `unknown` and validating where the concrete type is known.
-         *
-         * Callable any number of times before the call settles; refused after. A handler that stashed
-         * this emitter could otherwise paint a surface onto a run whose `tool_result` is already on
-         * screen, with no call left to answer it.
-         */
-        let settled = false;
-        // A handler emits a surface mid-call because it is about to WAIT on the human (a form, a card).
-        // Nothing reaches the run's event stream while they answer, so the slow-run watchdog would read
-        // that silence as a stall and post "Still working…" over an open form — which then reappears
-        // once the form is answered. Suspended from the first surface until the call settles (the
-        // `finally` below); the watchdog re-arms then, so a genuine stall afterwards is still caught.
-        let slowRunSuspended = false;
-        const emitSurface = async (emission) => {
-            if (settled)
-                throw new Error(`emitSurface: tool call ${toolUseId} has already completed`);
-            if (!slowRunSuspended) {
-                slowRunSuspended = true;
-                lifecycle.suspendSlowRunNotice({ runId: runId });
-            }
-            // Cast because `RunAgentPayload` is a closed union and `channel` is deliberately an open
-            // string — a seam that only accepts channels this file already knows about is not a
-            // channel-neutral seam. This mirrors `@jini-ai/protocol`'s own posture of typing each
-            // channel's BODY `unknown` and validating where the concrete type is known, applied one level
-            // up to the channel name itself.
-            //
-            // Blast radius of a bogus channel is bounded and worth stating: this path is human-only, so
-            // the failure mode is an event no renderer subscribes to — nothing rendered. It cannot put
-            // anything into model context, which is the property that would actually matter.
-            //
-            // That bound holds only for an UNKNOWN channel, which is why the spread order below matters.
-            // `payload` used to be spread LAST, so a handler could set `type` to a channel this bridge
-            // does know — `tool_result`, `mcp-ui` — and set `toolUseId` to a DIFFERENT call's, producing
-            // a well-formed forged event correlated against someone else's tool call. The cast is what
-            // let it past the closed `RunAgentPayload` union unnoticed. `SurfaceEmission.payload` is
-            // documented as "the channel's own fields, merged into the emitted event BESIDE `type`" —
-            // beside, not over — so both reserved keys are stripped rather than merely out-ordered.
-            // Stripping, not reordering: `correlationFor` returns `{}` for a channel that carries no
-            // `toolUseId`, so spread order alone would still let a payload smuggle one onto those.
-            const safePayload = { ...emission.payload };
-            delete safePayload['type'];
-            delete safePayload['toolUseId'];
-            const data = {
-                ...safePayload,
-                type: emission.channel,
-                ...correlationFor(emission.channel, toolUseId),
-            };
-            await lifecycle.emit({ runId: runId, input: { event: 'agent', data } });
-        };
         try {
             try {
-                const executed = await toolExecutor.execute({ principal: principal, run: run, toolId: toolId, input: input }, { signal: controller.signal, emitSurface: emitSurface });
-                settled = true;
-                // Recognized media blocks (images) are collected here purely to populate the sibling
-                // `media` field the `tool_result` event carries below, for a UI that wants to render one
-                // inline without re-parsing `content` (`ToolCard`'s `<img>`, per `assistant_demo_image`'s
-                // own doc). This does NOT remove the image block from `executed.output` — `image` is one
-                // of `tool-result-surfaces.ts`'s own `MODEL_VISIBLE_BLOCK_TYPES`, so the split below already
-                // keeps it in `modelOutput` on its own. An image reaching the model IS the point
-                // (`assistant_demo_image`/`admin.capture_screenshot` exist to prove exactly that round
-                // trip) — unlike an `mcp-ui` resource, which is genuinely human-only and must never survive
-                // into `modelOutput`. (Earlier this extraction fed its own de-imaged `remainder` into the
-                // surfaces split below and discarded the image from `output` entirely, on the assumption
-                // that the sibling `media` field was the only channel a caller needed — true for a UI
-                // reading the run's event stream, false for `@jini-ai/mcp`'s `execute_delegated_tool`, which
-                // hands the bridge's RETURN VALUE to the model with no access to that event stream at all.)
-                const { media } = extractResultMedia({ output: executed.output });
-                // THE MODEL/HUMAN FORK. A tool call's return value is definitionally what the model
-                // receives, so a UI resource left inside it is model-visible context no matter what any
-                // downstream layer does — `@jini-ai/mcp`'s `okResult()` JSON.stringifies the whole result
-                // into a single text block. This is the only point holding BOTH the raw result and the
-                // run's event stream, which is why the split happens here rather than later.
-                //
-                // Whitelist, not blacklist: only block types known to be model-safe survive into `output`;
-                // everything else is withheld and emitted for the human. See `tool-result-surfaces.ts` for
-                // why that direction is load-bearing.
-                const { modelOutput, surfaces } = splitToolResultSurfaces({ output: executed.output });
-                const result = surfaces.length === 0 ? executed : { ...executed, output: modelOutput };
-                // Emitted BEFORE `tool_result` so the surface is on screen by the time the transcript shows
-                // the call completing — otherwise the human is asked to confirm something not yet visible.
-                for (const surface of surfaces) {
-                    await lifecycle.emit({ runId: runId, input: {
-                            event: 'agent',
-                            data: { type: MCP_UI_EVENT_TYPE, toolUseId, resource: surface },
-                        } });
-                }
-                await lifecycle.emit({ runId: runId, input: {
-                        event: 'agent',
-                        data: {
-                            type: 'tool_result',
-                            toolUseId,
-                            content: resultContent({ result }),
-                            ...(result.status === 'completed' ? {} : { isError: true }),
-                            ...(media.length > 0 ? { media } : {}),
-                        },
-                    } });
-                return result;
+                const executed = await toolExecutor.execute({ principal: principal, run: run, toolId: toolId, input: input }, { signal: cancellation.controller.signal, emitSurface: seam.emitSurface });
+                seam.settle();
+                return await emitExecutedResult(call, { executed });
             }
             catch (error) {
-                settled = true;
+                seam.settle();
                 await lifecycle.emit({ runId: runId, input: {
                         event: 'agent',
                         data: { type: 'tool_result', toolUseId, content: errorMessage(error), isError: true },
@@ -210,10 +251,8 @@ export function createDelegatedToolBridge(options) {
             }
         }
         finally {
-            unsubscribeCancel();
-            invocation.signal?.removeEventListener('abort', abortFromTransport);
-            if (slowRunSuspended)
-                lifecycle.resumeSlowRunNotice({ runId: runId });
+            cancellation.dispose();
+            seam.release();
         }
     }
     return { execute };

package/dist/event-log.d.ts

@@ -19,6 +19,26 @@
  */
 export type { EventLog, EventLogAppendInput, EventLogAppendOptions, EventLogEntry, EventLogReplayResult, } from '@jini-ai/protocol';
 import type { EventLog } from '@jini-ai/protocol';
+import { type SchedulerPort } from './scheduler.js';
+/**
+ * Default time a terminal run's full payloads stay in memory after its `'end'` entry before they are
+ * compacted down to that `'end'` entry alone. A finished run's in-memory log only has to cover a
+ * client reconnecting and replaying, which takes minutes; a host that needs the full history long
+ * term keeps a durable copy (a product transcript, or `@jini-ai/daemon/store/event-log/sqlite`).
+ * Without this, every event of every run since boot stayed on the heap — measured at 118 MB of a
+ * 430 MB daemon heap, mostly base64 screenshot tool results (memory investigation 2026-10-21).
+ * Each delegated tool result is held twice while retained: the bridge's own `tool_result` and the
+ * CLI's MCP-wrapped `tool_result` for the same call. They are not deduplicated here because their
+ * ids are uncorrelated (the MCP server mints a fresh `toolUseId` per call) and their content differs
+ * in shape, and hosts persist transcripts from this stream; this retention window bounds both.
+ */
+export declare const DEFAULT_TERMINAL_EVENT_RETENTION_MS: number;
+/**
+ * Default cap on runs held at all. Matches `RunLifecycle`'s own `DEFAULT_MAX_TERMINAL_RUNS`, so a
+ * terminal run record the lifecycle still retains can still replay its `'end'` entry. Only ended
+ * runs are ever evicted to honour it — see {@link InMemoryEventLogOptions.maxRuns}.
+ */
+export declare const DEFAULT_MAX_EVENT_LOG_RUNS = 1000;
 export interface InMemoryEventLogOptions {
     /**
      * Maximum entries retained per run before the oldest are evicted. Eviction is opt-in: if
@@ -30,6 +50,23 @@ export interface InMemoryEventLogOptions {
     readonly maxEntriesPerRun?: number;
     /** Host clock; defaults to Date.now to preserve recorded timestamps. */
     readonly now?: () => number;
+    /**
+     * How long after a run's `'end'` entry its other entries are kept before the run is compacted to
+     * that `'end'` entry alone (a replay from `null` then reports `truncated`; a reconnect cursor older
+     * than it reports `replay-gap`, both existing port outcomes). Any later append to the run (a
+     * `resume()`) cancels the pending compaction. `null` keeps every entry forever (the old behaviour).
+     * Defaults to {@link DEFAULT_TERMINAL_EVENT_RETENTION_MS}.
+     */
+    readonly terminalRetentionMs?: number | null;
+    /**
+     * Cap on runs held. Past it, the oldest *ended* runs are dropped entirely; a live run (no `'end'`
+     * yet, or resumed since) is never evicted to make room, so with more live runs than the cap the
+     * log holds every live run and no ended one. `null` disables the cap. Defaults to
+     * {@link DEFAULT_MAX_EVENT_LOG_RUNS}.
+     */
+    readonly maxRuns?: number | null;
+    /** Timer port for the compaction above; defaults to unref'd native timers, so it never keeps a process alive. */
+    readonly scheduler?: SchedulerPort;
 }
 /**
  * Reference `EventLog` implementation: a per-run FIFO array, optionally capped at
@@ -39,11 +76,17 @@ export interface InMemoryEventLogOptions {
  * durable copy — matching this task's scope (a real persistent adapter is `@jini-ai/daemon/store/event-log/sqlite`'s
  * job).
  *
+ * Memory is bounded by default: an ended run is compacted to its `'end'` entry after
+ * `terminalRetentionMs`, and at most `maxRuns` runs are held (ended ones evicted first).
+ *
  * @param options.maxEntriesPerRun - Retention cap per run, see {@link InMemoryEventLogOptions}.
+ * @param options.terminalRetentionMs - Post-`'end'` retention, see {@link InMemoryEventLogOptions}.
+ * @param options.maxRuns - Run cap, see {@link InMemoryEventLogOptions}.
  * @returns An `EventLog` port implementation.
  * @complexity `append`/`drop` are O(1) amortized (O(k) only on the eviction
- * splice, k = entries over cap, which is normally 1). `replay` is O(n) in
- * the number of retained entries for the run.
+ * splice, k = entries over cap, which is normally 1; the run-cap pass is O(1)
+ * per append once at the cap). `replay` is O(n) in the number of retained
+ * entries for the run.
  */
 export declare function createInMemoryEventLog(_requiredArgs: Record<string, never>, options?: InMemoryEventLogOptions): EventLog;
 //# sourceMappingURL=event-log.d.ts.map

package/dist/event-log.js

@@ -1,3 +1,42 @@
+import { createTimeoutScheduler } from './scheduler.js';
+/**
+ * The protocol event that closes a run (`RunLifecycle.finish()` appends it). Seeing it is how this
+ * in-memory log knows a run's payloads have become history rather than live output.
+ */
+const TERMINAL_EVENT = 'end';
+/**
+ * Default time a terminal run's full payloads stay in memory after its `'end'` entry before they are
+ * compacted down to that `'end'` entry alone. A finished run's in-memory log only has to cover a
+ * client reconnecting and replaying, which takes minutes; a host that needs the full history long
+ * term keeps a durable copy (a product transcript, or `@jini-ai/daemon/store/event-log/sqlite`).
+ * Without this, every event of every run since boot stayed on the heap — measured at 118 MB of a
+ * 430 MB daemon heap, mostly base64 screenshot tool results (memory investigation 2026-10-21).
+ * Each delegated tool result is held twice while retained: the bridge's own `tool_result` and the
+ * CLI's MCP-wrapped `tool_result` for the same call. They are not deduplicated here because their
+ * ids are uncorrelated (the MCP server mints a fresh `toolUseId` per call) and their content differs
+ * in shape, and hosts persist transcripts from this stream; this retention window bounds both.
+ */
+export const DEFAULT_TERMINAL_EVENT_RETENTION_MS = 15 * 60 * 1000;
+/**
+ * Default cap on runs held at all. Matches `RunLifecycle`'s own `DEFAULT_MAX_TERMINAL_RUNS`, so a
+ * terminal run record the lifecycle still retains can still replay its `'end'` entry. Only ended
+ * runs are ever evicted to honour it — see {@link InMemoryEventLogOptions.maxRuns}.
+ */
+export const DEFAULT_MAX_EVENT_LOG_RUNS = 1000;
+/**
+ * Shrinks an ended run to its newest entry (its `'end'`), keeping `nextId` so cursors stay valid.
+ * Dedupe keys pointing at a compacted entry are forgotten with it (no production caller passes a
+ * `dedupeKey` today); keeping them would keep the payloads alive.
+ */
+function compactRunLog(runLog) {
+    runLog.cancelCompaction = undefined;
+    runLog.entries.splice(0, runLog.entries.length - 1);
+    const retained = runLog.entries[0];
+    for (const [key, entry] of runLog.dedupeIndex) {
+        if (entry !== retained)
+            runLog.dedupeIndex.delete(key);
+    }
+}
 /**
  * Reference `EventLog` implementation: a per-run FIFO array, optionally capped at
  * `maxEntriesPerRun` (opt-in — see {@link InMemoryEventLogOptions}), functionally a ring
@@ -6,24 +45,62 @@
  * durable copy — matching this task's scope (a real persistent adapter is `@jini-ai/daemon/store/event-log/sqlite`'s
  * job).
  *
+ * Memory is bounded by default: an ended run is compacted to its `'end'` entry after
+ * `terminalRetentionMs`, and at most `maxRuns` runs are held (ended ones evicted first).
+ *
  * @param options.maxEntriesPerRun - Retention cap per run, see {@link InMemoryEventLogOptions}.
+ * @param options.terminalRetentionMs - Post-`'end'` retention, see {@link InMemoryEventLogOptions}.
+ * @param options.maxRuns - Run cap, see {@link InMemoryEventLogOptions}.
  * @returns An `EventLog` port implementation.
  * @complexity `append`/`drop` are O(1) amortized (O(k) only on the eviction
- * splice, k = entries over cap, which is normally 1). `replay` is O(n) in
- * the number of retained entries for the run.
+ * splice, k = entries over cap, which is normally 1; the run-cap pass is O(1)
+ * per append once at the cap). `replay` is O(n) in the number of retained
+ * entries for the run.
  */
 export function createInMemoryEventLog(_requiredArgs, options = {}) {
     const maxEntriesPerRun = options.maxEntriesPerRun;
     const now = options.now ?? Date.now;
+    const terminalRetentionMs = options.terminalRetentionMs === undefined ? DEFAULT_TERMINAL_EVENT_RETENTION_MS : options.terminalRetentionMs;
+    const maxRuns = options.maxRuns === undefined ? DEFAULT_MAX_EVENT_LOG_RUNS : options.maxRuns;
+    const scheduler = options.scheduler ?? createTimeoutScheduler({});
     const runs = new Map();
+    // Ended runs, oldest `'end'` first (Set insertion order): the only runs `enforceRunCap` may evict.
+    const endedRuns = new Set();
     function getOrCreateRunLog(runId) {
         let runLog = runs.get(runId);
         if (!runLog) {
-            runLog = { entries: [], nextId: 1, dedupeIndex: new Map() };
+            runLog = { entries: [], nextId: 1, dedupeIndex: new Map(), cancelCompaction: undefined };
             runs.set(runId, runLog);
         }
         return runLog;
     }
+    function removeRun(runId) {
+        runs.get(runId)?.cancelCompaction?.();
+        runs.delete(runId);
+        endedRuns.delete(runId);
+    }
+    /** Tracks whether `runId` is live or ended after appending `event`, arming the post-`'end'` compaction. */
+    function noteRunPhase(runId, runLog, event) {
+        runLog.cancelCompaction?.();
+        runLog.cancelCompaction = undefined;
+        endedRuns.delete(runId);
+        if (event !== TERMINAL_EVENT)
+            return;
+        endedRuns.add(runId);
+        if (terminalRetentionMs === null)
+            return;
+        runLog.cancelCompaction = scheduler.schedule({ delayMs: terminalRetentionMs, callback: () => compactRunLog(runLog) });
+    }
+    /** Drops the oldest ended runs until at most `maxRuns` remain, or no ended run is left to drop. */
+    function enforceRunCap() {
+        if (maxRuns === null)
+            return;
+        for (const runId of endedRuns) {
+            if (runs.size <= maxRuns)
+                return;
+            removeRun(runId);
+        }
+    }
     return {
         async append(input, options = {}) {
             const runLog = getOrCreateRunLog(input.runId);
@@ -47,6 +124,8 @@ export function createInMemoryEventLog(_requiredArgs, options = {}) {
             if (maxEntriesPerRun !== undefined && runLog.entries.length > maxEntriesPerRun) {
                 runLog.entries.splice(0, runLog.entries.length - maxEntriesPerRun);
             }
+            noteRunPhase(input.runId, runLog, input.event);
+            enforceRunCap();
             return entry;
         },
         async replay({ runId, afterCursor }) {
@@ -85,7 +164,7 @@ export function createInMemoryEventLog(_requiredArgs, options = {}) {
             return Array.from(runs.keys()).sort();
         },
         async drop({ runId }) {
-            runs.delete(runId);
+            removeRun(runId);
         },
     };
 }

package/dist/http/attachments.d.ts

@@ -236,6 +236,16 @@ export interface CreateDiskAttachmentStoreOptions {
      */
     readonly retainAcrossRestarts?: boolean;
 }
+/** The `ftyp` box's declared end offset (big-endian size at bytes 0-3), clamped to the bytes
+ * actually present so a truncated or size-inflating file can never push the brand scan past the
+ * captured signature window.
+ *
+ * Exported so its short-body bounds guard can be exercised directly: {@link hasAvifSignature}, its
+ * only caller, already requires 8 bytes before calling it, so no call through that path can reach
+ * the guard — but the guard is what keeps this function safe on its own and stays. */
+export declare function ftypBoxEnd({ body }: {
+    readonly body: Uint8Array;
+}, _optional?: Record<string, never>): number;
 /**
  * `true` when `body` opens with an ISO-BMFF `ftyp` box whose major brand or compatible-brand list
  * names AVIF. This is a line-for-line mirror of the CMS package's `content-type-sniffer.ts`
@@ -263,6 +273,9 @@ export interface AttachmentRecord {
     batchDirectory: string;
     dev: number;
     ino: number;
+    /** Absent only for legacy sidecars; filled after their first successful integrity check. */
+    mtimeMs?: number;
+    ctimeMs?: number;
     createdAt: number;
     claimedRunId?: string;
     /**
@@ -292,6 +305,8 @@ export interface RecordedAttachmentIdentity {
     readonly dev: number;
     readonly ino: number;
     readonly size: number;
+    readonly mtimeMs?: number;
+    readonly ctimeMs?: number;
 }
 /**
  * What the filesystem reports about a file right now — the subset of `fs.Stats` (plus `realpath`)
@@ -307,6 +322,8 @@ export interface ObservedAttachmentIdentity {
     readonly dev: number;
     readonly ino: number;
     readonly size: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
     /** `realpath` of the file — differs from its own path when any path component became a symlink. */
     readonly canonicalPath: string;
 }
@@ -316,7 +333,9 @@ export interface ObservedAttachmentIdentity {
  * Every condition is a distinct real attack: a regular file swapped for a symlink or directory, a
  * parent directory swapped for a symlink pointing elsewhere, the file replaced by a different file
  * at the same path (new inode), the same inode truncated or appended to (new size), or the path
- * now resolving onto a different device.
+ * now resolving onto a different device. Modification/change timestamps also detect same-size
+ * rewrites and replacement files whose inode was recycled. Legacy records lack timestamps and
+ * use their original identity checks until the first verified read establishes that baseline.
  *
  * Pure and exported on purpose. Staging a *device* change for a file that keeps its path is not
  * something a test can do on a real filesystem, and a check that can only be exercised in
@@ -357,6 +376,7 @@ export declare function reserveAttachmentRecords({ attachments, records, runId,
  * Throws without releasing `claimed`'s reservations; releasing is the caller's job (`claim`'s own
  * `catch`), so a rejected claim still leaves nothing half-claimed and the caller can retry with a
  * corrected set.
+ * Missing legacy timestamps are filled from the verified stat; adoption persists that baseline.
  *
  * Exported so the integrity and mixed-batch checks can be exercised directly against fabricated
  * records over real files on disk, without a full `createDiskAttachmentStore` around them.
@@ -445,12 +465,15 @@ export interface PersistedAttachmentRecord {
     readonly batchId: string;
     readonly dev: number;
     readonly ino: number;
+    readonly mtimeMs?: number;
+    readonly ctimeMs?: number;
     readonly createdAt: number;
     readonly ownerId?: string;
 }
 /**
  * Turns one sidecar's parsed JSON back into an `AttachmentRecord`, or `undefined` for anything that
  * is not a well-formed record naming a file inside its own batch directory.
+ * Legacy sidecars may lack timestamps; adoption verifies their recorded identity before backfill.
  *
  * `batchDirectory` is re-derived here and `filePath`'s containment is re-checked against it with
  * the same parent-equality test `register` uses — the two checks that make an adopted record no
@@ -477,6 +500,8 @@ export declare function attachmentSidecarFileName({ id }: {
  * file registration accepted. Anything failing any of those is deleted — sidecar first, then the
  * file it named, and the file ONLY when containment passed, so an unparseable sidecar can never
  * make this an arbitrary-file-delete primitive for whatever the daemon can unlink.
+ * Legacy records use their original identity checks before timestamps are backfilled atomically.
+ * A backfill write failure propagates before cleanup, preserving the attachment for a later retry.
  *
  * **The retention consequence, stated rather than assumed harmless.** Because `claimedRunId` is not
  * persisted (see {@link PersistedAttachmentRecord}), a file claimed by a run that died with the