@agent-native/core 0.153.4 → 0.153.6

package/dist/agent/production-agent.js

@@ -2439,6 +2439,13 @@ async function waitForInterruptedToolLedgerEntry(opts) {
  * Dropping the echoed input costs nothing: the fault is already named by the
  * sentence before it, and two failures that differ ONLY in the arguments they
  * echo are the same failure.
+ *
+ * Digits stay. Collapsing them merges failures that are genuinely different:
+ * "Record 41 not found" and "Record 42 not found" are two missing records, so a
+ * seven-item sweep where every item legitimately 404s would trip the
+ * across-arguments breaker at item six. A guard message that varies its own
+ * running tally is fixed where that message is written, not by blinding every
+ * breaker to numbers.
  */
 function normalizeToolErrorForBreaker(error) {
     return (error
@@ -2455,6 +2462,61 @@ function rateLimitRecoveryHint(message) {
     }
     return "\n\nProvider rate-limit guidance: stop retrying this provider in this turn. Report the rate limit as a coverage gap, include any evidence already gathered, and ask the user to retry after the provider quota resets if full coverage is required.";
 }
+/**
+ * Tool errors the model has no way to clear: the missing thing lives outside
+ * the turn (a credential, a role grant, a connected account, a runtime, the
+ * user's own approval). Every retry costs a full round-trip carrying the whole
+ * transcript and lands on the identical error, so these stop on the FIRST
+ * occurrence rather than after `MAX_SAME_ERROR_ACROSS_ARGUMENTS` of them.
+ *
+ * The distinction is the one `stopForBigQueryNotConfigured` draws in
+ * templates/analytics: a *configuration* gap is permanent for this turn, a
+ * *query* failure is not. Anything the model can act on — a stale read to
+ * rebase, a bad argument, a full quota it can free, a wrong dataset name, a
+ * statement timeout — must stay out of this list and keep its retries.
+ * Precision over recall: a wrong match kills a turn that would have succeeded,
+ * which is worse than one more retry.
+ */
+export function permanentPreconditionRemedy(message) {
+    const trimmed = message.replace(/\s+/g, " ").trim();
+    for (const pattern of PERMANENT_PRECONDITION_PATTERNS) {
+        if (pattern.test(trimmed))
+            return trimmed;
+    }
+    return null;
+}
+const PERMANENT_PRECONDITION_PATTERNS = [
+    // "Requires editor role on deck ZJshjrXhjx (have viewer)". The trailing space
+    // is load-bearing: it keeps "must have required property" out.
+    /\brequires? (?:an? |the )?[\w-]+ role\b/i,
+    // "Gemini API key not configured. Save GEMINI_API_KEY in settings." Only the
+    // not-configured/not-set wordings — "not found" is how providers report a
+    // missing dataset or record, which the model can and should correct.
+    /\b(?:api[ -]?keys?|access tokens?|credentials?|secrets?)\b[^.]{0,60}\bnot (?:configured|set|connected|available)\b/i,
+    /\bsave [A-Z][A-Z0-9_]{3,} in (?:the )?settings\b/i,
+    // "Connect Builder.io before indexing a design system from Figma or code."
+    // Case-sensitive, sentence-initial, and followed by a capitalized service
+    // name, because that is the only shape that separates the imperative remedy
+    // from the retryable network failure: "failed to connect to the warehouse
+    // before the deadline" and "Connect timed out, retry first" both satisfy
+    // every looser reading of the same words.
+    /(?:^|[.:!?]\s+)Connect [A-Z][\w.-]*[^;]{0,40}?\b(?:before|first|in settings)\b/,
+    // "Plan mode blocked `update-extension`. Switch to Act mode …" — cleared by
+    // the user approving the plan, never by the model trying again.
+    /\bplan mode blocked\b/i,
+    // The templates' most-copied throw, and always `if (!getRequestUserEmail())`:
+    // one synchronous AsyncLocalStorage read of a value fixed when the request
+    // context was established. It cannot appear and disappear between tool calls
+    // of the same chunk, so retrying inside this turn lands on it again.
+    /\bno authenticated user\b/i,
+    // "SSRF blocked: refusing to fetch private/internal address (…)"
+    /\bssrf blocked\b/i,
+    // Deliberately absent: "only available in …". Retention windows ("only
+    // available from the last 90 days") share its wording and are fixed by
+    // narrowing the range, so it stopped turns that were one argument away from
+    // succeeding. The count-based breaker still ends a genuine runtime gate
+    // after six.
+];
 const SOURCE_SWEEP_TOOL_NAME = /\b(?:api|calls?|deals?|docs?|events?|issues?|messages?|metrics?|provider|query|records?|request|search|source|tickets?|transcripts?)\b/i;
 const SOURCE_SWEEP_PROVIDER_TOKEN = /\b(?:amplitude|apollo|bigquery|commonroom|data-source|ga4|github|gong|grafana|hubspot|jira|mixpanel|notion|posthog|postgres|postgresql|pylon|sentry|slack|stripe)\b/i;
 const SOURCE_SWEEP_EXCLUDED_TOOLS = new Set([
@@ -2560,14 +2622,20 @@ function restrictAgentTeamsAfterSourceSweep(tools) {
         };
     });
 }
+/**
+ * Deliberately carries no running call count. This decline is recorded as a
+ * tool error, and the breakers key on that text: a message that reports its own
+ * tally ("already made 13 call(s)") mints a fresh key on every decline, so the
+ * decline that exists to stop a spiral becomes the one thing nothing can count.
+ * The fixed threshold below says the same thing without varying.
+ */
 export function repeatedSourceSweepGuardMessage(opts) {
     const threshold = opts.threshold ?? SOURCE_SWEEP_TOOL_CALL_THRESHOLD;
     const target = opts.scope === "aggregate"
         ? "read-only source/search tools"
         : "the same read-only source/search tool";
-    return (`Skipped ${opts.toolName}: this turn already made ${opts.priorCalls} ` +
-        `call(s) to ${target}, which exceeds the ` +
-        `${threshold}-call convergence budget. Stop calling ${opts.toolName} ` +
+    return (`Skipped ${opts.toolName}: this turn already exhausted its ` +
+        `${threshold}-call convergence budget for ${target}. Stop calling ${opts.toolName} ` +
         `one item at a time and change strategy before answering. If a broader ` +
         `read-only bulk/source mechanism is available, use it now: provider API ` +
         `catalog/docs/request tools with pagination or staging, code execution ` +
@@ -2597,7 +2665,6 @@ export function shouldGuardRepeatedSourceSweep(opts) {
             priorCalls: priorSourceSweepCalls,
             message: repeatedSourceSweepGuardMessage({
                 toolName: opts.toolName,
-                priorCalls: priorSourceSweepCalls,
                 threshold,
                 scope: "aggregate",
             }),
@@ -2610,7 +2677,6 @@ export function shouldGuardRepeatedSourceSweep(opts) {
         priorCalls,
         message: repeatedSourceSweepGuardMessage({
             toolName: opts.toolName,
-            priorCalls,
             threshold,
             scope: "tool",
         }),
@@ -3095,29 +3161,50 @@ export async function runAgentLoop(opts) {
     // calls/results are folded into `toolCallHistory` / `toolResultHistory` so
     // final response guards see evidence from earlier chunks of this turn.
     const consumedJournalKeys = new Set();
-    const { toolCallJournal, priorToolCalls: journaledPriorToolCalls, priorToolResults: journaledPriorToolResults, } = await loadPriorTurnToolCallJournal(opts.threadId, opts.turnId);
+    const journalRead = await loadPriorTurnToolCallJournal(opts.threadId, opts.turnId);
+    const toolCallJournal = journalRead.status === "read" ? journalRead.toolCallJournal : null;
+    const journaledPriorToolCalls = journalRead.status === "read" ? journalRead.priorToolCalls : [];
+    const journaledPriorToolResults = journalRead.status === "read" ? journalRead.priorToolResults : [];
     toolCallHistory.push(...journaledPriorToolCalls);
     toolResultHistory.push(...journaledPriorToolResults);
+    // Every per-turn ceiling below is seeded from that read, and the write-replay
+    // hard block is enforced from it. On a continuation we cannot tell an
+    // already-completed side effect from a fresh one without it, so a failed read
+    // stops the turn instead of quietly resuming with a blank ledger.
+    const unreadableJournalStop = journalRead.status === "unreadable" && isInternalContinuationTurn(messages)
+        ? {
+            message: "I stopped because I could not read this turn's run ledger, so I could not tell which steps had already finished. " +
+                "Retrying would risk repeating a step that already completed. Please send the request again.",
+            errorCode: "tool_call_journal_unreadable",
+            details: journalRead.error,
+        }
+        : null;
     const readOnlyToolResultCache = seedReadOnlyToolResultsFromHistory(messages, actions, seedReadOnlyToolResultsFromJournal(toolCallJournal, actions));
     const duplicateReadOnlyToolCalls = seedDuplicateReadOnlyToolCallsFromHistory(messages, actions);
     const writeToolInterruptions = seedWriteToolInterruptionsFromHistory(messages, actions);
+    // All three repetition ledgers are SEEDED from earlier chunks of this turn,
+    // like `toolCallHistory` and `toolResultHistory` above. A fresh Map makes the
+    // limit per-CHUNK rather than per-turn, and a turn may chain up to
+    // MAX_RUN_LOOP_CONTINUATIONS (6) or MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS
+    // (20) of them — so the real ceiling becomes 20x the constant, and a spiral
+    // resumes with a clean slate at every chunk boundary.
     const repeatedToolErrors = new Map();
-    // Keyed WITHOUT the arguments — see MAX_SAME_ERROR_ACROSS_ARGUMENTS.
-    //
-    // SEEDED from earlier chunks of this turn, like `toolCallHistory` and
-    // `toolResultHistory` above. A fresh Map here would make the limit per-CHUNK
-    // rather than per-turn, and a turn may chain up to MAX_RUN_LOOP_CONTINUATIONS
-    // (6) or MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS (20) of them — so the real
-    // ceiling would be 36 or 120 identical failures, not 6, and a spiral would
-    // resume with a clean slate at every chunk boundary.
+    /** Keyed WITHOUT the arguments — see MAX_SAME_ERROR_ACROSS_ARGUMENTS. */
     const repeatedToolErrorsAnyArgs = new Map();
-    for (const prior of toolResultHistory) {
+    const repeatedToolCalls = new Map();
+    for (const prior of journaledPriorToolCalls) {
+        const key = toolCallCacheKey(prior.name, prior.input);
+        repeatedToolCalls.set(key, (repeatedToolCalls.get(key) ?? 0) + 1);
+    }
+    for (const prior of journaledPriorToolResults) {
         if (!prior.isError)
             continue;
-        const key = `${prior.name}:${normalizeToolErrorForBreaker(prior.content)}`;
-        repeatedToolErrorsAnyArgs.set(key, (repeatedToolErrorsAnyArgs.get(key) ?? 0) + 1);
+        const normalized = normalizeToolErrorForBreaker(prior.content);
+        const anyArgsKey = `${prior.name}:${normalized}`;
+        repeatedToolErrorsAnyArgs.set(anyArgsKey, (repeatedToolErrorsAnyArgs.get(anyArgsKey) ?? 0) + 1);
+        const errorKey = `${toolCallCacheKey(prior.name, prior.input)}:${normalized}`;
+        repeatedToolErrors.set(errorKey, (repeatedToolErrors.get(errorKey) ?? 0) + 1);
     }
-    const repeatedToolCalls = new Map();
     let finalGuardRetries = 0;
     let emptyFinalResponseRetries = 0;
     let iterations = 0;
@@ -3125,6 +3212,31 @@ export async function runAgentLoop(opts) {
     // trailing `done` would overwrite the boundary the continuation logic reads.
     let endedAtLoopLimit = false;
     let terminalActionStop = null;
+    /**
+     * A stop is either a hand-off to the user (the two `input_required` codes) or
+     * a failed run. Failed runs MUST leave a terminal `error` event behind: the
+     * run row's status, `error_code`, `listErroredRuns`, the outcome counters and
+     * the client's retry affordance all key off that event, and a stop that only
+     * streams text is recorded as `status='completed', terminal_reason='done'` —
+     * a guard trip counted as a success.
+     */
+    const sendTerminalActionStop = (stop) => {
+        if (stop.errorCode === "needs-approval" ||
+            stop.errorCode === "awaiting-user-input") {
+            send({ type: "text", text: stop.message });
+            return;
+        }
+        // Sent ONLY as an error: both the live client and the thread rebuild render
+        // an error event's message as assistant text themselves, so also sending it
+        // as `text` prints the same sentence twice.
+        send({
+            type: "error",
+            error: stop.message,
+            errorCode: stop.errorCode ?? "tool_failed",
+            ...(stop.details ? { details: stop.details } : {}),
+            recoverable: false,
+        });
+    };
     // Overridden (raised tokens, lowered effort) only after an empty-final-
     // response retry below — kept separate from `opts.maxOutputTokens`/
     // `opts.reasoningEffort` so the very first attempt is unaffected and later
@@ -3151,6 +3263,11 @@ export async function runAgentLoop(opts) {
     while (true) {
         if (signal.aborted)
             break;
+        if (unreadableJournalStop) {
+            terminalActionStop = unreadableJournalStop;
+            sendTerminalActionStop(unreadableJournalStop);
+            break;
+        }
         const turnInputTokens = priorTurnInputTokens + usage.inputTokens;
         if (turnInputTokens > maxRunInputTokens) {
             // Terminal for the whole TURN, not a chunk boundary: emitting
@@ -3882,9 +3999,6 @@ export async function runAgentLoop(opts) {
         // call run. The model cannot populate this — it comes from the request.
         const approvedToolCallKeys = new Set(opts.approvedToolCalls ?? []);
         const runToolCall = async (toolCall) => {
-            // Counted before any journal/cache short-circuit: serving a repeat from
-            // cache still means the model is asking the same question again.
-            noteRepeatedToolCall(toolCall.name, toolCall.input);
             const actionEntry = actions[toolCall.name];
             const placeholderNormalization = actionEntry
                 ? normalizeOptionalToolPlaceholders(actionEntry.tool.parameters, toolCall.input)
@@ -3898,6 +4012,11 @@ export async function runAgentLoop(opts) {
             if (jsonStringCoercion.changed) {
                 toolCall = { ...toolCall, input: jsonStringCoercion.input };
             }
+            // Count after the same normalization that is persisted in the journal:
+            // a model can send a JSON-encoded object/array, while the action and
+            // ledger both see the coerced value. Serving a repeat from cache still
+            // counts as asking the same question again.
+            noteRepeatedToolCall(toolCall.name, toolCall.input);
             const toolInputNormalized = placeholderNormalization.changed || jsonStringCoercion.changed;
             const wireToolInput = JSON.stringify(toolCall.input ?? {});
             const normalizedToolInput = normalizeToolCallInputForHistory(toolCall.input);
@@ -3931,6 +4050,21 @@ export async function runAgentLoop(opts) {
             };
             const finalizeToolErrorResult = (rawResult) => {
                 const sanitizedResult = sanitizeToolErrorText(rawResult);
+                // Counting is the wrong instrument for a precondition the turn cannot
+                // satisfy: six identical round-trips through a missing API key cost the
+                // user minutes and end where the first one did. Classified first so the
+                // remedy reaches them on attempt one.
+                const permanentRemedy = permanentPreconditionRemedy(sanitizedResult);
+                if (permanentRemedy) {
+                    requestedActionStop ??= {
+                        message: `I stopped because ${toolCall.name} needs a setup step outside this turn — a credential, a role, a connected account, or an approval — before it can run. ` +
+                            "Retrying would not have changed it, and anything completed before this is saved.",
+                        errorCode: "permanent_precondition",
+                        details: sanitizedResult,
+                    };
+                    return (`Stopped: ${toolCall.name} cannot run until a setup step outside this turn is fixed. ` +
+                        `Do not retry it with different arguments. ${sanitizedResult}`);
+                }
                 const errorKey = `${toolCallCacheKey(toolCall.name, toolCall.input)}:${normalizeToolErrorForBreaker(sanitizedResult)}`;
                 const count = (repeatedToolErrors.get(errorKey) ?? 0) + 1;
                 repeatedToolErrors.set(errorKey, count);
@@ -3946,9 +4080,9 @@ export async function runAgentLoop(opts) {
                         `with different arguments. Last error: ${sanitizedResult}`;
                     requestedActionStop ??= {
                         message: `I stopped because the ${toolCall.name} action rejected ${anyArgsCount} different attempts the same way, ` +
-                            "so changing the arguments again would not have worked. Anything completed before this is saved. " +
-                            `Error: ${sanitizedResult}`,
+                            "so changing the arguments again would not have worked. Anything completed before this is saved.",
                         errorCode: "repeated_tool_error_across_arguments",
+                        details: sanitizedResult,
                     };
                     return result;
                 }
@@ -3961,15 +4095,23 @@ export async function runAgentLoop(opts) {
                 // can do; never instruct them to "fix the arguments".
                 requestedActionStop ??= {
                     message: `I stopped because the ${toolCall.name} action failed ${count} times in a row the same way, ` +
-                        "so retrying it again would not have worked. Anything completed before this is saved. " +
-                        `Error: ${sanitizedResult}`,
+                        "so retrying it again would not have worked. Anything completed before this is saved.",
                     errorCode: "repeated_identical_tool_error",
+                    details: sanitizedResult,
                 };
                 return result;
             };
-            if (sourceSweepGuard) {
-                sourceSweepDelegationGuardActive = true;
-                const result = sourceSweepGuard.message;
+            /**
+             * A guard refused to run the tool. Recorded as an ERROR, not as a plain
+             * result: a decline costs a full model round-trip carrying the whole
+             * transcript, and `noteRepeatedToolCall` keys on name+args, so a model
+             * iterating ids mints a fresh key every time and declines forever until
+             * `maxIterations`. Routing through `finalizeToolErrorResult` gives the
+             * existing breakers something to count — no new counter — while the text
+             * the model reads is still the guard's own guidance.
+             */
+            const declineToolCall = (guidance) => {
+                const result = finalizeToolErrorResult(guidance);
                 send({
                     type: "tool_start",
                     id: toolCall.id,
@@ -3982,9 +4124,10 @@ export async function runAgentLoop(opts) {
                     tool: toolCall.name,
                     input: toolCall.input,
                     result,
+                    isError: true,
                     completedSideEffect: false,
                 });
-                recordToolResult(result, false);
+                recordToolResult(result, true);
                 return {
                     type: "tool-result",
                     toolCallId: toolCall.id,
@@ -3992,31 +4135,13 @@ export async function runAgentLoop(opts) {
                     toolInput: wireToolInput,
                     content: result,
                 };
+            };
+            if (sourceSweepGuard) {
+                sourceSweepDelegationGuardActive = true;
+                return declineToolCall(sourceSweepGuard.message);
             }
             if (sourceSweepDelegationGuard) {
-                const result = sourceSweepDelegationGuard;
-                send({
-                    type: "tool_start",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                });
-                send({
-                    type: "tool_done",
-                    id: toolCall.id,
-                    tool: toolCall.name,
-                    input: toolCall.input,
-                    result,
-                    completedSideEffect: false,
-                });
-                recordToolResult(result, false);
-                return {
-                    type: "tool-result",
-                    toolCallId: toolCall.id,
-                    toolName: toolCall.name,
-                    toolInput: wireToolInput,
-                    content: result,
-                };
+                return declineToolCall(sourceSweepDelegationGuard);
             }
             if (!actionEntry) {
                 const result = finalizeToolErrorResult(`Error: Unknown tool "${toolCall.name}"`);
@@ -4817,7 +4942,7 @@ export async function runAgentLoop(opts) {
             // TypeScript can't track ??= through async closures; cast to known type.
             const stop = requestedActionStop;
             terminalActionStop = stop;
-            send({ type: "text", text: stop.message });
+            sendTerminalActionStop(stop);
             break;
         }
     }
@@ -4893,6 +5018,10 @@ export async function runAgentLoop(opts) {
             }
         }
     }
+    // Assignments happen inside async tool-loop closures, which TypeScript cannot
+    // use for narrowing at this point. Snapshot the runtime value before the
+    // outcome branches so a stop is still represented as a possible value.
+    const finalTerminalActionStop = terminalActionStop;
     if (signal.aborted) {
         reportOutcome({ state: "canceled", message: "Agent run was aborted." });
     }
@@ -4904,26 +5033,26 @@ export async function runAgentLoop(opts) {
             message: `Agent stopped after ${maxIterations} iterations.`,
         });
     }
-    else if (terminalActionStop?.errorCode === "needs-approval") {
+    else if (finalTerminalActionStop?.errorCode === "needs-approval") {
         reportOutcome({
             state: "input_required",
             code: "needs_approval",
-            message: terminalActionStop.message,
+            message: finalTerminalActionStop.message,
         });
     }
-    else if (terminalActionStop?.errorCode === "awaiting-user-input") {
+    else if (finalTerminalActionStop?.errorCode === "awaiting-user-input") {
         reportOutcome({
             state: "input_required",
             code: "awaiting_user_input",
-            message: terminalActionStop.message,
+            message: finalTerminalActionStop.message,
         });
     }
-    else if (terminalActionStop) {
+    else if (finalTerminalActionStop) {
         reportOutcome({
             state: "failed",
-            code: terminalActionStop.errorCode ?? "tool_failed",
+            code: finalTerminalActionStop.errorCode ?? "tool_failed",
             retryable: false,
-            message: terminalActionStop.message,
+            message: finalTerminalActionStop.message,
         });
     }
     else {
@@ -4944,6 +5073,13 @@ function isRecoverableContinuationError(event) {
     const message = event.error.toLowerCase();
     if (code === "builder_gateway_error")
         return false;
+    // An explicit flag outranks the message sniff below, which exists for events
+    // that carry no flag at all. Every guard stop sets `recoverable: false`, and
+    // sniffing its prose is how a stop that merely NAMES a connection or a
+    // timeout gets continued into the spiral it was raised to end. The client
+    // applies the same precedence in `isAutoRecoverableError`.
+    if (event.recoverable === false)
+        return false;
     return (event.recoverable === true ||
         code === "builder_gateway_timeout" ||
         code === "builder_gateway_network_error" ||
@@ -5383,8 +5519,11 @@ async function emitRunText(run, text) {
  * per-turn journal the resume note uses (no new ledger read shape).
  */
 async function describeTurnProgress(threadId, turnId) {
-    const { toolCallJournal } = await loadPriorTurnToolCallJournal(threadId, turnId);
-    const completed = toolCallJournal?.completed ?? [];
+    const journalRead = await loadPriorTurnToolCallJournal(threadId, turnId);
+    if (journalRead.status === "unreadable") {
+        return "I could not read the run ledger, so I cannot say which steps completed.";
+    }
+    const completed = journalRead.toolCallJournal?.completed ?? [];
     if (completed.length === 0)
         return "No steps had completed yet.";
     const names = [...new Set(completed.map((entry) => entry.tool))];

package/dist/agent/run-loop-with-resume.d.ts

@@ -27,7 +27,7 @@ import type { ResolveRunSoftTimeoutOptions } from "./run-manager.js";
  * Rebuild the same safe continuation context for a logical turn that resumes
  * in a fresh hosted invocation.
  */
-export declare function appendDurableContinuationContext(messages: EngineMessage[], reason: AgentLoopContinuationReason, threadId: string): Promise<void>;
+export declare function appendDurableContinuationContext(messages: EngineMessage[], reason: AgentLoopContinuationReason, threadId: string, turnId?: string): Promise<void>;
 /**
  * Cap on continuation iterations inside a single
  * `runAgentLoopDirectWithSoftTimeout` invocation. The host's hard function

package/dist/agent/run-loop-with-resume.js

@@ -24,23 +24,35 @@ import { runAgentLoop, appendAgentLoopContinuation, isResumableEngineError, isTr
 import { resolveRunSoftTimeoutMs } from "./run-manager.js";
 import { getCurrentTurnEventsForThread } from "./run-store.js";
 import { classifyToolCallJournal, buildResumeJournalNote, } from "./tool-call-journal.js";
-async function readCurrentTurnEventsForResume(threadId, localEvents = []) {
+/**
+ * `persisted: false` means the durable half of the turn could not be read, so
+ * `events` holds only what this invocation saw. Callers that decide whether to
+ * DISCARD user-visible output must not read that as "nothing else happened".
+ */
+async function readCurrentTurnEventsForResume(threadId, turnId, localEvents = []) {
     let persistedEvents = [];
+    let persisted = true;
     try {
+        // Without the turnId this can return the PREVIOUS turn's events — see
+        // `getCurrentTurnEventsForThread`, whose run row is written without await.
         persistedEvents = threadId
-            ? await getCurrentTurnEventsForThread(threadId)
+            ? await getCurrentTurnEventsForThread(threadId, turnId)
             : [];
     }
-    catch {
-        persistedEvents = [];
+    catch (err) {
+        persisted = false;
+        console.warn("[run-loop] current-turn ledger read failed:", err instanceof Error ? err.message : String(err));
     }
     if (localEvents.length === 0)
-        return persistedEvents;
+        return { events: persistedEvents, persisted };
     const seen = new Set(persistedEvents.map((event) => JSON.stringify(event)));
-    return [
-        ...persistedEvents,
-        ...localEvents.filter((event) => !seen.has(JSON.stringify(event))),
-    ];
+    return {
+        events: [
+            ...persistedEvents,
+            ...localEvents.filter((event) => !seen.has(JSON.stringify(event))),
+        ],
+        persisted,
+    };
 }
 function actionPreparationContinuationOptions(events) {
     const actionPreparationTool = lastUnfinishedPreparingActionToolFromEvents(events);
@@ -86,8 +98,8 @@ function appendToolCallJournalNote(messages, events) {
         // up — the model still continues, just without the structured journal.
     }
 }
-async function appendContinuationAndJournal(messages, reason, threadId, localEvents = []) {
-    const events = await readCurrentTurnEventsForResume(threadId, localEvents);
+async function appendContinuationAndJournal(messages, reason, threadId, turnId, localEvents = []) {
+    const { events } = await readCurrentTurnEventsForResume(threadId, turnId, localEvents);
     appendAgentLoopContinuation(messages, reason, actionPreparationContinuationOptions(events));
     appendToolCallJournalNote(messages, events);
 }
@@ -95,21 +107,23 @@ async function appendContinuationAndJournal(messages, reason, threadId, localEve
  * Rebuild the same safe continuation context for a logical turn that resumes
  * in a fresh hosted invocation.
  */
-export async function appendDurableContinuationContext(messages, reason, threadId) {
-    await appendContinuationAndJournal(messages, reason, threadId);
+export async function appendDurableContinuationContext(messages, reason, threadId, turnId) {
+    await appendContinuationAndJournal(messages, reason, threadId, turnId);
 }
-async function hasCompletedSideEffectToolCallInCurrentTurn(threadId, localEvents = []) {
-    try {
-        const events = await readCurrentTurnEventsForResume(threadId, localEvents);
-        if (events.length === 0)
-            return false;
-        return events.some((event) => event.type === "tool_done" &&
-            event.completedSideEffect === true &&
-            event.isError !== true);
-    }
-    catch {
-        return false;
-    }
+/**
+ * `"unknown"` is not `"none"`: the only caller uses this to decide whether to
+ * emit `clear`, and `clear` WIPES user-visible output. A transient ledger error
+ * must not delete the tool cards that are the user's only proof a side effect
+ * landed.
+ */
+async function completedSideEffectInCurrentTurn(threadId, turnId, localEvents = []) {
+    const { events, persisted } = await readCurrentTurnEventsForResume(threadId, turnId, localEvents);
+    const found = events.some((event) => event.type === "tool_done" &&
+        event.completedSideEffect === true &&
+        event.isError !== true);
+    if (found)
+        return "some";
+    return persisted ? "none" : "unknown";
 }
 function internalContinuationReasonForAttempt(events) {
     const last = events.at(-1);
@@ -362,15 +376,15 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
             if (internalContinuationReason && !upstreamSignal.aborted) {
                 lastAttemptWasUnfinishedContinuation = true;
                 const continuationEvents = [...localTurnEvents];
-                if (!(await hasCompletedSideEffectToolCallInCurrentTurn(opts.threadId, continuationEvents))) {
+                if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, continuationEvents)) === "none") {
                     opts.send({ type: "clear" });
                 }
-                await appendContinuationAndJournal(opts.messages, internalContinuationReason, opts.threadId, continuationEvents);
+                await appendContinuationAndJournal(opts.messages, internalContinuationReason, opts.threadId, opts.turnId, continuationEvents);
                 continue;
             }
             if (softTimedOut && !upstreamSignal.aborted) {
                 lastAttemptWasUnfinishedContinuation = true;
-                await appendContinuationAndJournal(opts.messages, "run_timeout", opts.threadId, localTurnEvents);
+                await appendContinuationAndJournal(opts.messages, "run_timeout", opts.threadId, opts.turnId, localTurnEvents);
                 continue;
             }
             reportFinalOutcome(upstreamSignal.aborted
@@ -383,10 +397,10 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                 // Clear partial text the client received before the abort so the
                 // resumed model doesn't re-emit it and produce duplicated output.
                 lastAttemptWasUnfinishedContinuation = true;
-                if (!(await hasCompletedSideEffectToolCallInCurrentTurn(opts.threadId, localTurnEvents))) {
+                if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {
                     opts.send({ type: "clear" });
                 }
-                await appendContinuationAndJournal(opts.messages, "run_timeout", opts.threadId, localTurnEvents);
+                await appendContinuationAndJournal(opts.messages, "run_timeout", opts.threadId, opts.turnId, localTurnEvents);
                 continue;
             }
             const transientRateLimit = isTransientProviderRateLimitError(err);
@@ -402,10 +416,10 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
                 rateLimitRetryFitsBudget) {
                 lastAttemptWasUnfinishedContinuation = true;
                 backgroundRateLimitContinuations++;
-                if (!(await hasCompletedSideEffectToolCallInCurrentTurn(opts.threadId, localTurnEvents))) {
+                if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {
                     opts.send({ type: "clear" });
                 }
-                await appendContinuationAndJournal(opts.messages, "rate_limited", opts.threadId, localTurnEvents);
+                await appendContinuationAndJournal(opts.messages, "rate_limited", opts.threadId, opts.turnId, localTurnEvents);
                 await waitForBackgroundRateLimitCooldown(upstreamSignal);
                 continue;
             }
@@ -424,10 +438,10 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
             // the in-memory messages array, so the next attempt re-emits it).
             if (!upstreamSignal.aborted && isResumableEngineError(err)) {
                 lastAttemptWasUnfinishedContinuation = true;
-                if (!(await hasCompletedSideEffectToolCallInCurrentTurn(opts.threadId, localTurnEvents))) {
+                if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {
                     opts.send({ type: "clear" });
                 }
-                await appendContinuationAndJournal(opts.messages, continuationReasonForResumableError(err), opts.threadId, localTurnEvents);
+                await appendContinuationAndJournal(opts.messages, continuationReasonForResumableError(err), opts.threadId, opts.turnId, localTurnEvents);
                 continue;
             }
             if (upstreamSignal.aborted) {
@@ -467,7 +481,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
         // the terminal message stands alone instead of trailing a half sentence.
         // Preserve completed tool cards: they are the user's only durable proof
         // that a side effect landed before the final assistant note timed out.
-        if (!(await hasCompletedSideEffectToolCallInCurrentTurn(opts.threadId, localTurnEvents))) {
+        if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {
             opts.send({ type: "clear" });
         }
         opts.send({