From 675546aeed6f9c4b2838da8e58006fdba3af332b Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Sat, 10 Oct 2026 15:12:11 -0400
Subject: [PATCH 01/16] fix(guard): a withheld tool result says where its
 original is (#277)

agent-framework #277 (slimepriestess): a materialize receipt that listed a
clobbered LOG.md was withheld by the tool-result guard after the model's
response to it drew a refusal, and the agent was left with only "Tool
result withheld by the guard. The tool has already executed.": the record
of what the tool did was unreachable. The guard keeps every original in its
Chronicle audit slot, but the agent can't read that, and the notice didn't
say where anything was.

The maintainers chose (room-534, #67477 then #67560):
- spill and name: each withheld original goes where the inline cap's spill
  already puts oversized output, and the stub names the file; with no
  writable mount, the stub says the original is in the guard's audit record
  for an operator;
- (a) for the stub's wording: #159's neutral notice stays exactly as it is,
  followed only by the place. No refusal and no category enter the context
  (#159 keeps those in operational logs and pins it with a test), so
  reading the original back is the agent's informed choice;
- every withheld settlement gets it, not only a refusal: an aborted stream,
  a batch never submitted, and one whose audit sync failed.

How:
- ToolResultGuard.settle() starts an annotation for every withheld batch.
  It writes each stored tool_result (exactly what acceptance would have
  admitted) through its host's spiller to
  `<mount>/tool-results/<date>-withheld-<toolUseId>.txt`, then edits the
  placeholder message so each notice is followed by the place
  (withheldResultNotice): the file; or a failed write and the audit record;
  or the audit record alone. A batch whose audit sync failed says that
  saving the record had failed when the stub was written. "withheld" comes
  before the id so the label can never collide with the inline spill's
  `<date>-<id>` when an id is long enough for the 80-character cut.
- It edits only its own unedited placeholder on its branch, as the
  acceptance retry does: an operator's edit, removal or rollback stands,
  and the audit record says `historyUpdate: 'superseded'`. Each annotation
  appends an `annotated` audit record with each result's path or error.
- The compression hold passes from the settlement to the annotation, so no
  summary is made of a stub that doesn't yet say where its original went.
  The chain never rejects: a failure is logged and the hold is released.
- whenAnnotated(): Agent.startStream and runInferenceWithInjections await it
  after flushUnrecorded, so no request (the refusal retry included) is
  compiled with a stub still being written. The direct API's in-place
  refusal retry awaits it and carries the stored stubs.
- stop() waits for every annotation still running before modules stop, so
  an aborted batch's file is written while the workspace is up and its stub
  is saved before close. The guard registers each annotation with its host
  (WithheldHost.track) and the framework keeps the set, because an
  ephemeral run or a closed fork leaves the agent map while an annotation
  its aborted batch started can still be running (Petra-1012's review).
- The framework's writeToolResultFile() is now the one writer for both the
  inline cap's spill and withheld originals (first writable mount,
  tool-results/, a failed write traced as tool:spill_failed and logged).
  spillOrTruncate keeps its exact texts. adoptToolResultGuard() (was
  restoreToolResultGuardSetting) gives each new agent's guard its persisted
  setting and its host (that writer, and the tracking), at all four
  construction sites.

Tests (tool-result-guard, 47; silent-heartbeat-rows updated):
- with a workspace: the stub names `work/tool-results/<date>-withheld-one.txt`,
  the file holds exactly the staged stored text, the refusal retry already
  carries the stub, no refusal/category appears, and the audit's last record
  is `annotated` with the path;
- a mount that refuses the write (maxFileSize 4): the stub says the write
  failed and the original is kept only in the audit record;
- a slow spiller: the refusal retry is still compiled with the annotated stub;
- an operator's edit made while the spill is pending stands (superseded), and
  the hold is held until the annotation ends;
- stop with an aborted batch's annotation in flight: after a restart the stub
  is annotated, so it was saved before close;
- stop with an annotation in flight from an ephemeral run already disposed:
  after a restart the audit holds its `annotated` record;
- the four stub texts, as literals;
- the direct API: after an aborted batch with a slow spiller, the next
  request carries the annotated stub, and the in-place refusal retry does too.
- Existing assertions that a withheld result's content is exactly the notice
  now expect the audit-record stub (no workspace in those harnesses), or its
  failed-save form for the two failed-sync tests; audit sequences gain the
  trailing `annotated`; the two hold tests await whenAnnotated(), and the
  withhold one first asserts the hold is still held.
- Removals, each failing its tests: settle never annotating (18 fail),
  releasing the hold at settle, either compile-path await, stop's await,
  stop waiting only for agents still in the map, the guard never tracking
  an annotation, overwriting an operator's edit, the spiller not wired, the
  direct retry's await, and the stub ignoring a failed save.

Reviewed by Petra-1012 (Claude Opus 5.5), who found the disposed-agent gap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../guard-withheld-names-original.fixed.md    |  12 +
 src/agent.ts                                  |  16 +-
 src/framework.ts                              | 125 +++++----
 src/tool-result-guard.ts                      | 111 +++++++-
 test/silent-heartbeat-rows.test.ts            |   4 +-
 test/tool-result-guard.test.ts                | 251 ++++++++++++++++--
 6 files changed, 452 insertions(+), 67 deletions(-)
 create mode 100644 changelog.d/guard-withheld-names-original.fixed.md

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
new file mode 100644
index 000000000..3e341796f
--- /dev/null
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -0,0 +1,12 @@
+- A tool result the guard withholds now says where its original is. The
+  guard's notice ("Tool result withheld by the guard. The tool has already
+  executed.") is followed by the original's place: a workspace file under the
+  first writable mount's `tool-results/` (named `<date>-withheld-<toolUseId>`),
+  or, with no writable workspace or a failed write, the guard's audit record
+  (`framework/tool-result-guard`), for an operator. This holds for every
+  withheld settlement: a refusal, an aborted stream, a batch that was never
+  submitted, and one whose audit sync failed. The notice still names no
+  refusal and no category. The stub is written before any request is compiled,
+  including the refusal retry, and before stop closes the store. Before this,
+  a withheld result left only the notice, so the agent couldn't tell what the
+  tool had done (agent-framework #277).
diff --git a/src/agent.ts b/src/agent.ts
index 412707a33..bf4d48d0c 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -655,6 +655,8 @@ export class Agent {
     }
 
     this.toolResultGuard.flushUnrecorded();
+    // A withheld stub is compiled only once it says where its original went.
+    await this.toolResultGuard.whenAnnotated();
 
     // Filter tools to only allowed ones
     const tools = availableTools.filter((t) => this.canUseTool(t.name));
@@ -935,6 +937,8 @@ export class Agent {
     // Retry accepted history edits before assembling a real request. Pure
     // preview/compile entry points must not perform these writes.
     this.toolResultGuard.flushUnrecorded();
+    // A withheld stub is compiled only once it says where its original went.
+    await this.toolResultGuard.whenAnnotated();
 
     // A new activation supersedes every receipt flight the previous one left
     // open. Membrane fires the kv-unified wire receipt per provider attempt,
@@ -1192,9 +1196,19 @@ export class Agent {
       if (ids) {
         abandonedUsage = response.usage;
         const withheld = new Set(ids);
+        // The retry carries the stubs as stored: each says where its original
+        // went (agent-framework #277), once the guard has written that.
+        await this.toolResultGuard.whenAnnotated();
+        const stubs = new Map<string, Extract<ContentBlock, { type: 'tool_result' }>['content']>();
+        for (const message of this.contextManager.getAllMessages()) {
+          for (const block of message.content) {
+            if (block.type === 'tool_result' && withheld.has(block.toolUseId)) stubs.set(block.toolUseId, block.content);
+          }
+        }
         request = { ...request, messages: request.messages.map((message) => ({
           ...message, content: message.content.map((block) => block.type === 'tool_result' && withheld.has(block.toolUseId)
-            ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError } : block),
+            ? { type: 'tool_result', toolUseId: block.toolUseId,
+              content: stubs.get(block.toolUseId) ?? TOOL_RESULT_GUARD_NOTICE, isError: block.isError } : block),
         })) };
         response = await this.membrane.stream(request, { signal });
       }
diff --git a/src/framework.ts b/src/framework.ts
index 349bdd693..5f449de67 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -2018,6 +2018,12 @@ export class AgentFramework {
     this.eventGate?.dispose();
     this.livenessWatchdog?.stop();
 
+    // A stopping stream's batch settles as withheld, and its stub names where
+    // the original went: let those writes finish while the workspace is up.
+    // Tracked here rather than per agent, since an ephemeral run or a closed
+    // fork leaves the agent map while its annotation can still be running.
+    while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
+
     // Stop modules and MCPL servers in parallel
     const shutdownPromises: Promise<void>[] = [this.moduleRegistry.stopAll()];
     if (this.mcplServerRegistry) {
@@ -2694,7 +2700,13 @@ export class AgentFramework {
     };
   }
 
-  private restoreToolResultGuardSetting(agent: Agent): void {
+  /** Every guard's annotation still running, for stop() (agent-framework #277). */
+  private readonly guardAnnotations = new Set<Promise<void>>();
+
+  /** A new agent's guard: its persisted setting, the tool-results spill its
+   *  withheld originals are written to, and the set stop() waits on
+   *  (agent-framework #277). */
+  private adoptToolResultGuard(agent: Agent): void {
     const enabled = (this.store.getStateJson(FRAMEWORK_STATE_ID) as {
       toolResultGuards?: Record<string, unknown>;
     } | null)?.toolResultGuards?.[agent.name];
@@ -2702,6 +2714,13 @@ export class AgentFramework {
       throw new Error(`Invalid persisted tool_result_guard for ${agent.name}: expected a boolean`);
     }
     agent.toolResultGuard.setOverride(enabled);
+    agent.toolResultGuard.setHost({
+      spill: (label, text) => this.writeToolResultFile(label, text),
+      track: (annotation) => {
+        this.guardAnnotations.add(annotation);
+        void annotation.finally(() => this.guardAnnotations.delete(annotation));
+      },
+    });
   }
 
   private buildThinkTool(
@@ -4151,7 +4170,7 @@ export class AgentFramework {
       });
 
       const agent = new Agent(config, contextManager, this.membrane);
-      this.restoreToolResultGuardSetting(agent);
+      this.adoptToolResultGuard(agent);
       agent.markContextConsumed(); // RFC-006: nothing stored before now is replaceable
       this.ephemeralCandidates.set(agent, contextManager);
 
@@ -6457,7 +6476,7 @@ export class AgentFramework {
     });
 
     const agent = new Agent(config, contextManager, this.membrane);
-    this.restoreToolResultGuardSetting(agent);
+    this.adoptToolResultGuard(agent);
     agent.markContextConsumed(); // RFC-006: nothing stored before now is replaceable
     this.sharedSlotAgents.add(agent);
     const restoredSettings = this.readAgentRuntimeSettings(config.name);
@@ -6534,7 +6553,7 @@ export class AgentFramework {
       allowedTools: [...SUBCONSCIOUS_TOOL_NAMES, 'think', 'skip_reply', 'end_turn'],
     };
     const agent = new Agent(agentConfig, contextManager, this.membrane);
-    this.restoreToolResultGuardSetting(agent);
+    this.adoptToolResultGuard(agent);
     agent.markContextConsumed(); // RFC-006: nothing stored before now is replaceable
     this.sharedSlotAgents.add(agent); // reads the shared slot through its merged view
     this.agents.set(name, agent);
@@ -7386,7 +7405,7 @@ export class AgentFramework {
 
       const config: AgentConfig = { ...templateConfig, name, strategy: undefined };
       const agent = new Agent(config, contextManager, this.membrane);
-      this.restoreToolResultGuardSetting(agent);
+      this.adoptToolResultGuard(agent);
       agent.markContextConsumed(); // RFC-006: nothing stored before now is replaceable
       this.agents.set(name, agent);
       this.agentConfigs.set(name, config);
@@ -11704,6 +11723,40 @@ export class AgentFramework {
     return { blocks, spilled };
   }
 
+  /**
+   * Write one tool result's text to `<first writable mount>/tool-results/
+   * <label>.txt`: the one place both the inline cap's spill and the guard's
+   * withheld originals go. null when there is no writable workspace. A failed
+   * write is reported, traced and logged here, never thrown.
+   */
+  private async writeToolResultFile(label: string, content: string): Promise<{ path: string; error?: string } | null> {
+    const workspace = this.getWorkspaceModule();
+    const mountName = workspace ? this.firstWritableMountName(workspace) : null;
+    if (!workspace || !mountName) return null;
+    const safeLabel = label.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
+    const path = `${mountName}/tool-results/${safeLabel}.txt`;
+    let failure: string;
+    try {
+      const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain');
+      if (result.success) return { path };
+      failure = result.error ?? 'write refused';
+    } catch (err) {
+      failure = err instanceof Error ? err.message : String(err);
+    }
+    failure = failure.slice(0, 200);
+    this.emitTrace({
+      type: 'tool:spill_failed',
+      label: safeLabel,
+      path,
+      contentLength: content.length,
+      error: failure,
+    });
+    console.error(
+      `[spill] workspace write failed for ${path} (${content.length} chars): ${failure}`,
+    );
+    return { path, error: failure };
+  }
+
   private async spillOrTruncate(
     content: string,
     cap: number | undefined,
@@ -11718,52 +11771,32 @@ export class AgentFramework {
     const { head, tail } = splitPreservingImageSlots(content, cap);
     const kept = formatPreservedImageSlots(tail);
 
-    const workspace = this.getWorkspaceModule();
-    const mountName = workspace ? this.firstWritableMountName(workspace) : null;
-    if (workspace && mountName) {
-      const safeLabel = label.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
-      const path = `${mountName}/tool-results/${safeLabel}.txt`;
-      let failure: string;
-      try {
-        const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain');
-        if (result.success) {
-          // JSON serialization can expand each read-back code unit to six
-          // chars (\\u0000). Leave room for the page's metadata and a possible
-          // extra code unit at a surrogate-pair boundary.
-          const pageOverhead = JSON.stringify(path).length + 256;
-          const readLimit = Math.max(1, Math.min(2000, Math.floor((cap - pageOverhead) / 6) - 1));
-          return {
-            text: head
-              + `\n\n[truncated — showing ${head.length} of ${content.length} chars; full content: workspace file ${path}`
-              + `. Page with workspace--read ${JSON.stringify({ path, offsetChars: 0, limitChars: readLimit })}; `
-              + 'use nextOffsetChars as offsetChars until null, keeping limitChars. Or raise the inline cap via '
-              + 'agent_settings update tool_result_inline_max_chars.]'
-              + kept,
-            filePath: path,
-          };
-        }
-        failure = result.error ?? 'write refused';
-      } catch (err) {
-        failure = err instanceof Error ? err.message : String(err);
-      }
+    const written = await this.writeToolResultFile(label, content);
+    if (written && written.error === undefined) {
+      const path = written.path;
+      // JSON serialization can expand each read-back code unit to six
+      // chars (\\u0000). Leave room for the page's metadata and a possible
+      // extra code unit at a surrogate-pair boundary.
+      const pageOverhead = JSON.stringify(path).length + 256;
+      const readLimit = Math.max(1, Math.min(2000, Math.floor((cap - pageOverhead) / 6) - 1));
+      return {
+        text: head
+          + `\n\n[truncated — showing ${head.length} of ${content.length} chars; full content: workspace file ${path}`
+          + `. Page with workspace--read ${JSON.stringify({ path, offsetChars: 0, limitChars: readLimit })}; `
+          + 'use nextOffsetChars as offsetChars until null, keeping limitChars. Or raise the inline cap via '
+          + 'agent_settings update tool_result_inline_max_chars.]'
+          + kept,
+        filePath: path,
+      };
+    }
+    if (written) {
       // A workspace was there and the write FAILED — say that, loudly and
       // distinctly. Telling the agent "no writable workspace" would teach
       // them their residence lacks a capability it actually has.
-      failure = failure.slice(0, 200);
-      this.emitTrace({
-        type: 'tool:spill_failed',
-        label: safeLabel,
-        path,
-        contentLength: content.length,
-        error: failure,
-      });
-      console.error(
-        `[spill] workspace write failed for ${path} (${content.length} chars): ${failure}`,
-      );
       return {
         text: head
-          + `\n\n[truncated — showing ${head.length} of ${content.length} chars; spill to workspace file ${path} FAILED`
-          + ` (${failure}); content over the cap was not retained]`
+          + `\n\n[truncated — showing ${head.length} of ${content.length} chars; spill to workspace file ${written.path} FAILED`
+          + ` (${written.error}); content over the cap was not retained]`
           + kept,
         filePath: null,
       };
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 46a93dcd5..26e306568 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -8,6 +8,42 @@ import { isStateExistsError } from './module-registry.js';
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
+/** Where a withheld result's original was written: a workspace path, the
+ *  path a write to it failed at, or null when there is no writable workspace. */
+export type WithheldSpill = { path: string; error?: string } | null;
+
+/** Writes one withheld original as a workspace file (the framework's
+ *  tool-results spill). It reports a failed write rather than throwing. */
+export type WithheldSpiller = (label: string, text: string) => Promise<WithheldSpill>;
+
+/** What a host gives a guard for its withheld results: where originals are
+ *  written, and where each annotation is registered, so the host's stop can
+ *  wait for it even after the agent itself was disposed. */
+export interface WithheldHost {
+  spill: WithheldSpiller;
+  track(annotation: Promise<void>): void;
+}
+
+/**
+ * The stub a withheld result settles to: #159's neutral notice, then where
+ * the original is. It names no refusal and no category (#159 keeps those in
+ * operational logs), only the place, so reading it back is the agent's
+ * deliberate choice (agent-framework #277).
+ */
+export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean): string {
+  const audit = auditDurable
+    ? `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`
+    : `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator, though saving that record had failed when this was written`;
+  if (spill && spill.error === undefined) {
+    return `${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${spill.path}.`;
+  }
+  if (spill) {
+    return `${TOOL_RESULT_GUARD_NOTICE} Writing its full result to workspace file ${spill.path} failed (${spill.error}), ` +
+      `so it is kept only in ${audit}.`;
+  }
+  return `${TOOL_RESULT_GUARD_NOTICE} Its full result is kept in ${audit}.`;
+}
+
 interface PendingBatch {
   id: string;
   messageId: MessageId;
@@ -43,6 +79,11 @@ export class ToolResultGuard {
   private override: boolean | undefined;
   /** True until a recovery produces a clean response/new tool round. */
   recovering = false;
+  /** Writes withheld originals where the agent can read them; without it,
+   *  a stub names only the audit record. */
+  private host: WithheldHost | undefined;
+  /** Annotations of withheld stubs, chained in settlement order. */
+  private annotating: Promise<void> | undefined;
 
   constructor(
     private readonly agentName: string,
@@ -51,6 +92,11 @@ export class ToolResultGuard {
   ) {}
 
   get enabled(): boolean { return this.override ?? this.configured; }
+  setHost(host: WithheldHost | undefined): void { this.host = host; }
+  /** Settles once every withheld stub settled so far names where its
+   *  original is (or that edit was given up). A request is compiled only
+   *  after this, so no request carries a stub that is still being written. */
+  whenAnnotated(): Promise<void> { return this.annotating ?? Promise.resolve(); }
   setOverride(value: boolean | undefined): void { this.override = value; }
   get settingOverride(): boolean | undefined { return this.override; }
   get hasPending(): boolean { return this.pending !== undefined; }
@@ -290,7 +336,8 @@ export class ToolResultGuard {
 
   /** Transfer ownership from provider admission to an ordered storage job.
    * Failure retains the accepted payload and its hold until the edit succeeds.
-   * Withheld content is final already, so audit failures cannot keep it held. */
+   * A withheld batch's hold passes to its annotation instead, so no summary
+   * is made of a stub that doesn't yet say where its original went. */
   private settle(pending: PendingBatch, record: Record<string, unknown>, admit: boolean): void {
     this.pending = undefined;
     const operation: AuditOperation = {
@@ -298,8 +345,9 @@ export class ToolResultGuard {
         batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch },
       ...(admit ? { admission: { messageId: pending.messageId, content: pending.content,
         expected: pending.withheld, branch: pending.branch } } : {}),
-      heldMessageId: pending.messageId,
+      heldMessageId: admit ? pending.messageId : undefined,
     };
+    if (!admit) this.annotate(pending);
     this.unrecorded.push(operation);
     try {
       this.flushUnrecorded();
@@ -310,6 +358,65 @@ export class ToolResultGuard {
     }
   }
 
+  /**
+   * Turn a withheld batch's notices into stubs that say where each original
+   * is (agent-framework #277): written to the workspace when a writable mount
+   * takes it, else kept in the audit record. Its own unedited placeholder is
+   * the only thing it edits: an operator's later edit, removal or rollback
+   * stands. It releases the compression hold when done, whatever happened.
+   */
+  private annotate(pending: PendingBatch): void {
+    const previous = this.annotating ?? Promise.resolve();
+    const run = previous.then(async () => {
+      try {
+        const date = new Date().toISOString().slice(0, 10);
+        const spills = new Map<string, WithheldSpill>();
+        for (const block of pending.content) {
+          if (block.type !== 'tool_result') continue;
+          const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
+          let spill: WithheldSpill = null;
+          if (this.host) {
+            try {
+              spill = await this.host.spill(`${date}-withheld-${block.toolUseId}`, original);
+            } catch (error) {
+              console.error(`[tool-result-guard] agent=${this.agentName} could not spill withheld result ` +
+                `${block.toolUseId}:`, error);
+            }
+          }
+          spills.set(block.toolUseId, spill);
+        }
+        const annotated: ContentBlock[] = pending.withheld.map((block) => block.type === 'tool_result'
+          && spills.has(block.toolUseId)
+          ? { ...block, content: withheldResultNotice(spills.get(block.toolUseId)!, pending.durable) }
+          : block);
+        const sameBranch = this.cm.currentBranch().name === pending.branch;
+        const current = sameBranch ? this.cm.getMessage(pending.messageId) : null;
+        const unedited = current !== null && current !== undefined
+          && isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(pending.withheld)));
+        if (unedited) this.cm.editMessage(pending.messageId, annotated);
+        this.append({
+          type: 'annotated', batchId: pending.id, messageId: pending.messageId,
+          results: [...spills].map(([toolUseId, spill]) => ({
+            toolUseId, ...(spill ? { path: spill.path } : {}), ...(spill?.error !== undefined ? { error: spill.error } : {}),
+          })),
+          ...(unedited ? {} : { historyUpdate: 'superseded' }),
+        });
+      } catch (error) {
+        console.error(`[tool-result-guard] agent=${this.agentName} could not annotate withheld results:`, error);
+      } finally {
+        // Never rejects: a compile and stop() wait on this chain.
+        try {
+          this.releaseHold(pending.messageId);
+        } catch (error) {
+          console.error(`[tool-result-guard] agent=${this.agentName} could not release a withheld batch's hold:`, error);
+        }
+      }
+    });
+    this.annotating = run;
+    void run.finally(() => { if (this.annotating === run) this.annotating = undefined; });
+    this.host?.track(run);
+  }
+
   private releaseOperationHold(operation: AuditOperation): void {
     if (operation.heldMessageId !== undefined) {
       this.releaseHold(operation.heldMessageId);
diff --git a/test/silent-heartbeat-rows.test.ts b/test/silent-heartbeat-rows.test.ts
index 618d45257..3a17652c5 100644
--- a/test/silent-heartbeat-rows.test.ts
+++ b/test/silent-heartbeat-rows.test.ts
@@ -17,7 +17,7 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { AgentFramework } from '../src/index.js';
 import type { AgentConfig, Module, ModuleContext, ToolCall, ToolDefinition, ToolResult } from '../src/index.js';
-import { TOOL_RESULT_GUARD_NOTICE } from '../src/tool-result-guard.js';
+import { TOOL_RESULT_GUARD_NOTICE, withheldResultNotice } from '../src/tool-result-guard.js';
 import { PassthroughStrategy } from '@animalabs/context-manager';
 import { MockMembrane, MockYieldingStream, createMockResponse } from './helpers/mock-membrane.js';
 import { NativeFormatter } from '@animalabs/membrane';
@@ -411,7 +411,7 @@ describe('silent heartbeat stored rows', () => {
       const tickRows = stored(x.framework).slice(before);
       assert.deepEqual(tickRows.map((m) => m.participant), ['assistant', 'user', 'assistant']);
       for (const row of tickRows) assert.equal(row.metadata?.silentHeartbeat?.eventId, tick.eventId);
-      assert.equal((tickRows[1]!.content[0] as { content?: unknown }).content, TOOL_RESULT_GUARD_NOTICE);
+      assert.equal((tickRows[1]!.content[0] as { content?: unknown }).content, withheldResultNotice(null, true));
       assert.doesNotMatch(JSON.stringify(tickRows), /discard-this-partial-output/);
 
       const opening = membrane.calls[1]!.messages;
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 71ad0787a..82eec5e74 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { PassthroughStrategy, type StoredMessage, type StrategyContext } from '@animalabs/context-manager';
@@ -9,8 +9,14 @@ import { Membrane as RealMembrane, NativeFormatter, type ProviderAdapter, type P
   type ProviderResponse, type StreamCallbacks } from '@animalabs/membrane';
 import { AgentFramework, type AgentConfig, type AgentSettingsExtension, type Module, type ModuleContext,
   type ToolCall, type ToolResult, type ProcessEvent, type ProcessState } from '../src/index.js';
-import { TOOL_RESULT_GUARD_AUDIT_STATE, TOOL_RESULT_GUARD_NOTICE } from '../src/tool-result-guard.js';
+import { TOOL_RESULT_GUARD_AUDIT_STATE, TOOL_RESULT_GUARD_NOTICE, withheldResultNotice } from '../src/tool-result-guard.js';
 import { MockYieldingStream, createMockResponse } from './helpers/mock-membrane.js';
+import { WorkspaceModule } from '../src/modules/workspace/index.js';
+
+// What a withheld result settles to with no writable workspace (#277): the
+// neutral notice, then where the original is kept.
+const AUDIT_STUB = withheldResultNotice(null, true);
+const UNSAVED_STUB = withheldResultNotice(null, false);
 
 const dirs: string[] = [];
 afterEach(() => { while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true }); });
@@ -138,9 +144,12 @@ test('withholds the entire latest batch, retries inference once, and keeps origi
     assert.doesNotMatch(JSON.stringify(retry), /original-text-payload|original-error-payload|discard-this-partial-output|test-category/);
     assert.ok(!JSON.stringify(retry).includes(image));
     assert.equal(retry.messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_use').length, 3);
+    const retried = retry.messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.ok(retried.length === 3 && retried.every((b) => b.content === AUDIT_STUB),
+      'the retry already says where each original is');
     const guarded = toolResults(h.framework);
     assert.equal(guarded.length, 3);
-    assert.ok(guarded.every((block) => block.content === TOOL_RESULT_GUARD_NOTICE));
+    assert.ok(guarded.every((block) => block.content === AUDIT_STUB));
     assert.equal(guarded.find((b) => b.toolUseId === 'error')?.isError, true);
     assert.deepEqual(h.module.speeches, ['continued']);
     assert.ok(strategy.snapshots.every((s) => !s.includes('original-text-payload') && !s.includes(image)),
@@ -150,18 +159,18 @@ test('withholds the entire latest batch, retries inference once, and keeps origi
     const audit = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     assert.match(JSON.stringify(audit[0]), /original-text-payload|original-error-payload/);
     assert.ok(JSON.stringify(audit[0]).includes(image));
-    assert.equal(audit.at(-1)?.type, 'withheld');
+    assert.deepEqual(audit.slice(-2).map((r) => r.type), ['withheld', 'annotated']);
     const historical = store.getStateJsonAt(TOOL_RESULT_GUARD_AUDIT_STATE, stagedSequence) as unknown[];
     assert.deepEqual(audit[0], historical[0], 'redaction only appends; original Chronicle record is unchanged');
     const original = structuredClone(audit[0]);
     extension(h.framework).update('assistant', { tool_result_guard: false });
-    assert.ok(toolResults(h.framework).every((block) => block.content === TOOL_RESULT_GUARD_NOTICE));
+    assert.ok(toolResults(h.framework).every((block) => block.content === AUDIT_STUB));
     await h.framework.stop();
     originalStopped = true;
     const restarted = await AgentFramework.create(h.base);
     try {
       assert.equal(extension(restarted).get('assistant').tool_result_guard, false, 'explicit disable persists');
-      assert.ok(toolResults(restarted).every((block) => block.content === TOOL_RESULT_GUARD_NOTICE));
+      assert.ok(toolResults(restarted).every((block) => block.content === AUDIT_STUB));
       assert.deepEqual((restarted.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as unknown[])[0], original);
       const preview = await restarted.previewActivation('assistant');
       assert.doesNotMatch(JSON.stringify(preview), /original-text-payload|original-error-payload/);
@@ -175,7 +184,7 @@ test('successful physical rounds admit results; refusal affects only the newest
     await h.run();
     const results = toolResults(h.framework);
     assert.match(String(results.find((b) => b.toolUseId === 'accepted')?.content), /payload-accepted/);
-    assert.equal(results.find((b) => b.toolUseId === 'withheld')?.content, TOOL_RESULT_GUARD_NOTICE);
+    assert.equal(results.find((b) => b.toolUseId === 'withheld')?.content, AUDIT_STUB);
     assert.deepEqual(h.module.calls, ['accepted', 'withheld']);
     assert.equal(h.framework.getAgent('assistant')!.toolResultGuard.enabled, true);
   } finally { await h.framework.stop(); }
@@ -192,7 +201,7 @@ test('a second refusal stops recovery without auto-rewinding older or human mess
     const messages = h.framework.getAgent('assistant')!.getContextManager().getAllMessages();
     assert.ok(messages.some((m) => m.content.some((b) => b.type === 'text' && b.text === 'read')));
     assert.doesNotMatch(JSON.stringify(messages), /discard-this-partial-output|refusal-rewind/);
-    assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
+    assert.equal(toolResults(h.framework)[0].content, AUDIT_STUB);
   } finally { await h.framework.stop(); }
 });
 
@@ -248,7 +257,7 @@ test('budget restart submits staged originals, then recovers without re-executin
     assert.match(JSON.stringify(h.membrane.requests[1]), /payload-one/);
     assert.doesNotMatch(JSON.stringify(h.membrane.requests[2]), /payload-one/);
     assert.deepEqual(h.module.calls, ['one']);
-    assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
+    assert.equal(toolResults(h.framework)[0].content, AUDIT_STUB);
   } finally { await h.framework.stop(); }
 });
 
@@ -368,7 +377,9 @@ test('backward-compatible direct Agent inference also guards tool results', asyn
     assert.equal(final.usage?.inputTokens, 20, 'abandoned refused attempt usage is included');
     assert.match(JSON.stringify(requests[1]), /direct-original/);
     assert.doesNotMatch(JSON.stringify(requests[2]), /direct-original|discard-this/);
-    assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
+    const retried = requests[2].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(retried.map((b) => b.content), [AUDIT_STUB], 'the direct retry says where the original is too');
+    assert.equal(toolResults(h.framework)[0].content, AUDIT_STUB);
   } finally { await h.framework.stop(); }
 });
 
@@ -391,7 +402,7 @@ test('full oversized output survives withholding and reopening as a Chronicle bl
     const restarted = await AgentFramework.create(h.base);
     try {
       assert.deepEqual(restarted.getStore().getBlob(blobId), blob);
-      assert.equal(toolResults(restarted)[0].content, TOOL_RESULT_GUARD_NOTICE);
+      assert.equal(toolResults(restarted)[0].content, AUDIT_STUB);
     } finally { await restarted.stop(); }
   } finally { if (!originalStopped) await h.framework.stop(); }
 });
@@ -558,7 +569,7 @@ test('failed audit sync fails closed: originals are never submitted', async () =
     const provided = JSON.stringify(h.membrane.streams[0].receivedToolResults);
     assert.doesNotMatch(provided, /payload-one/, 'non-durable audit must not release originals');
     assert.match(provided, /Tool result withheld by the guard/);
-    assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
+    assert.equal(toolResults(h.framework)[0].content, UNSAVED_STUB);
     const guard = h.framework.getAgent('assistant')!.toolResultGuard;
     assert.equal(guard.hasPending, false);
   } finally { (store as { sync: () => void }).sync = sync; await h.framework.stop(); }
@@ -739,7 +750,9 @@ test('real compression: a withheld batch releases its hold and the placeholder c
     await r.drain();
     r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
     assert.ok(r.guard.withhold('test-category'));
-    assert.equal(r.cm.getCompressionHolds().size, 0, 'withhold releases the hold');
+    assert.deepEqual([...r.cm.getCompressionHolds()], [r.messageId], 'held until the stub says where the original is');
+    await r.guard.whenAnnotated();
+    assert.equal(r.cm.getCompressionHolds().size, 0, 'withhold releases the hold once annotated');
     await r.drain();
     assert.ok(r.prompts.some((p) => p.includes(TOOL_RESULT_GUARD_NOTICE)), 'placeholder compresses after release');
     assert.ok(!r.prompts.some((p) => p.includes(r.REAL)), 'withheld output never reaches memory');
@@ -761,6 +774,7 @@ test('every settlement path releases the hold, even when the audit write fails',
       const store = r.cm.getStore();
       (store as { appendToStateJson: unknown }).appendToStateJson = () => { throw new Error('storage down'); };
       try { settle(r.guard); } catch { /* audit failure surfaces; hold must still go */ }
+      await r.guard.whenAnnotated();
       assert.equal(r.guard.hasPending, false, `${name}: batch cleared`);
       assert.equal(r.cm.getCompressionHolds().size, 0, `${name}: hold released`);
     } finally { r.cm.close(); }
@@ -790,7 +804,7 @@ for (const failedType of ['staged', 'linked']) {
       failing = false;
       await h.run(); // A normal activation, with no new tool call, retries the audit.
       const records = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
-      assert.deepEqual(records.map((r) => r.type), ['staged', 'linked', 'withheld']);
+      assert.deepEqual(records.map((r) => r.type), ['staged', 'linked', 'withheld', 'annotated']);
       assert.match(JSON.stringify(records[0]), /payload-one/, 'the original is recoverable after storage returns');
       assert.doesNotMatch(JSON.stringify(h.membrane.requests[1]), /payload-one/);
       assert.deepEqual(h.module.calls, ['one']);
@@ -883,14 +897,14 @@ test('storage recovery: endTurn never admits a batch whose audit sync failed', a
   };
   try {
     await h.run();
-    assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
+    assert.equal(toolResults(h.framework)[0].content, UNSAVED_STUB);
     assert.equal(agent.getContextManager().getCompressionHolds().size, 0);
     assert.equal(agent.toolResultGuard.hasPending, false);
     store.sync = sync;
     await h.run();
     assert.doesNotMatch(JSON.stringify(h.membrane.requests[1]), /payload-one/);
     const records = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
-    assert.equal(records.at(-1)?.type, 'withheld');
+    assert.deepEqual(records.slice(-2).map((r) => r.type), ['withheld', 'annotated']);
     assert.match(JSON.stringify(records[0]), /payload-one/, 'the original is still archived');
   } finally { store.sync = sync; await h.framework.stop(); }
 });
@@ -962,3 +976,208 @@ test('storage recovery: shutdown retries edits queued by its terminating stream'
     } finally { await restarted.stop(); }
   } finally { cm.editMessage = edit; if (stopping) await stopping; else await h.framework.stop(); }
 });
+
+// ---------------------------------------------------------------------------
+// agent-framework #277: a withheld result says where its original is. The
+// guard's neutral notice stays (#159), followed by the place: a workspace
+// file when a writable mount takes it, else the guard's audit record.
+// ---------------------------------------------------------------------------
+
+async function workspaceHarness(scripts: NormalizedResponse[][], mount: { maxFileSize?: number } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'af-tool-result-guard-ws-')); dirs.push(dir);
+  const mountDir = join(dir, 'mount');
+  mkdirSync(mountDir, { recursive: true });
+  const membrane = new ScriptMembrane(scripts);
+  const module = new ReadModule();
+  const workspace = new WorkspaceModule({ mounts: [{
+    name: 'work', path: mountDir, mode: 'read-write', watch: 'never',
+    ...(mount.maxFileSize !== undefined ? { maxFileSize: mount.maxFileSize } : {}),
+  }] });
+  const framework = await AgentFramework.create({ storePath: join(dir, 'store'), membrane: membrane.asMembrane(),
+    agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system', toolResultGuard: true }],
+    modules: [module, workspace as unknown as Module], syncIntervalMs: 0 });
+  workspace.initStore(framework.getStore());
+  const run = async () => {
+    framework.pushEvent({ type: 'external-message', source: 'test', content: 'read', metadata: {} });
+    await framework.runUntilIdle();
+  };
+  return { framework, membrane, workspace, run };
+}
+
+/** Delay the framework's tool-results writer (no workspace: it then reports
+ *  none), keeping the framework's own wiring and tracking in place. */
+function slowSpill(framework: AgentFramework, wait: () => Promise<unknown>) {
+  (framework as unknown as { writeToolResultFile: () => Promise<null> }).writeToolResultFile = async () => {
+    await wait();
+    return null;
+  };
+}
+
+const SPILLED_STUB = /^Tool result withheld by the guard\. The tool has already executed\. Its full result is in workspace file (work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-one\.txt)\.$/;
+
+test('#277: a withheld original is written to the workspace, and its stub names the file', async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
+  try {
+    await h.run();
+    const stub = String(toolResults(h.framework)[0].content);
+    const path = SPILLED_STUB.exec(stub)?.[1];
+    assert.ok(path, `stub names the file: ${stub}`);
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const staged = (audit[0] as { content: Array<{ toolUseId?: string; content?: unknown }> }).content;
+    const admitted = staged.find((b) => b.toolUseId === 'one')?.content;
+    assert.match(String(admitted), /payload-one/);
+    const file = await h.workspace.readBinary(path);
+    assert.ok('data' in file, `the file is readable: ${JSON.stringify(file)}`);
+    assert.equal((file as { data: Buffer }).data.toString('utf8'), admitted,
+      'the file holds exactly what acceptance would have admitted');
+    const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(retried.map((b) => b.content), [stub], 'the retry already says where the original is');
+    assert.doesNotMatch(stub, /refus|test-category/, "#159's line: no refusal or category in the context");
+    assert.deepEqual(audit.at(-1), { ...audit.at(-1), type: 'annotated', results: [{ toolUseId: 'one', path }] });
+  } finally { await h.framework.stop(); }
+});
+
+test('#277: a failed workspace write says so, and the audit record still keeps the original', async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()]], { maxFileSize: 4 });
+  try {
+    await h.run();
+    const stub = String(toolResults(h.framework)[0].content);
+    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its full result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-one\.txt failed \(.+\), so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const annotated = audit.at(-1) as { type: string; results: Array<{ toolUseId: string; path?: string; error?: string }> };
+    assert.equal(annotated.type, 'annotated');
+    assert.equal(annotated.results[0].toolUseId, 'one');
+    assert.equal(typeof annotated.results[0].error, 'string');
+    assert.match(JSON.stringify(audit[0]), /payload-one/, 'the original is in the staged record');
+  } finally { await h.framework.stop(); }
+});
+
+test('#277: the refusal retry is compiled only once the stub says where the original is', async () => {
+  const h = await harness([[calls('one'), refused()], [answer()]], { toolResultGuard: true });
+  slowSpill(h.framework, () => new Promise((resolve) => setTimeout(resolve, 100)));
+  try {
+    await h.run();
+    const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(retried.map((b) => b.content), [AUDIT_STUB]);
+  } finally { await h.framework.stop(); }
+});
+
+test("#277: an operator's edit made before the stub is annotated stands, and the hold waits for it", async () => {
+  const r = await compressionRig();
+  try {
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => { release = resolve; });
+    let entered = false;
+    r.guard.setHost({ spill: async () => { entered = true; await gate; return null; }, track: () => {} });
+    r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
+    assert.ok(r.guard.withhold('test-category'));
+    for (let i = 0; i < 100 && !entered; i++) await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.ok(entered, 'the original is being written');
+    assert.deepEqual([...r.cm.getCompressionHolds()], [r.messageId], 'held while the original is being written');
+    r.cm.editMessage(r.messageId, [{ type: 'tool_result', toolUseId: 'tu-1', content: 'operator replacement' }]);
+    release();
+    await r.guard.whenAnnotated();
+    assert.equal((r.cm.getMessage(r.messageId)!.content[0] as { content: unknown }).content, 'operator replacement');
+    assert.equal(r.cm.getCompressionHolds().size, 0);
+    const audit = r.cm.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    assert.equal(audit.at(-1)?.type, 'annotated');
+    assert.equal(audit.at(-1)?.historyUpdate, 'superseded');
+  } finally { r.cm.close(); }
+});
+
+test('#277: stop lets an aborted batch\'s stub be annotated before the store closes', async () => {
+  const h = await harness([[calls('one')]], { toolResultGuard: true });
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  let spills = 0;
+  slowSpill(h.framework, () => { spills++; return gate; });
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  let stopped = false;
+  try {
+    await h.run().catch(() => {});
+    for (let i = 0; i < 100 && spills === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(spills, 1, 'the aborted batch is being annotated');
+    const stopping = h.framework.stop().then(() => { stopped = true; });
+    setTimeout(release, 50);
+    await stopping;
+    const restarted = await AgentFramework.create(h.base);
+    try {
+      assert.equal(toolResults(restarted)[0].content, AUDIT_STUB, 'the annotated stub was saved before close');
+    } finally { await restarted.stop(); }
+  } finally { release(); if (!stopped) await h.framework.stop(); }
+});
+
+test('#277: the stub has the same text for each place the original can be', () => {
+  const notice = 'Tool result withheld by the guard. The tool has already executed.';
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/2026-10-10-withheld-a.txt' }, true),
+    `${notice} Its full result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'disk full' }, true),
+    `${notice} Writing its full result to workspace file work/tool-results/x.txt failed (disk full), ` +
+    "so it is kept only in the guard's audit record (framework/tool-result-guard), for an operator.");
+  assert.equal(withheldResultNotice(null, true),
+    `${notice} Its full result is kept in the guard's audit record (framework/tool-result-guard), for an operator.`);
+  assert.equal(withheldResultNotice(null, false),
+    `${notice} Its full result is kept in the guard's audit record (framework/tool-result-guard), for an operator, ` +
+    'though saving that record had failed when this was written.');
+});
+
+test('#277: direct API: a request after an aborted batch is compiled once its stub is annotated', async () => {
+  const h = await harness([], { toolResultGuard: true });
+  const responses: unknown[] = [calls('one'), { aborted: true, reason: 'test-abort' }, answer()];
+  const requests: NormalizedRequest[] = [];
+  (h.membrane as unknown as { stream: (request: NormalizedRequest) => Promise<unknown> }).stream = async (request) => {
+    requests.push(structuredClone(request));
+    const response = responses.shift();
+    assert.ok(response);
+    return response;
+  };
+  try {
+    const agent = h.framework.getAgent('assistant')!;
+    slowSpill(h.framework, () => new Promise((resolve) => setTimeout(resolve, 100)));
+    agent.getContextManager().addMessage('user', [{ type: 'text', text: 'read' }]);
+    await agent.runInference(h.framework.getAllTools());
+    agent.provideToolResult('one', { success: true, data: 'direct-original' });
+    const aborted = await agent.runInference(h.framework.getAllTools());
+    assert.equal(aborted.aborted, true);
+    await agent.runInference(h.framework.getAllTools());
+    const next = requests[2].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(next.map((b) => b.content), [AUDIT_STUB]);
+  } finally { await h.framework.stop(); }
+});
+
+test('#277: stop waits for an annotation started by an ephemeral run it has already disposed', async () => {
+  const h = await harness([[calls('one')]]);
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  let spills = 0;
+  slowSpill(h.framework, () => { spills++; return gate; });
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  let stopped = false;
+  try {
+    const created = await h.framework.createEphemeralAgent({
+      name: 'ephemeral', model: 'test', systemPrompt: 'system', toolResultGuard: true,
+    });
+    created.contextManager.addMessage('user', [{ type: 'text', text: 'read' }]);
+    const completion = h.framework.runEphemeralToCompletion(created.agent, created.contextManager);
+    h.framework.start();
+    await completion.catch(() => {});
+    for (let i = 0; i < 100 && spills === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(spills, 1, "the ephemeral's aborted batch is being annotated");
+    assert.equal(h.framework.getAgent('ephemeral') ?? null, null, 'the run was disposed');
+    const stopping = h.framework.stop().then(() => { stopped = true; });
+    setTimeout(release, 50);
+    await stopping;
+    const restarted = await AgentFramework.create(h.base);
+    try {
+      const audit = restarted.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+      assert.ok(audit.some((r) => r.type === 'annotated' && r.agentName === 'ephemeral'),
+        'the annotation finished before the store closed');
+    } finally { await restarted.stop(); }
+  } finally { release(); if (!stopped) await h.framework.stop(); }
+});

From 085a5b9f2a72aa6e32a14ffb7e606b009635a2f5 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Sat, 10 Oct 2026 16:04:50 -0400
Subject: [PATCH 02/16] fix(guard): each withheld original gets its own file; a
 branch change stops the writes; the direct retry is compiled (#277)

Answers Greptile's three findings on #281 (review of 675546a).

1. Saved originals could overwrite each other. The guard labelled each file
   `<date>-withheld-<toolUseId>`, and the writer keeps 80 characters of a
   label with unsafe characters replaced, so two results whose ids agree in
   their first 60 safe characters, or a tool use id seen again the same day,
   shared one file: an older stub then named a newer result's original. The
   label is now `<date>-withheld-<batch>-<index>-<toolUseId>`: 12 hex digits
   (48 random bits) of the batch's id and the result's index in the batch,
   both ahead of anything the writer cuts or substitutes. Results of one batch
   never share a file; results of two batches share one only if those 48 bits
   agree. The stubs and the files are matched by index rather than by tool use
   id. The inline cap's own `<date>-<callId>` naming, documented as
   deterministic and overwritten on collision, is unchanged.

2. A rollback could receive late files. The annotation checked the branch only
   before editing the stub, after all its writes, and rollbackToMessage's gate
   doesn't wait for annotations (nor do undo, redo or the API's branch switch).
   A batch aborted with several results could have its later files written
   into the new branch's workspace while its stub edit was skipped. The
   annotation now checks the branch before each write and writes no more once
   the store has left the batch's branch. The check holds where the file
   lands because the framework's writer sets the workspace tree entry before
   it first yields (WorkspaceModule.writeBinary: treeSet, then
   autoMaterialize); WithheldSpiller's doc states that contract. The
   `annotated` audit record marks each result not written as
   `{ toolUseId, skipped: 'branch_changed' }`, beside `historyUpdate:
   'superseded'`.

3. The direct API's refusal retry could exceed the budget. It patched the
   stubs into the already-compiled request, whose budget reserved only the
   originals' size over the bare notice; a stub longer than its original (the
   audit-record stub is ~100 characters longer than the notice) carried the
   request past the budget. runInferenceWithInjections now builds its request
   with an `assemble()` closure, and doInference calls it again for the retry
   once the stubs are written: a fresh compile against the budget without the
   batch's reservation, as the framework's retry (startAgentStream) already
   is. The patching code and its notice import are gone.

Tests (test/tool-result-guard.test.ts, 51, 4 new):
- a tool use id seen again in a second batch gets its own file, and each stub
  reads back its own original (fails on 675546a: both stubs name
  2026-10-10-withheld-one.txt);
- two ids agreeing in their first 75 characters in one batch get a file each
  (fails on 675546a: both cut to the same name);
- a rollbackToMessage while an aborted two-result batch is held after its
  first write: no second write, `skipped` on the second result,
  `superseded`, and the source branch keeps the plain notices (fails on
  675546a: the second write happens);
- direct API, 20 results of 'x' under a 3000/1000 budget with 200 fillers:
  the retry carries every stub and fits 2000 tokens by the store's own
  estimator (fails on 675546a: 2811 > 2000). The refused attempt fitting is
  a control.
The two existing workspace tests now expect the new name format.

Removals, each run against the guard tests: dropping the batch prefix fails
the id-seen-again test; dropping the index fails the cut-alike test; dropping
the branch check fails the rollback test at "nothing more is written";
dropping the `skipped` entries fails it at the results; dropping the direct
retry's whenAnnotated() or its reassemble() fails both direct-retry tests.
Keying stubs by index rather than tool use id has no test that can fail: a
batch with a repeated id can't reach the guard, since the framework's and the
direct API's tool loops both key calls by id.
---
 .../guard-withheld-names-original.fixed.md    |  14 +-
 src/agent.ts                                  |  70 +++++-----
 src/tool-result-guard.ts                      |  41 ++++--
 test/tool-result-guard.test.ts                | 132 +++++++++++++++++-
 4 files changed, 200 insertions(+), 57 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 3e341796f..2c1406cc9 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -1,12 +1,16 @@
 - A tool result the guard withholds now says where its original is. The
   guard's notice ("Tool result withheld by the guard. The tool has already
   executed.") is followed by the original's place: a workspace file under the
-  first writable mount's `tool-results/` (named `<date>-withheld-<toolUseId>`),
-  or, with no writable workspace or a failed write, the guard's audit record
+  first writable mount's `tool-results/` (named
+  `<date>-withheld-<batch>-<index>-<toolUseId>`, one per result), or, with no
+  writable workspace or a failed write, the guard's audit record
   (`framework/tool-result-guard`), for an operator. This holds for every
   withheld settlement: a refusal, an aborted stream, a batch that was never
   submitted, and one whose audit sync failed. The notice still names no
   refusal and no category. The stub is written before any request is compiled,
-  including the refusal retry, and before stop closes the store. Before this,
-  a withheld result left only the notice, so the agent couldn't tell what the
-  tool had done (agent-framework #277).
+  including the refusal retry, and before stop closes the store. If the active
+  branch changes while the originals are being written, no more are written
+  and the stub stays as it was. The direct Agent API's refusal retry is now
+  compiled afresh, as the framework's is, so its longer stubs fit the budget.
+  Before this, a withheld result left only the notice, so the agent couldn't
+  tell what the tool had done (agent-framework #277).
diff --git a/src/agent.ts b/src/agent.ts
index bf4d48d0c..30ff1d284 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -2,7 +2,7 @@ import type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock, Yiel
 import { isAbortedResponse } from '@animalabs/membrane';
 import { createHash } from 'node:crypto';
 import type { CacheWireReceipt, KvUnifiedRequestHooks } from './kv-unified-wire.js';
-import { ToolResultGuard, TOOL_RESULT_GUARD_NOTICE } from './tool-result-guard.js';
+import { ToolResultGuard } from './tool-result-guard.js';
 import {
   indexSilentTickRows,
   separateSilentHeartbeatTicks,
@@ -672,28 +672,30 @@ export class Agent {
       this.toolResultGuard.storeResults(content, wireResults, this._state.toolResults);
     }
 
-    // Compile context (with optional injections)
-    const { messages, systemInjections } = await this.compileWithInjections(budget, injections);
+    // Pending tool results the guard isn't holding follow the compiled context.
+    const unguardedResults = this._state.status === 'ready' && !guardedResults
+      ? this.buildToolResultMessages(this._state.toolResults) : [];
 
-    // If we have pending tool results, add them
-    if (this._state.status === 'ready' && !guardedResults) {
-      const toolResultMessages = this.buildToolResultMessages(this._state.toolResults);
-      messages.push(...toolResultMessages);
-    }
-
-    const request: NormalizedRequest = {
-      messages: this.toolResultGuard.prepareRequest(messages, true),
-      system: this.buildSystemPrompt(systemInjections),
-      config: {
-        model: this.model,
-        maxTokens: this.maxTokens,
-        ...(this.temperature !== undefined && { temperature: this.temperature }),
-        ...(this.thinking !== undefined && { thinking: this.thinking }),
-      },
-      tools: tools.length > 0 ? tools : undefined,
-      ...(this.providerParams && { providerParams: this.providerParams }),
-      assistantParticipant: this.name,
+    // Compile the context (with optional injections) into a request. The
+    // guard's refusal retry is assembled the same way, afresh.
+    const assemble = async (): Promise<NormalizedRequest> => {
+      const { messages, systemInjections } = await this.compileWithInjections(budget, injections);
+      messages.push(...unguardedResults);
+      return {
+        messages: this.toolResultGuard.prepareRequest(messages, true),
+        system: this.buildSystemPrompt(systemInjections),
+        config: {
+          model: this.model,
+          maxTokens: this.maxTokens,
+          ...(this.temperature !== undefined && { temperature: this.temperature }),
+          ...(this.thinking !== undefined && { thinking: this.thinking }),
+        },
+        tools: tools.length > 0 ? tools : undefined,
+        ...(this.providerParams && { providerParams: this.providerParams }),
+        assistantParticipant: this.name,
+      };
     };
+    const request = await assemble();
 
     const abortController = new AbortController();
     if (options?.signal) {
@@ -706,7 +708,7 @@ export class Agent {
 
     // Set state to inferring
     this._inferenceStartedAt = Date.now();
-    const inferencePromise = this.doInference(request, abortController.signal);
+    const inferencePromise = this.doInference(request, abortController.signal, assemble);
     this._state = { status: 'inferring', promise: inferencePromise, abortController };
 
     try {
@@ -1183,7 +1185,9 @@ export class Agent {
 
   private async doInference(
     request: NormalizedRequest,
-    signal?: AbortSignal
+    signal: AbortSignal | undefined,
+    /** Compiles the context into a request again, for the guard's retry. */
+    reassemble: () => Promise<NormalizedRequest>,
   ): Promise<InferenceResult> {
     let response = await this.membrane.stream(request, { signal });
     // Usage of a refused attempt abandoned by the guard; it was billed and
@@ -1195,22 +1199,12 @@ export class Agent {
       const ids = this.toolResultGuard.withhold('unknown');
       if (ids) {
         abandonedUsage = response.usage;
-        const withheld = new Set(ids);
-        // The retry carries the stubs as stored: each says where its original
-        // went (agent-framework #277), once the guard has written that.
+        // The retry is compiled afresh, like every request: once each stub
+        // says where its original went (agent-framework #277), and against the
+        // budget without the batch's reservation, so a stub longer than its
+        // original can't carry the request past the budget.
         await this.toolResultGuard.whenAnnotated();
-        const stubs = new Map<string, Extract<ContentBlock, { type: 'tool_result' }>['content']>();
-        for (const message of this.contextManager.getAllMessages()) {
-          for (const block of message.content) {
-            if (block.type === 'tool_result' && withheld.has(block.toolUseId)) stubs.set(block.toolUseId, block.content);
-          }
-        }
-        request = { ...request, messages: request.messages.map((message) => ({
-          ...message, content: message.content.map((block) => block.type === 'tool_result' && withheld.has(block.toolUseId)
-            ? { type: 'tool_result', toolUseId: block.toolUseId,
-              content: stubs.get(block.toolUseId) ?? TOOL_RESULT_GUARD_NOTICE, isError: block.isError } : block),
-        })) };
-        response = await this.membrane.stream(request, { signal });
+        response = await this.membrane.stream(await reassemble(), { signal });
       }
     }
 
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 26e306568..be517ac4d 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -13,7 +13,10 @@ export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 export type WithheldSpill = { path: string; error?: string } | null;
 
 /** Writes one withheld original as a workspace file (the framework's
- *  tool-results spill). It reports a failed write rather than throwing. */
+ *  tool-results spill). It reports a failed write rather than throwing. It
+ *  commits the file to the workspace before it first yields
+ *  (WorkspaceModule.writeBinary sets the tree entry, then materializes), so a
+ *  branch check made just before the call holds where the file lands. */
 export type WithheldSpiller = (label: string, text: string) => Promise<WithheldSpill>;
 
 /** What a host gives a guard for its withheld results: where originals are
@@ -370,24 +373,36 @@ export class ToolResultGuard {
     const run = previous.then(async () => {
       try {
         const date = new Date().toISOString().slice(0, 10);
-        const spills = new Map<string, WithheldSpill>();
-        for (const block of pending.content) {
+        // A file is named by its batch and its place in the batch, ahead of
+        // anything the writer may cut or substitute: results of one batch
+        // never share a file, and results of two batches share one only if 48
+        // random bits of their batch ids agree. The tool use id after them is
+        // for whoever lists the directory.
+        const batch = pending.id.replace(/-/g, '').slice(0, 12);
+        // Keyed by the result's index in the batch, which the stub and the
+        // original share.
+        const spills = new Map<number, WithheldSpill>();
+        for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
+          // Once the store has left the batch's branch (a rollback, an undo, a
+          // host's switch), the stub below stays as it is, and a file written
+          // now would land in the other branch's workspace. Write no more.
+          if (this.cm.currentBranch().name !== pending.branch) break;
           const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
           let spill: WithheldSpill = null;
           if (this.host) {
             try {
-              spill = await this.host.spill(`${date}-withheld-${block.toolUseId}`, original);
+              spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original);
             } catch (error) {
               console.error(`[tool-result-guard] agent=${this.agentName} could not spill withheld result ` +
                 `${block.toolUseId}:`, error);
             }
           }
-          spills.set(block.toolUseId, spill);
+          spills.set(index, spill);
         }
-        const annotated: ContentBlock[] = pending.withheld.map((block) => block.type === 'tool_result'
-          && spills.has(block.toolUseId)
-          ? { ...block, content: withheldResultNotice(spills.get(block.toolUseId)!, pending.durable) }
+        const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
+          && spills.has(index)
+          ? { ...block, content: withheldResultNotice(spills.get(index)!, pending.durable) }
           : block);
         const sameBranch = this.cm.currentBranch().name === pending.branch;
         const current = sameBranch ? this.cm.getMessage(pending.messageId) : null;
@@ -396,9 +411,13 @@ export class ToolResultGuard {
         if (unedited) this.cm.editMessage(pending.messageId, annotated);
         this.append({
           type: 'annotated', batchId: pending.id, messageId: pending.messageId,
-          results: [...spills].map(([toolUseId, spill]) => ({
-            toolUseId, ...(spill ? { path: spill.path } : {}), ...(spill?.error !== undefined ? { error: spill.error } : {}),
-          })),
+          results: pending.content.flatMap((block, index): Array<Record<string, string>> => {
+            if (block.type !== 'tool_result') return [];
+            if (!spills.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'branch_changed' }];
+            const spill = spills.get(index);
+            return [{ toolUseId: block.toolUseId, ...(spill ? { path: spill.path } : {}),
+              ...(spill?.error !== undefined ? { error: spill.error } : {}) }];
+          }),
           ...(unedited ? {} : { historyUpdate: 'superseded' }),
         });
       } catch (error) {
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 82eec5e74..a738952c0 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1001,7 +1001,7 @@ async function workspaceHarness(scripts: NormalizedResponse[][], mount: { maxFil
     framework.pushEvent({ type: 'external-message', source: 'test', content: 'read', metadata: {} });
     await framework.runUntilIdle();
   };
-  return { framework, membrane, workspace, run };
+  return { framework, membrane, module, workspace, run };
 }
 
 /** Delay the framework's tool-results writer (no workspace: it then reports
@@ -1013,7 +1013,7 @@ function slowSpill(framework: AgentFramework, wait: () => Promise<unknown>) {
   };
 }
 
-const SPILLED_STUB = /^Tool result withheld by the guard\. The tool has already executed\. Its full result is in workspace file (work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-one\.txt)\.$/;
+const SPILLED_STUB = /^Tool result withheld by the guard\. The tool has already executed\. Its full result is in workspace file (work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt)\.$/;
 
 test('#277: a withheld original is written to the workspace, and its stub names the file', async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
@@ -1042,7 +1042,7 @@ test('#277: a failed workspace write says so, and the audit record still keeps t
   try {
     await h.run();
     const stub = String(toolResults(h.framework)[0].content);
-    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its full result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-one\.txt failed \(.+\), so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
+    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its full result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt failed \(.+\), so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     const annotated = audit.at(-1) as { type: string; results: Array<{ toolUseId: string; path?: string; error?: string }> };
     assert.equal(annotated.type, 'annotated');
@@ -1181,3 +1181,129 @@ test('#277: stop waits for an annotation started by an ephemeral run it has alre
     } finally { await restarted.stop(); }
   } finally { release(); if (!stopped) await h.framework.stop(); }
 });
+
+// ---------------------------------------------------------------------------
+// #281's review: each withheld result's file is its own, a branch change stops
+// the annotation's writes, and the direct API's refusal retry fits the budget.
+// ---------------------------------------------------------------------------
+
+/** The file a written stub names, whatever the naming. */
+const stubPath = (stub: string) => /workspace file (\S+\.txt)\.$/.exec(stub)?.[1];
+
+test('#277: a tool use id seen again gets a file of its own, and each stub reads back its own original', async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()], [calls('one'), refused()], [answer()]]);
+  try {
+    h.module.results.one = { success: true, data: 'first-original' };
+    await h.run();
+    h.module.results.one = { success: true, data: 'second-original' };
+    await h.run();
+    const stubs = toolResults(h.framework).map((block) => String(block.content));
+    const paths = stubs.map(stubPath);
+    assert.equal(paths.length, 2);
+    assert.ok(paths[0] && paths[1] && paths[0] !== paths[1], `each stub names a file of its own: ${JSON.stringify(stubs)}`);
+    for (const [index, expected] of ['first-original', 'second-original'].entries()) {
+      const file = await h.workspace.readBinary(paths[index]!);
+      assert.ok('data' in file, `the file is readable: ${JSON.stringify(file)}`);
+      assert.match((file as { data: Buffer }).data.toString('utf8'), new RegExp(expected), `stub ${index} reads back its own original`);
+    }
+  } finally { await h.framework.stop(); }
+});
+
+test("#277: results whose ids the writer's cut makes alike still get a file each", async () => {
+  // The writer keeps 80 characters of a label; these ids agree in their first 75.
+  const shared = 'call_' + 'a'.repeat(70);
+  const ids = [`${shared}-1`, `${shared}-2`];
+  const h = await workspaceHarness([[calls(...ids), refused()], [answer()]]);
+  try {
+    await h.run();
+    const stubs = toolResults(h.framework).map((block) => String(block.content));
+    const paths = stubs.map(stubPath);
+    assert.ok(paths[0] && paths[1] && paths[0] !== paths[1], `each stub names a file of its own: ${JSON.stringify(stubs)}`);
+    for (const [index, id] of ids.entries()) {
+      const file = await h.workspace.readBinary(paths[index]!);
+      assert.ok('data' in file, `the file is readable: ${JSON.stringify(file)}`);
+      assert.match((file as { data: Buffer }).data.toString('utf8'), new RegExp(`payload-${id}`), `stub ${index} reads back its own original`);
+    }
+  } finally { await h.framework.stop(); }
+});
+
+test('#277: a rollback while an aborted batch is being annotated gets none of its files, and its stub stays as it was', async () => {
+  const h = await harness([[calls('one', 'two')]], { toolResultGuard: true });
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  const labels: string[] = [];
+  // The writer commits a file before it first yields, so the annotation is
+  // held after its first file, where a rollback can land between two writes.
+  (h.framework as unknown as { writeToolResultFile: (label: string) => Promise<null> }).writeToolResultFile = async (label) => {
+    labels.push(label);
+    if (labels.length === 1) await gate;
+    return null;
+  };
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  try {
+    await h.run().catch(() => {});
+    for (let i = 0; i < 100 && labels.length === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(labels.length, 1, "the aborted batch's first original is being written");
+    const agent = h.framework.getAgent('assistant')!;
+    const cm = agent.getContextManager();
+    const source = cm.currentBranch().name;
+    const batch = cm.getAllMessages().find((m) => m.content.some((b) => b.type === 'tool_result'))!;
+    const read = cm.getAllMessages().find((m) => m.content.some((b) => b.type === 'text' && b.text === 'read'))!;
+    const rolled = await h.framework.rollbackToMessage('assistant', { messageId: read.id });
+    release();
+    await agent.toolResultGuard.whenAnnotated();
+    assert.equal(labels.length, 1, 'nothing more is written once the branch has changed');
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const annotated = audit.find((record) => record.type === 'annotated');
+    assert.ok(annotated, `the annotation is recorded on ${rolled.targetBranch}: ${JSON.stringify(audit)}`);
+    assert.deepEqual(annotated.results, [{ toolUseId: 'one' }, { toolUseId: 'two', skipped: 'branch_changed' }]);
+    assert.equal(annotated.historyUpdate, 'superseded');
+    await cm.switchBranch(source);
+    const kept = cm.getMessage(batch.id)!.content.filter((b) => b.type === 'tool_result');
+    assert.deepEqual(kept.map((b) => (b as { content: unknown }).content), [TOOL_RESULT_GUARD_NOTICE, TOOL_RESULT_GUARD_NOTICE],
+      'the source branch keeps the plain notice');
+  } finally { release(); await h.framework.stop(); }
+});
+
+class BudgetProbe extends PassthroughStrategy {
+  store?: { estimateTokens(message: { content: ContentBlock[] }): number };
+  select(...args: Parameters<PassthroughStrategy['select']>) {
+    this.store = args[0] as unknown as BudgetProbe['store'];
+    return super.select(...args);
+  }
+}
+
+test('#277: direct API: the refusal retry fits the budget, though its stubs are longer than the originals', async () => {
+  const probe = new BudgetProbe();
+  const budget = 3_000;
+  const h = await harness([], { toolResultGuard: true, strategy: probe, contextBudgetTokens: budget, maxTokens: 1_000 });
+  const ids = Array.from({ length: 20 }, (_, i) => `t${i}`);
+  const responses = [calls(...ids), refused(), answer()];
+  const requests: NormalizedRequest[] = [];
+  (h.membrane as unknown as { stream: (request: NormalizedRequest) => Promise<NormalizedResponse> }).stream = async (request) => {
+    requests.push(structuredClone(request));
+    const response = responses.shift();
+    assert.ok(response);
+    return response;
+  };
+  try {
+    const agent = h.framework.getAgent('assistant')!;
+    const cm = agent.getContextManager();
+    for (let i = 0; i < 200; i++) cm.addMessage('user', [{ type: 'text', text: `filler-${i} ` + 'y'.repeat(200) }]);
+    cm.addMessage('user', [{ type: 'text', text: 'read' }]);
+    await agent.runInference(h.framework.getAllTools());
+    for (const id of ids) agent.provideToolResult(id, { success: true, data: 'x' });
+    await agent.runInference(h.framework.getAllTools());
+    assert.equal(requests.length, 3);
+    const tokens = (request: NormalizedRequest) =>
+      request.messages.reduce((n, message) => n + probe.store!.estimateTokens({ content: message.content }), 0);
+    const limit = budget - 1_000;
+    assert.ok(tokens(requests[1]) <= limit, `the refused attempt fits: ${tokens(requests[1])} <= ${limit}`);
+    const retried = requests[2].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(retried.map((b) => b.content), ids.map(() => AUDIT_STUB), 'the retry carries every stub');
+    assert.ok(tokens(requests[2]) <= limit, `the retry fits: ${tokens(requests[2])} <= ${limit}`);
+  } finally { await h.framework.stop(); }
+});

From 9626707f2103554dfc4bdb808f2233a778f7f010 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Sat, 10 Oct 2026 16:13:38 -0400
Subject: [PATCH 03/16] test(guard): pin writeBinary's tree entry before its
 first yield, which the branch check relies on (#277)

Petra-1012's review of 085a5b9: the guard's branch check before each write
holds only because WorkspaceModule.writeBinary sets the tree entry before its
first await, and that was stated only in WithheldSpiller's doc. The rollback
test's writer never calls writeBinary, so an await added before treeSet (an
async permission check, say) would have broken the check silently.

- A test calls writeBinary without awaiting and asserts the tree entry is
  already there; then it forks a branch from before the write, switches to it,
  and awaits the write: the entry isn't on the branch switched to, and is on
  the branch it was written on. It passes on 675546a too: it pins existing
  behaviour. With `await Promise.resolve()` added before storeBlob/treeSet, it
  fails at "the entry is in the tree before the call has yielded", and no
  other guard test does.
- A comment at writeBinary names the guard as relying on this, and the test.
- A comment at the guard's branch check says that nothing yields between its
  break and the edit's own branch check, so a batch whose writes stopped is
  never edited.
---
 src/modules/workspace/index.ts |  4 ++++
 src/tool-result-guard.ts       |  2 ++
 test/tool-result-guard.test.ts | 25 +++++++++++++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index 9091ef1fb..e5b92400a 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1261,6 +1261,10 @@ export class WorkspaceModule implements Module {
       return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
     }
     const store = this.getStore();
+    // The tree entry is set before the first await, on the branch that is
+    // current when this is called. The tool-result guard relies on that: its
+    // branch check just before the call holds where the entry lands
+    // (agent-framework #277; pinned in tool-result-guard.test.ts).
     const blobHash = store.storeBlob(data, mimeType);
     store.treeSet(mount.treeStateId, relativePath, {
       blobHash,
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index be517ac4d..668f5b692 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -387,6 +387,8 @@ export class ToolResultGuard {
           // Once the store has left the batch's branch (a rollback, an undo, a
           // host's switch), the stub below stays as it is, and a file written
           // now would land in the other branch's workspace. Write no more.
+          // Nothing yields between this break and the edit's own branch check,
+          // so a batch whose writes stopped is never edited.
           if (this.cm.currentBranch().name !== pending.branch) break;
           const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
           let spill: WithheldSpill = null;
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index a738952c0..eefcef76a 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -12,6 +12,7 @@ import { AgentFramework, type AgentConfig, type AgentSettingsExtension, type Mod
 import { TOOL_RESULT_GUARD_AUDIT_STATE, TOOL_RESULT_GUARD_NOTICE, withheldResultNotice } from '../src/tool-result-guard.js';
 import { MockYieldingStream, createMockResponse } from './helpers/mock-membrane.js';
 import { WorkspaceModule } from '../src/modules/workspace/index.js';
+import { JsStore } from '@animalabs/chronicle';
 
 // What a withheld result settles to with no writable workspace (#277): the
 // neutral notice, then where the original is kept.
@@ -1307,3 +1308,27 @@ test('#277: direct API: the refusal retry fits the budget, though its stubs are
     assert.ok(tokens(requests[2]) <= limit, `the retry fits: ${tokens(requests[2])} <= ${limit}`);
   } finally { await h.framework.stop(); }
 });
+
+test("#277: writeBinary sets its tree entry before it first yields, as the guard's branch check relies on", async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'af-guard-write-binary-')); dirs.push(dir);
+  mkdirSync(join(dir, 'mount'));
+  const store = JsStore.openOrCreate({ path: join(dir, 'store') });
+  const workspace = new WorkspaceModule({ mounts: [{ name: 'work', path: join(dir, 'mount'), mode: 'read-write', watch: 'never' }] });
+  workspace.initStore(store);
+  try {
+    const tree = 'workspace/work/tree';
+    const path = 'tool-results/original.txt';
+    const source = store.currentBranch().name;
+    const before = store.currentSequence();
+    const writing = workspace.writeBinary(`work/${path}`, Buffer.from('original'), 'text/plain');
+    assert.ok(store.treeGet(tree, path), 'the entry is in the tree before the call has yielded');
+    // A branch switch can only come once the call has yielded: the entry
+    // stays where it was written, and the switched-to branch never gets it.
+    store.createBranchAt('elsewhere', source, before);
+    store.switchBranch('elsewhere');
+    assert.equal((await writing).success, true);
+    assert.equal(store.treeGet(tree, path), null, 'nothing lands on the branch switched to');
+    store.switchBranch(source);
+    assert.ok(store.treeGet(tree, path), 'the entry is on the branch it was written on');
+  } finally { store.close(); }
+});

From ef11718f9ad681dc8758a8214b7e21a1c48f7ece Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Sat, 10 Oct 2026 16:39:18 -0400
Subject: [PATCH 04/16] fix(guard): a withheld original's write names its
 branch, checked where the file commits (#277)

The guard's branch check before each spill call held where the file landed
only because WorkspaceModule.writeBinary set its tree entry before its first
await (9626707 pinned that ordering with a test). #248
(fix/workspace-truthful-listings, head 3bc6aed) runs every workspace write
inside the mount's turn, after settleBeforeMutation, so there the entry is set
after the turn queue and a possible pass: a rollback in between would put a
withheld original in the other branch's workspace. A trial merge of 3bc6aed
with 9626707 conflicts at writeBinary, and resolved with #248's body,
9626707's contract test fails (tool-result-guard.test.ts 51/52).

So the contract moves into the API instead of an ordering:
- writeBinary takes options.branch. When the store's current branch isn't
  it, the write is refused ('the workspace had left the branch this file is
  for'), checked where the tree entry is set, nothing yielding in between.
- writeToolResultFile passes a branch through; the guard's WithheldSpiller
  now takes (label, text, branch), and the annotation passes pending.branch.
- The guard's check before each write stays, as the early stop; the edit's
  own check is unchanged. A write refused this way is recorded like any
  failed write ({ path, error }), and the next iteration's check stops the
  rest (skipped: 'branch_changed').
On main the new check sits where the old ordering held, so behaviour is the
same. On #248 it goes after settleBeforeMutation, inside the turn, which is
the merge resolution.

Tests (tool-result-guard.test.ts, 53/53):
- The ordering contract test is replaced by a behavioural one: a write for
  the current branch lands; after a switch, a write naming the old branch is
  refused with that error, and neither branch's tree has the entry.
- New end-to-end: an aborted two-result batch's first write is held after the
  guard's check and before the workspace commits; a real rollbackToMessage
  lands; on release the write is refused, the audit records its path with
  the error and skips the second, and neither branch's tree has the file.
- Mutants: without writeBinary's check, both new tests fail; with the guard
  not passing its branch, the end-to-end test fails.
The rollback test's comment no longer claims the real writer's ordering.
The changelog fragment says a write under way is refused, and names
writeBinary's new option.
---
 .../guard-withheld-names-original.fixed.md    |  7 +-
 src/framework.ts                              | 13 ++--
 src/modules/workspace/index.ts                | 14 ++--
 src/tool-result-guard.ts                      | 19 ++---
 test/tool-result-guard.test.ts                | 69 ++++++++++++++++---
 5 files changed, 92 insertions(+), 30 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 2c1406cc9..5a850cf35 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -9,8 +9,11 @@
   submitted, and one whose audit sync failed. The notice still names no
   refusal and no category. The stub is written before any request is compiled,
   including the refusal retry, and before stop closes the store. If the active
-  branch changes while the originals are being written, no more are written
-  and the stub stays as it was. The direct Agent API's refusal retry is now
+  branch changes while the originals are being written, no more are written,
+  a write already under way is refused where it commits, and the stub stays
+  as it was, so no original lands on another branch. For this,
+  `WorkspaceModule.writeBinary` takes an optional `branch`: the file lands on
+  that branch or isn't written. The direct Agent API's refusal retry is now
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
   Before this, a withheld result left only the notice, so the agent couldn't
   tell what the tool had done (agent-framework #277).
diff --git a/src/framework.ts b/src/framework.ts
index 5f449de67..1a5cd02c7 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -2715,7 +2715,7 @@ export class AgentFramework {
     }
     agent.toolResultGuard.setOverride(enabled);
     agent.toolResultGuard.setHost({
-      spill: (label, text) => this.writeToolResultFile(label, text),
+      spill: (label, text, branch) => this.writeToolResultFile(label, text, branch),
       track: (annotation) => {
         this.guardAnnotations.add(annotation);
         void annotation.finally(() => this.guardAnnotations.delete(annotation));
@@ -11727,9 +11727,14 @@ export class AgentFramework {
    * Write one tool result's text to `<first writable mount>/tool-results/
    * <label>.txt`: the one place both the inline cap's spill and the guard's
    * withheld originals go. null when there is no writable workspace. A failed
-   * write is reported, traced and logged here, never thrown.
+   * write is reported, traced and logged here, never thrown. With a branch,
+   * the file lands on that branch or isn't written (see writeBinary).
    */
-  private async writeToolResultFile(label: string, content: string): Promise<{ path: string; error?: string } | null> {
+  private async writeToolResultFile(
+    label: string,
+    content: string,
+    branch?: string,
+  ): Promise<{ path: string; error?: string } | null> {
     const workspace = this.getWorkspaceModule();
     const mountName = workspace ? this.firstWritableMountName(workspace) : null;
     if (!workspace || !mountName) return null;
@@ -11737,7 +11742,7 @@ export class AgentFramework {
     const path = `${mountName}/tool-results/${safeLabel}.txt`;
     let failure: string;
     try {
-      const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain');
+      const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain', { branch });
       if (result.success) return { path };
       failure = result.error ?? 'write refused';
     } catch (err) {
diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index e5b92400a..58d28bab8 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1236,11 +1236,18 @@ export class WorkspaceModule implements Module {
    * mount, through the same Chronicle-tree + auto-materialize path as the
    * `write` tool. Public API for the framework's synthesized `save_image`
    * tool and other peer callers that hold bytes rather than text.
+   *
+   * `branch`, when given, ties the write to that branch: the store's current
+   * branch is checked where the tree entry is set, nothing yielding between
+   * the check and the entry, so the file lands on that branch or the write is
+   * refused. The tool-result guard writes a withheld original this way, for
+   * the branch its stub is on (agent-framework #277).
    */
   async writeBinary(
     mountPrefixedPath: string,
     data: Buffer,
     mimeType: string,
+    options: { branch?: string } = {},
   ): Promise<ToolResult> {
     let mount: MountState;
     let relativePath: string;
@@ -1261,10 +1268,9 @@ export class WorkspaceModule implements Module {
       return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
     }
     const store = this.getStore();
-    // The tree entry is set before the first await, on the branch that is
-    // current when this is called. The tool-result guard relies on that: its
-    // branch check just before the call holds where the entry lands
-    // (agent-framework #277; pinned in tool-result-guard.test.ts).
+    if (options.branch !== undefined && store.currentBranch().name !== options.branch) {
+      return { success: false, error: 'the workspace had left the branch this file is for', isError: true };
+    }
     const blobHash = store.storeBlob(data, mimeType);
     store.treeSet(mount.treeStateId, relativePath, {
       blobHash,
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 668f5b692..656d5bb69 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -13,11 +13,11 @@ export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 export type WithheldSpill = { path: string; error?: string } | null;
 
 /** Writes one withheld original as a workspace file (the framework's
- *  tool-results spill). It reports a failed write rather than throwing. It
- *  commits the file to the workspace before it first yields
- *  (WorkspaceModule.writeBinary sets the tree entry, then materializes), so a
- *  branch check made just before the call holds where the file lands. */
-export type WithheldSpiller = (label: string, text: string) => Promise<WithheldSpill>;
+ *  tool-results spill). It reports a failed write rather than throwing. The
+ *  file lands on `branch`, the branch the stub is on, or isn't written: the
+ *  workspace checks the branch where it commits the file
+ *  (WorkspaceModule.writeBinary). */
+export type WithheldSpiller = (label: string, text: string, branch: string) => Promise<WithheldSpill>;
 
 /** What a host gives a guard for its withheld results: where originals are
  *  written, and where each annotation is registered, so the host's stop can
@@ -385,16 +385,17 @@ export class ToolResultGuard {
         for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
           // Once the store has left the batch's branch (a rollback, an undo, a
-          // host's switch), the stub below stays as it is, and a file written
-          // now would land in the other branch's workspace. Write no more.
+          // host's switch), the stub below stays as it is: write no more.
           // Nothing yields between this break and the edit's own branch check,
-          // so a batch whose writes stopped is never edited.
+          // so a batch whose writes stopped is never edited. A write already
+          // under way when the branch changes is refused where it commits,
+          // since it names the batch's branch, so no file lands elsewhere.
           if (this.cm.currentBranch().name !== pending.branch) break;
           const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
           let spill: WithheldSpill = null;
           if (this.host) {
             try {
-              spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original);
+              spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original, pending.branch);
             } catch (error) {
               console.error(`[tool-result-guard] agent=${this.agentName} could not spill withheld result ` +
                 `${block.toolUseId}:`, error);
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index eefcef76a..d4f8716b2 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1233,8 +1233,8 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
   let release!: () => void;
   const gate = new Promise<void>((resolve) => { release = resolve; });
   const labels: string[] = [];
-  // The writer commits a file before it first yields, so the annotation is
-  // held after its first file, where a rollback can land between two writes.
+  // The annotation is held after its first write, where a rollback can land
+  // between two writes. (A rollback during a write: the next test.)
   (h.framework as unknown as { writeToolResultFile: (label: string) => Promise<null> }).writeToolResultFile = async (label) => {
     labels.push(label);
     if (labels.length === 1) await gate;
@@ -1269,6 +1269,54 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
   } finally { release(); await h.framework.stop(); }
 });
 
+test('#277: a write under way when a rollback lands is refused where it commits, and neither branch gets its file', async () => {
+  const h = await workspaceHarness([[calls('one', 'two')]]);
+  type Writer = (label: string, text: string, branch?: string) => Promise<{ path: string; error?: string } | null>;
+  const framework = h.framework as unknown as { writeToolResultFile: Writer };
+  const write = framework.writeToolResultFile.bind(h.framework);
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => { release = resolve; });
+  const branches: Array<string | undefined> = [];
+  // The first write is held after the guard's branch check and before the
+  // workspace commits the file: the rollback lands in between.
+  framework.writeToolResultFile = async (label, text, branch) => {
+    branches.push(branch);
+    if (branches.length === 1) await gate;
+    return write(label, text, branch);
+  };
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  try {
+    await h.run().catch(() => {});
+    for (let i = 0; i < 100 && branches.length === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(branches.length, 1, "the aborted batch's first original is being written");
+    const agent = h.framework.getAgent('assistant')!;
+    const cm = agent.getContextManager();
+    const source = cm.currentBranch().name;
+    assert.equal(branches[0], source, "the write names the batch's branch");
+    const read = cm.getAllMessages().find((m) => m.content.some((b) => b.type === 'text' && b.text === 'read'))!;
+    await h.framework.rollbackToMessage('assistant', { messageId: read.id });
+    release();
+    await agent.toolResultGuard.whenAnnotated();
+    assert.equal(branches.length, 1, 'nothing more is written once the branch has changed');
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const annotated = audit.find((record) => record.type === 'annotated') as
+      { results: Array<{ toolUseId: string; path?: string; error?: string; skipped?: string }> } | undefined;
+    assert.ok(annotated, `the annotation is recorded: ${JSON.stringify(audit)}`);
+    const [one, two] = annotated.results;
+    assert.equal(one.toolUseId, 'one');
+    assert.equal(one.error, 'the workspace had left the branch this file is for');
+    assert.deepEqual(two, { toolUseId: 'two', skipped: 'branch_changed' });
+    const relative = one.path!.replace(/^work\//, '');
+    const store = h.framework.getStore();
+    assert.equal(store.treeGet('workspace/work/tree', relative), null, 'the branch rolled back to has no file');
+    await cm.switchBranch(source);
+    assert.equal(store.treeGet('workspace/work/tree', relative), null, "nor does the batch's own branch");
+  } finally { release(); await h.framework.stop(); }
+});
+
 class BudgetProbe extends PassthroughStrategy {
   store?: { estimateTokens(message: { content: ContentBlock[] }): number };
   select(...args: Parameters<PassthroughStrategy['select']>) {
@@ -1309,7 +1357,7 @@ test('#277: direct API: the refusal retry fits the budget, though its stubs are
   } finally { await h.framework.stop(); }
 });
 
-test("#277: writeBinary sets its tree entry before it first yields, as the guard's branch check relies on", async () => {
+test('#277: writeBinary for a branch writes there, and is refused once the workspace has left it', async () => {
   const dir = mkdtempSync(join(tmpdir(), 'af-guard-write-binary-')); dirs.push(dir);
   mkdirSync(join(dir, 'mount'));
   const store = JsStore.openOrCreate({ path: join(dir, 'store') });
@@ -1317,18 +1365,17 @@ test("#277: writeBinary sets its tree entry before it first yields, as the guard
   workspace.initStore(store);
   try {
     const tree = 'workspace/work/tree';
-    const path = 'tool-results/original.txt';
     const source = store.currentBranch().name;
     const before = store.currentSequence();
-    const writing = workspace.writeBinary(`work/${path}`, Buffer.from('original'), 'text/plain');
-    assert.ok(store.treeGet(tree, path), 'the entry is in the tree before the call has yielded');
-    // A branch switch can only come once the call has yielded: the entry
-    // stays where it was written, and the switched-to branch never gets it.
+    const here = await workspace.writeBinary('work/tool-results/here.txt', Buffer.from('here'), 'text/plain', { branch: source });
+    assert.equal(here.success, true);
+    assert.ok(store.treeGet(tree, 'tool-results/here.txt'), 'a write for the current branch lands');
     store.createBranchAt('elsewhere', source, before);
     store.switchBranch('elsewhere');
-    assert.equal((await writing).success, true);
-    assert.equal(store.treeGet(tree, path), null, 'nothing lands on the branch switched to');
+    const there = await workspace.writeBinary('work/tool-results/there.txt', Buffer.from('there'), 'text/plain', { branch: source });
+    assert.deepEqual(there, { success: false, error: 'the workspace had left the branch this file is for', isError: true });
+    assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nothing lands on the branch the workspace is on');
     store.switchBranch(source);
-    assert.ok(store.treeGet(tree, path), 'the entry is on the branch it was written on');
+    assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nor on the branch the write named');
   } finally { store.close(); }
 });

From 47c1483bc473a67f5073ab71485122f43db2ce3c Mon Sep 17 00:00:00 2001
From: Nell-1783 <nell-1783@commons.astra.invalid>
Date: Sun, 11 Oct 2026 13:48:51 -0400
Subject: [PATCH 05/16] fix(guard): the annotation's waits are bounded and
 cover every sent compile; its record survives a failed stub edit; the stub
 says only what is so (sw-af281)

Nell-1783's half of the house's haiku review of #281 (sw-af281), split with Ada-1017 (room-203 #71715, #71722):
the annotation's lifecycle and the stub's text. Ada's half, the spill itself, builds on this.

Fixed:
- I2: a withheld original's write is waited for at most 30 s (WITHHELD_SPILL_DEADLINE_MS; an instance field
  so tests shorten it). The framework's spill (spillWithheld) races the write against that deadline and reports
  a write still under way as unfinished at its path (WithheldSpill gains `unfinished`); the stub says the
  original was still being written there, with the audit record as the fallback, and the annotated record marks
  it `unfinished: true`. Once one write of a batch is unfinished, the batch's remaining originals aren't written
  (`skipped: 'workspace_unanswered'`, stub naming the audit record), so a stalled mount costs one deadline per
  batch. Every request, the hold's release and stop() are bounded by it.
- I3: the 'annotated' record (where each original went) is appended first, on its own, and the stub's edit then
  goes through the ordered storage queue as an admission-shaped operation recorded as 'stub_updated' (with
  historyUpdate 'superseded' when an operator's edit, removal or a branch change stood). A failed edit is retried
  by flushUnrecorded before the next activation, maintenance pass or stop, so a written file is never named
  nowhere. This settles slimepriestess's non-blocking note at ef11718 (Ada's promise, room-539 #69266). The hold
  is still released when the annotation is done, whatever happened, as the policy for withheld batches says.
- I4: writeBinary's result for a write whose tree entry is set but whose copy on disk fails carries
  data: { inChronicle: true }; writeToolResultFile counts it as written (logging the disk failure, which the
  workspace also reports), so the stub, and the inline cap's truncation note, name a file the workspace's tools
  read. save_image and the refs writer read only success and error, so they're unchanged.
- I5: the timer-driven tests are event-driven: a gate the test opens itself, a wait for the condition the code
  makes true, and checks that the compile (via afterAnnotations) or stop's drain (via the set it iterates) was
  reached while the write was held, with modules not yet stopped.
- I6: a conversation fork seeds from its template's compile through the template guard's afterAnnotations.
- I7: ToolResultGuard.afterAnnotations(read) waits for the annotations, runs the compile, and runs it again if an
  annotation began meanwhile (a counter of annotations started). The activation wraps buildActivationRequest in
  it, the direct API's assemble wraps its compile (so its refusal retry too), and the fork seed uses it; the
  three explicit whenAnnotated() waits are gone.
- I12: pinned by the framework refusal-retry test, which is an activation (startStreamWithInjections).
- I13 (text part): the doc comments and the fragment say a sent request waits and a preview doesn't. Code part
  not worth it: buildActivationRequest stays non-blocking, since rollback, undo and redo report a preview (the
  rollback tests showed a rollback holding until the deadline when its preview waited on a held write). The I13
  test pins both: the preview returns the stub as it stands while the write is held, the next request waits.
- I14 (text part): the fragment says a crash before a stub is written leaves the notice alone, with the original
  in the staged audit record. Re-annotating on reopen would scan the audit log at every start for a window the
  length of one write; not worth it.
- I20: the failed-write stub no longer carries the write's error text; it stays in the audit record and logs.
- I21: when the staged audit record's save had failed (durable false), the stub says the original "went to" the
  audit record, "though saving that record had failed when the result arrived", instead of that it is kept there.
- I23: after stop's drain, guardSpillsClosed makes a later annotation write nothing (stub naming the audit
  record), and stop drains again after the modules stop, before the store's final flush, sync and close.
- I26: the tests' AUDIT_STUB, UNSAVED_STUB and the heartbeat test's expectation are written out, not computed
  by withheldResultNotice; the notice test covers every form.

Not changed: I10 (not worth it: the framework serializes an agent's starts by turn token; the direct API's gap
between its status check and state write predates #281, since its compile already awaited there) and I25 (not
worth it: the stub edit adds a provider cache miss only where a bare notice was on the wire, a batch never
submitted or whose audit failed; a refused batch's originals give way to the stub either way).
---
 .../guard-withheld-names-original.fixed.md    |  39 +-
 src/agent.ts                                  |  21 +-
 src/framework.ts                              |  88 ++++-
 src/modules/workspace/index.ts                |   9 +
 src/tool-result-guard.ts                      | 128 ++++--
 test/silent-heartbeat-rows.test.ts            |   7 +-
 test/tool-result-guard.test.ts                | 368 +++++++++++++++---
 7 files changed, 548 insertions(+), 112 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 5a850cf35..56106f659 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -4,16 +4,35 @@
   first writable mount's `tool-results/` (named
   `<date>-withheld-<batch>-<index>-<toolUseId>`, one per result), or, with no
   writable workspace or a failed write, the guard's audit record
-  (`framework/tool-result-guard`), for an operator. This holds for every
-  withheld settlement: a refusal, an aborted stream, a batch that was never
-  submitted, and one whose audit sync failed. The notice still names no
-  refusal and no category. The stub is written before any request is compiled,
-  including the refusal retry, and before stop closes the store. If the active
-  branch changes while the originals are being written, no more are written,
-  a write already under way is refused where it commits, and the stub stays
-  as it was, so no original lands on another branch. For this,
+  (`framework/tool-result-guard`), for an operator. A failed write's own error
+  stays in the audit record and the logs. When saving the audit record itself
+  had failed as the result arrived, the stub says so rather than that the
+  original is kept there. This holds for every withheld settlement: a refusal,
+  an aborted stream, a batch that was never submitted, and one whose audit sync
+  failed. The notice still names no refusal and no category. Before this, a
+  withheld result left only the notice, so the agent couldn't tell what the
+  tool had done (agent-framework #277).
+- How the stub is written. Where each original went is recorded first, and the
+  stub's edit is retried before the next activation, maintenance pass or stop
+  if it fails, so no written file goes unnamed. A file whose copy on disk fails
+  is still in the workspace's tree, where its tools read it, so the stub names
+  it; for this, `WorkspaceModule.writeBinary`'s result for that case carries
+  `data: { inChronicle: true }`. A write still under way after 30 seconds, as
+  on a stalled mount, is named as unfinished, with the audit record as the
+  fallback, and the batch's remaining originals then go only to the audit
+  record, so a stalled workspace can't hold the agent's requests or the
+  framework's stop. Every request that is sent is compiled only once its stubs
+  say where their originals went, including the refusal retry and a stub whose
+  annotation began during the compile, and a conversation fork seeded from its
+  template copies only such stubs. A request preview doesn't wait, so rollback,
+  undo and redo never wait on a workspace write, and a preview can show a stub
+  before its place is added. Stop lets running annotations finish while the
+  workspace is up; one that starts after that writes no file and is saved
+  before the store closes. A crash before a stub is written leaves the notice
+  alone, and the staged audit record still holds the original. If the active
+  branch changes while the originals are being written, no more are written, a
+  write already under way is refused where it commits, and the stub stays as
+  it was, so no original lands on another branch. For this,
   `WorkspaceModule.writeBinary` takes an optional `branch`: the file lands on
   that branch or isn't written. The direct Agent API's refusal retry is now
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
-  Before this, a withheld result left only the notice, so the agent couldn't
-  tell what the tool had done (agent-framework #277).
diff --git a/src/agent.ts b/src/agent.ts
index 30ff1d284..c7d5de6bf 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -655,8 +655,6 @@ export class Agent {
     }
 
     this.toolResultGuard.flushUnrecorded();
-    // A withheld stub is compiled only once it says where its original went.
-    await this.toolResultGuard.whenAnnotated();
 
     // Filter tools to only allowed ones
     const tools = availableTools.filter((t) => this.canUseTool(t.name));
@@ -677,9 +675,12 @@ export class Agent {
       ? this.buildToolResultMessages(this._state.toolResults) : [];
 
     // Compile the context (with optional injections) into a request. The
-    // guard's refusal retry is assembled the same way, afresh.
+    // guard's refusal retry is assembled the same way, afresh. A withheld
+    // stub is compiled only once it says where its original went, including
+    // one whose annotation began during the compile (#281 I7).
     const assemble = async (): Promise<NormalizedRequest> => {
-      const { messages, systemInjections } = await this.compileWithInjections(budget, injections);
+      const { messages, systemInjections } = await this.toolResultGuard.afterAnnotations(
+        () => this.compileWithInjections(budget, injections));
       messages.push(...unguardedResults);
       return {
         messages: this.toolResultGuard.prepareRequest(messages, true),
@@ -797,6 +798,10 @@ export class Agent {
    * it does not touch agent state and does not call the membrane, and
    * `ContextManager.compile` is itself side-effect-free (compression runs in
    * the background). Safe to call regardless of the agent's current status.
+   * It doesn't wait for the tool-result guard's annotations, so a preview
+   * never waits on a workspace write (rollback, undo and redo report one), and
+   * may show a withheld stub before its place is added; the activation waits
+   * for them around its call (#281 I13).
    */
   async buildActivationRequest(
     availableTools: ToolDefinition[],
@@ -939,8 +944,6 @@ export class Agent {
     // Retry accepted history edits before assembling a real request. Pure
     // preview/compile entry points must not perform these writes.
     this.toolResultGuard.flushUnrecorded();
-    // A withheld stub is compiled only once it says where its original went.
-    await this.toolResultGuard.whenAnnotated();
 
     // A new activation supersedes every receipt flight the previous one left
     // open. Membrane fires the kv-unified wire receipt per provider attempt,
@@ -967,7 +970,10 @@ export class Agent {
     this.lastStreamRealInputTokens = 0;
     this.lastStreamOutputTokens = 0;
 
-    const request = await this.buildActivationRequest(availableTools, injections, budget, compressionTools, options);
+    // A withheld stub is compiled only once it says where its original went,
+    // including one whose annotation began during the compile (#281 I7).
+    const request = await this.toolResultGuard.afterAnnotations(
+      () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
     request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
 
     const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
@@ -1203,7 +1209,6 @@ export class Agent {
         // says where its original went (agent-framework #277), and against the
         // budget without the batch's reservation, so a stub longer than its
         // original can't carry the request past the budget.
-        await this.toolResultGuard.whenAnnotated();
         response = await this.membrane.stream(await reassemble(), { signal });
       }
     }
diff --git a/src/framework.ts b/src/framework.ts
index 1a5cd02c7..e4812b874 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -88,6 +88,7 @@ import { ChannelRegistry, type ChannelToolOrigin } from './mcpl/channel-registry
 import { ConversationRouter, CONVERSATION_ROUTING_DEPRECATION_NOTICE } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import type { WorkspaceModule } from './modules/workspace/index.js';
+import type { WithheldSpill } from './tool-result-guard.js';
 import {
   toolResultDataToHistoryString,
   truncateForHistory,
@@ -769,6 +770,11 @@ class DefaultErrorPolicy implements ErrorPolicy {
 
 /** Default sync interval in milliseconds */
 const DEFAULT_SYNC_INTERVAL_MS = 1000;
+/** How long the tool-result guard waits for a withheld original's workspace
+ *  write before its stub says the write was still under way (#281 I2). A local
+ *  write takes milliseconds; this bounds a stalled mount, which would otherwise
+ *  hold every later request of the agent and the framework's stop. */
+const WITHHELD_SPILL_DEADLINE_MS = 30_000;
 /** Poll pending context-strategy maintenance independently of user activity. */
 const DEFAULT_MAINTENANCE_INTERVAL_MS = 5000;
 /** Bound one pass so a large backlog yields to inference and other agents. */
@@ -2023,6 +2029,10 @@ export class AgentFramework {
     // Tracked here rather than per agent, since an ephemeral run or a closed
     // fork leaves the agent map while its annotation can still be running.
     while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
+    // An annotation that starts after this point, such as one from a direct
+    // Agent API call stop doesn't cancel, writes no file to the stopping
+    // workspace: its stub names the audit record (#281 I23).
+    this.guardSpillsClosed = true;
 
     // Stop modules and MCPL servers in parallel
     const shutdownPromises: Promise<void>[] = [this.moduleRegistry.stopAll()];
@@ -2031,6 +2041,10 @@ export class AgentFramework {
     }
     await Promise.all(shutdownPromises);
 
+    // Those later annotations write nothing, so they finish at once; let them
+    // record and edit their stubs before the store closes (#281 I23).
+    while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
+
     // Streams may queue storage repairs while being cancelled above. Retry
     // after their teardown, while the store is still open, before final sync.
     for (const agent of this.agents.values()) {
@@ -2702,6 +2716,12 @@ export class AgentFramework {
 
   /** Every guard's annotation still running, for stop() (agent-framework #277). */
   private readonly guardAnnotations = new Set<Promise<void>>();
+  /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
+  private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
+  /** Set once stop() has let the running annotations finish: a withheld
+   *  original is then no longer written to a workspace that is stopping, and
+   *  its stub names the audit record (#281 I23). */
+  private guardSpillsClosed = false;
 
   /** A new agent's guard: its persisted setting, the tool-results spill its
    *  withheld originals are written to, and the set stop() waits on
@@ -2715,7 +2735,7 @@ export class AgentFramework {
     }
     agent.toolResultGuard.setOverride(enabled);
     agent.toolResultGuard.setHost({
-      spill: (label, text, branch) => this.writeToolResultFile(label, text, branch),
+      spill: (label, text, branch) => this.spillWithheld(label, text, branch),
       track: (annotation) => {
         this.guardAnnotations.add(annotation);
         void annotation.finally(() => this.guardAnnotations.delete(annotation));
@@ -7396,7 +7416,11 @@ export class AgentFramework {
       // seeding again would stack another template copy on top of it.
       const { messages: existing } = await contextManager.compile();
       if (existing.length === 0) {
-        const { messages: compiled } = await template.getContextManager().compile();
+        // The copy is the fork's own, and the template's annotation edits only
+        // the template's message: seed only from stubs that already say where
+        // their originals went (#281 I6).
+        const { messages: compiled } = await template.toolResultGuard.afterAnnotations(
+          () => template.getContextManager().compile());
         for (const msg of compiled) {
           const participant = msg.participant === template.name ? name : msg.participant;
           contextManager.addMessage(participant, msg.content);
@@ -11723,27 +11747,67 @@ export class AgentFramework {
     return { blocks, spilled };
   }
 
+  /** Where a tool result labelled `label` is written: `<first writable
+   *  mount>/tool-results/<label>.txt`, or null when there is no writable
+   *  workspace. */
+  private toolResultFilePlace(label: string): { workspace: WorkspaceModule; path: string; safeLabel: string } | null {
+    const workspace = this.getWorkspaceModule();
+    const mountName = workspace ? this.firstWritableMountName(workspace) : null;
+    if (!workspace || !mountName) return null;
+    const safeLabel = label.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
+    return { workspace, path: `${mountName}/tool-results/${safeLabel}.txt`, safeLabel };
+  }
+
   /**
-   * Write one tool result's text to `<first writable mount>/tool-results/
-   * <label>.txt`: the one place both the inline cap's spill and the guard's
-   * withheld originals go. null when there is no writable workspace. A failed
-   * write is reported, traced and logged here, never thrown. With a branch,
-   * the file lands on that branch or isn't written (see writeBinary).
+   * The guard's spill of a withheld original (agent-framework #277): the
+   * tool-results file, waited for at most withheldSpillDeadlineMs. A write
+   * still under way then is reported as unfinished at its path, and goes on
+   * by itself (#281 I2). Once stop() has let the running annotations finish,
+   * nothing more is written (#281 I23).
+   */
+  private async spillWithheld(label: string, text: string, branch: string): Promise<WithheldSpill> {
+    if (this.guardSpillsClosed) return null;
+    const place = this.toolResultFilePlace(label);
+    if (!place) return null;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const late = new Promise<WithheldSpill>((resolve) => {
+      timer = setTimeout(() => resolve({ path: place.path, unfinished: true }), this.withheldSpillDeadlineMs);
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([this.writeToolResultFile(label, text, branch), late]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Write one tool result's text to its tool-results file (see
+   * toolResultFilePlace): the one place both the inline cap's spill and the
+   * guard's withheld originals go. null when there is no writable workspace.
+   * A failed write is reported, traced and logged here, never thrown. With a
+   * branch, the file lands on that branch or isn't written (see writeBinary).
    */
   private async writeToolResultFile(
     label: string,
     content: string,
     branch?: string,
   ): Promise<{ path: string; error?: string } | null> {
-    const workspace = this.getWorkspaceModule();
-    const mountName = workspace ? this.firstWritableMountName(workspace) : null;
-    if (!workspace || !mountName) return null;
-    const safeLabel = label.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
-    const path = `${mountName}/tool-results/${safeLabel}.txt`;
+    const place = this.toolResultFilePlace(label);
+    if (!place) return null;
+    const { workspace, path, safeLabel } = place;
     let failure: string;
     try {
       const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain', { branch });
       if (result.success) return { path };
+      // The file is in the workspace's Chronicle tree, where its tools read
+      // it, and only its copy on disk failed: it is written for every reader
+      // the stub or the truncation note sends there (#281 I4). The workspace
+      // reports the disk failure itself (workspace:materialize-failed).
+      if ((result.data as { inChronicle?: boolean } | undefined)?.inChronicle === true) {
+        console.error(`[spill] ${path} is in the workspace's Chronicle tree, but its copy on disk failed: ${result.error}`);
+        return { path };
+      }
       failure = result.error ?? 'write refused';
     } catch (err) {
       failure = err instanceof Error ? err.message : String(err);
diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index 58d28bab8..e8438a78f 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1242,6 +1242,10 @@ export class WorkspaceModule implements Module {
    * the check and the entry, so the file lands on that branch or the write is
    * refused. The tool-result guard writes a withheld original this way, for
    * the branch its stub is on (agent-framework #277).
+   *
+   * A write whose tree entry is set but whose copy on disk fails returns
+   * success false with `data: { inChronicle: true }`: the workspace's tools
+   * read the file from the tree, so it is there for them (#281 I4).
    */
   async writeBinary(
     mountPrefixedPath: string,
@@ -1279,10 +1283,15 @@ export class WorkspaceModule implements Module {
     });
     const materializeError = await this.autoMaterialize(mount, relativePath, 'write', data);
     if (materializeError) {
+      // The file is in the Chronicle tree, where the workspace's tools read
+      // it; only its copy on disk failed. `inChronicle` lets a caller that
+      // needs the file readable tell this from a write that never happened
+      // (agent-framework #281 I4).
       return {
         success: false,
         error: `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`,
         isError: true,
+        data: { inChronicle: true },
       };
     }
     return {
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 656d5bb69..730297596 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -8,15 +8,19 @@ import { isStateExistsError } from './module-registry.js';
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
-/** Where a withheld result's original was written: a workspace path, the
- *  path a write to it failed at, or null when there is no writable workspace. */
-export type WithheldSpill = { path: string; error?: string } | null;
+/** Where a withheld result's original was written: a workspace path; the
+ *  path a write to it failed at (`error`); the path a write was still under
+ *  way to when the host stopped waiting for it (`unfinished`); or null when
+ *  there is no writable workspace. */
+export type WithheldSpill = { path: string; error?: string; unfinished?: true } | null;
 
 /** Writes one withheld original as a workspace file (the framework's
- *  tool-results spill). It reports a failed write rather than throwing. The
- *  file lands on `branch`, the branch the stub is on, or isn't written: the
- *  workspace checks the branch where it commits the file
- *  (WorkspaceModule.writeBinary). */
+ *  tool-results spill). It reports a failed write rather than throwing, and
+ *  it settles within a bounded time: a write still under way at the host's
+ *  deadline is reported as unfinished, so one stalled write can't hold every
+ *  later request and the host's stop (#281 I2). The file lands on `branch`,
+ *  the branch the stub is on, or isn't written: the workspace checks the
+ *  branch where it commits the file (WorkspaceModule.writeBinary). */
 export type WithheldSpiller = (label: string, text: string, branch: string) => Promise<WithheldSpill>;
 
 /** What a host gives a guard for its withheld results: where originals are
@@ -31,20 +35,28 @@ export interface WithheldHost {
  * The stub a withheld result settles to: #159's neutral notice, then where
  * the original is. It names no refusal and no category (#159 keeps those in
  * operational logs), only the place, so reading it back is the agent's
- * deliberate choice (agent-framework #277).
+ * deliberate choice (agent-framework #277). A failed write's own error text
+ * stays in the audit record and the logs, not here (#281 I20). The audit
+ * record is said to keep the original only when it was saved: a staged
+ * record whose save failed is still queued in memory, and a restart before
+ * its retry loses it (#281 I21).
  */
 export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean): string {
-  const audit = auditDurable
-    ? `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`
-    : `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator, though saving that record had failed when this was written`;
+  const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
+  const kept = (only: string) => auditDurable
+    ? `is kept ${only}in ${audit}`
+    : `went ${only}to ${audit}, though saving that record had failed when the result arrived`;
+  if (spill?.unfinished) {
+    return `${TOOL_RESULT_GUARD_NOTICE} Its full result was still being written to workspace file ${spill.path} ` +
+      `when this note was made; if that file is missing, it ${kept('')}.`;
+  }
   if (spill && spill.error === undefined) {
     return `${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${spill.path}.`;
   }
   if (spill) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Writing its full result to workspace file ${spill.path} failed (${spill.error}), ` +
-      `so it is kept only in ${audit}.`;
+    return `${TOOL_RESULT_GUARD_NOTICE} Writing its full result to workspace file ${spill.path} failed, so it ${kept('only ')}.`;
   }
-  return `${TOOL_RESULT_GUARD_NOTICE} Its full result is kept in ${audit}.`;
+  return `${TOOL_RESULT_GUARD_NOTICE} Its full result ${kept('')}.`;
 }
 
 interface PendingBatch {
@@ -87,6 +99,8 @@ export class ToolResultGuard {
   private host: WithheldHost | undefined;
   /** Annotations of withheld stubs, chained in settlement order. */
   private annotating: Promise<void> | undefined;
+  /** Annotations started so far, so a read can tell one began during it. */
+  private annotationsStarted = 0;
 
   constructor(
     private readonly agentName: string,
@@ -97,9 +111,29 @@ export class ToolResultGuard {
   get enabled(): boolean { return this.override ?? this.configured; }
   setHost(host: WithheldHost | undefined): void { this.host = host; }
   /** Settles once every withheld stub settled so far names where its
-   *  original is (or that edit was given up). A request is compiled only
-   *  after this, so no request carries a stub that is still being written. */
+   *  original is (or that edit was given up). It never rejects, and it is
+   *  bounded: the host reports a write still under way at its deadline as
+   *  unfinished (#281 I2). */
   whenAnnotated(): Promise<void> { return this.annotating ?? Promise.resolve(); }
+
+  /**
+   * Runs `read` (a compile of the context) once no withheld stub is still
+   * being annotated, and again if an annotation began while it ran, since a
+   * settlement can land during the compile's own awaits, such as a previous
+   * frame's teardown abandoning its batch (#281 I7). Every compile of a
+   * request that is sent goes through it: the agent's activations, its direct
+   * API calls and their refusal retry, and a conversation fork's seed from its
+   * template (#281 I6). A request preview doesn't, so it never waits on a
+   * workspace write (#281 I13).
+   */
+  async afterAnnotations<T>(read: () => Promise<T>): Promise<T> {
+    for (;;) {
+      await this.whenAnnotated();
+      const started = this.annotationsStarted;
+      const result = await read();
+      if (this.annotationsStarted === started) return result;
+    }
+  }
   setOverride(value: boolean | undefined): void { this.override = value; }
   get settingOverride(): boolean | undefined { return this.override; }
   get hasPending(): boolean { return this.pending !== undefined; }
@@ -367,9 +401,17 @@ export class ToolResultGuard {
    * takes it, else kept in the audit record. Its own unedited placeholder is
    * the only thing it edits: an operator's later edit, removal or rollback
    * stands. It releases the compression hold when done, whatever happened.
+   *
+   * Where each original went is recorded first, on its own ('annotated'), so
+   * a stub edit that fails can't take the record of a written file with it.
+   * The edit then goes through the ordered storage queue like an admission's:
+   * retried before the next activation, maintenance pass or stop until it
+   * lands or an operator's change supersedes it ('stub_updated'), so a failed
+   * edit no longer leaves a written file named nowhere (#281 I3).
    */
   private annotate(pending: PendingBatch): void {
     const previous = this.annotating ?? Promise.resolve();
+    this.annotationsStarted += 1;
     const run = previous.then(async () => {
       try {
         const date = new Date().toISOString().slice(0, 10);
@@ -382,6 +424,11 @@ export class ToolResultGuard {
         // Keyed by the result's index in the batch, which the stub and the
         // original share.
         const spills = new Map<number, WithheldSpill>();
+        // Results not written because an earlier write of the batch was still
+        // under way at the host's deadline: the workspace isn't answering, and
+        // waiting a deadline for each would hold every request and stop that
+        // much longer (#281 I2). Their stubs name the audit record.
+        const unanswered = new Set<number>();
         for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
           // Once the store has left the batch's branch (a rollback, an undo, a
@@ -391,6 +438,11 @@ export class ToolResultGuard {
           // under way when the branch changes is refused where it commits,
           // since it names the batch's branch, so no file lands elsewhere.
           if (this.cm.currentBranch().name !== pending.branch) break;
+          if ([...spills.values()].some((spill) => spill?.unfinished)) {
+            unanswered.add(index);
+            spills.set(index, null);
+            continue;
+          }
           const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
           let spill: WithheldSpill = null;
           if (this.host) {
@@ -407,24 +459,36 @@ export class ToolResultGuard {
           && spills.has(index)
           ? { ...block, content: withheldResultNotice(spills.get(index)!, pending.durable) }
           : block);
-        const sameBranch = this.cm.currentBranch().name === pending.branch;
-        const current = sameBranch ? this.cm.getMessage(pending.messageId) : null;
-        const unedited = current !== null && current !== undefined
-          && isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(pending.withheld)));
-        if (unedited) this.cm.editMessage(pending.messageId, annotated);
-        this.append({
-          type: 'annotated', batchId: pending.id, messageId: pending.messageId,
-          results: pending.content.flatMap((block, index): Array<Record<string, string>> => {
-            if (block.type !== 'tool_result') return [];
-            if (!spills.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'branch_changed' }];
-            const spill = spills.get(index);
-            return [{ toolUseId: block.toolUseId, ...(spill ? { path: spill.path } : {}),
-              ...(spill?.error !== undefined ? { error: spill.error } : {}) }];
-          }),
-          ...(unedited ? {} : { historyUpdate: 'superseded' }),
+        try {
+          this.append({
+            type: 'annotated', batchId: pending.id, messageId: pending.messageId,
+            results: pending.content.flatMap((block, index): Array<Record<string, string | true>> => {
+              if (block.type !== 'tool_result') return [];
+              if (!spills.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'branch_changed' }];
+              if (unanswered.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'workspace_unanswered' }];
+              const spill = spills.get(index);
+              return [{ toolUseId: block.toolUseId, ...(spill ? { path: spill.path } : {}),
+                ...(spill?.error !== undefined ? { error: spill.error } : {}),
+                ...(spill?.unfinished ? { unfinished: true as const } : {}) }];
+            }),
+          });
+        } catch (error) {
+          // It stays queued and is retried in order with the storage work
+          // ahead of it; the stub's edit waits behind it.
+          console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} annotation record queued for retry:`, error);
+        }
+        this.unrecorded.push({
+          record: { agentName: this.agentName, timestamp: Date.now(), type: 'stub_updated',
+            batchId: pending.id, messageId: pending.messageId },
+          admission: { messageId: pending.messageId, content: annotated, expected: pending.withheld, branch: pending.branch },
         });
+        try {
+          this.flushUnrecorded();
+        } catch (error) {
+          console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} stub edit queued for retry:`, error);
+        }
       } catch (error) {
-        console.error(`[tool-result-guard] agent=${this.agentName} could not annotate withheld results:`, error);
+        console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} could not annotate withheld results:`, error);
       } finally {
         // Never rejects: a compile and stop() wait on this chain.
         try {
diff --git a/test/silent-heartbeat-rows.test.ts b/test/silent-heartbeat-rows.test.ts
index 3a17652c5..f84f9eecd 100644
--- a/test/silent-heartbeat-rows.test.ts
+++ b/test/silent-heartbeat-rows.test.ts
@@ -17,7 +17,7 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { AgentFramework } from '../src/index.js';
 import type { AgentConfig, Module, ModuleContext, ToolCall, ToolDefinition, ToolResult } from '../src/index.js';
-import { TOOL_RESULT_GUARD_NOTICE, withheldResultNotice } from '../src/tool-result-guard.js';
+import { TOOL_RESULT_GUARD_NOTICE } from '../src/tool-result-guard.js';
 import { PassthroughStrategy } from '@animalabs/context-manager';
 import { MockMembrane, MockYieldingStream, createMockResponse } from './helpers/mock-membrane.js';
 import { NativeFormatter } from '@animalabs/membrane';
@@ -411,7 +411,10 @@ describe('silent heartbeat stored rows', () => {
       const tickRows = stored(x.framework).slice(before);
       assert.deepEqual(tickRows.map((m) => m.participant), ['assistant', 'user', 'assistant']);
       for (const row of tickRows) assert.equal(row.metadata?.silentHeartbeat?.eventId, tick.eventId);
-      assert.equal((tickRows[1]!.content[0] as { content?: unknown }).content, withheldResultNotice(null, true));
+      // Written out, not computed by the code under test (#281 I26).
+      assert.equal((tickRows[1]!.content[0] as { content?: unknown }).content, 'Tool result withheld by the guard. ' +
+        "The tool has already executed. Its full result is kept in the guard's audit record (framework/tool-result-guard), " +
+        'for an operator.');
       assert.doesNotMatch(JSON.stringify(tickRows), /discard-this-partial-output/);
 
       const opening = membrane.calls[1]!.messages;
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index d4f8716b2..e344f4d76 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { PassthroughStrategy, type StoredMessage, type StrategyContext } from '@animalabs/context-manager';
@@ -15,9 +15,13 @@ import { WorkspaceModule } from '../src/modules/workspace/index.js';
 import { JsStore } from '@animalabs/chronicle';
 
 // What a withheld result settles to with no writable workspace (#277): the
-// neutral notice, then where the original is kept.
-const AUDIT_STUB = withheldResultNotice(null, true);
-const UNSAVED_STUB = withheldResultNotice(null, false);
+// neutral notice, then where the original is kept. Written out, not computed
+// by withheldResultNotice, so a change of its wording fails here (#281 I26).
+const AUDIT_STUB = 'Tool result withheld by the guard. The tool has already executed. Its full result is kept in ' +
+  "the guard's audit record (framework/tool-result-guard), for an operator.";
+const UNSAVED_STUB = 'Tool result withheld by the guard. The tool has already executed. Its full result went to ' +
+  "the guard's audit record (framework/tool-result-guard), for an operator, though saving that record had failed " +
+  'when the result arrived.';
 
 const dirs: string[] = [];
 afterEach(() => { while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true }); });
@@ -160,7 +164,7 @@ test('withholds the entire latest batch, retries inference once, and keeps origi
     const audit = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     assert.match(JSON.stringify(audit[0]), /original-text-payload|original-error-payload/);
     assert.ok(JSON.stringify(audit[0]).includes(image));
-    assert.deepEqual(audit.slice(-2).map((r) => r.type), ['withheld', 'annotated']);
+    assert.deepEqual(audit.slice(-3).map((r) => r.type), ['withheld', 'annotated', 'stub_updated']);
     const historical = store.getStateJsonAt(TOOL_RESULT_GUARD_AUDIT_STATE, stagedSequence) as unknown[];
     assert.deepEqual(audit[0], historical[0], 'redaction only appends; original Chronicle record is unchanged');
     const original = structuredClone(audit[0]);
@@ -805,7 +809,7 @@ for (const failedType of ['staged', 'linked']) {
       failing = false;
       await h.run(); // A normal activation, with no new tool call, retries the audit.
       const records = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
-      assert.deepEqual(records.map((r) => r.type), ['staged', 'linked', 'withheld', 'annotated']);
+      assert.deepEqual(records.map((r) => r.type), ['staged', 'linked', 'withheld', 'annotated', 'stub_updated']);
       assert.match(JSON.stringify(records[0]), /payload-one/, 'the original is recoverable after storage returns');
       assert.doesNotMatch(JSON.stringify(h.membrane.requests[1]), /payload-one/);
       assert.deepEqual(h.module.calls, ['one']);
@@ -905,7 +909,7 @@ test('storage recovery: endTurn never admits a batch whose audit sync failed', a
     await h.run();
     assert.doesNotMatch(JSON.stringify(h.membrane.requests[1]), /payload-one/);
     const records = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
-    assert.deepEqual(records.slice(-2).map((r) => r.type), ['withheld', 'annotated']);
+    assert.deepEqual(records.slice(-3).map((r) => r.type), ['withheld', 'annotated', 'stub_updated']);
     assert.match(JSON.stringify(records[0]), /payload-one/, 'the original is still archived');
   } finally { store.sync = sync; await h.framework.stop(); }
 });
@@ -984,7 +988,7 @@ test('storage recovery: shutdown retries edits queued by its terminating stream'
 // file when a writable mount takes it, else the guard's audit record.
 // ---------------------------------------------------------------------------
 
-async function workspaceHarness(scripts: NormalizedResponse[][], mount: { maxFileSize?: number } = {}) {
+async function workspaceHarness(scripts: NormalizedResponse[][], mount: { maxFileSize?: number; autoMaterialize?: boolean } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'af-tool-result-guard-ws-')); dirs.push(dir);
   const mountDir = join(dir, 'mount');
   mkdirSync(mountDir, { recursive: true });
@@ -993,6 +997,7 @@ async function workspaceHarness(scripts: NormalizedResponse[][], mount: { maxFil
   const workspace = new WorkspaceModule({ mounts: [{
     name: 'work', path: mountDir, mode: 'read-write', watch: 'never',
     ...(mount.maxFileSize !== undefined ? { maxFileSize: mount.maxFileSize } : {}),
+    ...(mount.autoMaterialize !== undefined ? { autoMaterialize: mount.autoMaterialize } : {}),
   }] });
   const framework = await AgentFramework.create({ storePath: join(dir, 'store'), membrane: membrane.asMembrane(),
     agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system', toolResultGuard: true }],
@@ -1002,18 +1007,48 @@ async function workspaceHarness(scripts: NormalizedResponse[][], mount: { maxFil
     framework.pushEvent({ type: 'external-message', source: 'test', content: 'read', metadata: {} });
     await framework.runUntilIdle();
   };
-  return { framework, membrane, module, workspace, run };
+  return { framework, membrane, module, workspace, run, mountDir, storePath: join(dir, 'store') };
 }
 
-/** Delay the framework's tool-results writer (no workspace: it then reports
- *  none), keeping the framework's own wiring and tracking in place. */
+/** Delay the framework's spill of withheld originals (it then reports no
+ *  workspace), keeping the framework's own wiring and tracking in place. */
 function slowSpill(framework: AgentFramework, wait: () => Promise<unknown>) {
-  (framework as unknown as { writeToolResultFile: () => Promise<null> }).writeToolResultFile = async () => {
+  (framework as unknown as { spillWithheld: () => Promise<null> }).spillWithheld = async () => {
     await wait();
     return null;
   };
 }
 
+/** A gate a test opens itself, and a wait for a condition the code under test
+ *  makes true (#281 I5: no fixed timers standing in for events). */
+function gate() {
+  let open!: () => void;
+  const opened = new Promise<void>((resolve) => { open = resolve; });
+  return { opened, open };
+}
+async function until(check: () => boolean, what: string) {
+  for (let i = 0; i < 400 && !check(); i++) await new Promise((resolve) => setTimeout(resolve, 5));
+  assert.ok(check(), `timed out waiting until ${what}`);
+}
+
+/** Calls of a guard's afterAnnotations, the compile's wait for its stubs. */
+function watchCompiles(framework: AgentFramework, agentName = 'assistant') {
+  const guard = framework.getAgent(agentName)!.toolResultGuard;
+  const watched = { calls: 0 };
+  const original = guard.afterAnnotations.bind(guard);
+  guard.afterAnnotations = (read) => { watched.calls++; return original(read); };
+  return watched;
+}
+
+/** Whether stop() has reached its wait for the guards' annotations. */
+function watchStopDrain(framework: AgentFramework) {
+  const annotations = (framework as unknown as { guardAnnotations: Set<Promise<void>> }).guardAnnotations;
+  const watched = { reached: false };
+  const iterate = annotations[Symbol.iterator].bind(annotations);
+  annotations[Symbol.iterator] = () => { watched.reached = true; return iterate(); };
+  return watched;
+}
+
 const SPILLED_STUB = /^Tool result withheld by the guard\. The tool has already executed\. Its full result is in workspace file (work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt)\.$/;
 
 test('#277: a withheld original is written to the workspace, and its stub names the file', async () => {
@@ -1034,7 +1069,9 @@ test('#277: a withheld original is written to the workspace, and its stub names
     const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
     assert.deepEqual(retried.map((b) => b.content), [stub], 'the retry already says where the original is');
     assert.doesNotMatch(stub, /refus|test-category/, "#159's line: no refusal or category in the context");
-    assert.deepEqual(audit.at(-1), { ...audit.at(-1), type: 'annotated', results: [{ toolUseId: 'one', path }] });
+    assert.deepEqual(audit.at(-2), { ...audit.at(-2), type: 'annotated', results: [{ toolUseId: 'one', path }] });
+    assert.equal(audit.at(-1)?.type, 'stub_updated');
+    assert.equal(audit.at(-1)?.historyUpdate, undefined, 'the stub was edited to name the file');
   } finally { await h.framework.stop(); }
 });
 
@@ -1043,9 +1080,10 @@ test('#277: a failed workspace write says so, and the audit record still keeps t
   try {
     await h.run();
     const stub = String(toolResults(h.framework)[0].content);
-    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its full result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt failed \(.+\), so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
+    // The write's own error stays in the audit record and the logs (#281 I20).
+    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its full result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt failed, so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
-    const annotated = audit.at(-1) as { type: string; results: Array<{ toolUseId: string; path?: string; error?: string }> };
+    const annotated = audit.at(-2) as { type: string; results: Array<{ toolUseId: string; path?: string; error?: string }> };
     assert.equal(annotated.type, 'annotated');
     assert.equal(annotated.results[0].toolUseId, 'one');
     assert.equal(typeof annotated.results[0].error, 'string');
@@ -1054,13 +1092,22 @@ test('#277: a failed workspace write says so, and the audit record still keeps t
 });
 
 test('#277: the refusal retry is compiled only once the stub says where the original is', async () => {
+  // The framework's retry is a new activation (startStreamWithInjections), so
+  // this also pins that path's wait (#281 I12).
   const h = await harness([[calls('one'), refused()], [answer()]], { toolResultGuard: true });
-  slowSpill(h.framework, () => new Promise((resolve) => setTimeout(resolve, 100)));
+  const write = gate();
+  let spills = 0;
+  slowSpill(h.framework, () => { spills++; return write.opened; });
+  const compiles = watchCompiles(h.framework);
   try {
-    await h.run();
+    const running = h.run();
+    await until(() => spills === 1 && compiles.calls >= 2, 'the retry is being compiled while the stub is written');
+    assert.equal(h.membrane.requests.length, 1, 'the retry waits for the stub');
+    write.open();
+    await running;
     const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
     assert.deepEqual(retried.map((b) => b.content), [AUDIT_STUB]);
-  } finally { await h.framework.stop(); }
+  } finally { write.open(); await h.framework.stop(); }
 });
 
 test("#277: an operator's edit made before the stub is annotated stands, and the hold waits for it", async () => {
@@ -1081,17 +1128,21 @@ test("#277: an operator's edit made before the stub is annotated stands, and the
     assert.equal((r.cm.getMessage(r.messageId)!.content[0] as { content: unknown }).content, 'operator replacement');
     assert.equal(r.cm.getCompressionHolds().size, 0);
     const audit = r.cm.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
-    assert.equal(audit.at(-1)?.type, 'annotated');
+    assert.equal(audit.at(-2)?.type, 'annotated');
+    assert.equal(audit.at(-1)?.type, 'stub_updated');
     assert.equal(audit.at(-1)?.historyUpdate, 'superseded');
   } finally { r.cm.close(); }
 });
 
 test('#277: stop lets an aborted batch\'s stub be annotated before the store closes', async () => {
   const h = await harness([[calls('one')]], { toolResultGuard: true });
-  let release!: () => void;
-  const gate = new Promise<void>((resolve) => { release = resolve; });
+  const write = gate();
   let spills = 0;
-  slowSpill(h.framework, () => { spills++; return gate; });
+  slowSpill(h.framework, () => { spills++; return write.opened; });
+  const drain = watchStopDrain(h.framework);
+  let modulesStopped = false;
+  const stopModule = h.module.stop.bind(h.module);
+  h.module.stop = async () => { modulesStopped = true; await stopModule(); };
   h.membrane.onSubmit = () => {
     const stream = h.membrane.streams.at(-1)!;
     queueMicrotask(() => stream.cancel());
@@ -1099,30 +1150,46 @@ test('#277: stop lets an aborted batch\'s stub be annotated before the store clo
   let stopped = false;
   try {
     await h.run().catch(() => {});
-    for (let i = 0; i < 100 && spills === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
-    assert.equal(spills, 1, 'the aborted batch is being annotated');
+    await until(() => spills === 1, 'the aborted batch is being annotated');
     const stopping = h.framework.stop().then(() => { stopped = true; });
-    setTimeout(release, 50);
+    await until(() => drain.reached, 'stop waits for the annotation');
+    assert.equal(modulesStopped, false, 'modules and the store wait for the annotation');
+    assert.equal(stopped, false);
+    write.open();
     await stopping;
+    assert.equal(modulesStopped, true);
     const restarted = await AgentFramework.create(h.base);
     try {
       assert.equal(toolResults(restarted)[0].content, AUDIT_STUB, 'the annotated stub was saved before close');
     } finally { await restarted.stop(); }
-  } finally { release(); if (!stopped) await h.framework.stop(); }
+  } finally { write.open(); if (!stopped) await h.framework.stop(); }
 });
 
 test('#277: the stub has the same text for each place the original can be', () => {
   const notice = 'Tool result withheld by the guard. The tool has already executed.';
+  const audit = "the guard's audit record (framework/tool-result-guard), for an operator";
+  const unsaved = `${audit}, though saving that record had failed when the result arrived`;
   assert.equal(withheldResultNotice({ path: 'work/tool-results/2026-10-10-withheld-a.txt' }, true),
     `${notice} Its full result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
-  assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'disk full' }, true),
-    `${notice} Writing its full result to workspace file work/tool-results/x.txt failed (disk full), ` +
-    "so it is kept only in the guard's audit record (framework/tool-result-guard), for an operator.");
-  assert.equal(withheldResultNotice(null, true),
-    `${notice} Its full result is kept in the guard's audit record (framework/tool-result-guard), for an operator.`);
-  assert.equal(withheldResultNotice(null, false),
-    `${notice} Its full result is kept in the guard's audit record (framework/tool-result-guard), for an operator, ` +
-    'though saving that record had failed when this was written.');
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/2026-10-10-withheld-a.txt' }, false),
+    `${notice} Its full result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
+  // A failed write's own error text isn't the model's to read (#281 I20).
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'EACCES: /srv/host/secret' }, true),
+    `${notice} Writing its full result to workspace file work/tool-results/x.txt failed, so it is kept only in ${audit}.`);
+  // The audit record is said to keep it only when that record was saved (#281 I21).
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'disk full' }, false),
+    `${notice} Writing its full result to workspace file work/tool-results/x.txt failed, so it went only to ${unsaved}.`);
+  // A write still under way when the host stopped waiting (#281 I2).
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/y.txt', unfinished: true }, true),
+    `${notice} Its full result was still being written to workspace file work/tool-results/y.txt when this note ` +
+    `was made; if that file is missing, it is kept in ${audit}.`);
+  assert.equal(withheldResultNotice({ path: 'work/tool-results/y.txt', unfinished: true }, false),
+    `${notice} Its full result was still being written to workspace file work/tool-results/y.txt when this note ` +
+    `was made; if that file is missing, it went to ${unsaved}.`);
+  assert.equal(withheldResultNotice(null, true), `${notice} Its full result is kept in ${audit}.`);
+  assert.equal(withheldResultNotice(null, false), `${notice} Its full result went to ${unsaved}.`);
+  assert.equal(withheldResultNotice(null, true), AUDIT_STUB);
+  assert.equal(withheldResultNotice(null, false), UNSAVED_STUB);
 });
 
 test('#277: direct API: a request after an aborted batch is compiled once its stub is annotated', async () => {
@@ -1135,26 +1202,38 @@ test('#277: direct API: a request after an aborted batch is compiled once its st
     assert.ok(response);
     return response;
   };
+  const write = gate();
+  let spills = 0;
   try {
     const agent = h.framework.getAgent('assistant')!;
-    slowSpill(h.framework, () => new Promise((resolve) => setTimeout(resolve, 100)));
+    slowSpill(h.framework, () => { spills++; return write.opened; });
+    const compiles = watchCompiles(h.framework);
     agent.getContextManager().addMessage('user', [{ type: 'text', text: 'read' }]);
     await agent.runInference(h.framework.getAllTools());
     agent.provideToolResult('one', { success: true, data: 'direct-original' });
     const aborted = await agent.runInference(h.framework.getAllTools());
     assert.equal(aborted.aborted, true);
-    await agent.runInference(h.framework.getAllTools());
-    const next = requests[2].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
-    assert.deepEqual(next.map((b) => b.content), [AUDIT_STUB]);
-  } finally { await h.framework.stop(); }
+    await until(() => spills === 1, 'the aborted batch is being annotated');
+    const before = compiles.calls;
+    const next = agent.runInference(h.framework.getAllTools());
+    await until(() => compiles.calls > before, 'the next request is being compiled while the stub is written');
+    assert.equal(requests.length, 2, 'the next request waits for the stub');
+    write.open();
+    await next;
+    const results = requests[2].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(results.map((b) => b.content), [AUDIT_STUB]);
+  } finally { write.open(); await h.framework.stop(); }
 });
 
 test('#277: stop waits for an annotation started by an ephemeral run it has already disposed', async () => {
   const h = await harness([[calls('one')]]);
-  let release!: () => void;
-  const gate = new Promise<void>((resolve) => { release = resolve; });
+  const write = gate();
   let spills = 0;
-  slowSpill(h.framework, () => { spills++; return gate; });
+  slowSpill(h.framework, () => { spills++; return write.opened; });
+  const drain = watchStopDrain(h.framework);
+  let modulesStopped = false;
+  const stopModule = h.module.stop.bind(h.module);
+  h.module.stop = async () => { modulesStopped = true; await stopModule(); };
   h.membrane.onSubmit = () => {
     const stream = h.membrane.streams.at(-1)!;
     queueMicrotask(() => stream.cancel());
@@ -1168,11 +1247,12 @@ test('#277: stop waits for an annotation started by an ephemeral run it has alre
     const completion = h.framework.runEphemeralToCompletion(created.agent, created.contextManager);
     h.framework.start();
     await completion.catch(() => {});
-    for (let i = 0; i < 100 && spills === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
-    assert.equal(spills, 1, "the ephemeral's aborted batch is being annotated");
+    await until(() => spills === 1, "the ephemeral's aborted batch is being annotated");
     assert.equal(h.framework.getAgent('ephemeral') ?? null, null, 'the run was disposed');
     const stopping = h.framework.stop().then(() => { stopped = true; });
-    setTimeout(release, 50);
+    await until(() => drain.reached, 'stop waits for the annotation');
+    assert.equal(modulesStopped, false, 'modules and the store wait for the annotation');
+    write.open();
     await stopping;
     const restarted = await AgentFramework.create(h.base);
     try {
@@ -1180,7 +1260,7 @@ test('#277: stop waits for an annotation started by an ephemeral run it has alre
       assert.ok(audit.some((r) => r.type === 'annotated' && r.agentName === 'ephemeral'),
         'the annotation finished before the store closed');
     } finally { await restarted.stop(); }
-  } finally { release(); if (!stopped) await h.framework.stop(); }
+  } finally { write.open(); if (!stopped) await h.framework.stop(); }
 });
 
 // ---------------------------------------------------------------------------
@@ -1235,7 +1315,7 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
   const labels: string[] = [];
   // The annotation is held after its first write, where a rollback can land
   // between two writes. (A rollback during a write: the next test.)
-  (h.framework as unknown as { writeToolResultFile: (label: string) => Promise<null> }).writeToolResultFile = async (label) => {
+  (h.framework as unknown as { spillWithheld: (label: string) => Promise<null> }).spillWithheld = async (label) => {
     labels.push(label);
     if (labels.length === 1) await gate;
     return null;
@@ -1261,7 +1341,7 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
     const annotated = audit.find((record) => record.type === 'annotated');
     assert.ok(annotated, `the annotation is recorded on ${rolled.targetBranch}: ${JSON.stringify(audit)}`);
     assert.deepEqual(annotated.results, [{ toolUseId: 'one' }, { toolUseId: 'two', skipped: 'branch_changed' }]);
-    assert.equal(annotated.historyUpdate, 'superseded');
+    assert.equal(audit.find((record) => record.type === 'stub_updated')?.historyUpdate, 'superseded');
     await cm.switchBranch(source);
     const kept = cm.getMessage(batch.id)!.content.filter((b) => b.type === 'tool_result');
     assert.deepEqual(kept.map((b) => (b as { content: unknown }).content), [TOOL_RESULT_GUARD_NOTICE, TOOL_RESULT_GUARD_NOTICE],
@@ -1379,3 +1459,195 @@ test('#277: writeBinary for a branch writes there, and is refused once the works
     assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nor on the branch the write named');
   } finally { store.close(); }
 });
+
+// ---------------------------------------------------------------------------
+// sw-af281's review: the annotation's waits are bounded and cover every
+// compile, its record survives a failed stub edit, and the stub says only
+// what is so.
+// ---------------------------------------------------------------------------
+
+test('#281 I2: a write still under way at the deadline is named as unfinished, and nothing waits on it longer', async () => {
+  const h = await workspaceHarness([[calls('one', 'two'), refused()], [answer()]]);
+  (h.framework as unknown as { withheldSpillDeadlineMs: number }).withheldSpillDeadlineMs = 50;
+  const stalled = gate();
+  let writes = 0;
+  (h.framework as unknown as { writeToolResultFile: () => Promise<null> }).writeToolResultFile = async () => {
+    writes++;
+    await stalled.opened;
+    return null;
+  };
+  let stopped = false;
+  try {
+    await h.run();
+    assert.equal(writes, 1, "once the workspace stopped answering, the batch's next result isn't written");
+    assert.equal(h.membrane.requests.length, 2, 'the retry went out without the write');
+    const [one, two] = toolResults(h.framework).map((block) => String(block.content));
+    assert.match(one, /^Tool result withheld by the guard\. The tool has already executed\. Its full result was still being written to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt when this note was made; if that file is missing, it is kept in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
+    assert.equal(two, AUDIT_STUB);
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const annotated = audit.find((record) => record.type === 'annotated') as { results: Array<Record<string, unknown>> };
+    assert.equal(annotated.results[0].unfinished, true);
+    assert.deepEqual(annotated.results[1], { toolUseId: 'two', skipped: 'workspace_unanswered' });
+    await h.framework.stop();
+    stopped = true;
+    assert.equal(writes, 1, 'stop finished with the write still stalled');
+  } finally { stalled.open(); if (!stopped) await h.framework.stop(); }
+});
+
+test('#281 I3: a failed stub edit leaves the record of the written file, and the edit is retried before the next activation', async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()], [answer()]]);
+  const cm = h.framework.getAgent('assistant')!.getContextManager() as unknown as {
+    editMessage: (id: unknown, content: ContentBlock[]) => unknown;
+  };
+  const edit = cm.editMessage.bind(cm);
+  let failures = 0;
+  cm.editMessage = (id, content) => {
+    if (failures === 0 && JSON.stringify(content).includes('Its full result is in workspace file')) {
+      failures++;
+      throw new Error('injected stub edit failure');
+    }
+    return edit(id, content);
+  };
+  const audit = () => h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+  try {
+    await h.run();
+    assert.equal(failures, 1);
+    const annotated = audit().find((record) => record.type === 'annotated') as { results: Array<{ path?: string }> };
+    const path = annotated.results[0].path;
+    assert.ok(path && SPILLED_STUB.test(`${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${path}.`),
+      `the record names the written file though the edit failed: ${JSON.stringify(annotated)}`);
+    assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE, 'the stub is still the bare notice');
+    assert.equal(audit().some((record) => record.type === 'stub_updated'), false, 'the edit is still queued');
+    await h.run();
+    assert.equal(toolResults(h.framework)[0].content, `${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${path}.`);
+    assert.equal(audit().at(-1)?.type, 'stub_updated');
+    assert.equal(audit().at(-1)?.historyUpdate, undefined);
+    assert.equal(h.framework.getAgent('assistant')!.getContextManager().getCompressionHolds().size, 0);
+  } finally { await h.framework.stop(); }
+});
+
+test("#281 I4: a file whose copy on disk fails is still in the workspace's tree, and the stub names it", async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()]], { autoMaterialize: true });
+  // A file where the directory should be: the copy on disk fails for anyone, root included.
+  writeFileSync(join(h.mountDir, 'tool-results'), 'not a directory');
+  try {
+    await h.run();
+    const stub = String(toolResults(h.framework)[0].content);
+    const path = SPILLED_STUB.exec(stub)?.[1];
+    assert.ok(path, `the stub names the file: ${stub}`);
+    const file = await h.workspace.readBinary(path);
+    assert.ok('data' in file, `the workspace reads it: ${JSON.stringify(file)}`);
+    assert.match((file as { data: Buffer }).data.toString('utf8'), /payload-one/);
+    assert.equal(existsSync(join(h.mountDir, path.replace(/^work\//, ''))), false, 'its copy on disk failed');
+    const annotated = (h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>)
+      .find((record) => record.type === 'annotated') as { results: Array<Record<string, unknown>> };
+    assert.deepEqual(annotated.results, [{ toolUseId: 'one', path }]);
+  } finally { await h.framework.stop(); }
+});
+
+test("#281 I6: a conversation fork seeded while its template's stub is written copies the stub that names the original", async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'af-guard-fork-')); dirs.push(dir);
+  const membrane = new ScriptMembrane([[calls('one')]]);
+  const framework = await AgentFramework.create({ storePath: join(dir, 'store'), membrane: membrane.asMembrane(),
+    agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system', toolResultGuard: true }],
+    modules: [new ReadModule()], syncIntervalMs: 0,
+    conversations: { templateAgent: 'assistant', bind: { channel: 'mention' } } });
+  const write = gate();
+  let spills = 0;
+  slowSpill(framework, () => { spills++; return write.opened; });
+  membrane.onSubmit = () => {
+    const stream = membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  try {
+    framework.pushEvent({ type: 'external-message', source: 'test', content: 'read', metadata: {} });
+    await framework.runUntilIdle().catch(() => {});
+    await until(() => spills === 1, "the template's aborted batch is being annotated");
+    const compiles = watchCompiles(framework);
+    const internals = framework as unknown as { createConversationAgent(name: string, channelId: string): Promise<{
+      getContextManager(): { getAllMessages(): Array<{ content: ContentBlock[] }> } }> };
+    const forking = internals.createConversationAgent('assistant-chan-g1', 'world:chan');
+    await until(() => compiles.calls > 0, "the fork's seed waits for the template's stub");
+    write.open();
+    const fork = await forking;
+    const seeded = fork.getContextManager().getAllMessages()
+      .flatMap((message) => message.content.filter((block) => block.type === 'tool_result'));
+    assert.deepEqual(seeded.map((block) => (block as { content: unknown }).content), [AUDIT_STUB]);
+  } finally { write.open(); await framework.stop(); }
+});
+
+test('#281 I7: a compile during which an annotation began is compiled again once it is done', async () => {
+  const r = await compressionRig();
+  try {
+    const write = gate();
+    let entered = false;
+    r.guard.setHost({ spill: async () => { entered = true; await write.opened; return null; }, track: () => {} });
+    r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
+    let reads = 0;
+    const stub = () => (r.cm.getMessage(r.messageId)!.content[0] as { content: unknown }).content;
+    const compiled = r.guard.afterAnnotations(async () => {
+      reads++;
+      // A settlement lands during the compile, as a previous frame's teardown can.
+      if (reads === 1) assert.ok(r.guard.withhold('test-category'));
+      return stub();
+    });
+    await until(() => entered, 'the annotation is writing');
+    write.open();
+    assert.equal(await compiled, AUDIT_STUB);
+    assert.equal(reads, 2, 'compiled again once the annotation was done');
+  } finally { r.cm.close(); }
+});
+
+test('#281 I13: a request preview never waits on a workspace write, though the next request does', async () => {
+  const h = await harness([[calls('one')], [answer()]], { toolResultGuard: true });
+  const write = gate();
+  let spills = 0;
+  slowSpill(h.framework, () => { spills++; return write.opened; });
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  try {
+    await h.run().catch(() => {});
+    await until(() => spills === 1, 'the aborted batch is being annotated');
+    // Rollback, undo and redo report a preview: it must not wait on the write.
+    const preview = await h.framework.previewActivation('assistant');
+    const previewed = preview.messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(previewed.map((b) => b.content), [TOOL_RESULT_GUARD_NOTICE], 'the preview shows the stub as it stands');
+    const compiles = watchCompiles(h.framework);
+    const running = h.run();
+    await until(() => compiles.calls > 0, 'the next request is being compiled');
+    assert.equal(h.membrane.requests.length, 1, 'the next request waits for the stub');
+    write.open();
+    await running;
+    const sent = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(sent.map((b) => b.content), [AUDIT_STUB]);
+  } finally { write.open(); await h.framework.stop(); }
+});
+
+test('#281 I23: an annotation that starts while modules stop writes no file, and is saved before the store closes', async () => {
+  const h = await workspaceHarness([]);
+  const agent = h.framework.getAgent('assistant')!;
+  const framework = h.framework as unknown as { writeToolResultFile: (...args: unknown[]) => Promise<unknown> };
+  const writeFile = framework.writeToolResultFile.bind(h.framework);
+  let writes = 0;
+  framework.writeToolResultFile = async (...args) => { writes++; return writeFile(...args); };
+  const stopModule = h.module.stop.bind(h.module);
+  h.module.stop = async () => {
+    // A settlement during shutdown, as a direct-API call that stop doesn't cancel can make.
+    agent.toolResultGuard.storeResults([{ type: 'tool_result', toolUseId: 'late', content: 'late-original' }],
+      [{ toolUseId: 'late', content: 'late-original' }], []);
+    agent.toolResultGuard.abandon('stopping');
+    await stopModule();
+  };
+  await h.framework.stop();
+  assert.equal(writes, 0, 'nothing is written to the stopping workspace');
+  const restarted = await AgentFramework.create({ storePath: h.storePath, membrane: new ScriptMembrane([]).asMembrane(),
+    agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system', toolResultGuard: true }], modules: [], syncIntervalMs: 0 });
+  try {
+    assert.deepEqual(toolResults(restarted).map((block) => block.content), [AUDIT_STUB]);
+    const audit = restarted.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    assert.deepEqual(audit.slice(-3).map((record) => record.type), ['withheld', 'annotated', 'stub_updated']);
+    assert.deepEqual(audit.at(-2)?.results, [{ toolUseId: 'late' }]);
+  } finally { await restarted.stop(); }
+});

From 48f8c71f1ca14a881b25641b6e37fe0526f51820 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Sun, 11 Oct 2026 14:32:41 -0400
Subject: [PATCH 06/16] fix(guard): the stub says "its result", as stored; a
 thrown or absent spill and a declined write are recorded as such (sw-af281)

Ada-1017's half of the house's haiku review of #281 (sw-af281), split with
Nell-1783 (room-203 #71715, #71722): the spill itself. Built on Nell's
47c1483b. Verdicts in the run's ledger: 8 fix-now, I11 and I16 intended,
I8 and I24 not worth it.

- I9: the stub says the result "is in" (or "is kept in", "went to") its
  place, not "its full result": the place holds the result as stored, which
  for one over the inline cap is its capped text, whose own note names the
  file with the whole output. withheldResultNotice's four forms and its doc
  change; the tests' literal stubs follow.
- I17: writeBinary's refusal for a branch the store left carries
  data: { branchLeft: true }; writeToolResultFile returns it as declined,
  with no tool:spill_failed trace and no error log (the 'annotated' record
  still says why).
- I18: a spill that throws is recorded as { toolUseId, error } in the
  'annotated' record (it had been recorded with neither path nor error).
- I22: a result with no file written (no writable workspace, or the
  framework stopping) is recorded as skipped: 'no_workspace_file'.
- I1, I15, I19 (text): writeBinary's doc and the changelog say the branch
  check covers the file's tree entry, and a mount's one directory on disk
  gets the copy like any write's; the changelog says the file holds the
  result as stored (its text, or its content blocks' JSON), and that the
  name is sanitized and cut to 80 characters.

Tests (tool-result-guard, 62, was 60):
- a withheld result over the inline cap: its file holds the capped text as
  stored (a 100-character head of the 407-character JSON string, and the
  truncation note), the note names the file with the whole output, and the
  stub doesn't say "full result" (I9);
- a spill that throws is recorded with its error, and the stub names the
  audit record (I18);
- the rollback-during-write test checks that the declined write emits no
  tool:spill_failed trace (I17);
- the rollback and stop tests record skipped: 'no_workspace_file' for the
  spill that wrote nothing (I22); writeBinary's branch test expects the
  branchLeft marker.

Mutations (~/.local/state/ada-1017/tmp/chk/281s/mutants-1.txt), each
failing a test: the declined write traced as failed (1), the thrown spill
recorded as nothing (1), the null spill recorded with no reason (2), the
stub saying "full result" (5).

Runs (Node 24.19.0): tool-result-guard 62/62, tool-result-spill 18/18,
silent-heartbeat-rows 12/12, conversation-routing 15/15.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../guard-withheld-names-original.fixed.md    | 21 +++--
 src/framework.ts                              |  5 ++
 src/modules/workspace/index.ts                | 11 ++-
 src/tool-result-guard.ts                      | 22 +++--
 test/silent-heartbeat-rows.test.ts            |  2 +-
 test/tool-result-guard.test.ts                | 83 ++++++++++++++-----
 6 files changed, 109 insertions(+), 35 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 56106f659..a884ec538 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -2,10 +2,16 @@
   guard's notice ("Tool result withheld by the guard. The tool has already
   executed.") is followed by the original's place: a workspace file under the
   first writable mount's `tool-results/` (named
-  `<date>-withheld-<batch>-<index>-<toolUseId>`, one per result), or, with no
-  writable workspace or a failed write, the guard's audit record
-  (`framework/tool-result-guard`), for an operator. A failed write's own error
-  stays in the audit record and the logs. When saving the audit record itself
+  `<date>-withheld-<batch>-<index>-<toolUseId>`, one per result, with any
+  character outside `A-Za-z0-9._-` replaced and the name cut to 80
+  characters, so a long tool use id is cut), or, with no writable workspace
+  or a failed write, the guard's audit record (`framework/tool-result-guard`),
+  for an operator. The place holds the result as stored: its text, or the
+  JSON of its content blocks when it has more than text, and for a result
+  over the inline cap, its capped text, whose own note names the file with
+  the whole output. A failed write's own error stays in the audit record and
+  the logs; the audit record also says when no file was written or a write
+  threw. When saving the audit record itself
   had failed as the result arrived, the stub says so rather than that the
   original is kept there. This holds for every withheld settlement: a refusal,
   an aborted stream, a batch that was never submitted, and one whose audit sync
@@ -33,6 +39,9 @@
   branch changes while the originals are being written, no more are written, a
   write already under way is refused where it commits, and the stub stays as
   it was, so no original lands on another branch. For this,
-  `WorkspaceModule.writeBinary` takes an optional `branch`: the file lands on
-  that branch or isn't written. The direct Agent API's refusal retry is now
+  `WorkspaceModule.writeBinary` takes an optional `branch`: the file's tree
+  entry lands on that branch or isn't written, and a refused write's result
+  carries `data: { branchLeft: true }` (it isn't traced as a failed spill). A
+  mount has one directory on disk, so with `autoMaterialize` the file's copy
+  there is written like any other write's. The direct Agent API's refusal retry is now
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
diff --git a/src/framework.ts b/src/framework.ts
index e4812b874..2f846adfb 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -11808,6 +11808,11 @@ export class AgentFramework {
         console.error(`[spill] ${path} is in the workspace's Chronicle tree, but its copy on disk failed: ${result.error}`);
         return { path };
       }
+      // Declined, not failed: the store left the branch the file is for, so
+      // it isn't written anywhere, as the caller asked (#281 I17).
+      if ((result.data as { branchLeft?: boolean } | undefined)?.branchLeft === true) {
+        return { path, error: result.error ?? 'the workspace had left the branch this file is for' };
+      }
       failure = result.error ?? 'write refused';
     } catch (err) {
       failure = err instanceof Error ? err.message : String(err);
diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index e8438a78f..e57d435ef 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1239,9 +1239,12 @@ export class WorkspaceModule implements Module {
    *
    * `branch`, when given, ties the write to that branch: the store's current
    * branch is checked where the tree entry is set, nothing yielding between
-   * the check and the entry, so the file lands on that branch or the write is
-   * refused. The tool-result guard writes a withheld original this way, for
-   * the branch its stub is on (agent-framework #277).
+   * the check and the entry, so the file's tree entry lands on that branch or
+   * the write is refused, with `data: { branchLeft: true }`. A mount has one
+   * directory on disk, so with autoMaterialize the file's copy there is
+   * written like any other write's (#281 I1). The tool-result guard writes a
+   * withheld original this way, for the branch its stub is on
+   * (agent-framework #277).
    *
    * A write whose tree entry is set but whose copy on disk fails returns
    * success false with `data: { inChronicle: true }`: the workspace's tools
@@ -1273,7 +1276,7 @@ export class WorkspaceModule implements Module {
     }
     const store = this.getStore();
     if (options.branch !== undefined && store.currentBranch().name !== options.branch) {
-      return { success: false, error: 'the workspace had left the branch this file is for', isError: true };
+      return { success: false, error: 'the workspace had left the branch this file is for', isError: true, data: { branchLeft: true } };
     }
     const blobHash = store.storeBlob(data, mimeType);
     store.treeSet(mount.treeStateId, relativePath, {
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 730297596..73ca0cb5d 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -35,7 +35,10 @@ export interface WithheldHost {
  * The stub a withheld result settles to: #159's neutral notice, then where
  * the original is. It names no refusal and no category (#159 keeps those in
  * operational logs), only the place, so reading it back is the agent's
- * deliberate choice (agent-framework #277). A failed write's own error text
+ * deliberate choice (agent-framework #277). The place holds the result as
+ * stored, which for one over the inline cap is its capped text, whose own
+ * note names the file with the whole output; so the stub says "its result",
+ * not its full result (#281 I9). A failed write's own error text
  * stays in the audit record and the logs, not here (#281 I20). The audit
  * record is said to keep the original only when it was saved: a staged
  * record whose save failed is still queued in memory, and a restart before
@@ -47,16 +50,16 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
     ? `is kept ${only}in ${audit}`
     : `went ${only}to ${audit}, though saving that record had failed when the result arrived`;
   if (spill?.unfinished) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Its full result was still being written to workspace file ${spill.path} ` +
+    return `${TOOL_RESULT_GUARD_NOTICE} Its result was still being written to workspace file ${spill.path} ` +
       `when this note was made; if that file is missing, it ${kept('')}.`;
   }
   if (spill && spill.error === undefined) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${spill.path}.`;
+    return `${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${spill.path}.`;
   }
   if (spill) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Writing its full result to workspace file ${spill.path} failed, so it ${kept('only ')}.`;
+    return `${TOOL_RESULT_GUARD_NOTICE} Writing its result to workspace file ${spill.path} failed, so it ${kept('only ')}.`;
   }
-  return `${TOOL_RESULT_GUARD_NOTICE} Its full result ${kept('')}.`;
+  return `${TOOL_RESULT_GUARD_NOTICE} Its result ${kept('')}.`;
 }
 
 interface PendingBatch {
@@ -429,6 +432,8 @@ export class ToolResultGuard {
         // waiting a deadline for each would hold every request and stop that
         // much longer (#281 I2). Their stubs name the audit record.
         const unanswered = new Set<number>();
+        // A spill that threw, by index: its error, for the record.
+        const thrown = new Map<number, string>();
         for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
           // Once the store has left the batch's branch (a rollback, an undo, a
@@ -449,6 +454,9 @@ export class ToolResultGuard {
             try {
               spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original, pending.branch);
             } catch (error) {
+              // The host reports a failed write rather than throwing; a throw
+              // is recorded all the same, without a path (#281 I18).
+              thrown.set(index, (error instanceof Error ? error.message : String(error)).slice(0, 200));
               console.error(`[tool-result-guard] agent=${this.agentName} could not spill withheld result ` +
                 `${block.toolUseId}:`, error);
             }
@@ -466,7 +474,11 @@ export class ToolResultGuard {
               if (block.type !== 'tool_result') return [];
               if (!spills.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'branch_changed' }];
               if (unanswered.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'workspace_unanswered' }];
+              if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
               const spill = spills.get(index);
+              // No file was written: no writable workspace, or the framework
+              // was stopping (#281 I22).
+              if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
               return [{ toolUseId: block.toolUseId, ...(spill ? { path: spill.path } : {}),
                 ...(spill?.error !== undefined ? { error: spill.error } : {}),
                 ...(spill?.unfinished ? { unfinished: true as const } : {}) }];
diff --git a/test/silent-heartbeat-rows.test.ts b/test/silent-heartbeat-rows.test.ts
index f84f9eecd..d0154d0b7 100644
--- a/test/silent-heartbeat-rows.test.ts
+++ b/test/silent-heartbeat-rows.test.ts
@@ -413,7 +413,7 @@ describe('silent heartbeat stored rows', () => {
       for (const row of tickRows) assert.equal(row.metadata?.silentHeartbeat?.eventId, tick.eventId);
       // Written out, not computed by the code under test (#281 I26).
       assert.equal((tickRows[1]!.content[0] as { content?: unknown }).content, 'Tool result withheld by the guard. ' +
-        "The tool has already executed. Its full result is kept in the guard's audit record (framework/tool-result-guard), " +
+        "The tool has already executed. Its result is kept in the guard's audit record (framework/tool-result-guard), " +
         'for an operator.');
       assert.doesNotMatch(JSON.stringify(tickRows), /discard-this-partial-output/);
 
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index e344f4d76..4564e447c 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -17,9 +17,9 @@ import { JsStore } from '@animalabs/chronicle';
 // What a withheld result settles to with no writable workspace (#277): the
 // neutral notice, then where the original is kept. Written out, not computed
 // by withheldResultNotice, so a change of its wording fails here (#281 I26).
-const AUDIT_STUB = 'Tool result withheld by the guard. The tool has already executed. Its full result is kept in ' +
+const AUDIT_STUB = 'Tool result withheld by the guard. The tool has already executed. Its result is kept in ' +
   "the guard's audit record (framework/tool-result-guard), for an operator.";
-const UNSAVED_STUB = 'Tool result withheld by the guard. The tool has already executed. Its full result went to ' +
+const UNSAVED_STUB = 'Tool result withheld by the guard. The tool has already executed. Its result went to ' +
   "the guard's audit record (framework/tool-result-guard), for an operator, though saving that record had failed " +
   'when the result arrived.';
 
@@ -1049,7 +1049,7 @@ function watchStopDrain(framework: AgentFramework) {
   return watched;
 }
 
-const SPILLED_STUB = /^Tool result withheld by the guard\. The tool has already executed\. Its full result is in workspace file (work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt)\.$/;
+const SPILLED_STUB = /^Tool result withheld by the guard\. The tool has already executed\. Its result is in workspace file (work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt)\.$/;
 
 test('#277: a withheld original is written to the workspace, and its stub names the file', async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
@@ -1075,13 +1075,53 @@ test('#277: a withheld original is written to the workspace, and its stub names
   } finally { await h.framework.stop(); }
 });
 
+test('#281 I9: a withheld result over the inline cap is written as stored, and its own note names the whole output', async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
+  (h.module.results as Record<string, ToolResult>).one = { success: true, data: `long-${'x'.repeat(400)}` };
+  (h.framework as unknown as { toolResultInlineMaxCharsConfig: number }).toolResultInlineMaxCharsConfig = 100;
+  try {
+    await h.run();
+    const stub = String(toolResults(h.framework)[0].content);
+    const path = SPILLED_STUB.exec(stub)?.[1];
+    assert.ok(path, `the stub names the withheld file: ${stub}`);
+    const withheld = await h.workspace.readBinary(path);
+    assert.ok('data' in withheld);
+    const text = (withheld as { data: Buffer }).data.toString('utf8');
+    // The data is a string, stored as its JSON: 407 characters with the quotes.
+    assert.match(text, /^"long-x{94}\n\n\[truncated — showing 100 of 407 chars; full content: workspace file /,
+      'the withheld file holds the capped text, as stored');
+    const whole = /full content: workspace file (work\/tool-results\/[^\s\]"]+\.txt)/.exec(text)?.[1];
+    assert.ok(whole && whole !== path, `its note names the file with the whole output: ${text}`);
+    const full = await h.workspace.readBinary(whole);
+    assert.ok('data' in full);
+    assert.match((full as { data: Buffer }).data.toString('utf8'), /^"long-x{400}"$/);
+    assert.doesNotMatch(stub, /full result/, 'the stub says "its result", which the file holds');
+  } finally { await h.framework.stop(); }
+});
+
+test('#281 I18: a spill that throws is recorded with its error, and the stub names the audit record', async () => {
+  const h = await harness([[calls('one'), refused()], [answer()]], { toolResultGuard: true });
+  (h.framework as unknown as { spillWithheld: () => Promise<never> }).spillWithheld = async () => {
+    throw new Error('the host broke its promise');
+  };
+  const originalError = console.error;
+  console.error = () => {};
+  try {
+    await h.run();
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const annotated = audit.find((record) => record.type === 'annotated') as { results: unknown[] } | undefined;
+    assert.deepEqual(annotated?.results, [{ toolUseId: 'one', error: 'the host broke its promise' }]);
+    assert.equal(String(toolResults(h.framework)[0].content), AUDIT_STUB);
+  } finally { console.error = originalError; await h.framework.stop(); }
+});
+
 test('#277: a failed workspace write says so, and the audit record still keeps the original', async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]], { maxFileSize: 4 });
   try {
     await h.run();
     const stub = String(toolResults(h.framework)[0].content);
     // The write's own error stays in the audit record and the logs (#281 I20).
-    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its full result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt failed, so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
+    assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt failed, so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     const annotated = audit.at(-2) as { type: string; results: Array<{ toolUseId: string; path?: string; error?: string }> };
     assert.equal(annotated.type, 'annotated');
@@ -1170,24 +1210,24 @@ test('#277: the stub has the same text for each place the original can be', () =
   const audit = "the guard's audit record (framework/tool-result-guard), for an operator";
   const unsaved = `${audit}, though saving that record had failed when the result arrived`;
   assert.equal(withheldResultNotice({ path: 'work/tool-results/2026-10-10-withheld-a.txt' }, true),
-    `${notice} Its full result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
+    `${notice} Its result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
   assert.equal(withheldResultNotice({ path: 'work/tool-results/2026-10-10-withheld-a.txt' }, false),
-    `${notice} Its full result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
+    `${notice} Its result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
   // A failed write's own error text isn't the model's to read (#281 I20).
   assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'EACCES: /srv/host/secret' }, true),
-    `${notice} Writing its full result to workspace file work/tool-results/x.txt failed, so it is kept only in ${audit}.`);
+    `${notice} Writing its result to workspace file work/tool-results/x.txt failed, so it is kept only in ${audit}.`);
   // The audit record is said to keep it only when that record was saved (#281 I21).
   assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'disk full' }, false),
-    `${notice} Writing its full result to workspace file work/tool-results/x.txt failed, so it went only to ${unsaved}.`);
+    `${notice} Writing its result to workspace file work/tool-results/x.txt failed, so it went only to ${unsaved}.`);
   // A write still under way when the host stopped waiting (#281 I2).
   assert.equal(withheldResultNotice({ path: 'work/tool-results/y.txt', unfinished: true }, true),
-    `${notice} Its full result was still being written to workspace file work/tool-results/y.txt when this note ` +
+    `${notice} Its result was still being written to workspace file work/tool-results/y.txt when this note ` +
     `was made; if that file is missing, it is kept in ${audit}.`);
   assert.equal(withheldResultNotice({ path: 'work/tool-results/y.txt', unfinished: true }, false),
-    `${notice} Its full result was still being written to workspace file work/tool-results/y.txt when this note ` +
+    `${notice} Its result was still being written to workspace file work/tool-results/y.txt when this note ` +
     `was made; if that file is missing, it went to ${unsaved}.`);
-  assert.equal(withheldResultNotice(null, true), `${notice} Its full result is kept in ${audit}.`);
-  assert.equal(withheldResultNotice(null, false), `${notice} Its full result went to ${unsaved}.`);
+  assert.equal(withheldResultNotice(null, true), `${notice} Its result is kept in ${audit}.`);
+  assert.equal(withheldResultNotice(null, false), `${notice} Its result went to ${unsaved}.`);
   assert.equal(withheldResultNotice(null, true), AUDIT_STUB);
   assert.equal(withheldResultNotice(null, false), UNSAVED_STUB);
 });
@@ -1340,7 +1380,8 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     const annotated = audit.find((record) => record.type === 'annotated');
     assert.ok(annotated, `the annotation is recorded on ${rolled.targetBranch}: ${JSON.stringify(audit)}`);
-    assert.deepEqual(annotated.results, [{ toolUseId: 'one' }, { toolUseId: 'two', skipped: 'branch_changed' }]);
+    // The first write went to the slowed spill, which wrote nothing (#281 I22).
+    assert.deepEqual(annotated.results, [{ toolUseId: 'one', skipped: 'no_workspace_file' }, { toolUseId: 'two', skipped: 'branch_changed' }]);
     assert.equal(audit.find((record) => record.type === 'stub_updated')?.historyUpdate, 'superseded');
     await cm.switchBranch(source);
     const kept = cm.getMessage(batch.id)!.content.filter((b) => b.type === 'tool_result');
@@ -1368,6 +1409,8 @@ test('#277: a write under way when a rollback lands is refused where it commits,
     const stream = h.membrane.streams.at(-1)!;
     queueMicrotask(() => stream.cancel());
   };
+  const traces: Array<{ type: string }> = [];
+  h.framework.onTrace((event) => traces.push(event as { type: string }));
   try {
     await h.run().catch(() => {});
     for (let i = 0; i < 100 && branches.length === 0; i++) await new Promise((resolve) => setTimeout(resolve, 10));
@@ -1389,6 +1432,7 @@ test('#277: a write under way when a rollback lands is refused where it commits,
     assert.equal(one.toolUseId, 'one');
     assert.equal(one.error, 'the workspace had left the branch this file is for');
     assert.deepEqual(two, { toolUseId: 'two', skipped: 'branch_changed' });
+    assert.ok(!traces.some((event) => event.type === 'tool:spill_failed'), 'a declined write is not traced as a failed spill (#281 I17)');
     const relative = one.path!.replace(/^work\//, '');
     const store = h.framework.getStore();
     assert.equal(store.treeGet('workspace/work/tree', relative), null, 'the branch rolled back to has no file');
@@ -1453,7 +1497,8 @@ test('#277: writeBinary for a branch writes there, and is refused once the works
     store.createBranchAt('elsewhere', source, before);
     store.switchBranch('elsewhere');
     const there = await workspace.writeBinary('work/tool-results/there.txt', Buffer.from('there'), 'text/plain', { branch: source });
-    assert.deepEqual(there, { success: false, error: 'the workspace had left the branch this file is for', isError: true });
+    assert.deepEqual(there, { success: false, error: 'the workspace had left the branch this file is for', isError: true,
+      data: { branchLeft: true } }, 'declined, and marked so, not a failed write (#281 I17)');
     assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nothing lands on the branch the workspace is on');
     store.switchBranch(source);
     assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nor on the branch the write named');
@@ -1482,7 +1527,7 @@ test('#281 I2: a write still under way at the deadline is named as unfinished, a
     assert.equal(writes, 1, "once the workspace stopped answering, the batch's next result isn't written");
     assert.equal(h.membrane.requests.length, 2, 'the retry went out without the write');
     const [one, two] = toolResults(h.framework).map((block) => String(block.content));
-    assert.match(one, /^Tool result withheld by the guard\. The tool has already executed\. Its full result was still being written to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt when this note was made; if that file is missing, it is kept in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
+    assert.match(one, /^Tool result withheld by the guard\. The tool has already executed\. Its result was still being written to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt when this note was made; if that file is missing, it is kept in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
     assert.equal(two, AUDIT_STUB);
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     const annotated = audit.find((record) => record.type === 'annotated') as { results: Array<Record<string, unknown>> };
@@ -1502,7 +1547,7 @@ test('#281 I3: a failed stub edit leaves the record of the written file, and the
   const edit = cm.editMessage.bind(cm);
   let failures = 0;
   cm.editMessage = (id, content) => {
-    if (failures === 0 && JSON.stringify(content).includes('Its full result is in workspace file')) {
+    if (failures === 0 && JSON.stringify(content).includes('Its result is in workspace file')) {
       failures++;
       throw new Error('injected stub edit failure');
     }
@@ -1514,12 +1559,12 @@ test('#281 I3: a failed stub edit leaves the record of the written file, and the
     assert.equal(failures, 1);
     const annotated = audit().find((record) => record.type === 'annotated') as { results: Array<{ path?: string }> };
     const path = annotated.results[0].path;
-    assert.ok(path && SPILLED_STUB.test(`${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${path}.`),
+    assert.ok(path && SPILLED_STUB.test(`${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${path}.`),
       `the record names the written file though the edit failed: ${JSON.stringify(annotated)}`);
     assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE, 'the stub is still the bare notice');
     assert.equal(audit().some((record) => record.type === 'stub_updated'), false, 'the edit is still queued');
     await h.run();
-    assert.equal(toolResults(h.framework)[0].content, `${TOOL_RESULT_GUARD_NOTICE} Its full result is in workspace file ${path}.`);
+    assert.equal(toolResults(h.framework)[0].content, `${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${path}.`);
     assert.equal(audit().at(-1)?.type, 'stub_updated');
     assert.equal(audit().at(-1)?.historyUpdate, undefined);
     assert.equal(h.framework.getAgent('assistant')!.getContextManager().getCompressionHolds().size, 0);
@@ -1648,6 +1693,6 @@ test('#281 I23: an annotation that starts while modules stop writes no file, and
     assert.deepEqual(toolResults(restarted).map((block) => block.content), [AUDIT_STUB]);
     const audit = restarted.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     assert.deepEqual(audit.slice(-3).map((record) => record.type), ['withheld', 'annotated', 'stub_updated']);
-    assert.deepEqual(audit.at(-2)?.results, [{ toolUseId: 'late' }]);
+    assert.deepEqual(audit.at(-2)?.results, [{ toolUseId: 'late', skipped: 'no_workspace_file' }]);
   } finally { await restarted.stop(); }
 });

From 353d66fa048d6ba7b2ed1f387ba3a793b2691db1 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Sun, 11 Oct 2026 15:26:02 -0400
Subject: [PATCH 07/16] chore(guard): the code and tests say what they do,
 without the house's review labels

#281's review round (47c1483, 48f8c71) cited its review sheet's issue labels
in comments and test titles ('(#281 I2)', '#281 I9:' and so on), which mean
nothing to anyone reading the merged code. They're removed; each comment and
title keeps what it says, and the titles keep '#281:', as the file's '#277:'
titles keep their issue (as Agnes-1009 asked of connectome-host #230,
room-507 #72170). Text only: tool-result-guard 62/62, silent-heartbeat-rows
12/12, tool-result-spill 18/18.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/agent.ts                       |  6 ++---
 src/framework.ts                   | 18 +++++++-------
 src/modules/workspace/index.ts     |  6 ++---
 src/tool-result-guard.ts           | 24 +++++++++----------
 test/silent-heartbeat-rows.test.ts |  2 +-
 test/tool-result-guard.test.ts     | 38 +++++++++++++++---------------
 6 files changed, 47 insertions(+), 47 deletions(-)

diff --git a/src/agent.ts b/src/agent.ts
index c7d5de6bf..0e6a190ec 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -677,7 +677,7 @@ export class Agent {
     // Compile the context (with optional injections) into a request. The
     // guard's refusal retry is assembled the same way, afresh. A withheld
     // stub is compiled only once it says where its original went, including
-    // one whose annotation began during the compile (#281 I7).
+    // one whose annotation began during the compile.
     const assemble = async (): Promise<NormalizedRequest> => {
       const { messages, systemInjections } = await this.toolResultGuard.afterAnnotations(
         () => this.compileWithInjections(budget, injections));
@@ -801,7 +801,7 @@ export class Agent {
    * It doesn't wait for the tool-result guard's annotations, so a preview
    * never waits on a workspace write (rollback, undo and redo report one), and
    * may show a withheld stub before its place is added; the activation waits
-   * for them around its call (#281 I13).
+   * for them around its call.
    */
   async buildActivationRequest(
     availableTools: ToolDefinition[],
@@ -971,7 +971,7 @@ export class Agent {
     this.lastStreamOutputTokens = 0;
 
     // A withheld stub is compiled only once it says where its original went,
-    // including one whose annotation began during the compile (#281 I7).
+    // including one whose annotation began during the compile.
     const request = await this.toolResultGuard.afterAnnotations(
       () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
     request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
diff --git a/src/framework.ts b/src/framework.ts
index 2f846adfb..c11fd0b67 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -771,7 +771,7 @@ class DefaultErrorPolicy implements ErrorPolicy {
 /** Default sync interval in milliseconds */
 const DEFAULT_SYNC_INTERVAL_MS = 1000;
 /** How long the tool-result guard waits for a withheld original's workspace
- *  write before its stub says the write was still under way (#281 I2). A local
+ *  write before its stub says the write was still under way. A local
  *  write takes milliseconds; this bounds a stalled mount, which would otherwise
  *  hold every later request of the agent and the framework's stop. */
 const WITHHELD_SPILL_DEADLINE_MS = 30_000;
@@ -2031,7 +2031,7 @@ export class AgentFramework {
     while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
     // An annotation that starts after this point, such as one from a direct
     // Agent API call stop doesn't cancel, writes no file to the stopping
-    // workspace: its stub names the audit record (#281 I23).
+    // workspace: its stub names the audit record.
     this.guardSpillsClosed = true;
 
     // Stop modules and MCPL servers in parallel
@@ -2042,7 +2042,7 @@ export class AgentFramework {
     await Promise.all(shutdownPromises);
 
     // Those later annotations write nothing, so they finish at once; let them
-    // record and edit their stubs before the store closes (#281 I23).
+    // record and edit their stubs before the store closes.
     while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
 
     // Streams may queue storage repairs while being cancelled above. Retry
@@ -2720,7 +2720,7 @@ export class AgentFramework {
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
   /** Set once stop() has let the running annotations finish: a withheld
    *  original is then no longer written to a workspace that is stopping, and
-   *  its stub names the audit record (#281 I23). */
+   *  its stub names the audit record. */
   private guardSpillsClosed = false;
 
   /** A new agent's guard: its persisted setting, the tool-results spill its
@@ -7418,7 +7418,7 @@ export class AgentFramework {
       if (existing.length === 0) {
         // The copy is the fork's own, and the template's annotation edits only
         // the template's message: seed only from stubs that already say where
-        // their originals went (#281 I6).
+        // their originals went.
         const { messages: compiled } = await template.toolResultGuard.afterAnnotations(
           () => template.getContextManager().compile());
         for (const msg of compiled) {
@@ -11762,8 +11762,8 @@ export class AgentFramework {
    * The guard's spill of a withheld original (agent-framework #277): the
    * tool-results file, waited for at most withheldSpillDeadlineMs. A write
    * still under way then is reported as unfinished at its path, and goes on
-   * by itself (#281 I2). Once stop() has let the running annotations finish,
-   * nothing more is written (#281 I23).
+   * by itself. Once stop() has let the running annotations finish,
+   * nothing more is written.
    */
   private async spillWithheld(label: string, text: string, branch: string): Promise<WithheldSpill> {
     if (this.guardSpillsClosed) return null;
@@ -11802,14 +11802,14 @@ export class AgentFramework {
       if (result.success) return { path };
       // The file is in the workspace's Chronicle tree, where its tools read
       // it, and only its copy on disk failed: it is written for every reader
-      // the stub or the truncation note sends there (#281 I4). The workspace
+      // the stub or the truncation note sends there. The workspace
       // reports the disk failure itself (workspace:materialize-failed).
       if ((result.data as { inChronicle?: boolean } | undefined)?.inChronicle === true) {
         console.error(`[spill] ${path} is in the workspace's Chronicle tree, but its copy on disk failed: ${result.error}`);
         return { path };
       }
       // Declined, not failed: the store left the branch the file is for, so
-      // it isn't written anywhere, as the caller asked (#281 I17).
+      // it isn't written anywhere, as the caller asked.
       if ((result.data as { branchLeft?: boolean } | undefined)?.branchLeft === true) {
         return { path, error: result.error ?? 'the workspace had left the branch this file is for' };
       }
diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index e57d435ef..1803b28c7 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1242,13 +1242,13 @@ export class WorkspaceModule implements Module {
    * the check and the entry, so the file's tree entry lands on that branch or
    * the write is refused, with `data: { branchLeft: true }`. A mount has one
    * directory on disk, so with autoMaterialize the file's copy there is
-   * written like any other write's (#281 I1). The tool-result guard writes a
+   * written like any other write's. The tool-result guard writes a
    * withheld original this way, for the branch its stub is on
    * (agent-framework #277).
    *
    * A write whose tree entry is set but whose copy on disk fails returns
    * success false with `data: { inChronicle: true }`: the workspace's tools
-   * read the file from the tree, so it is there for them (#281 I4).
+   * read the file from the tree, so it is there for them.
    */
   async writeBinary(
     mountPrefixedPath: string,
@@ -1289,7 +1289,7 @@ export class WorkspaceModule implements Module {
       // The file is in the Chronicle tree, where the workspace's tools read
       // it; only its copy on disk failed. `inChronicle` lets a caller that
       // needs the file readable tell this from a write that never happened
-      // (agent-framework #281 I4).
+      // (agent-framework #281).
       return {
         success: false,
         error: `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`,
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 73ca0cb5d..07642e07c 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -18,7 +18,7 @@ export type WithheldSpill = { path: string; error?: string; unfinished?: true }
  *  tool-results spill). It reports a failed write rather than throwing, and
  *  it settles within a bounded time: a write still under way at the host's
  *  deadline is reported as unfinished, so one stalled write can't hold every
- *  later request and the host's stop (#281 I2). The file lands on `branch`,
+ *  later request and the host's stop. The file lands on `branch`,
  *  the branch the stub is on, or isn't written: the workspace checks the
  *  branch where it commits the file (WorkspaceModule.writeBinary). */
 export type WithheldSpiller = (label: string, text: string, branch: string) => Promise<WithheldSpill>;
@@ -38,11 +38,11 @@ export interface WithheldHost {
  * deliberate choice (agent-framework #277). The place holds the result as
  * stored, which for one over the inline cap is its capped text, whose own
  * note names the file with the whole output; so the stub says "its result",
- * not its full result (#281 I9). A failed write's own error text
- * stays in the audit record and the logs, not here (#281 I20). The audit
+ * not its full result. A failed write's own error text
+ * stays in the audit record and the logs, not here. The audit
  * record is said to keep the original only when it was saved: a staged
  * record whose save failed is still queued in memory, and a restart before
- * its retry loses it (#281 I21).
+ * its retry loses it.
  */
 export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean): string {
   const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
@@ -116,18 +116,18 @@ export class ToolResultGuard {
   /** Settles once every withheld stub settled so far names where its
    *  original is (or that edit was given up). It never rejects, and it is
    *  bounded: the host reports a write still under way at its deadline as
-   *  unfinished (#281 I2). */
+   *  unfinished. */
   whenAnnotated(): Promise<void> { return this.annotating ?? Promise.resolve(); }
 
   /**
    * Runs `read` (a compile of the context) once no withheld stub is still
    * being annotated, and again if an annotation began while it ran, since a
    * settlement can land during the compile's own awaits, such as a previous
-   * frame's teardown abandoning its batch (#281 I7). Every compile of a
+   * frame's teardown abandoning its batch. Every compile of a
    * request that is sent goes through it: the agent's activations, its direct
    * API calls and their refusal retry, and a conversation fork's seed from its
-   * template (#281 I6). A request preview doesn't, so it never waits on a
-   * workspace write (#281 I13).
+   * template. A request preview doesn't, so it never waits on a
+   * workspace write.
    */
   async afterAnnotations<T>(read: () => Promise<T>): Promise<T> {
     for (;;) {
@@ -410,7 +410,7 @@ export class ToolResultGuard {
    * The edit then goes through the ordered storage queue like an admission's:
    * retried before the next activation, maintenance pass or stop until it
    * lands or an operator's change supersedes it ('stub_updated'), so a failed
-   * edit no longer leaves a written file named nowhere (#281 I3).
+   * edit no longer leaves a written file named nowhere.
    */
   private annotate(pending: PendingBatch): void {
     const previous = this.annotating ?? Promise.resolve();
@@ -430,7 +430,7 @@ export class ToolResultGuard {
         // Results not written because an earlier write of the batch was still
         // under way at the host's deadline: the workspace isn't answering, and
         // waiting a deadline for each would hold every request and stop that
-        // much longer (#281 I2). Their stubs name the audit record.
+        // much longer. Their stubs name the audit record.
         const unanswered = new Set<number>();
         // A spill that threw, by index: its error, for the record.
         const thrown = new Map<number, string>();
@@ -455,7 +455,7 @@ export class ToolResultGuard {
               spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original, pending.branch);
             } catch (error) {
               // The host reports a failed write rather than throwing; a throw
-              // is recorded all the same, without a path (#281 I18).
+              // is recorded all the same, without a path.
               thrown.set(index, (error instanceof Error ? error.message : String(error)).slice(0, 200));
               console.error(`[tool-result-guard] agent=${this.agentName} could not spill withheld result ` +
                 `${block.toolUseId}:`, error);
@@ -477,7 +477,7 @@ export class ToolResultGuard {
               if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
               const spill = spills.get(index);
               // No file was written: no writable workspace, or the framework
-              // was stopping (#281 I22).
+              // was stopping.
               if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
               return [{ toolUseId: block.toolUseId, ...(spill ? { path: spill.path } : {}),
                 ...(spill?.error !== undefined ? { error: spill.error } : {}),
diff --git a/test/silent-heartbeat-rows.test.ts b/test/silent-heartbeat-rows.test.ts
index d0154d0b7..af98145e9 100644
--- a/test/silent-heartbeat-rows.test.ts
+++ b/test/silent-heartbeat-rows.test.ts
@@ -411,7 +411,7 @@ describe('silent heartbeat stored rows', () => {
       const tickRows = stored(x.framework).slice(before);
       assert.deepEqual(tickRows.map((m) => m.participant), ['assistant', 'user', 'assistant']);
       for (const row of tickRows) assert.equal(row.metadata?.silentHeartbeat?.eventId, tick.eventId);
-      // Written out, not computed by the code under test (#281 I26).
+      // Written out, not computed by the code under test.
       assert.equal((tickRows[1]!.content[0] as { content?: unknown }).content, 'Tool result withheld by the guard. ' +
         "The tool has already executed. Its result is kept in the guard's audit record (framework/tool-result-guard), " +
         'for an operator.');
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 4564e447c..795e9277f 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -16,7 +16,7 @@ import { JsStore } from '@animalabs/chronicle';
 
 // What a withheld result settles to with no writable workspace (#277): the
 // neutral notice, then where the original is kept. Written out, not computed
-// by withheldResultNotice, so a change of its wording fails here (#281 I26).
+// by withheldResultNotice, so a change of its wording fails here.
 const AUDIT_STUB = 'Tool result withheld by the guard. The tool has already executed. Its result is kept in ' +
   "the guard's audit record (framework/tool-result-guard), for an operator.";
 const UNSAVED_STUB = 'Tool result withheld by the guard. The tool has already executed. Its result went to ' +
@@ -1020,7 +1020,7 @@ function slowSpill(framework: AgentFramework, wait: () => Promise<unknown>) {
 }
 
 /** A gate a test opens itself, and a wait for a condition the code under test
- *  makes true (#281 I5: no fixed timers standing in for events). */
+ *  makes true (no fixed timers standing in for events). */
 function gate() {
   let open!: () => void;
   const opened = new Promise<void>((resolve) => { open = resolve; });
@@ -1075,7 +1075,7 @@ test('#277: a withheld original is written to the workspace, and its stub names
   } finally { await h.framework.stop(); }
 });
 
-test('#281 I9: a withheld result over the inline cap is written as stored, and its own note names the whole output', async () => {
+test('#281: a withheld result over the inline cap is written as stored, and its own note names the whole output', async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
   (h.module.results as Record<string, ToolResult>).one = { success: true, data: `long-${'x'.repeat(400)}` };
   (h.framework as unknown as { toolResultInlineMaxCharsConfig: number }).toolResultInlineMaxCharsConfig = 100;
@@ -1099,7 +1099,7 @@ test('#281 I9: a withheld result over the inline cap is written as stored, and i
   } finally { await h.framework.stop(); }
 });
 
-test('#281 I18: a spill that throws is recorded with its error, and the stub names the audit record', async () => {
+test('#281: a spill that throws is recorded with its error, and the stub names the audit record', async () => {
   const h = await harness([[calls('one'), refused()], [answer()]], { toolResultGuard: true });
   (h.framework as unknown as { spillWithheld: () => Promise<never> }).spillWithheld = async () => {
     throw new Error('the host broke its promise');
@@ -1120,7 +1120,7 @@ test('#277: a failed workspace write says so, and the audit record still keeps t
   try {
     await h.run();
     const stub = String(toolResults(h.framework)[0].content);
-    // The write's own error stays in the audit record and the logs (#281 I20).
+    // The write's own error stays in the audit record and the logs.
     assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Writing its result to workspace file work\/tool-results\/\d{4}-\d{2}-\d{2}-withheld-[0-9a-f]{12}-0-one\.txt failed, so it is kept only in the guard's audit record \(framework\/tool-result-guard\), for an operator\.$/);
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     const annotated = audit.at(-2) as { type: string; results: Array<{ toolUseId: string; path?: string; error?: string }> };
@@ -1133,7 +1133,7 @@ test('#277: a failed workspace write says so, and the audit record still keeps t
 
 test('#277: the refusal retry is compiled only once the stub says where the original is', async () => {
   // The framework's retry is a new activation (startStreamWithInjections), so
-  // this also pins that path's wait (#281 I12).
+  // this also pins that path's wait.
   const h = await harness([[calls('one'), refused()], [answer()]], { toolResultGuard: true });
   const write = gate();
   let spills = 0;
@@ -1213,13 +1213,13 @@ test('#277: the stub has the same text for each place the original can be', () =
     `${notice} Its result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
   assert.equal(withheldResultNotice({ path: 'work/tool-results/2026-10-10-withheld-a.txt' }, false),
     `${notice} Its result is in workspace file work/tool-results/2026-10-10-withheld-a.txt.`);
-  // A failed write's own error text isn't the model's to read (#281 I20).
+  // A failed write's own error text isn't the model's to read.
   assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'EACCES: /srv/host/secret' }, true),
     `${notice} Writing its result to workspace file work/tool-results/x.txt failed, so it is kept only in ${audit}.`);
-  // The audit record is said to keep it only when that record was saved (#281 I21).
+  // The audit record is said to keep it only when that record was saved.
   assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'disk full' }, false),
     `${notice} Writing its result to workspace file work/tool-results/x.txt failed, so it went only to ${unsaved}.`);
-  // A write still under way when the host stopped waiting (#281 I2).
+  // A write still under way when the host stopped waiting.
   assert.equal(withheldResultNotice({ path: 'work/tool-results/y.txt', unfinished: true }, true),
     `${notice} Its result was still being written to workspace file work/tool-results/y.txt when this note ` +
     `was made; if that file is missing, it is kept in ${audit}.`);
@@ -1380,7 +1380,7 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
     const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     const annotated = audit.find((record) => record.type === 'annotated');
     assert.ok(annotated, `the annotation is recorded on ${rolled.targetBranch}: ${JSON.stringify(audit)}`);
-    // The first write went to the slowed spill, which wrote nothing (#281 I22).
+    // The first write went to the slowed spill, which wrote nothing.
     assert.deepEqual(annotated.results, [{ toolUseId: 'one', skipped: 'no_workspace_file' }, { toolUseId: 'two', skipped: 'branch_changed' }]);
     assert.equal(audit.find((record) => record.type === 'stub_updated')?.historyUpdate, 'superseded');
     await cm.switchBranch(source);
@@ -1432,7 +1432,7 @@ test('#277: a write under way when a rollback lands is refused where it commits,
     assert.equal(one.toolUseId, 'one');
     assert.equal(one.error, 'the workspace had left the branch this file is for');
     assert.deepEqual(two, { toolUseId: 'two', skipped: 'branch_changed' });
-    assert.ok(!traces.some((event) => event.type === 'tool:spill_failed'), 'a declined write is not traced as a failed spill (#281 I17)');
+    assert.ok(!traces.some((event) => event.type === 'tool:spill_failed'), 'a declined write is not traced as a failed spill');
     const relative = one.path!.replace(/^work\//, '');
     const store = h.framework.getStore();
     assert.equal(store.treeGet('workspace/work/tree', relative), null, 'the branch rolled back to has no file');
@@ -1498,7 +1498,7 @@ test('#277: writeBinary for a branch writes there, and is refused once the works
     store.switchBranch('elsewhere');
     const there = await workspace.writeBinary('work/tool-results/there.txt', Buffer.from('there'), 'text/plain', { branch: source });
     assert.deepEqual(there, { success: false, error: 'the workspace had left the branch this file is for', isError: true,
-      data: { branchLeft: true } }, 'declined, and marked so, not a failed write (#281 I17)');
+      data: { branchLeft: true } }, 'declined, and marked so, not a failed write');
     assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nothing lands on the branch the workspace is on');
     store.switchBranch(source);
     assert.equal(store.treeGet(tree, 'tool-results/there.txt'), null, 'nor on the branch the write named');
@@ -1511,7 +1511,7 @@ test('#277: writeBinary for a branch writes there, and is refused once the works
 // what is so.
 // ---------------------------------------------------------------------------
 
-test('#281 I2: a write still under way at the deadline is named as unfinished, and nothing waits on it longer', async () => {
+test('#281: a write still under way at the deadline is named as unfinished, and nothing waits on it longer', async () => {
   const h = await workspaceHarness([[calls('one', 'two'), refused()], [answer()]]);
   (h.framework as unknown as { withheldSpillDeadlineMs: number }).withheldSpillDeadlineMs = 50;
   const stalled = gate();
@@ -1539,7 +1539,7 @@ test('#281 I2: a write still under way at the deadline is named as unfinished, a
   } finally { stalled.open(); if (!stopped) await h.framework.stop(); }
 });
 
-test('#281 I3: a failed stub edit leaves the record of the written file, and the edit is retried before the next activation', async () => {
+test('#281: a failed stub edit leaves the record of the written file, and the edit is retried before the next activation', async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()], [answer()]]);
   const cm = h.framework.getAgent('assistant')!.getContextManager() as unknown as {
     editMessage: (id: unknown, content: ContentBlock[]) => unknown;
@@ -1571,7 +1571,7 @@ test('#281 I3: a failed stub edit leaves the record of the written file, and the
   } finally { await h.framework.stop(); }
 });
 
-test("#281 I4: a file whose copy on disk fails is still in the workspace's tree, and the stub names it", async () => {
+test("#281: a file whose copy on disk fails is still in the workspace's tree, and the stub names it", async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]], { autoMaterialize: true });
   // A file where the directory should be: the copy on disk fails for anyone, root included.
   writeFileSync(join(h.mountDir, 'tool-results'), 'not a directory');
@@ -1590,7 +1590,7 @@ test("#281 I4: a file whose copy on disk fails is still in the workspace's tree,
   } finally { await h.framework.stop(); }
 });
 
-test("#281 I6: a conversation fork seeded while its template's stub is written copies the stub that names the original", async () => {
+test("#281: a conversation fork seeded while its template's stub is written copies the stub that names the original", async () => {
   const dir = mkdtempSync(join(tmpdir(), 'af-guard-fork-')); dirs.push(dir);
   const membrane = new ScriptMembrane([[calls('one')]]);
   const framework = await AgentFramework.create({ storePath: join(dir, 'store'), membrane: membrane.asMembrane(),
@@ -1621,7 +1621,7 @@ test("#281 I6: a conversation fork seeded while its template's stub is written c
   } finally { write.open(); await framework.stop(); }
 });
 
-test('#281 I7: a compile during which an annotation began is compiled again once it is done', async () => {
+test('#281: a compile during which an annotation began is compiled again once it is done', async () => {
   const r = await compressionRig();
   try {
     const write = gate();
@@ -1643,7 +1643,7 @@ test('#281 I7: a compile during which an annotation began is compiled again once
   } finally { r.cm.close(); }
 });
 
-test('#281 I13: a request preview never waits on a workspace write, though the next request does', async () => {
+test('#281: a request preview never waits on a workspace write, though the next request does', async () => {
   const h = await harness([[calls('one')], [answer()]], { toolResultGuard: true });
   const write = gate();
   let spills = 0;
@@ -1670,7 +1670,7 @@ test('#281 I13: a request preview never waits on a workspace write, though the n
   } finally { write.open(); await h.framework.stop(); }
 });
 
-test('#281 I23: an annotation that starts while modules stop writes no file, and is saved before the store closes', async () => {
+test('#281: an annotation that starts while modules stop writes no file, and is saved before the store closes', async () => {
   const h = await workspaceHarness([]);
   const agent = h.framework.getAgent('assistant')!;
   const framework = h.framework as unknown as { writeToolResultFile: (...args: unknown[]) => Promise<unknown> };

From ee7338da2b8a779597e2e89a53abebebe68bfb62 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Mon, 12 Oct 2026 02:55:54 -0400
Subject: [PATCH 08/16] fix(guard): a withheld batch stays held until its stub
 lands; compiles wait for every annotation; a stalled mount costs one deadline

Holds and retries:
- The stub's edit carries the batch's compression hold (heldMessageId), as
  an admission's edit does: the annotation releases the hold itself only
  when it ends before queuing the edit. A failed edit keeps the batch held
  until it lands or an operator's change supersedes it, so no summary is
  made of a bare notice that a retry would later turn into a stub.
- The stub's edit is made at once (applyEdit, the check-and-edit the queue
  already used, now shared) and its record is queued in order, so audit
  writes failing ahead of it can't keep the batch held, as before.
- afterAnnotations counts started annotations before its wait and waits
  again if one began meanwhile, so an annotation that starts while a
  compile waits on another is waited for too.
- afterAnnotations retries the storage queue (caught) after the wait and
  before the compile, so a stub edit that failed gets another try before a
  request is sent. A store still failing then sends the bare notice, held.
- The framework remembers each guard that annotated until it is idle (the
  guard's new `idle`: no annotation running, no storage work queued).
  Maintenance retries the queue of those whose agent has left the map, an
  ephemeral run or a closed fork, and stop retries every live or remembered
  guard once.

Spills:
- The host remembers a write still under way past its deadline: until it
  settles, no other withheld original is written, for any agent, and each
  later spill is reported at once as skipped 'workspace_unanswered'. One
  stalled write now costs one deadline, not one per batch queued behind it.
  The guard's per-batch skip goes, since the host's covers it.
- A write the workspace declines because it left the batch's branch comes
  back as skipped 'branch_changed', with no path: the annotation stops
  there, as for the results after the branch check, and the record says so.
- The 'annotated' and 'stub_updated' records carry sourceBranch.

Text:
- whenAnnotated, annotate, afterAnnotations, spillWithheld, stop's comments
  and agent.ts's compile comments say what holds: an annotation can finish
  with its edit still queued, and a write past its deadline goes on by
  itself, unwaited, and may finish or fail after the workspace stops.
- docs/tool-result-guard.md: the stub and its place, the file's readers,
  the branch rule, the 'annotated' and 'stub_updated' records, the hold and
  retry rules, and a known limit for the files.
- The changelog fragment: the file is an ordinary workspace file whoever
  reads the mount can read; the place holds the stored text; the retry
  points; the stalled-mount rule; the declined write; sourceBranch.

Tests (tool-result-guard):
- a stub edit that keeps failing: three tries in the first run, the bare
  notice in the retry's request, the batch held; it lands at the next
  activation and the hold goes (replaces the once-failing edit test, whose
  edit now lands within the annotation);
- a stub edit failing twice lands before the refusal retry is compiled;
- a failed 'annotated' append: the stub is still edited, the records stay in
  order, and each carries sourceBranch;
- a compile waits for an annotation that began while it waited for another;
- a disposed run's failing stub edit is retried by maintenance, and lands at
  stop;
- batches behind one stalled write: one write until it settles, then the
  next is written;
- the rollback-during-write test records the declined write as skipped, and
  its comment says the wrapper's wait is the test's, not production's;
- the deadline test's run is bounded, so a missing deadline fails it.
---
 .../guard-withheld-names-original.fixed.md    |  48 ++--
 docs/tool-result-guard.md                     | 108 +++++++-
 src/agent.ts                                  |  17 +-
 src/framework.ts                              |  90 +++++--
 src/tool-result-guard.ts                      | 195 ++++++++------
 test/tool-result-guard.test.ts                | 237 ++++++++++++++++--
 6 files changed, 550 insertions(+), 145 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index a884ec538..32e8b5a74 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -6,42 +6,54 @@
   character outside `A-Za-z0-9._-` replaced and the name cut to 80
   characters, so a long tool use id is cut), or, with no writable workspace
   or a failed write, the guard's audit record (`framework/tool-result-guard`),
-  for an operator. The place holds the result as stored: its text, or the
-  JSON of its content blocks when it has more than text, and for a result
-  over the inline cap, its capped text, whose own note names the file with
-  the whole output. A failed write's own error stays in the audit record and
-  the logs; the audit record also says when no file was written or a write
-  threw. When saving the audit record itself
+  for an operator. The place holds the result as stored, which is its text:
+  for a result over the inline cap, its capped text, whose own note names the
+  file with the whole output. A failed write's own error stays in the audit
+  record and the logs; the audit record also says when no file was written or
+  a write threw. When saving the audit record itself
   had failed as the result arrived, the stub says so rather than that the
   original is kept there. This holds for every withheld settlement: a refusal,
   an aborted stream, a batch that was never submitted, and one whose audit sync
   failed. The notice still names no refusal and no category. Before this, a
   withheld result left only the notice, so the agent couldn't tell what the
-  tool had done (agent-framework #277).
+  tool had done (agent-framework #277). The file is an ordinary workspace
+  file: the agent can read it back deliberately, and so can whoever else reads
+  the mount, such as another agent sharing it or a synced copy.
 - How the stub is written. Where each original went is recorded first, and the
-  stub's edit is retried before the next activation, maintenance pass or stop
-  if it fails, so no written file goes unnamed. A file whose copy on disk fails
+  stub's edit is then made at once. If it fails, it is retried before the next
+  activation, compile of a request that is sent, maintenance pass or stop,
+  including for an ephemeral run or a closed fork that has left the agent map,
+  and the batch stays held out of summaries until it lands. Until then, or if
+  the store keeps failing or the process stops first, the stub is the bare
+  notice and the audit record names the file. A file whose copy on disk fails
   is still in the workspace's tree, where its tools read it, so the stub names
   it; for this, `WorkspaceModule.writeBinary`'s result for that case carries
   `data: { inChronicle: true }`. A write still under way after 30 seconds, as
   on a stalled mount, is named as unfinished, with the audit record as the
-  fallback, and the batch's remaining originals then go only to the audit
-  record, so a stalled workspace can't hold the agent's requests or the
-  framework's stop. Every request that is sent is compiled only once its stubs
-  say where their originals went, including the refusal retry and a stub whose
-  annotation began during the compile, and a conversation fork seeded from its
-  template copies only such stubs. A request preview doesn't wait, so rollback,
+  fallback. Nothing waits for it after that, stop included: it goes on by
+  itself, and may finish or fail after the workspace has stopped. Until it
+  settles, no other withheld original is written, for this batch or a later
+  one of any agent: their stubs name the audit record, so a stalled workspace
+  costs one 30-second wait however many batches queue behind it, and can't
+  hold the agent's requests or the framework's stop. Every request that is
+  sent is compiled only once each annotation started so far has finished,
+  including one that began while the compile waited or ran, and the refusal
+  retry; a conversation fork seeded from its template copies only stubs whose
+  annotation has finished. A request preview doesn't wait, so rollback,
   undo and redo never wait on a workspace write, and a preview can show a stub
   before its place is added. Stop lets running annotations finish while the
   workspace is up; one that starts after that writes no file and is saved
   before the store closes. A crash before a stub is written leaves the notice
   alone, and the staged audit record still holds the original. If the active
   branch changes while the originals are being written, no more are written, a
-  write already under way is refused where it commits, and the stub stays as
-  it was, so no original lands on another branch. For this,
+  write already under way is refused where it commits and recorded as skipped
+  for the branch change, and the stub stays as it was, so no original lands on
+  another branch. For this,
   `WorkspaceModule.writeBinary` takes an optional `branch`: the file's tree
   entry lands on that branch or isn't written, and a refused write's result
   carries `data: { branchLeft: true }` (it isn't traced as a failed spill). A
   mount has one directory on disk, so with `autoMaterialize` the file's copy
-  there is written like any other write's. The direct Agent API's refusal retry is now
+  there is written like any other write's. The audit records `annotated`
+  (where each original went) and `stub_updated` (the stub's edit) carry the
+  batch's `sourceBranch`. The direct Agent API's refusal retry is now
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
diff --git a/docs/tool-result-guard.md b/docs/tool-result-guard.md
index efd50b5ad..3ab58b2d0 100644
--- a/docs/tool-result-guard.md
+++ b/docs/tool-result-guard.md
@@ -24,10 +24,14 @@ structured provider `stopReason: 'refusal'`, not keywords in output, ordinary
 provider errors, or natural-language refusal text.
 
 On that signal, every result in the batch is withheld. Tool calls, result IDs,
-and error flags remain intact; each entire payload becomes:
+and error flags remain intact; each entire payload becomes the guard's notice,
 
 > Tool result withheld by the guard. The tool has already executed.
 
+followed by where the original is (see "Where a withheld original goes"
+below). The same holds for every withheld settlement: a refusal, an aborted
+stream, a batch that was never submitted, and one whose audit sync failed.
+
 The refused attempt's partial assistant output is discarded. Inference is
 retried once on the same model, within the same logical turn; executed tools
 are never automatically run again. Refusal details stay in operational logs,
@@ -86,11 +90,14 @@ placeholder is not summarized while awaiting a decision: it is staged with a
 context-manager compression hold (`addMessage(..., { holdCompression: true })`,
 context-manager >= 0.12), placed before the strategy's ingress callback runs.
 Every settlement path (accept, withhold, turn-ended, unsubmitted, aborted)
-edits in the final content first and then releases the hold. Audit-only
-failures cannot keep a settled message held. If an acceptance edit fails,
-the guard keeps the accepted payload and its hold in a separate retry queue;
-it does not re-arm provider submission or refusal handling. Compression sees
-only the settled message: accepted output, or the notice for a withheld batch.
+edits in the final content first and then releases the hold: an accepted
+batch's payload, or a withheld batch's stub, which is edited once its
+originals have been written, so a withheld batch stays held meanwhile.
+Audit-only failures cannot keep a settled message held. If an acceptance
+edit or a stub's edit fails, the guard keeps the content and its hold in a
+separate retry queue; it does not re-arm provider submission or refusal
+handling. Compression sees only the settled message: accepted output, or a
+withheld batch's stub.
 Holds are in-memory; a reopened process has no pending batch and therefore
 no holds. Raw
 pending output goes directly to the provider. A clean following response
@@ -106,18 +113,21 @@ the provider receives placeholders instead of the originals, and the batch settl
 provider.
 
 Failed edits and audit writes are retried in order before the next real
-activation or guard audit write, during maintenance, and after stream teardown
-at shutdown. Preview/compile calls do not flush the queue. A history edit is
-retried only on its original branch and only if the message still contains the
-guard's placeholder or the accepted payload; later operator edits, removals,
-and branch changes take precedence. Such an acceptance is audited with
+activation, compile of a request that is sent, or guard audit write, during
+maintenance, and after stream teardown at shutdown, including those of an
+ephemeral run or a closed conversation fork that has left the agent map.
+Previews do not flush the queue. A history edit is retried only on its
+original branch and only if the message still contains the guard's
+placeholder or the content the edit writes; later operator edits, removals,
+and branch changes take precedence. Such an edit is audited with
 `historyUpdate: "superseded"` and its `sourceBranch` rather than overwriting
 the operator's view. Originals in the audit are never edited or removed.
 
 Storage retries are in-memory. If the process dies before storage recovers,
 unsynced records or unfinished edits cannot be promised to survive. Originals
 already made durable remain in Chronicle; reopened context conservatively
-retains any withholding notice whose acceptance edit did not persist.
+retains any withholding notice whose acceptance edit or stub edit did not
+persist, and an `annotated` record that was saved still names a written file.
 
 A stream that ends without a clean round and without a successor (abort,
 exhausted error retries; also an aborted direct `Agent.runInference`)
@@ -130,6 +140,77 @@ deliberately conservative: an interrupted submission does not establish that
 the output was accepted. Similarly, if context compilation omits a pending
 exchange, its unsubmitted payload is not admitted to memory.
 
+## Where a withheld original goes
+
+Each withheld result's original is written, as the result was stored (its
+text; for a result over the inline cap, its capped text, whose own note names
+the file with the whole output), to a file under the first writable mount's
+`tool-results/` directory, named
+`<date>-withheld-<batch>-<index>-<toolUseId>.txt` with any character outside
+`A-Za-z0-9._-` replaced and the name cut to 80 characters. Its stub names it:
+
+> Tool result withheld by the guard. The tool has already executed. Its result
+> is in workspace file work/tool-results/2026-10-10-withheld-1a2b3c4d5e6f-0-toolu_01.txt.
+
+Otherwise the stub names the guard's audit record, for an operator:
+
+- with no writable workspace, or once the framework is stopping: "Its result is
+  kept in the guard's audit record (framework/tool-result-guard), for an
+  operator.";
+- when the write failed: "Writing its result to workspace file … failed, so it
+  is kept only in the guard's audit record …". The error itself stays in the
+  audit record and the logs;
+- when the write was still under way after 30 seconds, as on a stalled mount:
+  "Its result was still being written to workspace file … when this note was
+  made; if that file is missing, it is kept in the guard's audit record …".
+  Nothing waits for that write after that, stop included: it goes on by itself
+  and may finish or fail after the workspace has stopped. Until it settles, no
+  other withheld original is written, for any agent; their stubs name the audit
+  record, so a stalled mount costs one 30-second wait however many batches
+  queue behind it.
+
+When saving the staged audit record itself had failed as the result arrived,
+the stub says the result went to the audit record "though saving that record
+had failed when the result arrived", rather than that it is kept there.
+
+The file is an ordinary workspace file. The agent can read it back
+deliberately, and so can whoever else reads the mount: another agent sharing
+it, a process, or a synced copy. Withholding keeps the original out of the
+agent's context, not out of its workspace.
+
+If the active branch changes while the originals are being written (a
+rollback, an undo, a host's switch), no more are written, and the stub stays as
+it was. A write already under way names the batch's branch, and the workspace
+refuses it where it commits the file (`WorkspaceModule.writeBinary`'s `branch`
+option, whose refusal carries `data: { branchLeft: true }`), so no original
+lands on another branch. With `autoMaterialize`, a mount has one directory on
+disk, and a written file's copy there is written like any other write's.
+
+Two audit records describe it, each with `batchId`, `messageId` and
+`sourceBranch`:
+
+- `annotated`, written first, on its own: one entry in `results` per result.
+  `{ toolUseId, path }` is a written file; with `error`, a failed write; with
+  `unfinished: true`, a write still under way at the deadline. `{ toolUseId,
+  error }` is a write that threw. `{ toolUseId, skipped }` is no write:
+  `no_workspace_file` (no writable workspace, or the framework was stopping),
+  `workspace_unanswered` (an earlier write was still under way past its
+  deadline) or `branch_changed` (the branch changed before or while it was
+  written).
+- `stub_updated`: the stub's edit, with `historyUpdate: "superseded"` when an
+  operator's edit, removal, rollback or branch change came first.
+
+The stub's edit is made at once. If it fails, it waits in the retry queue
+above, and the batch stays held until it lands, so no summary is made of a
+stub that doesn't yet say where its original went; meanwhile the agent's
+requests carry the bare notice, and the `annotated` record names the file.
+Every request that is sent is compiled once each annotation started so far
+has finished, including the refusal retry and the seed of a conversation fork
+from its template. A request preview (rollback, undo, redo) doesn't wait, and
+can show a stub before its place is added. At stop, the framework lets
+running annotations finish while the workspace is up; one that starts after
+that writes no file and is saved before the store closes.
+
 For example, an operator can inspect records without changing the agent's
 view:
 
@@ -160,3 +241,6 @@ retroactive and does not rewrite results already accepted into memory.
 - **Held stream text on abort.** Text held while a submitted batch is
   pending is dropped (not previewed) if the stream aborts or errors before
   the round settles.
+- **Withheld originals in the workspace.** Every reader of the mount can read
+  a withheld original's file, and nothing removes it; delete it as any
+  workspace file.
diff --git a/src/agent.ts b/src/agent.ts
index 0e6a190ec..20985052f 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -675,9 +675,11 @@ export class Agent {
       ? this.buildToolResultMessages(this._state.toolResults) : [];
 
     // Compile the context (with optional injections) into a request. The
-    // guard's refusal retry is assembled the same way, afresh. A withheld
-    // stub is compiled only once it says where its original went, including
-    // one whose annotation began during the compile.
+    // guard's refusal retry is assembled the same way, afresh. It is compiled
+    // only once each withheld stub's annotation has finished, including one
+    // that began during the compile, and after a stub edit that failed has
+    // been retried; one whose store still fails is compiled as the bare
+    // notice.
     const assemble = async (): Promise<NormalizedRequest> => {
       const { messages, systemInjections } = await this.toolResultGuard.afterAnnotations(
         () => this.compileWithInjections(budget, injections));
@@ -970,8 +972,9 @@ export class Agent {
     this.lastStreamRealInputTokens = 0;
     this.lastStreamOutputTokens = 0;
 
-    // A withheld stub is compiled only once it says where its original went,
-    // including one whose annotation began during the compile.
+    // Compiled only once each withheld stub's annotation has finished,
+    // including one that began during the compile, and after a stub edit that
+    // failed has been retried (see afterAnnotations).
     const request = await this.toolResultGuard.afterAnnotations(
       () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
     request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
@@ -1205,8 +1208,8 @@ export class Agent {
       const ids = this.toolResultGuard.withhold('unknown');
       if (ids) {
         abandonedUsage = response.usage;
-        // The retry is compiled afresh, like every request: once each stub
-        // says where its original went (agent-framework #277), and against the
+        // The retry is compiled afresh, like every request: once each stub's
+        // annotation has finished (agent-framework #277), and against the
         // budget without the batch's reservation, so a stub longer than its
         // original can't carry the request past the budget.
         response = await this.membrane.stream(await reassemble(), { signal });
diff --git a/src/framework.ts b/src/framework.ts
index c11fd0b67..1d0473956 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -88,7 +88,7 @@ import { ChannelRegistry, type ChannelToolOrigin } from './mcpl/channel-registry
 import { ConversationRouter, CONVERSATION_ROUTING_DEPRECATION_NOTICE } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import type { WorkspaceModule } from './modules/workspace/index.js';
-import type { WithheldSpill } from './tool-result-guard.js';
+import type { ToolResultGuard, WithheldSpill } from './tool-result-guard.js';
 import {
   toolResultDataToHistoryString,
   truncateForHistory,
@@ -2030,8 +2030,10 @@ export class AgentFramework {
     // fork leaves the agent map while its annotation can still be running.
     while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
     // An annotation that starts after this point, such as one from a direct
-    // Agent API call stop doesn't cancel, writes no file to the stopping
-    // workspace: its stub names the audit record.
+    // Agent API call stop doesn't cancel, starts no write to the stopping
+    // workspace: its stub names the audit record. A write that was past its
+    // deadline is not waited for, and may still finish or fail after the
+    // modules stop.
     this.guardSpillsClosed = true;
 
     // Stop modules and MCPL servers in parallel
@@ -2046,12 +2048,14 @@ export class AgentFramework {
     while (this.guardAnnotations.size > 0) await Promise.all([...this.guardAnnotations]);
 
     // Streams may queue storage repairs while being cancelled above. Retry
-    // after their teardown, while the store is still open, before final sync.
-    for (const agent of this.agents.values()) {
+    // after their teardown, while the store is still open, before final sync:
+    // every live agent's guard, and every guard that annotated, which an
+    // ephemeral run or a closed fork takes out of the agent map.
+    for (const [guard, name] of this.guardsWithStorageWork()) {
       try {
-        agent.toolResultGuard.flushUnrecorded();
+        guard.flushUnrecorded();
       } catch (error) {
-        console.error(`[tool-result-guard] agent=${agent.name} could not finish queued storage work at stop:`, error);
+        console.error(`[tool-result-guard] agent=${name} could not finish queued storage work at stop:`, error);
       }
     }
 
@@ -2285,6 +2289,19 @@ export class AgentFramework {
   }
 
   private async runQueuedMaintenance(): Promise<void> {
+    // A guard whose agent has left the map gets no activation to retry its
+    // queue; retry it here, and forget it once nothing of it is left.
+    const live = new Set([...this.agents.values()].map((agent) => agent.toolResultGuard));
+    for (const [guard, name] of this.annotatingGuards) {
+      if (!live.has(guard)) {
+        try {
+          guard.flushUnrecorded();
+        } catch (error) {
+          console.error(`[tool-result-guard] agent=${name} storage retry failed during maintenance:`, error);
+        }
+      }
+      if (guard.idle) this.annotatingGuards.delete(guard);
+    }
     const queued = [...this.agents.values()].flatMap((agent) => {
       try {
         agent.toolResultGuard.flushUnrecorded();
@@ -2716,6 +2733,14 @@ export class AgentFramework {
 
   /** Every guard's annotation still running, for stop() (agent-framework #277). */
   private readonly guardAnnotations = new Set<Promise<void>>();
+  /** Each guard that has annotated, by agent name, until it is idle: an
+   *  ephemeral run or a closed fork leaves the agent map with its annotation
+   *  still running and maybe a stub edit queued, which maintenance and stop
+   *  then retry (agent-framework #277). */
+  private readonly annotatingGuards = new Map<ToolResultGuard, string>();
+  /** A withheld original's write still under way past its deadline: until it
+   *  settles, the workspace isn't answering and no other is started. */
+  private stalledSpill: Promise<void> | undefined;
   /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
   /** Set once stop() has let the running annotations finish: a withheld
@@ -2734,15 +2759,26 @@ export class AgentFramework {
       throw new Error(`Invalid persisted tool_result_guard for ${agent.name}: expected a boolean`);
     }
     agent.toolResultGuard.setOverride(enabled);
-    agent.toolResultGuard.setHost({
+    const guard = agent.toolResultGuard;
+    guard.setHost({
       spill: (label, text, branch) => this.spillWithheld(label, text, branch),
       track: (annotation) => {
         this.guardAnnotations.add(annotation);
+        this.annotatingGuards.set(guard, agent.name);
         void annotation.finally(() => this.guardAnnotations.delete(annotation));
       },
     });
   }
 
+  /** Each guard that may have queued storage work, once, by agent name: the
+   *  live agents' and those that annotated. */
+  private guardsWithStorageWork(): Map<ToolResultGuard, string> {
+    const guards = new Map<ToolResultGuard, string>();
+    for (const agent of this.agents.values()) guards.set(agent.toolResultGuard, agent.name);
+    for (const [guard, name] of this.annotatingGuards) if (!guards.has(guard)) guards.set(guard, name);
+    return guards;
+  }
+
   private buildThinkTool(
     policy: SameRoundThinkTextPolicy,
   ): import('./types/index.js').ToolDefinition {
@@ -7417,8 +7453,8 @@ export class AgentFramework {
       const { messages: existing } = await contextManager.compile();
       if (existing.length === 0) {
         // The copy is the fork's own, and the template's annotation edits only
-        // the template's message: seed only from stubs that already say where
-        // their originals went.
+        // the template's message: seed only once each of the template's
+        // annotations has finished.
         const { messages: compiled } = await template.toolResultGuard.afterAnnotations(
           () => template.getContextManager().compile());
         for (const msg of compiled) {
@@ -11761,21 +11797,39 @@ export class AgentFramework {
   /**
    * The guard's spill of a withheld original (agent-framework #277): the
    * tool-results file, waited for at most withheldSpillDeadlineMs. A write
-   * still under way then is reported as unfinished at its path, and goes on
-   * by itself. Once stop() has let the running annotations finish,
-   * nothing more is written.
+   * still under way then is reported as unfinished at its path. Nothing waits
+   * for it after that, stop() included: it goes on by itself and may finish
+   * or fail after the workspace has stopped, and its record says only that
+   * it was unfinished. Until it settles, the workspace isn't answering, and no
+   * other write is started: each later spill, of any agent's batch, is
+   * reported unanswered at once, so a stalled mount costs one deadline. A
+   * write the workspace declines because it had left `branch` is reported
+   * as such, with no path, since no file was written. Once stop() has let the
+   * running annotations finish, no new write is started.
    */
   private async spillWithheld(label: string, text: string, branch: string): Promise<WithheldSpill> {
     if (this.guardSpillsClosed) return null;
     const place = this.toolResultFilePlace(label);
     if (!place) return null;
+    if (this.stalledSpill) return { skipped: 'workspace_unanswered' };
+    const write = this.writeToolResultFile(label, text, branch);
     let timer: ReturnType<typeof setTimeout> | undefined;
-    const late = new Promise<WithheldSpill>((resolve) => {
-      timer = setTimeout(() => resolve({ path: place.path, unfinished: true }), this.withheldSpillDeadlineMs);
+    const late = new Promise<'late'>((resolve) => {
+      timer = setTimeout(() => resolve('late'), this.withheldSpillDeadlineMs);
       timer.unref?.();
     });
     try {
-      return await Promise.race([this.writeToolResultFile(label, text, branch), late]);
+      const written = await Promise.race([write, late]);
+      if (written !== 'late') {
+        if (!written) return null;
+        if (written.branchLeft) return { skipped: 'branch_changed' };
+        return { path: written.path, ...(written.error !== undefined ? { error: written.error } : {}) };
+      }
+      const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => {
+        if (this.stalledSpill === stalled) this.stalledSpill = undefined;
+      });
+      this.stalledSpill = stalled;
+      return { path: place.path, unfinished: true };
     } finally {
       clearTimeout(timer);
     }
@@ -11792,7 +11846,7 @@ export class AgentFramework {
     label: string,
     content: string,
     branch?: string,
-  ): Promise<{ path: string; error?: string } | null> {
+  ): Promise<{ path: string; error?: string; branchLeft?: true } | null> {
     const place = this.toolResultFilePlace(label);
     if (!place) return null;
     const { workspace, path, safeLabel } = place;
@@ -11811,7 +11865,7 @@ export class AgentFramework {
       // Declined, not failed: the store left the branch the file is for, so
       // it isn't written anywhere, as the caller asked.
       if ((result.data as { branchLeft?: boolean } | undefined)?.branchLeft === true) {
-        return { path, error: result.error ?? 'the workspace had left the branch this file is for' };
+        return { path, error: result.error ?? 'the workspace had left the branch this file is for', branchLeft: true };
       }
       failure = result.error ?? 'write refused';
     } catch (err) {
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 07642e07c..874d44c72 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -8,19 +8,29 @@ import { isStateExistsError } from './module-registry.js';
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
-/** Where a withheld result's original was written: a workspace path; the
- *  path a write to it failed at (`error`); the path a write was still under
- *  way to when the host stopped waiting for it (`unfinished`); or null when
- *  there is no writable workspace. */
-export type WithheldSpill = { path: string; error?: string; unfinished?: true } | null;
+/** Where a withheld result's original went: a workspace path; the path a
+ *  write to it failed at (`error`); the path a write was still under way to
+ *  when the host stopped waiting for it (`unfinished`); no write, because the
+ *  workspace isn't answering (`workspace_unanswered`: an earlier write is
+ *  still under way past the host's deadline) or because the workspace had
+ *  left the stub's branch when the file would have been committed
+ *  (`branch_changed`); or null when no file is written at all (no writable
+ *  workspace, or the host is stopping). */
+export type WithheldSpill =
+  | { path: string; error?: string; unfinished?: true }
+  | { skipped: 'workspace_unanswered' | 'branch_changed' }
+  | null;
 
 /** Writes one withheld original as a workspace file (the framework's
  *  tool-results spill). It reports a failed write rather than throwing, and
  *  it settles within a bounded time: a write still under way at the host's
- *  deadline is reported as unfinished, so one stalled write can't hold every
- *  later request and the host's stop. The file lands on `branch`,
- *  the branch the stub is on, or isn't written: the workspace checks the
- *  branch where it commits the file (WorkspaceModule.writeBinary). */
+ *  deadline is reported as unfinished, and until that write settles the host
+ *  starts no other (each is `workspace_unanswered`), so a stalled workspace
+ *  costs one deadline however many results and batches queue behind it. The
+ *  file lands on `branch`, the branch the stub is on, or isn't written: the
+ *  workspace checks the branch where it commits the file
+ *  (WorkspaceModule.writeBinary), and a write it declines is
+ *  `branch_changed`. */
 export type WithheldSpiller = (label: string, text: string, branch: string) => Promise<WithheldSpill>;
 
 /** What a host gives a guard for its withheld results: where originals are
@@ -49,17 +59,15 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
   const kept = (only: string) => auditDurable
     ? `is kept ${only}in ${audit}`
     : `went ${only}to ${audit}, though saving that record had failed when the result arrived`;
-  if (spill?.unfinished) {
+  if (!spill || 'skipped' in spill) return `${TOOL_RESULT_GUARD_NOTICE} Its result ${kept('')}.`;
+  if (spill.unfinished) {
     return `${TOOL_RESULT_GUARD_NOTICE} Its result was still being written to workspace file ${spill.path} ` +
       `when this note was made; if that file is missing, it ${kept('')}.`;
   }
-  if (spill && spill.error === undefined) {
+  if (spill.error === undefined) {
     return `${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${spill.path}.`;
   }
-  if (spill) {
-    return `${TOOL_RESULT_GUARD_NOTICE} Writing its result to workspace file ${spill.path} failed, so it ${kept('only ')}.`;
-  }
-  return `${TOOL_RESULT_GUARD_NOTICE} Its result ${kept('')}.`;
+  return `${TOOL_RESULT_GUARD_NOTICE} Writing its result to workspace file ${spill.path} failed, so it ${kept('only ')}.`;
 }
 
 interface PendingBatch {
@@ -113,10 +121,14 @@ export class ToolResultGuard {
 
   get enabled(): boolean { return this.override ?? this.configured; }
   setHost(host: WithheldHost | undefined): void { this.host = host; }
-  /** Settles once every withheld stub settled so far names where its
-   *  original is (or that edit was given up). It never rejects, and it is
-   *  bounded: the host reports a write still under way at its deadline as
-   *  unfinished. */
+  /** Settles once every annotation started so far has finished: each of
+   *  those stubs has been edited to say where its original is, or its edit
+   *  failed and waits in the storage queue, retried in order until it lands
+   *  or an operator's change supersedes it (until then the stub is the bare
+   *  notice, kept out of summaries by its compression hold, and the audit
+   *  record names the place). It never rejects. Its wait is bounded: the host
+   *  reports a write still under way at its deadline as unfinished and starts
+   *  no other until that write settles. */
   whenAnnotated(): Promise<void> { return this.annotating ?? Promise.resolve(); }
 
   /**
@@ -128,15 +140,31 @@ export class ToolResultGuard {
    * API calls and their refusal retry, and a conversation fork's seed from its
    * template. A request preview doesn't, so it never waits on a
    * workspace write.
+   *
+   * Before `read`, a stub edit that failed gets another try with the rest of
+   * the storage queue; a store that is still failing then compiles the bare
+   * notice, which its hold keeps out of summaries.
    */
   async afterAnnotations<T>(read: () => Promise<T>): Promise<T> {
     for (;;) {
-      await this.whenAnnotated();
+      // Counted before the wait, so an annotation that starts while this one
+      // is awaited is waited for too.
       const started = this.annotationsStarted;
+      await this.whenAnnotated();
+      if (this.annotationsStarted !== started) continue;
+      try {
+        this.flushUnrecorded();
+      } catch (error) {
+        console.error(`[tool-result-guard] agent=${this.agentName} storage retry before a compile failed:`, error);
+      }
       const result = await read();
       if (this.annotationsStarted === started) return result;
     }
   }
+
+  /** No annotation is running and no storage work is queued: nothing of this
+   *  guard is left for a host to wait on or retry. */
+  get idle(): boolean { return this.annotating === undefined && this.unrecorded.length === 0; }
   setOverride(value: boolean | undefined): void { this.override = value; }
   get settingOverride(): boolean | undefined { return this.override; }
   get hasPending(): boolean { return this.pending !== undefined; }
@@ -176,24 +204,7 @@ export class ToolResultGuard {
     while (this.unrecorded.length > 0) {
       const operation = this.unrecorded[0];
       try {
-        if (operation.admission) {
-          const { messageId, content, expected, branch } = operation.admission;
-          const sameBranch = this.cm.currentBranch().name === branch;
-          const current = sameBranch ? this.cm.getMessage(messageId) : null;
-          // A retry must not undo an operator's later edit/removal/rollback.
-          // Reapplying our own payload is safe if an earlier edit wrote the
-          // message and then failed while propagating to context entries.
-          // Chronicle normalizes object-key order and drops undefined fields.
-          if (!sameBranch || !current ||
-            (!isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(expected)))
-              && !isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(content))))) {
-            operation.record.historyUpdate = 'superseded';
-          } else {
-            this.cm.editMessage(messageId, content);
-          }
-          // An audit-only retry must not repeat an edit that already succeeded.
-          operation.admission = undefined;
-        }
+        this.applyEdit(operation);
         this.write(operation.record);
         this.unrecorded.shift();
       } finally {
@@ -202,6 +213,29 @@ export class ToolResultGuard {
     }
   }
 
+  /** Make an operation's history edit, if it still has one: once it is made,
+   *  or superseded by an operator's change, only its record is left to
+   *  write, and its hold can go. */
+  private applyEdit(operation: AuditOperation): void {
+    if (!operation.admission) return;
+    const { messageId, content, expected, branch } = operation.admission;
+    const sameBranch = this.cm.currentBranch().name === branch;
+    const current = sameBranch ? this.cm.getMessage(messageId) : null;
+    // A retry must not undo an operator's later edit/removal/rollback.
+    // Reapplying our own payload is safe if an earlier edit wrote the
+    // message and then failed while propagating to context entries.
+    // Chronicle normalizes object-key order and drops undefined fields.
+    if (!sameBranch || !current ||
+      (!isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(expected)))
+        && !isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(content))))) {
+      operation.record.historyUpdate = 'superseded';
+    } else {
+      this.cm.editMessage(messageId, content);
+    }
+    // An audit-only retry must not repeat an edit that already succeeded.
+    operation.admission = undefined;
+  }
+
   private append(record: Record<string, unknown>): void {
     const stamped = { agentName: this.agentName, timestamp: Date.now(), ...record };
     this.unrecorded.push({ record: stamped });
@@ -376,8 +410,9 @@ export class ToolResultGuard {
 
   /** Transfer ownership from provider admission to an ordered storage job.
    * Failure retains the accepted payload and its hold until the edit succeeds.
-   * A withheld batch's hold passes to its annotation instead, so no summary
-   * is made of a stub that doesn't yet say where its original went. */
+   * A withheld batch's hold passes to its annotation instead, and from there
+   * to its stub's edit, so no summary is made of a stub that doesn't yet say
+   * where its original went. */
   private settle(pending: PendingBatch, record: Record<string, unknown>, admit: boolean): void {
     this.pending = undefined;
     const operation: AuditOperation = {
@@ -403,19 +438,25 @@ export class ToolResultGuard {
    * is (agent-framework #277): written to the workspace when a writable mount
    * takes it, else kept in the audit record. Its own unedited placeholder is
    * the only thing it edits: an operator's later edit, removal or rollback
-   * stands. It releases the compression hold when done, whatever happened.
+   * stands.
    *
    * Where each original went is recorded first, on its own ('annotated'), so
    * a stub edit that fails can't take the record of a written file with it.
-   * The edit then goes through the ordered storage queue like an admission's:
-   * retried before the next activation, maintenance pass or stop until it
-   * lands or an operator's change supersedes it ('stub_updated'), so a failed
-   * edit no longer leaves a written file named nowhere.
+   * The edit is made at once, so no storage work queued ahead of it holds it,
+   * and its record ('stub_updated') is written in order after the others. An
+   * edit that fails joins the ordered storage queue like an admission's, with
+   * the batch's compression hold: retried before the next activation, compile,
+   * maintenance pass or stop until it lands or an operator's change supersedes
+   * it. Until then the stub is the bare notice, which the hold keeps out of
+   * summaries, and the audit record names the file.
    */
   private annotate(pending: PendingBatch): void {
     const previous = this.annotating ?? Promise.resolve();
     this.annotationsStarted += 1;
     const run = previous.then(async () => {
+      // Set once the stub's edit is queued with the hold: the queue releases
+      // it when the edit lands or is superseded.
+      let holdQueued = false;
       try {
         const date = new Date().toISOString().slice(0, 10);
         // A file is named by its batch and its place in the batch, ahead of
@@ -427,11 +468,6 @@ export class ToolResultGuard {
         // Keyed by the result's index in the batch, which the stub and the
         // original share.
         const spills = new Map<number, WithheldSpill>();
-        // Results not written because an earlier write of the batch was still
-        // under way at the host's deadline: the workspace isn't answering, and
-        // waiting a deadline for each would hold every request and stop that
-        // much longer. Their stubs name the audit record.
-        const unanswered = new Set<number>();
         // A spill that threw, by index: its error, for the record.
         const thrown = new Map<number, string>();
         for (const [index, block] of pending.content.entries()) {
@@ -443,11 +479,8 @@ export class ToolResultGuard {
           // under way when the branch changes is refused where it commits,
           // since it names the batch's branch, so no file lands elsewhere.
           if (this.cm.currentBranch().name !== pending.branch) break;
-          if ([...spills.values()].some((spill) => spill?.unfinished)) {
-            unanswered.add(index);
-            spills.set(index, null);
-            continue;
-          }
+          // The result as stored. Both paths that store a tool result store
+          // its text; content stored as blocks would be written as their JSON.
           const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
           let spill: WithheldSpill = null;
           if (this.host) {
@@ -461,52 +494,70 @@ export class ToolResultGuard {
                 `${block.toolUseId}:`, error);
             }
           }
+          // Declined where it would have committed, since the workspace had
+          // left the batch's branch: nothing was written, and no more are, as
+          // for the results the branch check above stops.
+          if (spill && 'skipped' in spill && spill.skipped === 'branch_changed') break;
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
           && spills.has(index)
-          ? { ...block, content: withheldResultNotice(spills.get(index)!, pending.durable) }
+          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable) }
           : block);
         try {
           this.append({
-            type: 'annotated', batchId: pending.id, messageId: pending.messageId,
+            type: 'annotated', batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch,
             results: pending.content.flatMap((block, index): Array<Record<string, string | true>> => {
               if (block.type !== 'tool_result') return [];
               if (!spills.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'branch_changed' }];
-              if (unanswered.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'workspace_unanswered' }];
               if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
               const spill = spills.get(index);
               // No file was written: no writable workspace, or the framework
               // was stopping.
-              if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
-              return [{ toolUseId: block.toolUseId, ...(spill ? { path: spill.path } : {}),
-                ...(spill?.error !== undefined ? { error: spill.error } : {}),
-                ...(spill?.unfinished ? { unfinished: true as const } : {}) }];
+              if (spill === null || spill === undefined) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
+              if ('skipped' in spill) return [{ toolUseId: block.toolUseId, skipped: spill.skipped }];
+              return [{ toolUseId: block.toolUseId, path: spill.path,
+                ...(spill.error !== undefined ? { error: spill.error } : {}),
+                ...(spill.unfinished ? { unfinished: true as const } : {}) }];
             }),
           });
         } catch (error) {
           // It stays queued and is retried in order with the storage work
-          // ahead of it; the stub's edit waits behind it.
+          // ahead of it; the stub's record is written after it.
           console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} annotation record queued for retry:`, error);
         }
-        this.unrecorded.push({
+        const stub: AuditOperation = {
           record: { agentName: this.agentName, timestamp: Date.now(), type: 'stub_updated',
-            batchId: pending.id, messageId: pending.messageId },
+            batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch },
           admission: { messageId: pending.messageId, content: annotated, expected: pending.withheld, branch: pending.branch },
-        });
+          heldMessageId: pending.messageId,
+        };
         try {
-          this.flushUnrecorded();
+          this.applyEdit(stub);
         } catch (error) {
           console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} stub edit queued for retry:`, error);
         }
+        this.unrecorded.push(stub);
+        holdQueued = true;
+        try {
+          // A made edit's hold goes now, whatever storage work is still
+          // queued ahead of its record.
+          if (!stub.admission) this.releaseOperationHold(stub);
+          this.flushUnrecorded();
+        } catch (error) {
+          console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} stub's storage work queued for retry:`, error);
+        }
       } catch (error) {
         console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} could not annotate withheld results:`, error);
       } finally {
-        // Never rejects: a compile and stop() wait on this chain.
-        try {
-          this.releaseHold(pending.messageId);
-        } catch (error) {
-          console.error(`[tool-result-guard] agent=${this.agentName} could not release a withheld batch's hold:`, error);
+        // Never rejects: a compile and stop() wait on this chain. With no
+        // stub edit queued, nothing else holds the batch.
+        if (!holdQueued) {
+          try {
+            this.releaseHold(pending.messageId);
+          } catch (error) {
+            console.error(`[tool-result-guard] agent=${this.agentName} could not release a withheld batch's hold:`, error);
+          }
         }
       }
     });
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 795e9277f..2970e4665 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1030,6 +1030,17 @@ async function until(check: () => boolean, what: string) {
   for (let i = 0; i < 400 && !check(); i++) await new Promise((resolve) => setTimeout(resolve, 5));
   assert.ok(check(), `timed out waiting until ${what}`);
 }
+/** `promise`, or a failure once it has taken `ms`: a wait the code under test
+ *  should bound fails the test rather than hanging it. */
+async function bounded<T>(promise: Promise<T>, what: string, ms = 5000): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${what} took longer than ${ms} ms`)), ms);
+  });
+  try {
+    return await Promise.race([promise, late]);
+  } finally { clearTimeout(timer); }
+}
 
 /** Calls of a guard's afterAnnotations, the compile's wait for its stubs. */
 function watchCompiles(framework: AgentFramework, agentName = 'assistant') {
@@ -1390,7 +1401,7 @@ test('#277: a rollback while an aborted batch is being annotated gets none of it
   } finally { release(); await h.framework.stop(); }
 });
 
-test('#277: a write under way when a rollback lands is refused where it commits, and neither branch gets its file', async () => {
+test('#277: a write under way when a rollback lands is refused where it commits, recorded as skipped for the branch change, and neither branch gets its file', async () => {
   const h = await workspaceHarness([[calls('one', 'two')]]);
   type Writer = (label: string, text: string, branch?: string) => Promise<{ path: string; error?: string } | null>;
   const framework = h.framework as unknown as { writeToolResultFile: Writer };
@@ -1398,10 +1409,15 @@ test('#277: a write under way when a rollback lands is refused where it commits,
   let release!: () => void;
   const gate = new Promise<void>((resolve) => { release = resolve; });
   const branches: Array<string | undefined> = [];
-  // The first write is held after the guard's branch check and before the
-  // workspace commits the file: the rollback lands in between.
+  const labels: string[] = [];
+  // The guard's branch check and the workspace's commit run with nothing
+  // yielding between them. This wrapper adds a wait there, so a rollback
+  // lands in between, and the test pins the commit's own check, the one that
+  // holds should an await ever come between them. writeBinary's check alone
+  // is pinned by the test after this one.
   framework.writeToolResultFile = async (label, text, branch) => {
     branches.push(branch);
+    labels.push(label);
     if (branches.length === 1) await gate;
     return write(label, text, branch);
   };
@@ -1428,12 +1444,10 @@ test('#277: a write under way when a rollback lands is refused where it commits,
     const annotated = audit.find((record) => record.type === 'annotated') as
       { results: Array<{ toolUseId: string; path?: string; error?: string; skipped?: string }> } | undefined;
     assert.ok(annotated, `the annotation is recorded: ${JSON.stringify(audit)}`);
-    const [one, two] = annotated.results;
-    assert.equal(one.toolUseId, 'one');
-    assert.equal(one.error, 'the workspace had left the branch this file is for');
-    assert.deepEqual(two, { toolUseId: 'two', skipped: 'branch_changed' });
+    assert.deepEqual(annotated.results, [{ toolUseId: 'one', skipped: 'branch_changed' }, { toolUseId: 'two', skipped: 'branch_changed' }],
+      'the declined write names no path, since no file was written, and the next is not started');
     assert.ok(!traces.some((event) => event.type === 'tool:spill_failed'), 'a declined write is not traced as a failed spill');
-    const relative = one.path!.replace(/^work\//, '');
+    const relative = `tool-results/${labels[0].replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80)}.txt`;
     const store = h.framework.getStore();
     assert.equal(store.treeGet('workspace/work/tree', relative), null, 'the branch rolled back to has no file');
     await cm.switchBranch(source);
@@ -1523,7 +1537,7 @@ test('#281: a write still under way at the deadline is named as unfinished, and
   };
   let stopped = false;
   try {
-    await h.run();
+    await bounded(h.run(), 'the run, with its write stalled');
     assert.equal(writes, 1, "once the workspace stopped answering, the batch's next result isn't written");
     assert.equal(h.membrane.requests.length, 2, 'the retry went out without the write');
     const [one, two] = toolResults(h.framework).map((block) => String(block.content));
@@ -1539,36 +1553,223 @@ test('#281: a write still under way at the deadline is named as unfinished, and
   } finally { stalled.open(); if (!stopped) await h.framework.stop(); }
 });
 
-test('#281: a failed stub edit leaves the record of the written file, and the edit is retried before the next activation', async () => {
+test("#281: a stub edit that keeps failing leaves the record of the written file and keeps the batch's hold until it lands", async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()], [answer()]]);
   const cm = h.framework.getAgent('assistant')!.getContextManager() as unknown as {
     editMessage: (id: unknown, content: ContentBlock[]) => unknown;
+    getCompressionHolds(): Set<unknown>;
   };
   const edit = cm.editMessage.bind(cm);
-  let failures = 0;
+  let failing = true;
+  let attempts = 0;
   cm.editMessage = (id, content) => {
-    if (failures === 0 && JSON.stringify(content).includes('Its result is in workspace file')) {
-      failures++;
-      throw new Error('injected stub edit failure');
+    if (JSON.stringify(content).includes('Its result is in workspace file')) {
+      attempts++;
+      if (failing) throw new Error('injected stub edit failure');
     }
     return edit(id, content);
   };
+  // The write waits until the refusal retry's compile is waiting for it, so
+  // the stub's edit fails only where the guard handles it.
+  const framework = h.framework as unknown as { writeToolResultFile: (...args: unknown[]) => Promise<unknown> };
+  const writeFile = framework.writeToolResultFile.bind(h.framework);
+  const write = gate();
+  framework.writeToolResultFile = async (...args) => { await write.opened; return writeFile(...args); };
+  const compiles = watchCompiles(h.framework);
   const audit = () => h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
   try {
-    await h.run();
-    assert.equal(failures, 1);
+    const running = h.run();
+    await until(() => compiles.calls === 2, 'the refusal retry waits for the stub');
+    write.open();
+    await running;
+    assert.ok(attempts >= 3, `made at once, retried with the queue, and again before the retry was compiled: ${attempts}`);
     const annotated = audit().find((record) => record.type === 'annotated') as { results: Array<{ path?: string }> };
     const path = annotated.results[0].path;
     assert.ok(path && SPILLED_STUB.test(`${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${path}.`),
       `the record names the written file though the edit failed: ${JSON.stringify(annotated)}`);
     assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE, 'the stub is still the bare notice');
+    const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(retried.map((b) => b.content), [TOOL_RESULT_GUARD_NOTICE], 'the retry went out with the store still failing');
     assert.equal(audit().some((record) => record.type === 'stub_updated'), false, 'the edit is still queued');
+    assert.equal(cm.getCompressionHolds().size, 1, 'and still holds the batch out of summaries');
+    failing = false;
     await h.run();
     assert.equal(toolResults(h.framework)[0].content, `${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${path}.`);
     assert.equal(audit().at(-1)?.type, 'stub_updated');
     assert.equal(audit().at(-1)?.historyUpdate, undefined);
-    assert.equal(h.framework.getAgent('assistant')!.getContextManager().getCompressionHolds().size, 0);
-  } finally { await h.framework.stop(); }
+    assert.equal(cm.getCompressionHolds().size, 0, 'released once it landed');
+  } finally { write.open(); await h.framework.stop(); }
+});
+
+test('#281: a stub edit that failed is retried before the refusal retry is compiled, so the retry says where the original is', async () => {
+  const h = await harness([[calls('one'), refused()], [answer()]], { toolResultGuard: true });
+  const write = gate();
+  slowSpill(h.framework, () => write.opened);
+  const cm = h.framework.getAgent('assistant')!.getContextManager() as unknown as {
+    editMessage: (id: unknown, content: ContentBlock[]) => unknown;
+  };
+  const edit = cm.editMessage.bind(cm);
+  let attempts = 0;
+  cm.editMessage = (id, content) => {
+    if (JSON.stringify(content).includes('Its result is kept in')) {
+      attempts++;
+      // Both tries the annotation makes fail; the next succeeds.
+      if (attempts <= 2) throw new Error('injected stub edit failure');
+    }
+    return edit(id, content);
+  };
+  const compiles = watchCompiles(h.framework);
+  try {
+    const running = h.run();
+    await until(() => compiles.calls === 2, 'the refusal retry waits for the stub');
+    write.open();
+    await running;
+    assert.equal(attempts, 3);
+    const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+    assert.deepEqual(retried.map((b) => b.content), [AUDIT_STUB]);
+  } finally { write.open(); await h.framework.stop(); }
+});
+
+test("#281: when the record of where each original went can't be saved at first, the stub is still edited, and the records keep their order", async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
+  const store = h.framework.getStore();
+  const append = store.appendToStateJson.bind(store);
+  let failures = 0;
+  store.appendToStateJson = (id, value) => {
+    if (id === TOOL_RESULT_GUARD_AUDIT_STATE && (value as { type?: string } | undefined)?.type === 'annotated' && failures === 0) {
+      failures++;
+      throw new Error('injected annotated append failure');
+    }
+    return append(id, value);
+  };
+  try {
+    await h.run();
+    assert.equal(failures, 1);
+    const stub = String(toolResults(h.framework)[0].content);
+    const path = SPILLED_STUB.exec(stub)?.[1];
+    assert.ok(path, `the stub names the file: ${stub}`);
+    const audit = store.getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    assert.deepEqual(audit.slice(-3).map((record) => record.type), ['withheld', 'annotated', 'stub_updated']);
+    assert.deepEqual(audit.at(-2)?.results, [{ toolUseId: 'one', path }]);
+    const branch = h.framework.getAgent('assistant')!.getContextManager().currentBranch().name;
+    for (const record of audit.slice(-3)) assert.equal(record.sourceBranch, branch, `${String(record.type)} names its branch`);
+  } finally { store.appendToStateJson = append; await h.framework.stop(); }
+});
+
+test('#281: a compile waits for an annotation that began while it waited for another', async () => {
+  const r = await compressionRig();
+  try {
+    const first = gate();
+    const second = gate();
+    let entered = 0;
+    r.guard.setHost({ spill: async () => {
+      entered++;
+      await (entered === 1 ? first.opened : second.opened);
+      return null;
+    }, track: () => {} });
+    r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
+    assert.ok(r.guard.withhold('test-category'));
+    await until(() => entered === 1, 'the first annotation is writing');
+    const stub = (id: unknown) => (r.cm.getMessage(id as typeof r.messageId)!.content[0] as { content: unknown }).content;
+    let secondId: unknown;
+    let reads = 0;
+    const compiled = r.guard.afterAnnotations(async () => { reads++; return [stub(r.messageId), stub(secondId)]; });
+    // A second batch settles while the compile waits for the first annotation.
+    r.cm.addMessage('Claude', [{ type: 'tool_use', id: 'tu-2', name: 'search', input: {} }]);
+    secondId = r.guard.storeResults([{ type: 'tool_result', toolUseId: 'tu-2', content: 'SECOND' }],
+      [{ toolUseId: 'tu-2', content: 'SECOND' }], []);
+    r.guard.submissionResults([{ toolUseId: 'tu-2', content: 'SECOND' }]);
+    assert.ok(r.guard.withhold('test-category'));
+    first.open();
+    await until(() => entered === 2, 'the second annotation is writing');
+    assert.equal(reads, 0, 'the compile waits for it too');
+    second.open();
+    assert.deepEqual(await compiled, [AUDIT_STUB, AUDIT_STUB]);
+    assert.equal(reads, 1);
+  } finally { r.cm.close(); }
+});
+
+test("#281: a disposed run's failed stub edit is retried by maintenance and at stop", async () => {
+  const h = await harness([[calls('one')]]);
+  slowSpill(h.framework, async () => {});
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  let stopped = false;
+  try {
+    const created = await h.framework.createEphemeralAgent({
+      name: 'ephemeral', model: 'test', systemPrompt: 'system', toolResultGuard: true,
+    });
+    const cm = created.contextManager as unknown as { editMessage: (id: unknown, content: ContentBlock[]) => unknown };
+    const edit = cm.editMessage.bind(cm);
+    let failing = true;
+    let attempts = 0;
+    cm.editMessage = (id, content) => {
+      if (JSON.stringify(content).includes('Its result is kept in')) {
+        attempts++;
+        if (failing) throw new Error('injected stub edit failure');
+      }
+      return edit(id, content);
+    };
+    created.contextManager.addMessage('user', [{ type: 'text', text: 'read' }]);
+    const completion = h.framework.runEphemeralToCompletion(created.agent, created.contextManager);
+    h.framework.start();
+    await completion.catch(() => {});
+    await created.agent.toolResultGuard.whenAnnotated();
+    assert.equal(h.framework.getAgent('ephemeral') ?? null, null, 'the run was disposed');
+    assert.ok(attempts >= 2, `made at once and retried with the queue: ${attempts}`);
+    assert.equal(created.agent.toolResultGuard.idle, false, 'and still queued');
+    const before = attempts;
+    await (h.framework as unknown as { runQueuedMaintenance(): Promise<void> }).runQueuedMaintenance();
+    assert.ok(attempts > before, "maintenance retries the disposed run's queue");
+    failing = false;
+    await h.framework.stop();
+    stopped = true;
+    assert.equal(created.agent.toolResultGuard.idle, true, 'stop retried it, and it landed');
+    const restarted = await AgentFramework.create(h.base);
+    try {
+      const audit = restarted.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+      assert.ok(audit.some((record) => record.type === 'stub_updated' && record.agentName === 'ephemeral'),
+        "the disposed run's stub edit landed before the store closed");
+    } finally { await restarted.stop(); }
+  } finally { if (!stopped) await h.framework.stop(); }
+});
+
+test('#281: batches behind one stalled write cost one deadline: no write starts until it settles', async () => {
+  const h = await workspaceHarness([
+    [calls('one'), refused()], [answer()],
+    [calls('two'), refused()], [answer()],
+    [calls('three'), refused()], [answer()],
+  ]);
+  (h.framework as unknown as { withheldSpillDeadlineMs: number }).withheldSpillDeadlineMs = 50;
+  const framework = h.framework as unknown as {
+    writeToolResultFile: (...args: unknown[]) => Promise<unknown>;
+    stalledSpill: Promise<void> | undefined;
+  };
+  const writeFile = framework.writeToolResultFile.bind(h.framework);
+  const stalled = gate();
+  let writes = 0;
+  framework.writeToolResultFile = async (...args) => {
+    writes++;
+    if (writes === 1) await stalled.opened;
+    return writeFile(...args);
+  };
+  const annotated = () => (h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>)
+    .filter((record) => record.type === 'annotated') as Array<{ results: Array<Record<string, unknown>> }>;
+  try {
+    await bounded(h.run(), 'the first batch');
+    await bounded(h.run(), 'the second batch');
+    assert.equal(writes, 1, "no write starts while the first is still under way, for this agent's next batch either");
+    assert.equal(annotated()[0].results[0].unfinished, true);
+    assert.deepEqual(annotated()[1].results, [{ toolUseId: 'two', skipped: 'workspace_unanswered' }]);
+    assert.equal(toolResults(h.framework)[1].content, AUDIT_STUB);
+    stalled.open();
+    await until(() => framework.stalledSpill === undefined, 'the stalled write settles');
+    await bounded(h.run(), 'the third batch');
+    assert.equal(writes, 2, 'once it has settled, the next original is written');
+    assert.ok(typeof annotated()[2].results[0].path === 'string' && annotated()[2].results[0].unfinished === undefined);
+  } finally { stalled.open(); await h.framework.stop(); }
 });
 
 test("#281: a file whose copy on disk fails is still in the workspace's tree, and the stub names it", async () => {

From 1b1ba562cae96896cf734057ca80cc7f280725a4 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Mon, 12 Oct 2026 03:28:22 -0400
Subject: [PATCH 09/16] fix(guard): writes that stalled together each hold the
 workspace; an idle guard is forgotten when its annotation ends

Two boundaries from a review of ee7338d, each shown with a probe against the
framework's own methods:
- The host remembered one stalled write. Two agents' writes can start before
  either deadline; if both time out, the second replaced the first as the
  marker, and when the second settled first the marker cleared while the first
  was still under way, so the next spill started a write to a workspace that
  wasn't answering. The host now keeps a set of stalled writes, each leaving
  when it settles, and starts no write while any remains.
- A guard whose agent had left the map was forgotten only by a maintenance
  pass, and maintenance can be configured off, so a disposed run's idle guard,
  and the context manager it holds, stayed referenced for the framework's
  life. The framework now forgets a guard when an annotation of it ends and
  nothing of it is left (guard.idle). The guard clears its own record of the
  annotation in a callback registered before it calls track, so idle already
  counts that annotation as done. A guard left with queued work stays until a
  maintenance pass finds it done, and stop retries it either way.

Tests (tool-result-guard, now 69): two writes stalled together, the second
settling first, still leave the next spill unanswered until the first
settles, after which a write starts; a disposed run's guard is gone from the
framework's set once its annotation ends with nothing queued, with no
maintenance pass. Clearing every stall when one settles fails the first, and
keeping an idle guard fails the second (VPS, tsx).
---
 src/framework.ts               | 27 ++++++++------
 test/tool-result-guard.test.ts | 64 ++++++++++++++++++++++++++++++++--
 2 files changed, 79 insertions(+), 12 deletions(-)

diff --git a/src/framework.ts b/src/framework.ts
index 1d0473956..cd076e084 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -2736,11 +2736,14 @@ export class AgentFramework {
   /** Each guard that has annotated, by agent name, until it is idle: an
    *  ephemeral run or a closed fork leaves the agent map with its annotation
    *  still running and maybe a stub edit queued, which maintenance and stop
-   *  then retry (agent-framework #277). */
+   *  then retry (agent-framework #277). A guard leaves when an annotation of
+   *  its ends with nothing of it left; one left with queued work stays until
+   *  a maintenance pass finds that work done. */
   private readonly annotatingGuards = new Map<ToolResultGuard, string>();
-  /** A withheld original's write still under way past its deadline: until it
-   *  settles, the workspace isn't answering and no other is started. */
-  private stalledSpill: Promise<void> | undefined;
+  /** Withheld originals' writes still under way past their deadline: while
+   *  any is, the workspace isn't answering and no other is started. Several
+   *  can be, when writes of different agents' batches stalled together. */
+  private readonly stalledSpills = new Set<Promise<void>>();
   /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
   /** Set once stop() has let the running annotations finish: a withheld
@@ -2765,7 +2768,13 @@ export class AgentFramework {
       track: (annotation) => {
         this.guardAnnotations.add(annotation);
         this.annotatingGuards.set(guard, agent.name);
-        void annotation.finally(() => this.guardAnnotations.delete(annotation));
+        void annotation.finally(() => {
+          this.guardAnnotations.delete(annotation);
+          // The guard clears its own record of a finished annotation in a
+          // callback it registered before calling track, so `idle` already
+          // counts this one as done.
+          if (guard.idle) this.annotatingGuards.delete(guard);
+        });
       },
     });
   }
@@ -11811,7 +11820,7 @@ export class AgentFramework {
     if (this.guardSpillsClosed) return null;
     const place = this.toolResultFilePlace(label);
     if (!place) return null;
-    if (this.stalledSpill) return { skipped: 'workspace_unanswered' };
+    if (this.stalledSpills.size > 0) return { skipped: 'workspace_unanswered' };
     const write = this.writeToolResultFile(label, text, branch);
     let timer: ReturnType<typeof setTimeout> | undefined;
     const late = new Promise<'late'>((resolve) => {
@@ -11825,10 +11834,8 @@ export class AgentFramework {
         if (written.branchLeft) return { skipped: 'branch_changed' };
         return { path: written.path, ...(written.error !== undefined ? { error: written.error } : {}) };
       }
-      const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => {
-        if (this.stalledSpill === stalled) this.stalledSpill = undefined;
-      });
-      this.stalledSpill = stalled;
+      const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => this.stalledSpills.delete(stalled));
+      this.stalledSpills.add(stalled);
       return { path: place.path, unfinished: true };
     } finally {
       clearTimeout(timer);
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 2970e4665..ef667ddd0 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1745,7 +1745,7 @@ test('#281: batches behind one stalled write cost one deadline: no write starts
   (h.framework as unknown as { withheldSpillDeadlineMs: number }).withheldSpillDeadlineMs = 50;
   const framework = h.framework as unknown as {
     writeToolResultFile: (...args: unknown[]) => Promise<unknown>;
-    stalledSpill: Promise<void> | undefined;
+    stalledSpills: Set<Promise<void>>;
   };
   const writeFile = framework.writeToolResultFile.bind(h.framework);
   const stalled = gate();
@@ -1765,13 +1765,73 @@ test('#281: batches behind one stalled write cost one deadline: no write starts
     assert.deepEqual(annotated()[1].results, [{ toolUseId: 'two', skipped: 'workspace_unanswered' }]);
     assert.equal(toolResults(h.framework)[1].content, AUDIT_STUB);
     stalled.open();
-    await until(() => framework.stalledSpill === undefined, 'the stalled write settles');
+    await until(() => framework.stalledSpills.size === 0, 'the stalled write settles');
     await bounded(h.run(), 'the third batch');
     assert.equal(writes, 2, 'once it has settled, the next original is written');
     assert.ok(typeof annotated()[2].results[0].path === 'string' && annotated()[2].results[0].unfinished === undefined);
   } finally { stalled.open(); await h.framework.stop(); }
 });
 
+test('#281: writes that stalled together each hold the workspace as unanswered until it settles', async () => {
+  const h = await workspaceHarness([]);
+  const framework = h.framework as unknown as {
+    withheldSpillDeadlineMs: number;
+    writeToolResultFile: (label: string) => Promise<unknown>;
+    spillWithheld: (label: string, text: string, branch: string) => Promise<unknown>;
+  };
+  framework.withheldSpillDeadlineMs = 30;
+  const gates = new Map<string, ReturnType<typeof gate>>([['a', gate()], ['b', gate()]]);
+  const started: string[] = [];
+  framework.writeToolResultFile = async (label) => {
+    started.push(label);
+    await gates.get(label)?.opened;
+    return { path: `work/tool-results/${label}.txt` };
+  };
+  const branch = h.framework.getAgent('assistant')!.getContextManager().currentBranch().name;
+  try {
+    // Two agents' writes start together, and both outlive their deadline. The
+    // deadline's timer doesn't hold the process open, so the wait goes through
+    // bounded, whose timer does.
+    const [a, b] = await bounded(
+      Promise.all([framework.spillWithheld('a', 'A', branch), framework.spillWithheld('b', 'B', branch)]),
+      'both writes reach their deadline',
+    );
+    assert.deepEqual([a, b], [{ path: 'work/tool-results/a.txt', unfinished: true }, { path: 'work/tool-results/b.txt', unfinished: true }]);
+    gates.get('b')!.open();
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.deepEqual(await framework.spillWithheld('c', 'C', branch), { skipped: 'workspace_unanswered' },
+      'one stalled write settling leaves the other holding the workspace');
+    gates.get('a')!.open();
+    await until(() => (h.framework as unknown as { stalledSpills: Set<unknown> }).stalledSpills.size === 0, 'both settle');
+    assert.deepEqual(await framework.spillWithheld('d', 'D', branch), { path: 'work/tool-results/d.txt' });
+    assert.deepEqual(started, ['a', 'b', 'd']);
+  } finally { for (const g of gates.values()) g.open(); await h.framework.stop(); }
+});
+
+test("#281: a disposed run's guard is forgotten once its annotation ends with nothing queued, without a maintenance pass", async () => {
+  const h = await harness([[calls('one')]]);
+  slowSpill(h.framework, async () => {});
+  h.membrane.onSubmit = () => {
+    const stream = h.membrane.streams.at(-1)!;
+    queueMicrotask(() => stream.cancel());
+  };
+  try {
+    const created = await h.framework.createEphemeralAgent({
+      name: 'ephemeral', model: 'test', systemPrompt: 'system', toolResultGuard: true,
+    });
+    created.contextManager.addMessage('user', [{ type: 'text', text: 'read' }]);
+    const completion = h.framework.runEphemeralToCompletion(created.agent, created.contextManager);
+    h.framework.start();
+    await completion.catch(() => {});
+    await created.agent.toolResultGuard.whenAnnotated();
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(h.framework.getAgent('ephemeral') ?? null, null, 'the run was disposed');
+    assert.equal(created.agent.toolResultGuard.idle, true);
+    const remembered = (h.framework as unknown as { annotatingGuards: Map<unknown, string> }).annotatingGuards;
+    assert.equal(remembered.has(created.agent.toolResultGuard), false, 'nothing keeps the disposed guard');
+  } finally { await h.framework.stop(); }
+});
+
 test("#281: a file whose copy on disk fails is still in the workspace's tree, and the stub names it", async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]], { autoMaterialize: true });
   // A file where the directory should be: the copy on disk fails for anyone, root included.

From 625a3770e7e4db9d1099252aa79da2131fbbd36b Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Mon, 12 Oct 2026 04:18:54 -0400
Subject: [PATCH 10/16] fix(guard): keep a guard for retries exactly while it
 has work; name the audit record after a branch change; start no stream once
 stop closes admission

From a review of 3532bd0 and a second run of the review workflow over
353d66f..ee7338d.

- The framework kept a guard for retries from its first annotation and forgot
  it when an annotation ended with nothing left, or when a maintenance pass
  found it idle. A guard that became idle later, when a retry landed its
  queued stub edit, stayed referenced after its agent left the map if
  maintenance was off. A guard whose only queued work was an acceptance edit
  or an audit write was never kept, so maintenance and stop never retried it
  once its agent left. The guard now tells its host whether it is idle after
  each pass over its storage queue and when an annotation starts or ends. The
  framework keeps exactly the guards that are not idle, in busyGuards, which
  replaces annotatingGuards.
- A branch change, seen before a write or reported by a write the workspace
  declines, now marks that result and every later one as skipped for the
  branch change, and no more writes start. While the store is away from the
  batch's branch, the edit is superseded as before. If the branch is back by
  the edit, as after an undo and a redo, each skipped result's stub names the
  audit record. Before, those stubs kept the bare notice.
- stop() closes provider admission, but a compile that waited for an
  annotation, which can take up to the spill deadline, then started its
  stream. beginAgentTurn now checks admission at both of its ownership checks.
  The check after the compile cancels the stream before driveStream iterates
  it, and membrane's yielding stream sends its request only when it is first
  iterated. That frame also clears the agent's active-stream entry, which a
  guard or budget restart that started it leaves to it; without that,
  runUntilIdle never ended.
- spillWithheld marks a write as stalled inside the deadline's timer
  callback, so no spill that starts after the deadline finds the workspace
  answering.
- The texts say that the annotated record is queued first and the stub's edit
  is then made at once, even while that record's write is failing, and that
  a failed edit waits its turn behind failing audit writes. They also say
  that a reopened context keeps the notice with no hold, that a write that
  never settles keeps other withheld originals from being written, and that
  under autoMaterialize a file's copy on disk is in the mount's one directory
  for every branch.

Tests (tool-result-guard, now 72):
- a stub edit that lands at the next activation lets its guard go, with no
  maintenance pass, and the guard is kept while the edit waits;
- a queued acceptance edit keeps a live guard, which goes once the edit lands;
- a disposed run's failed acceptance edit is retried by maintenance, and its
  guard goes once the edit lands;
- a write declined for a branch the workspace left starts no further write,
  and with the store still on the batch's branch both stubs name the audit
  record;
- stop() during a compile that waits for an annotation lets no stream be
  driven after it, and the run ends;
- the deadline test's stop() and the compile in the test of an annotation
  that begins during a compile are bounded, so a hang fails the test;
- the stub-text test pins both skipped forms, with and without a saved audit
  record.

Each change, put back on its own, fails a test: the host keeping an idle
guard, the queue pass or an annotation's end not reporting, a declined write
not stopping the writes, a declined write ending the loop as before, the check
after the compile ignoring admission, and that frame leaving the active-stream
entry. Two pass, as expected. Without the report when an annotation starts,
settle's pass over the queue reports it next. Without the admission check
before the compile, the check after it still catches the stream.
---
 .../guard-withheld-names-original.fixed.md    |  35 +++---
 docs/tool-result-guard.md                     |  39 ++++---
 src/framework.ts                              |  86 ++++++++------
 src/tool-result-guard.ts                      |  82 ++++++++-----
 test/tool-result-guard.test.ts                | 110 +++++++++++++++++-
 5 files changed, 250 insertions(+), 102 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 32e8b5a74..db59a5848 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -19,13 +19,14 @@
   tool had done (agent-framework #277). The file is an ordinary workspace
   file: the agent can read it back deliberately, and so can whoever else reads
   the mount, such as another agent sharing it or a synced copy.
-- How the stub is written. Where each original went is recorded first, and the
-  stub's edit is then made at once. If it fails, it is retried before the next
-  activation, compile of a request that is sent, maintenance pass or stop,
-  including for an ephemeral run or a closed fork that has left the agent map,
-  and the batch stays held out of summaries until it lands. Until then, or if
-  the store keeps failing or the process stops first, the stub is the bare
-  notice and the audit record names the file. A file whose copy on disk fails
+- How the stub is written. Where each original went is queued first, as an
+  audit record of its own, and the stub's edit is then made at once. If it
+  fails, it is retried before the next activation, compile of a request that
+  is sent, maintenance pass or stop, including for an ephemeral run or a
+  closed fork that has left the agent map, and the batch stays held out of
+  summaries until it lands. Until then, or if the store keeps failing or the
+  process stops first, the stub is the bare notice, and the `annotated` audit
+  record names the file once its own write has landed. A file whose copy on disk fails
   is still in the workspace's tree, where its tools read it, so the stub names
   it; for this, `WorkspaceModule.writeBinary`'s result for that case carries
   `data: { inChronicle: true }`. A write still under way after 30 seconds, as
@@ -45,15 +46,17 @@
   workspace is up; one that starts after that writes no file and is saved
   before the store closes. A crash before a stub is written leaves the notice
   alone, and the staged audit record still holds the original. If the active
-  branch changes while the originals are being written, no more are written, a
-  write already under way is refused where it commits and recorded as skipped
-  for the branch change, and the stub stays as it was, so no original lands on
-  another branch. For this,
-  `WorkspaceModule.writeBinary` takes an optional `branch`: the file's tree
-  entry lands on that branch or isn't written, and a refused write's result
-  carries `data: { branchLeft: true }` (it isn't traced as a failed spill). A
-  mount has one directory on disk, so with `autoMaterialize` the file's copy
-  there is written like any other write's. The audit records `annotated`
+  branch changes while the originals are being written, no more are written:
+  a write already under way is refused where it commits, and it and the rest
+  are recorded as skipped for the branch change. While the store is away the
+  stub stays as it was; if the branch is back by the edit, those results'
+  stubs name the audit record. So no original's tree entry lands on another
+  branch. For this, `WorkspaceModule.writeBinary` takes an optional `branch`:
+  the file's tree entry lands on that branch or isn't written, and a refused
+  write's result carries `data: { branchLeft: true }` (it isn't traced as a
+  failed spill). A mount has one directory on disk for every branch, so with
+  `autoMaterialize` a file's copy there, made after its tree entry, is there
+  whichever branch is active, like any other write's. The audit records `annotated`
   (where each original went) and `stub_updated` (the stub's edit) carry the
   batch's `sourceBranch`. The direct Agent API's refusal retry is now
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
diff --git a/docs/tool-result-guard.md b/docs/tool-result-guard.md
index 3ab58b2d0..79dd79d7e 100644
--- a/docs/tool-result-guard.md
+++ b/docs/tool-result-guard.md
@@ -91,8 +91,9 @@ context-manager compression hold (`addMessage(..., { holdCompression: true })`,
 context-manager >= 0.12), placed before the strategy's ingress callback runs.
 Every settlement path (accept, withhold, turn-ended, unsubmitted, aborted)
 edits in the final content first and then releases the hold: an accepted
-batch's payload, or a withheld batch's stub, which is edited once its
-originals have been written, so a withheld batch stays held meanwhile.
+batch's payload, or a withheld batch's stub, which is edited once the write
+of each of its originals has ended, written or not, so a withheld batch stays
+held meanwhile.
 Audit-only failures cannot keep a settled message held. If an acceptance
 edit or a stub's edit fails, the guard keeps the content and its hold in a
 separate retry queue; it does not re-arm provider submission or refusal
@@ -125,9 +126,10 @@ the operator's view. Originals in the audit are never edited or removed.
 
 Storage retries are in-memory. If the process dies before storage recovers,
 unsynced records or unfinished edits cannot be promised to survive. Originals
-already made durable remain in Chronicle; reopened context conservatively
-retains any withholding notice whose acceptance edit or stub edit did not
-persist, and an `annotated` record that was saved still names a written file.
+already made durable remain in Chronicle. A reopened context keeps the
+withholding notice of any batch whose acceptance edit or stub edit did not
+persist, with no compression hold, and nothing edits it later; an
+`annotated` record that was saved still names a written file.
 
 A stream that ends without a clean round and without a successor (abort,
 exhausted error retries; also an aborted direct `Agent.runInference`)
@@ -167,7 +169,9 @@ Otherwise the stub names the guard's audit record, for an operator:
   and may finish or fail after the workspace has stopped. Until it settles, no
   other withheld original is written, for any agent; their stubs name the audit
   record, so a stalled mount costs one 30-second wait however many batches
-  queue behind it.
+  queue behind it. Writes already under way when it stalled each run to their
+  own deadline, and a write that never settles keeps the others from being
+  written for the life of the process.
 
 When saving the staged audit record itself had failed as the result arrived,
 the stub says the result went to the audit record "though saving that record
@@ -179,17 +183,21 @@ it, a process, or a synced copy. Withholding keeps the original out of the
 agent's context, not out of its workspace.
 
 If the active branch changes while the originals are being written (a
-rollback, an undo, a host's switch), no more are written, and the stub stays as
-it was. A write already under way names the batch's branch, and the workspace
+rollback, an undo, a host's switch), no more are written, and the rest are
+recorded as skipped for the branch change. While the store is away from the
+batch's branch, the stub stays as it was; if the branch is back by the edit,
+as after an undo and a redo, each skipped result's stub names the audit
+record. A write already under way names the batch's branch, and the workspace
 refuses it where it commits the file (`WorkspaceModule.writeBinary`'s `branch`
-option, whose refusal carries `data: { branchLeft: true }`), so no original
-lands on another branch. With `autoMaterialize`, a mount has one directory on
-disk, and a written file's copy there is written like any other write's.
+option, whose refusal carries `data: { branchLeft: true }`), so no original's
+tree entry lands on another branch. With `autoMaterialize`, a mount has one
+directory on disk for every branch, so a written file's copy there, made after
+its tree entry, is there whichever branch is active, like any other write's.
 
 Two audit records describe it, each with `batchId`, `messageId` and
 `sourceBranch`:
 
-- `annotated`, written first, on its own: one entry in `results` per result.
+- `annotated`, queued first, on its own: one entry in `results` per result.
   `{ toolUseId, path }` is a written file; with `error`, a failed write; with
   `unfinished: true`, a write still under way at the deadline. `{ toolUseId,
   error }` is a write that threw. `{ toolUseId, skipped }` is no write:
@@ -202,8 +210,11 @@ Two audit records describe it, each with `batchId`, `messageId` and
 
 The stub's edit is made at once. If it fails, it waits in the retry queue
 above, and the batch stays held until it lands, so no summary is made of a
-stub that doesn't yet say where its original went; meanwhile the agent's
-requests carry the bare notice, and the `annotated` record names the file.
+stub that doesn't yet say where its original went. Meanwhile a request
+compiled while it is failing, as the refusal retry is, carries the bare
+notice, and the `annotated` record, once saved, names the file. An activation
+or a direct API call retries the queue first, and fails while the edit keeps
+failing, as it does for a failing acceptance edit.
 Every request that is sent is compiled once each annotation started so far
 has finished, including the refusal retry and the seed of a conversation fork
 from its template. A request preview (rollback, undo, redo) doesn't wait, and
diff --git a/src/framework.ts b/src/framework.ts
index cd076e084..1098f3c97 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -2049,8 +2049,8 @@ export class AgentFramework {
 
     // Streams may queue storage repairs while being cancelled above. Retry
     // after their teardown, while the store is still open, before final sync:
-    // every live agent's guard, and every guard that annotated, which an
-    // ephemeral run or a closed fork takes out of the agent map.
+    // every live agent's guard, and every other guard that isn't idle, whose
+    // ephemeral run or closed fork has left the agent map.
     for (const [guard, name] of this.guardsWithStorageWork()) {
       try {
         guard.flushUnrecorded();
@@ -2290,17 +2290,15 @@ export class AgentFramework {
 
   private async runQueuedMaintenance(): Promise<void> {
     // A guard whose agent has left the map gets no activation to retry its
-    // queue; retry it here, and forget it once nothing of it is left.
+    // queue; retry it here. It leaves busyGuards once nothing of it is left.
     const live = new Set([...this.agents.values()].map((agent) => agent.toolResultGuard));
-    for (const [guard, name] of this.annotatingGuards) {
-      if (!live.has(guard)) {
-        try {
-          guard.flushUnrecorded();
-        } catch (error) {
-          console.error(`[tool-result-guard] agent=${name} storage retry failed during maintenance:`, error);
-        }
+    for (const [guard, name] of this.busyGuards) {
+      if (live.has(guard)) continue;
+      try {
+        guard.flushUnrecorded();
+      } catch (error) {
+        console.error(`[tool-result-guard] agent=${name} storage retry failed during maintenance:`, error);
       }
-      if (guard.idle) this.annotatingGuards.delete(guard);
     }
     const queued = [...this.agents.values()].flatMap((agent) => {
       try {
@@ -2733,16 +2731,17 @@ export class AgentFramework {
 
   /** Every guard's annotation still running, for stop() (agent-framework #277). */
   private readonly guardAnnotations = new Set<Promise<void>>();
-  /** Each guard that has annotated, by agent name, until it is idle: an
-   *  ephemeral run or a closed fork leaves the agent map with its annotation
-   *  still running and maybe a stub edit queued, which maintenance and stop
-   *  then retry (agent-framework #277). A guard leaves when an annotation of
-   *  its ends with nothing of it left; one left with queued work stays until
-   *  a maintenance pass finds that work done. */
-  private readonly annotatingGuards = new Map<ToolResultGuard, string>();
+  /** Each guard that isn't idle, by agent name, as the guard reports it. An
+   *  ephemeral run or a closed fork leaves the agent map with an annotation
+   *  maybe still running, or a stub edit, acceptance edit or audit write
+   *  queued, which maintenance and stop then retry (agent-framework #277). A
+   *  guard is here from the moment it has work left until the moment it has
+   *  none, however that comes about. */
+  private readonly busyGuards = new Map<ToolResultGuard, string>();
   /** Withheld originals' writes still under way past their deadline: while
-   *  any is, the workspace isn't answering and no other is started. Several
-   *  can be, when writes of different agents' batches stalled together. */
+   *  any is, the workspace isn't answering and no other withheld original's
+   *  write is started. Several can be, when writes of different agents'
+   *  batches stalled together. */
   private readonly stalledSpills = new Set<Promise<void>>();
   /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
@@ -2767,24 +2766,21 @@ export class AgentFramework {
       spill: (label, text, branch) => this.spillWithheld(label, text, branch),
       track: (annotation) => {
         this.guardAnnotations.add(annotation);
-        this.annotatingGuards.set(guard, agent.name);
-        void annotation.finally(() => {
-          this.guardAnnotations.delete(annotation);
-          // The guard clears its own record of a finished annotation in a
-          // callback it registered before calling track, so `idle` already
-          // counts this one as done.
-          if (guard.idle) this.annotatingGuards.delete(guard);
-        });
+        void annotation.finally(() => this.guardAnnotations.delete(annotation));
+      },
+      idle: (idle) => {
+        if (idle) this.busyGuards.delete(guard);
+        else this.busyGuards.set(guard, agent.name);
       },
     });
   }
 
   /** Each guard that may have queued storage work, once, by agent name: the
-   *  live agents' and those that annotated. */
+   *  live agents' and every other that isn't idle. */
   private guardsWithStorageWork(): Map<ToolResultGuard, string> {
     const guards = new Map<ToolResultGuard, string>();
     for (const agent of this.agents.values()) guards.set(agent.toolResultGuard, agent.name);
-    for (const [guard, name] of this.annotatingGuards) if (!guards.has(guard)) guards.set(guard, name);
+    for (const [guard, name] of this.busyGuards) if (!guards.has(guard)) guards.set(guard, name);
     return guards;
   }
 
@@ -9433,9 +9429,10 @@ export class AgentFramework {
         injections = injections ? [...injections, silentInjection] : [silentInjection];
       }
 
-      // An ephemeral watchdog may dispose this Agent while hooks/compile await.
-      // Do not create a provider stream after its generation lost ownership.
-      if (this.agents.get(agent.name) !== agent) {
+      // An ephemeral watchdog may dispose this Agent while hooks/compile await,
+      // and stop() may close provider admission. Do not create a provider
+      // stream after its generation lost ownership, or once admission closed.
+      if (this.agents.get(agent.name) !== agent || this.providerAdmissionClosed) {
         this.channelRegistry?.stopTyping();
         this.eventGate?.onInferenceEnded(agent.name);
         return false;
@@ -9460,9 +9457,20 @@ export class AgentFramework {
       } = await agent.startStreamWithInjections(tools, injections, undefined, compressionTools, {
         silentHeartbeat: trigger?.silentHeartbeat,
       });
-      if (this.agents.get(agent.name) !== agent) {
+      // The compile can wait for a withheld batch's annotation, up to the
+      // spill deadline (see ToolResultGuard.afterAnnotations), so check both
+      // again. Membrane's yielding stream starts its request when it is first
+      // iterated, so cancelling it here, before driveStream, sends nothing.
+      if (this.agents.get(agent.name) !== agent || this.providerAdmissionClosed) {
         stream.cancel();
         agent.cancelStream();
+        if (this.agents.get(agent.name) === agent) {
+          // The compile took the agent's stream id, so a frame that started
+          // this one (a guard or budget restart) no longer owns the entries
+          // it left, and its teardown leaves them to this frame.
+          this.activeStreams.delete(agent.name);
+          this.pendingAssistantBlocks.delete(agent.name);
+        }
         this.channelRegistry?.stopTyping();
         this.eventGate?.onInferenceEnded(agent.name);
         return false;
@@ -11824,7 +11832,13 @@ export class AgentFramework {
     const write = this.writeToolResultFile(label, text, branch);
     let timer: ReturnType<typeof setTimeout> | undefined;
     const late = new Promise<'late'>((resolve) => {
-      timer = setTimeout(() => resolve('late'), this.withheldSpillDeadlineMs);
+      timer = setTimeout(() => {
+        // Marked as the deadline passes, before anything else runs, so no
+        // spill that starts after it finds the workspace answering.
+        const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => this.stalledSpills.delete(stalled));
+        this.stalledSpills.add(stalled);
+        resolve('late');
+      }, this.withheldSpillDeadlineMs);
       timer.unref?.();
     });
     try {
@@ -11834,8 +11848,6 @@ export class AgentFramework {
         if (written.branchLeft) return { skipped: 'branch_changed' };
         return { path: written.path, ...(written.error !== undefined ? { error: written.error } : {}) };
       }
-      const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => this.stalledSpills.delete(stalled));
-      this.stalledSpills.add(stalled);
       return { path: place.path, unfinished: true };
     } finally {
       clearTimeout(timer);
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 874d44c72..2f08e3493 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -34,11 +34,18 @@ export type WithheldSpill =
 export type WithheldSpiller = (label: string, text: string, branch: string) => Promise<WithheldSpill>;
 
 /** What a host gives a guard for its withheld results: where originals are
- *  written, and where each annotation is registered, so the host's stop can
- *  wait for it even after the agent itself was disposed. */
+ *  written, where each annotation is registered, so the host's stop can
+ *  wait for it even after the agent itself was disposed, and where the
+ *  guard says whether it has work left. */
 export interface WithheldHost {
   spill: WithheldSpiller;
   track(annotation: Promise<void>): void;
+  /** Whether the guard is idle (see ToolResultGuard.idle), told after each
+   *  change that can alter it: when an annotation starts or ends, and after
+   *  each pass over the storage queue. A host keeps a guard that isn't idle
+   *  within reach for retries, whatever has become of its agent, and lets
+   *  an idle one go. */
+  idle(idle: boolean): void;
 }
 
 /**
@@ -198,18 +205,23 @@ export class ToolResultGuard {
    * hold here; it can never re-arm refusal handling or tool submission. */
   private unrecorded: AuditOperation[] = [];
 
-  /** Retry edits and audit writes before a new activation, audit write,
-   * maintenance pass, or shutdown. A failed operation stays at the head. */
+  /** Retry edits and audit writes before a new activation, a compile of a
+   * request that is sent (afterAnnotations), an audit write, a maintenance
+   * pass, or shutdown. A failed operation stays at the head. */
   flushUnrecorded(): void {
-    while (this.unrecorded.length > 0) {
-      const operation = this.unrecorded[0];
-      try {
-        this.applyEdit(operation);
-        this.write(operation.record);
-        this.unrecorded.shift();
-      } finally {
-        if (!operation.admission) this.releaseOperationHold(operation);
+    try {
+      while (this.unrecorded.length > 0) {
+        const operation = this.unrecorded[0];
+        try {
+          this.applyEdit(operation);
+          this.write(operation.record);
+          this.unrecorded.shift();
+        } finally {
+          if (!operation.admission) this.releaseOperationHold(operation);
+        }
       }
+    } finally {
+      this.host?.idle(this.idle);
     }
   }
 
@@ -440,10 +452,11 @@ export class ToolResultGuard {
    * the only thing it edits: an operator's later edit, removal or rollback
    * stands.
    *
-   * Where each original went is recorded first, on its own ('annotated'), so
+   * Where each original went is queued first, on its own ('annotated'), so
    * a stub edit that fails can't take the record of a written file with it.
-   * The edit is made at once, so no storage work queued ahead of it holds it,
-   * and its record ('stub_updated') is written in order after the others. An
+   * The edit is then made at once, so no storage work queued ahead of it
+   * holds it, not even that record if its write is failing, and its record
+   * ('stub_updated') is written in order after the others. An
    * edit that fails joins the ordered storage queue like an admission's, with
    * the batch's compression hold: retried before the next activation, compile,
    * maintenance pass or stop until it lands or an operator's change supersedes
@@ -470,15 +483,22 @@ export class ToolResultGuard {
         const spills = new Map<number, WithheldSpill>();
         // A spill that threw, by index: its error, for the record.
         const thrown = new Map<number, string>();
+        // Set once the branch has changed: no more is written.
+        let branchLeft = false;
         for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
           // Once the store has left the batch's branch (a rollback, an undo, a
-          // host's switch), the stub below stays as it is: write no more.
-          // Nothing yields between this break and the edit's own branch check,
-          // so a batch whose writes stopped is never edited. A write already
-          // under way when the branch changes is refused where it commits,
-          // since it names the batch's branch, so no file lands elsewhere.
-          if (this.cm.currentBranch().name !== pending.branch) break;
+          // host's switch), write no more. This result and every later one is
+          // skipped, and its original stays in the audit record. Nothing
+          // yields from here to the edit's own branch check, so while the
+          // store is away the stub stays as it is. A write already under way
+          // when the branch changes is refused where it commits, since it
+          // names the batch's branch, so no file lands elsewhere.
+          if (branchLeft || this.cm.currentBranch().name !== pending.branch) {
+            branchLeft = true;
+            spills.set(index, { skipped: 'branch_changed' });
+            continue;
+          }
           // The result as stored. Both paths that store a tool result store
           // its text; content stored as blocks would be written as their JSON.
           const original = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
@@ -495,13 +515,14 @@ export class ToolResultGuard {
             }
           }
           // Declined where it would have committed, since the workspace had
-          // left the batch's branch: nothing was written, and no more are, as
-          // for the results the branch check above stops.
-          if (spill && 'skipped' in spill && spill.skipped === 'branch_changed') break;
+          // left the batch's branch. Nothing was written, and no more are, as
+          // for the results the branch check above stops. If the branch is
+          // back by the edit, as after an undo and a redo, the stubs of this
+          // result and the later ones name the audit record.
+          if (spill && 'skipped' in spill && spill.skipped === 'branch_changed') branchLeft = true;
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
-          && spills.has(index)
           ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable) }
           : block);
         try {
@@ -509,12 +530,11 @@ export class ToolResultGuard {
             type: 'annotated', batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch,
             results: pending.content.flatMap((block, index): Array<Record<string, string | true>> => {
               if (block.type !== 'tool_result') return [];
-              if (!spills.has(index)) return [{ toolUseId: block.toolUseId, skipped: 'branch_changed' }];
               if (thrown.has(index)) return [{ toolUseId: block.toolUseId, error: thrown.get(index)! }];
-              const spill = spills.get(index);
+              const spill = spills.get(index) ?? null;
               // No file was written: no writable workspace, or the framework
               // was stopping.
-              if (spill === null || spill === undefined) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
+              if (spill === null) return [{ toolUseId: block.toolUseId, skipped: 'no_workspace_file' }];
               if ('skipped' in spill) return [{ toolUseId: block.toolUseId, skipped: spill.skipped }];
               return [{ toolUseId: block.toolUseId, path: spill.path,
                 ...(spill.error !== undefined ? { error: spill.error } : {}),
@@ -562,8 +582,12 @@ export class ToolResultGuard {
       }
     });
     this.annotating = run;
-    void run.finally(() => { if (this.annotating === run) this.annotating = undefined; });
+    void run.finally(() => {
+      if (this.annotating === run) this.annotating = undefined;
+      this.host?.idle(this.idle);
+    });
     this.host?.track(run);
+    this.host?.idle(false);
   }
 
   private releaseOperationHold(operation: AuditOperation): void {
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index ef667ddd0..668f80f17 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -838,10 +838,13 @@ test('storage recovery: failed accepted edit is retried before the next activati
     assert.equal(cm.getCompressionHolds().size, 1, 'keep provisional history out of compression until repaired');
     assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
     assert.throws(() => agent.toolResultGuard.flushUnrecorded(), /injected edit failure/);
+    const busy = (h.framework as unknown as { busyGuards: Map<unknown, string> }).busyGuards;
+    assert.equal(busy.has(agent.toolResultGuard), true, 'a queued acceptance edit keeps the guard within reach');
     failing = false;
     await h.run();
     assert.match(JSON.stringify(h.membrane.requests[1]), /payload-one/, 'next activation must see the accepted result');
     assert.equal(cm.getCompressionHolds().size, 0);
+    assert.equal(busy.has(agent.toolResultGuard), false, 'and the guard is let go once it lands');
     const records = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
     assert.equal(records.filter((r) => r.type === 'accepted').length, 1);
     assert.deepEqual(h.module.calls, ['one']);
@@ -1167,7 +1170,7 @@ test("#277: an operator's edit made before the stub is annotated stands, and the
     let release!: () => void;
     const gate = new Promise<void>((resolve) => { release = resolve; });
     let entered = false;
-    r.guard.setHost({ spill: async () => { entered = true; await gate; return null; }, track: () => {} });
+    r.guard.setHost({ spill: async () => { entered = true; await gate; return null; }, track: () => {}, idle: () => {} });
     r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
     assert.ok(r.guard.withhold('test-category'));
     for (let i = 0; i < 100 && !entered; i++) await new Promise((resolve) => setTimeout(resolve, 10));
@@ -1241,6 +1244,11 @@ test('#277: the stub has the same text for each place the original can be', () =
   assert.equal(withheldResultNotice(null, false), `${notice} Its result went to ${unsaved}.`);
   assert.equal(withheldResultNotice(null, true), AUDIT_STUB);
   assert.equal(withheldResultNotice(null, false), UNSAVED_STUB);
+  // A skipped write reads as no write at all.
+  for (const skipped of ['workspace_unanswered', 'branch_changed'] as const) {
+    assert.equal(withheldResultNotice({ skipped }, true), AUDIT_STUB);
+    assert.equal(withheldResultNotice({ skipped }, false), UNSAVED_STUB);
+  }
 });
 
 test('#277: direct API: a request after an aborted batch is compiled once its stub is annotated', async () => {
@@ -1547,7 +1555,7 @@ test('#281: a write still under way at the deadline is named as unfinished, and
     const annotated = audit.find((record) => record.type === 'annotated') as { results: Array<Record<string, unknown>> };
     assert.equal(annotated.results[0].unfinished, true);
     assert.deepEqual(annotated.results[1], { toolUseId: 'two', skipped: 'workspace_unanswered' });
-    await h.framework.stop();
+    await bounded(h.framework.stop(), 'stop, with the write still stalled');
     stopped = true;
     assert.equal(writes, 1, 'stop finished with the write still stalled');
   } finally { stalled.open(); if (!stopped) await h.framework.stop(); }
@@ -1592,12 +1600,16 @@ test("#281: a stub edit that keeps failing leaves the record of the written file
     assert.deepEqual(retried.map((b) => b.content), [TOOL_RESULT_GUARD_NOTICE], 'the retry went out with the store still failing');
     assert.equal(audit().some((record) => record.type === 'stub_updated'), false, 'the edit is still queued');
     assert.equal(cm.getCompressionHolds().size, 1, 'and still holds the batch out of summaries');
+    const guard = h.framework.getAgent('assistant')!.toolResultGuard;
+    const busy = (h.framework as unknown as { busyGuards: Map<unknown, string> }).busyGuards;
+    assert.equal(busy.has(guard), true, 'the framework keeps the guard within reach while its edit waits');
     failing = false;
     await h.run();
     assert.equal(toolResults(h.framework)[0].content, `${TOOL_RESULT_GUARD_NOTICE} Its result is in workspace file ${path}.`);
     assert.equal(audit().at(-1)?.type, 'stub_updated');
     assert.equal(audit().at(-1)?.historyUpdate, undefined);
     assert.equal(cm.getCompressionHolds().size, 0, 'released once it landed');
+    assert.equal(busy.has(guard), false, 'and lets it go once the edit lands, with no maintenance pass');
   } finally { write.open(); await h.framework.stop(); }
 });
 
@@ -1666,7 +1678,7 @@ test('#281: a compile waits for an annotation that began while it waited for ano
       entered++;
       await (entered === 1 ? first.opened : second.opened);
       return null;
-    }, track: () => {} });
+    }, track: () => {}, idle: () => {} });
     r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
     assert.ok(r.guard.withhold('test-category'));
     await until(() => entered === 1, 'the first annotation is writing');
@@ -1684,7 +1696,7 @@ test('#281: a compile waits for an annotation that began while it waited for ano
     await until(() => entered === 2, 'the second annotation is writing');
     assert.equal(reads, 0, 'the compile waits for it too');
     second.open();
-    assert.deepEqual(await compiled, [AUDIT_STUB, AUDIT_STUB]);
+    assert.deepEqual(await bounded(compiled, 'the compile'), [AUDIT_STUB, AUDIT_STUB]);
     assert.equal(reads, 1);
   } finally { r.cm.close(); }
 });
@@ -1736,6 +1748,44 @@ test("#281: a disposed run's failed stub edit is retried by maintenance and at s
   } finally { if (!stopped) await h.framework.stop(); }
 });
 
+test("#281: a disposed run's failed acceptance edit is retried by maintenance, and its guard is let go once it lands", async () => {
+  const h = await harness([[calls('one'), answer()]]);
+  const maintain = () => (h.framework as unknown as { runQueuedMaintenance(): Promise<void> }).runQueuedMaintenance();
+  const busy = (h.framework as unknown as { busyGuards: Map<unknown, string> }).busyGuards;
+  try {
+    const created = await h.framework.createEphemeralAgent({
+      name: 'ephemeral', model: 'test', systemPrompt: 'system', toolResultGuard: true,
+    });
+    const cm = created.contextManager as unknown as { editMessage: (id: unknown, content: ContentBlock[]) => unknown };
+    const edit = cm.editMessage.bind(cm);
+    let failing = true;
+    let attempts = 0;
+    cm.editMessage = (id, content) => {
+      if (JSON.stringify(content).includes('payload-one')) {
+        attempts++;
+        if (failing) throw new Error('injected acceptance edit failure');
+      }
+      return edit(id, content);
+    };
+    created.contextManager.addMessage('user', [{ type: 'text', text: 'read' }]);
+    const completion = h.framework.runEphemeralToCompletion(created.agent, created.contextManager);
+    h.framework.start();
+    await bounded(completion, 'the ephemeral run');
+    const guard = created.agent.toolResultGuard;
+    assert.equal(h.framework.getAgent('ephemeral') ?? null, null, 'the run was disposed');
+    assert.equal(guard.idle, false, 'with its acceptance edit queued');
+    assert.equal(busy.has(guard), true, 'which keeps its guard within reach');
+    const before = attempts;
+    await maintain();
+    assert.ok(attempts > before, "maintenance retries the disposed run's acceptance edit");
+    assert.equal(busy.has(guard), true, 'and keeps the guard while the edit fails');
+    failing = false;
+    await maintain();
+    assert.equal(guard.idle, true, 'the edit landed');
+    assert.equal(busy.has(guard), false, 'and the guard is let go');
+  } finally { await h.framework.stop(); }
+});
+
 test('#281: batches behind one stalled write cost one deadline: no write starts until it settles', async () => {
   const h = await workspaceHarness([
     [calls('one'), refused()], [answer()],
@@ -1772,6 +1822,54 @@ test('#281: batches behind one stalled write cost one deadline: no write starts
   } finally { stalled.open(); await h.framework.stop(); }
 });
 
+test('#281: a write declined for a branch the workspace left stops the writes, and a stub edited after the branch came back names the audit record', async () => {
+  const h = await workspaceHarness([[calls('one', 'two'), refused()], [answer()]]);
+  let writes = 0;
+  // Declined where it commits, as when the branch changed while the write was
+  // under way; the store is back on the batch's branch by the time it ends,
+  // as after an undo and a redo.
+  (h.framework as unknown as { writeToolResultFile: () => Promise<unknown> }).writeToolResultFile = async () => {
+    writes++;
+    return { path: 'work/tool-results/declined.txt', branchLeft: true };
+  };
+  try {
+    await bounded(h.run(), 'the run');
+    assert.equal(writes, 1, 'no write starts after the decline');
+    assert.deepEqual(toolResults(h.framework).map((block) => block.content), [AUDIT_STUB, AUDIT_STUB]);
+    const audit = h.framework.getStore().getStateJson(TOOL_RESULT_GUARD_AUDIT_STATE) as Array<Record<string, unknown>>;
+    const annotated = audit.find((record) => record.type === 'annotated') as { results: Array<Record<string, unknown>> };
+    assert.deepEqual(annotated.results, [
+      { toolUseId: 'one', skipped: 'branch_changed' },
+      { toolUseId: 'two', skipped: 'branch_changed' },
+    ]);
+  } finally { await h.framework.stop(); }
+});
+
+test('#281: stop during a compile that waits for an annotation lets no provider stream start after it', async () => {
+  const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
+  const framework = h.framework as unknown as { writeToolResultFile: (...args: unknown[]) => Promise<unknown> };
+  const writeFile = framework.writeToolResultFile.bind(h.framework);
+  const write = gate();
+  framework.writeToolResultFile = async (...args) => { await write.opened; return writeFile(...args); };
+  const compiles = watchCompiles(h.framework);
+  const traces: string[] = [];
+  h.framework.onTrace((event) => traces.push((event as { type: string }).type));
+  let stopped = false;
+  try {
+    const running = h.run();
+    await until(() => compiles.calls === 2, 'the refusal retry waits for the stub');
+    const stopping = h.framework.stop();
+    write.open();
+    await bounded(stopping, 'stop');
+    stopped = true;
+    // Nothing is left to drive, so the run ends too: the refused stream's
+    // entry went with the retry it started.
+    await bounded(running, 'the run');
+    assert.equal(h.membrane.requests.length, 2, 'the retry was compiled once its stub was written');
+    assert.equal(traces.includes('inference:completed'), false, 'but, compiled after stop began, it was never driven');
+  } finally { write.open(); if (!stopped) await h.framework.stop(); }
+});
+
 test('#281: writes that stalled together each hold the workspace as unanswered until it settles', async () => {
   const h = await workspaceHarness([]);
   const framework = h.framework as unknown as {
@@ -1827,7 +1925,7 @@ test("#281: a disposed run's guard is forgotten once its annotation ends with no
     await new Promise((resolve) => setImmediate(resolve));
     assert.equal(h.framework.getAgent('ephemeral') ?? null, null, 'the run was disposed');
     assert.equal(created.agent.toolResultGuard.idle, true);
-    const remembered = (h.framework as unknown as { annotatingGuards: Map<unknown, string> }).annotatingGuards;
+    const remembered = (h.framework as unknown as { busyGuards: Map<unknown, string> }).busyGuards;
     assert.equal(remembered.has(created.agent.toolResultGuard), false, 'nothing keeps the disposed guard');
   } finally { await h.framework.stop(); }
 });
@@ -1887,7 +1985,7 @@ test('#281: a compile during which an annotation began is compiled again once it
   try {
     const write = gate();
     let entered = false;
-    r.guard.setHost({ spill: async () => { entered = true; await write.opened; return null; }, track: () => {} });
+    r.guard.setHost({ spill: async () => { entered = true; await write.opened; return null; }, track: () => {}, idle: () => {} });
     r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
     let reads = 0;
     const stub = () => (r.cm.getMessage(r.messageId)!.content[0] as { content: unknown }).content;

From 12c52b4a2a39c77e106d78c26116fc1acba2693f Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Mon, 12 Oct 2026 04:53:03 -0400
Subject: [PATCH 11/16] docs(guard): a withheld batch's stub waits for the
 host's report on each original, not for every write to end

The guide said a withheld batch's stub is edited once the write of each of
its originals has ended. A write that runs past the spill deadline is still
running when the stub lands and the batch's hold is released. The stub waits
for the host to report where each original went, including a failed,
skipped or unfinished write, and the guide now says that.
---
 docs/tool-result-guard.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/tool-result-guard.md b/docs/tool-result-guard.md
index 79dd79d7e..ac1094d1e 100644
--- a/docs/tool-result-guard.md
+++ b/docs/tool-result-guard.md
@@ -91,9 +91,9 @@ context-manager compression hold (`addMessage(..., { holdCompression: true })`,
 context-manager >= 0.12), placed before the strategy's ingress callback runs.
 Every settlement path (accept, withhold, turn-ended, unsubmitted, aborted)
 edits in the final content first and then releases the hold: an accepted
-batch's payload, or a withheld batch's stub, which is edited once the write
-of each of its originals has ended, written or not, so a withheld batch stays
-held meanwhile.
+batch's payload, or a withheld batch's stub, which is edited once the host
+has reported where each of its originals went, including a failed, skipped
+or unfinished write, so a withheld batch stays held meanwhile.
 Audit-only failures cannot keep a settled message held. If an acceptance
 edit or a stub's edit fails, the guard keeps the content and its hold in a
 separate retry queue; it does not re-arm provider submission or refusal

From 5eb7d19624722a8b9e4d52c0c642cb6b8bab7555 Mon Sep 17 00:00:00 2001
From: Sebastian-2380 <sebastian-2380@commons.astra.invalid>
Date: Tue, 13 Oct 2026 02:19:00 -0400
Subject: [PATCH 12/16] fix(guard): bound withheld batches and retain request
 ownership

Give each withheld batch one deadline for its workspace writes. Later writes use the remaining time, and an exhausted batch starts no new file. Report the deadline and unanswered skips on stderr; preserve the existing gate until every overdue write settles. The inline cap's spill remains outside this bound.

Keep compilation ownership separate from the public agent status. Both inference entry points refuse overlapping starts, and the scheduler uses isCompilingRequest to retain a wake during a direct call's compile. Release ownership on assembly failure while preserving ready results. Read unguarded results after compilation, and check the abort signal after the direct refusal retry's annotation wait.

Invalidate framework turns that compile across stop with a lifecycle generation, and reopen withheld spills when the framework restarts. Once writeBinary sets its tree entry, report inChronicle even if later work throws. Both inline spill notes and withheld stubs name that readable file while tracing its failed disk copy. save_recent_image counts it as saved and includes the disk-copy error in its receipt.

Add regressions for these contracts, including exact virtual-time checks of the per-batch deadline and actual stream iteration after stop. Pin the annotation exception's hold release and retain existing tests for disk-copy failures and concurrent stalled writes. Clarify the operator guide and changelog about queued storage failures, unfinished audit records, branch-local tree entries, previews, and the scope of lifecycle and deadline guarantees.

Validation on Linux: build and typecheck; 293 focused tests passed across tool-result-guard, save-recent-image, workspace-three-way, and silent-heartbeat-rows. The subsequent 15-test round-specific guard run passed, including the added pre-aborted-call check. Before the fixes, nine of the first eleven guard regressions failed on behavior, with two controls passing; both image receipt regressions failed too. Full runtime suites and independent piece removals follow on this committed tree.

Co-authored-by: GPT-6 <noreply@openai.com>
---
 .../guard-withheld-names-original.fixed.md    |  22 +-
 docs/tool-result-guard.md                     |  36 +-
 src/agent.ts                                  | 217 ++++++-----
 src/framework.ts                              |  73 ++--
 src/modules/workspace/index.ts                |  16 +-
 src/tool-result-guard.ts                      |  50 +--
 test/save-recent-image.test.ts                |  42 +++
 test/tool-result-guard.test.ts                | 356 +++++++++++++++++-
 8 files changed, 629 insertions(+), 183 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index db59a5848..87ca1da61 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -26,29 +26,23 @@
   closed fork that has left the agent map, and the batch stays held out of
   summaries until it lands. Until then, or if the store keeps failing or the
   process stops first, the stub is the bare notice, and the `annotated` audit
-  record names the file once its own write has landed. A file whose copy on disk fails
+  record describes the spill's outcome when the annotation finishes, with `unfinished` for a write still running. That record is not revised when the write later settles. A file whose copy on disk fails
   is still in the workspace's tree, where its tools read it, so the stub names
   it; for this, `WorkspaceModule.writeBinary`'s result for that case carries
-  `data: { inChronicle: true }`. A write still under way after 30 seconds, as
-  on a stalled mount, is named as unfinished, with the audit record as the
-  fallback. Nothing waits for it after that, stop included: it goes on by
+  `data: { inChronicle: true }`, including when a post-commit operation throws. Inline truncation notes also name that readable tree file, and the disk-copy failure is logged and traced. Each batch has one 30-second deadline for all its withheld writes. A write still under way then is named as unfinished, with the audit record as the fallback. Nothing waits for it after that, stop included: it goes on by
   itself, and may finish or fail after the workspace has stopped. Until it
   settles, no other withheld original is written, for this batch or a later
-  one of any agent: their stubs name the audit record, so a stalled workspace
-  costs one 30-second wait however many batches queue behind it, and can't
-  hold the agent's requests or the framework's stop. Every request that is
-  sent is compiled only once each annotation started so far has finished,
+  one of any agent: their stubs name the audit record. Writes can start before the first deadline fires; those batches each use their own deadline. A write that never settles keeps new withheld spills disabled for the process lifetime. Deadline and skip messages name affected files on stderr. The inline cap's spills are outside this deadline. Requests sent by the framework and the direct Agent API are compiled only once each annotation started so far has finished,
   including one that began while the compile waited or ran, and the refusal
   retry; a conversation fork seeded from its template copies only stubs whose
   annotation has finished. A request preview doesn't wait, so rollback,
   undo and redo never wait on a workspace write, and a preview can show a stub
-  before its place is added. Stop lets running annotations finish while the
+  before its place is added, as can public `compileContext()`. Stop lets running annotations finish while the
   workspace is up; one that starts after that writes no file and is saved
   before the store closes. A crash before a stub is written leaves the notice
   alone, and the staged audit record still holds the original. If the active
   branch changes while the originals are being written, no more are written:
-  a write already under way is refused where it commits, and it and the rest
-  are recorded as skipped for the branch change. While the store is away the
+  a write that has not set its tree entry is refused where it commits, and it and the rest are recorded as skipped for the branch change. A write whose tree entry was already set remains on that branch. While the store is away the
   stub stays as it was; if the branch is back by the edit, those results'
   stubs name the audit record. So no original's tree entry lands on another
   branch. For this, `WorkspaceModule.writeBinary` takes an optional `branch`:
@@ -60,3 +54,9 @@
   (where each original went) and `stub_updated` (the stub's edit) carry the
   batch's `sourceBranch`. The direct Agent API's refusal retry is now
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
+
+- With `maintenanceIntervalMs: 0`, periodic retries of retained guards are disabled; stop still retries them. A failing audit record blocks later queued edits and their compression holds until its write succeeds. Shutdown reports an error if that retry still fails.
+- A framework-driven turn that compiled across stop is discarded before driving its stream, even if the framework has restarted. Restart reopens withheld spills. Direct Agent calls remain governed by their caller's abort signal; a refusal retry checks that signal again after waiting for annotations. Unguarded results are read after compilation, including on the retry.
+- `save_recent_image` reports a tree-only write as saved, including its path, size, MIME type, and `diskCopyError`. A later failure in a multi-image save includes that file among the already-saved paths.
+
+- `Agent.isCompilingRequest` is a read-only getter for the framework scheduler to keep a queued wake while request assembly owns the agent. Both direct and streaming entry points reject overlapping starts, and a failed compile releases that ownership. Existing public status values and request previews are unchanged.
diff --git a/docs/tool-result-guard.md b/docs/tool-result-guard.md
index ac1094d1e..1f22c89b9 100644
--- a/docs/tool-result-guard.md
+++ b/docs/tool-result-guard.md
@@ -94,7 +94,7 @@ edits in the final content first and then releases the hold: an accepted
 batch's payload, or a withheld batch's stub, which is edited once the host
 has reported where each of its originals went, including a failed, skipped
 or unfinished write, so a withheld batch stays held meanwhile.
-Audit-only failures cannot keep a settled message held. If an acceptance
+Once a history edit succeeds, its own audit-only failure does not retain that message's hold. If an acceptance
 edit or a stub's edit fails, the guard keeps the content and its hold in a
 separate retry queue; it does not re-arm provider submission or refusal
 handling. Compression sees only the settled message: accepted output, or a
@@ -117,6 +117,9 @@ Failed edits and audit writes are retried in order before the next real
 activation, compile of a request that is sent, or guard audit write, during
 maintenance, and after stream teardown at shutdown, including those of an
 ephemeral run or a closed conversation fork that has left the agent map.
+
+With `maintenanceIntervalMs: 0`, periodic retries are disabled; stop still retries retained guards. The queue is ordered: a failing audit write blocks later queued history edits and their compression holds until the write succeeds. Shutdown retries the same queue and reports an error if it still fails.
+
 Previews do not flush the queue. A history edit is retried only on its
 original branch and only if the message still contains the guard's
 placeholder or the content the edit writes; later operator edits, removals,
@@ -162,16 +165,11 @@ Otherwise the stub names the guard's audit record, for an operator:
 - when the write failed: "Writing its result to workspace file … failed, so it
   is kept only in the guard's audit record …". The error itself stays in the
   audit record and the logs;
-- when the write was still under way after 30 seconds, as on a stalled mount:
-  "Its result was still being written to workspace file … when this note was
-  made; if that file is missing, it is kept in the guard's audit record …".
-  Nothing waits for that write after that, stop included: it goes on by itself
-  and may finish or fail after the workspace has stopped. Until it settles, no
-  other withheld original is written, for any agent; their stubs name the audit
-  record, so a stalled mount costs one 30-second wait however many batches
-  queue behind it. Writes already under way when it stalled each run to their
-  own deadline, and a write that never settles keeps the others from being
-  written for the life of the process.
+- when the write is still under way at its batch's deadline: "Its result was still being written to workspace file … when this note was made; if that file is missing, it is kept in the guard's audit record …".
+
+Each batch has one 30-second deadline, starting when its annotation begins. Each successive write uses the remaining time. Once the deadline passes, the request can carry the unfinished-write notice; later results in the batch name the audit record. The underlying write continues independently, including after stop, and may finish or fail later. A deadline that fires logs the file's path to stderr. While any write remains overdue, new withheld spills are skipped as `workspace_unanswered` and logged. A write that never settles keeps that gate closed for the process lifetime. Other batches can start writes before the first deadline fires, and each such batch uses its own deadline. This bound covers withheld spills; the inline cap's original spill has no deadline.
+
+A file whose tree entry was set is readable through the workspace's tools even if its disk copy fails or throws. `WorkspaceModule.writeBinary` reports `data: { inChronicle: true }` for that outcome. Both withheld stubs and inline truncation notes name the tree file, while stderr and `tool:spill_failed` report the disk-copy failure. `save_recent_image` also counts that file as saved, with its path, size, MIME type, and `diskCopyError` in the saved receipt.
 
 When saving the staged audit record itself had failed as the result arrived,
 the stub says the result went to the audit record "though saving that record
@@ -203,8 +201,9 @@ Two audit records describe it, each with `batchId`, `messageId` and
   error }` is a write that threw. `{ toolUseId, skipped }` is no write:
   `no_workspace_file` (no writable workspace, or the framework was stopping),
   `workspace_unanswered` (an earlier write was still under way past its
-  deadline) or `branch_changed` (the branch changed before or while it was
-  written).
+  deadline), `batch_deadline` (the batch had no time left to start another write), or `branch_changed` (the workspace declined the write before its tree entry was set).
+
+The `annotated` record describes what each spill reported when the batch's annotation finished. An `unfinished` entry is not updated when the underlying write later settles.
 - `stub_updated`: the stub's edit, with `historyUpdate: "superseded"` when an
   operator's edit, removal, rollback or branch change came first.
 
@@ -215,12 +214,11 @@ compiled while it is failing, as the refusal retry is, carries the bare
 notice, and the `annotated` record, once saved, names the file. An activation
 or a direct API call retries the queue first, and fails while the edit keeps
 failing, as it does for a failing acceptance edit.
-Every request that is sent is compiled once each annotation started so far
-has finished, including the refusal retry and the seed of a conversation fork
-from its template. A request preview (rollback, undo, redo) doesn't wait, and
-can show a stub before its place is added. At stop, the framework lets
-running annotations finish while the workspace is up; one that starts after
-that writes no file and is saved before the store closes.
+Requests sent by the framework or the direct Agent inference API are compiled after the guard's annotations finish, including the refusal retry. A conversation fork also waits before compiling its template's seed. A preview, including public `compileContext()`, does not wait and can show a stub before its place is added.
+
+During real request assembly, a private compilation mark prevents overlapping direct and streaming starts. The read-only `Agent.isCompilingRequest` getter lets the framework scheduler keep a queued wake until compilation ends. The public status values stay unchanged. An assembly failure releases that ownership; ready tool results remain available for another attempt. The direct API reads unguarded results after each compile and checks an abort signal again after the refusal retry's annotation wait.
+
+At stop, the framework lets running annotations finish while the workspace is up. An annotation that starts after that drain writes no file and is saved before the store closes. A framework-driven turn that compiled across stop is discarded before its stream is driven, even if the same framework has since restarted. Restart reopens withheld spills. These lifecycle gates cover framework-driven turns; direct Agent calls use their caller's abort signal.
 
 For example, an operator can inspect records without changing the agent's
 view:
diff --git a/src/agent.ts b/src/agent.ts
index 20985052f..6ba2354e5 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -113,6 +113,8 @@ export class Agent {
   readonly sameRoundThinkTextPolicy: AgentConfig['sameRoundThinkTextPolicy'];
 
   private _state: AgentState = { status: 'idle' };
+  /** Owns request assembly while retaining any ready tool results underneath. */
+  private compilingRequest = false;
   private _inferenceStartedAt = 0;
   private _streamId = 0;
   /** kv-unified receipt flights opened by the CURRENT activation and not yet
@@ -186,6 +188,11 @@ export class Agent {
     return this._state;
   }
 
+  /** The framework scheduler keeps a wake queued while this agent is
+   * assembling a request. This is compilation ownership, not a replacement
+   * for the agent's public status. */
+  get isCompilingRequest(): boolean { return this.compilingRequest; }
+
   /**
    * Monotonically increasing stream generation counter.
    * Used to guard stale driveStream handlers after a budget restart.
@@ -646,6 +653,9 @@ export class Agent {
     budget?: TokenBudget,
     options?: InferenceOptions
   ): Promise<InferenceResult> {
+    if (this.compilingRequest || this._state.status === 'streaming') {
+      throw new Error(`Agent ${this.name} cannot run inference in state ${this.compilingRequest ? 'compiling' : this._state.status}`);
+    }
     if (this._state.status === 'inferring') {
       throw new Error(`Agent ${this.name} is already inferring`);
     }
@@ -670,10 +680,6 @@ export class Agent {
       this.toolResultGuard.storeResults(content, wireResults, this._state.toolResults);
     }
 
-    // Pending tool results the guard isn't holding follow the compiled context.
-    const unguardedResults = this._state.status === 'ready' && !guardedResults
-      ? this.buildToolResultMessages(this._state.toolResults) : [];
-
     // Compile the context (with optional injections) into a request. The
     // guard's refusal retry is assembled the same way, afresh. It is compiled
     // only once each withheld stub's annotation has finished, including one
@@ -683,7 +689,11 @@ export class Agent {
     const assemble = async (): Promise<NormalizedRequest> => {
       const { messages, systemInjections } = await this.toolResultGuard.afterAnnotations(
         () => this.compileWithInjections(budget, injections));
-      messages.push(...unguardedResults);
+      // Read after the awaited compile: results may have become ready while
+      // it was running. A retry takes a fresh read too.
+      if (this._state.status === 'ready' && !guardedResults) {
+        messages.push(...this.buildToolResultMessages(this._state.toolResults));
+      }
       return {
         messages: this.toolResultGuard.prepareRequest(messages, true),
         system: this.buildSystemPrompt(systemInjections),
@@ -698,7 +708,13 @@ export class Agent {
         assistantParticipant: this.name,
       };
     };
-    const request = await assemble();
+    let request: NormalizedRequest;
+    this.compilingRequest = true;
+    try {
+      request = await assemble();
+    } finally {
+      this.compilingRequest = false;
+    }
 
     const abortController = new AbortController();
     if (options?.signal) {
@@ -939,99 +955,103 @@ export class Agent {
     compressionTools: ToolDefinition[] = availableTools,
     options: ActivationRequestOptions = {},
   ): Promise<StartStreamResult> {
-    if (this._state.status !== 'idle') {
-      throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
+    if (this.compilingRequest || this._state.status !== 'idle') {
+      throw new Error(`Agent ${this.name} cannot start stream in state ${this.compilingRequest ? 'compiling' : this._state.status}`);
     }
+    this.compilingRequest = true;
+    try {
+      // Retry accepted history edits before assembling a real request. Pure
+      // preview/compile entry points must not perform these writes.
+      this.toolResultGuard.flushUnrecorded();
+
+      // A new activation supersedes every receipt flight the previous one left
+      // open. Membrane fires the kv-unified wire receipt per provider attempt,
+      // BEFORE the adapter call; only that attempt's usage event settles it.
+      // When the attempt dies without usage (transport error, idle timeout,
+      // framework cancel for a budget restart or endTurn) the flight stays open
+      // until the old driveStream's `finally` runs — and every successor path
+      // (error-policy retry, budget restart, the next wake after an abort)
+      // starts the new stream BEFORE that `finally`. The successor's first
+      // receipt then met the ledger's single-flight guard and failed the
+      // recovery itself: "kv-unified submission devops:46:…:4 is still in
+      // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
+      this.failOpenKvSubmissions();
+
+      this._streamId++;
+      this._inferenceStartedAt = Date.now();
+      this.lastStreamInputTokens = 0;
+      // Reset the cache-inclusive counters too: a new stream must not inherit
+      // the prior stream's window size — on the physical-window restart path
+      // that inherited value IS the oversized number that caused the restart,
+      // and projecting on it before this stream's first usage event would
+      // restart again (loop). The `> 0` guard downstream means "no usage
+      // observed on THIS stream yet" only because of this reset.
+      this.lastStreamRealInputTokens = 0;
+      this.lastStreamOutputTokens = 0;
+
+      // Compiled only once each withheld stub's annotation has finished,
+      // including one that began during the compile, and after a stub edit that
+      // failed has been retried (see afterAnnotations).
+      const request = await this.toolResultGuard.afterAnnotations(
+        () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
+      request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
+
+      const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
+        .getStrategy?.() as {
+        beginKvUnifiedSubmission?: (args: { submissionId: string; requestHash: string; layoutHash: string }) => void;
+        isKvUnifiedEnabled?: () => boolean;
+      };
+      const kvEnabled = receiptAware?.isKvUnifiedEnabled?.() === true;
+      const kvQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> = [];
+      let kvCall = 0;
+      if (kvEnabled) {
+        this.kvOpenQueue = kvQueue;
+        const layoutHash = stableHash(request.messages);
+        const kvRequest = request as NormalizedRequest & KvUnifiedRequestHooks;
+        kvRequest.onCacheWireReceipt = (receipt) => {
+          const submissionId = `${this.name}:${this._streamId}:${Date.now()}:${kvCall++}`;
+          receiptAware.beginKvUnifiedSubmission!({
+            submissionId,
+            requestHash: receipt.requestHash,
+            layoutHash,
+          });
+          kvQueue.push({ submissionId, wireReceipt: receipt });
+        };
+      }
 
-    // Retry accepted history edits before assembling a real request. Pure
-    // preview/compile entry points must not perform these writes.
-    this.toolResultGuard.flushUnrecorded();
+      const agent = this;
+      const stream = this.membrane.streamYielding(request, {
+        emitTokens: true,
+        emitBlocks: false,
+        emitUsage: true,
+        // Retry a content-policy refusal at the provider seam rather than at
+        // the framework level: membrane replays the SAME request immediately
+        // (cache-warm), where a framework-level requeue would recompile and
+        // land a different window. The framework's driveStream handles the
+        // resulting `retrying` event by discarding the abandoned attempt.
+        // Membrane reads this per physical round, including after settings
+        // tools run. A guarded result must reach the host on its FIRST refusal;
+        // never spend retries resubmitting unchanged guarded content.
+        get refusalRetries() {
+          return agent.toolResultGuard.hasSubmittedPending || agent.toolResultGuard.recovering
+            ? 0 : agent.refusalHandling?.retries ?? 0;
+        },
+      });
 
-    // A new activation supersedes every receipt flight the previous one left
-    // open. Membrane fires the kv-unified wire receipt per provider attempt,
-    // BEFORE the adapter call; only that attempt's usage event settles it.
-    // When the attempt dies without usage (transport error, idle timeout,
-    // framework cancel for a budget restart or endTurn) the flight stays open
-    // until the old driveStream's `finally` runs — and every successor path
-    // (error-policy retry, budget restart, the next wake after an abort)
-    // starts the new stream BEFORE that `finally`. The successor's first
-    // receipt then met the ledger's single-flight guard and failed the
-    // recovery itself: "kv-unified submission devops:46:…:4 is still in
-    // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
-    this.failOpenKvSubmissions();
-
-    this._streamId++;
-    this._inferenceStartedAt = Date.now();
-    this.lastStreamInputTokens = 0;
-    // Reset the cache-inclusive counters too: a new stream must not inherit
-    // the prior stream's window size — on the physical-window restart path
-    // that inherited value IS the oversized number that caused the restart,
-    // and projecting on it before this stream's first usage event would
-    // restart again (loop). The `> 0` guard downstream means "no usage
-    // observed on THIS stream yet" only because of this reset.
-    this.lastStreamRealInputTokens = 0;
-    this.lastStreamOutputTokens = 0;
-
-    // Compiled only once each withheld stub's annotation has finished,
-    // including one that began during the compile, and after a stub edit that
-    // failed has been retried (see afterAnnotations).
-    const request = await this.toolResultGuard.afterAnnotations(
-      () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
-    request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
-
-    const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
-      .getStrategy?.() as {
-      beginKvUnifiedSubmission?: (args: { submissionId: string; requestHash: string; layoutHash: string }) => void;
-      isKvUnifiedEnabled?: () => boolean;
-    };
-    const kvEnabled = receiptAware?.isKvUnifiedEnabled?.() === true;
-    const kvQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> = [];
-    let kvCall = 0;
-    if (kvEnabled) {
-      this.kvOpenQueue = kvQueue;
-      const layoutHash = stableHash(request.messages);
-      const kvRequest = request as NormalizedRequest & KvUnifiedRequestHooks;
-      kvRequest.onCacheWireReceipt = (receipt) => {
-        const submissionId = `${this.name}:${this._streamId}:${Date.now()}:${kvCall++}`;
-        receiptAware.beginKvUnifiedSubmission!({
-          submissionId,
-          requestHash: receipt.requestHash,
-          layoutHash,
-        });
-        kvQueue.push({ submissionId, wireReceipt: receipt });
+      this._state = { status: 'streaming', stream };
+      return {
+        stream,
+        request,
+        ...(kvEnabled
+          ? {
+              takeKvSubmission: () => kvQueue.shift(),
+              drainKvSubmissionIds: () => kvQueue.splice(0).map((item) => item.submissionId),
+            }
+          : {}),
       };
+    } finally {
+      this.compilingRequest = false;
     }
-
-    const agent = this;
-    const stream = this.membrane.streamYielding(request, {
-      emitTokens: true,
-      emitBlocks: false,
-      emitUsage: true,
-      // Retry a content-policy refusal at the provider seam rather than at
-      // the framework level: membrane replays the SAME request immediately
-      // (cache-warm), where a framework-level requeue would recompile and
-      // land a different window. The framework's driveStream handles the
-      // resulting `retrying` event by discarding the abandoned attempt.
-      // Membrane reads this per physical round, including after settings
-      // tools run. A guarded result must reach the host on its FIRST refusal;
-      // never spend retries resubmitting unchanged guarded content.
-      get refusalRetries() {
-        return agent.toolResultGuard.hasSubmittedPending || agent.toolResultGuard.recovering
-          ? 0 : agent.refusalHandling?.retries ?? 0;
-      },
-    });
-
-    this._state = { status: 'streaming', stream };
-    return {
-      stream,
-      request,
-      ...(kvEnabled
-        ? {
-            takeKvSubmission: () => kvQueue.shift(),
-            drainKvSubmissionIds: () => kvQueue.splice(0).map((item) => item.submissionId),
-          }
-        : {}),
-    };
   }
 
   /** Close every kv-unified receipt flight the previous activation left
@@ -1198,7 +1218,9 @@ export class Agent {
     /** Compiles the context into a request again, for the guard's retry. */
     reassemble: () => Promise<NormalizedRequest>,
   ): Promise<InferenceResult> {
-    let response = await this.membrane.stream(request, { signal });
+    let response = signal?.aborted
+      ? { aborted: true as const, reason: 'user' as const }
+      : await this.membrane.stream(request, { signal });
     // Usage of a refused attempt abandoned by the guard; it was billed and
     // is added to the retry's usage below rather than overwritten.
     let abandonedUsage: { inputTokens: number; outputTokens: number } | undefined;
@@ -1212,7 +1234,10 @@ export class Agent {
         // annotation has finished (agent-framework #277), and against the
         // budget without the batch's reservation, so a stub longer than its
         // original can't carry the request past the budget.
-        response = await this.membrane.stream(await reassemble(), { signal });
+        const retry = await reassemble();
+        response = signal?.aborted
+          ? { aborted: true, reason: 'user', partialUsage: response.usage }
+          : await this.membrane.stream(retry, { signal });
       }
     }
 
diff --git a/src/framework.ts b/src/framework.ts
index ecf816436..f1e9b765f 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -815,10 +815,9 @@ class DefaultErrorPolicy implements ErrorPolicy {
 
 /** Default sync interval in milliseconds */
 const DEFAULT_SYNC_INTERVAL_MS = 1000;
-/** How long the tool-result guard waits for a withheld original's workspace
- *  write before its stub says the write was still under way. A local
- *  write takes milliseconds; this bounds a stalled mount, which would otherwise
- *  hold every later request of the agent and the framework's stop. */
+/** Total time one withheld batch may spend awaiting workspace writes.
+ *  At the deadline its unfinished write is named as such, and later
+ *  originals stay in the audit. This bound applies to withheld spills. */
 const WITHHELD_SPILL_DEADLINE_MS = 30_000;
 /** Poll pending context-strategy maintenance independently of user activity. */
 const DEFAULT_MAINTENANCE_INTERVAL_MS = 5000;
@@ -1062,6 +1061,8 @@ export class AgentFramework {
   private providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
   private providerHoldHook: ProviderHoldHook | undefined;
   private providerAdmissionClosed = false;
+  /** Invalidates framework turns still assembling when stop begins. */
+  private lifecycleGeneration = 0;
   /** Last time we reported stale (busy-requeued) inference requests, per agent. */
   private staleWarnAt = new Map<string, number>();
   /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
@@ -1987,6 +1988,7 @@ export class AgentFramework {
 
     this.running = true;
     this.providerAdmissionClosed = false;
+    this.guardSpillsClosed = false;
     this.loopPromise = this.runLoop();
 
     // Start periodic sync timer (if enabled)
@@ -2049,6 +2051,7 @@ export class AgentFramework {
     // store is still open, rather than leaving them to a reboot replay.
     this.ackDeferredWrites();
     this.providerAdmissionClosed = true;
+    this.lifecycleGeneration++;
     this.queue.close();
     this.tuneOutCoordinator?.stop();
 
@@ -2875,7 +2878,8 @@ export class AgentFramework {
     agent.toolResultGuard.setOverride(enabled);
     const guard = agent.toolResultGuard;
     guard.setHost({
-      spill: (label, text, branch) => this.spillWithheld(label, text, branch),
+      spill: (label, text, branch, deadline) => this.spillWithheld(label, text, branch, deadline),
+      deadline: () => Date.now() + this.withheldSpillDeadlineMs,
       track: (annotation) => {
         this.guardAnnotations.add(annotation);
         void annotation.finally(() => this.guardAnnotations.delete(annotation));
@@ -8538,7 +8542,7 @@ export class AgentFramework {
         requests = [...providerCooldown.heldRequests, ...requests];
       }
 
-      // Skip if agent is busy (inferring, streaming, or waiting for tools) —
+      // Skip if agent is busy (compiling, inferring, streaming, or waiting for tools) —
       // or if a turn is alive at all (activeTurnTokens): the state machine
       // goes idle at endTurn's reset while driveStream teardown is still
       // pending, and a successor turn dequeued in that gap compiles while the
@@ -8604,7 +8608,7 @@ export class AgentFramework {
       // Truthiness, not `!== null`: prototype-built harnesses (and any field
       // added later) leave the slot undefined, which must read as "not held".
       const surgeryHeld = !!this.surgeryHold;
-      if (surgeryHeld || providerPrimaryWaiting || turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
+      if (surgeryHeld || providerPrimaryWaiting || turnAlive || agent.isCompilingRequest || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
         // Re-queue requests, but warn if they've been pending too long.
         // Suppressed while quiesced: a drain-phase busy requeue is expected,
         // not a wedge tell.
@@ -9361,6 +9365,7 @@ export class AgentFramework {
     turnToken: number,
     ownsProviderGate: boolean,
   ): Promise<boolean> {
+    const lifecycle = this.lifecycleGeneration;
     const continuingTurn = resumesLogicalTurn(trigger?.reason);
     const turnProseRouting = trigger?.suppressProse ? 'disabled' : agent.proseRouting;
     // Flush messages deferred during the PREVIOUS turn — before the
@@ -9656,11 +9661,12 @@ export class AgentFramework {
       } = await agent.startStreamWithInjections(tools, injections, undefined, compressionTools, {
         silentHeartbeat: trigger?.silentHeartbeat,
       });
-      // The compile can wait for a withheld batch's annotation, up to the
-      // spill deadline (see ToolResultGuard.afterAnnotations), so check both
-      // again. Membrane's yielding stream starts its request when it is first
+      // The compile can wait for annotations (each batch has one spill
+      // deadline), so check ownership, admission, and the lifecycle again.
+      // A stop followed by start must not revive this earlier turn.
+      // Membrane's yielding stream starts its request when it is first
       // iterated, so cancelling it here, before driveStream, sends nothing.
-      if (this.agents.get(agent.name) !== agent || this.providerAdmissionClosed) {
+      if (this.agents.get(agent.name) !== agent || this.providerAdmissionClosed || lifecycle !== this.lifecycleGeneration) {
         stream.cancel();
         agent.cancelStream();
         if (this.agents.get(agent.name) === agent) {
@@ -12087,23 +12093,28 @@ export class AgentFramework {
   }
 
   /**
-   * The guard's spill of a withheld original (agent-framework #277): the
-   * tool-results file, waited for at most withheldSpillDeadlineMs. A write
-   * still under way then is reported as unfinished at its path. Nothing waits
-   * for it after that, stop() included: it goes on by itself and may finish
-   * or fail after the workspace has stopped, and its record says only that
-   * it was unfinished. Until it settles, the workspace isn't answering, and no
-   * other write is started: each later spill, of any agent's batch, is
-   * reported unanswered at once, so a stalled mount costs one deadline. A
-   * write the workspace declines because it had left `branch` is reported
-   * as such, with no path, since no file was written. Once stop() has let the
-   * running annotations finish, no new write is started.
+   * A withheld original uses the remaining time in its batch's deadline.
+   * A write still under way at that deadline is reported as unfinished and
+   * continues independently, including after stop. From then until every
+   * overdue write settles, new withheld spills are workspace_unanswered.
+   * Writes from other batches can start before the first deadline fires.
+   * An exhausted batch starts no more writes even if none is overdue.
+   * The inline cap's spills use writeToolResultFile without this deadline.
    */
-  private async spillWithheld(label: string, text: string, branch: string): Promise<WithheldSpill> {
+  private async spillWithheld(label: string, text: string, branch: string,
+    deadline = Date.now() + this.withheldSpillDeadlineMs): Promise<WithheldSpill> {
     if (this.guardSpillsClosed) return null;
     const place = this.toolResultFilePlace(label);
     if (!place) return null;
-    if (this.stalledSpills.size > 0) return { skipped: 'workspace_unanswered' };
+    if (this.stalledSpills.size > 0) {
+      console.error(`[spill] ${place.path} skipped: workspace_unanswered (${this.stalledSpills.size} withheld write(s) past deadline)`);
+      return { skipped: 'workspace_unanswered' };
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      console.error(`[spill] ${place.path} skipped: batch_deadline`);
+      return { skipped: 'batch_deadline' };
+    }
     const write = this.writeToolResultFile(label, text, branch);
     let timer: ReturnType<typeof setTimeout> | undefined;
     const late = new Promise<'late'>((resolve) => {
@@ -12112,8 +12123,9 @@ export class AgentFramework {
         // spill that starts after it finds the workspace answering.
         const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => this.stalledSpills.delete(stalled));
         this.stalledSpills.add(stalled);
+        console.error(`[spill] ${place.path} still being written at the withheld batch deadline`);
         resolve('late');
-      }, this.withheldSpillDeadlineMs);
+      }, remaining);
       timer.unref?.();
     });
     try {
@@ -12153,7 +12165,9 @@ export class AgentFramework {
       // the stub or the truncation note sends there. The workspace
       // reports the disk failure itself (workspace:materialize-failed).
       if ((result.data as { inChronicle?: boolean } | undefined)?.inChronicle === true) {
-        console.error(`[spill] ${path} is in the workspace's Chronicle tree, but its copy on disk failed: ${result.error}`);
+        const error = (result.error ?? 'disk copy failed').slice(0, 200);
+        this.emitTrace({ type: 'tool:spill_failed', label: safeLabel, path, contentLength: content.length, error });
+        console.error(`[spill] ${path} is in the workspace's Chronicle tree, but its copy on disk failed: ${error}`);
         return { path };
       }
       // Declined, not failed: the store left the branch the file is for, so
@@ -16300,7 +16314,8 @@ export class AgentFramework {
           const destination = pathFor(image.rangeOffset);
           const bytes = Buffer.from(image.data, 'base64');
           const result = await workspace.writeBinary(destination, bytes, image.mediaType);
-          if (!result.success) {
+          const inChronicle = (result.data as { inChronicle?: boolean } | undefined)?.inChronicle === true;
+          if (!result.success && !inChronicle) {
             finish({
               success: false,
               error:
@@ -16314,6 +16329,10 @@ export class AgentFramework {
           }
           savedFiles.push({
             ...(result.data as Record<string, unknown>),
+            path: destination,
+            size: bytes.byteLength,
+            mimeType: image.mediaType,
+            ...(!result.success ? { diskCopyError: result.error ?? 'disk copy failed' } : {}),
             imageIndex: index + image.rangeOffset,
             ...image.receipt,
           });
diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index e771937ab..7920b2c31 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1455,8 +1455,16 @@ export class WorkspaceModule implements Module {
         return { success: false, error: 'the workspace had left the branch this file is for', isError: true, data: { branchLeft: true } };
       }
       const blobHash = store.storeBlob(data, mimeType);
-      const materializeError = await this.commitToolChange(mount, relativePath, { kind: 'set', blobHash, size: data.byteLength });
-      if (materializeError) {
+      let committed = false;
+      let materializeError: string | null;
+      try {
+        materializeError = await this.commitToolChange(mount, relativePath,
+          { kind: 'set', blobHash, size: data.byteLength }, () => { committed = true; });
+      } catch (error) {
+        if (!committed) throw error;
+        materializeError = error instanceof Error ? error.message : String(error);
+      }
+      if (materializeError !== null) {
         // The file is in the Chronicle tree, where the workspace's tools read
         // it; only its copy on disk failed. `inChronicle` lets a caller that
         // needs the file readable tell this from a write that never happened
@@ -1918,6 +1926,7 @@ export class WorkspaceModule implements Module {
     mount: MountState,
     relativePath: string,
     change: { kind: 'set'; blobHash: string; size: number; mode?: number } | { kind: 'remove'; previousHash: string },
+    onCommitted?: () => void,
   ): Promise<string | null> {
     const store = this.getStore();
     const intents = this.intents.get(mount.config.name)!;
@@ -1927,6 +1936,9 @@ export class WorkspaceModule implements Module {
     const known = this.agreementOrThrow().get(mount.config.name, relativePath) !== undefined;
     if (change.kind === 'set') {
       store.treeSet(mount.treeStateId, relativePath, { blobHash: change.blobHash, size: change.size, mode: change.mode ?? 0o644 });
+      // A later intent update or disk push can throw; the tree entry is
+      // already readable, even if the active branch changes during the push.
+      onCommitted?.();
       intents.update(relativePath, (cur) => {
         const next = { ...cur };
         delete next.tombstone;
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 2f08e3493..168f9340e 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -14,24 +14,24 @@ export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
  *  workspace isn't answering (`workspace_unanswered`: an earlier write is
  *  still under way past the host's deadline) or because the workspace had
  *  left the stub's branch when the file would have been committed
- *  (`branch_changed`); or null when no file is written at all (no writable
+ *  (`branch_changed`), or because the batch used its deadline before this
+ *  write could start (`batch_deadline`); or null when no file is written at all (no writable
  *  workspace, or the host is stopping). */
 export type WithheldSpill =
   | { path: string; error?: string; unfinished?: true }
-  | { skipped: 'workspace_unanswered' | 'branch_changed' }
+  | { skipped: 'workspace_unanswered' | 'branch_changed' | 'batch_deadline' }
   | null;
 
-/** Writes one withheld original as a workspace file (the framework's
- *  tool-results spill). It reports a failed write rather than throwing, and
- *  it settles within a bounded time: a write still under way at the host's
- *  deadline is reported as unfinished, and until that write settles the host
- *  starts no other (each is `workspace_unanswered`), so a stalled workspace
- *  costs one deadline however many results and batches queue behind it. The
- *  file lands on `branch`, the branch the stub is on, or isn't written: the
- *  workspace checks the branch where it commits the file
- *  (WorkspaceModule.writeBinary), and a write it declines is
- *  `branch_changed`. */
-export type WithheldSpiller = (label: string, text: string, branch: string) => Promise<WithheldSpill>;
+/**
+ * Writes one withheld original as a workspace file, using what remains of
+ * the batch's absolute deadline. A write still running then is unfinished.
+ * Once a write reaches that deadline, later spills are workspace_unanswered
+ * until all overdue writes settle. Other batches can start before that gate
+ * closes. An exhausted batch starts no write (batch_deadline).
+ * The tree entry lands on branch or the write is declined (branch_changed).
+ * The mount's disk directory is shared across branches.
+ */
+export type WithheldSpiller = (label: string, text: string, branch: string, deadline: number) => Promise<WithheldSpill>;
 
 /** What a host gives a guard for its withheld results: where originals are
  *  written, where each annotation is registered, so the host's stop can
@@ -39,6 +39,8 @@ export type WithheldSpiller = (label: string, text: string, branch: string) => P
  *  guard says whether it has work left. */
 export interface WithheldHost {
   spill: WithheldSpiller;
+  /** Absolute deadline for one batch, captured when its annotation starts. */
+  deadline(): number;
   track(annotation: Promise<void>): void;
   /** Whether the guard is idle (see ToolResultGuard.idle), told after each
    *  change that can alter it: when an annotation starts or ends, and after
@@ -133,17 +135,17 @@ export class ToolResultGuard {
    *  failed and waits in the storage queue, retried in order until it lands
    *  or an operator's change supersedes it (until then the stub is the bare
    *  notice, kept out of summaries by its compression hold, and the audit
-   *  record names the place). It never rejects. Its wait is bounded: the host
-   *  reports a write still under way at its deadline as unfinished and starts
-   *  no other until that write settles. */
+   *  record names the place). It never rejects. Each batch has one deadline
+   *  for all its workspace writes; queued batches are annotated in order.
+   *  A request may carry an unfinished-write notice once that deadline passes. */
   whenAnnotated(): Promise<void> { return this.annotating ?? Promise.resolve(); }
 
   /**
    * Runs `read` (a compile of the context) once no withheld stub is still
    * being annotated, and again if an annotation began while it ran, since a
    * settlement can land during the compile's own awaits, such as a previous
-   * frame's teardown abandoning its batch. Every compile of a
-   * request that is sent goes through it: the agent's activations, its direct
+   * frame's teardown abandoning its batch. The framework's sent-request
+   * compiles go through it: the agent's activations, its direct
    * API calls and their refusal retry, and a conversation fork's seed from its
    * template. A request preview doesn't, so it never waits on a
    * workspace write.
@@ -202,7 +204,9 @@ export class ToolResultGuard {
 
   /** Ordered storage work, separate from batches awaiting a provider verdict.
    * A failed acceptance edit retains both the payload and its compression
-   * hold here; it can never re-arm refusal handling or tool submission. */
+   * hold here; it can never re-arm refusal handling or tool submission.
+   * Any failed head, including an audit-only record, blocks later queued
+   * edits and their holds until that operation succeeds. */
   private unrecorded: AuditOperation[] = [];
 
   /** Retry edits and audit writes before a new activation, a compile of a
@@ -471,6 +475,7 @@ export class ToolResultGuard {
       // it when the edit lands or is superseded.
       let holdQueued = false;
       try {
+        const deadline = this.host?.deadline() ?? Infinity;
         const date = new Date().toISOString().slice(0, 10);
         // A file is named by its batch and its place in the batch, ahead of
         // anything the writer may cut or substitute: results of one batch
@@ -492,8 +497,9 @@ export class ToolResultGuard {
           // skipped, and its original stays in the audit record. Nothing
           // yields from here to the edit's own branch check, so while the
           // store is away the stub stays as it is. A write already under way
-          // when the branch changes is refused where it commits, since it
-          // names the batch's branch, so no file lands elsewhere.
+          // when the branch changes is refused before its tree entry is set,
+          // since it names the batch's branch. Once set, that entry stays on
+          // its branch; its disk copy uses the mount's shared directory.
           if (branchLeft || this.cm.currentBranch().name !== pending.branch) {
             branchLeft = true;
             spills.set(index, { skipped: 'branch_changed' });
@@ -505,7 +511,7 @@ export class ToolResultGuard {
           let spill: WithheldSpill = null;
           if (this.host) {
             try {
-              spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original, pending.branch);
+              spill = await this.host.spill(`${date}-withheld-${batch}-${index}-${block.toolUseId}`, original, pending.branch, deadline);
             } catch (error) {
               // The host reports a failed write rather than throwing; a throw
               // is recorded all the same, without a path.
diff --git a/test/save-recent-image.test.ts b/test/save-recent-image.test.ts
index eb8bd9f5f..7ca516bb0 100644
--- a/test/save-recent-image.test.ts
+++ b/test/save-recent-image.test.ts
@@ -147,6 +147,7 @@ async function startTurn(opts: {
   seedHistory?: (framework: AgentFramework) => void;
   toolResultInlineMaxChars?: number;
   world?: (module: SnapModule) => void;
+  workspace?: (workspace: WorkspaceModule) => void;
 }): Promise<Harness> {
   const tempDir = mkdtempSync(join(tmpdir(), opts.prefix));
   const mountDir = join(tempDir, 'mount');
@@ -180,6 +181,7 @@ async function startTurn(opts: {
     { type: 'image', source: { type: 'base64', data: GIF.toString('base64'), mediaType: 'image/gif' } },
   ] as ContentBlock[]);
   opts.seedHistory?.(framework);
+  opts.workspace?.(workspace);
   framework.start();
   framework.pushEvent({
     type: 'external-message',
@@ -814,3 +816,43 @@ describe('ToolImageLedger', () => {
     );
   });
 });
+
+for (const secondFails of [false, true]) {
+  it(`#281 round: a tree-only image save ${secondFails ? 'appears in a later failure receipt' : 'succeeds with a disk-copy warning'}`, async () => {
+    const h = await startTurn({
+      prefix: 'sri-tree-only-',
+      responses: [
+        [snapCall('call_snap')],
+        [saveCall('call_save', { path: 'files/images.png', index: 0, count: 2 })],
+        done,
+      ],
+      workspace: (workspace) => {
+        const write = workspace.writeBinary.bind(workspace);
+        let writes = 0;
+        workspace.writeBinary = async (...args) => {
+          if (++writes === 2 && secondFails) return { success: false, error: 'tree unavailable', isError: true };
+          const result = await write(...args);
+          assert.equal(result.success, true);
+          return { success: false, data: { inChronicle: true }, error: 'injected disk-copy failure', isError: true };
+        };
+      },
+    });
+    try {
+      const result = await waitForToolResult(h.framework, 'call_save');
+      if (secondFails) {
+        assert.equal(result.isError, true);
+        assert.match(result.content, /tree unavailable/);
+        assert.match(result.content, /already saved: files\/images-0.png/);
+      } else {
+        const files = saved(result);
+        assert.equal(files.length, 2);
+        assert.equal(files[0].path, 'files/images-0.png');
+        assert.equal(files[0].inChronicle, true);
+        assert.match(String(files[0].diskCopyError), /injected disk-copy failure/);
+        assert.equal(files[0].size, PNG.byteLength);
+        assert.equal(files[0].mimeType, 'image/png');
+      }
+      assert.ok((await fileBytes(h, 'files/images-0.png'))?.equals(PNG));
+    } finally { await h.framework.stop(); rmSync(h.tempDir, { recursive: true, force: true }); }
+  });
+}
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index a85e74eb8..25c389be8 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -1370,7 +1370,7 @@ for (const failedType of ['staged', 'linked']) {
     try {
       await assert.doesNotReject(h.run(), 'storage failure must not strand the live tool loop');
       const agent = h.framework.getAgent('assistant')!;
-      assert.equal(agent.state.status, 'idle');
+      assert.equal(String(agent.state.status), 'idle');
       assert.equal(agent.toolResultGuard.hasPending, false);
       assert.equal(agent.getContextManager().getCompressionHolds().size, 0);
       assert.match(JSON.stringify(h.membrane.streams[0].receivedToolResults), /Tool result withheld/);
@@ -1402,7 +1402,7 @@ test('storage recovery: failed accepted edit is retried before the next activati
   };
   try {
     await h.run();
-    assert.equal(agent.state.status, 'idle');
+    assert.equal(String(agent.state.status), 'idle');
     assert.equal(agent.toolResultGuard.hasPending, false, 'an accepted batch cannot claim another refusal');
     assert.equal(cm.getCompressionHolds().size, 1, 'keep provisional history out of compression until repaired');
     assert.equal(toolResults(h.framework)[0].content, TOOL_RESULT_GUARD_NOTICE);
@@ -1739,7 +1739,7 @@ test("#277: an operator's edit made before the stub is annotated stands, and the
     let release!: () => void;
     const gate = new Promise<void>((resolve) => { release = resolve; });
     let entered = false;
-    r.guard.setHost({ spill: async () => { entered = true; await gate; return null; }, track: () => {}, idle: () => {} });
+    r.guard.setHost({ deadline: () => Infinity, spill: async () => { entered = true; await gate; return null; }, track: () => {}, idle: () => {} });
     r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
     assert.ok(r.guard.withhold('test-category'));
     for (let i = 0; i < 100 && !entered; i++) await new Promise((resolve) => setTimeout(resolve, 10));
@@ -2243,7 +2243,7 @@ test('#281: a compile waits for an annotation that began while it waited for ano
     const first = gate();
     const second = gate();
     let entered = 0;
-    r.guard.setHost({ spill: async () => {
+    r.guard.setHost({ deadline: () => Infinity, spill: async () => {
       entered++;
       await (entered === 1 ? first.opened : second.opened);
       return null;
@@ -2414,7 +2414,7 @@ test('#281: a write declined for a branch the workspace left stops the writes, a
   } finally { await h.framework.stop(); }
 });
 
-test('#281: stop during a compile that waits for an annotation lets no provider stream start after it', async () => {
+test('#281: stop during a compile that waits for an annotation lets no provider stream be driven after it', async () => {
   const h = await workspaceHarness([[calls('one'), refused()], [answer()]]);
   const framework = h.framework as unknown as { writeToolResultFile: (...args: unknown[]) => Promise<unknown> };
   const writeFile = framework.writeToolResultFile.bind(h.framework);
@@ -2423,6 +2423,14 @@ test('#281: stop during a compile that waits for an annotation lets no provider
   const compiles = watchCompiles(h.framework);
   const traces: string[] = [];
   h.framework.onTrace((event) => traces.push((event as { type: string }).type));
+  let driven = 0;
+  const stream = h.membrane.streamYielding.bind(h.membrane);
+  h.membrane.streamYielding = (...args) => {
+    const result = stream(...args);
+    const iterate = result[Symbol.asyncIterator].bind(result);
+    result[Symbol.asyncIterator] = () => { driven++; return iterate(); };
+    return result;
+  };
   let stopped = false;
   try {
     const running = h.run();
@@ -2435,6 +2443,7 @@ test('#281: stop during a compile that waits for an annotation lets no provider
     // entry went with the retry it started.
     await bounded(running, 'the run');
     assert.equal(h.membrane.requests.length, 2, 'the retry was compiled once its stub was written');
+    assert.equal(driven, 1, 'only the original stream was driven; the retry sends nothing');
     assert.equal(traces.includes('inference:completed'), false, 'but, compiled after stop began, it was never driven');
   } finally { write.open(); if (!stopped) await h.framework.stop(); }
 });
@@ -2554,7 +2563,7 @@ test('#281: a compile during which an annotation began is compiled again once it
   try {
     const write = gate();
     let entered = false;
-    r.guard.setHost({ spill: async () => { entered = true; await write.opened; return null; }, track: () => {}, idle: () => {} });
+    r.guard.setHost({ deadline: () => Infinity, spill: async () => { entered = true; await write.opened; return null; }, track: () => {}, idle: () => {} });
     r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
     let reads = 0;
     const stub = () => (r.cm.getMessage(r.messageId)!.content[0] as { content: unknown }).content;
@@ -2624,3 +2633,338 @@ test('#281: an annotation that starts while modules stop writes no file, and is
     assert.deepEqual(audit.at(-2)?.results, [{ toolUseId: 'late', skipped: 'no_workspace_file' }]);
   } finally { await restarted.stop(); }
 });
+
+test('#281 round: an unexpected annotation exception releases its compression hold', async () => {
+  const r = await compressionRig();
+  const branch = r.cm.currentBranch.bind(r.cm);
+  try {
+    r.guard.abandon('test');
+    r.cm.currentBranch = () => { throw new Error('injected annotation branch read'); };
+    await r.guard.whenAnnotated();
+    r.cm.currentBranch = branch;
+    assert.equal(r.cm.getCompressionHolds().size, 0);
+    assert.equal(r.cm.getMessage(r.messageId!)!.content[0].type, 'tool_result');
+    assert.equal((r.cm.getMessage(r.messageId!)!.content[0] as { content: string }).content, TOOL_RESULT_GUARD_NOTICE);
+  } finally { r.cm.currentBranch = branch; await r.cm.close(); }
+});
+
+test('#281 round: a throw after treeSet reports the original as readable', async () => {
+  const h = await workspaceHarness([], { autoMaterialize: true });
+  const ws = h.workspace as unknown as { pushUnlocked: () => Promise<never> };
+  const push = ws.pushUnlocked;
+  try {
+    ws.pushUnlocked = async () => { throw new Error('injected push exception'); };
+    const result = await h.workspace.writeBinary('work/throw.txt', Buffer.from('original'), 'text/plain');
+    assert.equal(result.success, false);
+    assert.equal((result.data as { inChronicle?: boolean })?.inChronicle, true);
+    assert.match(result.error!, /injected push exception/);
+    const file = await h.workspace.readBinary('work/throw.txt');
+    assert.ok('data' in file);
+    assert.equal(file.data.toString(), 'original');
+  } finally { ws.pushUnlocked = push; await h.framework.stop(); }
+});
+
+test('#281 round: a throw before treeSet does not claim a readable original', async () => {
+  const h = await workspaceHarness([]);
+  const store = h.framework.getStore();
+  const set = store.treeSet.bind(store);
+  try {
+    store.treeSet = () => { throw new Error('injected tree exception'); };
+    await assert.rejects(h.workspace.writeBinary('work/throw.txt', Buffer.from('original'), 'text/plain'), /injected tree exception/);
+    assert.equal(store.treeGet('workspace/work/tree', 'throw.txt'), null);
+  } finally { store.treeSet = set; await h.framework.stop(); }
+});
+
+test('#281 round: abort during the direct refusal retry annotation sends no retry', async () => {
+  const h = await harness([], { toolResultGuard: true });
+  const requests: NormalizedRequest[] = [];
+  const responses = [calls('one'), refused(), answer()];
+  (h.membrane as unknown as { stream: (r: NormalizedRequest) => Promise<NormalizedResponse> }).stream = async (r) => {
+    requests.push(r); return responses.shift()!;
+  };
+  const write = gate();
+  let entered = false;
+  slowSpill(h.framework, () => { entered = true; return write.opened; });
+  try {
+    const agent = h.framework.getAgent('assistant')!;
+    await agent.runInference([]);
+    agent.provideToolResult('one', { success: true, data: 'original' });
+    const controller = new AbortController();
+    const inference = agent.runInference([], undefined, { signal: controller.signal });
+    await until(() => entered, 'the direct retry waits for annotation');
+    controller.abort();
+    write.open();
+    const result = await inference;
+    assert.equal(requests.length, 2);
+    assert.equal(result.aborted, true);
+    assert.equal(String(agent.state.status), 'idle');
+  } finally { write.open(); await h.framework.stop(); }
+});
+
+for (const entry of ['direct', 'stream'] as const) {
+  test(`#281 round: ${entry} compilation owns the agent until it succeeds or fails`, async () => {
+    const h = await harness([[answer()]]);
+    const agent = h.framework.getAgent('assistant')!;
+    (h.membrane as unknown as { stream: () => Promise<NormalizedResponse> }).stream = async () => answer();
+    const compile = gate();
+    let entered = false;
+    const after = agent.toolResultGuard.afterAnnotations.bind(agent.toolResultGuard);
+    agent.toolResultGuard.afterAnnotations = async (read) => { entered = true; await compile.opened; return after(read); };
+    const starting = entry === 'direct' ? agent.runInference([]) : agent.startStream([]);
+    try {
+      await until(() => entered, 'compile entered');
+      assert.equal((agent as unknown as { isCompilingRequest: boolean }).isCompilingRequest, true);
+      assert.equal(agent.state.status, 'idle', 'the public status union is unchanged');
+      assert.equal(agent.info.status, 'idle');
+      await assert.rejects(bounded(agent.runInference([]), 'overlapping direct call', 1000), /state compiling/);
+      await assert.rejects(bounded(agent.startStream([]), 'overlapping stream call', 1000), /state compiling/);
+      compile.open();
+      await starting;
+      if (entry === 'stream') {
+        await assert.rejects(agent.runInference([]), /state streaming/);
+        agent.cancelStream();
+      }
+      assert.equal(String(agent.state.status), 'idle');
+      agent.toolResultGuard.afterAnnotations = async () => { throw new Error('compile failed'); };
+      await assert.rejects(entry === 'direct' ? agent.runInference([]) : agent.startStream([]), /compile failed/);
+      assert.equal(String(agent.state.status), 'idle');
+      assert.equal((agent as unknown as { isCompilingRequest: boolean }).isCompilingRequest, false,
+        'failure releases compilation ownership');
+    } finally { compile.open(); await starting; agent.cancelStream(); await h.framework.stop(); }
+  });
+}
+
+test('#281 round: unguarded results are read after the direct compile', async () => {
+  const h = await harness([]);
+  const agent = h.framework.getAgent('assistant')!;
+  const compile = agent.compileWithInjections.bind(agent);
+  const requests: NormalizedRequest[] = [];
+  (h.membrane as unknown as { stream: (r: NormalizedRequest) => Promise<NormalizedResponse> }).stream = async (r) => {
+    requests.push(r); return answer();
+  };
+  agent.compileWithInjections = async (...args) => {
+    const result = await compile(...args);
+    // A tool result becoming ready in the compile's await must be observed,
+    // as it was before annotations added another await around compilation.
+    agent.enterWaitingForTools([{ id: 'late', name: 'test--read', input: {} }], new MockYieldingStream([]));
+    agent.provideToolResult('late', { success: true, data: 'arrived-during-compile' });
+    return result;
+  };
+  try {
+    await agent.runInference([]);
+    assert.match(JSON.stringify(requests[0]), /arrived-during-compile/);
+  } finally { await h.framework.stop(); }
+});
+
+test('#281 round: stop then start reopens withheld spills', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'guard-restart-')); dirs.push(dir);
+  const store = JsStore.openOrCreate({ path: join(dir, 'store') });
+  const framework = await AgentFramework.create({ store, membrane: new ScriptMembrane([]).asMembrane(),
+    agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system', toolResultGuard: true }],
+    modules: [], syncIntervalMs: 0, maintenanceIntervalMs: 0 });
+  const f = framework as unknown as {
+    toolResultFilePlace: () => unknown;
+    writeToolResultFile: () => Promise<unknown>;
+  };
+  f.toolResultFilePlace = () => ({ path: 'work/original.txt', safeLabel: 'original' });
+  let writes = 0;
+  f.writeToolResultFile = async () => { writes++; return { path: 'work/original.txt' }; };
+  try {
+    framework.start();
+    await framework.stop();
+    framework.start();
+    const guard = framework.getAgent('assistant')!.toolResultGuard;
+    guard.storeResults([{ type: 'tool_result', toolUseId: 'one', content: 'original' }],
+      [{ toolUseId: 'one', content: 'original' }], []);
+    guard.abandon('test');
+    await guard.whenAnnotated();
+    assert.equal(writes, 1);
+    assert.match(String(toolResults(framework)[0].content), /is in workspace file work\/original.txt/);
+  } finally { await framework.stop(); store.close(); }
+});
+
+test('#281 round: a framework compile from before stop cannot drive after restart', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'guard-generation-')); dirs.push(dir);
+  const store = JsStore.openOrCreate({ path: join(dir, 'store') });
+  const membrane = new ScriptMembrane([[answer()]]);
+  const framework = await AgentFramework.create({ store, membrane: membrane.asMembrane(),
+    agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system' }],
+    modules: [], syncIntervalMs: 0, maintenanceIntervalMs: 0 });
+  const agent = framework.getAgent('assistant')!;
+  const compile = gate();
+  const entered = gate();
+  const build = agent.buildActivationRequest.bind(agent);
+  agent.buildActivationRequest = async (...args) => { entered.open(); await compile.opened; return build(...args); };
+  let driven = 0;
+  const stream = membrane.streamYielding.bind(membrane);
+  membrane.streamYielding = (...args) => {
+    const result = stream(...args);
+    const iterate = result[Symbol.asyncIterator].bind(result);
+    result[Symbol.asyncIterator] = () => { driven++; return iterate(); };
+    return result;
+  };
+  let starting: Promise<void> | undefined;
+  try {
+    starting = (framework as unknown as { startAgentStream(a: typeof agent): Promise<void> }).startAgentStream(agent);
+    await entered.opened;
+    await framework.stop();
+    framework.start();
+    compile.open();
+    await starting;
+    assert.equal(driven, 0);
+  } finally { compile.open(); await starting; await framework.stop(); store.close(); }
+});
+
+// Drain async storage/annotation continuations without advancing deadline time.
+async function flushAsync() {
+  for (let i = 0; i < 8; i++) await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+test('#281 round: slow successful writes share one batch deadline', async (t) => {
+  const h = await workspaceHarness([]);
+  const f = h.framework as unknown as {
+    withheldSpillDeadlineMs: number;
+    writeToolResultFile: (label: string) => Promise<{ path: string }>;
+  };
+  f.withheldSpillDeadlineMs = 50;
+  const writes: string[] = [];
+  const first = gate();
+  const second = gate();
+  f.writeToolResultFile = async (label) => {
+    writes.push(label);
+    await (writes.length === 1 ? first.opened : second.opened);
+    return { path: `work/tool-results/${label}.txt` };
+  };
+  const guard = h.framework.getAgent('assistant')!.toolResultGuard;
+  try {
+    t.mock.timers.enable({ apis: ['Date', 'setTimeout'], now: Date.now() });
+    guard.storeResults(['one', 'two', 'three'].map((id) => ({ type: 'tool_result', toolUseId: id, content: id })),
+      ['one', 'two', 'three'].map((id) => ({ toolUseId: id, content: id })), []);
+    guard.abandon('test');
+    let annotated = false;
+    void guard.whenAnnotated().then(() => { annotated = true; });
+    await flushAsync();
+    assert.equal(writes.length, 1);
+    t.mock.timers.tick(30);
+    first.open();
+    await flushAsync();
+    assert.equal(writes.length, 2);
+    t.mock.timers.tick(19);
+    await flushAsync();
+    assert.equal(annotated, false);
+    t.mock.timers.tick(1);
+    await flushAsync();
+    assert.equal(annotated, true, 'the second write has only the remaining 20 ms');
+    assert.equal(writes.length, 2, 'the third original stays in audit');
+    const notices = toolResults(h.framework).map((b) => String(b.content));
+    assert.match(notices[0], /is in workspace file/);
+    assert.match(notices[1], /was still being written/);
+    assert.equal(notices[2], AUDIT_STUB);
+  } finally { first.open(); second.open(); t.mock.timers.reset(); await h.framework.stop(); }
+});
+
+test('#281 round: a withheld deadline and an unanswered skip are observable', async (t) => {
+  const h = await workspaceHarness([]);
+  const f = h.framework as unknown as {
+    withheldSpillDeadlineMs: number;
+    writeToolResultFile: () => Promise<null>;
+    spillWithheld: (label: string, text: string, branch: string) => Promise<unknown>;
+  };
+  f.withheldSpillDeadlineMs = 50;
+  const write = gate();
+  f.writeToolResultFile = async () => { await write.opened; return null; };
+  const logs: string[] = [];
+  t.mock.method(console, 'error', (...args: unknown[]) => { logs.push(args.map(String).join(' ')); });
+  try {
+    t.mock.timers.enable({ apis: ['Date', 'setTimeout'], now: Date.now() });
+    const spilling = f.spillWithheld('stalled', 'original', h.framework.getStore().currentBranch().name);
+    let settled = false;
+    void spilling.then(() => { settled = true; });
+    t.mock.timers.tick(49);
+    await flushAsync();
+    assert.equal(settled, false);
+    t.mock.timers.tick(1);
+    await flushAsync();
+    assert.equal(settled, true, 'the configured 50 ms, not a multi-second ceiling');
+    assert.deepEqual(await spilling, { path: 'work/tool-results/stalled.txt', unfinished: true });
+    await f.spillWithheld('skipped', 'original', h.framework.getStore().currentBranch().name);
+    assert.ok(logs.some((line) => /stalled/.test(line) && /deadline/.test(line)), logs.join('\n'));
+    assert.ok(logs.some((line) => /skipped/.test(line) && /workspace_unanswered/.test(line)), logs.join('\n'));
+  } finally { write.open(); t.mock.timers.reset(); await h.framework.stop(); }
+});
+
+test('#281 round: the scheduler preserves a wake while a direct compile owns the agent', async () => {
+  const h = await harness([]);
+  const agent = h.framework.getAgent('assistant')!;
+  const compile = gate();
+  const entered = gate();
+  const after = agent.toolResultGuard.afterAnnotations.bind(agent.toolResultGuard);
+  agent.toolResultGuard.afterAnnotations = async (read) => { entered.open(); await compile.opened; return after(read); };
+  (h.membrane as unknown as { stream: () => Promise<NormalizedResponse> }).stream = async () => answer();
+  const f = h.framework as unknown as {
+    pendingRequests: Array<{ agentName: string; reason: string; source: string; timestamp: number }>;
+    processInferenceRequests(): Promise<void>;
+    startAgentStream(): Promise<void>;
+  };
+  let starts = 0;
+  f.startAgentStream = async () => { starts++; };
+  const inference = agent.runInference([]);
+  try {
+    await entered.opened;
+    f.pendingRequests.push({ agentName: 'assistant', reason: 'test', source: 'test', timestamp: Date.now() });
+    await f.processInferenceRequests();
+    assert.equal(starts, 0);
+    assert.equal(f.pendingRequests.length, 1);
+    compile.open();
+    await inference;
+    await f.processInferenceRequests();
+    assert.equal(starts, 1, 'the retained wake is admitted after compilation and inference finish');
+  } finally { compile.open(); await inference; await h.framework.stop(); }
+});
+
+test('#281 round: an exhausted batch starts no new write without claiming a stalled workspace', async () => {
+  const h = await workspaceHarness([]);
+  const f = h.framework as unknown as {
+    spillWithheld(label: string, text: string, branch: string, deadline: number): Promise<unknown>;
+    writeToolResultFile(): Promise<null>;
+  };
+  let writes = 0;
+  f.writeToolResultFile = async () => { writes++; return null; };
+  try {
+    assert.deepEqual(await f.spillWithheld('expired', 'original', h.framework.getStore().currentBranch().name, Date.now() - 1),
+      { skipped: 'batch_deadline' });
+    assert.equal(writes, 0);
+  } finally { await h.framework.stop(); }
+});
+
+test('#281 round: an inline spill names the readable tree file and traces its failed disk copy', async () => {
+  const h = await workspaceHarness([], { autoMaterialize: true });
+  writeFileSync(join(h.mountDir, 'tool-results'), 'not a directory');
+  const traces: Array<{ type: string; path?: string }> = [];
+  h.framework.onTrace((event) => traces.push(event as { type: string; path?: string }));
+  try {
+    const f = h.framework as unknown as {
+      spillOrTruncate(text: string, cap: number, label: string): Promise<{ text: string; filePath: string | null }>;
+    };
+    const result = await f.spillOrTruncate('original'.repeat(30), 20, 'inline');
+    assert.equal(result.filePath, 'work/tool-results/inline.txt');
+    assert.match(result.text, /work\/tool-results\/inline.txt/);
+    const file = await h.workspace.readBinary(result.filePath!);
+    assert.ok('data' in file);
+    assert.equal(file.data.toString(), 'original'.repeat(30));
+    assert.ok(traces.some((t) => t.type === 'tool:spill_failed' && t.path === result.filePath));
+  } finally { await h.framework.stop(); }
+});
+
+test('#281 round: an already-aborted direct call never reaches membrane', async () => {
+  const h = await harness([]);
+  let calls = 0;
+  (h.membrane as unknown as { stream: () => Promise<NormalizedResponse> }).stream = async () => { calls++; return answer(); };
+  try {
+    const controller = new AbortController();
+    controller.abort();
+    const result = await h.framework.getAgent('assistant')!.runInference([], undefined, { signal: controller.signal });
+    assert.equal(result.aborted, true);
+    assert.equal(calls, 0);
+  } finally { await h.framework.stop(); }
+});

From a2824e72e508ff6445710bae95c32c155aa8d92e Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Tue, 13 Oct 2026 03:40:32 -0400
Subject: [PATCH 13/16] fix(guard): take request ownership out of this change;
 a restart is a new lifecycle; a batch's deadline runs from its arrival

From a review of the round before:

- The compile mark (a private flag, its isCompilingRequest getter, the
  scheduler's check and the refusal of direct inference while streaming)
  is taken out. A check before a turn's awaits can't establish who owns
  the start after them, and the refused-start catches reset the agent
  whoever owns it, so the mark made that reset reachable during a direct
  call's compile wait. Concurrent direct and scheduled starts on one Agent
  were not safe before this change either (an Agent compiles while its
  status reads idle); the docs and changelog say this change doesn't make
  them safe, that the annotation wait lengthens the window, and that
  abortInference() returns false during a direct call's initial assembly.
- The direct API reads its unguarded tool results once, after the first
  compile, and sends the same ones with the refusal retry, which is
  assembled while the agent is inferring.
- start() begins a new lifecycle generation, and withheld spills close
  for the generation a stop() ends, so a restart has them open whatever
  order the earlier stop finishes in. A turn compiled across a stop and a
  start is dropped with a line saying why.
- A batch's deadline is taken when the batch is queued, not when the
  batches ahead of it finish, so a request waiting on a chain of batches
  waits at most one deadline past the latest one's arrival.
- A stall's skipped spills are logged once, and counted when it clears.
- A write that fails after its tree entry is set says what failed: its
  disk copy refused, or the rest of the write after the entry ("Stored ...
  in Chronicle, but the rest of the write failed"), still inChronicle. The
  spill's trace and log say the same, and the comments say the entry
  stays on the branch that was current when it was set.
- The RFC-005 reference fetcher's writer takes an inChronicle file as
  saved and names it.

Tests: the turn begun after a restart drives (a control for the dropped
one) and the dropped one's line; a batch's deadline taken at queue time;
one log line per stall with its count; the trace's error field, its
200-character cut and its fallback; a throw recording the intent after
the entry; the reference writer; a real post-entry failure through
save_recent_image. The ownership tests go with the mark, and test titles
lose their round prefix. Removing each piece fails a test (seven
removals). The unguarded results' reuse on the retry has no catcher: no
supported call sequence combines unguarded results with the guard's
retry.
---
 .../guard-withheld-names-original.fixed.md    |   7 +-
 docs/tool-result-guard.md                     |   8 +-
 src/agent.ts                                  | 210 ++++++++----------
 src/framework.ts                              |  67 ++++--
 src/modules/workspace/index.ts                |  34 +--
 src/tool-result-guard.ts                      |   7 +-
 test/save-recent-image.test.ts                |  26 ++-
 test/tool-result-guard.test.ts                | 195 +++++++++-------
 8 files changed, 310 insertions(+), 244 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 87ca1da61..4fec02da2 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -56,7 +56,6 @@
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
 
 - With `maintenanceIntervalMs: 0`, periodic retries of retained guards are disabled; stop still retries them. A failing audit record blocks later queued edits and their compression holds until its write succeeds. Shutdown reports an error if that retry still fails.
-- A framework-driven turn that compiled across stop is discarded before driving its stream, even if the framework has restarted. Restart reopens withheld spills. Direct Agent calls remain governed by their caller's abort signal; a refusal retry checks that signal again after waiting for annotations. Unguarded results are read after compilation, including on the retry.
-- `save_recent_image` reports a tree-only write as saved, including its path, size, MIME type, and `diskCopyError`. A later failure in a multi-image save includes that file among the already-saved paths.
-
-- `Agent.isCompilingRequest` is a read-only getter for the framework scheduler to keep a queued wake while request assembly owns the agent. Both direct and streaming entry points reject overlapping starts, and a failed compile releases that ownership. Existing public status values and request previews are unchanged.
+- A framework-driven turn that compiled across stop is discarded before driving its stream, with a line saying why, even if the framework has restarted. A restart starts a new lifecycle, with withheld spills open. Direct Agent calls remain governed by their caller's abort signal; a refusal retry checks that signal again after waiting for annotations. The direct API reads its unguarded tool results once, after the first compile, and sends the same ones with the refusal retry.
+- Concurrent starts on one Agent, a direct inference call beside a framework-driven turn, are not made safe by this change: an Agent compiles while its status still reads idle, as before, and the annotation wait lengthens that window by up to the batch's deadline. `abortInference()` returns false during a direct call's initial assembly.
+- `save_recent_image` reports a tree-only write as saved, including its path, size, MIME type, `inChronicle` and `diskCopyError`. A later failure in a multi-image save includes that file among the already-saved paths. An RFC-005 reference fetched to such a file names it.
diff --git a/docs/tool-result-guard.md b/docs/tool-result-guard.md
index 1f22c89b9..d7e27cd81 100644
--- a/docs/tool-result-guard.md
+++ b/docs/tool-result-guard.md
@@ -167,9 +167,9 @@ Otherwise the stub names the guard's audit record, for an operator:
   audit record and the logs;
 - when the write is still under way at its batch's deadline: "Its result was still being written to workspace file … when this note was made; if that file is missing, it is kept in the guard's audit record …".
 
-Each batch has one 30-second deadline, starting when its annotation begins. Each successive write uses the remaining time. Once the deadline passes, the request can carry the unfinished-write notice; later results in the batch name the audit record. The underlying write continues independently, including after stop, and may finish or fail later. A deadline that fires logs the file's path to stderr. While any write remains overdue, new withheld spills are skipped as `workspace_unanswered` and logged. A write that never settles keeps that gate closed for the process lifetime. Other batches can start writes before the first deadline fires, and each such batch uses its own deadline. This bound covers withheld spills; the inline cap's original spill has no deadline.
+Each batch has one 30-second deadline, starting when the batch is queued, so a request waiting on a chain of batches waits at most one deadline past the latest one's arrival. Each successive write uses the remaining time. Once the deadline passes, the request can carry the unfinished-write notice; later results in the batch name the audit record. The underlying write continues, and may finish or fail later; stop() waits for the workspace's own turns, which such a write holds, until its teardown timeout. A deadline that fires logs the file's path to stderr. While any write remains overdue, new withheld spills are skipped as `workspace_unanswered`, logged once for the stall and counted when it clears. A write that never settles keeps that gate closed for the process lifetime. Other batches can start writes before the first deadline fires, each within its own deadline. This bound covers withheld spills; the inline cap's original spill has no deadline.
 
-A file whose tree entry was set is readable through the workspace's tools even if its disk copy fails or throws. `WorkspaceModule.writeBinary` reports `data: { inChronicle: true }` for that outcome. Both withheld stubs and inline truncation notes name the tree file, while stderr and `tool:spill_failed` report the disk-copy failure. `save_recent_image` also counts that file as saved, with its path, size, MIME type, and `diskCopyError` in the saved receipt.
+A file whose tree entry was set is readable through the workspace's tools, on the branch that was current when the entry was set, even if the rest of its write fails: its disk copy refused, or a throw after the entry. `WorkspaceModule.writeBinary` reports `data: { inChronicle: true }` for that outcome. Both withheld stubs and inline truncation notes name the tree file, while stderr and `tool:spill_failed` report the failure (the workspace's own `workspace:materialize-failed` event is emitted only for a refused push). `save_recent_image` also counts that file as saved, with its path, size, MIME type, `inChronicle` and `diskCopyError` in the saved receipt, and an RFC-005 reference fetched to such a file names it.
 
 When saving the staged audit record itself had failed as the result arrived,
 the stub says the result went to the audit record "though saving that record
@@ -216,9 +216,9 @@ or a direct API call retries the queue first, and fails while the edit keeps
 failing, as it does for a failing acceptance edit.
 Requests sent by the framework or the direct Agent inference API are compiled after the guard's annotations finish, including the refusal retry. A conversation fork also waits before compiling its template's seed. A preview, including public `compileContext()`, does not wait and can show a stub before its place is added.
 
-During real request assembly, a private compilation mark prevents overlapping direct and streaming starts. The read-only `Agent.isCompilingRequest` getter lets the framework scheduler keep a queued wake until compilation ends. The public status values stay unchanged. An assembly failure releases that ownership; ready tool results remain available for another attempt. The direct API reads unguarded results after each compile and checks an abort signal again after the refusal retry's annotation wait.
+Concurrent starts on one Agent, a direct inference call beside a framework-driven turn, are not made safe here: an Agent compiles its request while its status still reads idle (or ready), as before this change, and the wait for annotations lengthens that window, by up to the batch's deadline. `abortInference()` returns false during a direct call's initial assembly; a caller's own abort signal is checked before the request is sent, and again after the refusal retry's annotation wait. The direct API reads its unguarded tool results once, after the first compile, and sends the same ones with the refusal retry.
 
-At stop, the framework lets running annotations finish while the workspace is up. An annotation that starts after that drain writes no file and is saved before the store closes. A framework-driven turn that compiled across stop is discarded before its stream is driven, even if the same framework has since restarted. Restart reopens withheld spills. These lifecycle gates cover framework-driven turns; direct Agent calls use their caller's abort signal.
+At stop, the framework lets running annotations finish while the workspace is up. An annotation that starts after that drain writes no file and is saved before the store closes. A framework-driven turn that compiled across stop is discarded before its stream is driven, even if the same framework has since restarted. A restart starts a new lifecycle, with withheld spills open. These lifecycle gates cover framework-driven turns; direct Agent calls use their caller's abort signal.
 
 For example, an operator can inspect records without changing the agent's
 view:
diff --git a/src/agent.ts b/src/agent.ts
index 6ba2354e5..5dd7c3d45 100644
--- a/src/agent.ts
+++ b/src/agent.ts
@@ -113,8 +113,6 @@ export class Agent {
   readonly sameRoundThinkTextPolicy: AgentConfig['sameRoundThinkTextPolicy'];
 
   private _state: AgentState = { status: 'idle' };
-  /** Owns request assembly while retaining any ready tool results underneath. */
-  private compilingRequest = false;
   private _inferenceStartedAt = 0;
   private _streamId = 0;
   /** kv-unified receipt flights opened by the CURRENT activation and not yet
@@ -188,11 +186,6 @@ export class Agent {
     return this._state;
   }
 
-  /** The framework scheduler keeps a wake queued while this agent is
-   * assembling a request. This is compilation ownership, not a replacement
-   * for the agent's public status. */
-  get isCompilingRequest(): boolean { return this.compilingRequest; }
-
   /**
    * Monotonically increasing stream generation counter.
    * Used to guard stale driveStream handlers after a budget restart.
@@ -653,9 +646,6 @@ export class Agent {
     budget?: TokenBudget,
     options?: InferenceOptions
   ): Promise<InferenceResult> {
-    if (this.compilingRequest || this._state.status === 'streaming') {
-      throw new Error(`Agent ${this.name} cannot run inference in state ${this.compilingRequest ? 'compiling' : this._state.status}`);
-    }
     if (this._state.status === 'inferring') {
       throw new Error(`Agent ${this.name} is already inferring`);
     }
@@ -686,14 +676,16 @@ export class Agent {
     // that began during the compile, and after a stub edit that failed has
     // been retried; one whose store still fails is compiled as the bare
     // notice.
+    let unguardedResults: ReturnType<Agent['buildToolResultMessages']> | undefined;
     const assemble = async (): Promise<NormalizedRequest> => {
       const { messages, systemInjections } = await this.toolResultGuard.afterAnnotations(
         () => this.compileWithInjections(budget, injections));
-      // Read after the awaited compile: results may have become ready while
-      // it was running. A retry takes a fresh read too.
-      if (this._state.status === 'ready' && !guardedResults) {
-        messages.push(...this.buildToolResultMessages(this._state.toolResults));
-      }
+      // Read once, after the first compile, since results may have become
+      // ready while it ran; the refusal retry, assembled while the agent is
+      // inferring, sends the same ones.
+      unguardedResults ??= this._state.status === 'ready' && !guardedResults
+        ? this.buildToolResultMessages(this._state.toolResults) : [];
+      messages.push(...unguardedResults);
       return {
         messages: this.toolResultGuard.prepareRequest(messages, true),
         system: this.buildSystemPrompt(systemInjections),
@@ -708,13 +700,7 @@ export class Agent {
         assistantParticipant: this.name,
       };
     };
-    let request: NormalizedRequest;
-    this.compilingRequest = true;
-    try {
-      request = await assemble();
-    } finally {
-      this.compilingRequest = false;
-    }
+    const request = await assemble();
 
     const abortController = new AbortController();
     if (options?.signal) {
@@ -955,103 +941,99 @@ export class Agent {
     compressionTools: ToolDefinition[] = availableTools,
     options: ActivationRequestOptions = {},
   ): Promise<StartStreamResult> {
-    if (this.compilingRequest || this._state.status !== 'idle') {
-      throw new Error(`Agent ${this.name} cannot start stream in state ${this.compilingRequest ? 'compiling' : this._state.status}`);
+    if (this._state.status !== 'idle') {
+      throw new Error(`Agent ${this.name} cannot start stream in state ${this._state.status}`);
     }
-    this.compilingRequest = true;
-    try {
-      // Retry accepted history edits before assembling a real request. Pure
-      // preview/compile entry points must not perform these writes.
-      this.toolResultGuard.flushUnrecorded();
-
-      // A new activation supersedes every receipt flight the previous one left
-      // open. Membrane fires the kv-unified wire receipt per provider attempt,
-      // BEFORE the adapter call; only that attempt's usage event settles it.
-      // When the attempt dies without usage (transport error, idle timeout,
-      // framework cancel for a budget restart or endTurn) the flight stays open
-      // until the old driveStream's `finally` runs — and every successor path
-      // (error-policy retry, budget restart, the next wake after an abort)
-      // starts the new stream BEFORE that `finally`. The successor's first
-      // receipt then met the ledger's single-flight guard and failed the
-      // recovery itself: "kv-unified submission devops:46:…:4 is still in
-      // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
-      this.failOpenKvSubmissions();
-
-      this._streamId++;
-      this._inferenceStartedAt = Date.now();
-      this.lastStreamInputTokens = 0;
-      // Reset the cache-inclusive counters too: a new stream must not inherit
-      // the prior stream's window size — on the physical-window restart path
-      // that inherited value IS the oversized number that caused the restart,
-      // and projecting on it before this stream's first usage event would
-      // restart again (loop). The `> 0` guard downstream means "no usage
-      // observed on THIS stream yet" only because of this reset.
-      this.lastStreamRealInputTokens = 0;
-      this.lastStreamOutputTokens = 0;
-
-      // Compiled only once each withheld stub's annotation has finished,
-      // including one that began during the compile, and after a stub edit that
-      // failed has been retried (see afterAnnotations).
-      const request = await this.toolResultGuard.afterAnnotations(
-        () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
-      request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
-
-      const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
-        .getStrategy?.() as {
-        beginKvUnifiedSubmission?: (args: { submissionId: string; requestHash: string; layoutHash: string }) => void;
-        isKvUnifiedEnabled?: () => boolean;
-      };
-      const kvEnabled = receiptAware?.isKvUnifiedEnabled?.() === true;
-      const kvQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> = [];
-      let kvCall = 0;
-      if (kvEnabled) {
-        this.kvOpenQueue = kvQueue;
-        const layoutHash = stableHash(request.messages);
-        const kvRequest = request as NormalizedRequest & KvUnifiedRequestHooks;
-        kvRequest.onCacheWireReceipt = (receipt) => {
-          const submissionId = `${this.name}:${this._streamId}:${Date.now()}:${kvCall++}`;
-          receiptAware.beginKvUnifiedSubmission!({
-            submissionId,
-            requestHash: receipt.requestHash,
-            layoutHash,
-          });
-          kvQueue.push({ submissionId, wireReceipt: receipt });
-        };
-      }
 
-      const agent = this;
-      const stream = this.membrane.streamYielding(request, {
-        emitTokens: true,
-        emitBlocks: false,
-        emitUsage: true,
-        // Retry a content-policy refusal at the provider seam rather than at
-        // the framework level: membrane replays the SAME request immediately
-        // (cache-warm), where a framework-level requeue would recompile and
-        // land a different window. The framework's driveStream handles the
-        // resulting `retrying` event by discarding the abandoned attempt.
-        // Membrane reads this per physical round, including after settings
-        // tools run. A guarded result must reach the host on its FIRST refusal;
-        // never spend retries resubmitting unchanged guarded content.
-        get refusalRetries() {
-          return agent.toolResultGuard.hasSubmittedPending || agent.toolResultGuard.recovering
-            ? 0 : agent.refusalHandling?.retries ?? 0;
-        },
-      });
+    // Retry accepted history edits before assembling a real request. Pure
+    // preview/compile entry points must not perform these writes.
+    this.toolResultGuard.flushUnrecorded();
 
-      this._state = { status: 'streaming', stream };
-      return {
-        stream,
-        request,
-        ...(kvEnabled
-          ? {
-              takeKvSubmission: () => kvQueue.shift(),
-              drainKvSubmissionIds: () => kvQueue.splice(0).map((item) => item.submissionId),
-            }
-          : {}),
+    // A new activation supersedes every receipt flight the previous one left
+    // open. Membrane fires the kv-unified wire receipt per provider attempt,
+    // BEFORE the adapter call; only that attempt's usage event settles it.
+    // When the attempt dies without usage (transport error, idle timeout,
+    // framework cancel for a budget restart or endTurn) the flight stays open
+    // until the old driveStream's `finally` runs — and every successor path
+    // (error-policy retry, budget restart, the next wake after an abort)
+    // starts the new stream BEFORE that `finally`. The successor's first
+    // receipt then met the ledger's single-flight guard and failed the
+    // recovery itself: "kv-unified submission devops:46:…:4 is still in
+    // flight" (devops agent, 2026-09-16 07:33Z, no provider error logged).
+    this.failOpenKvSubmissions();
+
+    this._streamId++;
+    this._inferenceStartedAt = Date.now();
+    this.lastStreamInputTokens = 0;
+    // Reset the cache-inclusive counters too: a new stream must not inherit
+    // the prior stream's window size — on the physical-window restart path
+    // that inherited value IS the oversized number that caused the restart,
+    // and projecting on it before this stream's first usage event would
+    // restart again (loop). The `> 0` guard downstream means "no usage
+    // observed on THIS stream yet" only because of this reset.
+    this.lastStreamRealInputTokens = 0;
+    this.lastStreamOutputTokens = 0;
+
+    // Compiled only once each withheld stub's annotation has finished,
+    // including one that began during the compile, and after a stub edit that
+    // failed has been retried (see afterAnnotations).
+    const request = await this.toolResultGuard.afterAnnotations(
+      () => this.buildActivationRequest(availableTools, injections, budget, compressionTools, options));
+    request.messages = this.toolResultGuard.prepareRequest(request.messages, true);
+
+    const receiptAware = (this.contextManager as unknown as { getStrategy?: () => unknown })
+      .getStrategy?.() as {
+      beginKvUnifiedSubmission?: (args: { submissionId: string; requestHash: string; layoutHash: string }) => void;
+      isKvUnifiedEnabled?: () => boolean;
+    };
+    const kvEnabled = receiptAware?.isKvUnifiedEnabled?.() === true;
+    const kvQueue: Array<{ submissionId: string; wireReceipt: CacheWireReceipt }> = [];
+    let kvCall = 0;
+    if (kvEnabled) {
+      this.kvOpenQueue = kvQueue;
+      const layoutHash = stableHash(request.messages);
+      const kvRequest = request as NormalizedRequest & KvUnifiedRequestHooks;
+      kvRequest.onCacheWireReceipt = (receipt) => {
+        const submissionId = `${this.name}:${this._streamId}:${Date.now()}:${kvCall++}`;
+        receiptAware.beginKvUnifiedSubmission!({
+          submissionId,
+          requestHash: receipt.requestHash,
+          layoutHash,
+        });
+        kvQueue.push({ submissionId, wireReceipt: receipt });
       };
-    } finally {
-      this.compilingRequest = false;
     }
+
+    const agent = this;
+    const stream = this.membrane.streamYielding(request, {
+      emitTokens: true,
+      emitBlocks: false,
+      emitUsage: true,
+      // Retry a content-policy refusal at the provider seam rather than at
+      // the framework level: membrane replays the SAME request immediately
+      // (cache-warm), where a framework-level requeue would recompile and
+      // land a different window. The framework's driveStream handles the
+      // resulting `retrying` event by discarding the abandoned attempt.
+      // Membrane reads this per physical round, including after settings
+      // tools run. A guarded result must reach the host on its FIRST refusal;
+      // never spend retries resubmitting unchanged guarded content.
+      get refusalRetries() {
+        return agent.toolResultGuard.hasSubmittedPending || agent.toolResultGuard.recovering
+          ? 0 : agent.refusalHandling?.retries ?? 0;
+      },
+    });
+
+    this._state = { status: 'streaming', stream };
+    return {
+      stream,
+      request,
+      ...(kvEnabled
+        ? {
+            takeKvSubmission: () => kvQueue.shift(),
+            drainKvSubmissionIds: () => kvQueue.splice(0).map((item) => item.submissionId),
+          }
+        : {}),
+    };
   }
 
   /** Close every kv-unified receipt flight the previous activation left
diff --git a/src/framework.ts b/src/framework.ts
index f1e9b765f..3a7609609 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -1988,7 +1988,10 @@ export class AgentFramework {
 
     this.running = true;
     this.providerAdmissionClosed = false;
-    this.guardSpillsClosed = false;
+    // A new lifecycle: a turn compiled before an earlier stop() never drives,
+    // and withheld spills, closed for the generation a stop ended, are open
+    // for this one.
+    this.lifecycleGeneration++;
     this.loopPromise = this.runLoop();
 
     // Start periodic sync timer (if enabled)
@@ -2052,6 +2055,9 @@ export class AgentFramework {
     this.ackDeferredWrites();
     this.providerAdmissionClosed = true;
     this.lifecycleGeneration++;
+    // The generation this stop ends; withheld spills close for it alone, so a
+    // start() made before this stop finishes reopens them for its own.
+    const stoppingGeneration = this.lifecycleGeneration;
     this.queue.close();
     this.tuneOutCoordinator?.stop();
 
@@ -2128,7 +2134,7 @@ export class AgentFramework {
     // workspace: its stub names the audit record. A write that was past its
     // deadline is not waited for, and may still finish or fail after the
     // modules stop.
-    this.guardSpillsClosed = true;
+    this.guardSpillsClosedFor = stoppingGeneration;
 
     // Stop modules and MCPL servers in parallel
     const shutdownPromises: Promise<void>[] = [this.moduleRegistry.stopAll(teardownTimeoutMs)];
@@ -2671,7 +2677,14 @@ export class AgentFramework {
           if (!mount) return null;
           const path = `${mount}/refs/${fileName}`;
           const res = await workspace.writeBinary(path, data, mimeType);
-          return res.success ? path : null;
+          if (res.success) return path;
+          // Stored, with its disk copy failed: the workspace's tools read it
+          // from the tree, so the reference is fetched to that path.
+          if ((res.data as { inChronicle?: boolean } | undefined)?.inChronicle === true) {
+            console.error(`[refs] ${path} is in the workspace's Chronicle tree, but the rest of its write failed: ${res.error ?? 'unknown error'}`);
+            return path;
+          }
+          return null;
         },
       );
     }
@@ -2858,12 +2871,16 @@ export class AgentFramework {
    *  write is started. Several can be, when writes of different agents'
    *  batches stalled together. */
   private readonly stalledSpills = new Set<Promise<void>>();
+  /** Withheld spills skipped since the current stall began. */
+  private stallSkips = 0;
   /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
-  /** Set once stop() has let the running annotations finish: a withheld
-   *  original is then no longer written to a workspace that is stopping, and
-   *  its stub names the audit record. */
-  private guardSpillsClosed = false;
+  /** The lifecycle generation whose stop() has let the running annotations
+   *  finish: a withheld original is then no longer written to a workspace
+   *  that is stopping, and its stub names the audit record. A later start()
+   *  has a generation of its own, so its spills are open whatever order the
+   *  earlier stop finishes in. */
+  private guardSpillsClosedFor: number | null = null;
 
   /** A new agent's guard: its persisted setting, the tool-results spill its
    *  withheld originals are written to, and the set stop() waits on
@@ -8542,7 +8559,7 @@ export class AgentFramework {
         requests = [...providerCooldown.heldRequests, ...requests];
       }
 
-      // Skip if agent is busy (compiling, inferring, streaming, or waiting for tools) —
+      // Skip if agent is busy (inferring, streaming, or waiting for tools) —
       // or if a turn is alive at all (activeTurnTokens): the state machine
       // goes idle at endTurn's reset while driveStream teardown is still
       // pending, and a successor turn dequeued in that gap compiles while the
@@ -8608,7 +8625,7 @@ export class AgentFramework {
       // Truthiness, not `!== null`: prototype-built harnesses (and any field
       // added later) leave the slot undefined, which must read as "not held".
       const surgeryHeld = !!this.surgeryHold;
-      if (surgeryHeld || providerPrimaryWaiting || turnAlive || agent.isCompilingRequest || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
+      if (surgeryHeld || providerPrimaryWaiting || turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
         // Re-queue requests, but warn if they've been pending too long.
         // Suppressed while quiesced: a drain-phase busy requeue is expected,
         // not a wedge tell.
@@ -9667,6 +9684,10 @@ export class AgentFramework {
       // Membrane's yielding stream starts its request when it is first
       // iterated, so cancelling it here, before driveStream, sends nothing.
       if (this.agents.get(agent.name) !== agent || this.providerAdmissionClosed || lifecycle !== this.lifecycleGeneration) {
+        console.error(`[turn] ${agent.name}: a turn compiled while ${
+          this.agents.get(agent.name) !== agent ? 'the agent was replaced or removed'
+            : this.providerAdmissionClosed ? 'the framework was stopping'
+              : 'the framework was stopped and started again'} is dropped before it sends anything`);
         stream.cancel();
         agent.cancelStream();
         if (this.agents.get(agent.name) === agent) {
@@ -12103,11 +12124,15 @@ export class AgentFramework {
    */
   private async spillWithheld(label: string, text: string, branch: string,
     deadline = Date.now() + this.withheldSpillDeadlineMs): Promise<WithheldSpill> {
-    if (this.guardSpillsClosed) return null;
+    if (this.guardSpillsClosedFor === this.lifecycleGeneration) return null;
     const place = this.toolResultFilePlace(label);
     if (!place) return null;
     if (this.stalledSpills.size > 0) {
-      console.error(`[spill] ${place.path} skipped: workspace_unanswered (${this.stalledSpills.size} withheld write(s) past deadline)`);
+      // Said once per stall, with the count when it clears, so a stalled
+      // workspace doesn't write a line for every result it can't take.
+      if (this.stallSkips++ === 0) {
+        console.error(`[spill] withheld originals are skipped as workspace_unanswered while ${this.stalledSpills.size} write(s) past their deadline are under way (first: ${place.path})`);
+      }
       return { skipped: 'workspace_unanswered' };
     }
     const remaining = deadline - Date.now();
@@ -12121,7 +12146,13 @@ export class AgentFramework {
       timer = setTimeout(() => {
         // Marked as the deadline passes, before anything else runs, so no
         // spill that starts after it finds the workspace answering.
-        const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => this.stalledSpills.delete(stalled));
+        const stalled: Promise<void> = write.then(() => {}, () => {}).finally(() => {
+          this.stalledSpills.delete(stalled);
+          if (this.stalledSpills.size === 0 && this.stallSkips > 0) {
+            console.error(`[spill] the workspace answered again; ${this.stallSkips} withheld original(s) were skipped as workspace_unanswered meanwhile`);
+            this.stallSkips = 0;
+          }
+        });
         this.stalledSpills.add(stalled);
         console.error(`[spill] ${place.path} still being written at the withheld batch deadline`);
         resolve('late');
@@ -12161,13 +12192,15 @@ export class AgentFramework {
       const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain', { branch });
       if (result.success) return { path };
       // The file is in the workspace's Chronicle tree, where its tools read
-      // it, and only its copy on disk failed: it is written for every reader
-      // the stub or the truncation note sends there. The workspace
-      // reports the disk failure itself (workspace:materialize-failed).
+      // it, and the rest of the write failed (its copy on disk, or something
+      // after the entry was set): it is written for every reader the stub or
+      // the truncation note sends there. The workspace emits
+      // workspace:materialize-failed only for a refused push, so the failure
+      // is traced here too.
       if ((result.data as { inChronicle?: boolean } | undefined)?.inChronicle === true) {
-        const error = (result.error ?? 'disk copy failed').slice(0, 200);
+        const error = (result.error ?? 'the rest of the write failed').slice(0, 200);
         this.emitTrace({ type: 'tool:spill_failed', label: safeLabel, path, contentLength: content.length, error });
-        console.error(`[spill] ${path} is in the workspace's Chronicle tree, but its copy on disk failed: ${error}`);
+        console.error(`[spill] ${path} is in the workspace's Chronicle tree, but the rest of its write failed: ${error}`);
         return { path };
       }
       // Declined, not failed: the store left the branch the file is for, so
diff --git a/src/modules/workspace/index.ts b/src/modules/workspace/index.ts
index 7920b2c31..eeadb6ca2 100644
--- a/src/modules/workspace/index.ts
+++ b/src/modules/workspace/index.ts
@@ -1417,9 +1417,11 @@ export class WorkspaceModule implements Module {
    * withheld original this way, for the branch its stub is on
    * (agent-framework #277).
    *
-   * A write whose tree entry is set but whose copy on disk fails returns
-   * success false with `data: { inChronicle: true }`: the workspace's tools
-   * read the file from the tree, so it is there for them.
+   * A write whose tree entry is set but that then fails returns success
+   * false with `data: { inChronicle: true }`: its copy on disk was refused, or
+   * something after the entry (recording its intent, the event, the push)
+   * threw. The workspace's tools read the file from the tree, so it is there
+   * for them, on the branch that was current when the entry was set.
    */
   async writeBinary(
     mountPrefixedPath: string,
@@ -1456,25 +1458,21 @@ export class WorkspaceModule implements Module {
       }
       const blobHash = store.storeBlob(data, mimeType);
       let committed = false;
-      let materializeError: string | null;
+      let failure: string | null;
       try {
-        materializeError = await this.commitToolChange(mount, relativePath,
+        const materializeError = await this.commitToolChange(mount, relativePath,
           { kind: 'set', blobHash, size: data.byteLength }, () => { committed = true; });
+        failure = materializeError === null ? null
+          : `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`;
       } catch (error) {
         if (!committed) throw error;
-        materializeError = error instanceof Error ? error.message : String(error);
+        failure = `Stored "${mountPrefixedPath}" in Chronicle, but the rest of the write failed: ${error instanceof Error ? error.message : String(error)}.`;
       }
-      if (materializeError !== null) {
+      if (failure !== null) {
         // The file is in the Chronicle tree, where the workspace's tools read
-        // it; only its copy on disk failed. `inChronicle` lets a caller that
-        // needs the file readable tell this from a write that never happened
-        // (agent-framework #281).
-        return {
-          success: false,
-          error: `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`,
-          isError: true,
-          data: { inChronicle: true },
-        };
+        // it. `inChronicle` lets a caller that needs the file readable tell
+        // this from a write that never happened (agent-framework #281).
+        return { success: false, error: failure, isError: true, data: { inChronicle: true } };
       }
       return {
         success: true,
@@ -1937,7 +1935,9 @@ export class WorkspaceModule implements Module {
     if (change.kind === 'set') {
       store.treeSet(mount.treeStateId, relativePath, { blobHash: change.blobHash, size: change.size, mode: change.mode ?? 0o644 });
       // A later intent update or disk push can throw; the tree entry is
-      // already readable, even if the active branch changes during the push.
+      // already set, on the branch current now. If the active branch changes
+      // during the push, that branch's tree has the file and the new one may
+      // not.
       onCommitted?.();
       intents.update(relativePath, (cur) => {
         const next = { ...cur };
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 168f9340e..9b0eba100 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -39,7 +39,7 @@ export type WithheldSpiller = (label: string, text: string, branch: string, dead
  *  guard says whether it has work left. */
 export interface WithheldHost {
   spill: WithheldSpiller;
-  /** Absolute deadline for one batch, captured when its annotation starts. */
+  /** Absolute deadline for one batch (Date.now() time), taken when the batch is queued. */
   deadline(): number;
   track(annotation: Promise<void>): void;
   /** Whether the guard is idle (see ToolResultGuard.idle), told after each
@@ -470,12 +470,15 @@ export class ToolResultGuard {
   private annotate(pending: PendingBatch): void {
     const previous = this.annotating ?? Promise.resolve();
     this.annotationsStarted += 1;
+    // The batch's deadline runs from when it's queued, not from when the
+    // batches ahead of it finish, so a request waiting on a chain of batches
+    // waits at most one deadline past the latest one's arrival.
+    const deadline = this.host?.deadline() ?? Infinity;
     const run = previous.then(async () => {
       // Set once the stub's edit is queued with the hold: the queue releases
       // it when the edit lands or is superseded.
       let holdQueued = false;
       try {
-        const deadline = this.host?.deadline() ?? Infinity;
         const date = new Date().toISOString().slice(0, 10);
         // A file is named by its batch and its place in the batch, ahead of
         // anything the writer may cut or substitute: results of one batch
diff --git a/test/save-recent-image.test.ts b/test/save-recent-image.test.ts
index 7ca516bb0..83cac62e2 100644
--- a/test/save-recent-image.test.ts
+++ b/test/save-recent-image.test.ts
@@ -817,8 +817,32 @@ describe('ToolImageLedger', () => {
   });
 });
 
+it('a save whose write fails after its tree entry, through the workspace itself, is reported saved with its failure', async () => {
+  const h = await startTurn({
+    prefix: 'sri-tree-real-',
+    responses: [
+      [snapCall('call_snap')],
+      [saveCall('call_save', { path: 'files/images.png', index: 0, count: 1 })],
+      done,
+    ],
+    workspace: (workspace) => {
+      const ws = workspace as unknown as { intents: Map<string, { update: (...args: unknown[]) => unknown }> };
+      const intents = [...ws.intents.values()][0];
+      intents.update = () => { throw new Error('injected intent exception'); };
+    },
+  });
+  try {
+    const result = await waitForToolResult(h.framework, 'call_save');
+    const files = saved(result);
+    assert.equal(files.length, 1);
+    assert.equal(files[0].inChronicle, true);
+    assert.match(String(files[0].diskCopyError), /the rest of the write failed: injected intent exception/);
+    assert.ok((await fileBytes(h, String(files[0].path)))?.equals(PNG));
+  } finally { await h.framework.stop(); rmSync(h.tempDir, { recursive: true, force: true }); }
+});
+
 for (const secondFails of [false, true]) {
-  it(`#281 round: a tree-only image save ${secondFails ? 'appears in a later failure receipt' : 'succeeds with a disk-copy warning'}`, async () => {
+  it(`a tree-only image save ${secondFails ? 'appears in a later failure receipt' : 'succeeds with a disk-copy warning'}`, async () => {
     const h = await startTurn({
       prefix: 'sri-tree-only-',
       responses: [
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 25c389be8..8f8c30b1f 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -2474,7 +2474,7 @@ test('#281: writes that stalled together each hold the workspace as unanswered u
     );
     assert.deepEqual([a, b], [{ path: 'work/tool-results/a.txt', unfinished: true }, { path: 'work/tool-results/b.txt', unfinished: true }]);
     gates.get('b')!.open();
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await until(() => (h.framework as unknown as { stalledSpills: Set<unknown> }).stalledSpills.size === 1, 'b settles');
     assert.deepEqual(await framework.spillWithheld('c', 'C', branch), { skipped: 'workspace_unanswered' },
       'one stalled write settling leaves the other holding the workspace');
     gates.get('a')!.open();
@@ -2634,7 +2634,7 @@ test('#281: an annotation that starts while modules stop writes no file, and is
   } finally { await restarted.stop(); }
 });
 
-test('#281 round: an unexpected annotation exception releases its compression hold', async () => {
+test('an unexpected annotation exception releases its compression hold', async () => {
   const r = await compressionRig();
   const branch = r.cm.currentBranch.bind(r.cm);
   try {
@@ -2648,7 +2648,7 @@ test('#281 round: an unexpected annotation exception releases its compression ho
   } finally { r.cm.currentBranch = branch; await r.cm.close(); }
 });
 
-test('#281 round: a throw after treeSet reports the original as readable', async () => {
+test('a throw after treeSet reports the original as readable', async () => {
   const h = await workspaceHarness([], { autoMaterialize: true });
   const ws = h.workspace as unknown as { pushUnlocked: () => Promise<never> };
   const push = ws.pushUnlocked;
@@ -2664,7 +2664,78 @@ test('#281 round: a throw after treeSet reports the original as readable', async
   } finally { ws.pushUnlocked = push; await h.framework.stop(); }
 });
 
-test('#281 round: a throw before treeSet does not claim a readable original', async () => {
+test('a throw from recording the intent after treeSet still reports the original as readable', async () => {
+  const h = await workspaceHarness([]);
+  const ws = h.workspace as unknown as { intents: Map<string, { update: (...args: unknown[]) => unknown }> };
+  const intents = ws.intents.get('work')!;
+  const update = intents.update;
+  try {
+    intents.update = () => { throw new Error('injected intent exception'); };
+    const result = await h.workspace.writeBinary('work/intent.txt', Buffer.from('original'), 'text/plain');
+    assert.equal(result.success, false);
+    assert.equal((result.data as { inChronicle?: boolean })?.inChronicle, true);
+    assert.match(result.error!, /Stored "work\/intent\.txt" in Chronicle, but the rest of the write failed: injected intent exception/);
+    const file = await h.workspace.readBinary('work/intent.txt');
+    assert.ok('data' in file);
+  } finally { intents.update = update; await h.framework.stop(); }
+});
+
+test("the reference fetcher's writer takes a file the tree holds as saved", async () => {
+  const h = await workspaceHarness([], { autoMaterialize: true });
+  const ws = h.workspace as unknown as { pushUnlocked: () => Promise<never> };
+  const push = ws.pushUnlocked;
+  const f = h.framework as unknown as { getReferenceFetcher(): { saveFile: (name: string, data: Buffer, mime: string) => Promise<string | null> } };
+  try {
+    ws.pushUnlocked = async () => { throw new Error('injected push exception'); };
+    const saved = await f.getReferenceFetcher().saveFile('ref.txt', Buffer.from('fetched'), 'text/plain');
+    assert.equal(saved, 'work/refs/ref.txt', 'stored in the tree, so the reference names it');
+  } finally { ws.pushUnlocked = push; await h.framework.stop(); }
+});
+
+test("an inline spill's failed disk copy is traced with its error, cut at 200 characters, or a fallback", async () => {
+  const h = await workspaceHarness([]);
+  const traces: Array<{ type: string; error?: string }> = [];
+  h.framework.onTrace((e) => traces.push(e as never));
+  const f = h.framework as unknown as { writeToolResultFile(label: string, text: string, branch: string): Promise<unknown> };
+  const original = h.workspace.writeBinary.bind(h.workspace);
+  try {
+    for (const error of ['x'.repeat(300), undefined]) {
+      h.workspace.writeBinary = async () => ({ success: false, isError: true, ...(error ? { error } : {}), data: { inChronicle: true } });
+      await f.writeToolResultFile(`label-${error ? 'long' : 'none'}`, 'content', h.framework.getStore().currentBranch().name);
+      const traced = traces.filter((t) => t.type === 'tool:spill_failed').at(-1);
+      assert.ok(traced, 'traced');
+      assert.equal(traced!.error, error ? 'x'.repeat(200) : 'the rest of the write failed');
+    }
+  } finally { h.workspace.writeBinary = original; await h.framework.stop(); }
+});
+
+test("a batch's deadline is taken when it is queued, not when the batches ahead of it finish", async () => {
+  const r = await compressionRig();
+  try {
+    const first = gate();
+    let entered = 0;
+    let taken = 0;
+    r.guard.setHost({
+      deadline: () => { taken++; return Date.now() + 60_000; },
+      spill: async () => { entered++; if (entered === 1) await first.opened; return null; },
+      track: () => {}, idle: () => {},
+    });
+    r.guard.submissionResults([{ toolUseId: 'tu-1', content: r.REAL }]);
+    assert.ok(r.guard.withhold('test-category'));
+    await until(() => entered === 1, 'the first annotation is writing');
+    // A second batch queued behind the first, still writing.
+    r.cm.addMessage('Claude', [{ type: 'tool_use', id: 'tu-2', name: 'search', input: {} }]);
+    r.guard.storeResults([{ type: 'tool_result', toolUseId: 'tu-2', content: 'SECOND' }],
+      [{ toolUseId: 'tu-2', content: 'SECOND' }], []);
+    r.guard.submissionResults([{ toolUseId: 'tu-2', content: 'SECOND' }]);
+    assert.ok(r.guard.withhold('test-category'));
+    assert.equal(taken, 2, "the second batch's deadline was taken when it was queued");
+    first.open();
+    await bounded(r.guard.whenAnnotated(), 'both annotations');
+  } finally { r.cm.close(); }
+});
+
+test('a throw before treeSet does not claim a readable original', async () => {
   const h = await workspaceHarness([]);
   const store = h.framework.getStore();
   const set = store.treeSet.bind(store);
@@ -2675,7 +2746,7 @@ test('#281 round: a throw before treeSet does not claim a readable original', as
   } finally { store.treeSet = set; await h.framework.stop(); }
 });
 
-test('#281 round: abort during the direct refusal retry annotation sends no retry', async () => {
+test('abort during the direct refusal retry annotation sends no retry', async () => {
   const h = await harness([], { toolResultGuard: true });
   const requests: NormalizedRequest[] = [];
   const responses = [calls('one'), refused(), answer()];
@@ -2701,40 +2772,7 @@ test('#281 round: abort during the direct refusal retry annotation sends no retr
   } finally { write.open(); await h.framework.stop(); }
 });
 
-for (const entry of ['direct', 'stream'] as const) {
-  test(`#281 round: ${entry} compilation owns the agent until it succeeds or fails`, async () => {
-    const h = await harness([[answer()]]);
-    const agent = h.framework.getAgent('assistant')!;
-    (h.membrane as unknown as { stream: () => Promise<NormalizedResponse> }).stream = async () => answer();
-    const compile = gate();
-    let entered = false;
-    const after = agent.toolResultGuard.afterAnnotations.bind(agent.toolResultGuard);
-    agent.toolResultGuard.afterAnnotations = async (read) => { entered = true; await compile.opened; return after(read); };
-    const starting = entry === 'direct' ? agent.runInference([]) : agent.startStream([]);
-    try {
-      await until(() => entered, 'compile entered');
-      assert.equal((agent as unknown as { isCompilingRequest: boolean }).isCompilingRequest, true);
-      assert.equal(agent.state.status, 'idle', 'the public status union is unchanged');
-      assert.equal(agent.info.status, 'idle');
-      await assert.rejects(bounded(agent.runInference([]), 'overlapping direct call', 1000), /state compiling/);
-      await assert.rejects(bounded(agent.startStream([]), 'overlapping stream call', 1000), /state compiling/);
-      compile.open();
-      await starting;
-      if (entry === 'stream') {
-        await assert.rejects(agent.runInference([]), /state streaming/);
-        agent.cancelStream();
-      }
-      assert.equal(String(agent.state.status), 'idle');
-      agent.toolResultGuard.afterAnnotations = async () => { throw new Error('compile failed'); };
-      await assert.rejects(entry === 'direct' ? agent.runInference([]) : agent.startStream([]), /compile failed/);
-      assert.equal(String(agent.state.status), 'idle');
-      assert.equal((agent as unknown as { isCompilingRequest: boolean }).isCompilingRequest, false,
-        'failure releases compilation ownership');
-    } finally { compile.open(); await starting; agent.cancelStream(); await h.framework.stop(); }
-  });
-}
-
-test('#281 round: unguarded results are read after the direct compile', async () => {
+test('unguarded results are read after the direct compile', async () => {
   const h = await harness([]);
   const agent = h.framework.getAgent('assistant')!;
   const compile = agent.compileWithInjections.bind(agent);
@@ -2756,7 +2794,7 @@ test('#281 round: unguarded results are read after the direct compile', async ()
   } finally { await h.framework.stop(); }
 });
 
-test('#281 round: stop then start reopens withheld spills', async () => {
+test('stop then start reopens withheld spills', async () => {
   const dir = mkdtempSync(join(tmpdir(), 'guard-restart-')); dirs.push(dir);
   const store = JsStore.openOrCreate({ path: join(dir, 'store') });
   const framework = await AgentFramework.create({ store, membrane: new ScriptMembrane([]).asMembrane(),
@@ -2783,10 +2821,11 @@ test('#281 round: stop then start reopens withheld spills', async () => {
   } finally { await framework.stop(); store.close(); }
 });
 
-test('#281 round: a framework compile from before stop cannot drive after restart', async () => {
+test('a framework compile from before stop cannot drive after restart', async () => {
   const dir = mkdtempSync(join(tmpdir(), 'guard-generation-')); dirs.push(dir);
   const store = JsStore.openOrCreate({ path: join(dir, 'store') });
-  const membrane = new ScriptMembrane([[answer()]]);
+  // One scripted answer for the turn compiled before the stop, one for the turn begun after the restart.
+  const membrane = new ScriptMembrane([[answer()], [answer()]]);
   const framework = await AgentFramework.create({ store, membrane: membrane.asMembrane(),
     agents: [{ name: 'assistant', model: 'test', systemPrompt: 'system' }],
     modules: [], syncIntervalMs: 0, maintenanceIntervalMs: 0 });
@@ -2805,13 +2844,22 @@ test('#281 round: a framework compile from before stop cannot drive after restar
   };
   let starting: Promise<void> | undefined;
   try {
-    starting = (framework as unknown as { startAgentStream(a: typeof agent): Promise<void> }).startAgentStream(agent);
-    await entered.opened;
-    await framework.stop();
-    framework.start();
-    compile.open();
-    await starting;
+    const lines: string[] = [];
+    const error = console.error;
+    console.error = (...args: unknown[]) => { lines.push(args.map(String).join(' ')); };
+    try {
+      starting = (framework as unknown as { startAgentStream(a: typeof agent): Promise<void> }).startAgentStream(agent);
+      await entered.opened;
+      await framework.stop();
+      framework.start();
+      compile.open();
+      await starting;
+    } finally { console.error = error; }
     assert.equal(driven, 0);
+    assert.ok(lines.some((line) => /stopped and started again/.test(line) && /dropped before it sends anything/.test(line)), lines.join('\n'));
+    // A turn begun after the restart is admitted and drives its stream.
+    await (framework as unknown as { startAgentStream(a: typeof agent): Promise<void> }).startAgentStream(agent);
+    await until(() => driven === 1, 'the turn begun after the restart drives');
   } finally { compile.open(); await starting; await framework.stop(); store.close(); }
 });
 
@@ -2820,7 +2868,7 @@ async function flushAsync() {
   for (let i = 0; i < 8; i++) await new Promise<void>((resolve) => setImmediate(resolve));
 }
 
-test('#281 round: slow successful writes share one batch deadline', async (t) => {
+test('slow successful writes share one batch deadline', async (t) => {
   const h = await workspaceHarness([]);
   const f = h.framework as unknown as {
     withheldSpillDeadlineMs: number;
@@ -2863,7 +2911,7 @@ test('#281 round: slow successful writes share one batch deadline', async (t) =>
   } finally { first.open(); second.open(); t.mock.timers.reset(); await h.framework.stop(); }
 });
 
-test('#281 round: a withheld deadline and an unanswered skip are observable', async (t) => {
+test('a withheld deadline and an unanswered skip are observable', async (t) => {
   const h = await workspaceHarness([]);
   const f = h.framework as unknown as {
     withheldSpillDeadlineMs: number;
@@ -2887,42 +2935,19 @@ test('#281 round: a withheld deadline and an unanswered skip are observable', as
     await flushAsync();
     assert.equal(settled, true, 'the configured 50 ms, not a multi-second ceiling');
     assert.deepEqual(await spilling, { path: 'work/tool-results/stalled.txt', unfinished: true });
-    await f.spillWithheld('skipped', 'original', h.framework.getStore().currentBranch().name);
-    assert.ok(logs.some((line) => /stalled/.test(line) && /deadline/.test(line)), logs.join('\n'));
-    assert.ok(logs.some((line) => /skipped/.test(line) && /workspace_unanswered/.test(line)), logs.join('\n'));
+    for (const label of ['skipped-1', 'skipped-2', 'skipped-3']) {
+      assert.deepEqual(await f.spillWithheld(label, 'original', h.framework.getStore().currentBranch().name), { skipped: 'workspace_unanswered' });
+    }
+    assert.ok(logs.some((line) => /still being written/.test(line) && /deadline/.test(line)), logs.join('\n'));
+    // One line for the stall's skips, not one per skipped result.
+    assert.equal(logs.filter((line) => /workspace_unanswered/.test(line)).length, 1, logs.join('\n'));
+    write.open();
+    t.mock.timers.reset();
+    await until(() => logs.some((line) => /answered again; 3 withheld original\(s\) were skipped/.test(line)), 'the count when the stall clears');
   } finally { write.open(); t.mock.timers.reset(); await h.framework.stop(); }
 });
 
-test('#281 round: the scheduler preserves a wake while a direct compile owns the agent', async () => {
-  const h = await harness([]);
-  const agent = h.framework.getAgent('assistant')!;
-  const compile = gate();
-  const entered = gate();
-  const after = agent.toolResultGuard.afterAnnotations.bind(agent.toolResultGuard);
-  agent.toolResultGuard.afterAnnotations = async (read) => { entered.open(); await compile.opened; return after(read); };
-  (h.membrane as unknown as { stream: () => Promise<NormalizedResponse> }).stream = async () => answer();
-  const f = h.framework as unknown as {
-    pendingRequests: Array<{ agentName: string; reason: string; source: string; timestamp: number }>;
-    processInferenceRequests(): Promise<void>;
-    startAgentStream(): Promise<void>;
-  };
-  let starts = 0;
-  f.startAgentStream = async () => { starts++; };
-  const inference = agent.runInference([]);
-  try {
-    await entered.opened;
-    f.pendingRequests.push({ agentName: 'assistant', reason: 'test', source: 'test', timestamp: Date.now() });
-    await f.processInferenceRequests();
-    assert.equal(starts, 0);
-    assert.equal(f.pendingRequests.length, 1);
-    compile.open();
-    await inference;
-    await f.processInferenceRequests();
-    assert.equal(starts, 1, 'the retained wake is admitted after compilation and inference finish');
-  } finally { compile.open(); await inference; await h.framework.stop(); }
-});
-
-test('#281 round: an exhausted batch starts no new write without claiming a stalled workspace', async () => {
+test('an exhausted batch starts no new write without claiming a stalled workspace', async () => {
   const h = await workspaceHarness([]);
   const f = h.framework as unknown as {
     spillWithheld(label: string, text: string, branch: string, deadline: number): Promise<unknown>;
@@ -2937,7 +2962,7 @@ test('#281 round: an exhausted batch starts no new write without claiming a stal
   } finally { await h.framework.stop(); }
 });
 
-test('#281 round: an inline spill names the readable tree file and traces its failed disk copy', async () => {
+test('an inline spill names the readable tree file and traces its failed disk copy', async () => {
   const h = await workspaceHarness([], { autoMaterialize: true });
   writeFileSync(join(h.mountDir, 'tool-results'), 'not a directory');
   const traces: Array<{ type: string; path?: string }> = [];
@@ -2956,7 +2981,7 @@ test('#281 round: an inline spill names the readable tree file and traces its fa
   } finally { await h.framework.stop(); }
 });
 
-test('#281 round: an already-aborted direct call never reaches membrane', async () => {
+test('an already-aborted direct call never reaches membrane', async () => {
   const h = await harness([]);
   let calls = 0;
   (h.membrane as unknown as { stream: () => Promise<NormalizedResponse> }).stream = async () => { calls++; return answer(); };

From ba5520bd9e65eb8e8378dd4e67a7945110c92fa3 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Tue, 13 Oct 2026 03:59:28 -0400
Subject: [PATCH 14/16] fix(guard): say that stop() waits for a stalled write's
 mount turn; a thrown image write names the saved ones; the restart contract
 as it holds

From the final round's readers and its review:

- stop() does wait for a withheld write still under way at its deadline:
  the workspace's own stop drains the mount turn the write holds, bounded
  only by a teardown timeout passed to stop() (indefinitely without one,
  as since #248). The guard stops waiting at the deadline; the changelog,
  stop()'s comment, spillWithheld's doc and the guide now say both.
- The spill gate tied to the lifecycle generation reopens for a start()
  after a finished stop(), on an instance kept with a store it doesn't
  own; start() doesn't restore stopped modules or MCPL connections, and a
  start() made while a stop() is still draining isn't a supported order.
  The comment, guide and changelog say so instead of claiming any order.
- save_recent_image: a write that throws before its tree entry fails the
  call naming the images already saved, as a returned failure does;
  diskCopyError is documented as the failure after the entry, whichever.
- An exhausted batch's skips are logged once per batch, not per result.
- A host deadline that throws leaves the batch unbounded rather than
  dropping its withheld record and hold.

Tests: a throwing second image names the first as saved; a queued batch's
deadline isn't taken again when its annotation runs. Removing either fix
fails its test.
---
 .../guard-withheld-names-original.fixed.md    |  9 ++--
 docs/tool-result-guard.md                     |  6 +--
 src/framework.ts                              | 54 +++++++++++++------
 src/tool-result-guard.ts                      |  3 +-
 test/save-recent-image.test.ts                | 25 +++++++++
 test/tool-result-guard.test.ts                |  1 +
 6 files changed, 72 insertions(+), 26 deletions(-)

diff --git a/changelog.d/guard-withheld-names-original.fixed.md b/changelog.d/guard-withheld-names-original.fixed.md
index 4fec02da2..ee0e2cd84 100644
--- a/changelog.d/guard-withheld-names-original.fixed.md
+++ b/changelog.d/guard-withheld-names-original.fixed.md
@@ -29,10 +29,9 @@
   record describes the spill's outcome when the annotation finishes, with `unfinished` for a write still running. That record is not revised when the write later settles. A file whose copy on disk fails
   is still in the workspace's tree, where its tools read it, so the stub names
   it; for this, `WorkspaceModule.writeBinary`'s result for that case carries
-  `data: { inChronicle: true }`, including when a post-commit operation throws. Inline truncation notes also name that readable tree file, and the disk-copy failure is logged and traced. Each batch has one 30-second deadline for all its withheld writes. A write still under way then is named as unfinished, with the audit record as the fallback. Nothing waits for it after that, stop included: it goes on by
-  itself, and may finish or fail after the workspace has stopped. Until it
+  `data: { inChronicle: true }`, including when a post-commit operation throws. Inline truncation notes also name that readable tree file, and the disk-copy failure is logged and traced. Each batch has one 30-second deadline for all its withheld writes. A write still under way then is named as unfinished, with the audit record as the fallback. The guard stops waiting for it there; the write goes on, and may finish or fail later. `stop()` still waits for the workspace's own turns, which such a write holds, bounded only by a teardown timeout passed to `stop()` (indefinitely without one, as since #248). Until it
   settles, no other withheld original is written, for this batch or a later
-  one of any agent: their stubs name the audit record. Writes can start before the first deadline fires; those batches each use their own deadline. A write that never settles keeps new withheld spills disabled for the process lifetime. Deadline and skip messages name affected files on stderr. The inline cap's spills are outside this deadline. Requests sent by the framework and the direct Agent API are compiled only once each annotation started so far has finished,
+  one of any agent: their stubs name the audit record. Writes can start before the first deadline fires; those batches each use their own deadline. A write that never settles keeps new withheld spills disabled for the process lifetime. A deadline that fires names its file on stderr; a stall's skips are logged once, naming the first file, and counted when it clears; an exhausted batch's skips are logged once per batch. The inline cap's spills are outside this deadline. Requests sent by the framework and the direct Agent API are compiled only once each annotation started so far has finished,
   including one that began while the compile waited or ran, and the refusal
   retry; a conversation fork seeded from its template copies only stubs whose
   annotation has finished. A request preview doesn't wait, so rollback,
@@ -56,6 +55,6 @@
   compiled afresh, as the framework's is, so its longer stubs fit the budget.
 
 - With `maintenanceIntervalMs: 0`, periodic retries of retained guards are disabled; stop still retries them. A failing audit record blocks later queued edits and their compression holds until its write succeeds. Shutdown reports an error if that retry still fails.
-- A framework-driven turn that compiled across stop is discarded before driving its stream, with a line saying why, even if the framework has restarted. A restart starts a new lifecycle, with withheld spills open. Direct Agent calls remain governed by their caller's abort signal; a refusal retry checks that signal again after waiting for annotations. The direct API reads its unguarded tool results once, after the first compile, and sends the same ones with the refusal retry.
+- A framework-driven turn that compiled across stop is discarded before driving its stream, with a line saying why, even if the framework has restarted. A `start()` after a finished `stop()` starts a new lifecycle, with the spill gate open again; a `start()` made while a `stop()` is still draining isn't a supported order. Direct Agent calls remain governed by their caller's abort signal; a refusal retry checks that signal again after waiting for annotations. The direct API reads its unguarded tool results once, after the first compile, and sends the same ones with the refusal retry.
 - Concurrent starts on one Agent, a direct inference call beside a framework-driven turn, are not made safe by this change: an Agent compiles while its status still reads idle, as before, and the annotation wait lengthens that window by up to the batch's deadline. `abortInference()` returns false during a direct call's initial assembly.
-- `save_recent_image` reports a tree-only write as saved, including its path, size, MIME type, `inChronicle` and `diskCopyError`. A later failure in a multi-image save includes that file among the already-saved paths. An RFC-005 reference fetched to such a file names it.
+- `save_recent_image` reports a tree-only write as saved, including its path, size, MIME type, `inChronicle` and `diskCopyError` (the failure after the tree entry, whichever it was). A later failure in a multi-image save, returned or thrown, includes that file among the already-saved paths. An RFC-005 reference fetched to such a file names it.
diff --git a/docs/tool-result-guard.md b/docs/tool-result-guard.md
index d7e27cd81..4bddaa4e9 100644
--- a/docs/tool-result-guard.md
+++ b/docs/tool-result-guard.md
@@ -167,9 +167,9 @@ Otherwise the stub names the guard's audit record, for an operator:
   audit record and the logs;
 - when the write is still under way at its batch's deadline: "Its result was still being written to workspace file … when this note was made; if that file is missing, it is kept in the guard's audit record …".
 
-Each batch has one 30-second deadline, starting when the batch is queued, so a request waiting on a chain of batches waits at most one deadline past the latest one's arrival. Each successive write uses the remaining time. Once the deadline passes, the request can carry the unfinished-write notice; later results in the batch name the audit record. The underlying write continues, and may finish or fail later; stop() waits for the workspace's own turns, which such a write holds, until its teardown timeout. A deadline that fires logs the file's path to stderr. While any write remains overdue, new withheld spills are skipped as `workspace_unanswered`, logged once for the stall and counted when it clears. A write that never settles keeps that gate closed for the process lifetime. Other batches can start writes before the first deadline fires, each within its own deadline. This bound covers withheld spills; the inline cap's original spill has no deadline.
+Each batch has one 30-second deadline, starting when the batch is queued, so a request waiting on a chain of batches waits at most one deadline past the latest one's arrival. Each successive write uses the remaining time. Once the deadline passes, the request can carry the unfinished-write notice; later results in the batch name the audit record. The underlying write continues, and may finish or fail later. The guard stops waiting for it at the deadline, but `stop()` still waits for the workspace's own turns, which such a write holds, bounded only by a teardown timeout passed to `stop()`, and indefinitely without one. A deadline that fires logs the file's path to stderr. While any write remains overdue, new withheld spills are skipped as `workspace_unanswered`, logged once for the stall and counted when it clears. A write that never settles keeps that gate closed for the process lifetime. Other batches can start writes before the first deadline fires, each within its own deadline. This bound covers withheld spills; the inline cap's original spill has no deadline.
 
-A file whose tree entry was set is readable through the workspace's tools, on the branch that was current when the entry was set, even if the rest of its write fails: its disk copy refused, or a throw after the entry. `WorkspaceModule.writeBinary` reports `data: { inChronicle: true }` for that outcome. Both withheld stubs and inline truncation notes name the tree file, while stderr and `tool:spill_failed` report the failure (the workspace's own `workspace:materialize-failed` event is emitted only for a refused push). `save_recent_image` also counts that file as saved, with its path, size, MIME type, `inChronicle` and `diskCopyError` in the saved receipt, and an RFC-005 reference fetched to such a file names it.
+A file whose tree entry was set is readable through the workspace's tools, on the branch that was current when the entry was set, even if the rest of its write fails: its disk copy refused, or a throw after the entry. `WorkspaceModule.writeBinary` reports `data: { inChronicle: true }` for that outcome. Both withheld stubs and inline truncation notes name the tree file, while stderr and `tool:spill_failed` report the failure (the workspace's own `workspace:materialize-failed` event is emitted only for a refused push). `save_recent_image` also counts that file as saved, with its path, size, MIME type, `inChronicle` and `diskCopyError` (the failure after the tree entry, whichever it was) in the saved receipt, and an RFC-005 reference fetched to such a file names it. A write that throws before its tree entry is set fails the call, naming the images already saved.
 
 When saving the staged audit record itself had failed as the result arrived,
 the stub says the result went to the audit record "though saving that record
@@ -218,7 +218,7 @@ Requests sent by the framework or the direct Agent inference API are compiled af
 
 Concurrent starts on one Agent, a direct inference call beside a framework-driven turn, are not made safe here: an Agent compiles its request while its status still reads idle (or ready), as before this change, and the wait for annotations lengthens that window, by up to the batch's deadline. `abortInference()` returns false during a direct call's initial assembly; a caller's own abort signal is checked before the request is sent, and again after the refusal retry's annotation wait. The direct API reads its unguarded tool results once, after the first compile, and sends the same ones with the refusal retry.
 
-At stop, the framework lets running annotations finish while the workspace is up. An annotation that starts after that drain writes no file and is saved before the store closes. A framework-driven turn that compiled across stop is discarded before its stream is driven, even if the same framework has since restarted. A restart starts a new lifecycle, with withheld spills open. These lifecycle gates cover framework-driven turns; direct Agent calls use their caller's abort signal.
+At stop, the framework lets running annotations finish while the workspace is up. An annotation that starts after that drain writes no file and is saved before the store closes. A framework-driven turn that compiled across stop is discarded before its stream is driven, even if the same framework has since restarted. A `start()` after a finished `stop()` starts a new lifecycle, with the spill gate open again; a `start()` made while a `stop()` is still draining isn't a supported order. These lifecycle gates cover framework-driven turns; direct Agent calls use their caller's abort signal.
 
 For example, an operator can inspect records without changing the agent's
 view:
diff --git a/src/framework.ts b/src/framework.ts
index 3a7609609..c1a37389e 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -2132,8 +2132,8 @@ export class AgentFramework {
     // An annotation that starts after this point, such as one from a direct
     // Agent API call stop doesn't cancel, starts no write to the stopping
     // workspace: its stub names the audit record. A write that was past its
-    // deadline is not waited for, and may still finish or fail after the
-    // modules stop.
+    // deadline isn't waited for here, but the workspace's own stop waits for
+    // the mount turn it holds, bounded only by teardownTimeoutMs.
     this.guardSpillsClosedFor = stoppingGeneration;
 
     // Stop modules and MCPL servers in parallel
@@ -2873,13 +2873,18 @@ export class AgentFramework {
   private readonly stalledSpills = new Set<Promise<void>>();
   /** Withheld spills skipped since the current stall began. */
   private stallSkips = 0;
+  /** The deadline of the last batch whose exhausted skips were logged. */
+  private lastExhaustedDeadline: number | null = null;
   /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
   /** The lifecycle generation whose stop() has let the running annotations
    *  finish: a withheld original is then no longer written to a workspace
-   *  that is stopping, and its stub names the audit record. A later start()
-   *  has a generation of its own, so its spills are open whatever order the
-   *  earlier stop finishes in. */
+   *  that is stopping, and its stub names the audit record. A start() after
+   *  that stop() has finished has a generation of its own, so the spill gate
+   *  is open again for an instance kept with a store it doesn't own and that
+   *  is still open (start() doesn't restore stopped modules or MCPL
+   *  connections, and refuses an owned store that stop() closed). A start()
+   *  made while a stop() is still draining isn't a supported order. */
   private guardSpillsClosedFor: number | null = null;
 
   /** A new agent's guard: its persisted setting, the tool-results spill its
@@ -12116,7 +12121,9 @@ export class AgentFramework {
   /**
    * A withheld original uses the remaining time in its batch's deadline.
    * A write still under way at that deadline is reported as unfinished and
-   * continues independently, including after stop. From then until every
+   * goes on; the guard stops waiting for it, though stop() still waits for
+   * the workspace's turn it holds (bounded only by a teardown timeout). From
+   * then until every
    * overdue write settles, new withheld spills are workspace_unanswered.
    * Writes from other batches can start before the first deadline fires.
    * An exhausted batch starts no more writes even if none is overdue.
@@ -12137,7 +12144,11 @@ export class AgentFramework {
     }
     const remaining = deadline - Date.now();
     if (remaining <= 0) {
-      console.error(`[spill] ${place.path} skipped: batch_deadline`);
+      // Once per batch (its deadline is the batch's), not per result.
+      if (this.lastExhaustedDeadline !== deadline) {
+        this.lastExhaustedDeadline = deadline;
+        console.error(`[spill] a withheld batch used its deadline before all its originals were written; the rest are skipped as batch_deadline (first: ${place.path})`);
+      }
       return { skipped: 'batch_deadline' };
     }
     const write = this.writeToolResultFile(label, text, branch);
@@ -16346,18 +16357,27 @@ export class AgentFramework {
         for (const image of found) {
           const destination = pathFor(image.rangeOffset);
           const bytes = Buffer.from(image.data, 'base64');
-          const result = await workspace.writeBinary(destination, bytes, image.mediaType);
+          const failed = (why: unknown): void => finish({
+            success: false,
+            error:
+              `save_recent_image: failed writing "${destination}": ${why instanceof Error ? why.message : String(why)}` +
+              (savedFiles.length > 0
+                ? ` (already saved: ${savedFiles.map((f) => f.path).join(', ')})`
+                : ''),
+            isError: true,
+          });
+          let result: Awaited<ReturnType<typeof workspace.writeBinary>>;
+          try {
+            result = await workspace.writeBinary(destination, bytes, image.mediaType);
+          } catch (error) {
+            // Thrown before its tree entry was set; the images before it
+            // are saved, and the failure says so, as a returned one does.
+            failed(error);
+            return;
+          }
           const inChronicle = (result.data as { inChronicle?: boolean } | undefined)?.inChronicle === true;
           if (!result.success && !inChronicle) {
-            finish({
-              success: false,
-              error:
-                `save_recent_image: failed writing "${destination}": ${result.error}` +
-                (savedFiles.length > 0
-                  ? ` (already saved: ${savedFiles.map((f) => f.path).join(', ')})`
-                  : ''),
-              isError: true,
-            });
+            failed(result.error);
             return;
           }
           savedFiles.push({
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 9b0eba100..5321ef9cd 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -473,7 +473,8 @@ export class ToolResultGuard {
     // The batch's deadline runs from when it's queued, not from when the
     // batches ahead of it finish, so a request waiting on a chain of batches
     // waits at most one deadline past the latest one's arrival.
-    const deadline = this.host?.deadline() ?? Infinity;
+    let deadline = Infinity;
+    try { deadline = this.host?.deadline() ?? Infinity; } catch { /* no bound rather than no record */ }
     const run = previous.then(async () => {
       // Set once the stub's edit is queued with the hold: the queue releases
       // it when the edit lands or is superseded.
diff --git a/test/save-recent-image.test.ts b/test/save-recent-image.test.ts
index 83cac62e2..9fb8e9e10 100644
--- a/test/save-recent-image.test.ts
+++ b/test/save-recent-image.test.ts
@@ -817,6 +817,31 @@ describe('ToolImageLedger', () => {
   });
 });
 
+it('a write that throws before its tree entry names the images already saved', async () => {
+  const h = await startTurn({
+    prefix: 'sri-throw-',
+    responses: [
+      [snapCall('call_snap')],
+      [saveCall('call_save', { path: 'files/images.png', index: 0, count: 2 })],
+      done,
+    ],
+    workspace: (workspace) => {
+      const write = workspace.writeBinary.bind(workspace);
+      let writes = 0;
+      workspace.writeBinary = async (...args) => {
+        if (++writes === 2) throw new Error('injected tree exception');
+        return write(...args);
+      };
+    },
+  });
+  try {
+    const result = await waitForToolResult(h.framework, 'call_save');
+    assert.equal(result.isError, true);
+    assert.match(result.content, /injected tree exception/);
+    assert.match(result.content, /already saved: files\/images-0.png/);
+  } finally { await h.framework.stop(); rmSync(h.tempDir, { recursive: true, force: true }); }
+});
+
 it('a save whose write fails after its tree entry, through the workspace itself, is reported saved with its failure', async () => {
   const h = await startTurn({
     prefix: 'sri-tree-real-',
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 8f8c30b1f..8da5b65f4 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -2732,6 +2732,7 @@ test("a batch's deadline is taken when it is queued, not when the batches ahead
     assert.equal(taken, 2, "the second batch's deadline was taken when it was queued");
     first.open();
     await bounded(r.guard.whenAnnotated(), 'both annotations');
+    assert.equal(taken, 2, 'and not taken again when its annotation ran');
   } finally { r.cm.close(); }
 });
 

From 1742f90cba2052149e1de813cb21778c813a1465 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Tue, 13 Oct 2026 04:07:20 -0400
Subject: [PATCH 15/16] fix(guard): a withheld spill with no finite deadline
 takes its own

ba5520bd let a batch whose host deadline() threw carry Infinity as its
deadline, meaning no bound. spillWithheld turned that into a setTimeout
delay Node cuts to 1 ms (with a TimeoutOverflowWarning), so an ordinary
20 ms write came back unfinished and marked the workspace stalled.
spillWithheld now gives a deadline that isn't finite its own default, the
same one it uses with no deadline passed, which keeps both the record and
the bound.

Test: a 20 ms write spilled with an Infinity deadline is written, and
nothing is marked stalled; using the deadline as given fails it.
---
 src/framework.ts               |  3 +++
 src/tool-result-guard.ts       |  2 +-
 test/tool-result-guard.test.ts | 15 +++++++++++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/framework.ts b/src/framework.ts
index c1a37389e..74b38e67b 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -12131,6 +12131,9 @@ export class AgentFramework {
    */
   private async spillWithheld(label: string, text: string, branch: string,
     deadline = Date.now() + this.withheldSpillDeadlineMs): Promise<WithheldSpill> {
+    // A batch with no finite deadline (a host whose deadline() threw) gets
+    // this write's own, rather than a timer Node would cut to 1 ms.
+    if (!Number.isFinite(deadline)) deadline = Date.now() + this.withheldSpillDeadlineMs;
     if (this.guardSpillsClosedFor === this.lifecycleGeneration) return null;
     const place = this.toolResultFilePlace(label);
     if (!place) return null;
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index 5321ef9cd..aed22f75e 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -474,7 +474,7 @@ export class ToolResultGuard {
     // batches ahead of it finish, so a request waiting on a chain of batches
     // waits at most one deadline past the latest one's arrival.
     let deadline = Infinity;
-    try { deadline = this.host?.deadline() ?? Infinity; } catch { /* no bound rather than no record */ }
+    try { deadline = this.host?.deadline() ?? Infinity; } catch { /* the spill then takes its own deadline, rather than losing the record */ }
     const run = previous.then(async () => {
       // Set once the stub's edit is queued with the hold: the queue releases
       // it when the edit lands or is superseded.
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 8da5b65f4..641f4acfd 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -2709,6 +2709,21 @@ test("an inline spill's failed disk copy is traced with its error, cut at 200 ch
   } finally { h.workspace.writeBinary = original; await h.framework.stop(); }
 });
 
+test('a withheld spill with no finite deadline takes its own, not a 1 ms timer', async () => {
+  const h = await workspaceHarness([]);
+  const f = h.framework as unknown as {
+    writeToolResultFile: () => Promise<unknown>;
+    spillWithheld: (label: string, text: string, branch: string, deadline: number) => Promise<unknown>;
+    stalledSpills: Set<unknown>;
+  };
+  f.writeToolResultFile = async () => { await new Promise((resolve) => setTimeout(resolve, 20)); return { path: 'work/tool-results/slow.txt' }; };
+  try {
+    const spilled = await f.spillWithheld('slow', 'original', h.framework.getStore().currentBranch().name, Infinity);
+    assert.deepEqual(spilled, { path: 'work/tool-results/slow.txt' }, 'a 20 ms write finishes within the default deadline');
+    assert.equal(f.stalledSpills.size, 0);
+  } finally { await h.framework.stop(); }
+});
+
 test("a batch's deadline is taken when it is queued, not when the batches ahead of it finish", async () => {
   const r = await compressionRig();
   try {

From 229f8edb5e9114e70c3027acdb478cd7d165fba9 Mon Sep 17 00:00:00 2001
From: Ada-1017 <ada-1017@commons.astra.invalid>
Date: Tue, 13 Oct 2026 04:16:07 -0400
Subject: [PATCH 16/16] fix(guard): a batch that used its deadline is logged
 once, by the guard, which knows the batch

ba5520bd logged an exhausted batch's skips in spillWithheld, keyed on the
last deadline it had logged. That coalesced consecutive equal deadlines,
not batches: two agents' batches interleaving logged a line per switch,
and two batches sharing a millisecond deadline logged one line between
them. The guard's annotation loop knows its batch, so it says once per
batch, naming the batch, that it used its deadline; spillWithheld returns
the skip without a line.

Test: a three-result batch whose spills all come back batch_deadline logs
one line; logging per skipped result fails it.
---
 src/framework.ts               | 12 ++----------
 src/tool-result-guard.ts       |  7 +++++++
 test/tool-result-guard.test.ts | 12 ++++++++++++
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/src/framework.ts b/src/framework.ts
index 74b38e67b..34c2ef445 100644
--- a/src/framework.ts
+++ b/src/framework.ts
@@ -2873,8 +2873,6 @@ export class AgentFramework {
   private readonly stalledSpills = new Set<Promise<void>>();
   /** Withheld spills skipped since the current stall began. */
   private stallSkips = 0;
-  /** The deadline of the last batch whose exhausted skips were logged. */
-  private lastExhaustedDeadline: number | null = null;
   /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
   private withheldSpillDeadlineMs = WITHHELD_SPILL_DEADLINE_MS;
   /** The lifecycle generation whose stop() has let the running annotations
@@ -12146,14 +12144,8 @@ export class AgentFramework {
       return { skipped: 'workspace_unanswered' };
     }
     const remaining = deadline - Date.now();
-    if (remaining <= 0) {
-      // Once per batch (its deadline is the batch's), not per result.
-      if (this.lastExhaustedDeadline !== deadline) {
-        this.lastExhaustedDeadline = deadline;
-        console.error(`[spill] a withheld batch used its deadline before all its originals were written; the rest are skipped as batch_deadline (first: ${place.path})`);
-      }
-      return { skipped: 'batch_deadline' };
-    }
+    // The guard says once per batch that it used its deadline.
+    if (remaining <= 0) return { skipped: 'batch_deadline' };
     const write = this.writeToolResultFile(label, text, branch);
     let timer: ReturnType<typeof setTimeout> | undefined;
     const late = new Promise<'late'>((resolve) => {
diff --git a/src/tool-result-guard.ts b/src/tool-result-guard.ts
index aed22f75e..efd6d6e2a 100644
--- a/src/tool-result-guard.ts
+++ b/src/tool-result-guard.ts
@@ -494,6 +494,7 @@ export class ToolResultGuard {
         const thrown = new Map<number, string>();
         // Set once the branch has changed: no more is written.
         let branchLeft = false;
+        let deadlineSpent = false;
         for (const [index, block] of pending.content.entries()) {
           if (block.type !== 'tool_result') continue;
           // Once the store has left the batch's branch (a rollback, an undo, a
@@ -530,6 +531,12 @@ export class ToolResultGuard {
           // back by the edit, as after an undo and a redo, the stubs of this
           // result and the later ones name the audit record.
           if (spill && 'skipped' in spill && spill.skipped === 'branch_changed') branchLeft = true;
+          // A batch that used its deadline is said once, here, where the
+          // batch is known; the host returns the skip without a line.
+          if (spill && 'skipped' in spill && spill.skipped === 'batch_deadline' && !deadlineSpent) {
+            deadlineSpent = true;
+            console.error(`[tool-result-guard] agent=${this.agentName} batch=${pending.id} used its deadline before all its originals were written; the rest name the audit record (batch_deadline)`);
+          }
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
diff --git a/test/tool-result-guard.test.ts b/test/tool-result-guard.test.ts
index 641f4acfd..d7f308fbc 100644
--- a/test/tool-result-guard.test.ts
+++ b/test/tool-result-guard.test.ts
@@ -2709,6 +2709,18 @@ test("an inline spill's failed disk copy is traced with its error, cut at 200 ch
   } finally { h.workspace.writeBinary = original; await h.framework.stop(); }
 });
 
+test('a batch that used its deadline is logged once for the batch, by the guard', async (t) => {
+  const h = await workspaceHarness([[calls('one', 'two', 'three'), refused()], [answer()]]);
+  (h.framework as unknown as { spillWithheld: () => Promise<unknown> }).spillWithheld = async () => ({ skipped: 'batch_deadline' });
+  const lines: string[] = [];
+  t.mock.method(console, 'error', (...args: unknown[]) => { lines.push(args.map(String).join(' ')); });
+  try {
+    await bounded(h.run(), 'the run');
+    await h.framework.getAgent('assistant')!.toolResultGuard.whenAnnotated();
+    assert.equal(lines.filter((line) => /used its deadline/.test(line)).length, 1, lines.join('\n'));
+  } finally { await h.framework.stop(); }
+});
+
 test('a withheld spill with no finite deadline takes its own, not a 1 ms timer', async () => {
   const h = await workspaceHarness([]);
   const f = h.framework as unknown as {