@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/modules/workspace/reconcile.ts

@@ -55,9 +55,25 @@ import {
 import type { BranchIntent, BranchIntents, ConflictKind, ConflictRecord, DiskCounterpart } from './branch-intent.js';
 import { storedBytes, type StoredBytes } from './sync.js';
 import {
+  BENEATH_SYMLINK,
+  type Cause,
+  CHANGED,
+  CHANGED_WALK,
+  DIRECTORY,
+  EDITOR_FILE_REASON,
+  FILE_CHANGED,
   IGNORED,
+  LEAVES_MOUNT,
+  LINK_NOT_WALKED,
+  LINK_TO_DIRECTORY,
   type MountView,
   NOT_A_DIRECTORY,
+  type NotShown,
+  NOT_FOLLOWED,
+  NOT_REGULAR,
+  OUTSIDE_PARENT,
+  RESOLVES_OUTSIDE,
+  ROOT_UNAVAILABLE,
   OTHER_MOUNT,
   ROOT_REPLACED,
   type Walk,
@@ -76,8 +92,8 @@ import {
   walkScope,
   withinIncludes,
 } from './observe.js';
-import { EffectFailed, type Expect, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
-import { errnoWords } from './answers.js';
+import { EffectFailed, type Expect, callFailed, chainOf, chmodContained, narrowedTo, syncDirectories, unlinkContained, writeContained } from './effects.js';
+import { OUTSIDE_STEP, RESOLVED_OUTSIDE_STEP, UNFOLLOWED_STEP, errnoClause, errnoWords } from './answers.js';
 
 export type EntryState =
   | 'synced'
@@ -106,6 +122,7 @@ export interface PathReport {
   mimeType?: string;
   conflict?: ConflictReport;
   note?: string;
+  noteCause?: Cause;
   /**
    * For a conflict, what this pass found on disk at the path: grep's account
    * of a conflict's disk side needs it. Listings don't show it.
@@ -150,6 +167,8 @@ export interface PassResult {
    * still the selected branch, synchronously, before it reads.
    */
   branchId?: string;
+  /** Why it decided nothing, where it didn't. */
+  undecided?: string;
 }
 
 export interface MountRuntime {
@@ -225,7 +244,7 @@ export const WALK_CAP = 5000;
 /** What a pass learned about D for one path. */
 type DiskFact =
   | { kind: 'absent' }
-  | { kind: 'unobserved'; reason: string }
+  | ({ kind: 'unobserved' } & NotShown)
   | {
       kind: 'file';
       hash: string;
@@ -379,6 +398,7 @@ interface Verdict {
   conflict?: ConflictKind;
   op?: TreeOp;
   note?: string;
+  noteCause?: Cause;
   /**
    * Disk shows what a pending push of ours intended, unconfirmed: the state
    * is decided from it, and nothing at all is recorded (see module doc).
@@ -467,21 +487,22 @@ function settleAdoption(p: Pending, s: StoreSide | null): Agreed | 'forget' {
 /**
  * What's in the way, and the way out, when disk's shape keeps a push from a
  * path: no push writes a file over a directory or unlinks one, unlinks
- * anything but a regular file or a followed symlink to one, or writes below
- * a file or a symlink the walk won't take (`writeContained`,
- * `unlinkContained`), forced or not. Null for any other reason, which is
- * passed on as it is.
+ * anything but a regular file or a followed symlink to one, writes below a
+ * file or a symlink the walk won't take, or writes or unlinks through a
+ * symlink the mount doesn't follow or one that leads out of the mount
+ * (`writeContained`, `unlinkContained`), forced or not. Null for any other
+ * reason.
  */
 function inTheWay(reason: string | undefined, deletion: boolean): string | null {
   // Observation's words for what a deletion never unlinks, which the unlink
   // refuses in the same words.
-  if (deletion && (reason === 'not a regular file' || reason === 'a symlink to a directory, not walked')) {
-    const what = reason === 'not a regular file'
+  if (deletion && (reason === NOT_REGULAR || reason === LINK_TO_DIRECTORY)) {
+    const what = reason === NOT_REGULAR
       ? 'a pipe, socket or device at this path, or a symlink to one'
       : 'a symlink to a directory at this path';
     return `disk has ${what}, and no push unlinks it, forced or not — ask whoever runs this host if it should go`;
   }
-  if (reason === 'a directory') {
+  if (reason === DIRECTORY) {
     return deletion
       ? 'disk has a directory at this path, and no push unlinks one, forced or not — if it should go, move or remove it on disk'
       : 'disk has a directory at this path, and no push writes a file over one, forced or not — ' +
@@ -493,9 +514,95 @@ function inTheWay(reason: string | undefined, deletion: boolean): string | null
     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';
   }
+  const link = reason === NOT_FOLLOWED ? 'disk has a symlink at this path, which this mount does not follow'
+    : reason === LEAVES_MOUNT ? 'this path leads out of the mount through a symlink on it'
+      : null;
+  if (link !== null) {
+    return deletion
+      ? `${link}, and no push unlinks ${reason === NOT_FOLLOWED ? 'one' : 'through one'}, forced or not — ask whoever runs this host if it should go`
+      : `${link}, and no push writes through one, forced or not — write the file under another path, ` +
+        `or whoever runs this host can remove the link, and ${THEN.write}`;
+  }
+  if (deletion && reason === BENEATH_SYMLINK) {
+    return 'a symlink on this path does not lead to a directory inside the mount, so nothing beneath it is in this mount, and no push unlinks beneath one, '
+      + `forced or not — whoever runs this host can remove the link or make it lead to a directory inside the mount, and ${THEN.unlink}`;
+  }
+  if (reason === OUTSIDE_PARENT) {
+    return `a directory on this path leads out of the mount, and no push ${deletion ? 'unlinks' : 'writes'} beneath one, forced or not — ` +
+      (deletion ? 'ask whoever runs this host if what is there should go' : 'write the file under another path');
+  }
+  if (reason === NOT_REGULAR || reason === LINK_TO_DIRECTORY) {
+    const what = reason === NOT_REGULAR ? 'a pipe, socket or device at this path, or a symlink to one' : 'a symlink to a directory at this path';
+    return `disk has ${what}, and no push writes a file over it, forced or not — write the file under another path, ` +
+      `or whoever runs this host can remove it, and ${THEN.write}`;
+  }
   return null;
 }
 
+export type Meets = 'write' | 'unlink' | 'sync' | 'list' | 'read';
+
+const AGAIN: Record<Meets, string> = {
+  write: 'materializing again',
+  unlink: 'materializing again with applyDeletions',
+  sync: 'syncing this path again',
+  list: 'listing it',
+  read: 'calling again',
+};
+
+const THEN: Record<Meets, string> = {
+  write: 'materializing again then gets past it',
+  unlink: 'materializing again with applyDeletions then gets past it',
+  sync: 'a sync of this path then takes it in',
+  list: 'the workspace then reaches it',
+  read: 'a read then reaches it',
+};
+
+const CHANGED_WHILE: ReadonlySet<string> = new Set([CHANGED, CHANGED_WALK, FILE_CHANGED]);
+
+const WALKED_PAST: ReadonlySet<string> = new Set([IGNORED, EDITOR_FILE_REASON, LINK_NOT_WALKED]);
+
+export function explained(reason: string, cause: Cause, meets: Meets): string {
+  if (meets === 'write' || meets === 'unlink') {
+    const shaped = inTheWay(reason, meets === 'unlink');
+    if (shaped !== null) return shaped;
+  }
+  return withWayOn(reason, cause, meets);
+}
+
+function withWayOn(reason: string, cause: Cause, meets: Meets): string {
+  const on = wayOn(reason, cause, meets);
+  return on === null ? reason : `${reason} — ${on}`;
+}
+
+export function wayOn(reason: string, cause: Cause, meets: Meets): string | null {
+  const lasting = `${AGAIN[meets]} won't change that; `;
+  if (reason === ROOT_UNAVAILABLE) {
+    if (cause.errno === 'ENOENT' || cause.errno === 'ENOTDIR') return `${lasting}whoever runs this host can put the mount's directory back at its path, and ${THEN[meets]}`;
+    if (cause.errno === undefined) return `${AGAIN[meets]} checks it afresh; if it's still unavailable, whoever runs this host can check the mount's directory and its path`;
+  }
+  if (cause.errno !== undefined) return errnoClause(cause.errno, AGAIN[meets], THEN[meets]);
+  if (cause.again === true || CHANGED_WHILE.has(reason)) return `${AGAIN[meets]} checks it afresh`;
+  switch (reason) {
+    case NOT_FOLLOWED:
+      return lasting + UNFOLLOWED_STEP;
+    case LEAVES_MOUNT:
+      return lasting + OUTSIDE_STEP;
+    case BENEATH_SYMLINK:
+      return `${lasting}nothing beneath it is in this mount, and whoever runs this host can make it lead to a directory inside the mount, or, where it leads to a directory outside, mount that directory`;
+    case OUTSIDE_PARENT:
+    case RESOLVES_OUTSIDE:
+      return lasting + RESOLVED_OUTSIDE_STEP;
+    case NOT_REGULAR:
+      return `${lasting}whoever runs this host can put a regular file there, and ${THEN[meets]}`;
+    case DIRECTORY:
+      return `${lasting}ls of this path lists what's in it`;
+    case LINK_TO_DIRECTORY:
+      return `${lasting}ls of the directory it leads to lists what's in it`;
+    default:
+      return meets === 'sync' && WALKED_PAST.has(reason) ? 'a sync of this path checks it' : null;
+  }
+}
+
 /**
  * The forced way out the refusal of a disk copy that couldn't be verified
  * names, if any. A forced push skips the verification, so it gets past the
@@ -513,6 +620,14 @@ function forcedWay(note: string | undefined, deletion: boolean, forced: string):
   return '';
 }
 
+const UNSETTLED = "whether disk holds the change isn't known until it's checked: a materialize of this path checks it and says how it ended";
+
+function unverifiedCopy(v: Verdict, meets: 'write' | 'unlink', forced: string): string {
+  const note = v.note ?? 'not observed';
+  const on = wayOn(note, v.noteCause ?? {}, meets);
+  return `cannot verify disk copy (${note})${on !== null ? ` — ${on}` : ''}${forcedWay(v.note, meets === 'unlink', forced)}`;
+}
+
 /**
  * The synchronous precondition of every workspace mutation: evidence owed a
  * barrier is made durable first, and an adoption left pending on the
@@ -638,6 +753,10 @@ function adoptDisk(d: Extract<DiskFact, { kind: 'absent' | 'file' }>, s: StoreSi
   return { state: 'disk-only', ...(s ? { adopt: 'drop' as const, op: 'deleted' as const } : {}), p: 'forget', intent: {} };
 }
 
+function causeOf({ errno, ownStep }: NotShown): Cause {
+  return { ...(errno !== undefined ? { errno } : {}), ...(ownStep ? { ownStep } : {}) };
+}
+
 /** The rule (see module doc). Pure. */
 function decide(
   d: DiskFact,
@@ -653,9 +772,9 @@ function decide(
   if (d.kind === 'unobserved') {
     // Disk proves nothing, but an adoption on this branch settles by the tree.
     if (pIn?.kind === 'pending' && pIn.effect === 'adopt' && pIn.branchId === branchId && !adopt) {
-      return { state: 'unverified', note: d.reason, p: settleAdoption(pIn, s) };
+      return { state: 'unverified', note: d.reason, noteCause: causeOf(d), p: settleAdoption(pIn, s) };
     }
-    return { state: 'unverified', note: d.reason };
+    return { state: 'unverified', note: d.reason, noteCause: causeOf(d) };
   }
   if (d.kind === 'unhashed') {
     // Observed this way only when nothing tracks the path, which is then a
@@ -841,6 +960,7 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
   // is followed, as `rootReal` is: `followSymlinks` governs links within it.
   const root = await locateRoot(mount.view, mount.rootReal);
   const rootUnavailable = 'reason' in root ? root.reason : null;
+  const rootCause = 'reason' in root && root.errno !== undefined ? { errno: root.errno } : {};
 
   // The branch is labelled where the tracked candidates are read, with no
   // await between: the decision is checked against this label.
@@ -856,7 +976,7 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
   if (rootUnavailable !== null) {
     // Said whether or not anything is tracked: an unavailable mount must not
     // read as a verified empty directory.
-    gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: rootUnavailable });
+    gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: explained(rootUnavailable, rootCause, 'list') });
   }
 
   // Which paths to decide: what disk shows, and what the store, P and intent
@@ -895,7 +1015,7 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
   // Observe. Tracked facts are read again, synchronously, when deciding.
   for (const path of candidates) {
     if (rootUnavailable !== null) {
-      gathered.facts.set(path, { kind: 'unobserved', reason: rootUnavailable });
+      gathered.facts.set(path, { kind: 'unobserved', reason: rootUnavailable, ...rootCause });
       continue;
     }
     // What the mount passes over by design stays unobserved by a pass that
@@ -945,7 +1065,9 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
         if (r.kind === 'symlink' && r.path === path) continue;
         if (region === undefined || r.path.length > region.path.length) region = r;
       }
-      gathered.facts.set(path, { kind: 'unobserved', reason: region ? region.reason : 'not reached by the walk' });
+      gathered.facts.set(path, region
+        ? { kind: 'unobserved', reason: region.reason, ...(region.errno !== undefined ? { errno: region.errno } : {}) }
+        : { kind: 'unobserved', reason: 'not reached by the walk' });
       continue;
     }
     const p = agreement.get(mount.name, path);
@@ -962,11 +1084,12 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
     const after = await locateRoot(mount.view, mount.rootReal);
     if (!('identity' in after) || !sameRootIdentity(after.identity, gathered.rootIdentity)) {
       const reason = 'reason' in after ? after.reason : ROOT_REPLACED;
-      for (const path of gathered.facts.keys()) gathered.facts.set(path, { kind: 'unobserved', reason });
+      const errno = 'errno' in after ? after.errno : undefined;
+      for (const path of gathered.facts.keys()) gathered.facts.set(path, { kind: 'unobserved', reason, ...(errno !== undefined ? { errno } : {}) });
       gathered.rootIdentity = null;
       gathered.walk = null;
       gathered.dirs = [];
-      gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason });
+      gathered.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: explained(reason, errno !== undefined ? { errno } : {}, 'list') });
     }
   }
   return gathered;
@@ -1003,14 +1126,13 @@ export async function reconcilePass(
     }
   }
   if (gathered === null) {
-    result.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: 'the selected branch kept changing while the scan ran' });
+    result.undecided = 'the selected branch kept changing while the scan ran';
+    result.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : '', reason: explained(result.undecided, { again: true }, 'list') });
     return result;
   }
   if (opts.branchId !== undefined && gathered.branchId !== opts.branchId) {
-    result.incomplete.push({
-      path: scope.kind === 'dir' ? scope.dir : scope.paths.join(', '),
-      reason: 'the selected branch changed before this sync ran; nothing was taken from disk — sync again on this branch to take it',
-    });
+    result.undecided = 'the selected branch changed before this sync ran; nothing was taken from disk — sync again on this branch to take it';
+    result.incomplete.push({ path: scope.kind === 'dir' ? scope.dir : scope.paths.join(', '), reason: result.undecided });
     return result;
   }
   const { walk, facts } = gathered;
