@buoy-gg/agent-core 7.0.35 → 7.0.36

package/lib/commonjs/engine/runAgentTurn.js

@@ -3,19 +3,31 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "digestOf", {
+  enumerable: true,
+  get: function () {
+    return _digest.digestOf;
+  }
+});
+exports.readTargetDigest = readTargetDigest;
 exports.runAgentTurn = runAgentTurn;
 exports.runGatedAction = runGatedAction;
 var _catalog = require("../catalog/catalog.g");
 var _validateParams = require("../catalog/validateParams");
+var _normalizeParams = require("../catalog/normalizeParams");
 var _toProviderTools = require("../catalog/toProviderTools");
 var _snapshotReads = require("../catalog/snapshotReads");
 var _ledger = require("../effects/ledger");
 var _policy = require("../policy/policy");
 var _redact = require("../policy/redact");
 var _effectFor = require("./effectFor");
+var _digest = require("../effects/digest");
 var _uiTool = require("../blocks/uiTool");
 var _receipts = require("../blocks/receipts");
 var _types = require("../blocks/types");
+var _askGate = require("./askGate");
+var _textToolCalls = require("./textToolCalls");
+var _historyBudget = require("./historyBudget");
 /**
  * One turn: user sentence in, tool calls and an answer out.
  *
@@ -43,11 +55,46 @@ const MAX_RESULT_CHARS = 24_000;
  * store dump per step makes the trace unreadable rather than more useful.
  */
 const MAX_TRACE_RESULT_CHARS = 2_000;
+/**
+ * How many identical rounds before the model is told it is looping.
+ *
+ * `maxSteps` alone was the whole answer, and it is the wrong shape: a model
+ * that misread a result retries the same call until the cap, then the turn
+ * ends with nothing — the user watches twelve identical rows go by and gets
+ * no answer. The cap is a backstop, not feedback. Telling the model what it
+ * is doing gives it the chance to change approach, and costs one sentence.
+ *
+ * Signature is name + action + arguments, key-sorted so `{b,a}` and `{a,b}`
+ * are the same call. Three, not two: a legitimate retry after a transient
+ * failure is normal, and warning on it would be noise.
+ */
+const LOOP_REPEATS = 3;
+function callSignature(calls) {
+  const sort = v => {
+    if (v === null || typeof v !== "object") return v;
+    if (Array.isArray(v)) return v.map(sort);
+    const o = v;
+    return Object.keys(o).sort().reduce((a, k) => (a[k] = sort(o[k]), a), {});
+  };
+  return calls.map(c => `${c.name}:${JSON.stringify(sort(c.input ?? {}))}`).join("|");
+}
+const LOOP_WARNING = "[Buoy] You have now made this exact call three times in a row and gotten the same thing back. Repeating it again will not change the answer. Read the result you already have, then either try a different tool or different arguments, or tell the user plainly what you could not get and what you tried.";
 const DEFAULT_MAX_STEPS = 12;
 const DEFAULT_TURN_MS = 180_000;
 function findDescriptor(catalog, toolId, action) {
   return catalog.find(t => t.toolId === toolId)?.actions.find(a => a.action === action);
 }
