@animalabs/agent-framework 0.27.0 → 0.28.0

package/src/modules/workspace/read-page.ts

@@ -1,6 +1,7 @@
 import type { ToolResult } from '../../types/events.js';
 import { answerText, fieldLine, sectionLead, sectionText, textAnswer } from './result-text.js';
 import { type FileText, MAX_LINE_CHARS, numberedLine, safeCut } from './text.js';
+import { didNothing } from './answers.js';
 
 /**
  * One page of a read, held to the result limit as its text measures it: a
@@ -184,7 +185,12 @@ export function characterPage(path: string, file: FileText, offsetChars: number,
   const text = file.raw;
   const start = Math.min(offsetChars, text.length);
   if (splitsPair(text, start)) {
-    return { success: false, isError: true, error: 'offsetChars splits a surrogate pair; use nextOffsetChars from the previous page.' };
+    return {
+      success: false,
+      isError: true,
+      error: didNothing('read', `"offsetChars" ${start} falls between the two halves of a surrogate pair, one character in UTF-16. `
+        + `Give ${start - 1} or ${start + 1}; a page's nextOffsetChars never splits one.`),
+    };
   }
   let end = start + Math.min(limitChars, text.length - start);
   if (splitsPair(text, end)) end++;

package/src/modules/workspace/reconcile.ts

@@ -53,9 +53,11 @@ import {
   sameRootIdentity,
 } from './disk-agreement.js';
 import type { BranchIntent, BranchIntents, ConflictKind, ConflictRecord, DiskCounterpart } from './branch-intent.js';
+import { storedBytes, type StoredBytes } from './sync.js';
 import {
   IGNORED,
   type MountView,
+  NOT_A_DIRECTORY,
   OTHER_MOUNT,
   ROOT_REPLACED,
   type Walk,
@@ -75,6 +77,7 @@ import {
   withinIncludes,
 } from './observe.js';
 import { EffectFailed, type Expect, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
+import { errnoWords } from './answers.js';
 
 export type EntryState =
   | 'synced'
@@ -486,7 +489,7 @@ function inTheWay(reason: string | undefined, deletion: boolean): string | null
   }
   // A deletion below a file finds nothing there to unlink, so only a write
   // meets this one.
-  if (reason === 'a parent path is not a directory') {
+  if (reason === NOT_A_DIRECTORY) {
     return 'disk has a file or a symlink where this path needs a directory, and no push writes below one, forced or not — ' +
       'move or remove it on disk and materialize again, or write the file under another path';
   }
@@ -506,7 +509,7 @@ function inTheWay(reason: string | undefined, deletion: boolean): string | null
  * to pass.
  */
 function forcedWay(note: string | undefined, deletion: boolean, forced: string): string {
-  if (note === 'cannot open (EACCES)') return `, or, if disk lets the workspace ${deletion ? 'unlink' : 'write'} the file, ${forced}`;
+  if (note === `cannot open (${errnoWords('EACCES')})`) return `, or, if disk lets the workspace ${deletion ? 'unlink' : 'write'} the file, ${forced}`;
   return '';
 }
 