@@ -1135,6 +1257,7 @@ export async function reconcilePass(
       if (x.d.kind === 'file' || x.d.kind === 'absent') report.diskNow = x.d.kind;
     }
     if (x.verdict.note) report.note = x.verdict.note;
+    if (x.verdict.noteCause !== undefined) report.noteCause = x.verdict.noteCause;
     if (!(x.verdict.state === 'synced' && !entry)) result.reports.set(x.path, report);
   }
   if (walk) {
@@ -1164,7 +1287,9 @@ export async function reconcilePass(
       // holder), so naming the directory as unreached would never clear.
       const wholeScope = scope.kind === 'dir' && scope.dir !== '' && region.path === scope.dir;
       const unreached = hides && region.reason !== OTHER_MOUNT;
-      if (region.kind === 'error' || region.kind === 'cap' || unreached || wholeScope) result.incomplete.push({ path: region.path, reason: region.reason });
+      if (region.kind === 'error' || region.kind === 'cap' || unreached || wholeScope) {
+        result.incomplete.push({ path: region.path, reason: explained(region.reason, region.errno !== undefined ? { errno: region.errno } : {}, 'list') });
+      }
       // A name passed over by design that hides nothing tracked is reported nowhere else:
       // counted, so a sync that says 0 also says what it didn't look at
       // (agent-framework #276). A symlink region isn't counted: a link the
@@ -1271,7 +1396,8 @@ export async function pushPaths(
   // unmounted from. The push plans nothing, so it reports no branch.
   const root = await locateRoot(mount.view, mount.rootReal);
   if ('reason' in root) {
-    for (const path of paths) result.skipped.push({ path, reason: root.reason });
+    const why = explained(root.reason, root.errno !== undefined ? { errno: root.errno } : {}, 'write');
+    for (const path of paths) result.skipped.push({ path, reason: why });
     return result;
   }
   // Another mount's directory nested in this one is that mount's: no push
@@ -1344,7 +1470,7 @@ export async function pushPaths(
   // nothing is decided or recorded from them.
   const after = await locateRoot(mount.view, mount.rootReal);
   if (!('identity' in after) || !sameRootIdentity(after.identity, root.identity)) {
-    const reason = 'reason' in after ? after.reason : ROOT_REPLACED;
+    const reason = 'reason' in after ? explained(after.reason, after.errno !== undefined ? { errno: after.errno } : {}, 'write') : ROOT_REPLACED;
     for (const path of paths) result.skipped.push({ path, reason });
     return result;
   }
@@ -1365,9 +1491,6 @@ export async function pushPaths(
     const p = agreement.get(mount.name, path);
     const bi = mount.intents.get(path);
     const v = decide(d, s, p, bi, branchId, false);
-    // The ways out a refusal names, as materialize takes them: a deletion
-    // reaches disk only with applyDeletions.
-    const again = s ? 'materialize again' : 'materialize again with applyDeletions';
     // Where disk has deleted a file the workspace holds, a sync takes the
     // deletion, which removes the workspace's copy, and a forced push writes
     // the workspace's copy back: there is no disk copy to adopt or overwrite.
@@ -1483,8 +1606,7 @@ export async function pushPaths(
             ? d.kind === 'absent' || d.kind === 'file'
               ? `${v.note} — ${sync}`
               : `${v.note}, and disk's copy can't be verified (${d.kind === 'unobserved' ? d.reason : 'not hashed'}) — once it can be, ${sync}`
-            : inTheWay(v.note, !s) ??
-              `cannot verify disk copy (${v.note ?? 'not observed'}) — fix it and ${again}${forcedWay(v.note, !s, forced)}`,
+            : inTheWay(v.note, !s) ?? unverifiedCopy(v, s ? 'write' : 'unlink', forced),
         });
         continue;
       }
@@ -1549,7 +1671,7 @@ export async function pushPaths(
         // A deletion no push makes, forced or not (inTheWay), is refused for
         // that, as an unforced push refuses it, rather than left for
         // applyDeletions, which couldn't make it either.
-        const lasting = inTheWay(v.note, true);
+        const lasting = inTheWay(v.note, true) ?? (v.noteCause?.ownStep === true ? v.note ?? null : null);
         if (lasting !== null) result.skipped.push({ path, reason: lasting });
         else result.pendingDeletions.push(path);
         continue;
@@ -1679,18 +1801,18 @@ export async function pushPaths(
         effected.push({ step, dirs: [await unlinkContained(mount.view, mount.rootReal, step.path, step.expect)] });
       }
     } catch (err) {
-      const failure = err instanceof EffectFailed ? err : new EffectFailed(err instanceof Error ? err.message : String(err), true);
+      const failure = err instanceof EffectFailed ? err : callFailed('the push failed', err, true, 'colon');
       if (!failure.touched) {
         // Disk at this path is as planning saw it: its evidence goes back to
         // exactly what it was, whatever kind that was.
         agreement.restore(mount.name, step.path, step.before);
         recorded = true;
-        const why = inTheWay(failure.message, step.kind === 'unlink') ?? failure.message;
+        const why = step.kind === 'chmod' ? withWayOn(failure.message, failure.detail, 'write') : explained(failure.message, failure.detail, step.kind);
         result.skipped.push({ path: step.path, reason: `not ${step.kind === 'unlink' ? 'unlinked' : step.kind === 'chmod' ? 'given the workspace\'s mode' : 'written'}: ${why}` });
       } else {
         // No completion: the intent stays pending, and the next observation
         // resolves it from whatever disk then holds.
-        result.skipped.push({ path: step.path, reason: `${failure.message}; the outcome is checked at the next observation` });
+        result.skipped.push({ path: step.path, reason: `${failure.message} — ${UNSETTLED}` });
       }
     }
   }
@@ -1710,7 +1832,7 @@ export async function pushPaths(
       result.skipped.push({
         path: step.path,
         reason: `could not make the ${step.kind === 'write' ? 'write' : 'unlink'} durable (directory fsync of ${failed === '' ? 'the mount root' : failed}): ` +
-          `${unsynced.get(failed)}; the outcome is checked at the next observation`,
+          `${unsynced.get(failed)} — ${UNSETTLED}`,
       });
       continue;
     }
@@ -1784,5 +1906,6 @@ export async function pushPaths(
 }
 
 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})`;
+  return `${'missing' in stored ? 'the workspace copy is missing from the store' : `the workspace copy is unreadable in the store (${stored.unreadable})`}`
+    + " — a read of this path takes disk's copy where it can, and otherwise says what can be done";
 }

package/src/notice-tags.ts

@@ -0,0 +1,86 @@
+/**
+ * Build every fixed bracket opening the framework writes into an agent's
+ * context outside a tool result (a notice, a heartbeat or reminder text, a
+ * placeholder in a message's content) from a tag here, as `[tag]`,
+ * `[tag: …]` or `[tag …]`: text the framework didn't write is marked
+ * wherever it would open with one of these (supplied-text.ts). A toolset's
+ * `[server/toolset:instance]` label is built from its server's id and names
+ * instead.
+ */
+export const NOTICE_TAG = {
+  turnInterrupted: 'turn-interrupted',
+  closedChannel: 'closed channel',
+  tunedOut: 'tuned out',
+  refusalRewind: 'refusal-rewind',
+  drafts: 'drafts',
+  delivered: 'delivered',
+  routing: 'routing',
+  channels: 'channels',
+  continue: 'continue',
+  proseRouting: 'prose-routing',
+  toolBoundary: 'tool-boundary',
+  gate: 'Gate',
+  selfWake: 'self-wake',
+  discordSendFailed: 'discord-send-failed',
+  sendUndeliverable: 'send-undeliverable',
+  inferenceFailed: 'inference-failed',
+  speechNotPosted: 'speech-not-posted',
+  reasoning: 'reasoning',
+  workspace: 'workspace',
+  workspaceEvent: 'workspace event',
+  conflictsWithDisk: 'conflicts with disk',
+  tuneOut: 'Tune-out',
+  tuneOutWake: 'Tune-out wake',
+  tuneOutCadence: 'Tune-out cadence',
+  tuneOutCancelled: 'Tune-out cancelled',
+  focus: 'Focus',
+  agentLifecycle: 'Agent lifecycle',
+  standingDispositions: 'Standing dispositions',
+  channelInvitation: 'Channel invitation',
+  system: 'system',
+  toolsets: 'toolsets',
+  heartbeat: 'heartbeat',
+  silentHeartbeat: 'silent heartbeat',
+  heartbeatTick: 'heartbeat tick',
+  heartbeatContinue: 'Continue',
+  currentTime: 'current time',
+  reminder: 'reminder',
+  attachment: 'Attachment',
+  emptyMessage: 'Empty message',
+  imageNotShown: 'Image not shown',
+  audioNotShown: 'Audio not shown',
+  contentNotShown: 'Content not shown',
+  resourceNotShown: 'Resource not shown',
+  referenceNotShown: 'Reference not shown',
+  textNotShown: 'Text not shown',
+  reference: 'reference',
+  referenceId: 'ref',
+  resourceLink: 'resource link',
+  withheld: 'withheld',
+  unserializableConnectorValue: 'unserializable connector value',
+  unprintableValue: 'a value that cannot be printed',
+  undescribedFailure: 'failure could not be described',
+  script: 'script',
+  truncated: 'truncated',
+  cutToFit: 'cut to fit',
+  blockNotShown: 'block not shown',
+} as const;
+
+/**
+ * The bracket openings context-manager 0.23.0 and 0.23.1 write into an
+ * agent's context outside a tool result or read back from it, marked as the
+ * framework's own are. Check them against each context-manager release the
+ * framework takes.
+ */
+export const CONTEXT_MANAGER_TAGS = [
+  'content omitted', 'image not shown', 'Operator note', 'Recall', 'tool call omitted', 'tool result moved', 'Topic Transition',
+] as const;
+
+/**
+ * The bracket openings membrane 0.8.0 writes into an agent's request outside
+ * a tool result, marked as the framework's own are. Check them against each
+ * membrane release the framework takes.
+ */
+export const MEMBRANE_TAGS = [
+  'Audio', 'continuing', 'Document', 'duplicate tool_result for', 'Image', 'orphan tool_result for', 'Start', 'Tool Result', 'Video',
+] as const;

package/src/reasoning-loss-notice.ts

@@ -1,3 +1,5 @@
+import { NOTICE_TAG } from './notice-tags.js';
+import { oneLine, suppliedValue } from './supplied-text.js';
 import { safeSlice } from './safe-slice.js';
 
 export type ReasoningLossCause = 'tools' | 'system' | 'model';
@@ -45,12 +47,12 @@ export function reasoningLossNotice(input: ReasoningLossNoticeInput): string {
     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}`;
