@animalabs/agent-framework 0.23.3 → 0.24.1

package/src/recovery/offline-branch.ts

@@ -1,13 +1,19 @@
 import { JsStore } from '@animalabs/chronicle';
+import type { SurgeryMarkerReceipt } from '../operator-log.js';
 import { ContextManager, continuesBody, type BodyShard } from '@animalabs/context-manager';
 import { removeStoredInterval } from '../stored-removal.js';
 import { firstFreeBranchName } from '../branch-names.js';
 import {
   DEFAULT_DISCORD_AWARENESS_EMOJI,
   DiscordAwarenessOutbox,
+  boundDiscordAwarenessText,
   defaultDiscordAwarenessOutboxPath,
+  checkedDiscordAwarenessMarks,
   extractDiscordAwarenessRefs,
+  selectDiscordAwarenessRefs,
+  type DiscordAwarenessMarks,
   type DiscordAwarenessRef,
+  type DiscordMessageMetadataCarrier,
 } from './discord-awareness-outbox.js';
 
 export interface OfflineRecoveryBranchOptions {
@@ -29,8 +35,14 @@ export interface OfflineRecoveryBranchOptions {
   namespace?: string;
   /** Use for old message records that do not carry metadata.serverId. */
   discordServerId?: string;
+  /** The awareness ledger (default: under the store). */
   outboxPath?: string;
   emoji?: string;
+  /**
+   * Awareness marks on the removed Discord messages: an explicit publication
+   * choice, `none` by default. The recovery itself stays local either way.
+   */
+  marks?: DiscordAwarenessMarks;
   dryRun?: boolean;
 }
 
@@ -40,9 +52,27 @@ export interface OfflineRecoveryBranchResult {
   targetBranch: string;
   messagesRemoved: number;
   messagesSuppressed: number;
+  /** Removed messages that carry a Discord address. */
+  discordAddressable: number;
+  /** The publication scope recorded for this recovery. */
+  marksScope: 'none' | 'addressed' | 'all';
+  /** Marks queued for delivery (planned, for a dry run); not delivered. */
   discordMarkersQueued: number;
+  /** What became of the marks once the branch was made (absent on a dry
+   *  run): scheduling only, never Discord acceptance. */
+  markers?: SurgeryMarkerReceipt;
+  /** The refs that will be marked (empty unless marks were chosen). */
   refs: DiscordAwarenessRef[];
+  /** Removed addressable messages the marks choice leaves unmarked (outside
+   *  its scope); `markers` says whether the chosen ones are scheduled. */
+  unmarked: number;
+  /** Authorized refs (marks.refs) this recovery does not remove. */
+  notRemoved: number;
+  /** The awareness ledger the batch is recorded in. */
   outboxPath: string;
+  /** Set when a suppression-only batch's resume record couldn't be closed:
+   *  what of it is left, as the host's surgeries report it. */
+  suppressionRecord?: string;
 }
 
 /**
@@ -65,6 +95,10 @@ export async function createOfflineRecoveryBranch(
   if (count !== undefined && (!Number.isFinite(count) || count < 1)) {
     throw new Error('messages must be a positive integer');
   }
+  // The marks choice is checked as the live methods check it, before the
+  // store is opened: a malformed one would otherwise mark every removed
+  // message.
+  const marks = checkedDiscordAwarenessMarks(options.marks);
 
   const store = JsStore.openOrCreate({ path: options.storePath });
   let contextManager: ContextManager | null = null;
@@ -84,7 +118,7 @@ export async function createOfflineRecoveryBranch(
     let target: StoredWindowMessage;
     let targetIndex: number;
     let removedCount: number;
-    let refs: DiscordAwarenessRef[];
+    let carriers: DiscordMessageMetadataCarrier[];
 
     if (options.messageId) {
       // Search backward in bounded windows: recovery anchors are normally near
@@ -101,12 +135,7 @@ export async function createOfflineRecoveryBranch(
       target = located.message;
       targetIndex = located.index;
       removedCount = total - located.index - 1;
-      refs = collectDiscordRefs(
-        contextManager,
-        located.index + 1,
-        total,
-        options.discordServerId,
-      );
+      carriers = collectDiscordCarriers(contextManager, located.index + 1, total);
     } else if (options.contextId) {
       const located = findInternalMessageFromTail(contextManager, total, options.contextId.trim());
       if (!located) {
@@ -115,12 +144,7 @@ export async function createOfflineRecoveryBranch(
       target = located.message;
       targetIndex = located.index;
       removedCount = total - located.index - 1;
-      refs = collectDiscordRefs(
-        contextManager,
-        located.index + 1,
-        total,
-        options.discordServerId,
-      );
+      carriers = collectDiscordCarriers(contextManager, located.index + 1, total);
     } else {
       // Count mode remains for compatibility. Read only the target plus suffix,
       // avoiding full-history materialization and attachment blob inflation.
@@ -135,7 +159,7 @@ export async function createOfflineRecoveryBranch(
       target = countTarget;
       targetIndex = total - count! - 1;
       removedCount = count!;
-      refs = extractDiscordAwarenessRefs(discarded, options.discordServerId);
+      carriers = discarded.map(addressingOnly);
     }
 
     validateAnchorBoundary(contextManager, targetIndex, total, target);
@@ -145,7 +169,6 @@ export async function createOfflineRecoveryBranch(
       targetIndex,
       options.suppressMessageIds ?? [],
       options.suppressRanges ?? [],
-      options.discordServerId,
     );
     validateRemovalIntegrity(
       contextManager,
@@ -160,7 +183,10 @@ export async function createOfflineRecoveryBranch(
         ...suppression.intervals,
       ],
     );
-    refs = dedupeDiscordRefs([...refs, ...suppression.refs]);
+    carriers = [...carriers, ...suppression.carriers];
+    const addressable = extractDiscordAwarenessRefs(carriers, options.discordServerId).length;
+    const selection = selectDiscordAwarenessRefs(carriers, marks, options.discordServerId);
+    const refs = selection.refs;
 
     const sourceBranch = store.currentBranch().name;
     const held = new Set(store.listBranches().map((branch) => branch.name));
@@ -169,6 +195,10 @@ export async function createOfflineRecoveryBranch(
     if (targetBranch === sourceBranch) {
       throw new Error('Recovery branch name must differ from the active source branch');
     }
+    // A known collision is refused before anything is prepared.
+    if (store.listBranches().some((branch) => branch.name === targetBranch)) {
+      throw new Error(`Recovery branch ${targetBranch} already exists; choose another --branch`);
+    }
     const outboxPath = options.outboxPath
       ?? defaultDiscordAwarenessOutboxPath(options.storePath);
 
@@ -178,33 +208,44 @@ export async function createOfflineRecoveryBranch(
       targetBranch,
       messagesRemoved: removedCount,
       messagesSuppressed: suppression.messageCount,
+      discordAddressable: addressable,
+      marksScope: marks === 'none' ? 'none' : marks.scope,
       discordMarkersQueued: refs.length,
       refs,
+      unmarked: selection.unmarked,
+      notRemoved: selection.notRemoved,
       outboxPath,
     };
     if (options.dryRun) return result;
 
-    const outbox = new DiscordAwarenessOutbox(outboxPath);
-    const batch = outbox.prepare({
+    // The host is stopped, so this process is the ledger's only writer.
+    const outbox = new DiscordAwarenessOutbox(outboxPath, { store });
+    const batch = await outbox.prepare({
       agentName: options.agentName,
       sourceBranch,
       targetBranch,
       refs,
+      scope: marks === 'none' ? 'none' : marks.scope,
+      unmarked: selection.unmarked,
+      notRemoved: selection.notRemoved,
       emoji: options.emoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI,
       // Merely seeing targetBranch active does not prove branch-local
-      // suppressions finished. Only the recovery operation may activate this
-      // batch after every removal below succeeds.
-      activationPolicy: suppression.intervals.length > 0 ? 'explicit' : 'target-branch',
+      // suppressions finished: a start on it applies them again while the
+      // batch is prepared. Only the recovery may activate it, after every
+      // removal below succeeds.
       suppressionIntervals: suppression.intervals.map((interval) => ({
         fromId: String(interval.fromId),
         toId: String(interval.toId),
       })),
     });
 
-    // branchAt uses the target message's origin sequence. No message content is
-    // compiled or submitted to Membrane during this operation.
-    const createdBranch = contextManager.branchAt(target.id, targetBranch);
+    let createdBranch: string | undefined;
     try {
+      // branchAt uses the target message's origin sequence. No message
+      // content is compiled or submitted to Membrane during this operation.
+      // Creating the branch is part of the body: a failure here settles the
+      // batch like a failed switch or redaction.
+      createdBranch = contextManager.branchAt(target.id, targetBranch);
       await contextManager.switchBranch(createdBranch);
       // Each interval is removed by its messages' ids, so the order doesn't
       // change the result. removeStoredInterval takes a single message outside
@@ -213,18 +254,109 @@ export async function createOfflineRecoveryBranch(
       for (const interval of [...suppression.intervals].reverse()) {
         removeStoredInterval(contextManager, interval.fromId, interval.toId);
       }
-      if (batch) outbox.activate(batch.id);
     } catch (error) {
       // A partially suppressed branch is not safe to boot into. Preserve it
-      // for diagnosis, but leave Chronicle on the untouched source branch and
-      // keep the explicit outbox batch non-deliverable.
-      if (store.currentBranch().name === createdBranch) {
-        await contextManager.switchBranch(sourceBranch);
+      // for diagnosis, but put Chronicle back on the untouched source branch.
+      // Once the source is confirmed, the batch is retired (discard syncs the
+      // restored state before it records that): its surgery never happened.
+      // If it can't be confirmed, the batch stays prepared as the body's
+      // record: a start on its target branch finishes a suppression's
+      // removals, since its body is in effect there, and a start retires the
+      // batch, none of its marks sent. The error says which, and names the
+      // branch.
+      const failure = error instanceof Error ? error.message : String(error);
+      let restore = '';
+      try {
+        if (store.currentBranch().name !== sourceBranch) await contextManager.switchBranch(sourceBranch);
+      } catch (restoreError) {
+        restore = `; restoring ${sourceBranch} failed: ${boundDiscordAwarenessText(
+          restoreError instanceof Error ? restoreError.message : String(restoreError),
+        )}`;
+      }
+      const sourceConfirmed = store.currentBranch().name === sourceBranch;
+      let retire = '';
+      // A batch with marks never sends them once kept: the recovery, run
+      // again, chooses them again.
+      const redo = batch && batch.refs.length > 0
+        ? '. To apply its marks, run the recovery again onto a new --branch, choosing them again' : '';
+      if (batch) {
+        if (!sourceConfirmed) {
+          // The recovery starts from the store's current branch, which this
+          // one couldn't put back: a run from there would start from the fork.
+          const redoFromSource = batch.refs.length > 0
+            ? `. To apply its marks, redo it from ${sourceBranch}, choosing them again: the recovery starts from the ` +
+              `store's current branch, which isn't ${sourceBranch} now, so start the host, switch to ${sourceBranch} ` +
+              'through the host API\'s branch.switch, stop the host, and run the recovery again onto a new --branch'
+            : '';
+          retire = `; awareness batch ${batch.id} kept, since the source branch could not be confirmed: ` +
+            (suppression.intervals.length > 0
+              ? `a start on ${targetBranch} finishes its removals and retires it`
+              : 'the next start retires it') + `, none of its marks sent${redoFromSource}`;
+        } else {
+          try {
+            await outbox.discard(batch.id);
+            retire = `; awareness batch ${batch.id} retired, none of its marks sent${redo}`;
+          } catch (discardError) {
+            // None of its marks is ever sent: a start retires it. A write that
+            // fails leaves the batch as it was, prepared, as in the host's
+            // retireAfterRestore. A suppression's removals stay pending for
+            // its target branch: a start on a branch with that name finishes
+            // them.
+            const detail = boundDiscordAwarenessText(
+              discardError instanceof Error ? discardError.message : String(discardError),
+            );
+            const kept = `; awareness batch ${batch.id} could not be retired (${detail}); it stays prepared, none of ` +
+              'its marks to be sent';
+            if (suppression.intervals.length === 0) {
+              retire = `${kept}, until the next start retires it${redo}`;
+            } else {
+              let forked = true;
+              try {
+                forked = store.listBranches().some((branch) => branch.name === targetBranch);
+              } catch { /* unknown: say what a start on an existing branch would do */ }
+              retire = `${kept}. Its removals stay pending for ${targetBranch}: a start on a branch with that ` +
+                'name would finish them there and retire the batch' + (forked
+                ? `, and ${targetBranch} is kept, so delete it unless you want that, through the host API's ` +
+                  'branch.delete once the host runs'
+                : '') + redo;
+            }
+          }
+        }
       }