@@ -914,8 +917,8 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
       byDesign = OTHER_MOUNT;
     } else if (!opts.named) {
       const slash = path.lastIndexOf('/');
-      const above = slash < 0 ? undefined : passedOverAt(path.slice(0, slash), mount.view.ignore, mount.view.others);
-      const own = above === undefined && !walk ? passedOverAt(path, mount.view.ignore, mount.view.others) : undefined;
+      const above = slash < 0 ? undefined : passedOverAt(path.slice(0, slash), mount.view.ignore, mount.view.others, true);
+      const own = above === undefined && !walk ? passedOverAt(path, mount.view.ignore, mount.view.others, false) : undefined;
       byDesign = above ?? own;
     } else if (scope.kind === 'dir') {
       byDesign = passedOverBetween(scope.dir, path, ignoreBeneath(scope.dir, mount.view.ignore), mount.view.others);
@@ -1028,9 +1031,13 @@ export async function reconcilePass(
   }
 
   // The evidence about to be recorded describes the root it was gathered
-  // under, which is recorded first (once per mount), so no crash can leave
-  // evidence without its root.
-  if (gathered.rootIdentity && planned.some((x) => x.verdict.adopt !== undefined || x.verdict.p !== undefined)) {
+  // under, which is recorded first, so no crash can leave evidence without
+  // its root. Once a root is recorded, every pass that found it offers it,
+  // evidence or none: the same root on a new device, or with its first
+  // birth time, is recorded again (recordRootIdentity writes nothing
+  // otherwise), and a quiet mount's passes are where an old record learns
+  // its birth time.
+  if (gathered.rootIdentity && (agreement.rootIdentity(mount.name) !== undefined || planned.some((x) => x.verdict.adopt !== undefined || x.verdict.p !== undefined))) {
     agreement.recordRootIdentity(mount.name, gathered.rootIdentity);
   }
 
@@ -1386,12 +1393,12 @@ export async function pushPaths(
         continue;
       }
       const priorP = p && (p.kind === 'absent' || p.kind === 'content') ? p : null;
-      const blob = store.getBlob(s.hash);
+      const stored = storedBytes(store, s.hash);
       const forcedMode = mount.modesObserved && s.mode !== undefined && s.mode !== (d.kind === 'file' ? d.mode : undefined) ? s.mode : undefined;
       const agreedMode = priorP?.kind === 'content' ? priorP.mode : undefined;
-      if (blob) {
+      if ('bytes' in stored) {
         plans.push({
-          path, kind: 'write', blob, hash: s.hash, prior: priorP, before: agreement.get(mount.name, path), expect,
+          path, kind: 'write', blob: stored.bytes, hash: s.hash, prior: priorP, before: agreement.get(mount.name, path), expect,
           ...(forcedMode !== undefined ? { apply: forcedMode } : {}),
           ...(forcedMode !== undefined && d.kind === 'file' && agreedMode !== d.mode ? { overDisk: true as const } : {}),
           ...(s.mode !== undefined ? { storeMode: s.mode } : {}),
@@ -1400,7 +1407,7 @@ export async function pushPaths(
           ...(agreedMode !== undefined ? { priorMode: agreedMode } : {}),
           ...(d.kind === 'file' && d.mode !== undefined ? { seenMode: d.mode } : {}),
         });
-      } else result.skipped.push({ path, reason: 'the workspace copy is missing from the store' });
+      } else result.skipped.push({ path, reason: unstoredCopy(stored) });
       continue;
     }
     if (v.mode === 'adopt' && s && d.kind === 'file') {
@@ -1426,7 +1433,7 @@ export async function pushPaths(
     }
     // Whatever the verdict learned about disk (an agreement, a resolved
     // intent) is recorded before anything is pushed over it, and the root it
-    // was learned under before that (once per mount), as a pass does.
+    // was learned under before that, as a pass does.
     if (v.p !== undefined) agreement.recordRootIdentity(mount.name, root.identity);
     if (v.p === 'forget') agreement.forget(mount.name, path);
     else if (v.p !== undefined) agreement.set(mount.name, path, v.p, { afterCommittedState: true });
@@ -1551,11 +1558,12 @@ export async function pushPaths(
       plans.push({ path, kind: 'unlink', prior, before: agreement.get(mount.name, path), expect });
       continue;
     }
-    const blob = store.getBlob(s.hash);
-    if (!blob) {
-      result.skipped.push({ path, reason: 'the workspace copy is missing from the store' });
+    const stored = storedBytes(store, s.hash);
+    if (!('bytes' in stored)) {
+      result.skipped.push({ path, reason: unstoredCopy(stored) });
       continue;
     }
+    const blob = stored.bytes;
     // The store's mode goes to disk with its bytes where the file is new,
     // the push is forced, or disk still has the mode they last agreed on. A
     // push that completes our own unconfirmed one, whose bytes landed, is a
@@ -1774,3 +1782,7 @@ export async function pushPaths(
   agreement.maybeCheckpoint();
   return result;
 }
+
+function unstoredCopy(stored: Exclude<StoredBytes, { bytes: Buffer }>): string {
+  return 'missing' in stored ? 'the workspace copy is missing from the store' : `the workspace copy is unreadable in the store (${stored.unreadable})`;
+}

package/src/modules/workspace/result-text.ts

@@ -30,6 +30,8 @@ export function shownValue(value: string | number | boolean | null): string {
   return JSON.stringify(value).replace(/[\u0085\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
 }
 
+export type DiskState = 'done' | 'waits for materialize' | 'waits for materialize with applyDeletions' | 'in conflict with disk';
+
 /** A header line: a field's key and its value as shownValue writes it. */
 export const fieldLine = (key: string, value: string | number | boolean | null): string => `${key}: ${shownValue(value)}`;
 

package/src/modules/workspace/sync.ts

@@ -6,6 +6,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { JsStore } from '@animalabs/chronicle';
 
 export const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
 
@@ -18,3 +19,18 @@ export function hashContent(content: string | Buffer): string {
   hash.update(content);
   return hash.digest('hex');
 }
+
+export type StoredBytes = { bytes: Buffer } | { missing: true } | { unreadable: string };
+
+export function storedBytes(store: JsStore, hash: string): StoredBytes {
+  try {
+    const blob = store.getBlob(hash);
+    return blob ? { bytes: blob } : { missing: true };
+  } catch (error) {
+    if (store.isClosed()) throw error;
+    // Chronicle's getBlob throws, rather than answering null, for a blob file
+    // it can't read whole or whose format, checksum or hash doesn't check out,
+    // such as one a write cut short left truncated.
+    return { unreadable: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/modules/workspace/types.ts

@@ -58,7 +58,7 @@ export interface MountConfig {
    *   link is read and written where it leads now. Where that root now lies
    *   elsewhere than the last start placed it, each call nests in it, as a
    *   start would now, every mount
-   *   configured beneath its path, where that path leads beneath its root,
+   *   configured on or beneath its path, where that path leads beneath its root,
    *   and every other mount whose root, as that start placed it, lies
    *   beneath where its root lies now, or whose configured path lies
    *   beneath a directory that start found there. A mount configured
@@ -101,10 +101,32 @@ export interface MountConfig {
   /** Poll interval in ms for checking watched root identity changes (default: 2000) */
   watchRootPollMs?: number;
   /**
-   * Simple ignore patterns (NOT full gitignore syntax). Supported forms:
-   * - Exact name match: ".git", "node_modules"
-   * - Directory glob: "node_modules/**" (anything under node_modules)
-   * - Extension glob: "*.pyc" (any file ending in .pyc)
+   * Patterns in these of gitignore's forms, each covering the files
+   * gitignore's reading of it covers, with three differences: names compare
+   * exactly, as git's do with `core.ignorecase` off (its default folds case
+   * on macOS and Windows); "?" matches one character where git's matches
+   * one byte, so the two differ on names outside ASCII; and on a mount that
+   * follows links, a link to a directory counts as a directory, where git
+   * reads every link as a file:
+   * - A name, matched at any depth: ".git", "node_modules". Within a name,
+   *   "*" matches any run of characters and "?" any one: "*.pyc",
+   *   "npm-debug.log*".
+   * - A trailing "/" matches only a directory: "build/" covers every
+   *   directory named build, with what lies beneath it, and no file of that
+   *   name.
+   * - A leading or inner "/" makes a path from the mount's root: "/dist"
+   *   covers only the root's dist, and "a/b" only the root's a/b.
+   * - "**" as the first segment, before one name, matches that name at any
+   *   depth, as the name alone does; with a trailing "/**" as well, it reads
+   *   as the name with a trailing "/".
+   * - A trailing "/**" covers a directory from the root and what lies
+   *   beneath it: "node_modules/**" covers only the root's node_modules, and
+   *   no file of that name.
+   * The module refuses, when it's built, a pattern of any other form, such as
+   * a leading "!" or "#", a "[", a "\", a trailing space, "**" anywhere
+   * else, or an empty, "." or ".." segment, naming the pattern and why. A
+   * "?" can stand for a "[" or "\" in a name.
+   *
    * A sync without a path and the watcher pass over what the list covers,
    * and over entries with an editor's swap or backup file name whatever it
    * says, a directory with what lies beneath it: `.name.swp` and `.name.swx`
@@ -124,13 +146,17 @@ export interface MountConfig {
   ignore?: string[];
   /**
    * The files this mount holds, when it holds only some of what is under its
-   * path: the same pattern forms as `ignore`, read for files. A name or an
-   * extension glob covers a file by its own name, at any depth, and a directory
-   * glob (`dir/**`) covers what lies beneath that directory, and not a file
-   * named like it. Unlike `ignore`, a pattern that matches a directory's name
-   * covers nothing beneath it, since each file is covered by its own name:
-   * `["gate.json"]` holds every file named `gate.json`, and no other file
-   * beneath a directory of that name. A subtree is named with `dir/**`.
+   * path: patterns in `ignore`'s forms, read for files, and a `[` read as
+   * itself, so `[id].tsx` names that file. A pattern that matches
+   * only directories, with a trailing `/` or `/**`, covers what lies beneath a
+   * directory it matches: `fixtures/` every file beneath a directory named
+   * fixtures, at any depth, and `docs/**` or `/docs/` every file beneath the
+   * root's docs. Any other pattern covers a file by its own name, at any
+   * depth, or by its path from the root (`/gate.json`, `src/*.ts`). Unlike
+   * `ignore`, such a pattern covers nothing beneath a directory it matches,
+   * since each file is covered by its own name or path: `["gate.json"]` holds
+   * every file named `gate.json`, and no other file beneath a directory of
+   * that name.
    *
    * It's the mount's boundary for content: no workspace path reads, stores,
    * serves or writes back a file it doesn't cover, and no tool lists,
@@ -199,31 +225,62 @@ export interface MountConfig {
    * A path in a nested mount's directory is that mount's, whatever this
    * include covers: every tool gives the answer that names the mount holding
    * it and the path to use there. Through a link a mount follows, a place in
-   * that directory is named only where it's a directory, or a file that
-   * mount's own include covers with no file on its way, and is otherwise
-   * refused as leaving the mount. On a mount that doesn't follow links, a
-   * link on a path's way is refused, as on any such mount (followSymlinks).
-   * A nested mount's root is placed where disk has it at each start, and its
-   * directory is matched by spelling, so four cases fall outside this, as
-   * for any nested mount, and a fifth on a direct one: on a disk that folds
-   * names, a mount configured
-   * through a link that spells a directory otherwise than disk does isn't
-   * found nested, and this mount holds its files as its own; on such a disk,
-   * a path through a link that spells a nested mount's directory otherwise
-   * than that mount's configured path does, whether the link or the
-   * configured path is the one spelled otherwise than disk, isn't found to
-   * lead there, and this mount reads, lists, searches and writes there as
-   * its own, creating files too, though a walk from its root passes over the
-   * directory; on such a disk, a place in a nested mount's directory that a
-   * link does lead to is judged by that mount's include, and named, in the
-   * spelling the link's target gives, so a refusal can name a file disk
-   * spells outside that include, or leave a covered one unnamed; and a
-   * nested mount whose root moves while running, as `acceptRoot` takes,
-   * stays placed where it was until the next start; and where a direct
-   * mount's root is repointed between a read's parse and its open, a race
-   * left to whoever writes the disk, a mount nested in it by its
-   * directories alone, since its real root holds that root, can have the
-   * read serve a path in its directory.
+   * that directory is named only where it's a directory, or a file covered,
+   * with no file on its way, by that mount's own include and by the include
+   * of each other nested mount whose directory may hold it, from the
+   * innermost out to the first that surely holds it, and is otherwise
+   * refused as leaving the mount. A listing, or a pass, names a file there
+   * only where those includes cover it. On a mount that doesn't follow
+   * links, a link on a path's way is refused, as on any such mount
+   * (followSymlinks).
+   * Every check compares a path with a nested mount's directory level by
+   * level, as any disk may compare names: in either Unicode normalization
+   * form and in any case, as fully as a disk that folds names may compare
+   * them, at every level, whatever the disk does there, and reading nothing
+   * from the disk to do so. Start places each root the same way, so a mount
+   * configured through a link, or in a spelling, other than disk's is found
+   * nested. So a path, a walk or the workspace's history that names the
+   * directory in any spelling a disk may take for it reaches that mount,
+   * whether or not the directory is on disk yet, and so does a link whose
+   * target spells it otherwise. Where a link leads into the directory, the
+   * place beneath it is judged, and named, as disk spells it. A path that names the directory itself keeps what lies
+   * beneath as given, since that is the nested mount's to name. Where a disk
+   * keeps apart two names the comparison joins, it errs toward the nested
+   * mount, in where start places a mount as in every check: a name in
+   * another case, on a disk that tells case apart; a name in the other
+   * normalization form, on a disk that keeps the forms apart; and a name the
+   * comparison folds with it that a disk keeps apart, such as `ss` beside a
+   * nested `ß`, or one that differs from it only by a default-ignorable code
+   * point, such as a soft hyphen, on a disk that keeps those. Such a
+   * directory, or file, is no mount's, and every tool that names it is
+   * refused as a path that may lie in the nested mount, with the two
+   * spellings the workspace can't tell apart, and, for a link, where it
+   * leads, when that lies in this mount. The answer gives a step for each
+   * thing the caller may have meant: that mount's path to use; for a new
+   * file of this mount's, a path outside both spellings; and for one already
+   * there, whoever runs the workspace renaming one of the two spellings.
+   * Where start placed the nested mount only by a guess, comparing the real
+   * roots, as for two mounts' roots configured in spellings it can't tell
+   * apart, a path there is a guess too, however exactly it matches, and the
+   * answer names that directory as the path spells it, with the nested
+   * directory's spelling only in the step for a new file, names no host
+   * path, and asks for the configuration to be checked. Three cases fall
+   * outside this, as for any nested mount, and a fourth on a direct one: on a
+   * disk whose folding goes past the comparison's, which joins names that
+   * differ only by default-ignorable code points, in normalization form or in
+   * case, in full case folding, as Linux's casefold does, a name the
+   * comparison keeps apart can reach the directory; a second path to the
+   * directory that isn't a link, such as a bind mount, isn't found to lead
+   * there, though a walk passes over it, knowing each nested root by which
+   * directory it is; a nested mount whose root moves while running, as
+   * `acceptRoot` takes, stays placed where it was until the next start, but
+   * for the calls of a direct mount whose root has moved and on or beneath
+   * whose path it's configured, which place it where it lies; and where a
+   * direct mount's root is repointed between a read's parse and its open, or
+   * a write's parse and its staging, a race left to whoever writes the disk,
+   * a mount nested in it by its directories alone, since its real root holds
+   * that root, can have the read serve a path in its directory, or the write
+   * land there.
    *
    * Text the host registers for a path (`registerGeneratedTextFile`) is
    * served there whatever the include says, since it isn't one of the
@@ -237,12 +294,8 @@ export interface MountConfig {
    * include covers it.
    *
    * Left out, the mount holds everything under its path. Given, it's a list
-   * of at least one string, each a name, an `*.ext` glob or a `dir/**` glob,
-   * whose directory may be nested (`a/b/**`). The module refuses a pattern
-   * with a `/` that isn't such a glob, a `*` anywhere but a leading `*.` or
-   * that trailing `/**`, an empty, `.` or `..` segment, and, where `\` is the
-   * platform's separator, a `\`. Any other pattern is a file name, matched
-   * literally, so `[id].tsx` names the file of that name.
+   * of at least one pattern, and the module refuses one `ignore` would
+   * refuse but for a `[`.
    */
   include?: string[];
   /**

package/src/modules/workspace/watcher.ts

@@ -126,10 +126,15 @@ export class MountWatcher {
       // another mount's directory, the mount's ignore list and editors' swap
       // and backup files. chokidar 4
       // compares a string given here with the whole absolute path, so the
-      // list itself would match nothing.
-      ignored: (path: string) => {
+      // list itself would match nothing. It asks without stats before it
+      // stats a path, asking again with them before it watches the path, and
+      // when a path it watches is removed. So where it gives no kind, no
+      // directory-only pattern matches: a directory one matches never passed
+      // the check with its stats, so it is never watched, and its removal
+      // never reported.
+      ignored: (path: string, stats?: Stats) => {
         const relative = this.toRelative(path);
-        return relative !== null && passedOverAt(relative, ignore, this.others) !== undefined;
+        return relative !== null && passedOverAt(relative, ignore, this.others, stats?.isDirectory() ?? false) !== undefined;
       },
       // Its filter for editors' files tested the whole path, so a directory
       // with a dot in its name hid every `*.swp` beneath it, and the walk

package/src/prose-drafts.ts

@@ -2,8 +2,9 @@
  * Held prose drafts: a resident's plain speech that was not sent.
  *
  * Plain speech is held back for reasons that are right in themselves: an
- * explicit send in the same round suppresses the round's prose (so a "sent
- * it" postscript is not posted twice), a turn may have no destination, and a
+ * explicit send suppresses plain speech aimed where it may have posted, in
+ * its round and the turn's later ones (so a "sent it" postscript is not
+ * posted twice), a turn may have no destination, and a
  * malformed or unresolvable routing prefix bounces. Before drafts, the held words were
  * kept only as a count (or, in explicit mode, as one in-memory latest-wins
  * clipboard): the law was right, and the penalty was amnesia. A draft keeps
@@ -53,7 +54,7 @@ export const PROSE_DRAFT_RECORD_TYPE = 'framework/prose-draft';
 
 /** Why words were held instead of sent. */
 export type DraftReason =
-  /** An explicit send in the same round suppressed the round's plain speech. */
+  /** An explicit send in its turn may have posted where the speech was going. */
   | 'explicit-send'
   /** The speech had no destination (no route this turn, or a failed envelope). */
   | 'no-destination'

package/src/reasoning-loss-notice.ts

@@ -0,0 +1,62 @@
+import { safeSlice } from './safe-slice.js';
+
+export type ReasoningLossCause = 'tools' | 'system' | 'model';
+
+export type ReasoningLossAnchor = { text: string } | { toolCall: string };
+
+export interface ReasoningLossNoticeInput {
+  agentName: string;
+  scope:
+    | { kind: 'all'; through?: ReasoningLossAnchor; thisTurn: boolean }
+    | { kind: 'some'; count: number; first?: ReasoningLossAnchor; unplaced?: boolean; thisTurn: boolean };
+  causes: readonly ReasoningLossCause[];
+}
+
+const ANCHOR_CHARS = 80;
+
+const CAUSE_WORDS: Record<ReasoningLossCause, string> = {
+  tools: 'your tools changed',
+  system: 'your system prompt changed',
+  model: 'your model changed',
+};
+const CAUSE_ORDER: readonly ReasoningLossCause[] = ['tools', 'system', 'model'];
+
+export function reasoningLossNotice(input: ReasoningLossNoticeInput): string {
+  const causes = CAUSE_ORDER.filter((c) => input.causes.includes(c)).map((c) => CAUSE_WORDS[c]);
+  const because = causes.length > 0 ? `, because ${joinAnd(causes)}` : '';
+  const scope = input.scope;
+  let lost: string;
+  let reread: string;
+  if (scope.kind === 'all') {
+    const through = scope.through ? anchorWords(scope.through) : undefined;
+    const among = scope.thisTurn ? ", this turn's earlier steps among them," : '';
+    lost = through
+      ? `The reasoning behind your replies up to the one ${through}${among} is no longer in your context${because}.`
+      : `The reasoning behind your earlier replies${among} is no longer in your context${because}.`;
+    reread = 'Re-read before relying on an earlier decision.';
+  } else {
+    const one = scope.count === 1 && !scope.unplaced;
+    const replies = scope.unplaced
+      ? `at least ${scope.count} of your replies`
+      : one ? 'one of your replies' : `${scope.count} of your replies`;
+    const named = scope.first && !scope.unplaced ? anchorWords(scope.first) : undefined;
+    const first = named ? (one ? `, the one ${named}` : `, the first being the one ${named}`) : '';
+    const among = scope.thisTurn ? (one ? ', an earlier step of this turn' : ", this turn's earlier steps among them") : '';
+    lost = `Some of your earlier reasoning is no longer in your context: the reasoning behind ${replies}${first}${among}${because}.`;
+    reread = named ? 'Re-read before relying on a decision made since then.' : 'Re-read before relying on an earlier decision.';
+  }
+  return `[reasoning] ${input.agentName}: ${lost} Their words are still here. ${reread}`;
+}
+
+function anchorWords(anchor: ReasoningLossAnchor): string | undefined {
+  if ('toolCall' in anchor) return anchor.toolCall ? `that called \`${anchor.toolCall}\`` : undefined;
+  const text = anchor.text.replace(/\s+/g, ' ').trim();
+  if (!text) return undefined;
+  const clipped = text.length > ANCHOR_CHARS ? `${safeSlice(text, 0, ANCHOR_CHARS).trimEnd()}…` : text;
+  return `beginning "${clipped}"`;
+}
+
+function joinAnd(parts: readonly string[]): string {
+  if (parts.length <= 1) return parts.join('');
+  return `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+}

package/src/reasoning-loss.ts

@@ -0,0 +1,120 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import type { MessageId, ThinkingStrip } from '@animalabs/context-manager';
+import { ThinkingLossIncidents, type PlacedDrop } from './thinking-drops.js';
+import {
+  reasoningLossNotice,
+  type ReasoningLossAnchor,
+  type ReasoningLossCause,
+} from './reasoning-loss-notice.js';
+
+export interface StoredReplyReader {
+  getMessage(id: MessageId): { sequence: number; content: readonly ContentBlock[] } | null;
+}
+
+export interface ReasoningLossTurn {
+  start?: { branch: string; sequence: number };
+}
+
+const HEAD_CAUSES: Partial<Record<NonNullable<ThinkingStrip['changed']>[number], ReasoningLossCause>> = {
+  tools: 'tools',
+  system: 'system',
+  model: 'model',
+};
+
+export class ReasoningLossTeller {
+  private readonly told = new Map<string, Map<string, Set<MessageId>>>();
+  private readonly drops = new ThinkingLossIncidents();
+
+  forStrip(
+    agentName: string,
+    branch: string,
+    strip: ThinkingStrip,
+    turn: ReasoningLossTurn,
+    store: StoredReplyReader,
+  ): string | undefined {
+    const told = this.toldFor(agentName, branch);
+    const taken = strip.newly
+      .map((id) => ({ id, sequence: store.getMessage(id)?.sequence }))
+      .sort((a, b) => (a.sequence ?? Infinity) - (b.sequence ?? Infinity));
+    const replies = taken.filter((r) => !told.has(r.id));
+    if (replies.length === 0) return undefined;
+    const thisTurn = replies.some((r) => isThisTurn(r.sequence, branch, turn));
+    if (strip.cause === 'head') {
+      const causes = (strip.changed ?? [])
+        .map((c) => HEAD_CAUSES[c])
+        .filter((c): c is ReasoningLossCause => c !== undefined);
+      const newest = taken.filter((r) => r.sequence !== undefined).at(-1);
+      const through = newest ? anchorOf(store.getMessage(newest.id)?.content) : undefined;
+      const amongThisTurn = taken.some((r) => isThisTurn(r.sequence, branch, turn));
+      for (const r of replies) told.add(r.id);
+      return reasoningLossNotice({ agentName, scope: { kind: 'all', ...(through ? { through } : {}), thisTurn: amongThisTurn }, causes });
+    }
+    if (strip.cause !== 'first' && !taken.some((r) => isThisTurn(r.sequence, branch, turn))) return undefined;
+    const first = anchorOf(store.getMessage(replies[0]!.id)?.content);
+    for (const r of replies) told.add(r.id);
+    return reasoningLossNotice({
+      agentName,
+      scope: { kind: 'some', count: replies.length, ...(first ? { first } : {}), thisTurn },
+      causes: [],
+    });
+  }
+
+  forDrops(
+    agentName: string,
+    branch: string,
+    placed: readonly PlacedDrop[],
+    turn: ReasoningLossTurn,
+    store: StoredReplyReader,
+  ): string | undefined {
+    const replies = new Map<MessageId, number>();
+    const rounds = new Set<number>();
+    let blocks = 0;
+    for (const drop of placed) {
+      if (drop.kind === 'unplaced') continue;
+      blocks++;
+      if (drop.kind === 'round') rounds.add(drop.round);
+      else for (const body of drop.bodies) replies.set(body.messageId, body.sequence);
+    }
+    const unplaced = blocks < placed.length;
+    const count = replies.size + rounds.size;
+    const ordered = [...replies].sort((a, b) => a[1] - b[1]);
+    const thisTurn = rounds.size > 0 || ordered.some(([, sequence]) => isThisTurn(sequence, branch, turn));
+    const first = ordered.length > 0 && !unplaced ? anchorOf(store.getMessage(ordered[0]![0])?.content) : undefined;
+    if (this.drops.observe(agentName, blocks, branch) === undefined) return undefined;
+    const told = this.toldFor(agentName, branch);
+    for (const id of replies.keys()) told.add(id);
+    return reasoningLossNotice({
+      agentName,
+      scope: { kind: 'some', count, ...(first ? { first } : {}), ...(unplaced ? { unplaced: true } : {}), thisTurn },
+      causes: [],
+    });
+  }
+
+  forget(agentName: string): void {
+    this.told.delete(agentName);
+    this.drops.forget(agentName);
+  }
+
+  private toldFor(agentName: string, branch: string): Set<MessageId> {
+    let branches = this.told.get(agentName);
+    if (!branches) this.told.set(agentName, (branches = new Map()));
+    let told = branches.get(branch);
+    if (!told) branches.set(branch, (told = new Set()));
+    return told;
+  }
+}
+
+function isThisTurn(sequence: number | undefined, branch: string, turn: ReasoningLossTurn): boolean {
+  return sequence !== undefined && turn.start?.branch === branch && sequence > turn.start.sequence;
+}
+
+function anchorOf(content: readonly ContentBlock[] | undefined): ReasoningLossAnchor | undefined {
+  if (!content) return undefined;
+  for (const block of content) {
+    if (block.type === 'text' && typeof block.text === 'string' && block.text.trim() !== '') return { text: block.text };
+  }
+  for (const block of content) {
+    if (block.type === 'tool_use' && typeof block.name === 'string' && block.name !== '') return { toolCall: block.name };
+  }
+  return undefined;
+}

package/src/send-tools.ts

@@ -2,8 +2,9 @@
  * 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.
+ * prose where it may have posted; 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']);
 

package/src/sent-rows.ts

@@ -152,7 +152,7 @@ export function roundRows(
  * the two alike (read from the provider on 2026-10-23: Haiku 5.5 with the drop control, on an enforcing API-key
  * organization and on a subscription account, reported no drop for either, and dropped both replies' blocks when an
  * earlier user message changed). The store's own fields beside them, such as
- * `toolName`, don't reach the provider on membrane's native path, the only one noted (membrane 0.7.1's XML
+ * `toolName`, don't reach the provider on membrane's native path, the only one noted (membrane 0.8.0's XML
  * formatter reads `toolName`, and an XML stream is never noted).
  */
 function normalizedResult(block: ContentBlock): unknown {