+  return `[${NOTICE_TAG.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 ('toolCall' in anchor) return anchor.toolCall ? `that called \`${suppliedValue(anchor.toolCall)}\`` : undefined;
+  const text = oneLine(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}"`;

package/src/silent-heartbeat.ts

@@ -50,6 +50,7 @@
  * another reply's row and rewrite cached history. Exact matching for every
  * row would need the compile result to expose each message's source rows.
  */
+import { NOTICE_TAG } from './notice-tags.js';
 import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
 
 /** Request-only separator a silent tick's request ends on. It carries the
@@ -59,15 +60,15 @@ import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
  * text their request rendered (`SilentHeartbeatStamp.separator`), so changing
  * this constant changes only ticks that open afterwards. */
 export const SILENT_HEARTBEAT_SEPARATOR =
-  '[silent heartbeat] Scheduled private self-check. Review pending matters privately. ' +
+  `[${NOTICE_TAG.silentHeartbeat}] Scheduled private self-check. Review pending matters privately. ` +
   'Do not narrate or publish plain prose; use an explicit send tool only if you deliberately choose to contact someone.';
 
 /** The separator ticks rendered before their rows recorded its text: rows
  * stamped without `separator` still render it, byte for byte. */
-const LEGACY_SILENT_HEARTBEAT_SEPARATOR = '[heartbeat tick]';
+const LEGACY_SILENT_HEARTBEAT_SEPARATOR = `[${NOTICE_TAG.heartbeatTick}]`;
 
 /** Request-only turn a compile that ends on the agent's own message gets. */
