@jini-ai/daemon 0.2.1 → 0.3.0

package/dist/run-lifecycle.js

@@ -56,6 +56,59 @@ function toRunEvent(runId, entry) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Reads the two run-level fields the kernel persists on a run's `'start'` entry. Both are absent
+ * on a log whose start entry carried a non-record payload (or no start entry at all).
+ */
+function readStartMetadata(startEntry) {
+    const startData = startEntry && isRecord(startEntry.data) ? startEntry.data : null;
+    return {
+        contextRef: typeof startData?.contextRef === 'string' ? startData.contextRef : undefined,
+        idempotencyKey: typeof startData?.idempotencyKey === 'string' ? startData.idempotencyKey : undefined,
+    };
+}
+/** Rebuilds the public status block for a rehydrated run from its first/last/start/end log entries. */
+function rehydratedStatus(runId, bounds) {
+    return {
+        id: runId,
+        state: bounds.terminal?.state ?? 'running',
+        startedAt: bounds.startEntry?.recordedAt ?? bounds.firstEntry.recordedAt,
+        updatedAt: bounds.lastEntry.recordedAt,
+        endedAt: bounds.endEntry?.recordedAt,
+    };
+}
+/**
+ * Rebuilds one in-memory `RunRecord` from a run's replayed durable entries. Volatile fields
+ * (listeners, subscribers, watchdog, in-flight promises) cannot survive a restart and are reset.
+ */
+function rehydratedRunRecord(runId, entries) {
+    const startEntry = entries.find((entry) => entry.event === 'start');
+    const endEntry = [...entries].reverse().find((entry) => entry.event === 'end');
+    const firstEntry = entries[0];
+    const lastEntry = entries[entries.length - 1];
+    const terminal = endEntry === undefined ? null : terminalStateFromEndEntry(endEntry);
+    const { contextRef, idempotencyKey } = readStartMetadata(startEntry);
+    return {
+        record: {
+            contextRef,
+            idempotencyKey,
+            status: rehydratedStatus(runId, { startEntry, endEntry, firstEntry, lastEntry, terminal }),
+            resumable: terminal?.resumable ?? false,
+            cancelRequested: false,
+            lastCancelRequest: undefined,
+            cancelListeners: new Set(),
+            subscribers: new Set(),
+            terminalWaiters: [],
+            terminalEndEntry: endEntry,
+            watchdog: undefined,
+            startPromise: undefined,
+            finishPromise: undefined,
+            retentionTimer: undefined,
+        },
+        idempotencyKey,
+        isTerminal: terminal !== null,
+    };
+}
 function terminalStateFromEndEntry(entry) {
     if (!isRecord(entry.data))
         return { state: 'failed', resumable: false };
@@ -63,18 +116,176 @@ function terminalStateFromEndEntry(entry) {
     const state = status === 'succeeded' ? 'succeeded' : status === 'canceled' ? 'cancelled' : 'failed';
     return { state, resumable: entry.data.resumable === true };
 }
+// ---------------------------------------------------------------------------
+// start()/stream() phase helpers
+//
+// `start()` and `stream()` were each over the complexity gate (cyclomatic 12/13,
+// cognitive 12/12). Both are broken up the same way: pure/near-pure pieces with
+// real branching extracted to named, independently-testable top-level functions
+// (typed against plain object shapes rather than the private `RunRecord`, so
+// they can be exported without leaking that internal type), leaving each method
+// itself a flat sequence with only its two or three irreducible guard clauses.
+// ---------------------------------------------------------------------------
+/**
+ * `start()`'s idempotency-replay lookup: the run id an existing `idempotencyKey` already maps to,
+ * or `undefined` when there is no key or no existing mapping (a fresh start proceeds normally).
+ * Pure.
+ */
+export function resolveIdempotentReplayRunId(idempotencyIndex, idempotencyKey) {
+    if (idempotencyKey === undefined)
+        return undefined;
+    return idempotencyIndex.get(idempotencyKey);
+}
+/** Registers `runId` under `idempotencyKey` in `idempotencyIndex` — a no-op when no key was supplied. */
+export function registerIdempotencyKeyIfPresent(idempotencyIndex, idempotencyKey, runId) {
+    if (idempotencyKey === undefined)
+        return;
+    idempotencyIndex.set(idempotencyKey, runId);
+}
+/**
+ * Removes `idempotencyKey`'s mapping from `idempotencyIndex`, but only when it still points at
+ * `runId` — used to roll back a failed durable `'start'` append without clobbering a different
+ * run that may have since claimed the same key (defensive; `start()`'s own locking makes that
+ * race unreachable today, but the check costs nothing and documents the invariant).
+ */
+export function clearIdempotencyIndexEntryIfMatching(idempotencyIndex, idempotencyKey, runId) {
+    if (idempotencyKey !== undefined && idempotencyIndex.get(idempotencyKey) === runId) {
+        idempotencyIndex.delete(idempotencyKey);
+    }
+}
+/**
+ * Default terminal-run retention window: how long a completed/failed/cancelled run's in-memory
+ * record stays readable via `get`/`list`/`stream`/`resume` before eviction. `runs.set()` never had
+ * a matching `runs.delete()` for a run that finishes normally — every terminal run's record was kept
+ * for the daemon process's entire lifetime, unbounded by run volume or uptime. Terminal runs are
+ * still read after they end (status polling, run-history listing, stream reconnects), so the fix
+ * cannot be "delete on completion" — this bounds *how long* a terminal record survives instead of
+ * deleting it immediately. 24h comfortably covers same-day polling/listing/reconnect without
+ * retaining every run a long-lived daemon ever processed.
+ */
+export const DEFAULT_TERMINAL_RETENTION_MS = 24 * 60 * 60 * 1000;
+/**
+ * Default hard cap on concurrently-retained terminal run records, independent of
+ * {@link DEFAULT_TERMINAL_RETENTION_MS} — the oldest terminal record is evicted once this is
+ * exceeded. A TTL alone does not bound memory when runs complete faster than they age out (a burst
+ * arriving within the retention window keeps growing); this cap gives a true worst-case bound
+ * regardless of arrival rate.
+ */
+export const DEFAULT_MAX_TERMINAL_RUNS = 1000;
+/**
+ * How long a just-terminal run should remain retained before its eviction timer fires: `retentionMs`
+ * minus however much of that window has already elapsed since `terminalAt`. Floored at `0` so a run
+ * that was already past its retention window when this is computed (relevant for `rehydrate()`,
+ * where a run may have gone terminal long before this process started) schedules an immediate
+ * eviction rather than a negative-delay timer. Pure.
+ */
+export function computeRetentionDelayMs(terminalAt, retentionMs, now) {
+    return Math.max(0, retentionMs - (now - terminalAt));
+}
+/** The durable `'start'` entry's payload — pure field mapping, split out of `start()` so its two optional-field spreads don't count toward that method's own complexity. */
+export function buildStartPayload(runId, startInput) {
+    return {
+        runId,
+        contextRef: startInput.contextRef,
+        ...(startInput.agentId !== undefined ? { agentId: startInput.agentId } : {}),
+        ...(startInput.idempotencyKey !== undefined ? { idempotencyKey: startInput.idempotencyKey } : {}),
+    };
+}
+/**
+ * Arms `record.watchdog` when `timeoutMs` is configured — a no-op otherwise. `record` is typed as a
+ * plain `{watchdog}` shape (not `Pick<RunRecord, 'watchdog'>`) purely so this function can be
+ * exported without naming the private `RunRecord` type in a public signature.
+ */
+export function armWatchdogIfConfigured(record, timeoutMs, onTimeout) {
+    if (timeoutMs === undefined)
+        return;
+    record.watchdog = createInactivityWatchdog({ timeoutMs, onTimeout });
+}
+/**
+ * `stream()`'s replay-delivery step: sends every already-durable entry to `onEvent`, returning the
+ * delivered eventIds so a caller can avoid re-delivering the same event from a different source
+ * (buffered live events observed during the replay, a terminal catch-up event). Pure aside from
+ * calling the injected `onEvent`.
+ */
+export function deliverReplayedEvents(runId, entries, onEvent) {
+    const deliveredEventIds = new Set();
+    for (const entry of entries) {
+        const event = toRunEvent(runId, entry);
+        deliveredEventIds.add(event.eventId);
+        onEvent(event);
+    }
+    return deliveredEventIds;
+}
+/**
+ * Delivers every event in `events` not already present in `deliveredEventIds`, marking each as
+ * delivered as it goes. Reused in `stream()` for both the buffered-live-event catch-up and the
+ * single terminal-event catch-up, so the "don't double-deliver" bookkeeping lives in one place.
+ */
+export function deliverUndeliveredEvents(events, deliveredEventIds, onEvent) {
+    for (const event of events) {
+        if (!deliveredEventIds.has(event.eventId)) {
+            deliveredEventIds.add(event.eventId);
+            onEvent(event);
+        }
+    }
+}
+/**
+ * Closes out a `stream()` subscription once replay and catch-up delivery are done: a terminal run's
+ * subscriber is removed immediately (no further event will ever come), a still-live run's stays
+ * registered behind the returned `unsubscribe`. `record` is typed as a plain `{subscribers}` shape
+ * for the same exportability reason as {@link armWatchdogIfConfigured}.
+ */
+export function finishStreamSubscription(record, subscriber, terminal) {
+    if (terminal) {
+        record.subscribers.delete(subscriber);
+        return { kind: 'ok', unsubscribe: () => { } };
+    }
+    return { kind: 'ok', unsubscribe: () => record.subscribers.delete(subscriber) };
+}
+/**
+ * Constructs a fresh in-memory `RunRecord` for a new `start()` call. Pure field mapping with no
+ * branches at all — not exported (would leak the private `RunRecord` type), kept as a named
+ * function purely so `start()` itself reads as "build the record, register it" rather than an
+ * 11-field literal inline.
+ */
+function buildNewRunRecord(startInput, runId, now) {
+    return {
+        contextRef: startInput.contextRef,
+        idempotencyKey: startInput.idempotencyKey,
+        status: { id: runId, state: 'running', startedAt: now, updatedAt: now, endedAt: undefined },
+        resumable: false,
+        cancelRequested: false,
+        lastCancelRequest: undefined,
+        cancelListeners: new Set(),
+        subscribers: new Set(),
+        terminalWaiters: [],
+        terminalEndEntry: undefined,
+        watchdog: undefined,
+        startPromise: undefined,
+        finishPromise: undefined,
+        retentionTimer: undefined,
+    };
+}
 /**
  * Creates the in-process `RunLifecycle` reference implementation.
  *
  * @param input.eventLog - The durable `EventLog` port this lifecycle appends to and replays from.
+ * @param input.terminalRetentionMs - See {@link CreateRunLifecycleInput.terminalRetentionMs}.
+ * @param input.maxTerminalRuns - See {@link CreateRunLifecycleInput.maxTerminalRuns}.
  * @returns A `RunLifecycle` backed by an in-memory run registry plus the injected `EventLog`.
- * @complexity Per-call complexities documented on each method; the registry itself is a `Map` keyed by `runId` (O(1) lookup).
+ * @complexity Per-call complexities documented on each method; the registry itself is a `Map` keyed by `runId` (O(1) lookup). Memory is bounded: non-terminal runs are O(n) in concurrently-live runs, and terminal runs are capped at `maxTerminalRuns` (each additionally bounded in retention time by `terminalRetentionMs`) rather than growing for the life of the process.
  * @overallScore 100/100
  */
 export function createRunLifecycle(input) {
     const { eventLog } = input;
+    const terminalRetentionMs = input.terminalRetentionMs ?? DEFAULT_TERMINAL_RETENTION_MS;
+    const maxTerminalRuns = input.maxTerminalRuns ?? DEFAULT_MAX_TERMINAL_RUNS;
     const runs = new Map();
     const idempotencyIndex = new Map();
+    // Terminal runIds in the order they were tracked (oldest first) — the LRU order `enforceTerminalCap`
+    // trims from. A run leaves this list exactly once, either via its retention timer firing or via
+    // `resume()` reclaiming it; see `evictTerminalRun`/`untrackTerminalRun`.
+    const terminalRunOrder = [];
     let hydration = null;
     function requireRun(runId) {
         const record = runs.get(runId);
@@ -106,6 +317,40 @@ export function createRunLifecycle(input) {
         notifySubscribers(record, runEvent);
         return runEvent;
     }
+    /** `start()`'s phase 2: appends the durable `'start'` entry, rolling back the in-memory record and idempotency-index entry on failure. */
+    async function appendStartOrRollback(runId, record, startInput) {
+        const startPayload = buildStartPayload(runId, startInput);
+        const startPromise = appendEvent(runId, record, 'start', startPayload).then(() => undefined);
+        record.startPromise = startPromise;
+        try {
+            await startPromise;
+            record.startPromise = undefined;
+        }
+        catch (error) {
+            runs.delete(runId);
+            clearIdempotencyIndexEntryIfMatching(idempotencyIndex, startInput.idempotencyKey, runId);
+            throw error;
+        }
+    }
+    /**
+     * Waits out a record's in-flight durable `'start'` append, swallowing its failure.
+     *
+     * The read-only queries (`get`/`list`) use this so they never observe the window in which the
+     * in-memory record exists but its durable `'start'` entry does not: a rejecting append unwinds the
+     * record entirely, so anything reported from inside that window is a run that never existed. The
+     * rejection itself belongs to `start()`'s own caller, which is why it is dropped here rather than
+     * propagated out of a query that was only asked "what runs are there".
+     */
+    async function settlePendingStart(record) {
+        if (record?.startPromise === undefined)
+            return;
+        try {
+            await record.startPromise;
+        }
+        catch {
+            // Reported to `start()`'s caller — see above.
+        }
+    }
     function resolveTerminalWaiters(record) {
         const waiters = record.terminalWaiters.splice(0, record.terminalWaiters.length);
         const status = toPublicStatus(record);
@@ -113,14 +358,84 @@ export function createRunLifecycle(input) {
             resolve(status);
         }
     }
+    function removeFromTerminalOrder(runId) {
+        const index = terminalRunOrder.indexOf(runId);
+        if (index !== -1)
+            terminalRunOrder.splice(index, 1);
+    }
+    /**
+     * Evicts a terminal run's in-memory record: drops it from `runs`, cleans its `idempotencyIndex`
+     * entry (a stale entry would otherwise resolve `start()`'s idempotency replay to a run
+     * `requireRun` can no longer find, turning a harmless re-post into a thrown error), and removes it
+     * from `terminalRunOrder`. Called from a retention timer firing or from `enforceTerminalCap`. A
+     * no-op if the run was already reclaimed by `resume()` (its timer is cancelled there) or evicted
+     * by the other path (cap eviction can race a timer for the same run — only the first wins,
+     * `runs.get` returns `undefined` for the second).
+     */
+    function evictTerminalRun(runId) {
+        removeFromTerminalOrder(runId);
+        const record = runs.get(runId);
+        if (!record)
+            return;
+        record.retentionTimer = undefined;
+        runs.delete(runId);
+        clearIdempotencyIndexEntryIfMatching(idempotencyIndex, record.idempotencyKey, runId);
+    }
+    /** Trims the oldest terminal records until `terminalRunOrder` is back at or under `maxTerminalRuns`. */
+    function enforceTerminalCap() {
+        while (terminalRunOrder.length > maxTerminalRuns) {
+            evictTerminalRun(terminalRunOrder[0]);
+        }
+    }
+    /**
+     * Arms `record`'s retention timer and enrolls it in `terminalRunOrder` — called once per run,
+     * right when it first becomes terminal (from `finish()`) or when an already-terminal run is
+     * rehydrated (from `rehydrateOne`). `terminalAt` is the real terminal timestamp (the durable
+     * `'end'` entry's `recordedAt`), not "now": a rehydrated run may have gone terminal long before
+     * this process started, and its remaining retention window must account for that instead of
+     * restarting the full window on every restart.
+     */
+    function trackTerminalRun(runId, record, terminalAt) {
+        terminalRunOrder.push(runId);
+        const delay = computeRetentionDelayMs(terminalAt, terminalRetentionMs, Date.now());
+        const timer = setTimeout(() => evictTerminalRun(runId), delay);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        record.retentionTimer = timer;
+        enforceTerminalCap();
+    }
+    /** Reverses `trackTerminalRun`: cancels the pending eviction and un-enrolls `runId`. Called from `resume()` so a reclaimed run cannot be evicted out from under its new, non-terminal life. */
+    function untrackTerminalRun(runId, record) {
+        removeFromTerminalOrder(runId);
+        if (record.retentionTimer) {
+            clearTimeout(record.retentionTimer);
+            record.retentionTimer = undefined;
+        }
+    }
     /**
      * Fires when a run's inactivity watchdog times out with no intervening
      * `emit()`/`finish()`. Classified as a resumable failure (`code: null,
      * signal: null`), mirroring OD's own timeout/inactivity classification
      * (`isResumableFailure` in the researched `run-failure-classification.ts`
      * treats timeout/inactivity as one of only two resumable categories).
-     * A run that already reached a terminal state before the timer fired
-     * (a normal race with `finish()`) is left untouched.
+     *
+     * The `!record || isTerminalRunState(...)` guard below is defensive only and is currently
+     * unreachable through the public API — deliberately kept, not fake-tested, and the reason is
+     * recorded here so the next reader does not spend time trying to cover it:
+     *
+     * - `isTerminalRunState(...)`: every route to a terminal state runs through `finish()`, which
+     *   calls `record.watchdog?.cancel()` and assigns `record.status.state` in the *same synchronous
+     *   block* after its durable end append resolves. There is no interleaving point between the two,
+     *   so "watchdog still armed" and "record already terminal" cannot both hold when this fires. (If
+     *   the end append *throws*, the watchdog stays armed but the run also stays non-terminal.)
+     * - `!record`: the only `runs.delete()` is `start()`'s unwind on a failed durable start append,
+     *   which happens strictly before the watchdog is armed a few lines later. It is also required
+     *   for type-narrowing `record` before `record.status.state` is read, so it cannot simply be
+     *   dropped.
+     *
+     * Note the "start/finish race" test below does *not* exercise this guard despite its name: by the
+     * time it advances the timers, `finish()` has already cancelled the watchdog, so the callback
+     * never runs at all. It still correctly asserts that no second `finish()` happens.
      */
     async function handleInactivityTimeout(runId) {
         const record = runs.get(runId);
@@ -149,6 +464,29 @@ export function createRunLifecycle(input) {
             }
         }
     }
+    /**
+     * Restores one run into the in-memory index from its durable log. Returns what the caller must do
+     * about it: `'skipped'` for a run already resident or with no usable log, otherwise whether the
+     * restored run was already terminal.
+     */
+    async function rehydrateOne(runId) {
+        if (runs.has(runId))
+            return 'skipped';
+        const replay = await eventLog.replay(runId, null);
+        if (replay.kind !== 'ok' || replay.entries.length === 0)
+            return 'skipped';
+        const { record, idempotencyKey, isTerminal } = rehydratedRunRecord(runId, replay.entries);
+        runs.set(runId, record);
+        if (idempotencyKey !== undefined)
+            idempotencyIndex.set(idempotencyKey, runId);
+        // `eventLog.listRunIds()` returns every run id the durable log has ever seen, with no bound of
+        // its own — without this, a restart would re-populate `runs` with the daemon's entire terminal
+        // run history on every boot, reproducing the same unbounded growth this module now guards
+        // against at runtime.
+        if (isTerminal)
+            trackTerminalRun(runId, record, record.status.endedAt ?? Date.now());
+        return isTerminal ? 'terminal' : 'non-terminal';
+    }
     const lifecycle = {
         async rehydrate() {
             if (hydration)
@@ -156,45 +494,9 @@ export function createRunLifecycle(input) {
             hydration = (async () => {
                 const rehydratedNonTerminalRunIds = [];
                 for (const runId of await eventLog.listRunIds()) {
-                    if (runs.has(runId))
-                        continue;
-                    const replay = await eventLog.replay(runId, null);
-                    if (replay.kind !== 'ok' || replay.entries.length === 0)
-                        continue;
-                    const entries = replay.entries;
-                    const startEntry = entries.find((entry) => entry.event === 'start');
-                    const endEntry = [...entries].reverse().find((entry) => entry.event === 'end');
-                    const startData = startEntry && isRecord(startEntry.data) ? startEntry.data : null;
-                    const firstEntry = entries[0];
-                    const lastEntry = entries[entries.length - 1];
-                    const terminal = endEntry === undefined ? null : terminalStateFromEndEntry(endEntry);
-                    const contextRef = typeof startData?.contextRef === 'string' ? startData.contextRef : undefined;
-                    const idempotencyKey = typeof startData?.idempotencyKey === 'string' ? startData.idempotencyKey : undefined;
-                    const record = {
-                        contextRef,
-                        status: {
-                            id: runId,
-                            state: terminal?.state ?? 'running',
-                            startedAt: startEntry?.recordedAt ?? firstEntry.recordedAt,
-                            updatedAt: lastEntry.recordedAt,
-                            endedAt: endEntry?.recordedAt,
-                        },
-                        resumable: terminal?.resumable ?? false,
-                        cancelRequested: false,
-                        lastCancelRequest: undefined,
-                        cancelListeners: new Set(),
-                        subscribers: new Set(),
-                        terminalWaiters: [],
-                        terminalEndEntry: endEntry,
-                        watchdog: undefined,
-                        startPromise: undefined,
-                        finishPromise: undefined,
-                    };
-                    runs.set(runId, record);
-                    if (idempotencyKey !== undefined)
-                        idempotencyIndex.set(idempotencyKey, runId);
-                    if (terminal === null)
+                    if (await rehydrateOne(runId) === 'non-terminal') {
                         rehydratedNonTerminalRunIds.push(runId);
+                    }
                 }
                 // A process restart cannot retain an in-memory child process or cancellation listener.
                 // Persist an honest terminal outcome instead of advertising an orphaned run as still live.
@@ -205,72 +507,42 @@ export function createRunLifecycle(input) {
             return hydration;
         },
         async start(startInput) {
-            if (startInput.idempotencyKey !== undefined) {
-                const existingRunId = idempotencyIndex.get(startInput.idempotencyKey);
-                if (existingRunId) {
-                    const existing = requireRun(existingRunId);
-                    await existing.startPromise;
-                    return { run: toPublicStatus(existing), started: false };
-                }
+            // Synchronous on purpose: `resolveIdempotentReplayRunId` does no I/O, and the common case
+            // (no idempotencyKey, or a fresh one) must reach `runs.set()` below in the same synchronous
+            // turn as this call — not after even one microtask tick — so a caller that races `finish()`
+            // in immediately after `start()` (before ever awaiting it) still finds the record `finish()`
+            // needs. Wrapping this check in its own `await`ed async function previously broke exactly
+            // that: an `async function` always defers its continuation by a microtask even when its body
+            // never itself awaits, which shifted `runs.set()` behind the racing `finish()` call.
+            const existingRunId = resolveIdempotentReplayRunId(idempotencyIndex, startInput.idempotencyKey);
+            if (existingRunId !== undefined) {
+                const existing = requireRun(existingRunId);
+                await existing.startPromise;
+                return { run: toPublicStatus(existing), started: false };
             }
             const runId = startInput.runId ?? randomUUID();
             if (runs.has(runId)) {
                 throw new Error(`RunLifecycle: run "${runId}" already exists`);
             }
-            const now = Date.now();
-            const record = {
-                contextRef: startInput.contextRef,
-                status: { id: runId, state: 'running', startedAt: now, updatedAt: now, endedAt: undefined },
-                resumable: false,
-                cancelRequested: false,
-                lastCancelRequest: undefined,
-                cancelListeners: new Set(),
-                subscribers: new Set(),
-                terminalWaiters: [],
-                terminalEndEntry: undefined,
-                watchdog: undefined,
-                startPromise: undefined,
-                finishPromise: undefined,
-            };
+            const record = buildNewRunRecord(startInput, runId, Date.now());
             runs.set(runId, record);
-            if (startInput.idempotencyKey !== undefined) {
-                idempotencyIndex.set(startInput.idempotencyKey, runId);
-            }
-            const startPayload = {
-                runId,
-                contextRef: startInput.contextRef,
-                ...(startInput.agentId !== undefined ? { agentId: startInput.agentId } : {}),
-                ...(startInput.idempotencyKey !== undefined ? { idempotencyKey: startInput.idempotencyKey } : {}),
-            };
-            const startPromise = appendEvent(runId, record, 'start', startPayload).then(() => undefined);
-            record.startPromise = startPromise;
-            try {
-                await startPromise;
-                record.startPromise = undefined;
-            }
-            catch (error) {
-                runs.delete(runId);
-                if (startInput.idempotencyKey !== undefined &&
-                    idempotencyIndex.get(startInput.idempotencyKey) === runId) {
-                    idempotencyIndex.delete(startInput.idempotencyKey);
-                }
-                throw error;
-            }
-            if (startInput.inactivityTimeoutMs !== undefined) {
-                record.watchdog = createInactivityWatchdog({
-                    timeoutMs: startInput.inactivityTimeoutMs,
-                    onTimeout: () => {
-                        void handleInactivityTimeout(runId);
-                    },
-                });
-            }
+            registerIdempotencyKeyIfPresent(idempotencyIndex, startInput.idempotencyKey, runId);
+            await appendStartOrRollback(runId, record, startInput);
+            armWatchdogIfConfigured(record, startInput.inactivityTimeoutMs, () => {
+                void handleInactivityTimeout(runId);
+            });
             return { run: toPublicStatus(record), started: true };
         },
         async get(runId) {
+            await settlePendingStart(runs.get(runId));
+            // Re-read rather than reusing the record above: a failed start deletes it (see `start()`'s
+            // unwind), and reporting a run whose durable `'start'` entry does not exist would advertise a
+            // run no restart could ever rehydrate.
             const record = runs.get(runId);
             return record ? toPublicStatus(record) : undefined;
         },
         async list(contextRef) {
+            await Promise.all(Array.from(runs.values(), settlePendingStart));
             const all = Array.from(runs.values());
             const filtered = contextRef === undefined ? all : all.filter((record) => record.contextRef === contextRef);
             return filtered.map(toPublicStatus);
@@ -343,6 +615,7 @@ export function createRunLifecycle(input) {
                 record.status.endedAt = endEntry.recordedAt;
                 record.resumable = finishInput.resumable;
                 record.terminalEndEntry = endEntry;
+                trackTerminalRun(finishInput.runId, record, endEntry.recordedAt);
                 const endEvent = toRunEvent(finishInput.runId, endEntry);
                 notifySubscribers(record, endEvent);
                 resolveTerminalWaiters(record);
@@ -364,6 +637,7 @@ export function createRunLifecycle(input) {
             if (!eligible) {
                 return { run: toPublicStatus(record), resumed: false };
             }
+            untrackTerminalRun(runId, record);
             const now = Date.now();
             record.status.state = 'running';
             record.status.updatedAt = now;
@@ -380,6 +654,12 @@ export function createRunLifecycle(input) {
         },
         async waitForTerminal(runId) {
             const record = requireRun(runId);
+            // Awaited (and *propagated*, unlike in `get`/`list`) before any waiter is registered. A run
+            // whose durable start append rejects is unwound, and nothing ever calls `finish()` for it — so
+            // a waiter parked inside that window would never be resolved by anyone. Failing the wait with
+            // the same error that failed the start is the only honest terminal answer, and awaiting first
+            // means `terminalWaiters` can only ever hold waiters for a run that really does exist.
+            await record.startPromise;
             if (isTerminalRunState(record.status.state)) {
                 return toPublicStatus(record);
             }
@@ -411,32 +691,14 @@ export function createRunLifecycle(input) {
                     record.subscribers.delete(subscriber);
                     return replay;
                 }
-                const deliveredEventIds = new Set();
-                for (const entry of replay.entries) {
-                    const event = toRunEvent(runId, entry);
-                    deliveredEventIds.add(event.eventId);
-                    onEvent(event);
-                }
-                for (const event of bufferedLiveEvents) {
-                    if (!deliveredEventIds.has(event.eventId)) {
-                        deliveredEventIds.add(event.eventId);
-                        onEvent(event);
-                    }
-                }
+                const deliveredEventIds = deliverReplayedEvents(runId, replay.entries, onEvent);
+                deliverUndeliveredEvents(bufferedLiveEvents, deliveredEventIds, onEvent);
                 replaying = false;
                 const terminal = isTerminalRunState(record.status.state);
                 if (terminal && record.terminalEndEntry) {
-                    const terminalEvent = toRunEvent(runId, record.terminalEndEntry);
-                    if (!deliveredEventIds.has(terminalEvent.eventId)) {
-                        deliveredEventIds.add(terminalEvent.eventId);
-                        onEvent(terminalEvent);
-                    }
-                }
-                if (terminal) {
-                    record.subscribers.delete(subscriber);
-                    return { kind: 'ok', unsubscribe: () => { } };
+                    deliverUndeliveredEvents([toRunEvent(runId, record.terminalEndEntry)], deliveredEventIds, onEvent);
                 }
-                return { kind: 'ok', unsubscribe: () => record.subscribers.delete(subscriber) };
+                return finishStreamSubscription(record, subscriber, terminal);
             }
             catch (error) {
                 // Subscription is installed before durable replay to close the replay→live race. Any