-      throw error;
+      // A partly suppressed branch is unsafe to start on, unless its batch was
+      // kept because the source couldn't be confirmed: a start on it then
+      // completes the suppression, as the batch's note says.
+      const kept = createdBranch === undefined ? ''
+        : suppression.intervals.length === 0 ? `; branch ${createdBranch} is kept for diagnosis`
+        : batch && !sourceConfirmed ? `; branch ${createdBranch} is kept: it may be partly suppressed`
+        : `; branch ${createdBranch} is kept for diagnosis: it may be partly suppressed, so don't start on it, and ` +
+          'delete it once it has been looked at (the host API\'s branch.delete, once the host runs)';
+      if (!restore && !retire && !kept) throw error;
+      throw new Error(`${failure}${restore}${kept}${retire}`, { cause: error });
     }
 
-    return result;
+    // The body change landed. Marker bookkeeping is reported apart from it
+    // and never undoes it.
+    const facts = {
+      scope: (marks === 'none' ? 'none' : marks.scope) as SurgeryMarkerReceipt['scope'],
+      unmarked: selection.unmarked,
+      notRemoved: selection.notRemoved,
+    };
+    let markers: SurgeryMarkerReceipt = { ...facts, status: 'none', queued: 0 };
+    let suppressionRecord: string | undefined;
+    if (batch) {
+      const settled = await outbox.settleActivation(batch.id);
+      if (batch.refs.length > 0) {
+        markers = settled.status === 'queued'
+          ? { ...facts, status: 'queued', queued: settled.queued, batchId: batch.id }
+          : { ...facts, status: 'not-scheduled', queued: 0, error: settled.error };
+      } else if (settled.status === 'not-scheduled') {
+        // A suppression-only batch carries no marks, and its activation
+        // closes the body's resume record: if that failed, say what became of it.
+        suppressionRecord = `the resume record (awareness batch ${batch.id}, no marks) could not be closed: ${settled.error}`;
+      }
+    }
+    return { ...result, discordMarkersQueued: markers.queued, markers, ...(suppressionRecord ? { suppressionRecord } : {}) };
   } finally {
     contextManager?.close();
     store.close();
@@ -372,8 +504,7 @@ function buildSuppressionPlan(
   targetIndex: number,
   rawMessageIds: string[],
   rawRanges: Array<{ fromMessageId: string; toMessageId: string }>,
-  forcedServerId?: string,
-): { intervals: SuppressionInterval[]; refs: DiscordAwarenessRef[]; messageCount: number } {
+): { intervals: SuppressionInterval[]; carriers: DiscordMessageMetadataCarrier[]; messageCount: number } {
   const messageIds = rawMessageIds.map(normalizeDiscordMessageId);
   const ranges = rawRanges.map((range) => ({
     fromMessageId: normalizeDiscordMessageId(range.fromMessageId),
@@ -383,7 +514,7 @@ function buildSuppressionPlan(
     ...messageIds,
     ...ranges.flatMap((range) => [range.fromMessageId, range.toMessageId]),
   ]);
-  if (wanted.size === 0) return { intervals: [], refs: [], messageCount: 0 };
+  if (wanted.size === 0) return { intervals: [], carriers: [], messageCount: 0 };
 
   const locations = new Map<string, MessageLocation>();
   for (let offset = 0; offset <= targetIndex; offset += RECOVERY_SCAN_WINDOW) {
@@ -473,45 +604,48 @@ function buildSuppressionPlan(
     }
   }
 
-  const refs: DiscordAwarenessRef[] = [];
+  const carriers: DiscordMessageMetadataCarrier[] = [];
   for (const interval of merged) {
-    refs.push(...collectDiscordRefs(
-      contextManager,
-      interval.start,
-      interval.end + 1,
-      forcedServerId,
-    ));
+    carriers.push(...collectDiscordCarriers(contextManager, interval.start, interval.end + 1));
   }
   return {
     intervals: merged,
-    refs: dedupeDiscordRefs(refs),
+    carriers,
     messageCount: merged.reduce((sum, interval) => sum + interval.end - interval.start + 1, 0),
   };
 }
 
-function collectDiscordRefs(
+/**
+ * The addressing metadata of removed messages, read in bounded windows: only
+ * the Discord address and the MCPL tags (for `addressed` selection) are kept,
+ * never content. A sharded message may repeat its metadata across adjacent
+ * records; selection dedupes by address.
+ */
+function collectDiscordCarriers(
   contextManager: ContextManager,
   start: number,
   end: number,
-  forcedServerId?: string,
-): DiscordAwarenessRef[] {
-  const refs: DiscordAwarenessRef[] = [];
+): DiscordMessageMetadataCarrier[] {
+  const carriers: DiscordMessageMetadataCarrier[] = [];
   for (let offset = start; offset < end; offset += RECOVERY_SCAN_WINDOW) {
     const messages = contextManager.getMessageWindow(
       offset,
       Math.min(RECOVERY_SCAN_WINDOW, end - offset),
       { resolveBlobs: false },
     ).messages;
-    refs.push(...extractDiscordAwarenessRefs(messages, forcedServerId));
+    carriers.push(...messages.map(addressingOnly));
   }
-  // A sharded message may repeat Discord metadata across adjacent records.
-  return dedupeDiscordRefs(refs);
+  return carriers;
 }
 
-function dedupeDiscordRefs(refs: DiscordAwarenessRef[]): DiscordAwarenessRef[] {
-  const deduped = new Map<string, DiscordAwarenessRef>();
-  for (const ref of refs) {
-    deduped.set(`${ref.serverId}\0${ref.channelId}\0${ref.messageId}`, ref);
-  }
-  return [...deduped.values()];
+function addressingOnly(message: { metadata?: Record<string, unknown> }): DiscordMessageMetadataCarrier {
+  const metadata = message.metadata ?? {};
+  return {
+    metadata: {
+      serverId: metadata.serverId,
+      channelId: metadata.channelId,
+      messageId: metadata.messageId,
+      tags: metadata.tags,
+    },
+  };
 }

package/src/recovery/recover-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { createOfflineRecoveryBranch } from './offline-branch.js';
+import type { DiscordAwarenessMarks } from './discord-awareness-outbox.js';
 
 interface CliOptions {
   storePath?: string;
@@ -15,6 +16,7 @@ interface CliOptions {
   discordServerId?: string;
   outboxPath?: string;
   emoji?: string;
+  marks: 'none' | 'addressed' | 'all';
   dryRun: boolean;
 }
 
@@ -22,9 +24,12 @@ function usage(): string {
   return `Usage:
   agent-framework-recover --store <path> --agent <name> <anchor> [options]
 
-Creates and activates a Chronicle recovery branch while the normal host is down,
-then queues Discord reactions for addressable messages removed from awareness.
-Message content is never compiled or written to the recovery outbox.
+Creates and activates a Chronicle recovery branch while the normal host is
+down. The recovery is local to the resident: by default no Discord reaction is
+placed. --marks chooses to mark removed Discord messages with an awareness
+reaction (queued here, delivered when the host and its Discord MCPL server
+next connect). Message content is never compiled or written to the awareness
+ledger.
 
 Options:
   --message-id <id|link>      Last Discord message the agent should still see
@@ -35,6 +40,10 @@ Options:
   --branch <name>             Recovery branch name (generated by default)
   --namespace <namespace>     Context namespace (default: agents/<agent>)
   --discord-server <id>       Override/inject the Discord MCPL server id
+  --marks <none|addressed|all>
+                              Awareness marks on removed Discord messages
+                              (default none; addressed = mentions, replies to
+                              the bot and DMs; all = every addressable message)
   --outbox <path>             Override the branch-independent outbox path
   --emoji <emoji>             Marker reaction (default: 💤)
   --dry-run                   Inspect counts/addresses without writing
@@ -44,7 +53,7 @@ The agent host must be stopped before running this command.`;
 }
 
 function parseArgs(args: string[]): CliOptions {
-  const options: CliOptions = { dryRun: false, suppressMessageIds: [], suppressRanges: [] };
+  const options: CliOptions = { dryRun: false, suppressMessageIds: [], suppressRanges: [], marks: 'none' };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     const value = () => {
@@ -80,6 +89,14 @@ function parseArgs(args: string[]): CliOptions {
       case '--discord-server': options.discordServerId = value(); break;
       case '--outbox': options.outboxPath = value(); break;
       case '--emoji': options.emoji = value(); break;
+      case '--marks': {
+        const marks = value();
+        if (marks !== 'none' && marks !== 'addressed' && marks !== 'all') {
+          throw new Error('--marks must be none, addressed or all');
+        }
+        options.marks = marks;
+        break;
+      }
       case '--dry-run': options.dryRun = true; break;
       case '--help':
       case '-h':
@@ -101,6 +118,9 @@ async function main(): Promise<void> {
     throw new Error(`--store, --agent, and one anchor (--message-id, --context-id, or --messages) are required\n\n${usage()}`);
   }
 
+  // A CLI choice and its application are the same moment (the host is
+  // stopped), so the scope is evaluated now rather than frozen to refs.
+  const marks: DiscordAwarenessMarks = options.marks === 'none' ? 'none' : { scope: options.marks };
   const result = await createOfflineRecoveryBranch({
     storePath: options.storePath,
     agentName: options.agentName,
@@ -114,6 +134,7 @@ async function main(): Promise<void> {
     discordServerId: options.discordServerId,
     outboxPath: options.outboxPath,
     emoji: options.emoji,
+    marks,
     dryRun: options.dryRun,
   });
 

package/src/send-tools.ts

@@ -0,0 +1,11 @@
+/**
+ * Tools whose call delivers the resident's message to a channel or person,
+ * by bare name (an MCPL server's `<prefix>--` stripped). The framework reads
+ * a call of one as an explicit send that silences the round's auto-routed
+ * prose; the history module's semantic index reads its message argument as
+ * what the resident wrote to someone, whether or not it was delivered.
+ */
+export const SEND_TOOLS = new Set(['channel_publish', 'send_message', 'reply_message', 'send_dm']);
+
+/** Strip the `server--` MCPL prefix from a tool name. */
+export const bareToolName = (n: string): string => n.split('--').pop()!;

package/src/timezone.ts

@@ -2,8 +2,10 @@
  * Agent-visible wall-clock formatting.
  *
  * Persistence and protocol timestamps should remain epoch milliseconds or UTC
- * ISO strings.  These helpers are only for presentation boundaries where a
- * timestamp is rendered into an agent's context or a tool result.
+ * ISO strings.  These helpers are for presentation boundaries where a
+ * timestamp is rendered into an agent's context or a tool result, and the
+ * zone resolveTimeZone gives also places clock rows' boundaries
+ * (clock-rows.ts).
  */
 
 export function isValidTimeZone(timeZone: string): boolean {

package/src/tool-image-ledger.ts

@@ -316,7 +316,8 @@ export interface StoredCut {
   head: string;
   /** The image slots past the cut that the stored copy re-appends after its
    *  truncation notice, in text order: the newest MAX_KEPT_IMAGE_SLOTS of
-   *  those the live copy showed. */
+   *  those the live copy showed, or under a readers' bound the newest of
+   *  those that fit it, down to none (cutStoredToolResultToFit). */
   kept: string[];
   /** How many image slots past the cut the live copy showed. */
   fell: number;
@@ -326,8 +327,10 @@ export interface StoredCut {
  * Where a tool result's text longer than `cap` is cut: by its stored copy
  * (cutStoredToolResult), by history's own truncation (truncateForHistory),
  * and by its live copy, for each text block beside an image
- * (tryNativeToolResultContent, framework.ts), so the stored copy and the live
- * copy cut alike. The text's length when it isn't longer than `cap`.
+ * (tryNativeToolResultContent, framework.ts), so at one cap the stored copy
+ * and the live copy cut alike. Under a readers' bound the stored copy's cut
+ * can come earlier (cutStoredToolResultToFit). The text's length when it
+ * isn't longer than `cap`.
  *
  * The cut is made at the cap, or before it when the cap would split a
  * surrogate pair (safeSlice's rule), and that is where the moves back are
@@ -395,9 +398,13 @@ export function cutStoredToolResult(text: string, cap: number, shown: ShownRange
 /** What a stored copy re-appends after its truncation notice: the kept
  *  slots, each on its own line so a reference stub stays parseable, under a
  *  note saying how many fell past the cut, and how many of those were left
- *  out and aren't counted. Empty when none fell past the cut. */
+ *  out and aren't counted, all of them where none fit the bound
+ *  (cutStoredToolResultToFit). Empty when none fell past the cut. */
 export function formatKeptImageSlots(cut: StoredCut): string {
   if (cut.fell === 0) return '';
+  if (cut.kept.length === 0) {
+    return `\n[${cut.fell} image slot(s) fell past the cut and are left out, and save_recent_image doesn't count them.]`;
+  }
   const leftOut = cut.fell - cut.kept.length;
   const note = leftOut === 0
     ? `${cut.fell} image slot(s) fell past the cut; kept here in order so save_recent_image still counts them:`
@@ -406,14 +413,61 @@ export function formatKeptImageSlots(cut: StoredCut): string {
   return `\n[${note}]\n${cut.kept.join('\n')}`;
 }
 
+/** The most a stored copy's truncation notice takes (spillOrTruncate,
+ *  framework.ts): the spill notice names its file twice, once in its paging
+ *  advice, and fits this on a path from a mount name of up to about seventy
+ *  characters. */
+export const TOOL_RESULT_NOTICE_ROOM = 640;
+
+/**
+ * A result's cap and bound when its message holds `n` results. A reader's
+ * strategy spends its per-message bound across the message's blocks in
+ * order, so each result takes an equal share of the readers' smallest
+ * bound, fixed before any result is cut, since its siblings may still be
+ * running when save_recent_image counts it, and its cap is at most that
+ * share. `keptCap` is where a withheld stub's kept fields are cut, leaving
+ * the stub's notice its room (tool-result-guard.ts). With no bound, each
+ * keeps the cap.
+ */
+export function toolResultShare(cap: number, bound: number | undefined, n: number): { cap: number; bound: number | undefined; keptCap: number } {
+  if (bound === undefined) return { cap, bound, keptCap: cap };
+  const share = Math.floor(bound / Math.max(1, n));
+  return { cap: Math.min(cap, share), bound: share, keptCap: Math.min(cap, Math.max(1, share - TOOL_RESULT_NOTICE_ROOM)) };
+}
+
+/**
+ * Cut a tool result's text at `cap` as cutStoredToolResult does, unless its
+ * stored copy would then pass `bound`, the most a reader's strategy keeps of
+ * it (toolResultShare): the head, room for the notice after it, and the kept
+ * slots after that (formatKeptImageSlots). A strategy cuts a longer message
+ * from its end, and with it the notice that holds the way to the rest, so
+ * there the head moves back until the copy fits. The kept slots grow as the
+ * head moves back, so the cut is found again until head and slots fit or the
+ * head is empty. Slots that alone pass the room keep the newest that fit,
+ * the rest left out and uncounted, as past MAX_KEPT_IMAGE_SLOTS. A bound
+ * under the notice's room can't hold the notice. With no bound, or where the
+ * cut at the cap already fits, the cut is cutStoredToolResult's.
+ */
+export function cutStoredToolResultToFit(text: string, cap: number, shown: ShownRanges | null, bound: number | undefined): StoredCut {
+  let cut = cutStoredToolResult(text, cap, shown);
+  if (bound === undefined || text.length <= cap) return cut;
+  const room = bound - TOOL_RESULT_NOTICE_ROOM;
+  while (cut.head.length > 0 && cut.head.length + formatKeptImageSlots(cut).length > room) {
+    cut = cutStoredToolResult(text, Math.max(0, room - formatKeptImageSlots(cut).length), shown);
+  }
+  while (cut.kept.length > 0 && formatKeptImageSlots(cut).length > room) cut = { ...cut, kept: cut.kept.slice(1) };
+  return cut;
+}
+
 /**
  * The image slots a tool result's stored copy holds: its text's, or, when the
  * text is longer than `cap`, those the cut keeps, in head and after the
- * notice (cutStoredToolResult). The notice itself holds none. For counting a
- * result before its stored copy is written, as it will count after.
+ * notice (cutStoredToolResultToFit, under the readers' `bound`). The notice
+ * itself holds none. For counting a result before its stored copy is
+ * written, as it will count after.
  */
-export function storedImageSlots(text: string, cap: number, shown: ShownRanges | null): ParsedImagePlaceholder[] {
-  const cut = cutStoredToolResult(text, cap, shown);
+export function storedImageSlots(text: string, cap: number, shown: ShownRanges | null, bound: number | undefined): ParsedImagePlaceholder[] {
+  const cut = cutStoredToolResultToFit(text, cap, shown, bound);
   return parseImagePlaceholders(cut.head + formatKeptImageSlots(cut));
 }