@intx/inference 0.2.2 → 0.4.0

package/dist/reactor.js

@@ -13,6 +13,9 @@
 //
 // (INFERENCE.md § Agent Reactor)
 import { getLogger } from "@intx/log";
+import { ApprovalDecision, signalKindToGateType } from "@intx/types";
+import { canonicalJsonStringify } from "@intx/types/wire-definition-hash";
+import { type } from "arktype";
 import { runInference } from "./harness.js";
 import { createCapabilities } from "./director.js";
 import { createGateManager } from "./gates.js";
@@ -21,21 +24,64 @@ import { createStateManager } from "./state.js";
 import { validateActions } from "./actions.js";
 import { createToolResultTurn, createInboundTurn, assertWellFormedToolSequence, } from "./turns.js";
 const logger = getLogger(["interchange", "reactor"]);
-function buildHarnessOpts(turns, source, options, signal, nextSeq, deps) {
-    if (options !== undefined) {
-        return {
-            turns,
-            source,
-            inferenceOptions: options,
-            signal,
-            nextSeq,
-            deps,
-        };
-    }
-    return { turns, source, signal, nextSeq, deps };
+// Sentinel returned by a per-call tool run when a before-tool extension parked
+// the call on a gate. Distinct from every ToolResult so a suspended call is
+// excluded from the tool-result history append and from tool.done continuation.
+const SUSPENDED = Symbol("suspended");
+// Exhaustiveness guard for the resume-dispatch switch. A newly added
+// SignalKind or approval outcome that is not classified fails to type-check
+// here, so the switch cannot silently drop an unhandled case.
+function assertNever(x) {
+    throw new Error(`Unhandled resume case: ${JSON.stringify(x)}`);
+}
+function buildHarnessOpts(turns, source, options, signal, nextSeq, readMaterial, deps) {
+    // exactOptionalPropertyTypes is on: only set the optional keys when defined.
+    return {
+        turns,
+        source,
+        ...(options !== undefined ? { inferenceOptions: options } : {}),
+        signal,
+        nextSeq,
+        ...(readMaterial !== undefined ? { readMaterial } : {}),
+        deps,
+    };
 }
 const DEFAULT_GATE_TIMEOUT_MS = 3_600_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+const DEFAULT_DOOM_LOOP_THRESHOLD = 3;
+/**
+ * Resolve the caller-facing `doomLoopThreshold` into the reactor's internal
+ * form: a positive integer when detection is active, or `null` when it is
+ * disabled. `undefined` (omitted) takes the default; `false` disables; a
+ * number is validated here — the construction edge is the one place that owns
+ * the default and rejects a malformed value loudly, so a stray `0`, negative,
+ * or non-integer throws rather than silently disarming the guard. Downstream
+ * code compares against the returned `number | null` and never sees the raw
+ * `false`, whose numeric coercion would otherwise trip the loop immediately.
+ */
+function resolveDoomLoopThreshold(raw) {
+    if (raw === false)
+        return null;
+    if (raw === undefined)
+        return DEFAULT_DOOM_LOOP_THRESHOLD;
+    if (!Number.isInteger(raw) || raw < 1) {
+        throw new Error(`doomLoopThreshold must be a positive integer or false, got ${String(raw)}`);
+    }
+    return raw;
+}
+/**
+ * Order-independent identity of a batch of executed tool calls. Each call
+ * canonicalizes to its name and arguments (the call `id` is excluded, since it
+ * differs on every request); sorting makes a parallel batch match regardless
+ * of the order the model emitted its calls. Two turns share a signature when
+ * they run the same multiset of `(name, arguments)` pairs.
+ */
+function toolBatchSignature(calls) {
+    return calls
+        .map((call) => canonicalJsonStringify({ name: call.name, arguments: call.arguments }))
+        .sort()
+        .join("\n");
+}
 /**
  * Creates a reactor instance bound to the given configuration.
  * Call `start()` to begin the event loop.
@@ -49,6 +95,10 @@ export function createReactor(config) {
     failOverToNextSource = () => false, resetToPreferredSource = () => {
         /* single-source: nothing to reset */
     }, } = config;