-export const CONTINUE_ROW = '[Continue]';
+export const CONTINUE_ROW = `[${NOTICE_TAG.heartbeatContinue}]`;
 
 /** Identity of one authenticated silent heartbeat tick. */
 export interface SilentHeartbeatTick {
@@ -189,14 +190,17 @@ export interface RequestOnlyRowIndex {
 /** Index the agent's own rows that follow request-only turns: the rows of its
  * silent ticks, and the rows of each reply to a `[Continue]`. The two are
  * independent, so a row can be both. Only stamped rows are keyed, so an
- * agent's history walk costs a metadata read per row. */
-export function indexRequestOnlyRows(stored: readonly StoredRowLike[], agentName: string): RequestOnlyRowIndex {
+ * agent's history walk costs a metadata read per row. `own` is the agent's
+ * name, or every participant that is its own voice, as a derived agent's
+ * inherited rows are. */
+export function indexRequestOnlyRows(stored: readonly StoredRowLike[], own: string | ReadonlySet<string>): RequestOnlyRowIndex {
+  const ownNames = typeof own === 'string' ? new Set([own]) : own;
   const ticks = new Map<string, { tick: string; text: string }>();
   const prompts = new Map<string, RequestOnlyPrompt>();
   for (const row of stored) {
-    if (row.participant !== agentName) continue;
+    if (!ownNames.has(row.participant)) continue;
     const stamp = silentHeartbeatOf(row.metadata);
-    const ownTick = stamp !== undefined && stamp.agentName === agentName;
+    const ownTick = stamp !== undefined && stamp.agentName === row.participant;
     const prompt = promptedByOf(row.metadata);
     if (!ownTick && !prompt) continue;
     const keys = identityKeys(row.content);

package/src/stored-injections.ts

@@ -84,6 +84,13 @@ export function isAnotherAgentsInjection(metadata: unknown, agentName: string):
   return mark !== undefined && mark.agent !== agentName;
 }
 
+/** Whether a row is `agentName`'s own stored injection: its context, which
+ *  its view keeps however the rest is read, as a shared fork's does, whose
+ *  view is otherwise its source's (AgentFramework's deriveSharedContext). */
+export function isOwnInjection(metadata: unknown, agentName: string): boolean {
+  return storedInjectionMarkOf(metadata)?.agent === agentName;
+}
+
 /**
  * Whether an injection is stored, rather than placed by `compile()` each
  * time: an `afterUser` one, unless it opts out