@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/modules/history/semantic.ts

@@ -26,6 +26,7 @@
 
 import type { ContextManager, StoredMessage } from '@animalabs/context-manager';
 import type { ContentBlock } from '@animalabs/membrane';
+import { safeSlice } from '../../safe-slice.js';
 
 export interface SemanticIndexConfig {
   /** Base URL of the embed-service, e.g. `http://100.90.161.34:8804`. */
@@ -104,6 +105,35 @@ export interface SearchResponse {
 
 const PRIVATE_PROSE_TOOLS = new Set(['think', 'journal', 'skip_reply', 'private_note']);
 
+/**
+ * The semantic index service's failure, said of the service alone: it didn't
+ * answer in time, couldn't be reached, cut its answer off, answered without
+ * what its request's caller reads, or answered with an HTTP error. `status` is
+ * the answer's HTTP status, and null where no whole answer came. Each caller
+ * says what that meant for its own work, a search or the background sync.
+ */
+export class EmbedServiceError extends Error {
+  constructor(message: string, readonly status: number | null) {
+    super(message);
+    this.name = 'EmbedServiceError';
+  }
+}
+
+/**
+ * What stopped a request reaching the service: fetch's cause, such as a
+ * refused connection. When several addresses were tried, as for a name like
+ * localhost with both an IPv6 and an IPv4 address, the cause is an
+ * AggregateError with no message of its own, and each address's error says it.
+ */
+function unreachedReason(e: unknown): string {
+  const cause = (e as { cause?: unknown } | null)?.cause;
+  if (cause instanceof AggregateError && !cause.message) {
+    const each = cause.errors.map((err) => (err instanceof Error ? err.message : String(err))).filter(Boolean);
+    if (each.length > 0) return each.join('; ');
+  }
+  return (cause instanceof Error && cause.message) || (e instanceof Error ? e.message : String(e));
+}
+
 export class SemanticIndexClient {
   private readonly base: string;
   private readonly ns: string;
@@ -114,21 +144,69 @@ export class SemanticIndexClient {
     this.timeoutMs = cfg.requestTimeoutMs ?? 30_000;
   }
 
-  private async call<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T> {
+  /**
+   * A request's answer, as JSON. `expect` is what the caller reads of it: an
+   * answer without that, such as a web page at a wrong address, fails as
+   * one, with its status, since the service did answer.
+   */
+  private async call<T>(
+    method: 'GET' | 'POST', path: string, body?: unknown, expect?: { what: string; is: (json: unknown) => boolean },
+  ): Promise<T> {
     const headers: Record<string, string> = { 'content-type': 'application/json' };
     if (this.cfg.token) headers.authorization = `Bearer ${this.cfg.token}`;
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    // The request's kind, for a message: search, upsert, delete or stats.
+    const request = path.slice(path.lastIndexOf('/') + 1);
+    // The timeout as the client used it: whole seconds, or else milliseconds.
+    const within = this.timeoutMs % 1000 === 0 ? `${this.timeoutMs / 1000} s` : `${this.timeoutMs} ms`;
     try {
-      const res = await fetch(`${this.base}${path}`, {
-        method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: ctrl.signal,
-      });
-      const text = await res.text();
+      let res: Response;
+      let text: string;
+      let answered = false;
+      try {
+        res = await fetch(`${this.base}${path}`, {
+          method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: ctrl.signal,
+        });
+        answered = true;
+        // An answer cut off after its status, or not finished within the
+        // timeout, counts as no answer. That's rare, and a stats or delete
+        // request that misses its 404 this way is made again on a later pass
+        // of the sync.
+        text = await res.text();
+      } catch (e) {
+        throw new EmbedServiceError(
+          answered
+            ? ctrl.signal.aborted
+              ? `the semantic index service's answer to the ${request} request didn't finish within ${within}`
+              : `the semantic index service's answer to the ${request} request was cut off (${unreachedReason(e)})`
+            : ctrl.signal.aborted
+              ? `the semantic index service didn't answer the ${request} request within ${within}`
+              : `the semantic index service couldn't be reached for the ${request} request (${unreachedReason(e)})`,
+          null,
+        );
+      }
       let json: unknown;
       try { json = JSON.parse(text); } catch { json = undefined; }
       if (!res.ok) {
-        const msg = (json as { error?: { message?: string } } | undefined)?.error?.message ?? text.slice(0, 200);
-        throw new Error(`embed-service ${method} ${path} → ${res.status}: ${msg}`);
+        // The service's message, or any other body, is quoted to at most its
+        // first 200 UTF-16 units, one fewer rather than end on half of a
+        // surrogate pair, and a quote that's cut ends in "…". A message that
+        // isn't text quotes the body instead.
+        const given = (json as { error?: { message?: unknown } } | undefined)?.error?.message;
+        const quoted = typeof given === 'string' ? given : text;
+        const cut = safeSlice(quoted, 0, 200);
+        const msg = cut.length < quoted.length ? `${cut}…` : cut;
+        throw new EmbedServiceError(
+          `the semantic index service answered the ${request} request with an error (HTTP ${res.status}${msg ? `: ${msg}` : ''})`,
+          res.status,
+        );
+      }
+      if (expect && !expect.is(json)) {
+        throw new EmbedServiceError(
+          `the semantic index service answered the ${request} request without ${expect.what} (HTTP ${res.status})`,
+          res.status,
+        );
       }
       return json as T;
     } finally {
@@ -139,15 +217,17 @@ export class SemanticIndexClient {
   /** Stats for this namespace; `null` when the namespace does not exist yet. */
   async stats(): Promise<IndexStats | null> {
     try {
-      return await this.call<IndexStats>('GET', `/v1/index/${this.ns}/stats`);
+      return await this.call<IndexStats>('GET', `/v1/index/${this.ns}/stats`, undefined, {
+        what: 'stats by kind', is: (json) => isObject((json as { by_kind?: unknown } | undefined)?.by_kind),
+      });
     } catch (e) {
-      if (e instanceof Error && /→ 404/.test(e.message)) return null;
+      if (e instanceof EmbedServiceError && e.status === 404) return null;
       throw e;
     }
   }
 
   async upsert(items: IndexItem[]): Promise<{ inserted: number; updated: number; unchanged: number; count: number }> {
-    return this.call('POST', `/v1/index/${this.ns}/upsert`, { items });
+    return this.call('POST', `/v1/index/${this.ns}/upsert`, { items }, { what: 'a JSON object', is: isObject });
   }
 
   async delete(ids: string[]): Promise<{ deleted: number }> {
@@ -155,10 +235,29 @@ export class SemanticIndexClient {
   }
 
   async search(req: SearchRequest): Promise<SearchResponse> {
-    return this.call<SearchResponse>('POST', `/v1/index/${this.ns}/search`, req);
+    return this.call('POST', `/v1/index/${this.ns}/search`, req, {
+      what: 'a list of hits, each with an id', is: (json) => {
+        const hits = (json as { hits?: unknown } | undefined)?.hits;
+        return Array.isArray(hits) && hits.every(isHit);
+      },
+    });
   }
 }
 
+/** A JSON object: not null, and not a list. */
+function isObject(json: unknown): boolean {
+  return typeof json === 'object' && json !== null && !Array.isArray(json);
+}
+
+/**
+ * A hit as semantic_search needs one: an object with a string id, which it
+ * reads of every hit. Its ts and meta are read only for the hits it returns,
+ * and as far as they can be read.
+ */
+function isHit(hit: unknown): boolean {
+  return isObject(hit) && typeof (hit as { id?: unknown }).id === 'string';
+}
+
 /** Text to embed for one message, or '' when there is nothing worth indexing. */
 export function messageIndexText(msg: StoredMessage, includePrivateTools = true): string {
   const parts: string[] = [];
@@ -194,7 +293,7 @@ export function messageToItem(msg: StoredMessage, cfg: { includePrivateTools?: b
   const tsMs = msg.timestamp.getTime();
   return {
     id: `msg:${String(msg.id)}`,
-    text: text.slice(0, cfg.maxChars ?? 32_000),
+    text: safeSlice(text, 0, cfg.maxChars ?? 32_000),
     ts: tsMs / 1000,
     channel: channelOf(msg),
     kind: 'message',
@@ -221,7 +320,7 @@ export function summaryToItem(s: SummaryLike, cfg: { maxChars?: number }): Index
   if (!text) return null;
   return {
     id: `sum:${s.id}`,
-    text: text.slice(0, cfg.maxChars ?? 32_000),
+    text: safeSlice(text, 0, cfg.maxChars ?? 32_000),
     ts: s.startMs / 1000,
     kind: 'summary',
     level: s.level,
@@ -258,6 +357,11 @@ export class SemanticIndexer {
     private readonly log: (msg: string) => void = () => {},
   ) {}
 
+  /** A line for the host's log, naming this indexer's index first, since a host can keep several. */
+  warn(line: string): void {
+    this.log(`[history/semantic] index ${JSON.stringify(this.cfg.namespace)}: ${line}`);
+  }
+
   /**
    * Edits and removals since the last successful sync. The time-cursor walk
    * only revisits the overlap window, so an edit to an older message (its
@@ -271,7 +375,16 @@ export class SemanticIndexer {
   private readonly editedIds = new Set<string>();
   private readonly removedIds = new Set<string>();
   private detach: (() => void) | null = null;
-  /** Set once the service answers 404 to /delete (a build without the route): removals are dropped from then on. */
+  /**
+   * Set once the service answers 404 to /delete in a pass whose /stats
+   * answered with stats, which shows the index is made, so the 404 means a
+   * build without the route. From then on, removals are dropped as they come
+   * and no pass calls /delete, until the host restarts or binds the module
+   * again, which makes a new indexer. A pass whose /stats answers 404 has no
+   * index to remove from and makes no /delete call; a /delete 404 in a pass
+   * whose /stats answered with something that isn't stats is re-queued like
+   * any other failure, since that answer doesn't show the index is made.
+   */
   private deleteUnsupported = false;
   /** Called whenever the pending edit/remove sets change. */
   onPendingChange: ((p: PendingChanges) => void) | null = null;
@@ -290,7 +403,7 @@ export class SemanticIndexer {
     if (this.detach) return;
     const on = (this.cm as { onMessage?: ContextManager['onMessage'] }).onMessage;
     if (typeof on !== 'function') {
-      this.log('[history/semantic] context-manager has no onMessage: edits and removals will not reach the index');
+      this.warn("the context-manager has no onMessage, so edits and removals won't reach the index");
       return;
     }
     this.detach = on.call(this.cm, (e) => {
@@ -323,8 +436,27 @@ export class SemanticIndexer {
     const report: SyncReport = { pushed: 0, inserted: 0, updated: 0, unchanged: 0, more: false, messagesScanned: 0, summariesScanned: 0 };
     if (this.backingOff) { report.more = true; return report; }
     const batchSize = Math.min(256, Math.max(1, this.cfg.syncBatch ?? 128));
+    // Failures of the edits and removals phase, which don't end the pass, and a
+    // stats answer that isn't stats: lastError names each, ended or not.
+    const phaseErrors: string[] = [];
+    let notStats: EmbedServiceError | null = null;
     try {
-      const stats = await this.client.stats();
+      // A 2xx that isn't stats, such as a web page from a wrong route, gives no
+      // watermark: the pass walks from the start, as for a namespace that
+      // doesn't exist yet, and lastError names the answer. Every pass then
+      // starts over, and a history longer than a pass's budget is never
+      // walked to its end, so a pass whose budget runs out fails on that
+      // answer.
+      let stats: IndexStats | null = null;
+      try {
+        stats = await this.client.stats();
+      } catch (e) {
+        if (!(e instanceof EmbedServiceError && e.status !== null && e.status >= 200 && e.status < 300)) throw e;
+        notStats = e;
+      }
+      // /stats answered 404, which stats() reads as a namespace that doesn't
+      // exist: there's no index to remove from.
+      const noIndex = stats === null && notStats === null;
       const msgWm = stats?.by_kind.message?.max_cursor ?? null;
       const sumWm = stats?.by_kind.summary?.max_cursor ?? null;
       let budget = maxItems;
@@ -340,14 +472,14 @@ export class SemanticIndexer {
       // This phase fails on its own: a failure re-queues its ids, is logged
       // and reported via lastError, and the tick falls through to summaries
       // and the time walk, so one bad delete/upsert cannot freeze indexing.
-      let phaseError: string | null = null;
       if (this.removedIds.size > 0 || this.editedIds.size > 0) {
         const removed = [...this.removedIds];
         // Edits spend the budget like any other upsert, so a large queue left
         // by an outage cannot make a search's bounded catch-up unbounded; the
         // rest stay queued for the next pass.
-        // Only actionable edits (an upsert or a delete) spend it: one whose
-        // message left the branch is dropped for free.
+        // An edit whose message is on the branch spends it, one edited down to
+        // nothing indexable too, even in a pass that makes no /delete call; one
+        // whose message left the branch is dropped for free.
         this.removedIds.clear();
         const edited: string[] = [];
         const toDelete = removed.map((id) => `msg:${id}`);
@@ -367,22 +499,40 @@ export class SemanticIndexer {
           if (item) toUpsert.push(item); else { toDelete.push(`msg:${id}`); blanked.push(id); }
         }
         if (this.editedIds.size > 0) report.more = true;
-        if (toDelete.length > 0) {
+        // The removals and blanked edits are dropped with no /delete call in
+        // two cases. With no index (/stats answered 404), there's nothing to
+        // remove, and the index this pass makes takes only what the store
+        // holds and can index, which leaves them out. Once the service is known
+        // to lack the route (deleteUnsupported), the index keeps them, and
+        // search-time checks (on-branch, still indexable) keep them out of
+        // results.
+        if (toDelete.length > 0 && !noIndex && !this.deleteUnsupported) {
           try {
             await this.client.delete(toDelete);
           } catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
-            if (/→ 404/.test(msg)) {
-              // A service build without /delete (or a namespace that does
-              // not exist). Drop the removals and blanked edits: search-time
-              // checks (on-branch, still indexable) keep them out of results.
+            // What the delete held, by kind, for the warning.
+            const what = [
+              removed.length > 0 ? `${removed.length} removal(s)` : null,
+              blanked.length > 0 ? `${blanked.length} edit(s) down to nothing indexable` : null,
+            ].filter((s): s is string => s !== null).join(' and ');
+            if (e instanceof EmbedServiceError && e.status === 404 && stats !== null) {
+              // This pass's /stats answered with stats, so the index is made
+              // and the 404 is the route's: a service build without /delete.
               this.deleteUnsupported = true;
-              this.log(`[history/semantic] /delete unsupported by the embed-service; dropping ${toDelete.length} removal(s): ${msg}`);
+              this.warn(
+                `/delete answered 404, so the service lacks that route; dropping ${what}. Later removals and edits `
+                  + `down to nothing indexable are dropped too, until the host restarts or binds the history module `
+                  + `again: ${msg}`,
+              );
             } else {
+              // Any other failure, and a 404 in a pass whose /stats answered
+              // with something that isn't stats, which doesn't show the index
+              // is made: re-queued, for a later pass.
               for (const id of removed) this.removedIds.add(id);
               for (const id of blanked) if (!this.removedIds.has(id)) this.editedIds.add(id);
-              phaseError = msg;
-              this.log(`[history/semantic] delete failed, ${removed.length} removal(s) re-queued: ${msg}`);
+              phaseErrors.push(msg);
+              this.warn(`delete failed, ${what} re-queued: ${msg}`);
             }
           }
         }
@@ -395,8 +545,8 @@ export class SemanticIndexer {
         } catch (e) {
           const msg = e instanceof Error ? e.message : String(e);
           for (const id of edited) if (!this.removedIds.has(id)) this.editedIds.add(id);
-          phaseError = msg;
-          this.log(`[history/semantic] edit re-upsert failed, ${edited.length} edit(s) re-queued: ${msg}`);
+          phaseErrors.push(msg);
+          this.warn(`edit re-upsert failed, ${edited.length} edit(s) re-queued: ${msg}`);
         }
         this.pendingChanged();
       }
@@ -458,16 +608,23 @@ export class SemanticIndexer {
         fromMs = lastMs;
       }
       await flush();
-      this.consecutiveFailures = 0; this.lastError = phaseError; this.lastSyncAt = Date.now();
+      if (notStats && report.more) throw notStats;
+      this.consecutiveFailures = 0; this.lastError = named(notStats?.message ?? null, ...phaseErrors); this.lastSyncAt = Date.now();
       return report;
     } catch (e) {
       this.consecutiveFailures++;
       const delay = Math.min(15 * 60_000, 5_000 * 2 ** Math.min(8, this.consecutiveFailures - 1));
       this.backoffUntil = Date.now() + delay;
-      this.lastError = e instanceof Error ? e.message : String(e);
-      this.log(`[history/semantic] sync failed (${this.consecutiveFailures}×, retry in ${Math.round(delay / 1000)}s): ${this.lastError}`);
+      const failure = e instanceof Error ? e.message : String(e);
+      this.lastError = named(failure, notStats?.message ?? null, ...phaseErrors);
+      this.warn(`sync failed (${this.consecutiveFailures}×, retry in ${Math.round(delay / 1000)}s): ${failure}`);
       report.more = true;
       return report;
     }
   }
 }
+
+/** Each failure a sync pass met, once, in the order given, for its lastError: null if none. */
+function named(...failures: (string | null)[]): string | null {
+  return [...new Set(failures.filter((f): f is string => f !== null))].join('; ') || null;
+}

package/src/modules/unknown-tool.ts

@@ -0,0 +1,16 @@
+import type { ToolDefinition } from '../types/events.js';
+
+/**
+ * What a module answers for a tool name it doesn't route: there's no such
+ * tool, so nothing ran, and which tools the module has, read from its own
+ * getTools() so the list can't drift. The registry hands every `module--name`
+ * to its module, even one the module doesn't declare, since some modules route
+ * undeclared names on purpose, so this answer is the module's to give.
+ */
+export function unknownToolMessage(module: string, name: string, tools: readonly Pick<ToolDefinition, 'name'>[]): string {
+  const missing = `There's no tool "${module}--${name}", so nothing ran.`;
+  const names = tools.map((tool) => `${module}--${tool.name}`);
+  if (names.length === 0) return `${missing} The ${module} module has no tools of its own: every tool you can call is in your tool list.`;
+  if (names.length === 1) return `${missing} The ${module} module's one tool is ${names[0]}.`;
+  return `${missing} The ${module} module's tools are ${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}.`;
+}

package/src/modules/workspace/disk-agreement.ts

@@ -15,7 +15,9 @@
  * that isn't that directory any more (an unmounted drive whose mountpoint is
  * now empty, a replaced directory) is an unavailable mount, never a disk on
  * which every file was deleted; only an explicit acceptance takes it, and
- * that starts its evidence afresh.
+ * that starts its evidence afresh. A place, where a walk stopped (`walks`),
+ * binds no root: it only says where the next walk starts, in whatever
+ * directory the root is by then.
  *
  * Every transition is write-ahead (see reconcile.ts): an `intent` entry
  * (`pending`, with the prior value and the expected one) is durable before the
@@ -46,9 +48,15 @@ export interface Fingerprint {
   hashedAt: number;
 }
 
+/**
+ * `mode`: the permission bits disk held (`st_mode & 0o777`). Evidence from
+ * before modes were recorded, or recorded after the kernel refused a
+ * widening of the workspace's own change, has none: a sync takes disk's mode
+ * in.
+ */
 export type Agreed =
   | { kind: 'absent' }
-  | { kind: 'content'; hash: string; size: number; fp?: Fingerprint };
+  | { kind: 'content'; hash: string; size: number; fp?: Fingerprint; mode?: number };
 
 export type Candidate = { kind: 'absent' } | { kind: 'content'; hash: string };
 
@@ -61,6 +69,21 @@ export interface Pending {
   expect: Candidate;
   /** Branch the intent was recorded on (an adoption's meaning is branch-relative). */
   branchId: string;
+  /**
+   * For a write whose plan gives the file a mode: the mode it saw (`from`)
+   * and the one it gives (`to`); a write that creates the file records `to`
+   * for both. A push that goes on as our own narrowing push, stopped before
+   * its bytes, records that push's `from`, the old bytes' own mode, and the
+   * store's mode now, or where the store records none, the mode the stopped
+   * push narrowed to, whether or not it gives a mode itself. It narrows to
+   * `from & to` before the bytes and widens to `to` after them, so a stop
+   * leaves disk at one of those three, with the old bytes or the new, and
+   * those are the push's own. A file that has setuid or setgid
+   * when the write checks it loses them before the bytes too, a chmod that
+   * keeps the permission bits it has then, so a stop after that chmod alone
+   * leaves disk at the mode the write saw, less those bits.
+   */
+  modes?: { from: number; to: number };
 }
 
 export interface Interrupted {
@@ -92,16 +115,30 @@ type JournalEntry =
   /** The root's identity; with `reset`, an accepted new root, whose evidence starts empty. */
   | { t: 'root'; mount: string; identity: RootIdentity; reset?: true }
   | { t: 'set'; mount: string; path: string; value: Physical }
-  | { t: 'forget'; mount: string; path: string };
+  | { t: 'forget'; mount: string; path: string }
+  /**
+   * Where a capped walk of `scope` stopped (the last entry it took), or null
+   * once a walk covered the scope. It carries no `path` field: agent-framework
+   * 0.22 replays an entry it doesn't know as a `forget` of `entry.path`, and
+   * so leaves the evidence alone when there is none.
+   */
+  | { t: 'walk'; mount: string; scope: string; after: string | null };
 
 interface MountEvidence {
   root: string;
   identity?: RootIdentity;
   paths: Map<string, Physical>;
+  /** By scope ('' for the mount root): where the next walk of it resumes. */
+  walks: Map<string, string>;
 }
 
 interface Snapshot {
-  mounts: Record<string, { root: string; identity?: RootIdentity; paths: Record<string, Physical> }>;
+  mounts: Record<string, {
+    root: string;
+    identity?: RootIdentity;
+    paths: Record<string, Physical>;
+    walks?: Record<string, string>;
+  }>;
 }
 
 export const DISK_AGREEMENT_RECORD_TYPE = 'workspace/disk-agreement';
@@ -117,21 +154,40 @@ export function sameCandidate(a: Candidate, b: Candidate): boolean {
   return a.kind === b.kind && (a.kind === 'absent' || a.hash === (b as { hash: string }).hash);
 }
 
+/** A record with no mode claimed: a content record's, and a pending intent's own modes and its prior's. */
+function withoutModes(value: Physical): Physical {
+  if (value.kind === 'content' && value.mode !== undefined) {
+    const { mode: _mode, ...rest } = value;
+    return rest;
+  }
+  if (value.kind === 'pending') {
+    const { modes: _modes, ...intent } = value;
+    if (intent.prior?.kind !== 'content' || intent.prior.mode === undefined) return intent;
+    const { mode: _mode, ...prior } = intent.prior;
+    return { ...intent, prior };
+  }
+  return value;
+}
+
 export class DiskAgreement {
   private readonly store: JsStore;
   private readonly journal: RecordJournal<JournalEntry, Snapshot>;
   private readonly mounts = new Map<string, MountEvidence>();
   private configured: Array<{ name: string; root: string }> = [];
   /**
-   * An append (or a rebuild) not yet made durable. Cleared only by a
-   * barrier that succeeds, so a failed barrier stays owed: a later pass with
-   * nothing new to record still settles it before deciding anything.
+   * An append of evidence (or a rebuild) not yet made durable. Cleared only
+   * by a barrier that succeeds, so a failed barrier stays owed: a later pass
+   * with nothing new to record still settles it before deciding anything. A
+   * place owes none (recordWalk).
    */
   private unsynced = false;
+  /** Whether this host observes file modes (not on Windows): where it doesn't, no record it writes claims one. */
+  private readonly modesObserved: () => boolean;
 
-  constructor(store: JsStore) {
+  constructor(store: JsStore, opts: { modesObserved?: () => boolean } = {}) {
     this.store = store;
     this.journal = new RecordJournal<JournalEntry, Snapshot>(store, { type: DISK_AGREEMENT_RECORD_TYPE });
+    this.modesObserved = opts.modesObserved ?? (() => true);
   }
 
   /**
@@ -183,19 +239,19 @@ export class DiskAgreement {
         root: mount.root,
         ...(mount.identity ? { identity: mount.identity } : {}),
         paths: new Map(Object.entries(mount.paths)),
+        walks: new Map(Object.entries(mount.walks ?? {})),
       });
     }
     for (const { entry } of entries) {
       if (entry.t === 'mount') {
         const existing = replayed.get(entry.mount);
-        if (!existing || !sameRootPath(existing.root, entry.root)) replayed.set(entry.mount, { root: entry.root, paths: new Map() });
+        if (!existing || !sameRootPath(existing.root, entry.root)) {
+          replayed.set(entry.mount, { root: entry.root, paths: new Map(), walks: new Map() });
+        }
         continue;
       }
       const mount = replayed.get(entry.mount);
-      if (!mount) continue;
-      if (entry.t === 'root') applyRoot(mount, entry);
-      else if (entry.t === 'set') mount.paths.set(entry.path, entry.value);
-      else mount.paths.delete(entry.path);
+      if (mount) apply(mount, entry);
     }
     this.mounts.clear();
     for (const { name, root } of this.configured) {
@@ -203,7 +259,7 @@ export class DiskAgreement {
       if (found && sameRootPath(found.root, root)) {
         this.mounts.set(name, found);
       } else {
-        this.mounts.set(name, { root, paths: new Map() });
+        this.mounts.set(name, { root, paths: new Map(), walks: new Map() });
         this.journal.append({ t: 'mount', mount: name, root });
       }
     }
@@ -250,6 +306,29 @@ export class DiskAgreement {
     return out;
   }
 
+  /**
+   * Where the next walk of `scope` ('' for the mount root) resumes: the last
+   * entry a walk of it took before its cap stopped it, if one did.
+   */
+  walkResumesAfter(mount: string, scope: string): string | undefined {
+    this.ensureReconciled();
+    return this.mounts.get(mount)?.walks.get(scope);
+  }
+
+  /**
+   * Record where a walk of `scope` stopped (`after`), or that one covered it
+   * (null). Kept with the evidence so a restart resumes there too. A place
+   * that's lost costs coverage, never a decision: an append that didn't land
+   * loses one, and a checkpoint written by a version that doesn't keep them
+   * (0.22) loses them all, and each scope's walks start at its top again.
+   * So recording one owes no barrier: a pass that moves only its place makes
+   * no store sync, and the place becomes durable with the next one.
+   */
+  recordWalk(mount: string, scope: string, after: string | null): void {
+    if ((this.walkResumesAfter(mount, scope) ?? null) === after) return;
+    this.write({ t: 'walk', mount, scope, after }, {});
+  }
+
   /**
    * Record an intent. `durable` makes it (and every append before it) stable
    * before the caller performs the effect; batches pass it on their last one.
@@ -275,7 +354,8 @@ export class DiskAgreement {
   /**
    * Put back exactly the evidence a path had before an intent whose effect
    * never touched it — whatever kind it was (agreed, pending, interrupted, or
-   * unknown) — so the intent leaves no trace in what P says.
+   * unknown) — so the intent leaves no trace in what P says; where modes go
+   * unobserved, less any mode it carried, as every record written there.
    */
   restore(mount: string, path: string, value: Physical | undefined): void {
     if (value === undefined) this.forget(mount, path);
@@ -284,14 +364,21 @@ export class DiskAgreement {
 
   private write(entry: JournalEntry, opts: { durable?: boolean; afterCommittedState?: boolean }): void {
     this.ensureReconciled();
-    this.unsynced = true; // until proven durable: a failed append may still have landed
+    // A host that doesn't observe modes has none that's true to record: a
+    // record it writes carries no mode, and a host that observes them reads
+    // the path's mode as unknown, as for evidence from before modes were
+    // recorded. This holds whatever built the record: disk, the store's
+    // entry, or an earlier record a POSIX host wrote, put back by a restore.
+    // (A checkpoint re-serializes the evidence as it stands, other hosts'
+    // records included, as replaying the journal would.)
+    if (entry.t === 'set' && !this.modesObserved()) entry = { ...entry, value: withoutModes(entry.value) };
+    // Evidence is owed a barrier until proven durable: a failed append may
+    // still have landed. A place isn't (recordWalk).
+    if (entry.t !== 'walk') this.unsynced = true;
     this.journal.append(entry, opts);
     if (opts.durable) this.unsynced = false; // synced after this append, and so everything before it
     const mount = this.mounts.get((entry as { mount: string }).mount);
-    if (!mount) return;
-    if (entry.t === 'root') applyRoot(mount, entry);
-    else if (entry.t === 'set') mount.paths.set(entry.path, entry.value);
-    else if (entry.t === 'forget') mount.paths.delete(entry.path);
+    if (mount) apply(mount, entry);
   }
 
   /** Checkpoint when the tail has outgrown the live evidence. */
@@ -307,6 +394,7 @@ export class DiskAgreement {
         root: mount.root,
         ...(mount.identity ? { identity: mount.identity } : {}),
         paths: Object.fromEntries(mount.paths),
+        ...(mount.walks.size > 0 ? { walks: Object.fromEntries(mount.walks) } : {}),
       };
     }
     this.journal.checkpoint(snapshot);
@@ -319,7 +407,23 @@ export class DiskAgreement {
   }
 }
 
+/** Apply one entry to a mount's evidence; one of a kind this version doesn't know changes nothing. */
+function apply(mount: MountEvidence, entry: JournalEntry): void {
+  if (entry.t === 'root') applyRoot(mount, entry);
+  else if (entry.t === 'set') mount.paths.set(entry.path, entry.value);
+  else if (entry.t === 'forget') mount.paths.delete(entry.path);
+  else if (entry.t === 'walk') {
+    if (entry.after === null) mount.walks.delete(entry.scope);
+    else mount.walks.set(entry.scope, entry.after);
+  }
+}
+
 function applyRoot(mount: MountEvidence, entry: Extract<JournalEntry, { t: 'root' }>): void {
   mount.identity = entry.identity;
-  if (entry.reset) mount.paths.clear();
+  if (entry.reset) {
+    // Evidence about another directory says nothing about this one, and the
+    // accepted root's walks start at its top.
+    mount.paths.clear();
+    mount.walks.clear();
+  }
 }