+    // Resolved once at the construction edge: a positive integer while detection
+    // is active, or `null` when the caller disabled it with `false`. Every
+    // downstream comparison reads this binding, never the raw config value.
+    const doomLoopThreshold = resolveDoomLoopThreshold(config.doomLoopThreshold);
     // Monotonic sequence counter, scoped to this session.
     let seq = 0;
     function nextSeq() {
@@ -132,6 +182,10 @@ export function createReactor(config) {
     let running = false;
     let done = false;
     let shutdownStarted = false;
+    // Correlation state is empty until context loading and gate rehydration
+    // finish. Hold early deliveries so a resumed approval cannot be mistaken
+    // for a new conversation message during that startup window.
+    let startupDeliveries = [];
     // Per-message run-bracket state. Set when the loop dequeues a
     // message.received and begins per-message work; cleared at the
     // terminal point (wait/reply/done) or at a reactor-fatal abandon.
@@ -140,9 +194,22 @@ export function createReactor(config) {
     // produces unambiguous start/end pairs downstream.
     let currentMessageRunId = null;
     let currentMessageId = null;
+    // Doom-loop detection state, scoped to the current message run. Each executed
+    // tool-call turn is reduced to a batch signature; consecutive identical
+    // signatures accumulate here, and the run is broken when the count reaches
+    // `doomLoopThreshold`. This is run-scoped, not cycle-scoped: it resets only in
+    // `openMessageRun`, never in `resetCycleAccumulators`. It is also deliberately
+    // ephemeral (closure state, not persisted) -- a mid-run restart resets it to
+    // zero and the loop simply re-accumulates and trips a few turns later.
+    let lastToolBatchSignature = null;
+    let toolBatchRepeatCount = 0;
+    let lastToolBatchNames = [];
     function openMessageRun(messageId) {
         currentMessageRunId = crypto.randomUUID();
         currentMessageId = messageId;
+        lastToolBatchSignature = null;
+        toolBatchRepeatCount = 0;
+        lastToolBatchNames = [];
         emit({
             type: "message.run.started",
             seq: nextSeq(),
@@ -175,6 +242,10 @@ export function createReactor(config) {
     let cycleInferred = false;
     let cycleToolCallsExecuted = 0;
     let cycleCompactorName = null;
+    // A suspension registers a gate and may persist a pending operation. That is
+    // a durable state change even when the cycle ran no inference and completed
+    // no tool call, so it must force the cycle commit.
+    let cycleSuspended = false;
     // Director-supplied checkpoint message override; consumed exactly once.
     let pendingMessage = null;
     // AbortController for in-flight inference/tool operations.
@@ -197,6 +268,67 @@ export function createReactor(config) {
     // deliver() is fire-and-forget async, so two rapid delivers can interleave
     // across an await boundary in the validator, causing double-correlation.
     const correlatingIds = new Set();
+    // Decide how a correlated approval-kind pending operation resumes, granting
+    // any one-shot bypass synchronously so no delivery can interleave between the
+    // grant and the re-dispatch enqueued by the caller. An operation that carries
+    // a `suspendedCall` is an ask-flow suspension: the approver's decision routes
+    // it down the re-dispatch rail. An operation without one is an async-tool
+    // pending marker, which resumes on the normal gate-cleared rail.
+    //
+    // The nested switch is total: the outer `assertNever(op.kind)` rejects a
+    // future SignalKind at compile time, and the inner `assertNever` rejects a
+    // future decision outcome. A malformed decision body fails loud at the parse
+    // boundary before the switch.
+    function resumePendingOperation(op, message) {
+        if (op.suspendedCall === undefined) {
+            return { mode: "gate-cleared" };
+        }
+        const suspendedCall = op.suspendedCall;
+        if (message.content === undefined) {
+            throw new Error(`Correlated approval decision for ${op.correlationId} has no body to parse`);
+        }
+        let raw;
+        try {
+            raw = JSON.parse(message.content);
+        }
+        catch (cause) {
+            throw new Error(`Correlated approval decision for ${op.correlationId} is not valid JSON`, { cause });
+        }
+        const decision = ApprovalDecision(raw);
+        if (decision instanceof type.errors) {
+            throw new Error(`Correlated approval decision for ${op.correlationId} is malformed: ${decision.summary}`);
+        }
+        switch (op.kind) {
+            case "approval":
+                switch (decision.outcome) {
+                    case "approved":
+                        // Authorize the exact parked call to run once, then re-dispatch it.
+                        // Grant on every before-tool extension: only the authz extension
+                        // responds, but referencing it directly would re-couple the reactor
+                        // to authz and break a deployment that runs without it.
+                        for (const ext of beforeToolExtensions) {
+                            ext.grantOneShot?.(suspendedCall.id);
+                        }
+                        return { mode: "redispatch", calls: [suspendedCall] };
+                    case "rejected": {
+                        // The approver denied the call. Answer the parked call with a
+                        // synthetic error result rather than re-running it — no one-shot
+                        // bypass is granted, so the tool never executes. The approver's
+                        // reason, when present, is surfaced to the model verbatim.
+                        const content = "denied by approver" +
+                            (decision.message !== undefined ? `: ${decision.message}` : "");
+                        return {
+                            mode: "error_result",
+                            result: { callId: suspendedCall.id, content, isError: true },
+                        };
+                    }
+                    default:
+                        return assertNever(decision.outcome);
+                }
+            default:
+                return assertNever(op.kind);
+        }
+    }
     async function tryCorrelate(message) {
         const correlationId = message.headers.interchangeCorrelationId;
         if (correlationId === undefined)
@@ -222,19 +354,77 @@ export function createReactor(config) {
                 return false;
             }
         }
-        // Clear the gate associated with this correlation, if any.
-        const gate = gates.findByCorrelationId(correlationId);
-        if (gate !== undefined) {
-            gates.clear(gate.gateId);
+        // Capture the operation before removal so the resume dispatch can read its
+        // kind and suspended call. Removal happens only after the dispatch is
+        // decided, all inside this correlatingIds-guarded critical section so a
+        // double-deliver early-returns rather than double-dispatching.
+        const op = pending;
+        let dispatch;
+        try {
+            dispatch = resumePendingOperation(op, message);
         }
-        correlations.remove(correlationId);
-        if (stateManager !== null) {
-            stateManager.removePendingOperation(correlationId);
-            // Append the correlated message to conversation history so the model
-            // sees the response content when it re-infers after the gate clears.
-            const msg = createInboundTurn(message);
-            if (msg !== null) {
-                stateManager.appendTurn(msg);
+        catch (cause) {
+            correlatingIds.delete(correlationId);
+            throw cause;
+        }
+        const gate = gates.findByCorrelationId(correlationId);
+        switch (dispatch.mode) {
+            case "redispatch": {
+                // Clear the gate WITHOUT enqueuing gate.cleared: the re-dispatched call
+                // is the resumption, so a gate.cleared-driven re-infer would double the
+                // continuation. The re-dispatch's own tool.done drives the re-infer.
+                if (gate !== undefined) {
+                    gates.clearSilently(gate.gateId);
+                    if (stateManager !== null) {
+                        stateManager.setGatesSnapshot(gates.snapshot());
+                    }
+                }
+                correlations.remove(correlationId);
+                if (stateManager !== null) {
+                    stateManager.removePendingOperation(correlationId);
+                }
+                // The grant is already recorded (synchronously, in
+                // resumePendingOperation) with no await since; enqueue the re-dispatch
+                // so it runs on the loop with normal event ordering. The director seeds
+                // its outstanding-result count off this event before the call's
+                // tool.done arrives.
+                enqueue({ type: "resume.execute_tools", calls: dispatch.calls });
+                break;
+            }
+            case "error_result": {
+                // The approver denied the call. Clear the gate SILENTLY (like the
+                // approved redispatch) so it cannot also trip onGateCleared and enqueue
+                // a second continuation. The synthetic error result answers the parked
+                // call; the director appends it and re-infers once.
+                if (gate !== undefined) {
+                    gates.clearSilently(gate.gateId);
+                    if (stateManager !== null) {
+                        stateManager.setGatesSnapshot(gates.snapshot());
+                    }
+                }
+                correlations.remove(correlationId);
+                if (stateManager !== null) {
+                    stateManager.removePendingOperation(correlationId);
+                }
+                enqueue({ type: "resume.tool_result", result: dispatch.result });
+                break;
+            }
+            case "gate-cleared": {
+                // Async-tool resumption: clear the gate normally so the director
+                // re-infers, and append the correlated response to history so the model
+                // sees the content it was waiting on.
+                if (gate !== undefined) {
+                    gates.clear(gate.gateId);
+                }
+                correlations.remove(correlationId);
+                if (stateManager !== null) {
+                    stateManager.removePendingOperation(correlationId);
+                    const msg = createInboundTurn(message);
+                    if (msg !== null) {
+                        stateManager.appendTurn(msg);
+                    }
+                }
+                break;
             }
         }
         emit({
@@ -305,19 +495,11 @@ export function createReactor(config) {
             emitError(`writePrompt failed: ${cause instanceof Error ? cause.message : String(cause)}`, false);
         }
         const p = (async () => {
-            // Per-source attempt budget for transient errors (quota/retryable/
-            // timeout). Kept small because failover, not flogging one source, is
-            // the recovery path: the harness already does its own mechanical
-            // retry under each attempt, so this caps reactor-level same-source
-            // retries at one before moving to the next source.
-            const sameSourceAttempts = 2;
-            const defaultRetryMs = 60_000;
             // Each cycle starts at the most-preferred source; a failover in a
             // prior cycle must not leave the agent permanently demoted.
             resetToPreferredSource();
-            let attempt = 0;
             for (;;) {
-                const harnessOpts = buildHarnessOpts(prompt, config.source, options, signal, nextSeq, deps);
+                const harnessOpts = buildHarnessOpts(prompt, config.source, options, signal, nextSeq, config.readMaterial, deps);
                 let lastDone;
                 let lastError;
                 for await (const event of inferenceRunner(harnessOpts)) {
@@ -377,47 +559,17 @@ export function createReactor(config) {
                     enqueue({ type: "inference.error", error: err, partial });
                     return;
                 }
-                // A rate limit is the one category worth waiting out on the same
-                // source: it clears with time, and the reactor's backoff is longer
-                // than the harness's own per-call retry. The harness has already
-                // exhausted its internal mechanical retries for retryable/timeout
-                // by the time the reactor sees them, so those fail over rather than
-                // re-running the same source (which would just retry-compound).
-                if (err.category === "quota_exhausted") {
-                    attempt += 1;
-                    if (attempt < sameSourceAttempts && !signal.aborted) {
-                        const delayMs = err.retryAfterMs ?? defaultRetryMs;
-                        logger.warn `Rate limited, retrying same source after ${String(delayMs)}ms`;
-                        await new Promise((resolve) => {
-                            const timer = setTimeout(resolve, delayMs);
-                            const onAbort = () => {
-                                clearTimeout(timer);
-                                resolve();
-                            };
-                            signal.addEventListener("abort", onAbort, { once: true });
-                        });
-                        if (signal.aborted) {
-                            enqueue({
-                                type: "inference.error",
-                                error: {
-                                    category: "aborted",
-                                    message: "inference aborted during rate limit backoff",
-                                },
-                                partial,
-                            });
-                            return;
-                        }
-                        continue;
-                    }
-                }
-                // Same-source rate-limit budget exhausted, or a source-specific
-                // failure (credential, protocol mismatch, retryable, timeout): fail
-                // over to the next source. A pacing delay the leaving source asked
-                // for must not gate the next source.
+                // Any remaining error (quota, credential, protocol mismatch,
+                // retryable, timeout) is source-specific. The harness wrapper owns
+                // mechanical retry and has already exhausted it against this source
+                // by the time the reactor sees the error, including honoring a
+                // provider Retry-After for quota, so re-running the same source
+                // would only retry-compound. Fail over to the next source instead.
+                // A pacing delay the leaving source asked for must not gate the
+                // next source.
                 pendingPacingDelayMs = 0;
                 if (failOverToNextSource()) {
                     logger.warn `Failing over to next inference source after ${err.category}`;
-                    attempt = 0;
                     continue;
                 }
                 // No further source to fail over to: surface the last error.
@@ -434,21 +586,37 @@ export function createReactor(config) {
         const state = stateManager;
         const signal = operationController.signal;
         const runOne = async (call) => {
-            // Run before-tool extensions. First block or throw terminates the chain.
+            // Run before-tool extensions. The first non-allow decision terminates
+            // the chain: `block` answers the call with an error result, `suspend`
+            // parks it (no result, no tool.done).
             for (const ext of beforeToolExtensions) {
-                let blockReason;
+                let decision;
                 try {
-                    blockReason = await ext.beforeTool(call, state.snapshot(), signal);
+                    decision = await ext.beforeTool(call, state.snapshot(), signal);
                 }
                 catch (cause) {
                     const msg = cause instanceof Error ? cause.message : String(cause);
                     emitError(`BeforeToolExtension threw for ${call.name}: ${msg}`, false);
-                    blockReason = msg;
+                    decision = { type: "block", reason: msg };
                 }
-                if (blockReason !== undefined) {
+                if (decision.type === "suspend") {
+                    // Park the call: register the gate, persist the pending operation,
+                    // snapshot, and commit. The call is neither run nor answered — no
+                    // tool.start, no tool.done, no tool-result turn. The gate clears
+                    // when the correlated external decision is delivered.
+                    await suspendOnGate({
+                        gateType: decision.gate.type,
+                        gateId: decision.gate.gateId,
+                        timeoutMs: Math.max(1, decision.gate.timeoutAt - Date.now()),
+                        correlationId: decision.gate.correlationId,
+                        pendingOp: decision.pendingOp,
+                    });
+                    return SUSPENDED;
+                }
+                if (decision.type === "block") {
                     const blocked = {
                         callId: call.id,
-                        content: blockReason,
+                        content: decision.reason,
                         isError: true,
                     };
                     emit({
@@ -467,6 +635,10 @@ export function createReactor(config) {
                 const gateId = `pending-${marker.correlationId}`;
                 const op = {
                     correlationId: marker.correlationId,
+                    // Placeholder: async markers should carry their own SignalKind. The
+                    // resume switch keys on suspendedCall presence (absent here) as the
+                    // interim discriminator instead of on kind.
+                    kind: "approval",
                     registeredAt: Date.now(),
                     gateId,
                     ...(marker.expectedFrom !== undefined
@@ -489,22 +661,44 @@ export function createReactor(config) {
             }
             return current;
         };
-        let results;
+        let outcomes;
         if (parallel) {
             const p = Promise.all(calls.map((c) => runOne(c)));
             void track(p);
-            results = await p;
+            outcomes = await p;
         }
         else {
-            results = [];
+            outcomes = [];
             for (const call of calls) {
                 const p = runOne(call);
                 void track(p);
-                results.push(await p);
+                outcomes.push(await p);
             }
         }
+        // Suspended calls are parked, not answered: they contribute no tool
+        // result to history and no tool.done continuation event.
+        const results = outcomes.filter((o) => o !== SUSPENDED);
+        // Doom-loop accounting keys off the calls that actually ran, aligned to
+        // their outcome by index (both the parallel and serial paths above keep
+        // `outcomes` in `calls` order). A parked call contributes nothing, so a
+        // suspend-then-redispatch cycle counts its one real execution once. The
+        // loop reads `toolBatchRepeatCount` after this returns and breaks the run
+        // when it reaches the threshold. A `null` threshold means detection is
+        // disabled, so the accounting is skipped entirely.
+        const ranCalls = calls.filter((_call, i) => outcomes[i] !== SUSPENDED);
+        if (doomLoopThreshold !== null && ranCalls.length > 0) {
+            const signature = toolBatchSignature(ranCalls);
+            if (signature === lastToolBatchSignature) {
+                toolBatchRepeatCount += 1;
+            }
+            else {
+                lastToolBatchSignature = signature;
+                toolBatchRepeatCount = 1;
+            }
+            lastToolBatchNames = ranCalls.map((call) => call.name);
+        }
         cycleToolCallsExecuted += results.length;
-        if (addToHistory && stateManager !== null) {
+        if (addToHistory && stateManager !== null && results.length > 0) {
             stateManager.appendTurn(createToolResultTurn(results));
         }
         for (const result of results) {
@@ -558,6 +752,7 @@ export function createReactor(config) {
         cycleInferred = false;
         cycleToolCallsExecuted = 0;
         cycleCompactorName = null;
+        cycleSuspended = false;
     }
     async function commitCycle() {
         if (stateManager === null)
@@ -567,7 +762,8 @@ export function createReactor(config) {
         // no override) commits nothing.
         const hasWork = cycleInferred ||
             cycleToolCallsExecuted > 0 ||
-            cycleCompactorName !== null;
+            cycleCompactorName !== null ||
+            cycleSuspended;
         const hasOverride = pendingMessage !== null;
         if (!hasWork && !hasOverride) {
             resetCycleAccumulators();
@@ -606,6 +802,144 @@ export function createReactor(config) {
             tokenUsage: stateManager.getTokenUsage(),
         });
     }
+    let suspendingGate = null;
+    // Callback the gate manager invokes when a gate resolves, times out, or is
+    // shut down. Refreshes the snapshot and drives the loop's next step.
+    //
+    // A parked ask-flow approval that TIMES OUT ends without running its tool:
+    // it must be answered with a synthetic error result rather than left as a
+    // dangling tool_use. That path enqueues `resume.tool_result` INSTEAD OF
+    // `reactor.gate.cleared` — the two are mutually exclusive, because enqueuing
+    // both would drive two re-inferences for one timeout. Every other case (an
+    // async-marker pending op with no suspendedCall, no pending op at all, a
+    // `resolved`/`shutdown` reason, or a shutting-down reactor) keeps today's
+    // behavior: enqueue `reactor.gate.cleared` and let the director re-infer.
+    //
+    // A delivered `resolved` never reaches here on the ask rail — the redispatch
+    // and reject paths clear the gate silently (no onCleared) — so the timeout
+    // branch is gated on `reason === "timeout"` and shutdown stays on the plain
+    // path: a shutting-down reactor must not manufacture tool results.
+    function onGateCleared(gateId, reason) {
+        // A clear that fires while this gate's suspend is still committing must not
+        // take effect before `reactor.gate.blocked` is emitted. Record it and let
+        // suspendOnGate replay the full handler once the block is announced.
+        if (suspendingGate !== null &&
+            suspendingGate.gateId === gateId &&
+            suspendingGate.deferredClear === null) {
+            suspendingGate.deferredClear = { reason };
+            return;
+        }
+        if (stateManager !== null) {
+            stateManager.setGatesSnapshot(gates.snapshot());
+        }
+        if (reason === "timeout") {
+            const op = correlations.findByGateId(gateId);
+            if (op !== undefined && op.suspendedCall !== undefined) {
+                correlations.remove(op.correlationId);
+                if (stateManager !== null) {
+                    stateManager.removePendingOperation(op.correlationId);
+                }
+                enqueue({
+                    type: "resume.tool_result",
+                    result: {
+                        callId: op.suspendedCall.id,
+                        content: "approval timed out",
+                        isError: true,
+                    },
+                });
+                return;
+            }
+        }
+        emit({
+            type: "reactor.gate.cleared",
+            seq: nextSeq(),
+            data: { gateId, reason },
+        });
+        enqueue({ type: "reactor.gate.cleared", gateId, reason });
+    }
+    // Parks the reactor on a gate. Shared by the director's `suspend` action and
+    // the before-tool `suspend` decision so both paths register the gate,
+    // durably persist any pending operation, snapshot the active gates, and
+    // commit before returning to the loop — a suspended reactor's state must be
+    // durable across restart. When `pendingOp` is supplied its correlation is
+    // registered and it is persisted; the director path has already persisted
+    // its pending operation (via the tool's pending marker), so it passes none.
+    async function suspendOnGate(args) {
+        const { gateType, gateId, timeoutMs, correlationId, pendingOp } = args;
+        if (pendingOp !== undefined) {
+            correlations.register(pendingOp);
+            if (stateManager !== null) {
+                stateManager.addPendingOperation(pendingOp);
+            }
+        }
+        // Track this suspend as in flight so a clear racing the commit below is
+        // deferred until `reactor.gate.blocked` has been emitted.
+        const inFlightSuspend = { gateId, deferredClear: null };
+        suspendingGate = inFlightSuspend;
+        // Register the gate. onGateCleared enqueues the cleared event so the loop
+        // processes it normally without blocking here.
+        void gates.register(gateId, gateType, timeoutMs, correlationId, onGateCleared);
+        if (stateManager !== null) {
+            stateManager.setGatesSnapshot(gates.snapshot());
+        }
+        // Registering the gate (and any pending operation) is a durable state
+        // change that must be committed even if this cycle did no other work.
+        cycleSuspended = true;
+        // Commit before the loop continues so the suspended state is durable
+        // across restart.
+        await commitCycle();
+        // Emit `reactor.gate.blocked` only AFTER the commit. This event resolves
+        // the `send()` awaiter as "suspended", and a downstream consumer (the warm
+        // agent's run-boundary durability mirror) reads the pending operation back
+        // out of the just-committed context store the instant `send()` settles.
+        // Emitting before the commit would resolve `send()` first, letting that
+        // mirror read a store that has not yet persisted the pending op -- it would
+        // durably mirror an empty pending-operation set and lose the approval
+        // snapshot, so a parked correlation could not be re-registered after a hub
+        // reconnect. This upholds persist-before-settle: the durable commit the
+        // header promises before returning to the loop lands before the suspension
+        // settles.
+        emit({
+            type: "reactor.gate.blocked",
+            seq: nextSeq(),
+            data: {
+                reason: gateType,
+                gateId,
+                ...(correlationId !== undefined ? { correlationId } : {}),
+                ...(pendingOp?.approvalSnapshot !== undefined
+                    ? { approvalSnapshot: pendingOp.approvalSnapshot }
+                    : {}),
+            },
+        });
+        // The suspension is announced. If the gate cleared while the commit was in
+        // flight, its handler was deferred to keep it after `blocked`; replay it
+        // now, in order.
+        suspendingGate = null;
+        if (inFlightSuspend.deferredClear !== null) {
+            onGateCleared(gateId, inFlightSuspend.deferredClear.reason);
+        }
+    }
+    // Re-registers a live gate and correlation for each pending operation loaded
+    // from the context store on restart. The remaining timeout is computed from
+    // the persisted absolute deadline (`timeoutAt`) against the current clock, so
+    // the deadline is preserved across the restart rather than restarted; a
+    // deadline already in the past clamps to 1ms so the gate fires on the next
+    // tick. An operation persisted without a `timeoutAt` (hold-indefinitely) has
+    // no deadline to preserve; the gate manager cannot express an indefinite
+    // hold, so it is armed with the session-level `gateTimeout` — the same
+    // effective timeout the director-suspend fallback uses — rather than a
+    // silent zero. This does not run through `suspendOnGate`: rehydration must
+    // not re-emit `reactor.gate.blocked` (the suspension already happened before
+    // the restart) and must not commit (nothing changed).
+    function rehydrateGates(ops) {
+        for (const op of ops) {
+            const timeoutMs = op.timeoutAt !== undefined
+                ? Math.max(1, op.timeoutAt - Date.now())
+                : gateTimeout;
+            correlations.register(op);
+            void gates.register(op.gateId, signalKindToGateType(op.kind), timeoutMs, op.correlationId, onGateCleared);
+        }
+    }
     // -------------------------------------------------------------------------
     // Main loop
     // -------------------------------------------------------------------------
@@ -651,6 +985,17 @@ export function createReactor(config) {
                 }
                 openMessageRun(event.message.headers.messageId);
             }
+            // A parked approval that ended without running its tool (rejected or
+            // timed out) carries a synthetic error result answering the parked call.
+            // Land it in history before the director decides so the tool_result turn
+            // closes the dangling tool_use and the re-inference the director returns
+            // sees a well-formed sequence. No tool ran, so no tool.done and no
+            // counter change accompany it.
+            if (event.type === "resume.tool_result") {
+                if (stateManager !== null) {
+                    stateManager.appendTurn(createToolResultTurn([event.result]));
+                }
+            }
             let actions;
             try {
                 actions = await director.decide(event, stateManager.snapshot(), capabilities);
@@ -725,34 +1070,13 @@ export function createReactor(config) {
             const suspendAction = normalized.find((a) => a.type === "suspend");
             if (suspendAction !== undefined && suspendAction.type === "suspend") {
                 const { gate } = suspendAction;
-                const effectiveTimeout = gate.timeoutMs > 0 ? gate.timeoutMs : gateTimeout;
-                emit({
-                    type: "reactor.gate.blocked",
-                    seq: nextSeq(),
-                    data: { reason: gate.type, gateId: gate.gateId },
-                });
-                if (stateManager !== null) {
-                    stateManager.setGatesSnapshot(gates.snapshot());
-                }
-                // Register the gate. The onCleared callback enqueues the cleared event
-                // so the loop processes it normally without blocking here.
-                void gates.register(gate.gateId, gate.type, effectiveTimeout, gate.correlationId, (gateId, reason) => {
-                    if (stateManager !== null) {
-                        stateManager.setGatesSnapshot(gates.snapshot());
-                    }
-                    emit({
-                        type: "reactor.gate.cleared",
-                        seq: nextSeq(),
-                        data: { gateId, reason },
-                    });
-                    enqueue({ type: "reactor.gate.cleared", gateId, reason });
+                await suspendOnGate({
+                    gateType: gate.type,
+                    gateId: gate.gateId,
+                    timeoutMs: gate.timeoutMs > 0 ? gate.timeoutMs : gateTimeout,
+                    correlationId: gate.correlationId,
+                    pendingOp: undefined,
                 });
-                if (stateManager !== null) {
-                    stateManager.setGatesSnapshot(gates.snapshot());
-                }
-                // Commit before the loop continues so the suspended-state turns are
-                // durable across restart.
-                await commitCycle();
                 continue;
             }
             // Handle reply — emit the content for the harness/supervisor to send.
@@ -811,6 +1135,17 @@ export function createReactor(config) {
                 const parallel = toolsAction.parallel !== false;
                 const addToHistory = toolsAction.addToHistory !== false;
                 await executeTools(toolsAction.calls, parallel, addToHistory);
+                if (doomLoopThreshold !== null &&
+                    toolBatchRepeatCount >= doomLoopThreshold) {
+                    const tools = lastToolBatchNames.join(", ");
+                    const message = `Doom loop detected: an identical tool batch (${tools}) executed ` +
+                        `${String(doomLoopThreshold)} times consecutively`;
+                    emitError(message, true);
+                    closeMessageRun("failed", { message, kind: "doom_loop" });
+                    done = true;
+                    await initiateShutdown();
+                    break;
+                }
                 continue;
             }
             // No infer/tools/reply/suspend/wait/compact action — if a checkpoint
@@ -873,19 +1208,45 @@ export function createReactor(config) {
                 initialUsage = loaded.tokenUsage;
             }
             catch (cause) {
+                done = true;
+                startupDeliveries = null;
                 logger.error `Context store load failed: ${cause}`;
                 emitError(`Context store load failed: ${cause instanceof Error ? cause.message : String(cause)}`, true);
                 emit({ type: "reactor.done", seq: nextSeq(), data: {} });
                 return;
             }
             stateManager = createStateManager(sessionId, initialTurns, initialOps, initialUsage);
-            stateManager.setGatesSnapshot(gates.snapshot());
-            emit({ type: "reactor.start", seq: nextSeq(), data: {} });
             try {
+                // Re-arm gates for operations that were suspended before the restart.
+                // The state manager holds the loaded pending operations, but a gate is
+                // in-memory and does not survive a restart; without this a reloaded
+                // suspended agent is wedged (no live gate to clear, no correlation to
+                // match). Each op re-registers its correlation and a live gate keyed on
+                // the op's own gateId and correlationId, so a delivered signal clears
+                // it exactly as the original suspension would have.
+                //
+                // Rehydration runs inside this try/catch because the pending operations
+                // come from the context store — an untrusted external boundary — and
+                // correlation/gate registration throws synchronously on a duplicate
+                // correlationId or gateId. A throw must surface as reactor.error plus
+                // reactor.done (matching the load-failure path), not brick the reactor
+                // as a silent unhandled rejection.
+                rehydrateGates(initialOps);
+                stateManager.setGatesSnapshot(gates.snapshot());
+                emit({ type: "reactor.start", seq: nextSeq(), data: {} });
+                const bufferedDeliveries = startupDeliveries;
+                startupDeliveries = null;
+                if (bufferedDeliveries !== null) {
+                    for (const message of bufferedDeliveries) {
+                        processDelivery(message);
+                    }
+                }
                 await loop();
             }
             catch (cause) {
                 const msg = cause instanceof Error ? cause.message : String(cause);
+                done = true;
+                startupDeliveries = null;
                 logger.error `Reactor loop threw unexpectedly: ${cause}`;
                 emitError(`Internal reactor error: ${msg}`, true);
                 closeMessageRun("failed", {
@@ -898,11 +1259,30 @@ export function createReactor(config) {
             }
         })();
     }
-    function deliver(message) {
-        if (done)
-            return;
+    function processDelivery(message) {
         void (async () => {
-            const correlated = await tryCorrelate(message);
+            let correlated;
+            try {
+                correlated = await tryCorrelate(message);
+            }
+            catch (cause) {
+                // A correlation-path invariant failed (e.g. a malformed approval
+                // decision). Surface it as a fatal reactor error rather than a silent
+                // unhandled rejection, and stop the run — the resume cannot proceed on
+                // a decision the reactor cannot trust.
+                const msg = cause instanceof Error ? cause.message : String(cause);
+                logger.error `Correlation dispatch failed: ${cause}`;
+                emitError(`Correlation dispatch failed: ${msg}`, true);
+                closeMessageRun("failed", {
+                    message: `Correlation dispatch failed: ${msg}`,
+                    kind: "reactor_fatal",
+                });
+                done = true;
+                if (!shutdownStarted) {
+                    await initiateShutdown();
+                }
+                return;
+            }
             if (!correlated) {
                 emit({
                     type: "message.received",
@@ -913,7 +1293,21 @@ export function createReactor(config) {
             }
         })();
     }
+    function deliver(message) {
+        if (done)
+            return;
+        if (startupDeliveries !== null) {
+            startupDeliveries.push(message);
+            return;
+        }
+        processDelivery(message);
+    }
     function abort(reason) {
+        // The loop cannot dequeue the abort event while it is awaiting an active
+        // inference or tool batch. Signal that operation immediately so it can
+        // settle and return control to the loop, where the queued abort retains
+        // its priority over every other event.
+        operationController.abort();
         enqueue({ type: "abort", reason });
     }
     return { start, deliver, abort };