@animalabs/agent-framework 0.22.1 → 0.22.2

package/src/modules/workspace/observe.ts

@@ -19,7 +19,7 @@
  * identity, and what they showed — a listing, an absence — is accepted only
  * if each is still the directory its logical path names afterwards. A walk records which
  * directories it listed completely, and only those prove a file absent: an
- * unreadable directory, an ignored subtree, the file cap, a symlink the walk
+ * unreadable directory, an ignored subtree, the walk cap, a symlink the walk
  * doesn't descend, or a directory that changed while it was listed leave
  * everything beneath them unproven. Outside a walk, absence is proven the
  * same way: by a directory inside the mount, still at its path, that lacks
@@ -672,13 +672,29 @@ export function sniffImageMime(head: Buffer): string | undefined {
 // ===========================================================================
 
 export interface Walk {
-  /** Regular files seen. */
+  /** Regular files the walk took: the pass observes each one. */
   files: Set<string>;
+  /**
+   * Regular files a listing showed that the walk didn't take, past its cap
+   * or outside the stretch a resumed walk covered: present, and not
+   * observed by this pass.
+   */
+  seen: Set<string>;
+  /**
+   * The names in `others` that aren't ignored and that the walk took, as it
+   * takes files, against its cap: the pass observes these by path. The rest
+   * are present, and not observed by this pass.
+   */
+  othersTaken: Set<string>;
   /** Directories seen. */
   dirs: Set<string>;
   /** Names seen that are neither (symlinks, sockets…), or ignored: present, unproven. */
   others: Map<string, string>;
-  /** Directories listed completely. */
+  /**
+   * Directories whose listing the walk read whole, and that were still the
+   * directory at their path once it had: every name in one is in `files`,
+   * `seen`, `dirs` or `others`, so a name in none of them is absent.
+   */
   complete: Set<string>;
   /** Directories that don't exist (everything beneath them is absent). */
   missing: Set<string>;
@@ -690,6 +706,59 @@ export interface Walk {
    * never walked; the pass reports the link itself by path.
    */
   incomplete: Array<{ path: string; reason: string; kind: 'error' | 'cap' | 'ignored' | 'symlink' }>;
+  /**
+   * When the walk cap stopped the walk, the last entry it took. A walk that
+   * resumes after it takes the entries after it first, in the walk's order
+   * (`compareInWalk`), then wraps to the start of its scope.
+   */
+  stoppedAfter?: string;
+}
+
+/** Names compare by UTF-16 code unit, the same on every platform and filesystem. */
+function compareNames(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Where file `a` falls against file `b` in the walk's order: in each
+ * directory, its files by name, then its subdirectories by name, each with
+ * everything beneath it. A resumed walk relies on visiting files in the
+ * order it compares positions by, so the walk sorts each listing itself
+ * rather than take `readdir`'s order, which is the platform's (Node returns
+ * UTF-8 byte order on Linux, which differs from this one for some names).
+ */
+function compareInWalk(a: string, b: string): number {
+  const x = a.split('/');
+  const y = b.split('/');
+  for (let i = 0; ; i++) {
+    const lastX = i === x.length - 1;
+    const lastY = i === y.length - 1;
+    if (x[i] !== y[i]) {
+      if (lastX && lastY) return compareNames(x[i]!, y[i]!);
+      if (lastX) return -1; // a directory's files come before its subdirectories
+      if (lastY) return 1;
+      return compareNames(x[i]!, y[i]!);
+    }
+    if (lastX && lastY) return 0;
+    if (lastX) return -1;
+    if (lastY) return 1;
+  }
+}
+
+/**
+ * Where the subtree of directory `dir` falls against file `at` in the walk's
+ * order: wholly before it, holding it (an ancestor of it), or wholly after it.
+ */
+function subtreeAgainst(dir: string, at: string): 'before' | 'holds' | 'after' {
+  if (dir === '') return 'holds';
+  const d = dir.split('/');
+  const p = at.split('/');
+  for (let i = 0; i < d.length; i++) {
+    // `at` is a file in the directory above d[i], whose files come first.
+    if (i === p.length - 1) return 'after';
+    if (d[i] !== p[i]) return compareNames(d[i]!, p[i]!) < 0 ? 'before' : 'after';
+  }
+  return 'holds';
 }
 
 /**
@@ -740,17 +809,32 @@ async function checkChild(view: MountView, rootReal: string, parent: CheckedDir,
 
 /**
  * List a directory scope ('' for the mount root), descending when recursive,
- * up to `cap` files in total. A scope that resolves outside the mount is not
- * listed at all; beneath it, the walk only descends real directories, never
- * symlinks. Each directory's listing counts only if, once listed, it is still
- * the directory at its path: a directory moved or replaced meanwhile is an
- * incomplete region, contributing no names and proving nothing absent.
+ * taking up to `cap` entries in the walk's order (`compareInWalk`): files,
+ * and links or other entries that aren't directories. A scope
+ * that resolves outside the mount is not listed at all; beneath it, the walk
+ * only descends real directories, never symlinks. Each directory's listing
+ * counts only if, once listed, it is still the directory at its path: a
+ * directory moved or replaced meanwhile is an incomplete region, contributing
+ * no names and proving nothing absent.
+ *
+ * Each listing is read whole and every name in it recorded, so the files the
+ * cap leaves are known present (`seen`) and a name the listing lacks is
+ * proven absent, whichever files were taken. Once the cap is reached, no
+ * further directory is listed.
+ *
+ * With `resumeAfter` (an entry in the scope, from an earlier walk's
+ * `stoppedAfter`), a recursive walk takes the entries after it first, then
+ * wraps to the start of the scope, so repeated walks cover a scope larger
+ * than the cap.
  */
 export async function walkScope(
   view: MountView, rootReal: string, scope: string, recursive: boolean, cap: number,
-  opts: { named?: boolean } = {},
+  opts: { named?: boolean; resumeAfter?: string } = {},
 ): Promise<Walk> {
-  const walk: Walk = { files: new Set(), dirs: new Set(), others: new Map(), complete: new Set(), missing: new Set(), incomplete: [] };
+  const walk: Walk = {
+    files: new Set(), seen: new Set(), othersTaken: new Set(), dirs: new Set(), others: new Map(), complete: new Set(), missing: new Set(),
+    incomplete: [],
+  };
   const top = await checkDir(view, rootReal, scope);
   if (top.kind === 'absent') {
     walk.missing.add(scope);
@@ -760,20 +844,85 @@ export async function walkScope(
     walk.incomplete.push({ path: scope, reason: top.outside ? 'the directory resolves outside the mount' : top.reason, kind: 'error' });
     return walk;
   }
-  let capped = false;
   // A scope a path sync names is walked even where the ignore list covers
   // it: a pattern covering the scope itself, or a directory above it, doesn't
   // apply beneath it. So a named directory's contents are synced, as a named
   // file is (agent-framework #276). A listing keeps the ignore: its pass
   // would otherwise start tracking what it lists.
   const ignore = opts.named ? view.ignore.filter((pattern) => !coveredByIgnore(scope, [pattern])) : view.ignore;
+  // A position outside the scope, or for a walk that doesn't descend, is no
+  // position in this walk's order.
+  const after = recursive && opts.resumeAfter !== undefined && (scope === '' || opts.resumeAfter.startsWith(scope + '/'))
+    ? opts.resumeAfter
+    : undefined;
 
-  const visit = async (dir: CheckedDir): Promise<void> => {
+  /** A listing's entries that aren't directories or ignored, in the walk's order, each a regular file or not. */
+  type Listing = { leaves: Array<[string, boolean]>; subdirs: string[]; dev: string; ino: string };
+  /**
+   * Each directory is listed once: a resumed walk visits the ones holding its
+   * position on both sides of it, and the second visit reuses the listing
+   * while the directory at its path is still the one it was read from.
+   */
+  const listings = new Map<string, Listing | null>();
+  const visited = new Set<string>();
+  /** Paths already reported as errors, so a second visit doesn't report them again. */
+  const failed = new Set<string>();
+  const fail = (path: string, reason: string): void => {
+    if (failed.has(path)) return;
+    failed.add(path);
+    walk.incomplete.push({ path, reason, kind: 'error' });
+  };
+  let left = cap;
+  let lastTaken: string | undefined;
+
+  /**
+   * Take back what the walk read at or beneath `rel`, a directory replaced
+   * or gone since it was listed: it describes the directory that was there,
+   * so no listing there proves anything absent, the entries and
+   * subdirectories they left untaken aren't the cap's to report, and a
+   * subdirectory proven missing there proves nothing about what's there
+   * now. What was taken stays taken: the pass observes it by path.
+   */
+  const dropBeneath = (rel: string): void => {
+    const beneath = (path: string): boolean => rel === '' || path.startsWith(rel + '/');
+    for (const [path, listing] of listings) {
+      if (path !== rel && !beneath(path)) continue;
+      if (listing) {
+        for (const [leaf, isFile] of listing.leaves) if (isFile) walk.seen.delete(leaf);
+        for (const sub of listing.subdirs) walk.dirs.delete(sub);
+      }
+      walk.complete.delete(path);
+      listings.set(path, null);
+    }
+    // The links, ignored names and other entries those listings showed, and
+    // the regions they gave rise to, described the directory that was there.
+    for (const [path] of walk.others) if (beneath(path) && !walk.othersTaken.has(path)) walk.others.delete(path);
+    for (let i = walk.incomplete.length - 1; i >= 0; i--) {
+      const region = walk.incomplete[i]!;
+      if ((region.kind === 'symlink' || region.kind === 'ignored') && beneath(region.path)) walk.incomplete.splice(i, 1);
+    }
+    for (const path of walk.missing) if (beneath(path)) walk.missing.delete(path);
+  };
+
+  const list = async (dir: CheckedDir): Promise<Listing | null> => {
     const rel = dir.rel;
-    if (capped) {
-      walk.incomplete.push({ path: rel, reason: `not visited: the file cap (${cap}) was reached`, kind: 'cap' });
-      return;
+    const known = listings.get(rel);
+    if (known === null) return null;
+    if (known !== undefined) {
+      // The scope's own directory comes back as the same CheckedDir, so its
+      // identity is checked against the path again, as a subdirectory's is
+      // by the fresh check that brought it here.
+      const now = dir.identity();
+      if (known.dev === now.dev && known.ino === now.ino && await dir.stillHere()) return known;
+      dropBeneath(rel);
+      fail(rel, CHANGED_WALK);
+      return null;
     }
+    listings.set(rel, null);
+    // Reading a directory is a check of it too, and replaces an earlier proof
+    // that it was missing: the scope's own directory, read afresh on the
+    // wrap, has no check of its own.
+    walk.missing.delete(rel);
     let entries;
     try {
       entries = await readdir(dir.real, { withFileTypes: true });
@@ -782,18 +931,23 @@ export async function walkScope(
       if (code === 'ENOENT' || code === 'ENOTDIR') {
         // Gone since it was checked: absent beneath only if that can be shown.
         const proof = rel === '' ? ROOT_UNAVAILABLE : await confirmAbsent(view, rootReal, rel, 'beneath');
-        if (typeof proof === 'string') walk.incomplete.push({ path: rel, reason: proof, kind: 'error' });
-        else walk.missing.add(rel);
-        return;
+        if (typeof proof === 'string') fail(rel, proof);
+        else {
+          walk.missing.add(rel);
+          // Nothing was listed, so a later check that finds it again, on the
+          // wrap, lists it afresh.
+          listings.delete(rel);
+        }
+        return null;
       }
-      walk.incomplete.push({ path: rel, reason: `cannot list (${code ?? String(err)})`, kind: 'error' });
-      return;
+      fail(rel, `cannot list (${code ?? String(err)})`);
+      return null;
     }
-    const files: string[] = [];
+    entries.sort((a, b) => compareNames(a.name, b.name));
+    const leaves: Array<[string, boolean]> = [];
     const subdirs: string[] = [];
     const others: Array<[string, string]> = [];
     const regions: Walk['incomplete'] = [];
-    let reachedCap = false;
     for (const entry of entries) {
       const childRel = rel ? `${rel}/${entry.name}` : entry.name;
       if (isIgnored(childRel, entry.name, ignore)) {
@@ -804,15 +958,10 @@ export async function walkScope(
       if (entry.isDirectory()) {
         subdirs.push(childRel);
       } else if (entry.isFile()) {
-        if (walk.files.size + files.length >= cap) {
-          capped = true;
-          reachedCap = true;
-          regions.push({ path: rel, reason: `the file cap (${cap}) was reached`, kind: 'cap' });
-          break;
-        }
-        files.push(childRel);
+        leaves.push([childRel, true]);
       } else {
         const symlink = entry.isSymbolicLink();
+        leaves.push([childRel, false]);
         others.push([childRel, symlink ? 'a symlink' : 'not a regular file']);
         if (symlink) regions.push({ path: childRel, reason: 'a symlink, not walked', kind: 'symlink' });
       }
@@ -820,25 +969,102 @@ export async function walkScope(
     // A listing of a directory that was moved or replaced meanwhile says
     // nothing about this path: neither its names nor its absences count.
     if (!(await dir.stillHere())) {
-      walk.incomplete.push({ path: rel, reason: CHANGED_WALK, kind: 'error' });
-      return;
+      fail(rel, CHANGED_WALK);
+      return null;
     }
-    for (const f of files) walk.files.add(f);
+    for (const [p, isFile] of leaves) if (isFile) walk.seen.add(p);
     for (const d of subdirs) walk.dirs.add(d);
     for (const [p, why] of others) walk.others.set(p, why);
     walk.incomplete.push(...regions);
-    if (reachedCap) return;
     walk.complete.add(rel);
+    const listing = { leaves, subdirs, ...dir.identity() };
+    listings.set(rel, listing);
+    return listing;
+  };
+
+  type Stretch = 'all' | 'after' | 'upto';
+  const fileIn = (stretch: Stretch, file: string): boolean =>
+    stretch === 'all' || (compareInWalk(file, after!) > 0) === (stretch === 'after');
+  const dirIn = (stretch: Stretch, dir: string): boolean => {
+    if (stretch === 'all') return true;
+    const at = subtreeAgainst(dir, after!);
+    return at === 'holds' || at === (stretch === 'after' ? 'after' : 'before');
+  };
+
+  const visit = async (dir: CheckedDir, stretch: Stretch): Promise<void> => {
+    visited.add(dir.rel);
+    const listing = await list(dir);
+    if (!listing) return;
+    // A link or other entry that isn't a directory is taken as a file is,
+    // against the cap: the pass observes each one it takes, and following a
+    // link can read as much as a file.
+    for (const [leaf, isFile] of listing.leaves) {
+      if (left === 0) break;
+      if (!fileIn(stretch, leaf)) continue;
+      left--;
+      if (isFile) {
+        walk.seen.delete(leaf);
+        walk.files.add(leaf);
+      } else {
+        walk.othersTaken.add(leaf);
+      }
+      lastTaken = leaf;
+    }
     if (!recursive) return;
-    for (const sub of subdirs) {
+    for (const sub of listing.subdirs) {
+      // Once the cap is reached, no further directory is listed.
+      if (left === 0) break;
+      if (!dirIn(stretch, sub)) continue;
       const child = await checkChild(view, rootReal, dir, sub);
-      if (child.kind === 'checked') await visit(child.dir);
-      else if (child.kind === 'absent') walk.missing.add(sub);
-      else walk.incomplete.push({ path: sub, reason: child.reason, kind: 'error' });
+      // This check replaces what an earlier one proved of `sub` itself, such
+      // as missing on the after stretch and found again on the wrap. What was
+      // proven beneath a directory that is still the same one stands, and
+      // list() drops it from one that isn't.
+      walk.missing.delete(sub);
+      if (child.kind === 'checked') {
+        await visit(child.dir, stretch);
+        continue;
+      }
+      // On the wrap, a directory listed on the first stretch that isn't the
+      // directory there now: what the walk read of it describes another.
+      dropBeneath(sub);
+      if (child.kind === 'absent') walk.missing.add(sub);
+      else fail(sub, child.reason);
     }
   };
 
-  await visit(top.dir);
+  if (after === undefined) {
+    await visit(top.dir, 'all');
+  } else {
+    await visit(top.dir, 'after');
+    if (left > 0) await visit(top.dir, 'upto');
+  }
+
+  // What the cap left: directories holding entries not taken, and
+  // directories a listing showed that weren't listed. A walk that doesn't
+  // descend leaves its subdirectories by design.
+  const capped = `the walk cap (${cap}) was reached`;
+  const holdingUntaken = new Set<string>();
+  for (const f of walk.seen) holdingUntaken.add(parentOf(f));
+  for (const [p, why] of walk.others) if (why !== 'ignored by the mount' && !walk.othersTaken.has(p)) holdingUntaken.add(parentOf(p));
+  for (const d of holdingUntaken) {
+    walk.incomplete.push({ path: d, reason: `${capped} before everything here was taken`, kind: 'cap' });
+  }
+  let unlisted = 0;
+  if (recursive) {
+    for (const d of walk.dirs) {
+      if (visited.has(d) || walk.missing.has(d) || failed.has(d)) continue;
+      unlisted++;
+      walk.incomplete.push({ path: d, reason: `not visited: ${capped}`, kind: 'cap' });
+    }
+  }
+  // The cap stopped the walk only if it left something: a walk whose last
+  // file used up the cap covered its scope. A directory the walk didn't list
+  // counts as left, even one that holds nothing it would take (empty, or
+  // only ignored names): telling them apart would take another read. Such a
+  // walk keeps its place and reports the directory as not visited, and the
+  // next one lists it on its way to the wrap.
+  if (left === 0 && lastTaken !== undefined && (holdingUntaken.size > 0 || unlisted > 0)) walk.stoppedAfter = lastTaken;
   return walk;
 }
 
@@ -855,7 +1081,7 @@ export function provenAbsent(walk: Walk, path: string): boolean {
     if (walk.missing.has(dir)) return true;
     const child = dir ? `${dir}/${parts[i]}` : parts[i]!;
     if (walk.complete.has(dir)) {
-      if (walk.others.has(child)) return false; // present, but unproven
+      if (walk.others.has(child) || walk.seen.has(child)) return false; // present, but unproven
       if (i === parts.length - 1) return !walk.files.has(child) && !walk.dirs.has(child);
       if (!walk.dirs.has(child)) return true; // no directory there: nothing beneath can exist
     }

package/src/modules/workspace/reconcile.ts

@@ -152,6 +152,14 @@ export interface MountRuntime {
   treeStateId: string;
   intents: BranchIntents;
   readOnly: boolean;
+  /** The most entries one walk of the mount takes, files and the other entries that aren't directories (`MountConfig.walkCap`). */
+  walkCap: number;
+  /**
+   * Whether the mount runs a catch-up scan (`watch: 'always'`, at start and
+   * when its watcher reattaches), which takes turns with its whole-mount
+   * syncs.
+   */
+  catchUpScan: boolean;
 }
 
 export type Scope =
@@ -163,8 +171,16 @@ export interface PassOptions {
   rehash?: boolean;
   /** Paths whose disk state is adopted explicitly (a path sync). */
   adopt?: (path: string) => boolean;
-  /** Walk cap for directory scopes. */
+  /** Walk cap for directory scopes; the mount's `walkCap` when absent. */
   cap?: number;
+  /**
+   * A recursive directory pass of a sync or a catch-up scan: its walk resumes
+   * after the last entry the previous one of this scope took, and records
+   * where it stopped, so repeated passes cover a scope larger than the cap.
+   * A listing's pass, and an agent-action scan's, start at their scope's
+   * start and record no place.
+   */
+  resume?: boolean;
   /**
    * The scope was named by a path sync: ignore patterns that cover it don't
    * apply beneath it (see walkScope). A listing's scope keeps them.
@@ -618,10 +634,16 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
     for (const [p] of agreement.paths(mount.name, scope.dir)) if (inScope(p, scope)) candidates.add(p);
     for (const [p] of mount.intents.list(scope.dir)) if (inScope(p, scope)) candidates.add(p);
     if (rootUnavailable === null) {
-      walk = await walkScope(mount.view, mount.rootReal, scope.dir, scope.recursive, opts.cap ?? WALK_CAP, { named: opts.named });
+      const resumeAfter = opts.resume ? agreement.walkResumesAfter(mount.name, scope.dir) : undefined;
+      walk = await walkScope(mount.view, mount.rootReal, scope.dir, scope.recursive, opts.cap ?? mount.walkCap, {
+        named: opts.named,
+        ...(resumeAfter !== undefined ? { resumeAfter } : {}),
+      });
       for (const f of walk.files) if (inScope(f, scope)) candidates.add(f);
-      // Ignored names are listed only when something tracks them (above).
-      for (const [p, why] of walk.others) if (why !== 'ignored by the mount' && inScope(p, scope)) candidates.add(p);
+      // The other entries it took (a link, a socket…). Ignored names, and the
+      // entries the cap left, are listed only when something tracks them
+      // (above).
+      for (const p of walk.othersTaken) if (inScope(p, scope)) candidates.add(p);
       for (const d of walk.dirs) if (inScope(d, { kind: 'dir', dir: scope.dir, recursive: false })) gathered.dirs.push(d);
     }
   }
@@ -637,16 +659,23 @@ async function gather(store: JsStore, agreement: DiskAgreement, mount: MountRunt
       gathered.facts.set(path, { kind: 'absent' });
       continue;
     }
-    if (walk && !walk.files.has(path) && !walk.others.has(path)) {
-      // Beneath a region the walk didn't reach: unproven either way.
-      const region = walk.incomplete.find((r) => r.path === '' || path === r.path || path.startsWith(r.path + '/'));
-      gathered.facts.set(path, { kind: 'unobserved', reason: region ? region.reason : 'not reached by the walk' });
-      continue;
-    }
     if (walk?.others.get(path) === 'ignored by the mount') {
       gathered.facts.set(path, { kind: 'unobserved', reason: 'ignored by the mount' });
       continue;
     }
+    if (walk && !walk.files.has(path) && !walk.othersTaken.has(path)) {
+      // Not taken by the walk, or beneath a region it didn't reach: unproven
+      // either way. The nearest region holding it says why.
+      let region: Walk['incomplete'][number] | undefined;
+      for (const r of walk.incomplete) {
+        if (r.path !== '' && path !== r.path && !path.startsWith(r.path + '/')) continue;
+        // A link's own region is about what lies beneath it, not the link.
+        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' });
+      continue;
+    }
     const p = agreement.get(mount.name, path);
     const hasStore = store.treeGet(mount.treeStateId, path) !== null;
     const hasIntent = mount.intents.get(path) !== null;
@@ -793,6 +822,18 @@ export async function reconcilePass(
     agreement.set(mount.name, x.path, next, { afterCommittedState: first });
     first = false;
   }
+  // Where the walk stopped, once what it observed is decided: the next pass
+  // of this scope resumes after it, or starts afresh once this one covered
+  // the scope. A walk that couldn't list its scope's own directory covered
+  // none of it, and leaves the place as it was. Unlike evidence, a place
+  // binds no root: it only says where the next walk starts, and that walk
+  // takes its turn after it in whatever directory is the root by then.
+  let resumeAfter: string | null | undefined;
+  if (opts.resume && walk && scope.kind === 'dir' && scope.recursive && walk.complete.has(scope.dir)) {
+    resumeAfter = walk.stoppedAfter ?? null;
+    agreement.recordWalk(mount.name, scope.dir, resumeAfter);
+  }
+
   // 5. Durable before returning. An agreement advance (D = S) has no pending
   // intent to recover from, so losing its append would leave an older P that
   // another branch would misread as a disk edit.
@@ -816,15 +857,31 @@ export async function reconcilePass(
   }
   if (walk) {
     const tracked = [...result.reports.values()].filter((r) => r.state === 'unverified').map((r) => r.path);
+    if (typeof resumeAfter === 'string' && scope.kind === 'dir') {
+      // A watched mount's catch-up scan takes turns with its whole-mount
+      // syncs; nothing else moves a place.
+      const next = scope.dir !== ''
+        ? 'the next sync of this directory'
+        : mount.catchUpScan
+          ? 'the next sync of the mount, or its catch-up scan if that comes first,'
+          : 'the next sync of the mount';
+      result.incomplete.push({
+        path: scope.dir,
+        reason: `the walk cap (${opts.cap ?? mount.walkCap}) was reached: ${next} resumes after ${mount.name}/${resumeAfter}`,
+      });
+    }
     for (const region of walk.incomplete) {
-      const hides = tracked.some((p) => p === region.path || p.startsWith(region.path + '/'));
+      // A link's own region hides only what lies beneath it: the link itself
+      // is reported by path, with its own reason.
+      const hides = tracked.some((p) => (region.kind !== 'symlink' && p === region.path) || p.startsWith(region.path + '/'));
       if (region.kind === 'error' || region.kind === 'cap' || hides) result.incomplete.push({ path: region.path, reason: region.reason });
       // An ignored name 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: the link
-      // itself is a candidate the pass reports by path, taken through the
+      // (agent-framework #276). A symlink region isn't counted: a link the
+      // walk took is a candidate the pass reports by path, taken through the
       // link when it's a file on a mount that follows symlinks, and
-      // otherwise listed under `skipped`.
+      // otherwise listed under `skipped`; a tracked link the cap left is
+      // unverified for the cap.
       else if (region.kind === 'ignored') result.passedOver.set(region.reason, (result.passedOver.get(region.reason) ?? 0) + 1);
     }
   }

package/src/modules/workspace/types.ts

@@ -22,7 +22,9 @@ export interface MountConfig {
    * - 'on-agent-action': after each completed agent tool batch, the mount is
    *   scanned, and the agent's next inference waits for that scan up to
    *   `agentActionScanDeadlineMs`; a scan that takes longer finishes while
-   *   the round goes on
+   *   the round goes on. Each scan walks from the mount's start, so on a
+   *   mount over its `walkCap` it covers the first `walkCap` entries every
+   *   time, and files past them come in as `walkCap` describes
    * - 'never': no background reads; listings and lazy reads still observe
    *   the paths they show
    */
@@ -42,6 +44,29 @@ export interface MountConfig {
   followSymlinks?: boolean;
   /** Maximum file size in bytes (default: 5MB) */
   maxFileSize?: number;
+  /**
+   * The most entries one walk of this mount takes (default: 5000), a
+   * positive integer no larger than Number.MAX_SAFE_INTEGER: files, and
+   * links or other entries that aren't
+   * directories, each of which the pass observes. A sync that reaches it
+   * reports the rest as incomplete, and the next sync of the same scope
+   * resumes after the last entry it took, wrapping to the start, so repeated
+   * syncs cover a larger mount. A watched mount's catch-up scan (at start,
+   * and when its watcher reattaches) takes its turn in the same rotation as
+   * the mount's bare syncs, so on a mount over the cap, a change made while
+   * the process was down waits for the rotation to reach it. The place is
+   * kept with the mount's disk evidence, so a restart resumes there, unless
+   * the machine went down before the store made the latest place durable.
+   * An agent-action scan (`watch: 'on-agent-action'`) and a listing (`ls`,
+   * `glob`, `grep`) take up to it from their scope's start every time. Each
+   * directory's listing is read whole, so a deletion is seen wherever the
+   * walk lists, whatever it took.
+   *
+   * It bounds what a walk observes, not the walk's own work: directories
+   * don't count against it, and each one the walk visits is read whole, so
+   * a tree of many directories that hold nothing is walked in full.
+   */
+  walkCap?: number;
   /**
    * If set, filesystem changes on this mount request inference.
    * - `true` — wake on any op (created | modified | deleted)