+
+/**
+ * Why a picture did not render, in the model's own terms.
+ *
+ * Two messages, not one, because they answer different questions: the first
+ * is "your block was refused", the second is "your block was shown but with
+ * holes in it". The literal opening of the rejection is pinned by the
+ * trajectory classifier (evals/ask-buoy/lib/trajectory.ts) — keep it.
+ */
+const URL_PROVENANCE_REJECTION = "Rejected: every image URL must be one you read from a tool result in THIS conversation (images.list, a storage value, a response body). Never invent or remember URLs — read them first, then show them.";
+const droppedImageNote = n => ` NOTE: ${n} image ${n === 1 ? "URL was" : "URLs were"} dropped — they were not read from a tool result in this conversation, so the card the user is looking at has no picture there. Do not tell them it does; read the URLs and show it again, or say the artwork is missing.`;
 function encodeResult(value) {
   let text;
   try {
@@ -92,11 +139,30 @@ function summarise(value) {
 function countOf(n) {
   return n === 1 ? "1 item" : `${n} items`;
 }
+
+/**
+ * A call that came back reporting its own failure.
+ *
+ * Buoy adapters RESOLVE with `{ok:false, error}` rather than throwing, so the
+ * dispatch's try/catch never fires and a refused write looked like a completed
+ * one: the row read "Done", and — much worse — the effect ledger recorded a
+ * change that had not happened, so the changes bar offered to undo nothing.
+ * Caught on device: a typed-edit refusal ("qty is a number, 'many' is text")
+ * left the bag untouched and the bar claiming one permanent change.
+ *
+ * `ok === false` is the same signal `summarise` above already trusts to turn a
+ * result into the row's text, so this reads it no more liberally than the UI
+ * already does.
+ */
+function reportsFailure(value) {
+  return typeof value === "object" && value !== null && value.ok === false;
+}
 async function* runAgentTurn(input) {
   const {
     provider,
     catalog,
     system,
+    systemVolatile,
     model,
     maxTokens,
     dispatch,
@@ -116,15 +182,72 @@ async function* runAgentTurn(input) {
   });
   tools.push((0, _uiTool.uiProviderTool)());
   const maxSteps = policy.maxSteps ?? DEFAULT_MAX_STEPS;
-  const deadline = Date.now() + DEFAULT_TURN_MS;
+  /**
+   * The conversation this turn belongs to. Handed back on every `record` so a
+   * dispatch that settles after the user started a new conversation lands in
+   * the app (nothing can pull it back) but not in the new chat's undo bar.
+   */
+  const ledgerGeneration = ledger.generation;
+  /**
+   * What every request costs before a single message is added: the tool
+   * definitions, the system prompt, and the room the model needs to reply.
+   *
+   * Measured, not guessed — the tool block alone is ~32k characters for a
+   * typical install and ~94k with all 24 tools available, which is far too
+   * much to leave out of a budget. `maxTokens` is multiplied by four because
+   * the budget is in characters.
+   */
+  const requestReserve = system.length + (systemVolatile?.length ?? 0) + tools.reduce((n, t) => n + t.description.length + JSON.stringify(t.inputSchema).length, 0) + maxTokens * 4;
+  /**
+   * Caps the AGENT's wall-clock, not the user's. Time spent parked on an
+   * approval sheet is pushed onto the deadline as it is spent (see the
+   * `requestApproval` await below) — otherwise a user who takes three minutes
+   * to tap Approve gets the change applied and then "this is taking too long"
+   * for the turn that applied it.
+   */
+  let deadline = Date.now() + DEFAULT_TURN_MS;
 
-  // Every http(s) URL that appeared in a tool result THIS turn. The prompt
-  // tells the model image URLs must come from here; this Set is the
-  // enforcement — a model-remembered or injected URL in an image block is
+  // Every http(s) URL that appeared in a tool result in this CONVERSATION.
+  // The prompt tells the model image URLs must come from here; this Set is
+  // the enforcement — a model-remembered or injected URL in an image block is
   // both a fabrication vector and a data-exfil beacon (the GET carries
-  // whatever is encoded into the URL).
-  const seenUrls = new Set();
+  // whatever is encoded into the URL). Session-owned when the caller passes
+  // one; see RunTurnInput.seenUrls for why it is not per-turn.
+  const seenUrls = input.seenUrls ?? new Set();
   const URL_RE = /https?:\/\/[^\s"'\\)\]}>]+/g;
+
+  /** Whether any text has gone out THIS TURN — see `breakBefore`. */
+  let answerStarted = false;
+
+  /**
+   * The last few rounds' call signatures. See LOOP_REPEATS — a run of
+   * identical rounds gets one warning appended to the results, once, so the
+   * model is told rather than silently capped.
+   */
+  const recentSignatures = [];
+  let loopWarned = false;
+
+  /**
+   * Everything the model SAID this turn, in order. Read once, at the end, by
+   * the ask gate — a question asked in round one and left hanging is the same
+   * dead end as one asked in the last round. See askGate.ts.
+   */
+  const spoken = [];
+  /**
+   * Whether the user already has something to tap. An `actions` or
+   * `suggestions` block is the model doing this job itself, and a second card
+   * asking the same thing underneath it is worse than none.
+   *
+   * Note this does NOT suppress the shortfall gate below — that one asks
+   * whether the user can tap the GAP, which unrelated chips do not answer.
+   */
+  let offeredTap = false;
+  /**
+   * Whether this turn actually went and looked — navigated, described the
+   * screen, tapped something, refetched. The shortfall gate stays quiet when
+   * it did: an agent that tried and came up short has earned its answer.
+   */
+  let attemptedAcquisition = false;
   for (let step = 0; step < maxSteps; step++) {
     if (signal?.aborted) {
       yield {
@@ -133,24 +256,112 @@ async function* runAgentTurn(input) {
       return messages;
     }
     if (Date.now() > deadline) {
+      // Same shape as the step cap below. This used to be an `error`, which
+      // drew the failed-turn card with Try again — and Try again re-sends the
+      // question, restarting the whole investigation that just ran out of
+      // time. Continue picks up with everything so far still in history.
       yield {
-        type: "error",
-        message: "This is taking too long — stopping here."
+        type: "block",
+        block: {
+          id: `cap${Date.now()}`,
+          kind: "notice",
+          tone: "warning",
+          // Keeps the "This is taking too long" prefix: the eval classifier
+          // (evals/ask-buoy/lib/trajectory.ts) tells a time-out from a step
+          // cap by it.
+          text: `This is taking too long — stopped after ${Math.round(DEFAULT_TURN_MS / 1000)}s. What it found so far is above.`,
+          actions: [{
+            label: "Continue",
+            primary: true,
+            send: "Continue where you left off."
+          }]
+        }
       };
       yield {
         type: "done"
       };
       return messages;
     }
+
+    /**
+     * BUDGET, EVERY REQUEST — not once per turn.
+     *
+     * The session trims when a turn opens, and that used to be the only
+     * check. But a turn is not one request: each step appends an assistant
+     * message and a tool-results message, and a single result can be 24,000
+     * characters. A twelve-step investigation could therefore add six figures
+     * of history AFTER the only check had run, and the turn died on the
+     * provider's context limit with an opaque error — in exactly the long
+     * sessions the tool is for.
+     *
+     * The current round is never touched: it is the question being answered.
+     */
+    const budgeted = (0, _historyBudget.budgetForRequest)(messages, requestReserve);
+    if (budgeted.droppedRounds > 0) {
+      messages.length = 0;
+      messages.push(...budgeted.messages);
+      yield {
+        type: "history-trimmed",
+        droppedRounds: budgeted.droppedRounds
+      };
+    } else if (budgeted.messages !== messages) {
+      messages.length = 0;
+      messages.push(...budgeted.messages);
+    }
     let text = "";
+    /** See `breakBefore`: set once the first text of THIS round has gone out. */
+    let textThisRound = false;
+    const textEvent = delta => {
+      // Only when this round opens a NEW paragraph of an answer that has
+      // already started. A turn whose first words arrive in round three has
+      // nothing to be separated from, and marking that would put the flag on
+      // events where it means nothing.
+      const opensNewRound = answerStarted && !textThisRound;
+      textThisRound = true;
+      answerStarted = true;
+      return opensNewRound ? {
+        type: "text",
+        delta,
+        breakBefore: true
+      } : {
+        type: "text",
+        delta
+      };
+    };
     const calls = [];
+    /**
+     * Recovered from text rather than emitted as calls — see textToolCalls.ts.
+     * Tracked by id so each one's result can tell the model to stop doing that;
+     * they are otherwise ordinary calls and get every check the others get.
+     */
+    const salvagedIds = new Set();
+    /**
+     * Text withheld from the screen while it could still be a tool-call
+     * envelope. Streamed text cannot be un-shown, so the choice has to be made
+     * before it leaves — and a model that writes its call as JSON must not
+     * have that JSON become the answer the user reads.
+     */
+    let held = "";
+    let holding = true;
     // Carried, never read: Anthropic requires the turn's thinking blocks back
     // verbatim with its tool results. See providers/anthropic.ts note 5.
     const thinking = [];
     let failed = false;
+    /**
+     * What the provider said about how the stream ended.
+     *
+     * Undefined means it never said — a bare EOF, or a host-supplied provider
+     * whose generator simply returned. Both are treated as incomplete, so the
+     * fail-safe direction is the default rather than something each adapter
+     * has to remember to opt into.
+     */
+    let outcome;
+    /** Set for the two kinds that are recoverable rather than a hard failure. */
+    let incomplete;
     for await (const ev of provider.send({
       messages,
       system,
+      systemVolatile,
       tools,
       model,
       maxTokens,
@@ -158,10 +369,18 @@ async function* runAgentTurn(input) {
     })) {
       if (ev.type === "text") {
         text += ev.delta;
-        yield {
-          type: "text",
-          delta: ev.delta
-        };
+        if (!holding) {
+          yield textEvent(ev.delta);
+        } else if ((0, _textToolCalls.couldBeToolCallEnvelope)(text)) {
+          held += ev.delta;
+        } else {
+          // Not an envelope after all. Release everything at once and stream
+          // the rest as usual — the reader loses nothing but a few characters
+          // of latency at the very start of the answer.
+          holding = false;
+          held = "";
+          yield textEvent(text);
+        }
       } else if (ev.type === "tool-call") {
         calls.push(ev.call);
       } else if (ev.type === "thinking") {
@@ -177,35 +396,154 @@ async function* runAgentTurn(input) {
           };
         }
       } else if (ev.type === "error") {
-        // A mid-stream error can arrive on an already-committed 200.
-        yield {
-          type: "error",
-          message: ev.message
-        };
-        failed = true;
-      } else if (ev.type === "done" && ev.usage) {
-        // Surfaced so a host can meter cost per seat. Parsed for a long time;
-        // went nowhere anyone could see.
-        yield {
-          type: "usage",
-          input: ev.usage.input,
-          output: ev.usage.output
-        };
+        if (ev.kind === "truncated" || ev.kind === "timeout") {
+          // Not a failure the user did anything about, and not one Try again
+          // can fix — re-sending the QUESTION restarts an investigation that
+          // may already have written things. Held back from the error card
+          // (which is what draws Try again) and handled below as a recoverable
+          // stop with a Continue button.
+          incomplete = {
+            message: ev.message
+          };
+        } else {
+          // A mid-stream error can arrive on an already-committed 200.
+          yield {
+            type: "error",
+            message: ev.message
+          };
+          failed = true;
+        }
+      } else if (ev.type === "done") {
+        outcome = ev.outcome;
+        if (ev.usage) {
+          // Surfaced so a host can meter cost per seat. Parsed for a long time;
+          // went nowhere anyone could see.
+          yield {
+            type: "usage",
+            ...ev.usage,
+            model: ev.model
+          };
+        }
       }
     }
     if (failed) {
+      // Whatever was withheld is the model's own words on the way to an error.
+      // Show it rather than swallowing it.
+      if (held) yield textEvent(held);
       yield {
         type: "done"
       };
       return messages;
     }
+
+    /**
+     * THE COMPLETION GATE. Nothing below this runs a tool unless the provider
+     * said the response was whole.
+     *
+     * The failure it exists for is not theoretical and does not look like a
+     * failure: a connection cut after the model emitted
+     * `{"key":"cart","value":[]}` leaves valid JSON, a plausible-looking plan,
+     * and no error anywhere. The old code parsed those arguments, dispatched
+     * the write, sent the result back and carried on — a real mutation from
+     * half a sentence. Bare EOF is not consent.
+     *
+     * `output-limited` is the same shape from a different cause: the model hit
+     * max_tokens partway through planning. What it managed to SAY is real and
+     * is shown; what it was part-way through DOING is not run.
+     */
+    if (!incomplete && outcome !== "completed") {
+      incomplete = {
+        message: outcome === "output-limited" ? calls.length ? "The model ran out of room mid-plan, so nothing was run. What it found so far is above." : "The model ran out of room before finishing this answer." : "The answer ended before the endpoint said it was finished, so nothing was run."
+      };
+    }
+    if (incomplete) {
+      // Held text is the model's own words on the way out. Show it: the user
+      // watched it arrive and hiding it now reads as the app losing work.
+      if (held) yield textEvent(held);
+      /**
+       * Text only — never the tool calls, and never the thinking.
+       *
+       * An assistant turn carrying `tool_use` with no matching `tool_result`
+       * is an instant 400 on the next request, and these calls are exactly the
+       * ones that must not be answered. Keeping the text preserves what the
+       * user can see on screen for whatever comes next.
+       */
+      if (text.trim()) messages.push({
+        role: "assistant",
+        text
+      });
+      yield {
+        type: "block",
+        block: {
+          id: `cut${Date.now()}`,
+          kind: "notice",
+          tone: "warning",
+          text: incomplete.message,
+          actions: [{
+            label: "Continue",
+            primary: true,
+            send: "Continue where you left off."
+          }]
+        }
+      };
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+    if (held) {
+      // A model that wrote its call out as JSON instead of calling it. Run it,
+      // and show its `reply` — never the blob. See textToolCalls.ts.
+      const salvaged = calls.length === 0 ? (0, _textToolCalls.parseTextToolCalls)(held, catalog) : undefined;
+      if (salvaged) {
+        for (const call of salvaged.calls) {
+          calls.push(call);
+          salvagedIds.add(call.id);
+        }
+        text = salvaged.reply;
+        if (salvaged.reply) yield textEvent(salvaged.reply);
+      } else {
+        yield textEvent(held);
+      }
+      held = "";
+    }
     messages.push({
       role: "assistant",
       text,
       toolCalls: calls.length ? calls : undefined,
       thinking: thinking.length ? thinking : undefined
     });
+    if (text.trim()) spoken.push(text.trim());
     if (calls.length === 0) {
+      // The turn is over and the model wrote its own words. Two ways those
+      // words end badly, and they are different failures — see askGate.ts.
+      const said = spoken.join("\n\n");
+
+      // 1. It answered a smaller question than it was asked and handed the
+      //    rest back. Fires even when chips were offered: the question is
+      //    whether the user can tap the GAP, not whether they can tap.
+      const gap = (0, _askGate.synthesizeShortfallBlock)({
+        text: said,
+        attempted: attemptedAcquisition
+      });
+      if (gap) yield {
+        type: "block",
+        block: gap
+      };
+
+      // 2. It ended waiting on the user in prose. Suppressed once anything
+      //    tappable is on screen, the gap button included.
+      const asked = offeredTap || gap ? null : (0, _askGate.synthesizeAskBlock)(said);
+      if (asked) {
+        yield {
+          type: "block",
+          block: asked
+        };
+        yield {
+          type: "awaiting-user",
+          blockId: asked.id
+        };
+      }
       yield {
         type: "done"
       };
@@ -213,8 +551,220 @@ async function* runAgentTurn(input) {
     }
     const results = [];
     let realmWillDie = false;
+
+    /**
+     * Reads, already in flight.
+     *
+     * The loop below stays strictly serial — every yield, every ledger entry
+     * and every approval keeps its order — but a round of independent READS
+     * used to pay each round trip end to end. The prompt tells the model to
+     * chain reads freely ("reading is cheap; do it"), and a three-read round
+     * cost three times the device latency for no reason.
+     *
+     * ONLY when the whole batch is safe to overlap: every call a catalog read,
+     * none needing approval, no `buoy_ui`, nothing snapshot-only or
+     * session-local. One write, one approval or one unknown action in the
+     * batch and nothing is prefetched — the mixed case is where ordering
+     * actually matters, and it is not worth the risk for the latency.
+     */
+    const prefetch = new Map();
+    if (calls.length > 1) {
+      const safe = calls.every(c => {
+        if (c.name === _uiTool.UI_TOOL_NAME) return false;
+        const id = (0, _toProviderTools.fromProviderToolName)(c.name, catalog);
+        if (!id || id === "ask-buoy") return false;
+        const act = c.input?.action;
+        if (typeof act !== "string" || act === _snapshotReads.SNAPSHOT_ACTION) return false;
+        const d = findDescriptor(catalog, id, act);
+        if (!d || d.effect !== "read") return false;
+        return (0, _policy.decide)({
+          descriptor: d,
+          toolId: id,
+          policy,
+          isRelease
+        }).verdict === "allow";
+      });
+      if (safe) {
+        for (const c of calls) {
+          const id = (0, _toProviderTools.fromProviderToolName)(c.name, catalog);
+          const act = String(c.input.action);
+          const raw = {
+            ...(c.input.params ?? {})
+          };
+          const d = findDescriptor(catalog, id, act);
+          const norm = (0, _normalizeParams.normalizeParams)(id, act, raw);
+          const withDefaults = (0, _validateParams.applyDefaults)(norm.params, d.params);
+          if (!(0, _validateParams.validateParams)(withDefaults, d.params).ok) continue;
+          // Rejections are swallowed here and re-awaited in the loop, where
+          // they are turned into the same tool_result they always were.
+          const p = Promise.resolve(dispatch(id, act, withDefaults)).catch(e => {
+            throw e;
+          });
+          p.catch(() => {});
+          prefetch.set(c.id, p);
+        }
+      }
+    }
     let awaiting = null;
+
+    /**
+     * A call Stop got to first — as a row, so the transcript says which ones.
+     *
+     * Resolved leniently: the call has not been validated yet, and a label
+     * that falls back to `tool.action` is better than no row for a call the
+     * user needs to know did not run.
+     */
+    const stoppedStep = call => {
+      const toolId = (0, _toProviderTools.fromProviderToolName)(call.name, catalog) ?? call.name;
+      const action = typeof call.input?.action === "string" ? call.input.action : "";
+      const descriptor = action ? findDescriptor(catalog, toolId, action) : undefined;
+      const params = call.input?.params ?? {};
+      return [{
+        type: "tool-start",
+        id: call.id,
+        toolId,
+        action,
+        label: descriptor ? (0, _policy.describeCall)(toolId, descriptor, params) : `${toolId}.${action}`,
+        description: descriptor?.summary ?? "",
+        params,
+        effect: descriptor?.effect ?? "read"
+      }, {
+        type: "tool-end",
+        id: call.id,
+        ok: false,
+        summary: "stopped",
+        durationMs: 0
+      }];
+    };
+
+    /**
+     * THE BATCH BARRIER — what the whole batch will do, decided before any of
+     * it does anything.
+     *
+     * A model answers with several calls at once, and they used to run one at
+     * a time with each approval asked when its own call came up. So
+     * `[set the flag, delete the cache]` wrote the flag, THEN asked about the
+     * delete — and a user who declined had already changed the app, with the
+     * bubble reading "changed the flag" directly above "left the cache alone".
+     * Declining is supposed to mean the plan does not happen.
+     *
+     * The fix is not to ask again later or to refuse afterwards, neither of
+     * which can unrun a write. It is to ask FIRST: every gated call in the
+     * batch is put to the user before the batch's first mutation dispatches,
+     * so consent is given with the whole plan visible.
+     *
+     * Resolution here is pure and duplicates the loop's own — deliberately.
+     * Anything it cannot resolve (an unknown tool, a bad shape) comes back as
+     * neither mutating nor gated, so the loop reports it exactly as it always
+     * did and the barrier simply does not fire. Failing back to today's
+     * behaviour is the right failure for a safety gate to have.
+     */
+    const planned = calls.map(call => {
+      if (call.name === _uiTool.UI_TOOL_NAME) return undefined;
+      const toolId = (0, _toProviderTools.fromProviderToolName)(call.name, catalog);
+      const action = typeof call.input?.action === "string" ? call.input.action : undefined;
+      if (!toolId || !action) return undefined;
+      const descriptor = findDescriptor(catalog, toolId, action);
+      if (!descriptor) return undefined;
+      const raw = call.input.params ?? {};
+      const params = (0, _validateParams.applyDefaults)((0, _normalizeParams.normalizeParams)(toolId, action, raw).params, descriptor.params);
+      if (!(0, _validateParams.validateParams)(params, descriptor.params).ok) return undefined;
+      const verdict = (0, _policy.decide)({
+        descriptor,
+        toolId,
+        policy,
+        isRelease
+      });
+      return {
+        call,
+        toolId,
+        action,
+        descriptor,
+        params,
+        label: (0, _policy.describeCall)(toolId, descriptor, params),
+        mutates: descriptor.effect !== "read",
+        gated: verdict.verdict === "needs-approval",
+        reason: verdict.verdict === "needs-approval" ? verdict.reason : ""
+      };
+    });
+    const gatedInBatch = planned.some(p => p?.gated);
+    /** Decisions the barrier has already taken, so no call is asked twice. */
+    const decided = new Map();
+    let barrierRun = false;
+    let batchDeclined = false;
+
+    /** Put every gated call in the batch to the user, in the order written. */
+    async function* runBarrier() {
+      barrierRun = true;
+      for (const p of planned) {
+        if (!p?.gated || decided.has(p.call.id)) continue;
+        yield {
+          type: "approval-required",
+          id: p.call.id,
+          toolId: p.toolId,
+          action: p.action,
+          label: p.label,
+          description: p.descriptor.summary,
+          reason: p.reason
+        };
+        const askedAt = Date.now();
+        const targetDigest = await readTargetDigest({
+          toolId: p.toolId,
+          action: p.action,
+          params: p.params,
+          dispatch,
+          catalog
+        });
+        const approved = requestApproval ? await requestApproval({
+          id: p.call.id,
+          toolId: p.toolId,
+          action: p.action,
+          label: p.label,
+          description: p.descriptor.summary,
+          reason: p.reason,
+          params: p.params,
+          targetDigest
+        }) : false;
+        // The user's deliberation is not the agent's runtime.
+        deadline += Date.now() - askedAt;
+        decided.set(p.call.id, approved);
+        if (!approved) {
+          // One refusal ends the PLAN, not just the call. The remaining
+          // changes were proposed together and nothing has run yet, so
+          // carrying on with the rest would apply half of something the user
+          // has just turned down.
+          batchDeclined = true;
+          return;
+        }
+      }
+    }
     for (const call of calls) {
+      /**
+       * Stop was pressed while this batch was running.
+       *
+       * The abort signal used to be read only at the top of a ROUND, so a
+       * response carrying three calls ran all three after the tap — and the
+       * bubble then said "Stopped." over two writes the user believed it had
+       * prevented. Each call now checks before it starts. A dispatch already
+       * in flight is left to finish (nothing can pull a store write back out
+       * of an adapter) and keeps its receipt; everything after it is reported
+       * as not run, each as its own row, so the transcript says exactly which
+       * changes landed. A result is still pushed for every call — the provider
+       * requires one per tool_use or the next request is rejected.
+       */
+      if (signal?.aborted) {
+        // A `buoy_ui` card that was never shown is not a step; no row for it.
+        if (call.name !== _uiTool.UI_TOOL_NAME) {
+          for (const ev of stoppedStep(call)) yield ev;
+        }
+        results.push({
+          toolCallId: call.id,
+          content: "Not run — the user pressed Stop before this call started.",
+          isError: true
+        });
+        continue;
+      }
+
       // `buoy_ui`: show or ask. Validated like any action; an Ask block ends
       // the turn after this batch — the answer comes back as a user message.
       if (call.name === _uiTool.UI_TOOL_NAME) {
@@ -222,19 +772,35 @@ async function* runAgentTurn(input) {
         if (!built.ok || !built.block) {
           results.push({
             toolCallId: call.id,
-            content: `Invalid ${_uiTool.UI_TOOL_NAME} block:\n${built.errors.join("\n")}`,
+            /**
+             * The trailing sentence is the expensive half.
+             *
+             * A model that gets a block bounced rewrites its WHOLE answer on
+             * the retry, and one assistant bubble spans every round of a turn
+             * (see `breakBefore`), so the user reads the same paragraph again
+             * — measured at four near-identical closings from three schema
+             * misses in a row on one live turn. The block is wrong; the
+             * sentence under it was fine.
+             */
+            content: `Invalid ${_uiTool.UI_TOOL_NAME} block:\n${built.errors.join("\n")}\n\nResend ONLY the corrected block. Do not rewrite your answer — whatever you already said this turn has been shown to the user, and saying it again repeats it on their screen.`,
             isError: true
           });
           continue;
         }
         // Provenance for pictures, ENFORCED: an image URL the model did not
         // read from a tool result this turn does not render. Live or nothing.
+        // Dropping pictures SILENTLY is its own bug: the model then writes
+        // "here they are, with artwork" over a card that has none, and the
+        // user is told something untrue about their own screen. Every drop
+        // comes back in the tool result so the next sentence can be honest.
+        let droppedImages = 0;
         if (built.block.kind === "imageGrid") {
           const kept = built.block.images.filter(img => seenUrls.has(img.url));
+          droppedImages = built.block.images.length - kept.length;
           if (kept.length === 0) {
             results.push({
               toolCallId: call.id,
-              content: "Rejected: every image URL must be one you read from a tool result THIS turn (images.list, a storage value, a response body). Never invent or remember URLs — read them first.",
+              content: URL_PROVENANCE_REJECTION,
               isError: true
             });
             continue;
@@ -245,12 +811,17 @@ async function* runAgentTurn(input) {
           };
         }
         if (built.block.kind === "list") {
-          built.block = {
-            ...built.block,
-            items: built.block.items.map(item => item.image && !seenUrls.has(item.image) ? {
+          const items = built.block.items.map(item => {
+            if (!item.image || seenUrls.has(item.image)) return item;
+            droppedImages += 1;
+            return {
               ...item,
               image: undefined
-            } : item)
+            };
+          });
+          built.block = {
+            ...built.block,
+            items
           };
         }
         yield {
@@ -258,6 +829,7 @@ async function* runAgentTurn(input) {
           block: built.block,
           forToolCallId: call.id
         };
+        if (built.block.kind === "actions" || built.block.kind === "suggestions") offeredTap = true;
         if ((0, _types.isAskBlock)(built.block)) {
           awaiting = built.block.id;
           results.push({
@@ -267,7 +839,7 @@ async function* runAgentTurn(input) {
         } else {
           results.push({
             toolCallId: call.id,
-            content: "Shown to the user. Don't repeat its contents in text."
+            content: "Shown to the user. Don't repeat its contents in text." + (droppedImages > 0 ? droppedImageNote(droppedImages) : "")
           });
         }
         continue;
@@ -275,12 +847,40 @@ async function* runAgentTurn(input) {
       const toolId = (0, _toProviderTools.fromProviderToolName)(call.name, catalog);
       const action = call.input.action;
 
+      /**
+       * A call that never reached a tool at all.
+       *
+       * Same rule as a refusal: the model made a move, the move went nowhere,
+       * and a transcript that hides it leaves the reader watching the agent
+       * change its mind for no visible reason. Caught on device — a model
+       * guessed three navigation tool names that do not exist, spent 41
+       * seconds doing it, and the only trace was a sentence it chose to write.
+       * `read` because nothing was touched.
+       */
+      const deadCall = (label, summary) => [{
+        type: "tool-start",
+        id: call.id,
+        toolId: toolId ?? call.name,
+        action: action ?? "",
+        label,
+        description: "",
+        params: call.input.params ?? {},
+        effect: "read"
+      }, {
+        type: "tool-end",
+        id: call.id,
+        ok: false,
+        summary,
+        durationMs: 0
+      }];
+
       // Two different mistakes, kept apart on purpose. Merging them tells a
       // model that forgot `action` that the TOOL does not exist, and it stops
       // reaching for a tool that was fine — the same distinction
       // `dispatchToolAction` draws between an unknown tool and an unknown
       // action, for the same reason.
       if (!toolId) {
+        for (const ev of deadCall(call.name, "No such tool")) yield ev;
         results.push({
           toolCallId: call.id,
           content: `There is no tool called "${call.name}". Use one of the tools you were given.`,
@@ -289,6 +889,7 @@ async function* runAgentTurn(input) {
         continue;
       }
       if (!action) {
+        for (const ev of deadCall(call.name, "No action given")) yield ev;
         results.push({
           toolCallId: call.id,
           content: `"${call.name}" needs an "action" — it is required, and it names which of this tool's actions to run. See the action list in the tool's description.`,
@@ -302,6 +903,7 @@ async function* runAgentTurn(input) {
         // has nowhere to go but guess again, and the next guess is no better
         // informed than the last.
         const known = catalog.find(t => t.toolId === toolId)?.actions.map(a => a.action).join(", ");
+        for (const ev of deadCall(`${toolId}.${action}`, "No such action")) yield ev;
         results.push({
           toolCallId: call.id,
           content: `"${action}" is not an action on ${toolId}.${known ? ` Valid actions: ${known}.` : ""}`,
@@ -310,7 +912,11 @@ async function* runAgentTurn(input) {
         continue;
       }
       const raw = call.input.params ?? {};
-      const params = (0, _validateParams.applyDefaults)(raw, descriptor.params);
+      // Accept the parameter-name misses every model makes (queryKey for
+      // queryHash, requestId for id, flat rule fields, …) before validation,
+      // so a mechanical alias never costs a turn. See normalizeParams.ts.
+      const normalized = (0, _normalizeParams.normalizeParams)(toolId, action, raw);
+      const params = (0, _validateParams.applyDefaults)(normalized.params, descriptor.params);
       const check = (0, _validateParams.validateParams)(params, descriptor.params);
       if (!check.ok) {
         results.push({
@@ -320,6 +926,7 @@ async function* runAgentTurn(input) {
         });
         continue;
       }
+      const aliasTrailer = (0, _normalizeParams.aliasNote)(normalized.notes);
       const label = (0, _policy.describeCall)(toolId, descriptor, params);
       const verdict = (0, _policy.decide)({
         descriptor,
@@ -327,14 +934,29 @@ async function* runAgentTurn(input) {
         policy,
         isRelease
       });
+
+      // A step the user can SEE, for a call that never ran. `tool-end` alone
+      // updates a row that was never opened, so a refusal used to leave no
+      // trace in the transcript at all — the model simply changed its mind
+      // between one sentence and the next.
+      const unrunStep = summary => [{
+        type: "tool-start",
+        id: call.id,
+        toolId,
+        action,
+        label,
+        description: descriptor.summary,
+        params,
+        effect: descriptor.effect
+      }, {
+        type: "tool-end",
+        id: call.id,
+        ok: false,
+        summary,
+        durationMs: 0
+      }];
       if (verdict.verdict === "refuse") {
-        yield {
-          type: "tool-end",
-          id: call.id,
-          ok: false,
-          summary: "refused",
-          durationMs: 0
-        };
+        for (const ev of unrunStep("refused")) yield ev;
         results.push({
           toolCallId: call.id,
           content: verdict.reason,
@@ -342,25 +964,77 @@ async function* runAgentTurn(input) {
         });
         continue;
       }
-      if (verdict.verdict === "needs-approval") {
-        yield {
-          type: "approval-required",
-          id: call.id,
-          toolId,
-          action,
-          label,
-          description: descriptor.summary,
-          reason: verdict.reason
-        };
-        const approved = requestApproval ? await requestApproval({
-          id: call.id,
-          toolId,
-          action,
-          label,
-          description: descriptor.summary,
-          reason: verdict.reason
-        }) : false;
+
+      /**
+       * Nothing in this batch changes anything until every card in it has been
+       * answered. See `runBarrier` — this is the line that makes a decline
+       * mean "the plan does not happen" rather than "the rest of the plan does
+       * not happen".
+       */
+      const gatedHere = verdict.verdict === "needs-approval";
+      if (gatedInBatch && !barrierRun && (descriptor.effect !== "read" || gatedHere)) {
+        yield* runBarrier();
+      }
+      if (batchDeclined && (descriptor.effect !== "read" || gatedHere)) {
+        for (const ev of unrunStep("declined")) yield ev;
+        results.push({
+          toolCallId: call.id,
+          content: decided.get(call.id) === false ? "The user declined this change. Do not retry it; ask what they would prefer." : "Not run — the user declined another change in this same batch, so none of it was applied. Ask what they would prefer before proposing it again.",
+          isError: true
+        });
+        continue;
+      }
+      if (gatedHere) {
+        let approved;
+        if (decided.has(call.id)) {
+          // The barrier already put this card up, before the batch's first
+          // mutation. Asking again would be the same question twice.
+          approved = decided.get(call.id);
+        } else {
+          // The barrier could not resolve this call (see `planned`), so it was
+          // never offered. Ask here, exactly as this always did — a gate that
+          // fails closed by silently declining would be worse than one that
+          // asks late.
+          yield {
+            type: "approval-required",
+            id: call.id,
+            toolId,
+            action,
+            label,
+            description: descriptor.summary,
+            reason: verdict.reason
+          };
+          const askedAt = Date.now();
+          // What the write is about to replace, as of NOW. Only a restored
+          // card ever reads it back — see readTargetDigest.
+          const targetDigest = await readTargetDigest({
+            toolId,
+            action,
+            params,
+            dispatch,
+            catalog
+          });
+          approved = requestApproval ? await requestApproval({
+            id: call.id,
+            toolId,
+            action,
+            label,
+            description: descriptor.summary,
+            reason: verdict.reason,
+            params,
+            targetDigest
+          }) : false;
+          // The user's deliberation is not the agent's runtime. Give the clock
+          // back before anything else can trip the deadline check.
+          deadline += Date.now() - askedAt;
+          decided.set(call.id, approved);
+        }
         if (!approved) {
+          // The row is the whole point here. Without it the bubble read as a
+          // contradiction — "Bumped the line from 5 to 9." straight into "I
+          // left it as it was" — with nothing on screen to say a change had
+          // been proposed and turned down.
+          for (const ev of unrunStep("declined")) yield ev;
           results.push({
             toolCallId: call.id,
             content: "The user declined this change. Do not retry it; ask what they would prefer.",
@@ -369,6 +1043,7 @@ async function* runAgentTurn(input) {
           continue;
         }
       }
+      if (_askGate.ACQUISITION_CALLS.has(`${toolId}.${action}`)) attemptedAcquisition = true;
       yield {
         type: "tool-start",
         id: call.id,
@@ -385,7 +1060,50 @@ async function* runAgentTurn(input) {
       // exactly. This is the one thing that makes storage reversible here when
       // the Scenarios engine has to treat it as permanent.
       const before = await captureBefore(descriptor, toolId, params, dispatch);
-      const stateBefore = await captureStateBefore(descriptor, toolId, params, dispatch);
+      const stateBefore = await captureStoreState(descriptor, toolId, params, dispatch);
+
+      /**
+       * THE FINAL GUARD. Everything above this line happened in the past.
+       *
+       * `decide()` ran before the approval card went up, and between there and
+       * here are three awaits: the target read, the person deciding, and two
+       * pre-reads. Each one yields the thread, and a person can do a lot in
+       * that gap — press Stop, or flip the read-only toggle in the settings
+       * sheet while the card is still on screen. Both were reproduced: the
+       * write went ahead on the verdict it captured before they touched
+       * anything, which is precisely the moment the product promises it will
+       * not. `live` is mutated in place by the session (see `refreshLive`), so
+       * asking again reads the toggles as they are NOW.
+       *
+       * Below this there is no `await` before `dispatch` is CALLED. That is
+       * load-bearing: an await here would reopen the same gap one line lower.
+       */
+      if (signal?.aborted) {
+        for (const ev of unrunStep("stopped")) yield ev;
+        results.push({
+          toolCallId: call.id,
+          content: "Not run — the user pressed Stop before this call started.",
+          isError: true
+        });
+        continue;
+      }
+      const stillAllowed = (0, _policy.decide)({
+        descriptor,
+        toolId,
+        policy,
+        isRelease
+      });
+      if (stillAllowed.verdict === "refuse") {
+        // `needs-approval` is NOT re-refused: reaching here means the tap
+        // already happened, and asking twice for one call is its own bug.
+        for (const ev of unrunStep("refused")) yield ev;
+        results.push({
+          toolCallId: call.id,
+          content: stillAllowed.reason,
+          isError: true
+        });
+        continue;
+      }
       try {
         // `getSnapshot` is reserved: it is not an adapter action, so it goes to
         // the snapshot reader and is trimmed to the fields worth sending. See
@@ -393,21 +1111,14 @@ async function* runAgentTurn(input) {
         // ledger the model asks about lives HERE, not behind an adapter, so
         // routing it through dispatch would only work on a device and would
         // record the undo as a fresh effect.
-        const result = action === _snapshotReads.SNAPSHOT_ACTION ? (0, _snapshotReads.projectSnapshot)(toolId, await requireSnapshot(readSnapshot, toolId), params) : toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch) : await dispatch(toolId, action, params);
+        const result = action === _snapshotReads.SNAPSHOT_ACTION ? (0, _snapshotReads.projectSnapshot)(toolId, await requireSnapshot(readSnapshot, toolId), params) : toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch) : await (prefetch.get(call.id) ?? dispatch(toolId, action, params));
         const cleaned = (0, _redact.redact)((0, _redact.stripSelfTraffic)(result));
-        if (descriptor.effect !== "read" && toolId !== "ask-buoy") {
-          // A delete of something we created IS the undo, whoever asked for
-          // it — mark the matching entry undone instead of leaving the bar
-          // promising an undo against a rule that no longer exists.
-          ledger.noteExternalRevert(toolId, action, params);
-          const fx = (0, _effectFor.effectFor)(toolId, descriptor, params, result, before);
-          if (fx) ledger.record(toolId, action, fx);
-        }
+        const refused = reportsFailure(result);
         const encodedResult = encodeResult(cleaned);
         yield {
           type: "tool-end",
           id: call.id,
-          ok: true,
+          ok: !refused,
           summary: summarise(result),
           durationMs: Date.now() - startedAt,
           result: encodedResult.length > MAX_TRACE_RESULT_CHARS ? `${encodedResult.slice(0, MAX_TRACE_RESULT_CHARS)}…` : encodedResult
@@ -415,12 +1126,36 @@ async function* runAgentTurn(input) {
 
         // The receipt: what the user sees of this result, built from the
         // same redacted data the model gets. See blocks/receipts.ts.
-        const receipt = (0, _receipts.projectReceipt)({
+        //
+        // The store is read back a second time so the diff shows what the
+        // write ACTUALLY did rather than what it asked for — the two differ on
+        // every `path` edit and every keyed list edit, and the request-shaped
+        // version reported untouched fields as deleted.
+        const stateAfter = stateBefore === undefined || refused ? undefined : await captureStoreState(descriptor, toolId, params, dispatch);
+        if (descriptor.effect !== "read" && toolId !== "ask-buoy" && !refused) {
+          // A delete of something we created IS the undo, whoever asked for
+          // it — mark the matching entry undone instead of leaving the bar
+          // promising an undo against a rule that no longer exists.
+          ledger.noteExternalRevert(toolId, action, params);
+          // Recorded AFTER the read-back so a cache edit's entry can carry both
+          // halves: the data to restore and a fingerprint of what the write
+          // left behind, which is how undo knows whether the app has since
+          // replaced it. See effectFor / ledger "query-write".
+          const fx = (0, _effectFor.effectFor)(toolId, descriptor, params, result, before, {
+            before: stateBefore,
+            after: stateAfter
+          });
+          if (fx) ledger.record(toolId, action, fx, ledgerGeneration);
+        }
+        // No receipt for a call that changed nothing: a "what changed" card
+        // under a refusal is the same lie as the ledger entry, drawn bigger.
+        const receipt = refused ? undefined : (0, _receipts.projectReceipt)({
           toolId,
           action,
           params,
           result: cleaned,
           before: stateBefore ?? before,
+          after: stateAfter,
           effect: descriptor.effect
         });
         if (receipt) yield {
@@ -431,7 +1166,7 @@ async function* runAgentTurn(input) {
         for (const url of encodedResult.match(URL_RE) ?? []) seenUrls.add(url);
         results.push({
           toolCallId: call.id,
-          content: encodedResult + ownedKeyNote(toolId, descriptor, params, storeKeyOwners)
+          content: encodedResult + ownedKeyNote(toolId, descriptor, params, storeKeyOwners) + aliasTrailer + (salvagedIds.has(call.id) ? _textToolCalls.SALVAGE_NOTE : "")
         });
         if (toolId === "app" && (action === "reloadApp" || action === "reload")) {
           realmWillDie = true;
@@ -452,6 +1187,20 @@ async function* runAgentTurn(input) {
         });
       }
     }
+
+    // Looping? Say so, once, on the LAST result of this round — so it arrives
+    // attached to the thing being repeated rather than as a free-floating
+    // user turn, and the model reads it before deciding what to do next.
+    if (calls.length) {
+      recentSignatures.push(callSignature(calls));
+      if (recentSignatures.length > LOOP_REPEATS) recentSignatures.shift();
+      const looping = !loopWarned && recentSignatures.length === LOOP_REPEATS && recentSignatures.every(sig => sig === recentSignatures[0]);
+      if (looping) {
+        loopWarned = true;
+        const last = results[results.length - 1];
+        if (last) last.content = `${last.content}\n\n${LOOP_WARNING}`;
+      }
+    }
     messages.push({
       role: "tool-results",
       results
@@ -516,6 +1265,27 @@ function ownedKeyNote(toolId, descriptor, params, storeKeyOwners) {
   if (!storeName) return "";
   return `\n\n[Buoy] This wrote to disk, but "${params.key}" is the saved copy of the live "${storeName}" store, so nothing on screen has changed — the app read that key once at startup and has held the state in memory since. Call zustand.rehydrate({"storeName":"${storeName}"}) to make the app pick this up, or use zustand.setState next time to change the store directly. If you meant to set the value for the app's next launch, this is already done and no further action is needed.`;
 }
+/**
+ * Fingerprint the value a write is about to replace.
+ *
+ * Built for the approval card that outlives its turn: the app crashed with
+ * "Set bag line L-01 qty to 14" still asking, relaunched, and the card came
+ * back — and Allow wrote qty 14 against whatever the bag was NOW, maybe a
+ * different account, maybe a line that no longer existed. A hash of the
+ * params alone would not catch that (same label, same params, different
+ * world). So the card carries a digest of the TARGET at ask time, and a
+ * restored Allow re-reads and compares before it writes. Undefined when the
+ * target cannot be read — then the card can only warn, not check.
+ */
+async function readTargetDigest(input) {
+  const descriptor = findDescriptor(input.catalog ?? _catalog.CATALOG, input.toolId, input.action);
+  if (!descriptor || descriptor.effect === "read") return undefined;
+  const store = await captureStoreState(descriptor, input.toolId, input.params, input.dispatch);
+  if (store !== undefined) return (0, _digest.digestOf)(store);
+  const before = await captureBefore(descriptor, input.toolId, input.params, input.dispatch);
+  if (before !== undefined) return (0, _digest.digestOf)(before);
+  return undefined;
+}
 /**
  * One human-initiated action through EVERY gate the model's calls go through:
  * catalog lookup, param validation, policy, pre-read, effect ledger.
@@ -548,7 +1318,8 @@ async function runGatedAction(input) {
       error: `${toolId}.${action} is not in Buoy's catalog.`
     };
   }
-  const params = (0, _validateParams.applyDefaults)(input.params ?? {}, descriptor.params);
+  const normalized = (0, _normalizeParams.normalizeParams)(toolId, action, input.params ?? {});
+  const params = (0, _validateParams.applyDefaults)(normalized.params, descriptor.params);
   const check = (0, _validateParams.validateParams)(params, descriptor.params);
   if (!check.ok) {
     return {
@@ -569,11 +1340,51 @@ async function runGatedAction(input) {
     };
   }
   const before = await captureBefore(descriptor, toolId, params, dispatch);
+  /**
+   * The same read-back the model's path takes. It was missing here, and the
+   * gap was invisible: a `setQueryData` through a block button or a restored
+   * approval card recorded a ledger entry with no prior value, so Undo had
+   * nothing to put back and the concurrent-writer check had no fingerprint to
+   * compare. The bar said "1 undoable" over a change that could not be undone.
+   */
+  const stateBefore = await captureStoreState(descriptor, toolId, params, dispatch);
+
+  // Asked again after the pre-reads, for the same reason the model's path asks
+  // again: those are awaits, and read-only can be switched on inside one.
+  const stillAllowed = (0, _policy.decide)({
+    descriptor,
+    toolId,
+    policy,
+    isRelease
+  });
+  if (stillAllowed.verdict === "refuse") {
+    return {
+      ok: false,
+      error: stillAllowed.reason
+    };
+  }
   try {
     const result = toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch) : await dispatch(toolId, action, params);
+
+    // Same rule as the model's path: a resolved `{ok:false}` is a refusal, not
+    // a change. Without this a block button (or an approval answered after a
+    // reload) put a phantom entry in the undo bar too.
+    if (reportsFailure(result)) {
+      const err = result.error;
+      return {
+        ok: false,
+        error: typeof err === "string" ? err : "The tool refused this."
+      };
+    }
     if (descriptor.effect !== "read" && toolId !== "ask-buoy") {
       ledger.noteExternalRevert(toolId, action, params);
-      const fx = (0, _effectFor.effectFor)(toolId, descriptor, params, result, before);
+      // Read back AFTER the write, exactly as the model's path does — the two
+      // halves together are what make a cache edit undoable.
+      const stateAfter = await captureStoreState(descriptor, toolId, params, dispatch);
+      const fx = (0, _effectFor.effectFor)(toolId, descriptor, params, result, before, {
+        before: stateBefore,
+        after: stateAfter
+      });
       if (fx) ledger.record(toolId, action, fx);
     }
     return {
@@ -645,16 +1456,46 @@ async function requireSnapshot(readSnapshot, toolId) {
  * Zustand only for now: `getStoreState` is cheap and the write params carry
  * the after-state, so the diff is exact without the store's cooperation.
  */
-async function captureStateBefore(descriptor, toolId, params, dispatch) {
-  if (toolId !== "zustand" || descriptor.action !== "setState") return undefined;
-  if (typeof params.storeName !== "string") return undefined;
-  try {
-    return await dispatch(toolId, "getStoreState", {
-      storeName: params.storeName
-    });
-  } catch {
-    return undefined;
+/**
+ * Read a zustand store whole, for the before/after halves of a write receipt.
+ * Called on both sides of the dispatch — see the receipt above.
+ */
+async function captureStoreState(descriptor, toolId, params, dispatch) {
+  if (toolId === "zustand" && descriptor.action === "setState") {
+    if (typeof params.storeName !== "string") return undefined;
+    try {
+      return await dispatch(toolId, "getStoreState", {
+        storeName: params.storeName
+      });
+    } catch {
+      return undefined;
+    }
+  }
+  /**
+   * The same read-both-sides trick for the CACHE.
+   *
+   * A zustand edit produced a "what changed" card and the identical edit to a
+   * query produced nothing — for the write the prompt calls "THE way to change
+   * what a server-backed screen shows". The QA tester's confirmation that the
+   * right field moved was missing from the most-used tool in the product.
+   */
+  if (toolId === "query" && descriptor.action === "setQueryData") {
+    // hashQueryKey, not JSON.stringify: React Query SORTS object keys when it
+    // hashes, so a key carrying `{query:"",category:null}` hashes as
+    // `{"category":null,"query":""}`. Stringifying in insertion order produced
+    // a hash that matched nothing, the read came back empty, and the card
+    // silently did not draw.
+    const queryHash = typeof params.queryHash === "string" ? params.queryHash : Array.isArray(params.queryKey) ? (0, _normalizeParams.hashQueryKey)(params.queryKey) : undefined;
+    if (!queryHash) return undefined;
+    try {
+      return await dispatch(toolId, "getQueryData", {
+        queryHash
+      });
+    } catch {
+      return undefined;
+    }
   }
+  return undefined;
 }
 async function captureBefore(descriptor, toolId, params, dispatch) {
   if (descriptor.effect === "read") return undefined;