@animalabs/agent-framework 0.23.3 → 0.24.1

package/src/modules/workspace/index.ts

@@ -5,12 +5,11 @@
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
 
-import { isUtf8 } from 'node:buffer';
 import { constants as fsConstants } from 'node:fs';
 import type { Stats } from 'node:fs';
 import { open, readdir, readlink, stat, lstat, realpath } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, parse, resolve, relative, sep } from 'node:path';
-import type { JsStore } from '@animalabs/chronicle';
+import type { JsStore, JsTreeEntry } from '@animalabs/chronicle';
 import type { Module, ModuleContext, ProcessState, EventResponse } from '../../types/module.js';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from '../../types/events.js';
 import type {
@@ -23,6 +22,7 @@ import type {
   ReadImageInput,
   WriteInput,
   EditInput,
+  EditManyInput,
   DeleteInput,
   LsInput,
   GlobInput,
@@ -39,9 +39,12 @@ import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher, type FsChange } from './watcher.js';
 import { hashContent, DEFAULT_MAX_FILE_SIZE } from './sync.js';
 import { DiskAgreement, sameRootIdentity } from './disk-agreement.js';
-import { BranchIntents } from './branch-intent.js';
-import { IGNORED, NONBLOCK, OTHER_MOUNT, ROOT_REPLACED, ROOT_UNAVAILABLE, checkDir, checkRoot, diskSpelling, filesystemTrustsCtime, foldsCase, inOtherMount, leadsInto, linkLeads, linkOnTheWay, linkRefusal, linkWords, locateRoot, nestedAtReal, nestedHolder, passedOverAt, readPrefix, type CheckedDir, type LinkFound, type MountView, type NestedMount, type WorkspaceEntries } from './observe.js';
+import { type BranchIntent, BranchIntents } from './branch-intent.js';
+import { IGNORED, NONBLOCK, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beginsWithDir, checkDir, checkRoot, coversLanding, diskSpelling, filesystemTrustsCtime, foldsCase, includePatternReadable, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, namesNestedPlace, nestedAtReal, nestedHolder, observePath, parsedSpelling, passedOverAt, pathSegments, readBytes, readPrefix, shownLeads, sniffImageMime, walkScope, withinIncludes, type CheckedDir, type LinkFound, type MountView, type NestedMount, type WorkspaceEntries } from './observe.js';
 import { TOOL_BATCH_HOOK_TIMEOUT_MS, ensureStateRegistered } from '../../module-registry.js';
+import { DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS } from '../../tool-result-history.js';
+import { type EditSpec, type FilePlan, countBudget, decodeForEdit, hintBudget, planFile } from './edit-plan.js';
+import { type EditProblem, type EditTool, cutLine, editList, editReceipt, fitted, refusalText } from './edit-text.js';
 import {
   type MountRuntime,
   type PassOptions,
@@ -73,6 +76,18 @@ const CATCH_UP_BOUND_MS = 30_000;
 const NOT_RUNNING = 'The workspace has stopped: it takes no more work until it starts again';
 /** The workspace's own deadline must end before the framework's hook bound. */
 const AGENT_ACTION_SCAN_DEADLINE_MAX_MS = TOOL_BATCH_HOOK_TIMEOUT_MS - 1_000;
+/** A direct mount's ignore list when its config names none (MountConfig.ignore). */
+const DIRECT_MOUNT_IGNORE: readonly string[] = ['node_modules', 'dist', '.git', 'build', 'coverage', 'target', '__pycache__', '.venv'];
+/**
+ * How many files a direct mount's grep reads, and its listings look at, at
+ * once. Over a layout of seven checkouts, 5,929 files, a direct grep reading
+ * 16 at a time on Node's default threadpool had a median time below the
+ * store-backed grep's over the same files at every load tried, and one
+ * reading them in turn took 2 to 2.4 times as long.
+ */
+const DIRECT_READS_AT_ONCE = 16;
+/** Why sync passes over a direct mount, as its result's `skipped` says. */
+const DIRECT_SYNC_SKIPPED = "a direct mount: its tools read disk as it is, so there's nothing to take in";
 
 export type {
   WorkspaceConfig,
@@ -83,6 +98,7 @@ export type {
   ReadImageInput,
   WriteInput,
   EditInput,
+  EditManyInput,
   DeleteInput,
   LsInput,
   GlobInput,
@@ -133,15 +149,28 @@ class WorkspaceImageReadError extends Error {
  * link and, where it leads somewhere, its target, a symlink whose canonical
  * target lands outside the canonical mount root, or one among the path's
  * directories leading out of it (`escape`), a file swapped underneath the read
- * (`changed`), and a path in another mount's directory nested in the one
- * named, or reached through a symlink among the path's directories leading
- * there (`other_mount`), whose message names the mount that holds it and the
- * path to use there. A `mount_unavailable` for a root whose realpath or stat
- * fails otherwise carries that errno, such as EACCES.
+ * (`changed`), a path the mount's `include` doesn't cover (`outside_include`),
+ * and a path in another mount's directory nested in the one named
+ * (`other_mount`), whose message names the mount that holds it and the path
+ * to use there. A symlink leading into such a directory is `other_mount`
+ * only where its refusal names that mount: a directory, or a file that
+ * mount's include covers. Anywhere else, on a mount that doesn't follow
+ * symlinks, it gets the code of a link where it stands, `symlink` at the
+ * path itself and `parent_symlink` on its way, and on one that does,
+ * `escape`, as a path that leaves the mount. On a mount with an include, a
+ * link's message names its target only where a tool could name it: a
+ * directory, or a file the include covers. A link the include doesn't cover
+ * is outside the mount, and its message tells nothing of where it leads, so
+ * on a path's way its code is `parent_symlink` wherever it leads; named
+ * itself, it's refused as outside the include (`outside_include`), as any
+ * path the include doesn't cover is.
+ * A `mount_unavailable` for a root whose realpath or stat fails otherwise
+ * carries that errno, such as EACCES.
  */
 export type WorkspaceReadErrorCode =
   | 'unknown_mount'
   | 'traversal'
+  | 'outside_include'
   | 'other_mount'
   | 'mount_unavailable'
   | 'not_found'
@@ -166,6 +195,14 @@ export type WorkspaceReadStage =
   | 'stat'
   | 'read';
 
+/** A path the mount's `include` doesn't cover: outside the mount. */
+class OutsideIncludeError extends Error {
+  constructor(shownPath: string, mount: MountConfig) {
+    super(`"${shownPath}" is outside the mount's include: mount "${mount.name}" holds only ${(mount.include ?? []).join(', ')}. `
+      + 'The host\'s operator sets the include in the mount\'s configuration, so calling again with this path changes nothing.');
+  }
+}
+
 /**
  * A file operation's path lies in another mount's directory nested in the
  * mount it names. The message names the mount that holds it and the path to
@@ -231,6 +268,16 @@ export interface ReadFileFromDiskOptions {
   maxBytes?: number;
 }
 
+/**
+ * Why a pass decided nothing, or null where it decided its paths. A pass gives
+ * up deciding, and reports no path, when the selected branch kept changing
+ * while it gathered, or when a sync's branch was no longer selected; it then
+ * carries no branchId, and the region it leaves incomplete says why.
+ */
+function undecidedOf(pass: PassResult): string | null {
+  return pass.branchId === undefined ? (pass.incomplete[0]?.reason ?? 'the pass decided nothing') : null;
+}
+
 function errnoOf(err: unknown): string | undefined {
   return typeof err === 'object' && err !== null && 'code' in err && typeof (err as { code?: unknown }).code === 'string'
     ? (err as { code: string }).code
@@ -288,27 +335,37 @@ function matchesPartialPrefix(buffer: Buffer, prefix: Buffer): boolean {
  * link's reason, as the observations give it, after the path; or, for a
  * directory the walk couldn't ask, a failure to read, coded `not_found` with
  * the readlink's errno, as every failed lookup is. A link's code follows
- * where it leads, so a caller choosing advice by code gets advice that fits:
+ * where its refusal says it leads (shownLeads), so a caller choosing advice
+ * by code gets advice that fits, and the code says no more than the message:
  * `escape` for a link leading outside the mount, the code a path resolving
- * outside it gets too; `other_mount` for one into a nested mount's directory,
- * the code that mount's own paths get; and `parent_symlink` for any other,
- * which `symlink`, a file that is itself a link, leaves apart.
+ * outside it gets too; `other_mount` for one into a nested mount's directory
+ * where the message names that mount (namesHolder), the code that mount's own
+ * paths get; and for any other, a link the mount's include doesn't cover
+ * among them, the code of a link the mount doesn't follow where it stands:
+ * `symlink` at the path itself, as any other link there gets, and
+ * `parent_symlink` among its directories, judged on the parsed path
+ * (`relativePath`), whatever spelling the caller gave. Where the link leads is
+ * read beneath `rootReal`, the root the check that found it resolved, so the
+ * link and its target are judged beneath one root, by that root's nesting
+ * (`nested`).
  */
 async function linkReadError(
-  mount: { config: { name: string; path: string } },
+  mount: { config: { name: string; path: string; include?: readonly string[] } },
   found: LinkFound,
   mountPrefixedPath: string,
-  nested: readonly { dir: string; name: string }[],
+  relativePath: string,
+  nested: readonly NestedMount[],
+  rootReal: string,
 ): Promise<WorkspaceReadError> {
   if (!('link' in found)) {
     return new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}: ${linkWords(mount.config.name, found, null)}`, 'readlink', found.code);
   }
-  const rootReal = await realpath(mount.config.path).catch(() => resolve(mount.config.path));
-  const leads = await linkLeads(mount.config.path, rootReal, found.link);
-  const reason = `${mountPrefixedPath}: ${linkWords(mount.config.name, found, leads, nested)}`;
-  const code = leads.kind === 'outside' ? 'escape'
-    : leads.kind === 'inside' && nestedHolder(leads.target, nested) ? 'other_mount'
-    : 'parent_symlink';
+  const leads = await shownLeads(rootReal, rootReal, found, mount.config.include);
+  const reason = `${mountPrefixedPath}: ${linkWords(mount.config.name, found, leads, nested, mount.config.include)}`;
+  const holder = leads?.kind === 'inside' ? nestedHolder(leads.target, nested) : undefined;
+  const code = leads?.kind === 'outside' ? 'escape'
+    : leads?.kind === 'inside' && holder && namesHolder(leads, holder) ? 'other_mount'
+    : relativePath === found.link ? 'symlink' : 'parent_symlink';
   return new WorkspaceReadError(code, reason, 'readlink');
 }
 
@@ -325,6 +382,48 @@ function nestedDir(from: string, to: string): string | undefined {
   return rel.split(sep).join('/');
 }
 
+/** Each directory above `path`, innermost first, to the filesystem's root. */
+function ancestorsOf(path: string): string[] {
+  const dirs: string[] = [];
+  for (let dir = dirname(path); ; dir = dirname(dir)) {
+    dirs.push(dir);
+    if (dirname(dir) === dir) return dirs;
+  }
+}
+
+/**
+ * Where a mount is nested in an outer mount, as a start places it: at its
+ * directory as configured beneath the outer mount's configured path
+ * (`outerPath`), beneath each directory above its configured path that is
+ * the outer root on disk (`above`, each with where it lies on disk), and
+ * where its real root (`real`) lies beneath the outer root (`outerReal`),
+ * each also as disk spells it beneath `spellAt`. Its real root is claimed
+ * where it doesn't hold the outer root, which it would otherwise claim
+ * whole. Undefined where it's nested nowhere.
+ */
+async function placementOf(
+  outerPath: string,
+  outerReal: string,
+  innerPath: string,
+  real: string,
+  above: ReadonlyArray<{ dir: string; real: string }>,
+  spellAt: string,
+): Promise<{ configured: string | undefined; fromRoots: Array<{ dir: string; root: string }>; spellings: Array<{ dir: string; root: string }>; claims: boolean } | undefined> {
+  const configured = nestedDir(outerPath, innerPath);
+  const throughRoot = above.filter((a) => a.real === outerReal).map((a) => nestedDir(a.dir, innerPath));
+  const fromRoots: Array<{ dir: string; root: string }> = [];
+  for (const dir of [configured, ...throughRoot, nestedDir(outerReal, real)]) {
+    if (dir !== undefined && !fromRoots.some((s) => s.dir === dir)) fromRoots.push({ dir, root: join(outerPath, ...dir.split('/')) });
+  }
+  if (fromRoots.length === 0) return undefined;
+  const spellings = [...fromRoots];
+  for (const found of fromRoots) {
+    const dir = await diskSpelling(spellAt, found.dir);
+    if (!spellings.some((s) => s.dir === dir)) spellings.push({ dir, root: join(outerPath, ...dir.split('/')) });
+  }
+  return { configured, fromRoots, spellings, claims: !isContainedPath(real, outerReal) };
+}
+
 /** A mount nested in another, as the outer mount's otherMounts holds it. */
 interface NestedMountEntry {
   name: string;
@@ -340,6 +439,22 @@ interface NestedMountEntry {
   spellings: Array<{ dir: string; root: string }>;
 }
 
+/**
+ * A path as parsePath reads it: its mount, and its mount-relative and
+ * mount-prefixed paths as the parse spells them; with the root the parse
+ * judged it beneath, a direct mount's as the parse resolved it and any
+ * other's as configured, and, where a direct mount's root lies elsewhere
+ * than the last start placed it, the mounts nested in it there
+ * (movedNesting), null otherwise.
+ */
+interface ParsedPath {
+  mount: MountState;
+  relativePath: string;
+  path: string;
+  root: string;
+  moved: NestedMount[] | null;
+}
+
 /** How many links realBeneath follows to a place not made yet before it stops, as the kernel's limit does. */
 const LINKS_FOLLOWED = 40;
 
@@ -348,13 +463,14 @@ const LINKS_FOLLOWED = 40;
  * it, with the links on its way and in it taken out, read without holding
  * the process. Where nothing is there yet, a link leads where its target
  * would be, and anything else lies beneath its nearest existing directory's
- * real path, with the rest as given. A link's target is read from the
- * link's directory as it is on disk, and nothing is resolved lexically on
- * the way, so a `..` is taken from where the links before it lead, as the
+ * real path, with the rest as given, a `..` after a name that isn't there
+ * taken lexically. A link's target is read from the link's directory as it
+ * is on disk, so a `..` is taken from where the links before it lead, as the
  * kernel takes it. Where realpath fails for any other reason, such as a
- * loop or a lack of permission, the whole path as path.resolve reads it.
+ * loop or a lack of permission, the whole path as path.resolve reads it, and
+ * `unresolved`, where given, takes the first such code.
  */
-async function realBeneath(given: string, links = 0): Promise<string> {
+async function realBeneath(given: string, links = 0, unresolved?: { code?: string }): Promise<string> {
   // A trailing separator, as a link to a directory is often written, names
   // the same place, but readlink would then follow the link it names.
   const { root } = parse(given);
@@ -365,14 +481,33 @@ async function realBeneath(given: string, links = 0): Promise<string> {
   } catch (err) {
     const code = errnoOf(err);
     const parent = dirname(absolute);
-    if ((code !== 'ENOENT' && code !== 'ENOTDIR') || links >= LINKS_FOLLOWED || parent === absolute) return resolve(absolute);
-    const place = await realBeneath(parent, links);
+    if ((code !== 'ENOENT' && code !== 'ENOTDIR') || links > LINKS_FOLLOWED || parent === absolute) {
+      if (unresolved) unresolved.code ??= links > LINKS_FOLLOWED ? 'ELOOP' : code ?? 'EIO';
+      return resolve(absolute);
+    }
+    const place = await realBeneath(parent, links, unresolved);
     const target = await readlink(absolute).catch(() => null);
-    if (target !== null) return realBeneath(isAbsolute(target) ? target : `${place}${sep}${target}`, links + 1);
+    if (target !== null) return realBeneath(isAbsolute(target) ? target : `${place}${sep}${target}`, links + 1, unresolved);
     return join(place, basename(absolute));
   }
 }
 
+/**
+ * A configured value as a refusal shows it: a number or a bigint as
+ * JavaScript writes it (JSON would say null for NaN, and throws for a
+ * bigint), anything else as JSON, or as String gives it where JSON can't,
+ * as for a list holding a bigint.
+ */
+function shownValue(value: unknown): string {
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'bigint') return `${value}n`;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
 function isContainedPath(root: string, candidate: string): boolean {
   if (candidate === root) return true;
   const normalizedRoot = root.endsWith(sep) ? root : root + sep;
@@ -826,6 +961,10 @@ export class WorkspaceModule implements Module {
   private otherMounts = new Map<string, NestedMountEntry[]>();
   /** Whether each mount's root folds case (foldsCase), where disk has it, as the last start read it. */
   private rootFoldsCase = new Map<string, boolean>();
+  /** Where the last start placed each mount's root (readNesting's `reals`). */
+  private placedRoots = new Map<string, string>();
+  /** Each directory above each mount's configured path, with where the last start found it on disk (readNesting's `above`). */
+  private placedAbove = new Map<string, Array<{ dir: string; real: string }>>();
   /**
    * Whether a file's mode is observed, taken in and applied (MountRuntime's
    * `modesObserved`): not on Windows, which reports no POSIX modes. A test
@@ -837,17 +976,49 @@ export class WorkspaceModule implements Module {
    *  mounts, so restoration must be second-callback-safe like watcher
    *  startup already is (issue #72). Cleared after application. */
   private savedState: WorkspaceModuleState | null = null;
+  /**
+   * The mounts configured direct that run as 'chronicle' this session, with
+   * the changes the store held there that disk lacked (chooseKinds), for
+   * ensureRunning to say once both halves of the lifecycle have run.
+   */
+  private notDirect = new Map<string, Array<{ path: string; what: string }>>();
 
   constructor(config: WorkspaceConfig) {
     for (const mount of config.mounts) {
       const cap: unknown = mount.walkCap;
       if (cap !== undefined && !(Number.isSafeInteger(cap) && (cap as number) > 0)) {
-        // Numbers as JavaScript writes them (JSON would say null for NaN), anything else as JSON.
-        const shown = typeof cap === 'number' ? String(cap) : typeof cap === 'bigint' ? `${cap}n` : JSON.stringify(cap) ?? String(cap);
         throw new Error(
-          `[workspace] Mount "${mount.name}": walkCap must be a positive integer no larger than ${Number.MAX_SAFE_INTEGER}, not ${shown}`,
+          `[workspace] Mount "${mount.name}": walkCap must be a positive integer no larger than ${Number.MAX_SAFE_INTEGER}, not ${shownValue(cap)}`,
         );
       }
+      const backend: unknown = mount.backend;
+      if (backend !== undefined && backend !== 'chronicle' && backend !== 'direct') {
+        throw new Error(`[workspace] Mount "${mount.name}": backend must be 'chronicle' or 'direct', not ${shownValue(backend)}`);
+      }
+      const refused = backend === 'direct' ? directRefusals(mount) : [];
+      if (refused.length > 0) {
+        throw new Error(`[workspace] Mount "${mount.name}" is direct, which reads disk as it is with no store, watcher or push: ${refused.join('; ')}`);
+      }
+      const include: unknown = mount.include;
+      if (include !== undefined) {
+        // A pattern the matcher can't read would match nothing, and take every
+        // file out of the mount unsaid (includePatternReadable).
+        if (!Array.isArray(include) || include.length === 0) {
+          throw new Error(
+            `[workspace] Mount "${mount.name}": include must be a non-empty list of names, "*.ext" globs or "dir/**" globs, not ${shownValue(include)}`,
+          );
+        }
+        // By index: an entry that is itself undefined, or a hole, is unreadable too.
+        const at = include.findIndex((p) => !includePatternReadable(p));
+        if (at >= 0) {
+          const unreadable: unknown = include[at];
+          throw new Error(
+            `[workspace] Mount "${mount.name}": include must be a non-empty list of names, "*.ext" globs or "dir/**" globs, `
+            + `with no "." or ".." segment${sep === '\\' ? ' and no "\\", which this platform reads as a separator' : ''}; `
+            + `${shownValue(unreadable)} is none of these`,
+          );
+        }
+      }
     }
     // Detect overlapping mount paths: a mount nested inside another is that
     // mount's directory, which the outer mount passes over in every pass,
@@ -890,23 +1061,34 @@ export class WorkspaceModule implements Module {
     // before the call, knowing no mount, and a later initStore starts clean.
     const mounts = new Map<string, MountState>();
     const intents = new Map<string, BranchIntents>();
+    // A direct mount's files never go into the store, so its states aren't
+    // made. One that ran as 'chronicle' before has them, and they're read
+    // below for what the store holds there that disk lacks.
+    const made = this.config.mounts.some((m) => m.backend === 'direct') ? new Set(store.listStates().map((s) => s.id)) : null;
 
     // Register tree states for each mount: the workspace tree, and the
     // branch-local intent that qualifies it.
     for (const mount of this.config.mounts) {
       const treeStateId = `workspace/${mount.name}/tree`;
       const intentTreeStateId = `workspace/${mount.name}/intent`;
-      for (const id of [treeStateId, intentTreeStateId]) {
-        ensureStateRegistered(store, {
-          id,
-          strategy: 'tree',
-          deltaSnapshotEvery: this.config.deltaSnapshotEvery ?? 50,
-          fullSnapshotEvery: this.config.fullSnapshotEvery ?? 10,
-        });
+      const direct = mount.backend === 'direct';
+      // A mount configured direct that ran as 'chronicle' runs direct only
+      // once chooseKinds finds nothing held there.
+      const ranStoreBacked = direct && made!.has(treeStateId) && made!.has(intentTreeStateId);
+      if (!direct) {
+        for (const id of [treeStateId, intentTreeStateId]) {
+          ensureStateRegistered(store, {
+            id,
+            strategy: 'tree',
+            deltaSnapshotEvery: this.config.deltaSnapshotEvery ?? 50,
+            fullSnapshotEvery: this.config.fullSnapshotEvery ?? 10,
+          });
+        }
       }
 
       mounts.set(mount.name, {
         config: mount,
+        direct: direct && !ranStoreBacked,
         treeStateId,
         intentTreeStateId,
         lastMaterializedSeq: 0,
@@ -916,7 +1098,9 @@ export class WorkspaceModule implements Module {
         watcherReadyAt: null,
         watcherError: null,
       });
-      intents.set(mount.name, new BranchIntents(store, intentTreeStateId));
+      if (!direct || ranStoreBacked) {
+        intents.set(mount.name, new BranchIntents(store, intentTreeStateId));
+      }
     }
 
     this.store = store;
@@ -924,14 +1108,53 @@ export class WorkspaceModule implements Module {
     for (const [name, intent] of intents) this.intents.set(name, intent);
 
     // What disk last agreed with, per mount and path: global records, so a
-    // branch switch never rewinds it.
+    // branch switch never rewinds it. A mount configured direct has its
+    // evidence read only where a 'chronicle' run left its states, for what
+    // the store holds there that disk lacks (chooseKinds); one that never ran
+    // so has none to read, and none is begun for it.
     this.agreement = new DiskAgreement(store, { modesObserved: () => this.modesObserved });
-    this.agreement.open(this.config.mounts.map((m) => ({ name: m.name, root: resolve(m.path) })));
+    this.agreement.open(this.config.mounts.filter((m) => intents.has(m.name)).map((m) => ({ name: m.name, root: resolve(m.path) })));
 
+    this.chooseKinds();
     this.applySavedState();
     this.ensureRunning();
   }
 
+  /**
+   * Whether each mount configured direct runs direct: not while the store
+   * holds changes there that disk lacks, on the branch selected then, so
+   * they stay in view (MountConfig.backend); it runs as 'chronicle' instead,
+   * and ensureRunning says so. Decided when initStore gives the store, and
+   * again at each start, which knows how the mounts nest, so a start that
+   * finds none held starts the mount direct. A path held more than one way
+   * is named for the last way set here.
+   */
+  private chooseKinds(): void {
+    // Every mount is decided before any is set, so a read of the store that
+    // throws leaves the decisions as they were.
+    const decided = new Map<string, Array<{ path: string; what: string }>>();
+    for (const [name, state] of this.mounts) {
+      if (state.config.backend !== 'direct') continue;
+      // One with no states from a 'chronicle' run holds nothing.
+      if (!this.intents.has(name)) {
+        decided.set(name, []);
+        continue;
+      }
+      const held = this.heldChanges(state);
+      const what = new Map<string, string>();
+      for (const path of held.owed) what.set(path, 'changed in the workspace');
+      for (const path of held.unreadable) what.set(path, UNREADABLE_INTENT);
+      for (const path of held.deletions) what.set(path, 'deleted in the workspace');
+      for (const path of held.conflicts) what.set(path, 'in conflict');
+      decided.set(name, [...what].sort(([a], [b]) => a.localeCompare(b)).map(([path, label]) => ({ path, what: label })));
+    }
+    this.notDirect = new Map();
+    for (const [name, held] of decided) {
+      this.mounts.get(name)!.direct = held.length === 0;
+      if (held.length > 0) this.notDirect.set(name, held);
+    }
+  }
+
   // ==========================================================================
   // Reconciliation plumbing
   // ==========================================================================
@@ -960,7 +1183,7 @@ export class WorkspaceModule implements Module {
    * A mount as observation reads it, with the root identity the workspace
    * recorded for it, if any: what a pass reads beneath (runtime), with
    * rootIdentity's, and what a disk read checks its root against (readRoot),
-   * with rootIdentityForRead's.
+   * with rootIdentityForRead's. A direct mount's has none (diskView).
    */
   private viewOf(mount: MountState, rootIdentity: MountView['rootIdentity']): MountView {
     return {
@@ -969,12 +1192,42 @@ export class WorkspaceModule implements Module {
       rootIdentity,
       followSymlinks: mount.config.followSymlinks === true,
       maxFileSize: mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE,
-      ignore: mount.config.ignore ?? [],
+      ignore: this.ignoreOf(mount),
+      ...(mount.config.include ? { include: mount.config.include } : {}),
       others: this.othersOf(mount.config.name),
       nested: this.nestedOf(mount.config.name),
     };
   }
 
+  /**
+   * A mount's ignore list: its config's, or, for a mount configured direct
+   * that names none, the direct kind's default (MountConfig.ignore), whichever
+   * kind it runs as this session, as its watch mode goes by its config
+   * (watchOf).
+   */
+  private ignoreOf(mount: MountState): string[] {
+    return mount.config.ignore ?? (mount.config.backend === 'direct' ? [...DIRECT_MOUNT_IGNORE] : []);
+  }
+
+  /**
+   * A direct mount as its tools read it: its view, with no root identity,
+   * since it promises what's at its root now and keeps no evidence to check
+   * that against (MountConfig.backend), and its root as realpath resolves it,
+   * or as given where that fails, as a pass's runtime takes it. The view
+   * reads beneath that root, so a walk, a listing and grep's reads judge
+   * and open their files beneath one root, however its configured path is
+   * repointed meanwhile. A read of one file goes through openContainedFile
+   * instead, which refuses it once its root is no longer the directory it
+   * checked.
+   */
+  private async diskView(mount: MountState): Promise<{ view: MountView; rootReal: string; moved: NestedMount[] | null }> {
+    const root = resolve(mount.config.path);
+    const rootReal = await realpath(root).catch(() => root);
+    const view = { ...this.viewOf(mount, undefined), root: rootReal };
+    const moved = await this.movedNesting(mount, rootReal);
+    return { view: moved === null ? view : { ...view, nested: moved, others: moved.map((n) => n.dir) }, rootReal, moved };
+  }
+
   /** The view reconciliation needs of a mount, refreshed per pass. */
   private async runtime(mount: MountState): Promise<MountRuntime> {
     const root = resolve(mount.config.path);
@@ -994,7 +1247,7 @@ export class WorkspaceModule implements Module {
       intents: this.intents.get(mount.config.name)!,
       readOnly: mount.config.mode === 'read-only',
       walkCap: mount.config.walkCap ?? WALK_CAP,
-      catchUpScan: (mount.config.watch ?? 'always') === 'always',
+      catchUpScan: watchOf(mount.config) === 'always',
       modesObserved: this.modesObserved,
     };
   }
@@ -1008,15 +1261,18 @@ export class WorkspaceModule implements Module {
    * under that spelling beside their own. So the start stops before a segment
    * spelled any other way, not there, or not a directory, and before a link,
    * which a walk of the whole mount doesn't go through either. It lists only
-   * directories it has checked lie inside the mount, and none the mount
-   * passes over by design, which the walk then answers for.
+   * directories it has checked lie inside the mount, and, on a 'chronicle'
+   * mount, none it passes over by design, which the walk then answers for.
+   * A direct mount walks a path its tools name whatever its ignore list or
+   * an editor's file name covers there (MountConfig.ignore), so there it
+   * lists such directories too, and only another mount's it doesn't.
    */
   private async walkStart(mount: MountState, base: string, beneath: string): Promise<string> {
     if (beneath === '') return base;
-    const { view, rootReal } = await this.runtime(mount);
+    const { view, rootReal } = mount.direct ? await this.diskView(mount) : await this.runtime(mount);
     let start = base;
     for (const segment of beneath.split('/')) {
-      if (start !== '' && passedOverAt(start, view.ignore, view.others) !== undefined) break;
+      if (start !== '' && (mount.direct ? inOtherMount(start, view.others) : passedOverAt(start, view.ignore, view.others) !== undefined)) break;
       const here = await checkDir(view, rootReal, start);
       if (here.kind !== 'checked') break;
       const entry = (await readdir(here.dir.real, { withFileTypes: true }).catch(() => [])).find((e) => e.name === segment);
@@ -1048,10 +1304,23 @@ export class WorkspaceModule implements Module {
   /** One store→disk push; the caller holds the mount's turn. */
   private async pushUnlocked(mount: MountState, paths: string[], opts: PushOptions = {}): Promise<PushResult> {
     const watcher = this.watchers.get(mount.config.name);
-    return pushPaths(this.getStore(), this.agreementOrThrow(), await this.runtime(mount), paths, {
+    // A path outside the mount's include never reaches disk, even when the
+    // workspace's history holds it from before the include. It's skipped,
+    // and a materialize counts it, with the reason.
+    const inside: string[] = [];
+    const outside: string[] = [];
+    for (const p of paths) {
+      // A key no spelling names, such as an earlier version's `a//b.txt`,
+      // isn't the mount's either, and isn't the include's to report.
+      if (!parsedSpelling(p)) continue;
+      (insideMount(p, mount.config.include) ? inside : outside).push(p);
+    }
+    const pushed = await pushPaths(this.getStore(), this.agreementOrThrow(), await this.runtime(mount), inside, {
       ...opts,
       beforeEffect: (p) => watcher?.suppress(p),
     });
+    for (const path of outside) pushed.skipped.push({ path, reason: OUTSIDE_INCLUDE });
+    return pushed;
   }
 
   async start(ctx: ModuleContext): Promise<void> {
@@ -1062,12 +1331,14 @@ export class WorkspaceModule implements Module {
     // before they're known. A stop begun meanwhile stands, and this start then
     // sets nothing.
     const stops = this.stopsBegun;
-    const { nesting, reals } = await this.readNesting();
+    const { nesting, reals, above } = await this.readNesting();
     const rootFoldsCase = new Map<string, boolean>();
     for (const mount of this.config.mounts) rootFoldsCase.set(mount.name, await foldsCase(reals.get(mount.name)!));
     if (this.stopsBegun !== stops) return;
     this.otherMounts = nesting;
     this.rootFoldsCase = rootFoldsCase;
+    this.placedRoots = reals;
+    this.placedAbove = above;
 
     this.ctx = ctx;
     this.stopped = false;
@@ -1207,16 +1478,19 @@ export class WorkspaceModule implements Module {
   /**
    * Start chokidar watchers and emit workspace:mounted events.
    * Idempotent: safe to call from both start() and initStore(), fires once
-   * per mount regardless of which runs second.
+   * per mount regardless of which runs second. Once both have run, it
+   * decides again which mounts configured direct run direct, now that the
+   * mounts' nesting is known, and says which don't, once for this start.
    */
   private ensureRunning(): void {
     if (!this.ctx || this.mounts.size === 0) return;
+    this.chooseKinds();
+    if (this.notDirect.size > 0) this.sayNotDirect();
 
     for (const [name, mount] of this.mounts) {
       if (this.watchers.has(name)) continue;
 
-      const watchMode = mount.config.watch ?? 'always';
-      if (watchMode === 'always') {
+      if (watchOf(mount.config) === 'always') {
         // Chokidar is started with ignoreInitial:true, so changes made while
         // the session was down would be invisible. A catch-up pass takes them
         // in under the three-way rule: only real differences produce tree
@@ -1300,6 +1574,51 @@ export class WorkspaceModule implements Module {
     }
   }
 
+  /**
+   * Say, for whoever runs the host, which mounts configured direct run as
+   * 'chronicle' this session (chooseKinds), what the workspace holds there
+   * that keeps them so, and the two ways to start one direct: on stderr,
+   * and as one ops alert for them all (the framework's failures log, its
+   * `ops:alert` trace and, where one is set, its webhook, which posts one
+   * alert of a kind per cooldown and keeps only the start and end of a long
+   * one). So the words of fixed length, what's happening and the ways out,
+   * come first, and the mounts and what they hold after them.
+   */
+  private sayNotDirect(): void {
+    const mounts = [...this.notDirect];
+    const one = mounts.length === 1;
+    // An intent the workspace can't read may hold a change or may not, so
+    // it's counted as what it is.
+    const counted = (paths: Array<{ what: string }>) => {
+      const u = paths.filter((h) => h.what === UNREADABLE_INTENT).length;
+      const c = paths.length - u;
+      return [
+        c > 0 ? `${c} change${c === 1 ? '' : 's'} that disk lacks` : '',
+        u > 0 ? `${u} intent${u === 1 ? '' : 's'} it can't read` : '',
+      ].filter((part) => part !== '').join(' and ');
+    };
+    const each = mounts.map(([name, paths]) => `"${name}" (${counted(paths)})`);
+    const which = one
+      ? `Mount "${mounts[0]![0]}" holds ${counted(mounts[0]![1])}`
+      : `Mounts ${each.slice(0, -1).join(', ')} and ${each[each.length - 1]} hold`;
+    const held = mounts.flatMap(([name, paths]) => paths.map((h) => `"${name}/${h.path}" (${h.what})`));
+    // Materialize settles an intent the workspace can't read only where the
+    // workspace holds a copy there, and says nothing of one it doesn't, so
+    // the ways out say what does wherever one is held, past the ten paths
+    // named too.
+    const intents = mounts.some(([, paths]) => paths.some((h) => h.what === UNREADABLE_INTENT))
+      ? "Sync the path of an intent it can't read. "
+      : '';
+    const message = (one
+      ? "A mount configured direct runs as 'chronicle' this session. To start it direct, settle each held change, then start it again: "
+      : "Mounts configured direct run as 'chronicle' this session. To start a mount direct, settle each change held at it, then start it again: ") +
+      "sync its path to take disk's copy, or configure the mount 'chronicle' and read-write, materialize it, " +
+      `follow the answer, and restore its direct config. ${intents}${which}: ${held.slice(0, 10).join(', ')}` +
+      `${held.length > 10 ? `, and ${held.length - 10} more` : ''}.`;
+    console.warn(`[workspace] ${message}`);
+    this.ctx?.notifyOps?.('workspace-mount-not-direct', 'framework', message, { held: Object.fromEntries(mounts.map(([name, paths]) => [name, paths.length])) });
+  }
+
   private async initialScan(mountName: string): Promise<void> {
     const store = this.store;
     const mount = this.mounts.get(mountName);
@@ -1367,12 +1686,15 @@ export class WorkspaceModule implements Module {
     this.ctx = null;
   }
 
-  /** Mount names + modes, for peer callers (framework spill/journal paths)
-   *  that need a writable mount without reaching into private state. */
-  getMounts(): Array<{ name: string; mode: 'read-write' | 'read-only' }> {
+  /** Mount names + modes, and each mount's include where it sets one, for
+   *  peer callers (framework spill/journal paths) that need a mount for files
+   *  of their own, the first writable one without an include
+   *  (firstWritableMountName), without reaching into private state. */
+  getMounts(): Array<{ name: string; mode: 'read-write' | 'read-only'; include?: readonly string[] }> {
     return [...this.mounts.values()].map((m) => ({
       name: m.config.name,
       mode: m.config.mode === 'read-only' ? 'read-only' : 'read-write',
+      ...(m.config.include ? { include: [...m.config.include] } : {}),
     }));
   }
 
@@ -1381,6 +1703,19 @@ export class WorkspaceModule implements Module {
   // ==========================================================================
 
   getTools(): ToolDefinition[] {
+    // Where a mount runs direct, four descriptions say what that changes.
+    // A host with none keeps them as they were, and its residents' caches.
+    const direct = [...this.mounts.values()].some((m) => m.direct);
+    const lsDirect = direct
+      ? ' A direct mount (ls without a path says which, with its ignore list) lists disk\'s files as they are now: each with '
+        + 'its size and no state, or a note where the mount doesn\'t take it. A path its ignore list covers is listed when you name it.'
+      : '';
+    const grepDirect = direct
+      ? ' On a direct mount, grep searches disk\'s files as they are now (version disk), and lists as skipped, with why, '
+        + 'those it doesn\'t: binary, over the size limit, or not read, such as a link the mount doesn\'t follow.'
+      : '';
+    const globDirect = direct ? ' On a direct mount, a match carries its size, or a note where the mount doesn\'t take it, and no state.' : '';
+    const syncDirect = direct ? ' A direct mount is listed under `skipped`: its tools read disk as it is, so there\'s nothing to take in.' : '';
     return [
       {
         name: 'read',
@@ -1426,18 +1761,62 @@ export class WorkspaceModule implements Module {
       },
       {
         name: 'edit',
-        description: 'Edit a file by replacing a substring. The oldString must be unique unless replaceAll is true.',
+        description: 'Edit a file by replacing exact text. oldString must occur exactly once, or with replaceAll at least once, '
+          + "and every occurrence is replaced; occurrences that overlap count, but can't each be replaced. "
+          + 'A miss shows the closest region it finds, numbered, and a count that differs shows the lines that matched. '
+          + 'CRLF line ends are matched with LF text and kept, as is a BOM. As second chances, straight and curly quotes match as equal, '
+          + "and an oldString carrying the file's BOM at its start or a line's CR at its end, as a character page shows them, matches without them, "
+          + 'its newString read the same way. '
+          + "Only the replaced text changes, and the new text's line ends take those of the text it replaces. "
+          + 'A change disk made to the file is taken in first, and the answer says so. '
+          + 'The answer shows the changed region, numbered, a long line from shortly before the change on it, as its length allows. '
+          + 'For several edits at once, in one file or across files, applied all or none, use edit_many.',
         inputSchema: {
           type: 'object' as const,
           properties: {
             path: { type: 'string', description: 'File path (mount-prefixed)' },
-            oldString: { type: 'string', description: 'String to find' },
-            newString: { type: 'string', description: 'Replacement string' },
-            replaceAll: { type: 'boolean', description: 'Replace all occurrences (default: false)' },
+            oldString: { type: 'string', description: 'Exact text to replace, including whitespace and indentation' },
+            newString: { type: 'string', description: 'Replacement text' },
+            replaceAll: { type: 'boolean', description: 'Replace every occurrence (default: false)' },
           },
           required: ['path', 'oldString', 'newString'],
         },
       },
+      {
+        name: 'edit_many',
+        description: 'Apply several exact edits at once, in one file or across files of one mount, all or none: no edit is stored unless every edit applies. '
+          + "Each edit's oldString must occur in its file exactly `occurrences` times (1 when left out), and every one is replaced; "
+          + "occurrences that overlap count, but can't each be replaced. "
+          + "Each edit is matched in its file as this call reads it, never in another edit's result, so the list's order doesn't matter, "
+          + "and two edits' matches may touch but not overlap. Matching is edit's. "
+          + "A refusal names the problems it finds, each by its edit's number in the list (from 1). "
+          + 'All or none holds in the workspace: on a mount that writes to disk, disk can still refuse a file, '
+          + "and the answer then says every edit is stored and names each file disk refused, with its push's reason. "
+          + "The answer shows each edit's first changed region, numbered, a long line from shortly before each change on it, as its length allows.",
+        inputSchema: {
+          type: 'object' as const,
+          properties: {
+            edits: {
+              type: 'array',
+              description: "The edits, each matched in its file as this call reads it, never in another edit's result",
+              items: {
+                type: 'object',
+                properties: {
+                  path: { type: 'string', description: 'File path (mount-prefixed); every edit names a file of the same mount' },
+                  oldString: { type: 'string', description: 'Exact text to replace, as the file holds it before this call' },
+                  newString: { type: 'string', description: 'Replacement text' },
+                  occurrences: {
+                    type: 'integer',
+                    description: 'How many times oldString occurs in the file (default: 1); every one is replaced, and any other count is refused',
+                  },
+                },
+                required: ['path', 'oldString', 'newString'],
+              },
+            },
+          },
+          required: ['edits'],
+        },
+      },
       {
         name: 'delete',
         description: 'Delete a file from the workspace. On a mount without autoMaterialize the disk copy stays, '
@@ -1461,18 +1840,18 @@ export class WorkspaceModule implements Module {
           + 'interrupted) — sync the path to take disk, or materialize that path with force to take the workspace, '
           + 'with applyDeletions too where the workspace deleted it; '
           + 'disk-missing-provenance-unknown; unverified (disk could not be checked). `incomplete` names regions '
-          + 'the listing could not see.',
+          + 'the listing could not see.' + lsDirect,
         inputSchema: {
           type: 'object' as const,
           properties: {
-            path: { type: 'string', description: 'Directory path (mount-prefixed, optional)' },
+            path: { type: 'string', description: 'Directory path (mount-prefixed, optional; without it, the mounts are listed, each with its include where it has one)' },
             recursive: { type: 'boolean', description: 'List recursively (default: false)' },
           },
         },
       },
       {
         name: 'glob',
-        description: 'Find files matching a glob pattern, checked against disk first; each match carries its state, as ls describes.',
+        description: 'Find files matching a glob pattern, checked against disk first; each match carries its state, as ls describes.' + globDirect,
         inputSchema: {
           type: 'object' as const,
           properties: {
@@ -1488,7 +1867,7 @@ export class WorkspaceModule implements Module {
           + 'which version matched: the workspace\'s (with its state); the disk version kept with a conflict '
           + '(conflicting-disk); or, once disk has changed since the conflict was recorded, that recorded version '
           + '(recorded-disk). Disk versions it could not search are listed as skipped: disk-only files (binary or '
-          + 'over the size limit), and a conflict\'s disk version that is binary, oversize, or newer than the one recorded.',
+          + 'over the size limit), and a conflict\'s disk version that is binary, oversize, or newer than the one recorded.' + grepDirect,
         inputSchema: {
           type: 'object' as const,
           properties: {
@@ -1514,7 +1893,9 @@ export class WorkspaceModule implements Module {
       {
         name: 'materialize',
         description: 'Write workspace files to the real filesystem. Use after writing/editing to push changes to disk. '
-          + 'Never deletes disk files unless applyDeletions is given; lists workspace deletions it left on disk.',
+          + 'Never deletes disk files unless applyDeletions is given; lists workspace deletions it left on disk. '
+          + 'On a mount with an include, what the include doesn\'t cover is never written, and one naming a '
+          + 'directory counts what it left beneath it under `passedOver`, by mount and reason, without naming it.',
         inputSchema: {
           type: 'object' as const,
           properties: {
@@ -1546,15 +1927,17 @@ export class WorkspaceModule implements Module {
           + 'reported nowhere else is counted under `passedOver`, by mount and reason: another mount\'s '
           + 'directory nested in this one, entries the mount\'s ignore list covers, and entries with an '
           + 'editor\'s swap or backup file name (`.name.swp` and `.name.swx` as the whole name, names ending '
-          + 'in `~` or in `.subl…tmp`), that hold nothing the workspace tracks (such a directory counts once, '
-          + 'with what lies beneath it). So a '
+          + 'in `~` or in `.subl…tmp`), each holding nothing the workspace tracks (such a directory counts '
+          + 'once, with what lies beneath it); and files and links outside the mount\'s include, a link '
+          + 'counted as "a symlink, not walked" instead where it leads to a directory on a mount that follows '
+          + 'symlinks, and wherever it leads on one that doesn\'t. So a '
           + 'total of 0, with no conflicts and nothing under `passedOver`, `incomplete` or `skipped`, means the '
           + 'sync looked everywhere and nothing had changed. A path the mount ignores, or an editor\'s file, is '
           + 'synced when you name it, and listed under `ignored`: a sync without a path passes over it. A path '
           + 'in another mount\'s directory isn\'t synced even when you name it: use the mount that holds it. Naming '
           + 'an ignored directory sets aside the patterns that cover it or a directory above it; one that '
           + 'covers only something inside it still applies, and what it covers is passed over, as are editors\' '
-          + 'files inside it.',
+          + 'files inside it.' + syncDirect,
         inputSchema: {
           type: 'object' as const,
           properties: {
@@ -1587,7 +1970,7 @@ export class WorkspaceModule implements Module {
     const mountName = slash < 0 ? path : path.slice(0, slash);
     const mount = this.config.mounts.find(m => m.name === mountName);
     if (!mount) throw new Error(`Unknown mount: "${mountName}"`);
-    // Against the resolved root, as parsePath judges it.
+    // Against the resolved root, as parsePathAsGiven's traversal guard judges it.
     const root = resolve(mount.path);
     const resolved = resolve(root, slash < 0 ? '' : path.slice(slash + 1));
     if (!isContainedPath(root, resolved)) throw new Error(`Path traversal detected: "${path}"`);
@@ -1645,16 +2028,18 @@ export class WorkspaceModule implements Module {
       const input = call.input as Record<string, unknown>;
       const generated = typeof input?.path === 'string' ? this.findGeneratedTextFile(input.path) : undefined;
       if (generated) {
-        if (call.callerAgentName !== generated.agentName) return {success:false,isError:true,error:'Generated file belongs to another agent'};
-        if (call.name !== 'read') return {success:false,isError:true,error:'Generated file is read-only; edit the presentation configuration instead'};
-        return await this.handleRead(input as unknown as ReadInput, generated.read());
+        if (call.name === 'read' && call.callerAgentName === generated.agentName) {
+          return await this.handleRead(input as unknown as ReadInput, generated.read());
+        }
+        return { success: false, isError: true, error: this.generatedFileRefusal(generated, call.callerAgentName) };
       }
 
       switch (call.name) {
         case 'read': return await this.handleRead(input as unknown as ReadInput);
         case 'read_image': return await this.handleReadImage(input as unknown as ReadImageInput);
         case 'write': return await this.handleWrite(input as unknown as WriteInput);
-        case 'edit': return await this.handleEdit(input as unknown as EditInput);
+        case 'edit': return await this.handleEdit(input as unknown as EditInput, call.resultMaxChars);
+        case 'edit_many': return await this.handleEditMany(input as unknown as EditManyInput, call.resultMaxChars, call.callerAgentName);
         case 'delete': return await this.handleDelete(input as unknown as DeleteInput);
         case 'ls': return await this.handleLs(input as unknown as LsInput);
         case 'glob': return await this.handleGlob(input as unknown as GlobInput);
@@ -1663,7 +2048,7 @@ export class WorkspaceModule implements Module {
         case 'materialize': return await this.handleMaterialize(input as unknown as MaterializeInput);
         case 'sync': return await this.handleSync(input as unknown as SyncInput);
         default:
-          return { success: false, error: `Unknown tool: ${call.name}`, isError: true };
+          return { success: false, error: `Unknown tool: ${call.name}, so nothing was done`, isError: true };
       }
     } catch (err) {
       return { success: false, error: err instanceof Error ? err.message : String(err), isError: true };
@@ -1742,8 +2127,11 @@ export class WorkspaceModule implements Module {
 
   /**
    * Resolve a mount-prefixed path (e.g. "tickets/2026-04-22-foo.md") to its
-   * absolute filesystem path. Returns null if the mount is unknown or the
-   * resolved path escapes the mount root.
+   * absolute filesystem path. Returns null if the mount is unknown or
+   * doesn't hold the path: one that leaves the mount's directory, lies in
+   * another mount's directory nested in it, or falls outside its include, or
+   * one that can't name a file of it, with a separator right after the
+   * mount's name or a lone UTF-16 surrogate.
    *
    * **Lexical containment only.** The guard reasons about `..` segments in the
    * path string; it knows nothing about what is on disk. A symlink inside the
@@ -1752,15 +2140,26 @@ export class WorkspaceModule implements Module {
    * path for resolution-only purposes (write targets, nonexistent paths,
    * display); for reading file content, use {@link readFileFromDisk}, which
    * enforces the mount's `followSymlinks` policy and canonical containment.
+   * It judges other mounts' directories by where the last start placed them,
+   * so for a direct mount whose root has moved since, it can differ from
+   * `readFileFromDisk`, which takes the nesting where the root lies now
+   * (movedNesting), about which paths lie in another mount's directory.
    *
    * @deprecated for direct filesystem reads — call `readFileFromDisk()`.
    */
   resolveAbsolutePath(mountPrefixedPath: string): string | null {
     try {
-      // Synchronous, so the path as given: it reaches the same file, and
-      // the nested-mount check matches it as configured or as disk spells
-      // the nested mount's directory (readNesting).
-      const { mount, relativePath } = this.refuseNested({ ...this.parsePathAsGiven(mountPrefixedPath), path: mountPrefixedPath });
+      // Synchronous, so the path as given. The nested-mount check takes it
+      // in each spelling readNesting knows for the nested mount's directory,
+      // or in any spelling a disk that folds names may fold to one of them,
+      // erring toward that mount (holderOf's asGiven, beginsWithDir). The
+      // include judges it as given, so on a disk that
+      // folds names a covered name whose file disk spells otherwise returns
+      // that file's path, which the tools refuse, and a covered file named in
+      // another case is null, which the tools read. A path the mount doesn't
+      // hold, outside its include or in another mount's directory nested in
+      // it, is null, as for a path that leaves the mount's directory.
+      const { mount, relativePath } = this.refuseNotHeld({ ...this.parsePathAsGiven(mountPrefixedPath), path: mountPrefixedPath }, mountPrefixedPath, true);
       return resolve(mount.config.path, relativePath);
     } catch {
       return null;
@@ -1783,10 +2182,13 @@ export class WorkspaceModule implements Module {
    * (agent-framework #277).
    *
    * A write whose tree entry is set but that then fails returns success
-   * false with `data: { inChronicle: true }`: its copy on disk was refused, or
-   * something after the entry (recording its intent, the event, the push)
-   * threw. The workspace's tools read the file from the tree, so it is there
-   * for them, on the branch that was current when the entry was set.
+   * false with `data: { inChronicle: true }`: its copy on disk was refused,
+   * the store failed after recording the entry, which skips the push where
+   * the mount pushes, or something after the entry (recording its intent,
+   * the event, the push) threw. The workspace's tools read the file from the
+   * tree, so it is there for them, on the branch that was current when the
+   * entry was set. A set that threw and couldn't be read back throws, saying
+   * that whether the entry is set isn't known.
    */
   async writeBinary(
     mountPrefixedPath: string,
@@ -1844,7 +2246,12 @@ export class WorkspaceModule implements Module {
           : `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${answer.refused}.`;
       } catch (error) {
         if (!committed) throw error;
-        failure = `Stored "${mountPrefixedPath}" in Chronicle, but the rest of the write failed: ${error instanceof Error ? error.message : String(error)}.`;
+        // As write words it: a store that failed after recording the file
+        // skipped its push, so on a mount that pushes, disk lacks it.
+        failure = error instanceof StoredThenFailed
+          ? `Stored "${mountPrefixedPath}" in Chronicle, but the store failed after recording it: ${error.message}.`
+            + (error.pushes ? " Its push to disk didn't run, so disk lacks the change until a materialize of the path writes it." : '')
+          : `Stored "${mountPrefixedPath}" in Chronicle, but the rest of the write failed: ${error instanceof Error ? error.message : String(error)}.`;
       }
       if (failure !== null) {
         // The file is in the Chronicle tree, where the workspace's tools read
@@ -1861,8 +2268,10 @@ export class WorkspaceModule implements Module {
 
   /**
    * Read a file's raw bytes from a mount (through the Chronicle tree, synced
-   * first like the `read` tool). Public API for the framework's synthesized
-   * `read_image` tool and other peer callers that need binary content.
+   * first like the `read` tool; on a direct mount, from disk as
+   * readBinaryFromDisk reads it, at most the mount's `maxFileSize`). Public
+   * API for the framework's synthesized `read_image` tool and other peer
+   * callers that need binary content.
    */
   async readBinary(
     mountPrefixedPath: string,
@@ -1881,11 +2290,13 @@ export class WorkspaceModule implements Module {
     } catch (error) {
       return { error: error instanceof Error ? error.message : String(error) };
     }
+    // A direct mount's bytes are disk's, as read takes them, at most its size limit.
+    if (mount.direct) return this.bytesFromDisk(mount, relativePath, mountPrefixedPath, mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE);
     const store = this.getStore();
     return this.withMount(mount, async () => {
-      await this.ensureSynced(mount, relativePath);
+      const { report, undecided } = await this.ensureSynced(mount, relativePath);
       const entry = store.treeGet(mount.treeStateId, relativePath);
-      if (!entry) return { error: `File not found: ${mountPrefixedPath}` };
+      if (!entry) return { error: undecided !== null ? this.notCheckedYet(mountPrefixedPath, undecided) : this.notInWorkspace(mountPrefixedPath, report) };
       const blob = store.getBlob(entry.blobHash);
       if (!blob) return { error: `Blob not found for: ${mountPrefixedPath}` };
       return { data: blob };
@@ -1926,8 +2337,17 @@ export class WorkspaceModule implements Module {
     } catch (error) {
       return { error: error instanceof Error ? error.message : String(error) };
     }
-    const absolutePath = resolve(mount.config.path, relativePath);
-    const maxBytes = opts.maxBytes;
+    const read = await this.bytesFromDisk(mount, relativePath, mountPrefixedPath, opts.maxBytes);
+    return 'error' in read ? read : { data: read.data, absolutePath: resolve(mount.config.path, relativePath) };
+  }
+
+  /** A file's bytes as readBinaryFromDisk reads them, once its path is parsed. */
+  private async bytesFromDisk(
+    mount: MountState,
+    relativePath: string,
+    mountPrefixedPath: string,
+    maxBytes: number | undefined,
+  ): Promise<{ data: Buffer } | { error: string }> {
     let tooLarge: string | undefined;
     try {
       const { handle, fileStat } = await this.openContainedFile(mount, relativePath, mountPrefixedPath, (fileStat) => {
@@ -1937,14 +2357,14 @@ export class WorkspaceModule implements Module {
         }
       });
       try {
-        if (maxBytes === undefined) return { data: await handle.readFile(), absolutePath };
+        if (maxBytes === undefined) return { data: await handle.readFile() };
         // No more than maxBytes is loaded: a file grown past it since the
         // fstat above is refused here, as one already over it was there. Its
         // size is an fstat's after the read, and at least one more than the
         // bytes kept, so the refusal's size is always past maxBytes.
         const { bytes, more } = await readPrefix(handle, maxBytes, fileStat.size);
         if (more) return { error: `File too large: ${Math.max((await handle.stat()).size, bytes.length + 1)} > ${maxBytes} bytes` };
-        return { data: bytes, absolutePath };
+        return { data: bytes };
       } finally {
         await handle.close();
       }
@@ -1987,9 +2407,11 @@ export class WorkspaceModule implements Module {
    * as configured still names it as configured (resolveAbsolutePath). A
    * directory not on disk keeps the spellings the roots give alone. Each
    * mount's real root comes back beside the nesting (`reals`), for what
-   * start reads there.
+   * start reads there, and each directory above each configured path with
+   * where it lies on disk (`above`), for a direct mount whose root moves
+   * (movedNesting).
    */
-  private async readNesting(): Promise<{ nesting: Map<string, NestedMountEntry[]>; reals: Map<string, string> }> {
+  private async readNesting(): Promise<{ nesting: Map<string, NestedMountEntry[]>; reals: Map<string, string>; above: Map<string, Array<{ dir: string; real: string }>> }> {
     const reals = new Map<string, string>();
     // Each directory above a mount's configured path, with where it lies on
     // disk, so a path that reaches another mount's root through a link, as
@@ -1999,10 +2421,7 @@ export class WorkspaceModule implements Module {
       const given = resolve(mount.path);
       reals.set(mount.name, await realBeneath(given));
       const dirs: Array<{ dir: string; real: string }> = [];
-      for (let dir = dirname(given); ; dir = dirname(dir)) {
-        dirs.push({ dir, real: await realBeneath(dir) });
-        if (dirname(dir) === dir) break;
-      }
+      for (const dir of ancestorsOf(given)) dirs.push({ dir, real: await realBeneath(dir) });
       above.set(mount.name, dirs);
     }
     const nesting = new Map<string, NestedMountEntry[]>();
@@ -2012,23 +2431,9 @@ export class WorkspaceModule implements Module {
       for (const inner of this.config.mounts) {
         if (outer === inner) continue;
         const real = reals.get(inner.name)!;
-        const innerPath = resolve(inner.path);
-        const configured = nestedDir(outerPath, innerPath);
-        const fromRoots: Array<{ dir: string; root: string }> = [];
-        // Its directory as configured, read against this mount's root as
-        // configured and from each directory above it that is this mount's
-        // root on disk, and its real root against this mount's.
-        const throughRoot = above.get(inner.name)!.filter((a) => a.real === outerReal).map((a) => nestedDir(a.dir, innerPath));
-        for (const dir of [configured, ...throughRoot, nestedDir(outerReal, real)]) {
-          if (dir !== undefined && !fromRoots.some((s) => s.dir === dir)) fromRoots.push({ dir, root: join(outerPath, ...dir.split('/')) });
-        }
-        if (fromRoots.length === 0) continue;
-        const spellings = [...fromRoots];
-        for (const found of fromRoots) {
-          const dir = await diskSpelling(outerPath, found.dir);
-          if (!spellings.some((s) => s.dir === dir)) spellings.push({ dir, root: join(outerPath, ...dir.split('/')) });
-        }
-        const claims = !isContainedPath(real, outerReal);
+        const at = await placementOf(outerPath, outerReal, resolve(inner.path), real, above.get(inner.name)!, outerPath);
+        if (at === undefined) continue;
+        const { configured, fromRoots, spellings, claims } = at;
         nesting.set(outer.name, [...(nesting.get(outer.name) ?? []), { name: inner.name, ...(claims ? { real } : {}), fromRoots, spellings }]);
         const placed = fromRoots.filter((s) => s.dir !== configured);
         if (placed.length > 0) {
@@ -2039,12 +2444,118 @@ export class WorkspaceModule implements Module {
         }
       }
     }
-    return { nesting, reals };
+    return { nesting, reals, above };
   }
 
-  /** The mounts nested in `mountName`, by directory, name and real root where it has one (MountView's `nested`), in each spelling known. */
+  /**
+   * The mounts nested in `mountName`, by directory, name, real root where it
+   * has one, and include (MountView's `nested`), in each spelling known.
+   */
   private nestedOf(mountName: string): NestedMount[] {
-    return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => ({ dir: s.dir, name: o.name, real: o.real })));
+    return (this.otherMounts.get(mountName) ?? []).flatMap((o) =>
+      o.spellings.map((s) => ({ dir: s.dir, name: o.name, real: o.real, include: this.mounts.get(o.name)?.config.include })));
+  }
+
+  /**
+   * The mounts nested in `mount` as a call of it that resolved its root to
+   * `rootReal` sees them: movedNesting where that differs from where the
+   * last start placed it, the start's placement (nestedOf) otherwise.
+   */
+  private async nestedFor(mount: MountState, rootReal: string): Promise<NestedMount[]> {
+    return (await this.movedNesting(mount, rootReal)) ?? this.nestedOf(mount.config.name);
+  }
+
+  /**
+   * The mounts nested in a direct mount whose root a check resolved to
+   * `rootReal`, where that's elsewhere than the last start placed it, as when
+   * a link it's configured through is repointed; null where the start's
+   * placement holds, or where nothing is at `rootReal`: there the parse's
+   * checks keep the start's placement, and a read says the root is gone. A
+   * direct mount reads beneath whatever directory is at its root, so a check
+   * judges which mount a path is by the root it resolved. A tool's parse
+   * resolves it once, and its respelling and its checks of the path it's
+   * given (parseFilePath's, refusesAsOutside, grep's) read disk beneath that
+   * root and judge by the nesting there. A read and a walk each resolve it
+   * for themselves, and judge the include and the nesting again beneath it.
+   * So a root repointed during a call can change which answer or refusal a
+   * path gets, but nothing a read or a walk serves is a file the include
+   * leaves out, nothing a walk serves lies in another mount's directory as
+   * its own nesting places it, and nothing a read serves lies in the
+   * directory of a mount its own nesting claims by real root. Whoever writes
+   * the disk can race a read in two ways, as a rename during a call can on
+   * any mount. On a disk that folds names, a read judges the include by the
+   * path as its parse spelled it, so a root repointed between the two can
+   * have it serve a file the new root spells otherwise (sameLevels). And a
+   * mount nested by its directories alone, since its real root holds this
+   * one, is judged by the parse's nesting, so a root repointed between a
+   * read's parse and its open can have it serve a path in that mount's
+   * directory. Each mount is placed as a start places it (placementOf), from
+   * where its real root and the directories above its configured path lie on
+   * disk. For a mount configured at this mount's own path or beneath it,
+   * that's where they lie now: beneath `rootReal` where they lie beneath this
+   * mount's path, and the directories above this mount's path as resolving
+   * that path finds them. For any other mount, it's where the last start
+   * found them. Each carries its own include, as nestedOf gives it. It
+   * resolves nothing but the directories on this mount's own configured path
+   * and those beneath its root, so a share elsewhere that doesn't answer
+   * holds only its own calls, unless such a directory is a link into it,
+   * where that mount's files lie. What it leaves to the next start: a mount
+   * configured elsewhere whose own root has moved since, as when a link on
+   * its configured path is repointed, this mount's own reached through
+   * another link among them, that mount's spellings through other links, and
+   * the other mounts' own placements, so a direct root moved into another
+   * mount's directory is that mount's too, as a nested mount's root moved
+   * while running stays placed.
+   */
+  private async movedNesting(mount: MountState, rootReal: string): Promise<NestedMount[] | null> {
+    // One start's placements, whatever a start in the meantime sets.
+    const { placedRoots, placedAbove } = this;
+    const placed = placedRoots.get(mount.config.name);
+    if (!mount.direct || placed === undefined || placed === rootReal) return null;
+    const there = await stat(rootReal).then(() => true, (err: unknown) => {
+      const code = errnoOf(err);
+      return code !== 'ENOENT' && code !== 'ENOTDIR';
+    });
+    if (!there) return null;
+    const outerPath = resolve(mount.config.path);
+    const nested: NestedMount[] = [];
+    // The directories above this mount's own path, as they lie on disk now,
+    // resolved as resolving the path itself does.
+    let ownAbove: Array<{ dir: string; real: string }> | undefined;
+    const aboveOwn = async () => ownAbove ??= await Promise.all(ancestorsOf(outerPath).map(async (dir) => ({ dir, real: await realBeneath(dir) })));
+    for (const inner of this.config.mounts) {
+      if (inner.name === mount.config.name) continue;
+      const innerPath = resolve(inner.path);
+      const configured = nestedDir(outerPath, innerPath);
+      let real: string | undefined;
+      let above: ReadonlyArray<{ dir: string; real: string }>;
+      if (configured !== undefined || innerPath === outerPath) {
+        // A mount configured on this mount's own path, or beneath it, lies
+        // where that path now leads: its real root, and each directory above
+        // it, resolved now, beneath this root where they lie beneath it.
+        const segments = configured?.split('/') ?? [];
+        real = await realBeneath(join(rootReal, ...segments));
+        const beneath: Array<{ dir: string; real: string }> = [];
+        for (let i = segments.length - 1; i >= 1; i--) {
+          beneath.push({ dir: join(outerPath, ...segments.slice(0, i)), real: await realBeneath(join(rootReal, ...segments.slice(0, i))) });
+        }
+        // This mount's own path, which is the root, would add only the
+        // configured directory, which placementOf adds anyway.
+        above = [...beneath, ...await aboveOwn()];
+      } else {
+        // Any other mount lies where the last start found it and the
+        // directories above its path. One leading here only since, as
+        // through this mount's own link, waits for the next start.
+        real = placedRoots.get(inner.name);
+        if (real === undefined) continue;
+        above = placedAbove.get(inner.name) ?? [];
+      }
+      const at = await placementOf(outerPath, rootReal, innerPath, real, above, rootReal);
+      if (at === undefined) continue;
+      const include = this.mounts.get(inner.name)?.config.include;
+      for (const s of at.spellings) nested.push({ dir: s.dir, name: inner.name, ...(at.claims ? { real } : {}), include });
+    }
+    return nested;
   }
 
   /**
@@ -2052,17 +2563,32 @@ export class WorkspaceModule implements Module {
    * of that mount, judged lexically where the path lands (`.`, `..` and
    * repeated separators resolved, as for the traversal guard; a link of the
    * outer mount isn't followed), with the path to use there; undefined when
-   * no nested mount's directory holds it.
+   * no nested mount's directory holds it. A path parsePath has respelled is
+   * compared with the directory's spellings exactly. One judged as given
+   * (`asGiven`, resolveAbsolutePath's) is compared loosely, as a disk that
+   * folds names may compare it (beginsWithDir), so it can't reach that
+   * mount's directory by spelling a segment otherwise. On a disk that tells
+   * names apart, that takes a directory of this mount's own spelled like the
+   * nested one in another way as that mount's too.
    */
-  private holderOf(mountName: string, relativePath: string): { name: string; use: string } | undefined {
+  private holderOf(mountName: string, relativePath: string, asGiven = false, moved: NestedMount[] | null = null): { name: string; use: string } | undefined {
     const mount = this.mounts.get(mountName);
     if (!mount) return undefined;
-    const resolved = resolve(mount.config.path, relativePath);
-    const holder = (this.otherMounts.get(mountName) ?? [])
-      .flatMap((o) => o.spellings.filter((s) => isContainedPath(s.root, resolved)).map((s) => ({ name: o.name, root: s.root })))
-      .sort((a, b) => b.root.length - a.root.length)[0];
+    const root = resolve(mount.config.path);
+    const resolved = resolve(root, relativePath);
+    if (!isContainedPath(root, resolved)) return undefined;
+    const segments = resolved === root ? [] : relative(root, resolved).split(sep);
+    // A direct mount whose root a call found moved is judged by that call's
+    // nesting (movedNesting), each directory beneath its configured path.
+    const dirs = moved !== null
+      ? moved.map((n) => ({ name: n.name, dir: n.dir }))
+      : (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => ({ name: o.name, dir: s.dir })));
+    const holder = dirs
+      .filter((s) => beginsWithDir(segments, s.dir.split('/'), asGiven))
+      .map((s) => ({ name: s.name, depth: s.dir.split('/').length }))
+      .sort((a, b) => b.depth - a.depth)[0];
     if (!holder) return undefined;
-    const rest = relative(holder.root, resolved).split(sep).join('/');
+    const rest = segments.slice(holder.depth).join('/');
     return { name: holder.name, use: rest ? `${holder.name}/${rest}` : holder.name };
   }
 
@@ -2071,8 +2597,8 @@ export class WorkspaceModule implements Module {
    * mount and the path to use: for a sync or a push, which of them leaves
    * it; for a listing, whose the path is.
    */
-  private otherMountNote(mountName: string, relativePath: string, by: 'sync' | 'push' | 'list'): string {
-    const holder = this.holderOf(mountName, relativePath);
+  private otherMountNote(mountName: string, relativePath: string, by: 'sync' | 'push' | 'list', moved: NestedMount[] | null = null): string {
+    const holder = this.holderOf(mountName, relativePath, false, moved);
     const what = by === 'sync' ? ', which no sync of this mount takes in' : by === 'push' ? ', which no push of this mount writes' : '';
     return holder
       ? `it lies in mount "${holder.name}", nested in this one${what}: use "${holder.use}"`
@@ -2081,76 +2607,231 @@ export class WorkspaceModule implements Module {
 
   /**
    * parsePath for the file operations (read, write, edit, delete, and the
-   * module's binary and disk reads and writes). A path in another mount's
-   * directory nested in this one is that mount's: this mount's passes don't
-   * observe it and its pushes don't write it, so its file operations refuse
-   * it, naming the innermost mount that holds it and the path to use there.
+   * module's binary and disk reads and writes), refused where the mount
+   * doesn't hold the path. A path in another mount's directory nested in
+   * this one is that mount's: this mount's passes don't observe it and its
+   * pushes don't write it, so the refusal names the innermost mount that
+   * holds it and the path to use there. A path the mount's include doesn't
+   * cover is outside the mount, whatever disk or the workspace's history has
+   * there. A directory is checked the same way, since a path can be a
+   * directory on one side and a file on the other.
    */
   private async parseFilePath(path: string): Promise<{ mount: MountState; relativePath: string; path: string }> {
-    const parsed = this.refuseNested(await this.parsePath(path));
-    // A path can also reach a nested mount's directory through a symlink on
-    // its way. No push of this mount writes it there and no read reads it,
-    // so it's refused here, before anything is stored, and the checks where
-    // disk is acted on refuse it again.
-    const refusal = await this.leadsIntoNested(parsed.mount, parsed.relativePath, parsed.path);
+    const spelled = await this.parsePath(path);
+    // Both checks judge by the nesting the parse found, and the second reads
+    // disk beneath the root the parse resolved.
+    const { mount, root, moved } = spelled;
+    const parsed = this.refuseNotHeld(spelled, path, false, moved);
+    // A path can also reach a nested mount's directory, or a file this
+    // mount's own include leaves out, through a symlink on its way. No push
+    // of this mount writes it there and no read reads it, so it's refused
+    // here, before anything is stored, and the checks where disk is acted on
+    // refuse it again.
+    const refusal = await this.landingRefusal(mount, parsed.relativePath, parsed.path, moved ?? this.nestedOf(mount.config.name), root);
     if (refusal) throw refusal;
     return parsed;
   }
 
   /**
    * The refusal for a path of `mount` that reaches a nested mount's directory
-   * through a symlink on its way (nestedAtReal), or null where it doesn't. On
-   * a mount that doesn't follow the link, the refusal is the link's own
-   * (linkWords), as the readers and pushes give it. A mount with nothing
-   * nested has nothing to find, so it pays nothing.
+   * through a symlink on its way (nestedAtReal), or a file this mount's own
+   * include leaves out (coversLanding), or, on a mount that follows links
+   * with an include, one realpath can't resolve, or null where it doesn't.
+   * On a mount that doesn't follow the link, the refusal is the link's own
+   * (linkWords), as the readers and pushes give it. On one that does, it
+   * names the nested mount only where the place is that mount's
+   * (namesNestedPlace); anywhere else the place is no mount's, so the path
+   * leaves this one, in the disk readers' words, as it does where it lands
+   * on a file this mount's include leaves out. A mount with nothing nested,
+   * and without both an include and links followed, has nothing to find, so
+   * it pays nothing. The caller gives the nesting and the root to judge by
+   * (`nested`, `root`). A direct mount's file operation gives those its
+   * parse found, so where the path lands, and any link on its way, is judged
+   * beneath the root that parse resolved; any other caller gives the start's
+   * nesting and the configured path.
    */
-  private async leadsIntoNested(mount: MountState, relativePath: string, path: string): Promise<Error | null> {
-    const nested = this.nestedOf(mount.config.name);
-    if (nested.length === 0) return null;
-    const holder = nestedAtReal(await realBeneath(resolve(mount.config.path, relativePath)), nested);
-    if (!holder) return null;
+  private async landingRefusal(mount: MountState, relativePath: string, path: string, nested: readonly NestedMount[], root: string): Promise<Error | null> {
+    const judged = mount.config.followSymlinks === true && mount.config.include !== undefined;
+    if (nested.length === 0 && !judged) return null;
+    const unresolved: { code?: string } = {};
+    const real = await realBeneath(resolve(root, relativePath), 0, unresolved);
+    // Where realpath can't resolve the path, as for a loop or a directory
+    // this process can't search, where it lands can't be judged, and a
+    // promise about content fails closed: the path is refused, by every file
+    // operation, in the words a disk read gives a path it can't resolve,
+    // whatever the place realpath stopped short of would say.
+    if (judged && unresolved.code !== undefined) return new WorkspaceReadError('not_found', `Unable to resolve file: ${path}`, 'realpath', unresolved.code);
+    const holder = nestedAtReal(real, nested);
+    if (!holder) {
+      if (!judged) return null;
+      const rootReal = await realBeneath(root);
+      if (!isContainedPath(rootReal, real) || await stat(real).then((info) => info.isDirectory(), () => false)) return null;
+      return await coversLanding({ include: mount.config.include }, rootReal, real, relativePath) ? null : new WorkspaceReadError('escape', `Symlink escape detected: ${path}`, 'realpath');
+    }
     if (mount.config.followSymlinks !== true) {
-      const found = await linkOnTheWay({ root: mount.config.path, followSymlinks: false }, relativePath);
-      if (found !== null) return await linkReadError(mount, found, path, nested);
+      const rootReal = await realBeneath(root);
+      const found = await linkOnTheWay({ root: rootReal, followSymlinks: false }, relativePath);
+      if (found !== null) return await linkReadError(mount, found, path, relativePath, nested, rootReal);
     }
+    // On a mount with an include, the path to use there names each directory
+    // on the place's way as that mount's, so a place beneath anything else
+    // there, such as a file the include leaves out, isn't named; one beneath
+    // a directory not there yet is.
+    const onItsWay = holder.include === undefined
+      || await stat(dirname(real)).then((info) => info.isDirectory(), (err: unknown) => errnoOf(err) === 'ENOENT');
+    const directory = holder.include !== undefined && await stat(real).then((info) => info.isDirectory(), () => false);
+    if (!onItsWay || !namesNestedPlace(holder.rest, holder.include, directory)) return new WorkspaceReadError('escape', `Symlink escape detected: ${path}`, 'realpath');
     return new NestedMountError(path, mount.config.name, holder.name, holder.use, 'leads into');
   }
 
-  /** A parsed path, refused if it lies in a nested mount's directory (parseFilePath). */
-  private refuseNested<P extends { mount: MountState; relativePath: string; path: string }>(parsed: P): P {
-    const holder = this.holderOf(parsed.mount.config.name, parsed.relativePath);
+  /**
+   * A parsed path, refused where the mount doesn't hold it: in a nested
+   * mount's directory first, naming the mount that holds it, then outside
+   * the mount's include. Each is judged on the path as the caller parsed it:
+   * as disk spells it for parseFilePath, as given for resolveAbsolutePath,
+   * which is synchronous and says so (`asGiven`, so the nested-mount check
+   * folds where disk does). The include's refusal shows the path as given
+   * (`given`), since it answers the path the caller asked about.
+   */
+  private refuseNotHeld<P extends { mount: MountState; relativePath: string; path: string }>(parsed: P, given: string, asGiven = false, moved: NestedMount[] | null = null): P {
+    const holder = this.holderOf(parsed.mount.config.name, parsed.relativePath, asGiven, moved);
     if (holder) throw new NestedMountError(parsed.path, parsed.mount.config.name, holder.name, holder.use);
+    if (!insideMount(parsed.relativePath, parsed.mount.config.include)) {
+      throw new OutsideIncludeError(given, parsed.mount.config);
+    }
     return parsed;
   }
 
+  /**
+   * Whether a mount-relative path names a file, as grep decides what a path
+   * it's given names: for a path the include covers, a file in the
+   * workspace's history, or anything but a directory on disk. Grep takes it
+   * as a directory only when neither side has a file there, and filters what
+   * it finds beneath it by the mount's include. A path the include doesn't
+   * cover names no file of the mount's, whatever disk or history holds
+   * there, so one refusesAsOutside lets through is a directory. A direct
+   * mount has no history: what a run of it as 'chronicle' left in the store
+   * isn't its own, so disk alone decides. Disk is read beneath `root`: a
+   * direct mount's is the root its parse resolved, a store-backed mount's
+   * its configured path.
+   */
+  private async namesFile(mount: MountState, relativePath: string, root: string): Promise<boolean> {
+    return relativePath !== '' && insideMount(relativePath, mount.config.include) && (
+      (!mount.direct && this.getStore().treeGet(mount.treeStateId, relativePath) !== null) ||
+      await lstat(join(root, relativePath)).then((s) => !s.isDirectory(), () => false)
+    );
+  }
+
+  /**
+   * Whether sync, materialize, grep, glob or ls refuses a path it's given as
+   * outside the mount's include. A path the include doesn't cover is a scope
+   * exactly where a listing names a directory: where disk has a directory
+   * reached from the mount's root through directories, with no link among
+   * them, or the workspace's history holds an entry beneath it that's the
+   * mount's own to list (withinIncludes). The one exception is a directory
+   * the ignore list covers, which a listing passes over and which is still a
+   * scope when it's named, since a sync that names it takes in what's there
+   * (#276). Anything else is refused, a file at the path included, which no
+   * scope tool takes up. The walk descends no link it meets. Where covered
+   * history makes a name a scope and disk has since put a link there, a
+   * mount that doesn't follow symlinks refuses the link, as it refuses any
+   * link on a path's way, and on a mount that does, a pass of the scope
+   * follows the link, and its answer shows whether the link leads out of the
+   * mount. A
+   * path in another mount's directory nested in this one is that mount's,
+   * whatever this mount's include says, so it isn't refused here: each tool
+   * names the mount that holds it, as the file operations do. A direct mount
+   * has no history, as namesFile says, and is judged beneath the root its
+   * parse resolved (`root`), by the nesting there (`moved`, movedNesting).
+   */
+  private async refusesAsOutside(mount: MountState, relativePath: string, moved: NestedMount[] | null, root: string): Promise<boolean> {
+    if (this.holderOf(mount.config.name, relativePath, false, moved)) return false;
+    if (insideMount(relativePath, mount.config.include)) return false;
+    const own = { include: mount.config.include, nested: this.nestedOf(mount.config.name) };
+    if (!mount.direct && this.getStore().treeList(mount.treeStateId, relativePath + '/')
+      .some((entry) => withinIncludes(own, entry.path))) return false;
+    // A directory, and each directory above it to the mount's root, as the
+    // walk reaches it: through no link, since the walk descends none.
+    const segments = relativePath.split('/');
+    for (let i = 1; i <= segments.length; i++) {
+      const entry = await lstat(join(root, ...segments.slice(0, i))).catch(() => null);
+      if (!entry?.isDirectory()) return true;
+    }
+    return false;
+  }
+
   /**
    * Parse a mount-prefixed path into its mount and mount-relative path, as
-   * disk spells it (diskSpelling), with `path` the mount-prefixed path so
-   * spelled. On a disk that folds names, a path spelled otherwise reaches
-   * disk's file, so every tool takes it by disk's name: one name per file,
-   * and the names its answers give are disk's, except that a path that names
-   * a workspace entry exactly, or does once its directories take disk's
-   * spelling, keeps the entry's spelling. A path the workspace records an
-   * intent at, such as a deletion disk hasn't been given yet, counts as an
-   * entry here, so the calls that settle it reach it. The workspace's
-   * entries (entriesOf) stand in for disk where it has nothing yet, so a
-   * draft has one name too. Neither applies to a path that disk's spelling
-   * puts in a nested mount's directory.
+   * disk spells it (diskSpelling). `path` is the mount-prefixed path in that
+   * spelling where it differs from the one spelling, and otherwise the path
+   * as the caller gave it. The path is read in its one spelling first
+   * (parsePathAsGiven), so the respelling only ever sees a path with no
+   * empty, `.` or `..` segment and no separator before its first. On a disk
+   * that folds names, a path spelled otherwise reaches disk's file, so every
+   * tool takes it by disk's name: one name per file, and the names its
+   * answers give are disk's, except that a path that names a workspace entry
+   * exactly, or does once its directories take disk's spelling, keeps the
+   * entry's spelling, and what lies past a link on the way keeps the
+   * caller's, since the step reads nothing past a link. A path the workspace
+   * records an intent at, such as a deletion disk hasn't been given yet,
+   * counts as an entry here, so the calls that settle it reach it. The
+   * workspace's entries (entriesOf) stand in for disk where it has nothing
+   * yet, so a draft has one name too. Neither applies to a path that disk's
+   * spelling puts in a nested mount's directory. A direct mount holds no
+   * entries, so its paths take disk's spelling alone. Past a nested mount's
+   * directory the path stays as given, since what lies there is that mount's
+   * to name. Every answer shows `path`, a name the include leaves out
+   * included, since how disk spells a name the caller gave is no content of
+   * that file, except the include's own refusal, which shows the path
+   * exactly as given (refuseNotHeld), since it answers the path asked about.
    * A handler that must read something at the moment it's asked, as
    * handleSync reads the branch a path sync adopts on, reads it before
-   * calling this, since this awaits disk. The entries are read when the
-   * step needs them, some after those awaits, from the branch current then.
+   * calling this, since this awaits disk. The entries are read when the step
+   * needs them, some after those awaits, from the branch current then.
    */
-  private async parsePath(path: string): Promise<{ mount: MountState; relativePath: string; path: string }> {
+  private async parsePath(path: string): Promise<ParsedPath> {
     const given = this.parsePathAsGiven(path);
-    const relativePath = await diskSpelling(resolve(given.mount.config.path), given.relativePath, this.entriesOf(given.mount));
+    // A direct mount's root is resolved once here, so the respelling and the
+    // checks of the path that follow read disk beneath one root and judge by
+    // the nesting there (movedNesting).
+    const configured = resolve(given.mount.config.path);
+    const root = given.mount.direct ? await realpath(configured).catch(() => configured) : configured;
+    const moved = given.mount.direct ? await this.movedNesting(given.mount, root) : null;
+    const spelled = await diskSpelling(root, given.relativePath, given.mount.direct ? undefined : this.entriesOf(given.mount));
+    // Past a nested mount's directory the path stays as given: what lies
+    // there is that mount's, whose own include decides what a tool may name,
+    // so this mount doesn't respell it.
+    // The directory itself takes disk's spelling, as a listing names it.
+    // The respelling keeps each segment's place, so the given path's rest
+    // follows the directory's segments.
+    const depth = this.nestedDepth(given.mount.config.name, spelled, moved);
+    const relativePath = depth === undefined ? spelled
+      : [...spelled.split('/').slice(0, depth), ...given.relativePath.split('/').slice(depth)].join('/');
     return {
       mount: given.mount,
       relativePath,
       path: relativePath === given.relativePath ? path : `${given.mount.config.name}/${relativePath}`,
+      root,
+      moved,
     };
   }
 
+  /**
+   * How many segments the innermost nested mount's directory that holds
+   * `relativePath` has, in a spelling it's known by (othersOf), or, for a
+   * direct mount whose root has moved, in the nesting there (`moved`);
+   * undefined when no nested mount's directory holds it.
+   */
+  private nestedDepth(mountName: string, relativePath: string, moved: NestedMount[] | null = null): number | undefined {
+    let depth: number | undefined;
+    for (const dir of moved?.map((n) => n.dir) ?? this.othersOf(mountName)) {
+      if (relativePath !== dir && !relativePath.startsWith(`${dir}/`)) continue;
+      const segments = dir.split('/').length;
+      if (depth === undefined || segments > depth) depth = segments;
+    }
+    return depth;
+  }
+
   /**
    * A mount's entries on the current branch, and the paths it records an
    * intent at there, as diskSpelling reads them when it does, whether its
@@ -2168,14 +2849,34 @@ export class WorkspaceModule implements Module {
       // given yet or a conflict, is the workspace's own name for the file
       // there, as an entry is, so the calls that settle it reach it.
       has: (path) => store.treeGet(mount.treeStateId, path) !== null || store.treeGet(intents.treeStateId, path) !== null,
-      under: (prefix) => store.treeList(mount.treeStateId, prefix).map((entry) => entry.path),
+      // Only an entry this mount's include covers spells a draft's path
+      // (insideMount): not a key no spelling names, such as `c/` or `a//b.txt`
+      // from an earlier version, nor one the include leaves out, which would
+      // respell a covered draft into a name the include leaves out. An entry
+      // in a nested mount's directory that this mount's include covers
+      // spells one whatever that mount's include says, so on a disk that
+      // folds names, a draft naming the directory in another spelling takes
+      // the entry's spelling and is judged as in it.
+      under: (prefix) => store.treeList(mount.treeStateId, prefix).map((entry) => entry.path).filter((path) => insideMount(path, mount.config.include)),
       holder: (path) => this.holderOf(mount.config.name, path)?.name,
       rootFoldsCase: this.rootFoldsCase.get(mount.config.name) ?? false,
     };
   }
 
   /**
-   * Parse a mount-prefixed path into (mountName, relativePath), as spelled.
+   * Parse a mount-prefixed path into its mount and the one mount-relative
+   * path every later step reads, as given, before disk's spelling
+   * (parsePath): `/` between segments (`\` read as `/` where it's the
+   * platform's separator), with no empty or `.` segment and no trailing `/`,
+   * and '' for the mount's root. So the traversal guard here and every later
+   * step judge one spelling of the path, which parsePath then respells name
+   * by name as disk lists them. A `..` segment takes back the segment before
+   * it, before anything looks the path up, so a mount's include judges the
+   * path every tool acts on, and one with nothing left to take back climbs
+   * above the mount's root and is refused, whatever it reaches afterwards. A
+   * separator straight after the mount's name would make the rest an
+   * absolute path, so that is refused too, and every reader that takes a
+   * path refuses it here, a disk reader included.
    */
   private parsePathAsGiven(path: string): { mount: MountState; relativePath: string } {
     // A file's name on disk is UTF-8, which can't hold a lone surrogate: the
@@ -2185,25 +2886,37 @@ export class WorkspaceModule implements Module {
     }
     const slashIdx = path.indexOf('/');
     const mountName = slashIdx >= 0 ? path.slice(0, slashIdx) : path;
-    const relativePath = slashIdx >= 0 ? path.slice(slashIdx + 1) : '';
+    const given = slashIdx >= 0 ? path.slice(slashIdx + 1) : '';
 
     const mount = this.mounts.get(mountName);
     if (!mount) {
       throw new Error(`Unknown mount: "${mountName}". Available: ${[...this.mounts.keys()].join(', ')}`);
     }
-
-    // Path traversal guard (CWE-22): ensure resolved path stays within mount.
-    // Containment must compare with the PLATFORM separator (isContainedPath):
-    // resolve() emits backslashes on Windows, so a '/'-suffixed root never
-    // prefix-matches there and every in-mount path was rejected as traversal.
-    // Against the resolved root, so a root configured with a trailing
-    // separator, or relative, contains its own paths, the root included.
+    const segments = pathSegments(given);
+    if (given.startsWith('/') || (sep === '\\' && given.startsWith('\\'))) {
+      throw new Error(`Path traversal detected: "${path}" has a separator right after mount "${mountName}", which makes it an absolute path: give it from the mount's root.`);
+    }
+    const kept: string[] = [];
+    for (const segment of segments) {
+      if (segment !== '..') kept.push(segment);
+      else if (kept.pop() === undefined) {
+        throw new Error(`Path traversal detected: "${path}" climbs above the root of mount "${mountName}".`);
+      }
+    }
+    const relativePath = kept.join('/');
+
+    // Path traversal guard (CWE-22), on the path every later step reads: on
+    // Windows a first segment such as `C:` names another drive. Containment
+    // must compare with the PLATFORM separator (isContainedPath): resolve()
+    // emits backslashes on Windows, so a '/'-suffixed root never prefix-matches
+    // there and every in-mount path was rejected as traversal. Against the
+    // resolved root, so a root configured with a trailing separator, or
+    // relative, contains its own paths, the root included.
     const root = resolve(mount.config.path);
     const resolved = resolve(root, relativePath);
     if (!isContainedPath(root, resolved)) {
       throw new Error(`Path traversal detected: "${path}" resolves outside mount "${mountName}"`);
     }
-
     return { mount, relativePath };
   }
 
@@ -2272,6 +2985,8 @@ export class WorkspaceModule implements Module {
    * which answers while the evidence awaits reopening; where even it can't
    * be read, as when the evidence was never read back whole, the read is
    * refused too, with an errno only where no directory is at the root's path.
+   * A direct mount's root is checked against no identity, and its read reads
+   * no evidence: it promises what's at its root now (diskView).
    */
   private async readRoot(mount: MountState): Promise<{ real: string; dir: CheckedDir }> {
     const name = mount.config.name;
@@ -2283,13 +2998,15 @@ export class WorkspaceModule implements Module {
       throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${name}`, 'realpath_root', errnoOf(err));
     }
     let rootIdentity: MountView['rootIdentity'];
-    try {
-      rootIdentity = this.agreementOrThrow().rootIdentityForRead(name);
-    } catch (err) {
-      // The evidence can't be read back, so neither can the check be made.
-      // Where no directory is at the root's path, its errno still says so.
-      throw new WorkspaceReadError('mount_unavailable',
-        `Mount unavailable: ${name}: ${err instanceof Error ? err.message : String(err)}`, 'root', await rootAbsence(root));
+    if (!mount.direct) {
+      try {
+        rootIdentity = this.agreementOrThrow().rootIdentityForRead(name);
+      } catch (err) {
+        // The evidence can't be read back, so neither can the check be made.
+        // Where no directory is at the root's path, its errno still says so.
+        throw new WorkspaceReadError('mount_unavailable',
+          `Mount unavailable: ${name}: ${err instanceof Error ? err.message : String(err)}`, 'root', await rootAbsence(root));
+      }
     }
     const checked = await checkRoot(this.viewOf(mount, rootIdentity), real);
     if ('dir' in checked) return { real, dir: checked.dir };
@@ -2305,11 +3022,13 @@ export class WorkspaceModule implements Module {
    * with the code and errno readRoot gives what is at its path now (its stage
    * and words are this check's): gone, or not a directory, with ENOENT or
    * ENOTDIR, so a caller reads a root gone mid-read as one gone before it; or
-   * another directory, with none.
+   * another directory, with none. A direct mount reads whatever directory is
+   * at its root (MountConfig.backend), so for it, another directory there is
+   * one the next read reads.
    */
   private async rootMoved(mount: MountState): Promise<WorkspaceReadError> {
     const errno = await rootAbsence(resolve(mount.config.path));
-    const reason = errno === undefined ? ROOT_REPLACED : ROOT_UNAVAILABLE;
+    const reason = errno !== undefined ? ROOT_UNAVAILABLE : mount.direct ? DIRECT_ROOT_REPLACED : ROOT_REPLACED;
     return new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}: ${reason}`, 'root', errno);
   }
 
@@ -2324,7 +3043,8 @@ export class WorkspaceModule implements Module {
    *    among the directories on its way beneath the mount's root, wherever it
    *    leads (linkOnTheWay), before anything resolves it: as `escape` for a
    *    link leading outside the mount, as `other_mount` for one into a nested
-   *    mount's directory, and as `parent_symlink` for any other.
+   *    mount's directory where its refusal names that mount, and as
+   *    `parent_symlink` for any other.
    * 2. `lstat` the lexical path — refuse directories; refuse a final-component
    *    symlink when the mount does not `followSymlinks`; refuse anything else
    *    that isn't a regular file, such as a FIFO, without opening it.
@@ -2384,9 +3104,14 @@ export class WorkspaceModule implements Module {
     // mount that doesn't follow symlinks goes through none among the
     // directories on the way, wherever it leads. Asked again of the path's
     // resolution after the open, below.
-    const linkView = { root: mount.config.path, followSymlinks: follow };
+    // The checks below judge by the root step 0 checked, and read the links
+    // on the path's way beneath it. The lstat and the open go through the
+    // configured path, and step 5 refuses a read whose root is no longer the
+    // directory step 0 checked, so what's served is judged beneath one root.
+    const linkView = { root: realMountRoot, followSymlinks: follow };
+    const nested = await this.nestedFor(mount, realMountRoot);
     const onTheWay = await linkOnTheWay(linkView, relativePath, 'parents');
-    if (onTheWay !== null) throw await linkReadError(mount, onTheWay, mountPrefixedPath, this.nestedOf(mount.config.name));
+    if (onTheWay !== null) throw await linkReadError(mount, onTheWay, mountPrefixedPath, relativePath, nested, realMountRoot);
 
     let fileInfo: Awaited<ReturnType<typeof lstat>>;
     try {
@@ -2473,14 +3198,23 @@ export class WorkspaceModule implements Module {
       }
 
       // A directory swapped for a link since the walk above is caught here, by
-      // what the path resolved to after the open.
+      // what the path resolved to after the open, and the check below holds
+      // the opened file to that path. A link put back after this realpath,
+      // leading to the opened file itself, passes both: a race this doesn't
+      // close.
       const resolvedThrough = await linkRefusal(linkView, realMountRoot, relativePath, realFilePath);
-      if (resolvedThrough !== null) throw await linkReadError(mount, resolvedThrough, mountPrefixedPath, this.nestedOf(mount.config.name));
-
-      if (!isContainedPath(realMountRoot, realFilePath)) {
+      if (resolvedThrough !== null) throw await linkReadError(mount, resolvedThrough, mountPrefixedPath, relativePath, nested, realMountRoot);
+
+      const inside = isContainedPath(realMountRoot, realFilePath);
+      const holder = inside ? nestedAtReal(realFilePath, nested) : undefined;
+      // A place in a nested mount's directory that its include leaves out is
+      // no mount's, so the path leaves this one (namesNestedPlace), and so
+      // does one reaching a file this mount's own include leaves out
+      // (coversLanding).
+      const own = holder === undefined && inside && !(await coversLanding({ include: mount.config.include }, realMountRoot, realFilePath, relativePath));
+      if (!inside || own || (holder !== undefined && !namesNestedPlace(holder.rest, holder.include, false))) {
         throw new WorkspaceReadError('escape', `Symlink escape detected: ${mountPrefixedPath}`, 'realpath');
       }
-      const holder = nestedAtReal(realFilePath, this.nestedOf(mount.config.name));
       if (holder) throw new WorkspaceReadError('other_mount', leadsInto(mount.config.name, relativePath, holder), 'realpath');
 
       let pathStat: Stats;
@@ -2532,7 +3266,9 @@ export class WorkspaceModule implements Module {
    * - Once the workspace has recorded the mount root's identity, with the
    *   first evidence it gathers there, a root that is another directory is
    *   an unavailable mount: a replaced directory, a link swapped in for it,
-   *   or an unmounted drive's mountpoint. In any mount, recorded or not, a
+   *   or an unmounted drive's mountpoint. A direct mount's reads check no
+   *   recorded identity: they read beneath whatever directory is at its
+   *   root (MountConfig.backend). In any mount, recorded or not, a
    *   root that stops being the directory the read checked until the file
    *   has been opened and checked is unavailable too: with ENOENT or
    *   ENOTDIR where no directory is there, as before the read, and with no
@@ -2540,9 +3276,10 @@ export class WorkspaceModule implements Module {
    *   the descriptor that was checked.
    *
    * Throws {@link WorkspaceReadError} with a `code` distinguishing unknown
-   * mount, lexical traversal, a path in another mount's directory nested in
-   * the one named (`other_mount`), unavailable mount, missing or non-regular
-   * file, directory, policy-denied symlink, outside-mount target, and
+   * mount, lexical traversal, a path the mount's include doesn't cover
+   * (`outside_include`), a path in another mount's directory nested in the one named
+   * (`other_mount`), unavailable mount, missing or non-regular file,
+   * directory, policy-denied symlink, outside-mount target, and
    * file-changed-during-read.
    */
   async readFileFromDisk(
@@ -2560,7 +3297,8 @@ export class WorkspaceModule implements Module {
       // A link's refusal (parseFilePath) carries its own code.
       if (err instanceof WorkspaceReadError) throw err;
       const message = err instanceof Error ? err.message : String(err);
-      const code: WorkspaceReadErrorCode = err instanceof NestedMountError ? 'other_mount'
+      const code: WorkspaceReadErrorCode = err instanceof OutsideIncludeError ? 'outside_include'
+        : err instanceof NestedMountError ? 'other_mount'
         : message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
       throw new WorkspaceReadError(code, message, 'parse');
     }
@@ -2692,9 +3430,11 @@ export class WorkspaceModule implements Module {
   /**
    * Commit a tool's write or delete to the workspace tree, with the branch
    * intent it implies: store origin for a path disk never agreed with; for a
-   * deletion, a tombstone, unless the evidence holds no agreed disk copy (P
+   * deletion, a tombstone, written before the entry is removed, unless the
+   * agreement's evidence for the path, P, holds no agreed disk copy (P
    * absent, or no P and store origin), when it clears the path's intent and
-   * pushes nothing. It pushes the change to disk when the mount opts in via
+   * pushes nothing. It pushes the change to
+   * disk when the mount opts in via
    * `autoMaterialize` — required for cross-agent pipelines, since another
    * agent's watcher on the same directory only sees real filesystem events.
    * The push follows materialize's rule: a disk copy that changed since it
@@ -2713,85 +3453,210 @@ export class WorkspaceModule implements Module {
   private async commitToolChange(
     mount: MountState,
     relativePath: string,
-    change: { kind: 'set'; blobHash: string; size: number; mode?: number } | { kind: 'remove'; previousHash: string },
+    change: ToolChange,
     onCommitted?: () => void,
   ): Promise<{ refused: string | null; modeKept: string | null; note: string | null }> {
+    const { refused, modeKept, notes } = await this.commitToolChanges(mount, [{ path: relativePath, change }], onCommitted && (() => onCommitted()));
+    return { refused: refused.get(relativePath) ?? null, modeKept: modeKept.get(relativePath) ?? null, note: notes.get(relativePath) ?? null };
+  }
+
+  /**
+   * commitToolChange for several paths of one mount at once, as edit_many
+   * commits its files: every path's precondition is enforced before any entry
+   * is set, then a deletion's tombstone is written, then every entry is set
+   * in one record of the store, which takes all of them or none, then each
+   * other path's intent, by the rule commitToolChange's doc gives, which the
+   * code below applies, with no await between, and one push takes the paths
+   * to disk, but for a deletion that clears its path's intent. `onCommitted`
+   * is told of each path once the entries are set, also when the store throws
+   * after setting them, whose error then goes on in place of the push
+   * (changesLanded).
+   * Answers, by path, the reason for each that reached the workspace but not
+   * disk (`refused`), and, apart from it, why one whose bytes reached disk
+   * left the file's mode as disk had it (`modeKept`), and that a deletion
+   * clearing a conflict that named a disk file unlinked nothing (`notes`), as
+   * commitToolChange answers them for one path.
+   */
+  private async commitToolChanges(
+    mount: MountState,
+    changes: Array<{ path: string; change: ToolChange }>,
+    onCommitted?: (path: string) => void,
+  ): Promise<{ refused: Map<string, string>; modeKept: Map<string, string>; notes: Map<string, string> }> {
     const store = this.getStore();
+    const agreement = this.agreementOrThrow();
     const intents = this.intents.get(mount.config.name)!;
     // The mutation's precondition, enforced here, synchronously with the
     // commit: whatever settleBeforeMutation's pass could or couldn't settle.
-    settleAdoptionBeforeMutation(store, this.agreementOrThrow(), { name: mount.config.name, treeStateId: mount.treeStateId }, relativePath);
-    const evidence = this.agreementOrThrow().get(mount.config.name, relativePath);
-    const known = evidence !== undefined;
-    if (change.kind === 'set') {
-      store.treeSet(mount.treeStateId, relativePath, { blobHash: change.blobHash, size: change.size, mode: change.mode ?? 0o644 });
-      // A later intent update or disk push can throw; the tree entry is
-      // already set, on the branch current now. If the active branch changes
-      // during the push, that branch's tree has the file and the new one may
-      // not.
-      onCommitted?.();
-      intents.update(relativePath, (cur) => {
-        const next = { ...cur };
-        delete next.tombstone;
-        // Disk has never agreed with this path: a missing disk copy is a draft
-        // not yet materialized, not a deletion.
-        if (!known) next.origin = 'store';
-        return next;
-      });
-    } else {
-      store.treeRemove(mount.treeStateId, relativePath);
-      onCommitted?.();
-      // A deletion whose evidence holds no agreed disk copy (disk last agreed
-      // it had nothing here, or has never agreed with this entry, which the
-      // workspace created) puts the store back at the agreement. Nothing on
-      // disk is the workspace's to unlink, so it pushes nothing, and it
-      // clears the path's whole intent: no tombstone, so it needs no proof of
-      // absence, which a path disk can't show, such as one beneath a symlink
-      // the mount doesn't follow, would never give; and no conflict, which
-      // has nothing left to be about once the workspace has given up its
-      // side. Whatever disk holds there is a sync's to observe, a file the
-      // workspace never saw included. Any other deletion keeps its
-      // tombstone, which guards it: a copy disk agreed with, a push of ours
-      // that may have landed (pending or interrupted), or an entry from
-      // before the evidence.
-      let agreed = true;
-      let note: string | null = null;
-      intents.update(relativePath, (cur) => {
-        agreed = !(evidence?.kind === 'absent' || (evidence === undefined && cur.origin === 'store'));
-        if (agreed) {
-          const next = { ...cur, tombstone: { hash: change.previousHash } };
-          delete next.origin;
-          return next;
+    // Every path's comes first, so nothing that can refuse follows a set.
+    for (const { path } of changes) {
+      settleAdoptionBeforeMutation(store, agreement, { name: mount.config.name, treeStateId: mount.treeStateId }, path);
+    }
+    const entry = (change: ToolChange & { kind: 'set' }) => ({ blobHash: change.blobHash, size: change.size, mode: change.mode ?? 0o644 });
+    // The changes the tree doesn't hold yet, which the read-back below checks,
+    // read before any intent is written, so no read comes between a
+    // tombstone's write and the put-back's guard.
+    const changing = changes.filter(({ path, change }) => !holds(store.treeGet(mount.treeStateId, path), change));
+    // Each path's intent, by the rule commitToolChange's doc gives. A
+    // deletion's tombstone is written before its entry is removed. Removed
+    // without it, the entry would read as a file this branch doesn't have,
+    // which no materialize deletes and no second delete can reach
+    // (anima-research/agent-framework#553). Every other intent is written
+    // after the tree change: what it gives up, the tombstone a write replaces
+    // or the origin and conflict a deletion clears, guards the path until the
+    // change lands.
+    const notes = new Map<string, string>();
+    const unpushed = new Set<string>();
+    const intentChanges = changes.map(({ path, change }): { path: string; first: boolean; next: (cur: BranchIntent) => BranchIntent } => {
+      const evidence = agreement.get(mount.config.name, path);
+      const cur = intents.get(path) ?? {};
+      if (change.kind === 'remove') {
+        // A deletion whose evidence holds no agreed disk copy (disk last
+        // agreed it had nothing here, or has never agreed with this entry,
+        // which the workspace created) puts the store back at the
+        // agreement. Nothing on disk is the workspace's to unlink, so it
+        // pushes nothing, and it clears the path's whole intent: no
+        // tombstone, so it needs no proof of absence, which a path disk
+        // can't show, such as one beneath a symlink the mount doesn't
+        // follow, would never give; and no conflict, which has nothing left
+        // to be about once the workspace has given up its side. Whatever
+        // disk holds there is a sync's to observe, a file the workspace
+        // never saw included. Any other deletion keeps its tombstone, which
+        // guards it: a copy disk agreed with, a push of ours that may have
+        // landed (pending or interrupted), or an entry from before the
+        // evidence.
+        if (!(evidence?.kind === 'absent' || (evidence === undefined && cur.origin === 'store'))) {
+          return {
+            path,
+            first: true,
+            next: (current) => {
+              const next = { ...current, tombstone: { hash: change.previousHash } };
+              delete next.origin;
+              return next;
+            },
+          };
         }
+        unpushed.add(path);
         // A conflict it clears may name a file disk held there, which the
-        // workspace never took in: the answer says that file wasn't unlinked,
-        // where the deletion alone would read as having removed it. The
-        // deletion doesn't look at disk, so a file nothing recorded gets no
-        // note.
+        // workspace never took in: the answer says that file wasn't
+        // unlinked, where the deletion alone would read as having removed
+        // it. The deletion doesn't look at disk, so a file nothing recorded
+        // gets no note.
         if (cur.conflict?.disk) {
-          note = `nothing was unlinked: when last observed, disk held a file at ${mount.config.name}/${relativePath} ` +
-            `that the workspace never took in (conflict: ${cur.conflict.kind}), and a sync observes whatever disk holds there`;
+          notes.set(path, `nothing was unlinked: when last observed, disk held a file at ${mount.config.name}/${path} `
+            + `that the workspace never took in (conflict: ${cur.conflict.kind}), and a sync observes whatever disk holds there`);
         }
-        return {};
-      });
-      if (!agreed) return { refused: null, modeKept: null, note };
+        return { path, first: false, next: () => ({}) };
+      }
+      return {
+        path,
+        first: false,
+        next: (current) => {
+          const next = { ...current };
+          delete next.tombstone;
+          // Disk has never agreed with this path: a missing disk copy is a
+          // draft not yet materialized, not a deletion.
+          if (evidence === undefined) next.origin = 'store';
+          return next;
+        },
+      };
+    });
+    // A tombstone written for a change that then doesn't land is put back:
+    // the path's intent record as it was, a damaged one's bytes included, so
+    // a refused deletion changes nothing. The put-back is best effort, since
+    // the error that stopped the call is its answer. A tombstone it leaves
+    // beside the entry guards nothing: decide gives no verdict from one while
+    // the entry is there, status and materialize take it as no deletion, and
+    // the path's next agreement clears it.
+    const written: Array<{ path: string; record: JsTreeEntry | null }> = [];
+    const putBack = () => {
+      for (const { path, record } of written) {
+        try {
+          if (record) store.treeSet(intents.treeStateId, path, record);
+          else if (store.treeGet(intents.treeStateId, path)) store.treeRemove(intents.treeStateId, path);
+        } catch (error) {
+          // Left beside the entry, where it guards nothing (above).
+          console.warn(
+            `[workspace] Mount "${mount.config.name}": a change to ${path} failed, and putting its branch intent back threw too `
+            + `(${error instanceof Error ? error.message : String(error)}), so a tombstone may be left beside the entry. One there `
+            + `deletes nothing, and the path's next agreement with disk clears it`,
+          );
+        }
+      }
+    };
+    try {
+      for (const { path, first, next } of intentChanges) {
+        if (!first) continue;
+        written.push({ path, record: store.treeGet(intents.treeStateId, path) });
+        intents.update(path, next);
+      }
+    } catch (error) {
+      putBack();
+      throw error;
     }
-    if (!this.pushesOnCommit(mount)) return { refused: null, modeKept: null, note: null };
-
-    const pushed = await this.pushUnlocked(mount, [relativePath], {
-      applyDeletions: change.kind === 'remove',
+    // A store can fail after its record lands: Chronicle 0.4 writes a state's
+    // auto-snapshot after appending its update, and that failure reaches the
+    // caller with the update recorded (anima-research/chronicle#39). So a set
+    // that threw is read back, and where every path it changes holds what its
+    // change leaves, the record is in: the paths' intents follow, as for any
+    // set, and then the error goes on in place of the push. A change the tree
+    // already holds can't show whether the record is in, so a call whose every
+    // change the tree holds already goes on as the store's own failure.
+    let landedThenThrew: { error: unknown } | null = null;
+    try {
+      if (changes.length === 1) {
+        const [{ path, change }] = changes as [{ path: string; change: ToolChange }];
+        if (change.kind === 'set') store.treeSet(mount.treeStateId, path, entry(change));
+        else store.treeRemove(mount.treeStateId, path);
+      } else {
+        // One record for every path, so a store that fails partway sets none.
+        store.treeBatch(mount.treeStateId, changes.map(({ path, change }) => (change.kind === 'set'
+          ? { op: 'set', path, entry: entry(change) }
+          : { op: 'remove', path })));
+      }
+    } catch (error) {
+      // A read-back that fails can't tell whether the change landed, so its
+      // error goes on and a tombstone stays: put back where the removal did
+      // land, it would leave #553's state, and beside an entry it guards
+      // nothing.
+      if (changing.length === 0 || !changesLanded(store, mount.treeStateId, changing, error)) {
+        putBack();
+        throw error;
+      }
+      landedThenThrew = { error };
+    }
+    // A later intent update or disk push can throw; the tree entries are
+    // already set, on the branch current now. If the active branch changes
+    // during the push, that branch's tree has the files and the new one may
+    // not.
+    for (const { path } of changes) onCommitted?.(path);
+    for (const { path, first, next } of intentChanges) if (!first) intents.update(path, next);
+    const pushing = changes.filter(({ path }) => !unpushed.has(path));
+    if (landedThenThrew) throw new StoredThenFailed(landedThenThrew.error, this.pushesOnCommit(mount) && pushing.length > 0, notes);
+    const refused = new Map<string, string>();
+    const modeKept = new Map<string, string>();
+    if (!this.pushesOnCommit(mount) || pushing.length === 0) return { refused, modeKept, notes };
+
+    const pushed = await this.pushUnlocked(mount, pushing.map(({ path }) => path), {
+      applyDeletions: pushing.some(({ change }) => change.kind === 'remove'),
       branchId: store.currentBranch().id,
     });
-    const refused = pushed.skipped.find((s) => s.path === relativePath);
-    if (!refused) return { refused: null, modeKept: pushed.modesKept.find((k) => k.path === relativePath)?.reason ?? null, note: null };
-    this.ctx?.pushEvent({
-      type: 'workspace:materialize-failed',
-      mount: mount.config.name,
-      path: relativePath,
-      op: change.kind === 'set' ? 'write' : 'delete',
-      error: refused.reason,
-    } as ProcessEvent);
-    return { refused: refused.reason, modeKept: null, note: null };
+    for (const { path, change } of pushing) {
+      const skipped = pushed.skipped.find((s) => s.path === path);
+      if (!skipped) {
+        const kept = pushed.modesKept.find((k) => k.path === path)?.reason;
+        if (kept) modeKept.set(path, kept);
+        continue;
+      }
+      refused.set(path, skipped.reason);
+      this.ctx?.pushEvent({
+        type: 'workspace:materialize-failed',
+        mount: mount.config.name,
+        path,
+        op: change.kind === 'set' ? 'write' : 'delete',
+        error: skipped.reason,
+      } as ProcessEvent);
+    }
+    return { refused, modeKept, notes };
   }
 
   // ==========================================================================
@@ -2821,13 +3686,24 @@ export class WorkspaceModule implements Module {
    * path, as a file tool names the one it acts on: a path the mount passes
    * over by design is observed, as a sync naming it would observe it (#276),
    * while a path in another mount's directory is refused before this, and
-   * passed over by any pass. The caller holds the mount's turn.
+   * passed over by any pass. Answers the pass's report on the path, and why
+   * the pass decided nothing where it did (undecidedOf), which leaves disk
+   * unchecked. The caller holds the mount's turn.
    */
-  private async ensureSynced(mount: MountState, relativePath: string): Promise<PathReport | undefined> {
+  private async ensureSynced(mount: MountState, relativePath: string): Promise<{ report: PathReport | undefined; undecided: string | null }> {
     const store = this.getStore();
-    if (store.treeGet(mount.treeStateId, relativePath)) return undefined;
+    if (store.treeGet(mount.treeStateId, relativePath)) return { report: undefined, undecided: null };
     const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true });
-    return pass.reports.get(relativePath);
+    return { report: pass.reports.get(relativePath), undecided: undecidedOf(pass) };
+  }
+
+  /**
+   * Why the workspace holds no entry at a path, after a pass over it that
+   * decided nothing: disk wasn't checked, so it may have a copy, and the same
+   * call made again checks it.
+   */
+  private notCheckedYet(path: string, reason: string): string {
+    return `${this.notInWorkspace(path, { path, state: 'unverified', note: reason })} Make the same call again, which checks disk first.`;
   }
 
   /** Why the workspace holds no entry at a path, when disk explains it. */
@@ -2850,6 +3726,63 @@ export class WorkspaceModule implements Module {
     }
   }
 
+  /**
+   * A file's bytes for read, from where the mount keeps what it reads: the
+   * workspace's copy, taken in from disk first where it holds none
+   * (ensureSynced); or, on a direct mount, disk's file as it is now
+   * (bytesOnDisk). An error says why there are none to read.
+   */
+  private async bytesOf(mount: MountState, relativePath: string, path: string): Promise<{ bytes: Buffer } | { error: string }> {
+    if (mount.direct) return this.bytesOnDisk(mount, relativePath, path);
+    const store = this.getStore();
+    return this.withMount(mount, async () => {
+      const { report } = await this.ensureSynced(mount, relativePath);
+      const entry = store.treeGet(mount.treeStateId, relativePath);
+      if (!entry) return { error: this.notInWorkspace(path, report) };
+      const blob = store.getBlob(entry.blobHash);
+      if (!blob) return { error: `Blob not found for: ${path}` };
+      return { bytes: blob };
+    });
+  }
+
+  /**
+   * A direct mount's file for read: its bytes on disk as they are now,
+   * through the mount's boundary as readFileFromDisk reaches them
+   * (openContainedFile), whose refusals are the answer. What a 'chronicle'
+   * mount never stores, it doesn't show either: a file over the mount's
+   * size limit, and a binary one, with a NUL in its first 8 KB, which
+   * read_image reads where it's an image.
+   */
+  private async bytesOnDisk(mount: MountState, relativePath: string, path: string): Promise<{ bytes: Buffer } | { error: string }> {
+    const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    const over = `${path} is over the size limit (${maxSize} bytes), so read doesn't show it.`;
+    let opened: Awaited<ReturnType<WorkspaceModule['openContainedFile']>>;
+    try {
+      opened = await this.openContainedFile(mount, relativePath, path, (fileStat) => {
+        if (fileStat.size > maxSize) throw new Error(over);
+      });
+    } catch (err) {
+      // A refusal that names only the path says why with its errno, as a
+      // failed read below does.
+      const bare = err instanceof WorkspaceReadError && err.errno !== undefined && err.message === `Unable to read file: ${path}`;
+      return { error: bare ? `${err.message} (${err.errno})` : err instanceof Error ? err.message : String(err) };
+    }
+    try {
+      // No more than the limit is loaded, as for a file over it at its fstat.
+      const { bytes, more } = await readPrefix(opened.handle, maxSize, opened.fileStat.size);
+      if (more) return { error: over };
+      if (looksBinary(bytes)) {
+        return { error: `${path} is binary, so read doesn't show it as text${sniffImageMime(bytes) ? '; read it with read_image.' : '.'}` };
+      }
+      return { bytes };
+    } catch (err) {
+      const errno = errnoOf(err);
+      return { error: `Unable to read file: ${path}${errno ? ` (${errno})` : ''}` };
+    } finally {
+      await opened.handle.close();
+    }
+  }
+
   // ==========================================================================
   // Tool Handlers
   // ==========================================================================
@@ -2867,17 +3800,9 @@ export class WorkspaceModule implements Module {
     if (content === undefined) {
       const { mount, relativePath, path } = await this.parseFilePath(input.path);
       input = { ...input, path };
-      const store = this.getStore();
-      const found = await this.withMount(mount, async (): Promise<{ text: string } | { error: string }> => {
-        const report = await this.ensureSynced(mount, relativePath);
-        const entry = store.treeGet(mount.treeStateId, relativePath);
-        if (!entry) return { error: this.notInWorkspace(input.path, report) };
-        const blob = store.getBlob(entry.blobHash);
-        if (!blob) return { error: `Blob not found for: ${input.path}` };
-        return { text: blob.toString('utf-8') };
-      });
+      const found = await this.bytesOf(mount, relativePath, path);
       if ('error' in found) return { success: false, error: found.error, isError: true };
-      content = found.text;
+      content = found.bytes.toString('utf-8');
     }
     if (characterPaging) {
       const start = Math.min(offsetChars, content.length);
@@ -2971,48 +3896,23 @@ export class WorkspaceModule implements Module {
     const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
     let treeError: WorkspaceImageReadError | null = null;
 
-    try {
-      const image = this.tryReadImageFromTree(mount, relativePath, input.path, maxSize);
-      if (image) {
-        return {
-          success: true,
-          data: [
-            {
-              type: 'text',
-              text: `Path: ${input.path}\nMIME: ${image.mimeType}\nBytes: ${image.bytes.byteLength}`,
-            },
-            {
-              type: 'image',
-              data: image.bytes.toString('base64'),
-              mimeType: image.mimeType,
-            },
-          ],
-        };
-      }
-    } catch (err) {
-      if (err instanceof WorkspaceImageReadError) {
-        treeError = err;
-      } else {
-        throw err;
+    // The workspace's copy first, where it holds one, then disk's. A direct
+    // mount holds none, so its image is disk's.
+    if (!mount.direct) {
+      try {
+        const image = this.tryReadImageFromTree(mount, relativePath, input.path, maxSize);
+        if (image) return imageResult(input.path, image);
+      } catch (err) {
+        if (err instanceof WorkspaceImageReadError) {
+          treeError = err;
+        } else {
+          throw err;
+        }
       }
     }
 
     try {
-      const image = await this.readImageFromFilesystem(mount, relativePath, input.path, maxSize);
-      return {
-        success: true,
-        data: [
-          {
-            type: 'text',
-            text: `Path: ${input.path}\nMIME: ${image.mimeType}\nBytes: ${image.bytes.byteLength}`,
-          },
-          {
-            type: 'image',
-            data: image.bytes.toString('base64'),
-            mimeType: image.mimeType,
-          },
-        ],
-      };
+      return imageResult(input.path, await this.readImageFromFilesystem(mount, relativePath, input.path, maxSize));
     } catch (err) {
       if (err instanceof WorkspaceImageReadError) {
         if (err.code === 'not_found' && treeError) {
@@ -3056,168 +3956,454 @@ export class WorkspaceModule implements Module {
       }));
     } catch (error) {
       if (!committed) throw error;
-      return storedButUnfinished('write', input.path, { threw: error instanceof Error ? error.message : String(error) });
+      return storedButUnfinished('write', input.path, error instanceof StoredThenFailed
+        ? { storeFailed: error.message, pushes: error.pushes }
+        : { threw: error instanceof Error ? error.message : String(error) });
     }
     if (refused !== null) return storedButUnfinished('write', input.path, { refused });
 
     return { success: true, data: { ...receipt, ...(modeKept ? { modeKept } : {}) } };
   }
 
-  private async handleEdit(input: EditInput): Promise<ToolResult> {
-    // Refused before anything is read: an empty oldString matches between
-    // every character, and UTF-8 can't store a lone surrogate.
-    if (input.oldString === '') {
-      return { success: false, isError: true, error: 'The edit did nothing: "oldString" is empty, and an empty string matches between every character. Give the text to replace.' };
+  private async handleEdit(input: EditInput, maxChars = DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS): Promise<ToolResult> {
+    return this.applyEdits('edit', [{
+      path: input.path,
+      oldString: input.oldString,
+      newString: input.newString,
+      expected: input.replaceAll ? 'all' : 1,
+    }], maxChars);
+  }
+
+  private async handleEditMany(
+    input: EditManyInput,
+    maxChars = DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS,
+    callerAgentName?: string,
+  ): Promise<ToolResult> {
+    if (input.edits.length === 0) {
+      return { success: false, isError: true, error: 'The edit_many call did nothing: "edits" is empty. Give at least one edit.' };
     }
-    for (const field of ['oldString', 'newString'] as const) {
-      if (LONE_SURROGATE.test(input[field])) {
-        return { success: false, isError: true, error: `The edit did nothing: "${field}" holds a lone UTF-16 surrogate, which UTF-8 can't store.` };
+    return this.applyEdits('edit_many', input.edits.map((edit) => ({
+      path: edit.path,
+      oldString: edit.oldString,
+      newString: edit.newString,
+      expected: edit.occurrences ?? 1,
+    })), maxChars, callerAgentName);
+  }
+
+  /**
+   * A call's edits, all or none, applied to the stored copies of their files:
+   * edit's one, or edit_many's in the files of one mount. Each edit is matched
+   * in its file's text as this call reads it, never in another edit's result
+   * (edit-plan.ts), and any problem refuses the call with none of its edits
+   * stored: edit names its first problem, and edit_many every problem found.
+   *
+   * Each edit's own input is checked first, and each path's mount. A problem
+   * there refuses edit at once, before any file's text is read, and edit_many
+   * when its edits name more than one mount, which no one pass settles.
+   * Otherwise edit_many goes on to settle and plan the rest, so its one
+   * refusal names the problems it finds; the settling is what a read or a
+   * listing of its files would take in from disk, and the refusal says what
+   * it took in. A failure before the commit sets the entries stores none of
+   * them, and edit_many's answer to it says so. A store that throws as it
+   * sets them is read back (commitToolChanges), so the answer says they're
+   * stored where its record landed, and that it can't tell where they
+   * couldn't be read back.
+   * Under the mount's turn, one pass settles every path with disk, by the
+   * rule a listing uses, so the edits apply to what disk now holds. That pass
+   * is the only step that awaits before the commit: every file is then read,
+   * every edit planned, and every entry set (commitToolChanges) with no turn
+   * of the event loop between, so no pass, branch change or other call moves
+   * the tree between a file's read and its set. Disk then takes what it can
+   * of the stored change.
+   *
+   * The answer is held to `maxChars`, the length the call's result may have
+   * (ToolCall.resultMaxChars), as edit-text.ts describes.
+   */
+  private async applyEdits(
+    tool: EditTool,
+    given: Array<{ path: string; oldString: string; newString: string; expected: number | 'all' }>,
+    maxChars: number,
+    callerAgentName?: string,
+  ): Promise<ToolResult> {
+    const refuse = (problems: EditProblem[], notes: string[] = []): ToolResult =>
+      ({ success: false, isError: true, error: refusalText(tool, problems, notes, maxChars) });
+
+    // Each edit's own input, before anything is read: an empty old text
+    // matches between every character, and UTF-8 can't store a lone surrogate.
+    const problems: EditProblem[] = [];
+    const specs = new Map<number, EditSpec>();
+    for (const [index, edit] of given.entries()) {
+      const spec: EditSpec = {
+        index,
+        oldText: edit.oldString.replaceAll('\r\n', '\n'),
+        newText: edit.newString.replaceAll('\r\n', '\n'),
+        expected: edit.expected,
+      };
+      const found = problems.length;
+      if (spec.oldText === '') {
+        problems.push({ kind: 'input', edit: index, text: '"oldString" is empty, and an empty string matches between every character. Give the text to replace.' });
+      } else if (spec.oldText === spec.newText) {
+        // An edit's new text takes the line ends of the text it replaces, so
+        // one whose only change is its line ends changes nothing.
+        problems.push({
+          kind: 'input',
+          edit: index,
+          text: edit.oldString !== edit.newString
+            ? "oldString and newString are the same once their CRLF line ends are read as LF, so there's nothing to change: an edit keeps the file's line ends, and write replaces the whole file, line ends included."
+            : "oldString and newString are the same, so there's nothing to change.",
+        });
       }
+      for (const field of ['oldString', 'newString'] as const) {
+        if (LONE_SURROGATE.test(edit[field])) {
+          problems.push({ kind: 'input', edit: index, text: `"${field}" holds a lone UTF-16 surrogate, which UTF-8 can't store.` });
+        }
+      }
+      if (problems.length === found) specs.set(index, spec);
     }
-    const { mount, relativePath, path } = await this.parseFilePath(input.path);
-    input = { ...input, path };
-    if (mount.config.mode === 'read-only') {
-      return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
+    // edit names its first problem, so one in its input refuses it before
+    // its path is looked up on disk.
+    if (tool === 'edit' && problems.length) return refuse(problems);
+
+    // Each path in its mount, as disk spells it, before any file's text is
+    // read. Edits of one stored path are one file, planned once from one
+    // text, whatever path named it, and named as disk spells it.
+    const parsed = new Map<string, { mount: MountState; relativePath: string; path: string } | Extract<EditProblem, { kind: 'file' }>>();
+    const targets = new Map<string, EditTarget>();
+    const mounts = new Map<string, MountState>();
+    for (const [index, { path }] of given.entries()) {
+      if (!parsed.has(path)) parsed.set(path, await this.editablePath(tool, path, callerAgentName));
+      const where = parsed.get(path)!;
+      if ('kind' in where) {
+        where.edits.push(index);
+        continue;
+      }
+      mounts.set(where.mount.config.name, where.mount);
+      const key = `${where.mount.config.name}/${where.relativePath}`;
+      let target = targets.get(key);
+      if (!target) targets.set(key, (target = { relativePath: where.relativePath, path: where.path, edits: [], specs: [] }));
+      target.edits.push(index);
+      const spec = specs.get(index);
+      if (spec) target.specs.push(spec);
+    }
+    for (const where of parsed.values()) if ('kind' in where) problems.push(where);
+    if (mounts.size > 1) {
+      problems.push({ kind: 'mounts', edits: [...targets.values()].flatMap((target) => target.edits), mounts: [...mounts.keys()] });
     }
+    const [mount] = mounts.values();
+    if (tool === 'edit' && problems.length) return refuse(problems);
+    if (!mount || mounts.size > 1) return refuse(problems);
 
     const store = this.getStore();
+    // Whether the commit set the call's entries, all of them at once.
     let committed = false;
-    let appliedNote: string | null = null;
+    // What each file's settling took in, for a receipt.
+    const applied = new Map<EditTarget, string | null>();
+    // The conflict each file's settling found, on a mount that doesn't push:
+    // the success answer names it, and so does the answer to a store that
+    // failed after recording the edits, which stand as on a success.
+    const conflicts = new Map<EditTarget, string>();
     try {
       return await this.withMount(mount, async (): Promise<ToolResult> => {
-        // The edit applies to the path as disk holds it now: a change on disk
-        // to a file the workspace holds is taken in first, by the rule a
-        // listing uses. The pass settles a pending intent on the path too, as
-        // settleBeforeMutation's would, and the commit enforces the rest
-        // (commitToolChange). A write passes over its path only to settle a
-        // pending intent, since it replaces the whole file. As every file
-        // tool's pass does, it names the path it acts on, so a file the
-        // mount passes over by design is observed (see PassOptions.named).
-        const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true });
-        const report = pass.reports.get(relativePath);
-        // A mode taken in alone isn't a change to the text: it brings nothing
-        // new to read, as it makes no event (emitFsEvents), and the edit then
-        // writes at the mode disk has, so it leaves nothing to say.
-        const took = (op: TreeOp) => pass.ops.some((o) => o.path === relativePath && o.op === op && !o.modeOnly);
-        // Which copy the edit used, when it isn't the one the workspace last
-        // agreed on with disk: disk's newer text, or the workspace's copy
-        // because disk's couldn't be read or disk has none. A file the
-        // workspace didn't hold has no older copy, so taking it in needs no
-        // word.
-        const whichCopy = (verb: string): string | null => took('modified')
-          ? `Disk's copy had changed since the workspace last agreed with it, so it was taken in first, and the edit ${verb} that text.`
-          : report?.state === 'unverified'
-            ? `The path couldn't be checked against disk (${report.note ?? 'not observed'}), so the edit ${verb} the workspace's copy.`
-            : report?.state === 'disk-missing-provenance-unknown'
-              ? `Disk has no copy of this file, and nothing records whether it was deleted there, so the edit ${verb} the workspace's copy.`
-              : null;
-        // A conflict the pass found is named when the edit is refused for the
-        // text it found, on either kind of mount, and on a success where the
-        // mount doesn't push, since such a mount keeps the conflict until
-        // materialize or sync settles it. A pushing mount's success met none
-        // (below). A stored edit that couldn't finish leaves it to the push's
-        // reason, which names the conflict, or to ls, which its answer points to.
-        const conflict = report?.state === 'conflict' ? report.conflict?.kind ?? 'both-changed' : null;
-        // Where disk has no copy now, whatever the conflict's kind, a sync of
-        // the path takes disk's deletion and a forced materialize writes the
-        // workspace's copy back. Where it has one, a sync keeps it and gives
-        // up the workspace's, whether or not the workspace can hold disk's
-        // copy: one it can't hold stays on disk alone.
-        const conflictNote = (where: string): string | null => conflict === null ? null
-          : `The path is in conflict with disk (${conflict}): the edit ${where} the workspace's copy. ` + (report?.diskNow === 'absent'
-            ? "Sync the path to take disk's deletion, which removes the workspace's copy, or materialize it with force to write the workspace's copy back to disk."
-            : "Sync the path to keep disk's copy and give up the workspace's, or materialize it with force to write the workspace's over disk's.");
-        const suffix = [whichCopy('looked in'), conflictNote('looked in')].filter((n) => n !== null).map((n) => ` ${n}`).join('');
-        appliedNote = whichCopy('applied to');
-
-        const entry = store.treeGet(mount.treeStateId, relativePath);
-        if (!entry) {
-          // A pass also drops a copy disk made binary or too large, which
-          // the disk-only answer describes; any other drop is disk's deletion.
-          const error = took('deleted') && report?.state !== 'disk-only'
-            ? `File not found: ${input.path}. Disk's copy was deleted since the workspace last agreed with it, and that was taken in first.`
-            : this.notInWorkspace(input.path, report);
-          return { success: false, error, isError: true };
-        }
-
-        const blob = store.getBlob(entry.blobHash);
-        if (!blob) {
-          return { success: false, error: `Blob not found for: ${input.path}`, isError: true };
-        }
-        // Decoding would turn each invalid sequence into U+FFFD, and writing
-        // the text back would change bytes the edit never named.
-        if (!isUtf8(blob)) {
-          return {
-            success: false,
-            isError: true,
-            error: `The edit did nothing: ${input.path} isn't valid UTF-8, so editing it would change bytes outside the text it replaces. `
-              + `Read shows each invalid byte sequence as U+FFFD, and a write replaces the whole file as UTF-8, so writing back what read shows puts U+FFFD in their place.${suffix}`,
-          };
-        }
-
-        let content = blob.toString('utf-8');
-
-        // An edit that would replace nothing is refused, replaceAll or not;
-        // without replaceAll, the text must occur once, and the refusal says
-        // how often it does. With replaceAll, whether it occurs is enough.
-        const count = input.replaceAll
-          ? Number(content.includes(input.oldString))
-          : content.split(input.oldString).length - 1;
-        if (count === 0) {
-          return { success: false, error: `String not found in ${input.path}.${suffix}`, isError: true };
-        }
-        if (count > 1 && !input.replaceAll) {
-          return {
-            success: false,
-            error: `String found ${count} times in ${input.path}. Use replaceAll: true or provide more context.${suffix}`,
-            isError: true,
-          };
+        // As every file tool's pass does, it names the paths it acts on, so a
+        // file the mount passes over by design is observed (see PassOptions.named).
+        const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [...targets.values()].map((target) => target.relativePath) }, { named: true });
+        // A pass that decided nothing checked no file's disk copy.
+        const undecided = undecidedOf(pass);
+        // Nothing below awaits until the commit's push.
+        const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+        const hints = hintBudget();
+        // As much as the largest file the call names holds, at least, so the
+        // budget is the same whatever order its files are planned in.
+        let largest = maxSize;
+        for (const target of targets.values()) largest = Math.max(largest, store.treeGet(mount.treeStateId, target.relativePath)?.size ?? 0);
+        const counts = countBudget(largest);
+        const notes: string[] = [];
+        const pushes = this.pushesOnCommit(mount);
+        const plans: Array<{ target: EditTarget; plan: FilePlan; mode: number; backOnDisk: string | null; conflictNote: string | null }> = [];
+        for (const target of targets.values()) {
+          const report = pass.reports.get(target.relativePath);
+          // A mode taken in alone isn't a change to the text: it brings nothing
+          // new to read, as it makes no event (emitFsEvents), and the edits
+          // then write at the mode disk has, so it leaves nothing to say.
+          const took = (op: TreeOp) => pass.ops.some((o) => o.path === target.relativePath && o.op === op && !o.modeOnly);
+          // Which copy the edits used, when it isn't the one the workspace
+          // last agreed on with disk: disk's newer text, or the workspace's
+          // copy because disk's couldn't be read or disk has none. A file the
+          // workspace didn't hold has no older copy, so taking it in needs no
+          // word.
+          const subject = tool === 'edit' ? 'the edit' : editList(target.edits);
+          // A pass that decided nothing checked no copy on disk, held or not,
+          // and took nothing in, so the edits would apply to text disk may
+          // have moved past, on whichever branch is selected once it gave up.
+          // They're refused, as a call made again can check.
+          if (undecided !== null) {
+            problems.push({
+              kind: 'file',
+              edits: target.edits,
+              path: target.path,
+              text: `${target.path} couldn't be checked against disk (${undecided}), so ${subject} changed nothing. Make the same call again, which checks disk first.`,
+              whole: true,
+            });
+            continue;
+          }
+          const whichCopy = (verb: string): string | null => took('modified')
+            ? `Disk's copy${tool === 'edit' ? '' : ` of ${target.path}`} had changed since the workspace last agreed with it, so it was taken in first, and ${subject} ${verb} that text.`
+            : report?.state === 'unverified'
+              ? `${tool === 'edit' ? 'The path' : target.path} couldn't be checked against disk (${report.note ?? 'not observed'}), so ${subject} ${verb} the workspace's copy.`
+              : report?.state === 'disk-missing-provenance-unknown'
+                ? `Disk has no copy of ${tool === 'edit' ? 'this file' : target.path}, and nothing records whether it was deleted there, so ${subject} ${verb} the workspace's copy.`
+                : null;
+          // A conflict the pass found is named when the edits are refused for
+          // the text they found, on either kind of mount, and on a success
+          // where the mount doesn't push, since such a mount keeps the conflict
+          // until materialize or sync settles it. A pushing mount's push that
+          // completed met none: unforced, it stops at a conflict, so the edits
+          // made the two copies agree, which settles it, or there was none.
+          // Edits stored that couldn't finish leave it to the push's reason,
+          // which names the conflict, or to ls, which that answer points to
+          // when the rest of the call failed; where the store failed after
+          // recording them, the answer names it as the success does.
+          // What a sync does follows what disk holds now, whatever kind the
+          // conflict was recorded as: where disk has no copy, it takes the
+          // deletion; where disk has one, it keeps disk's copy and gives up
+          // the workspace's, though a copy the workspace can't hold, binary
+          // or past maxFileSize, isn't taken in.
+          const conflict = report?.state === 'conflict' ? report.conflict?.kind ?? 'both-changed' : null;
+          const conflictNote = (where: string): string | null => conflict === null ? null
+            : `${tool === 'edit' ? 'The path' : target.path} is in conflict with disk (${conflict}): ${subject} ${where} the workspace's copy. `
+              + (report?.diskNow === 'absent'
+                ? "Sync the path to take disk's deletion, which removes the workspace's copy, or materialize it with force to write the workspace's copy back to disk."
+                : "Sync the path to keep disk's copy and give up the workspace's, or materialize it with force to write the workspace's over disk's.");
+          applied.set(target, whichCopy('applied to'));
+          // The edits make the path the workspace's own change, so a file disk
+          // lacked goes back with this call's push, or with the next
+          // materialize where the mount doesn't push. A push that didn't
+          // complete answers with its reason instead.
+          const backOnDisk = report?.state !== 'disk-missing-provenance-unknown' ? null
+            : tool === 'edit'
+              ? `${pushes ? 'Its push put the file back on disk' : 'A materialize of the path puts it back on disk'}; if it was deleted there on purpose, delete it here too.`
+              : `${pushes ? `This call's push put ${target.path} back on disk` : `A materialize of ${target.path} puts it back on disk`}; if it was deleted there on purpose, delete it here too.`;
+          const lookedIn = [whichCopy('looked in'), conflictNote('looked in')].filter((note): note is string => note !== null);
+
+          const entry = store.treeGet(mount.treeStateId, target.relativePath);
+          if (!entry) {
+            // A pass also drops a copy disk made binary or too large, which
+            // the disk-only answer describes; any other drop is disk's deletion.
+            const text = took('deleted') && report?.state !== 'disk-only'
+              ? `File not found: ${target.path}. Disk's copy was deleted since the workspace last agreed with it, and that was taken in first.`
+              : this.notInWorkspace(target.path, report);
+            problems.push({ kind: 'file', edits: target.edits, path: target.path, text, whole: true });
+            continue;
+          }
+          notes.push(...lookedIn);
+          const blob = store.getBlob(entry.blobHash);
+          if (!blob) {
+            problems.push({ kind: 'file', edits: target.edits, path: target.path, text: `Blob not found for: ${target.path}`, whole: true });
+            continue;
+          }
+          // Decoding would turn each invalid sequence into U+FFFD, and writing
+          // the text back would change bytes the edits never named.
+          const file = decodeForEdit(blob);
+          if (!file) {
+            problems.push({
+              kind: 'file',
+              edits: target.edits,
+              path: target.path,
+              text: `${target.path} isn't valid UTF-8, so editing it would change bytes outside the text it replaces. `
+                + 'Read shows each invalid byte sequence as U+FFFD, and a write replaces the whole file as UTF-8, so writing back what read shows puts U+FFFD in their place.',
+              whole: false,
+            });
+            continue;
+          }
+          if (!target.specs.length) continue;
+          const planned = planFile(file, blob, target.specs, hints, maxSize, counts);
+          if ('problems' in planned) {
+            // One at a time: a call of many edits can have more problems
+            // than a spread passes as arguments.
+            for (const problem of planned.problems) problems.push({ ...problem, path: target.path });
+            continue;
+          }
+          // The planner refuses a file its counts take past the limit before
+          // building it, from the least its bytes can be; one it built past
+          // the limit, as its CRs or multi-byte characters can take it, is
+          // refused here.
+          if ('tooLarge' in planned || planned.plan.bytes.length > maxSize) {
+            const size = 'tooLarge' in planned ? `at least ${planned.tooLarge.toLocaleString('en-US')}` : planned.plan.bytes.length.toLocaleString('en-US');
+            problems.push({
+              kind: 'file',
+              edits: target.edits,
+              path: target.path,
+              text: `${target.path} would be ${size} bytes with ${tool === 'edit' ? 'this edit' : editList(target.edits)}, `
+                + `past the ${maxSize.toLocaleString('en-US')}-byte limit this mount sets on a file, so the workspace couldn't keep it. `
+                + "An edit that leaves the file within the limit applies. The limit is the mount's maxFileSize setting, which only whoever runs the host can change.",
+              whole: false,
+            });
+            continue;
+          }
+          plans.push({
+            target,
+            plan: planned.plan,
+            mode: entry.mode,
+            backOnDisk,
+            conflictNote: pushes ? null : conflictNote(tool === 'edit' || target.edits.length === 1 ? 'is in' : 'are in'),
+          });
+          const conflicted = plans.at(-1)!.conflictNote;
+          if (conflicted !== null) conflicts.set(target, conflicted);
         }
+        if (problems.length) return refuse(problems, notes);
 
-        // A replacer function, so that the new text goes in as given: in a
-        // replacement string, $&, $$, $' and $` are patterns.
-        content = input.replaceAll
-          ? content.replaceAll(input.oldString, () => input.newString)
-          : content.replace(input.oldString, () => input.newString);
-
-        const newBuffer = Buffer.from(content, 'utf-8');
-        const newBlobHash = store.storeBlob(newBuffer, 'text/plain');
-        const { refused, modeKept } = await this.commitToolChange(mount, relativePath, {
-          kind: 'set',
-          blobHash: newBlobHash,
-          size: newBuffer.byteLength,
-          mode: entry.mode,
-        }, () => { committed = true; });
-        if (refused !== null) return storedButUnfinished('edit', input.path, { refused }, appliedNote);
-
-        // The edit makes the path the workspace's own change (commitToolChange),
-        // so a file disk lacked goes back with this edit's push, or with the
-        // next materialize where the mount doesn't push. A push that didn't
-        // complete answers above, with its reason. One that completed met no
-        // conflict, since this push, unforced, stops at one: the edit made the
-        // two copies agree, which settles it, or there was none. So only a
-        // mount that doesn't push still holds the conflict the pass found.
-        const pushes = this.pushesOnCommit(mount);
-        const backOnDisk = report?.state === 'disk-missing-provenance-unknown'
-          ? `${pushes ? 'Its push put the file back on disk' : 'A materialize of the path puts it back on disk'}; if it was deleted there on purpose, delete it here too.`
-          : null;
-        const notes = [appliedNote, backOnDisk, pushes ? null : conflictNote('is in')].filter((n): n is string => n !== null);
+        const { refused, modeKept } = await this.commitToolChanges(mount, plans.map(({ target, plan, mode }) => ({
+          path: target.relativePath,
+          change: { kind: 'set' as const, blobHash: store.storeBlob(plan.bytes, 'text/plain'), size: plan.bytes.length, mode },
+        })), () => { committed = true; });
+        if (refused.size > 0) return this.editsStoredButUnfinished(tool, [...targets.values()], applied, conflicts, { refused, modeKept }, maxChars);
         return {
           success: true,
-          data: {
-            path: input.path,
-            size: newBuffer.byteLength,
-            ...(notes.length > 0 ? { note: notes.join(' ') } : {}),
-            ...(modeKept ? { modeKept } : {}),
-          },
+          data: editReceipt(tool, plans.map(({ target, plan, backOnDisk, conflictNote }) => ({
+            path: target.path,
+            plan,
+            notes: [applied.get(target) ?? null, backOnDisk, conflictNote].filter((note): note is string => note !== null),
+            modeKept: modeKept.get(target.relativePath) ?? null,
+          })), given.length, maxChars),
         };
       });
     } catch (error) {
-      if (!committed) throw error;
-      return storedButUnfinished('edit', input.path, { threw: error instanceof Error ? error.message : String(error) }, appliedNote);
+      const message = error instanceof Error ? error.message : String(error);
+      if (committed) {
+        return this.editsStoredButUnfinished(tool, [...targets.values()], applied, conflicts, error instanceof StoredThenFailed
+          ? { storeFailed: message, pushes: error.pushes }
+          : { threw: message }, maxChars);
+      }
+      // A set that threw and couldn't be read back may have stored the edits,
+      // and a second call could then apply them twice.
+      if (error instanceof CommitUnknownError) {
+        const [set, read] = [cutLine(error.setError), cutLine(error.readError)];
+        return {
+          success: false,
+          isError: true,
+          error: tool === 'edit_many'
+            ? `The edit_many call can't tell whether it stored its edits: the store failed as it set them (${set}), and reading them back failed too (${read}). `
+              + 'Read its files before sending it again: a second call can apply its edits twice.'
+            : `Whether the edit of "${[...targets.values()][0]!.path}" is stored isn't known: the store failed as it set it (${set}), and reading it back failed too (${read}). `
+              + 'Read the file before sending the edit again: a second edit can apply the change twice.',
+        };
+      }
+      // The commit sets every entry in one record or none, and a set that
+      // threw was read back, so nothing is stored; or every change was one
+      // the tree already held, which leaves the tree as it was either way.
+      if (tool === 'edit_many') return { success: false, isError: true, error: `The edit_many call stored none of its edits: ${cutLine(message)}` };
+      throw error;
+    }
+  }
+
+  /**
+   * Where an edit's path is in its mount, or why the call can't edit it: a
+   * path no mount holds, one outside its mount or holding a lone surrogate
+   * (parsePath), one a nested mount holds or that leads into one through a
+   * link (parseFilePath), a path that names its mount's root, a read-only
+   * mount, or for edit_many a generated file. edit's
+   * generated file is refused before it gets here, by the same rule
+   * (handleToolCall checks a call's `path`, which edit_many's input lacks).
+   */
+  private async editablePath(
+    tool: EditTool,
+    path: string,
+    callerAgentName: string | undefined,
+  ): Promise<{ mount: MountState; relativePath: string; path: string } | Extract<EditProblem, { kind: 'file' }>> {
+    const unusable = (text: string) => ({ kind: 'file' as const, edits: [], path, text, whole: true });
+    try {
+      // In the one spelling every file tool reads, as disk spells it, so two
+      // spellings of a file are one entry and, in one call, one plan
+      // (parsePathAsGiven); and a path in a mount nested inside this one is
+      // that mount's, which every file tool refuses here (parseFilePath).
+      const where = await this.parseFilePath(path);
+      // One that names the mount's root, its bare name included, names no
+      // file.
+      if (where.relativePath === '') return unusable(`${path} names the root of mount "${where.mount.config.name}", which isn't a file; ls ${where.mount.config.name} lists the files in it.`);
+      if (where.mount.config.mode === 'read-only') return unusable(`Mount "${where.mount.config.name}" is read-only`);
+      const generated = tool === 'edit_many' ? this.findGeneratedTextFile(path) : undefined;
+      if (generated) return unusable(`${path}: ${this.generatedFileRefusal(generated, callerAgentName)}.`);
+      return where;
+    } catch (error) {
+      return unusable(error instanceof Error ? error.message : String(error));
     }
   }
 
+  /**
+   * Why a call can't change a generated file: another agent's is that agent's,
+   * and the agent's own is read-only, since it shows the agent's tool
+   * presentation, which set_tool_visibility and set_tool_description change.
+   */
+  private generatedFileRefusal(generated: { agentName: string }, callerAgentName: string | undefined): string {
+    return callerAgentName !== generated.agentName
+      ? 'Generated file belongs to another agent'
+      : 'Generated file is read-only; change the tool presentation it shows with set_tool_visibility or set_tool_description instead';
+  }
+
+  /**
+   * The answer to edits stored but not finished: the commit set every file's
+   * entry, and then disk refused some of their pushes, or the store failed
+   * after recording them, so their push didn't run, or the rest of the call
+   * failed. It stays an error, since part of the call failed, and leads with
+   * what is stored, which must not be sent again: a second call can apply
+   * those edits twice. edit's is the answer write and delete give, one path's;
+   * edit_many's lists the files disk refused, each with its push's reason,
+   * notes each file disk took with its mode left as disk had it, as the
+   * success answer's `modeKept` does, within `maxChars`, and never says to
+   * send the call again. Where the store failed after recording the edits,
+   * which stand as on a success, it names each conflict the success answer
+   * would (`conflicts`, found only where the mount doesn't push).
+   */
+  private editsStoredButUnfinished(
+    tool: EditTool,
+    targets: EditTarget[],
+    applied: Map<EditTarget, string | null>,
+    conflicts: Map<EditTarget, string>,
+    outcome: { refused: Map<string, string>; modeKept: Map<string, string> } | { threw: string } | { storeFailed: string; pushes: boolean },
+    maxChars: number,
+  ): ToolResult {
+    const conflictOf = (target: EditTarget) => ('storeFailed' in outcome ? conflicts.get(target) ?? null : null);
+    if (tool === 'edit') {
+      const [target] = targets;
+      const note = [applied.get(target!) ?? null, conflictOf(target!)].filter((text): text is string => text !== null).join(' ');
+      return storedButUnfinished('edit', target!.path, 'refused' in outcome ? { refused: outcome.refused.get(target!.relativePath)! } : outcome, note || null);
+    }
+    const stored = "Every edit of this call is stored in the workspace, so don't send the call again: a second call can apply its edits twice.";
+    // The head is never cut, so what stands for the whole call goes in it,
+    // and the parts are the files disk refused, each with its push's reason.
+    let head: string;
+    const parts: string[] = [];
+    if ('refused' in outcome) {
+      const files = targets.length;
+      const refused = outcome.refused.size;
+      head = `${stored}\n\n${files === 1
+        ? "Disk didn't take the call's one file. Its push didn't complete:"
+        : `Disk took ${files - refused} of the call's ${files} files. ${refused === 1
+          ? "This file's push didn't complete:"
+          : "These files' pushes didn't complete, each with its reason:"}`}`;
+      for (const target of targets) {
+        const reason = outcome.refused.get(target.relativePath);
+        if (reason !== undefined) parts.push(`${target.path}: ${reason}`);
+      }
+    } else if ('storeFailed' in outcome) {
+      head = `${stored}\n\nThe store failed after recording them: ${cutLine(outcome.storeFailed)}.`
+        + (outcome.pushes ? " Their push to disk didn't run, so disk lacks them until a materialize of their files writes them." : '');
+    } else {
+      head = `${stored}\n\nThe rest of the call failed: ${cutLine(outcome.threw)}. ls shows each path's state.`;
+    }
+    const kept = 'modeKept' in outcome
+      ? targets.flatMap((target) => {
+        const reason = outcome.modeKept.get(target.relativePath);
+        return reason === undefined ? [] : [`Disk took ${target.path}: ${reason}.`];
+      })
+      : [];
+    const notes = [
+      ...kept,
+      ...targets.flatMap((target) => [applied.get(target) ?? null, conflictOf(target)]).filter((note): note is string => !!note),
+    ];
+    return { success: false, isError: true, error: fitted(head, parts, notes, maxChars, 'stored') };
+  }
+
   private async handleDelete(input: DeleteInput): Promise<ToolResult> {
     const { mount, relativePath, path } = await this.parseFilePath(input.path);
     input = { ...input, path };
@@ -3229,11 +4415,12 @@ export class WorkspaceModule implements Module {
     let committed = false;
     try {
       return await this.withMount(mount, async (): Promise<ToolResult> => {
-        const report = await this.ensureSynced(mount, relativePath);
+        const { report, undecided } = await this.ensureSynced(mount, relativePath);
         await this.settleBeforeMutation(mount, relativePath);
         const entry = store.treeGet(mount.treeStateId, relativePath);
         if (!entry) {
-          return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
+          const error = undecided !== null ? this.notCheckedYet(input.path, undecided) : this.notInWorkspace(input.path, report);
+          return { success: false, error, isError: true };
         }
 
         const { refused, note } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash },
@@ -3250,68 +4437,162 @@ export class WorkspaceModule implements Module {
       });
     } catch (error) {
       if (!committed) throw error;
+      if (error instanceof StoredThenFailed) {
+        // Its note, as the success answer's: a deletion that cleared a
+        // conflict naming a disk file unlinked nothing.
+        const note = error.notes.get(relativePath);
+        return storedButUnfinished('delete', input.path, { storeFailed: error.message, pushes: error.pushes },
+          note === undefined ? null : `${note.charAt(0).toUpperCase()}${note.slice(1)}.`);
+      }
       return storedButUnfinished('delete', input.path, { threw: error instanceof Error ? error.message : String(error) });
     }
   }
 
   private async handleLs(input: LsInput): Promise<ToolResult> {
-    const store = this.getStore();
-
     if (!input.path) {
-      // List all mounts
+      // List all mounts, with the kind a mount configured direct runs as
+      // this session and the ignore list it walks by, whose default no
+      // config shows, and each with its include where it has one, so the
+      // files a mount holds show before a path outside them is refused.
       const mounts = [...this.mounts.entries()].map(([name, m]) => ({
         name,
         path: m.config.path,
         mode: m.config.mode,
+        ...(m.config.backend === 'direct' ? { backend: m.direct ? 'direct' : 'chronicle', ignore: this.ignoreOf(m) } : {}),
+        ...(m.config.include ? { include: [...m.config.include] } : {}),
       }));
       return { success: true, data: { mounts } };
     }
 
-    const { mount, relativePath, path } = await this.parsePath(input.path);
+    const { mount, relativePath, path, moved, root } = await this.parsePath(input.path);
+    // A path outside the mount's include that's no scope (refusesAsOutside)
+    // is refused, as glob refuses it, and shown as given.
+    if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
+      return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+    }
     input = { ...input, path };
     const recursive = input.recursive === true;
 
     // Every listing checks the paths it shows against disk first, under the
-    // three-way rule, whatever the mount's watch mode.
-    return this.withMount(mount, async (): Promise<ToolResult> => {
-      const pass = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive });
-      const reports = [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path));
-      const incomplete = pass.incomplete.length > 0 ? { incomplete: pass.incomplete } : {};
-
-      if (recursive) {
-        return {
-          success: true,
-          data: {
-            path: input.path,
-            entries: reports.map((r) => ({ path: r.path, ...stateView(r) })),
-            count: reports.length,
-            ...incomplete,
-          },
-        };
-      }
-
-      // Non-recursive: the scope's files, and the directories beneath it that
-      // disk or the workspace has.
-      const prefix = relativePath ? relativePath + '/' : '';
-      const dirNames = new Set(pass.dirs.map((d) => d.slice(prefix.length)));
-      for (const entry of store.treeList(mount.treeStateId, prefix || undefined)) {
-        const slash = entry.path.indexOf('/', prefix.length);
-        if (slash >= 0) dirNames.add(entry.path.slice(prefix.length, slash));
-      }
-      const children: Array<Record<string, unknown>> = [
-        ...[...dirNames].sort().map((name) => ({ name, type: 'directory' })),
-        ...reports.map((r) => ({ name: r.path.slice(prefix.length), type: 'file', ...stateView(r) })),
-      ];
+    // three-way rule, whatever the mount's watch mode; a direct mount's
+    // shows disk's.
+    const listing = await this.listingOf(mount, relativePath, recursive);
+    const incomplete = listing.incomplete.length > 0 ? { incomplete: listing.incomplete } : {};
+    if (recursive) {
       return {
         success: true,
         data: {
           path: input.path,
-          entries: children,
-          count: children.length,
+          entries: listing.files,
+          count: listing.files.length,
           ...incomplete,
         },
       };
+    }
+
+    // Non-recursive: the scope's files, and the directories beneath it.
+    const prefix = relativePath ? relativePath + '/' : '';
+    const children: Array<Record<string, unknown>> = [
+      ...listing.dirs.map((d) => d.slice(prefix.length)).sort().map((name) => ({ name, type: 'directory' })),
+      ...listing.files.map(({ path: file, ...view }) => ({ name: file.slice(prefix.length), type: 'file', ...view })),
+    ];
+    return {
+      success: true,
+      data: {
+        path: input.path,
+        entries: children,
+        count: children.length,
+        ...incomplete,
+      },
+    };
+  }
+
+  /**
+   * What a listing shows of a directory scope, from where the mount keeps
+   * what it reads: the store-backed kind's pass (listingFromStore), or, on a
+   * direct mount, disk (listingFromDisk). `keep` chooses the files shown.
+   */
+  private listingOf(mount: MountState, dir: string, recursive: boolean, keep?: (path: string) => boolean): Promise<Listing> {
+    return mount.direct ? this.listingFromDisk(mount, dir, recursive, keep) : this.listingFromStore(mount, dir, recursive, keep);
+  }
+
+  /**
+   * A 'chronicle' mount's listing: a pass over the scope under the three-way
+   * rule, each path it decided with its state, and the directories beneath
+   * the scope that disk or the workspace has.
+   */
+  private listingFromStore(mount: MountState, dir: string, recursive: boolean, keep?: (path: string) => boolean): Promise<Listing> {
+    const store = this.getStore();
+    return this.withMount(mount, async (): Promise<Listing> => {
+      const pass = await this.passUnlocked(mount, { kind: 'dir', dir, recursive });
+      const files = [...pass.reports.values()]
+        .sort((a, b) => a.path.localeCompare(b.path))
+        .filter((report) => keep === undefined || keep(report.path))
+        .map((report) => ({ path: report.path, ...stateView(report) }));
+      if (recursive) return { files, dirs: [], incomplete: pass.incomplete };
+      // Read with the pass's reports, on the branch it decided on, before
+      // anything else takes the mount's turn.
+      const dirs = new Set(pass.dirs);
+      const prefix = dir ? dir + '/' : '';
+      // History implies a directory only where it's the mount's own to name
+      // (withinIncludes): not history in a nested mount's directory that
+      // that mount's include leaves out.
+      const own = { include: mount.config.include, nested: this.nestedOf(mount.config.name) };
+      for (const entry of store.treeList(mount.treeStateId, prefix || undefined)) {
+        if (!withinIncludes(own, entry.path)) continue;
+        const slash = entry.path.indexOf('/', prefix.length);
+        if (slash >= 0) dirs.add(entry.path.slice(0, slash));
+      }
+      return { files, dirs: [...dirs], incomplete: pass.incomplete };
+    });
+  }
+
+  /**
+   * A direct mount's listing: its walk of the scope (diskWalk), with each
+   * entry it took as disk has it now, observed as a pass observes it: a
+   * file's size, or why the mount doesn't take it (a link it doesn't follow,
+   * one that leaves the mount, what isn't a regular file). A file gone since
+   * the walk listed it is no longer there to show.
+   */
+  private async listingFromDisk(mount: MountState, dir: string, recursive: boolean, keep?: (path: string) => boolean): Promise<Listing> {
+    const { view, rootReal, taken, dirs, incomplete } = await this.diskWalk(mount, dir, recursive);
+    const files: Listing['files'] = [];
+    await inOrder(taken.filter((path) => keep === undefined || keep(path)), DIRECT_READS_AT_ONCE, (path) => observePath(view, rootReal, path), (seen, path) => {
+      if (seen.kind === 'file') files.push({ path, size: seen.size });
+      else if (seen.kind === 'unobserved') files.push({ path, note: seen.reason });
     });
+    return { files, dirs, incomplete };
+  }
+
+  /**
+   * A direct mount's walk of a scope, from its view (diskView): the entries
+   * it took that aren't directories (files, links and the like), in path
+   * order; the directories directly beneath a scope it doesn't descend; and
+   * the regions it couldn't see that a pass reports beside no tracked file:
+   * what it couldn't list, what the cap left, and a scope in another mount's
+   * directory, said as a listing says it. A path the walk names is walked
+   * whatever the mount's ignore list or an editor's file name covers there
+   * (MountConfig.ignore), as a path sync's walk is.
+   */
+  private async diskWalk(mount: MountState, dir: string, recursive: boolean): Promise<{
+    view: MountView; rootReal: string; taken: string[]; dirs: string[]; incomplete: Array<{ path: string; reason: string }>;
+  }> {
+    const { view, rootReal, moved } = await this.diskView(mount);
+    const walk = await walkScope(view, rootReal, dir, recursive, mount.config.walkCap ?? WALK_CAP, { named: true });
+    const incomplete = walk.incomplete
+      .filter((region) => region.kind === 'error' || region.kind === 'cap' || (region.kind === 'ignored' && region.path === dir && dir !== ''))
+      .map((region) => ({
+        path: region.path,
+        reason: region.reason === OTHER_MOUNT ? this.otherMountNote(mount.config.name, region.path, 'list', moved) : region.reason,
+      }));
+    return {
+      view,
+      rootReal,
+      taken: [...walk.files, ...walk.othersTaken].sort((a, b) => a.localeCompare(b)),
+      // A walk that doesn't descend sees the scope's own subdirectories alone.
+      dirs: recursive ? [] : [...walk.dirs],
+      incomplete,
+    };
   }
 
   private async handleGlob(input: GlobInput): Promise<ToolResult> {
@@ -3322,7 +4603,16 @@ export class WorkspaceModule implements Module {
     // Search across mounts
     const mountsToSearch = input.path
       ? [await this.parsePath(input.path)]
-      : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
+      : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '', moved: null, root: resolve(m.config.path) }));
+    // The path is a directory to search in. One outside the mount's include
+    // that's no scope (refusesAsOutside) is refused, as grep refuses it,
+    // rather than searched and reported as matching nothing.
+    if (input.path) {
+      const { mount, relativePath, moved, root } = mountsToSearch[0]!;
+      if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
+        return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+      }
+    }
 
     // Every match lies beneath the pattern's literal directory, so the walk
     // starts there: past the walk's cap, a walk of the whole scope can stop
@@ -3330,15 +4620,10 @@ export class WorkspaceModule implements Module {
     const patternDir = literalDirOf(input.pattern);
     for (const { mount, relativePath } of mountsToSearch) {
       const start = await this.walkStart(mount, relativePath, patternDir);
-      const pass = await this.withMount(mount, () =>
-        this.passUnlocked(mount, { kind: 'dir', dir: start, recursive: true }));
-      for (const report of [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path))) {
-        const testPath = relativePath ? report.path.slice(relativePath.length + 1) : report.path;
-        if (regex.test(testPath)) {
-          matches.push({ path: `${mount.config.name}/${report.path}`, ...stateView(report) });
-        }
-      }
-      for (const region of pass.incomplete) {
+      const matched = (path: string) => regex.test(relativePath ? path.slice(relativePath.length + 1) : path);
+      const listing = await this.listingOf(mount, start, true, matched);
+      for (const { path, ...view } of listing.files) matches.push({ path: `${mount.config.name}/${path}`, ...view });
+      for (const region of listing.incomplete) {
         incomplete.push({ path: `${mount.config.name}/${region.path}`, reason: region.reason });
       }
     }
@@ -3355,7 +4640,6 @@ export class WorkspaceModule implements Module {
   }
 
   private async handleGrep(input: GrepInput): Promise<ToolResult> {
-    const store = this.getStore();
     let regex: RegExp;
     try {
       regex = new RegExp(input.pattern);
@@ -3374,11 +4658,19 @@ export class WorkspaceModule implements Module {
 
     const mountsToSearch = input.path
       ? [await this.parsePath(input.path)]
-      : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
+      : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '', moved: null, root: resolve(m.config.path) }));
+    // A path outside the mount's include that's no scope is refused, as read
+    // refuses it, rather than searched and reported as holding no match.
+    if (input.path) {
+      const { mount, relativePath, moved, root } = mountsToSearch[0]!;
+      if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
+        return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+      }
+    }
 
     type GrepMatch = { line: number; text: string; context?: string[] };
-    const results: Array<{ file: string; state: string; version: 'workspace' | 'conflicting-disk' | 'recorded-disk'; matches: GrepMatch[] }> = [];
-    const skipped: Array<{ file: string; reason: string; size?: number; mimeType?: string }> = [];
+    const results: Array<{ file: string; state?: string; version: GrepText['version']; matches: GrepMatch[] }> = [];
+    const skipped: GrepSkip[] = [];
     const incomplete: Array<{ path: string; reason: string }> = [];
 
     const search = (content: string): GrepMatch[] => {
@@ -3398,12 +4690,13 @@ export class WorkspaceModule implements Module {
       return found;
     };
 
-    for (const { mount, relativePath } of mountsToSearch) {
+    for (const { mount, relativePath, moved, root } of mountsToSearch) {
       // A path named in another mount's directory, as holderOf resolves it,
       // is that mount's: grep searches nothing of this mount's there, and
-      // says whose it is.
-      if (this.holderOf(mount.config.name, relativePath)) {
-        incomplete.push({ path: `${mount.config.name}/${relativePath}`, reason: this.otherMountNote(mount.config.name, relativePath, 'list') });
+      // says whose it is. A direct mount's is judged by the nesting its parse
+      // found where its root lies now (movedNesting).
+      if (this.holderOf(mount.config.name, relativePath, false, moved)) {
+        incomplete.push({ path: `${mount.config.name}/${relativePath}`, reason: this.otherMountNote(mount.config.name, relativePath, 'list', moved) });
         continue;
       }
       // A `path` and a filter whose directories don't overlap leave no file
@@ -3411,110 +4704,16 @@ export class WorkspaceModule implements Module {
       const deeper = deeperOf(relativePath, filterDir);
       if (deeper === null) continue;
       const start = await this.walkStart(mount, relativePath, deeper === relativePath ? '' : deeper.slice(relativePath ? relativePath.length + 1 : 0));
-      await this.withMount(mount, async () => {
-        // A `path` naming a single file greps just that file; otherwise it is a
-        // directory prefix. (A file path once produced the prefix "notes.md/"
-        // and silently matched nothing.)
-        const fileScope = relativePath !== '' && (
-          store.treeGet(mount.treeStateId, relativePath) !== null ||
-          await lstat(join(mount.config.path, relativePath)).then((s) => !s.isDirectory(), () => false)
-        );
-        // What follows reads the tree and branch intent to go with the pass's
-        // reports, synchronously. They must be the branch the pass decided
-        // on: one selected in between would label its content with the other
-        // branch's states. So a pass whose branch is no longer selected runs
-        // again, and a branch that keeps changing leaves the scope unsearched.
-        //
-        // A copy held at a path that now leads into a nested mount's directory
-        // through a link is that mount's file too: read refuses it
-        // (parseFilePath), so grep searches none of it and says why. The pass
-        // can't check such a path's disk, so only an unverified one can be
-        // one. Asking awaits disk, so it's done before the branch is
-        // compared, and a branch selected meanwhile runs the pass again.
-        let pass: PassResult | null = null;
-        let refused = new Map<string, string>();
-        for (let attempt = 0; attempt < 3 && pass === null; attempt++) {
-          const next = await this.passUnlocked(mount, fileScope
-            ? { kind: 'paths', paths: [relativePath] }
-            : { kind: 'dir', dir: start, recursive: true });
-          const asked = new Map<string, string>();
-          for (const report of next.reports.values()) {
-            if (report.state !== 'unverified') continue;
-            const refusal = await this.leadsIntoNested(mount, report.path, `${mount.config.name}/${report.path}`);
-            if (refusal) asked.set(report.path, refusal.message);
-          }
-          if (next.branchId === undefined || next.branchId === store.currentBranch().id) {
-            pass = next;
-            refused = asked;
-          }
-        }
-        if (pass === null) {
-          incomplete.push({
-            path: `${mount.config.name}/${relativePath}`,
-            reason: 'the selected branch kept changing while grep ran; nothing here was searched — grep again',
-          });
-          return;
-        }
-        for (const region of pass.incomplete) {
-          incomplete.push({ path: `${mount.config.name}/${region.path}`, reason: region.reason });
-        }
-
-        const intents = this.intents.get(mount.config.name)!;
-        for (const report of [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path))) {
-          if (fileGlob && !fileGlob.test(report.path)) continue;
-          const file = `${mount.config.name}/${report.path}`;
-          if (report.state === 'disk-only') {
-            skipped.push({
-              file,
-              reason: 'disk-only: binary or over the size limit, never stored',
-              ...(report.size !== undefined ? { size: report.size } : {}),
-              ...(report.mimeType ? { mimeType: report.mimeType } : {}),
-            });
-            continue;
-          }
-          // A path in another mount's directory is that mount's: grep gives
-          // none of this mount's copy of it, as read refuses it. Beneath a
-          // scope it's passed over by design, like the directory.
-          if (inOtherMount(report.path, this.othersOf(mount.config.name))) continue;
-          const refusal = refused.get(report.path);
-          if (refusal !== undefined) {
-            skipped.push({ file, reason: refusal });
-            continue;
-          }
-          // The workspace's version, labelled with the path's state.
-          const entry = store.treeGet(mount.treeStateId, report.path);
-          const blob = entry ? store.getBlob(entry.blobHash) : null;
-          if (blob) {
-            const found = search(blob.toString('utf-8'));
-            if (found.length > 0) results.push({ file, state: report.state, version: 'workspace', matches: found });
-          } else if (entry) {
-            skipped.push({ file, reason: 'the workspace copy is missing from the store, so it was not searched' });
-          }
-          if (report.state !== 'conflict') continue;
-          // A conflict's disk side. The version recorded with the conflict is
-          // disk's only while disk still holds it; once disk has changed
-          // since, it is labelled as recorded, and a file disk holds now
-          // (never stored) is listed as not searched. A binary or oversize
-          // disk version was never stored either.
-          const disk = intents.get(report.path)?.conflict?.disk;
-          const changed = report.conflict?.diskChangedSinceRecorded === true;
-          const diskBlob = disk?.stored ? store.getBlob(disk.stored) : null;
-          if (diskBlob) {
-            const found = search(diskBlob.toString('utf-8'));
-            if (found.length > 0) results.push({ file, state: report.state, version: changed ? 'recorded-disk' : 'conflicting-disk', matches: found });
-          }
-          if (disk?.stored && !diskBlob) {
-            skipped.push({ file, reason: 'conflict: the disk version recorded with the conflict is missing from the store, so it was not searched' });
-          }
-          if (changed) {
-            if (report.diskNow === 'file') {
-              skipped.push({ file, reason: 'conflict: disk changed since the conflict was recorded; grep searches stored text, so the file disk holds now was not searched' });
-            }
-          } else if (disk && !disk.stored) {
-            skipped.push({ file, reason: 'conflict: the disk version is binary or over the size limit, never stored', size: disk.size });
-          }
-        }
-      });
+      const searched = (text: GrepText): void => {
+        const matches = search(text.text);
+        if (matches.length > 0) results.push({ file: text.file, ...(text.state !== undefined ? { state: text.state } : {}), version: text.version, matches });
+      };
+      const kept = (path: string): boolean => fileGlob === null || fileGlob.test(path);
+      const found = mount.direct
+        ? await this.textsFromDisk(mount, relativePath, root, start, kept, searched)
+        : await this.textsFromStore(mount, relativePath, start, kept, searched);
+      skipped.push(...found.skipped);
+      incomplete.push(...found.incomplete);
     }
 
     return {
@@ -3529,6 +4728,169 @@ export class WorkspaceModule implements Module {
     };
   }
 
+  /**
+   * The texts a 'chronicle' mount's grep searches beneath `start`, or in the
+   * single file `relativePath` names, those `keep` lets through, each handed
+   * to `each` in path order: a pass over the scope, then each path's
+   * workspace copy, labelled with its state, and a conflict's disk side.
+   * What it doesn't search is in `skipped`, and what it couldn't see in
+   * `incomplete`, each mount-prefixed.
+   */
+  private async textsFromStore(
+    mount: MountState,
+    relativePath: string,
+    start: string,
+    keep: (path: string) => boolean,
+    each: (text: GrepText) => void,
+  ): Promise<{ skipped: GrepSkip[]; incomplete: Array<{ path: string; reason: string }> }> {
+    const store = this.getStore();
+    const skipped: GrepSkip[] = [];
+    const incomplete: Array<{ path: string; reason: string }> = [];
+    await this.withMount(mount, async () => {
+      // A `path` naming a single file greps just that file; otherwise it is a
+      // directory prefix. (A file path once produced the prefix "notes.md/"
+      // and silently matched nothing.)
+      const fileScope = await this.namesFile(mount, relativePath, resolve(mount.config.path));
+      // What follows reads the tree and branch intent to go with the pass's
+      // reports, synchronously. They must be the branch the pass decided
+      // on: one selected in between would label its content with the other
+      // branch's states. So a pass whose branch is no longer selected runs
+      // again, and a branch that keeps changing leaves the scope unsearched.
+      //
+      // A copy held at a path that now leads into a nested mount's directory
+      // through a link is that mount's file too, and one that now lands on a
+      // file this mount's include leaves out is no file of this mount's:
+      // read refuses either (parseFilePath), so grep searches none of it and
+      // says why. The pass
+      // can't check such a path's disk, so only an unverified one can be
+      // one. Asking awaits disk, so it's done before the branch is
+      // compared, and a branch selected meanwhile runs the pass again.
+      let pass: PassResult | null = null;
+      let refused = new Map<string, string>();
+      for (let attempt = 0; attempt < 3 && pass === null; attempt++) {
+        const next = await this.passUnlocked(mount, fileScope
+          ? { kind: 'paths', paths: [relativePath] }
+          : { kind: 'dir', dir: start, recursive: true });
+        const asked = new Map<string, string>();
+        for (const report of next.reports.values()) {
+          if (report.state !== 'unverified') continue;
+          const refusal = await this.landingRefusal(mount, report.path, `${mount.config.name}/${report.path}`, this.nestedOf(mount.config.name), resolve(mount.config.path));
+          if (refusal) asked.set(report.path, refusal.message);
+        }
+        if (next.branchId === undefined || next.branchId === store.currentBranch().id) {
+          pass = next;
+          refused = asked;
+        }
+      }
+      if (pass === null) {
+        incomplete.push({
+          path: `${mount.config.name}/${relativePath}`,
+          reason: 'the selected branch kept changing while grep ran; nothing here was searched — grep again',
+        });
+        return;
+      }
+      for (const region of pass.incomplete) {
+        incomplete.push({ path: `${mount.config.name}/${region.path}`, reason: region.reason });
+      }
+
+      const intents = this.intents.get(mount.config.name)!;
+      for (const report of [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path))) {
+        if (!keep(report.path)) continue;
+        const file = `${mount.config.name}/${report.path}`;
+        if (report.state === 'disk-only') {
+          skipped.push({
+            file,
+            reason: 'disk-only: binary or over the size limit, never stored',
+            ...(report.size !== undefined ? { size: report.size } : {}),
+            ...(report.mimeType ? { mimeType: report.mimeType } : {}),
+          });
+          continue;
+        }
+        // A path in another mount's directory is that mount's: grep gives
+        // none of this mount's copy of it, as read refuses it. Beneath a
+        // scope it's passed over by design, like the directory.
+        if (inOtherMount(report.path, this.othersOf(mount.config.name))) continue;
+        const refusal = refused.get(report.path);
+        if (refusal !== undefined) {
+          skipped.push({ file, reason: refusal });
+          continue;
+        }
+        // The workspace's version, labelled with the path's state.
+        const entry = store.treeGet(mount.treeStateId, report.path);
+        const blob = entry ? store.getBlob(entry.blobHash) : null;
+        if (blob) {
+          each({ file, state: report.state, version: 'workspace', text: blob.toString('utf-8') });
+        } else if (entry) {
+          skipped.push({ file, reason: 'the workspace copy is missing from the store, so it was not searched' });
+        }
+        if (report.state !== 'conflict') continue;
+        // A conflict's disk side. The version recorded with the conflict is
+        // disk's only while disk still holds it; once disk has changed
+        // since, it is labelled as recorded, and a file disk holds now
+        // (never stored) is listed as not searched. A binary or oversize
+        // disk version was never stored either.
+        const disk = intents.get(report.path)?.conflict?.disk;
+        const changed = report.conflict?.diskChangedSinceRecorded === true;
+        const diskBlob = disk?.stored ? store.getBlob(disk.stored) : null;
+        if (diskBlob) {
+          each({ file, state: report.state, version: changed ? 'recorded-disk' : 'conflicting-disk', text: diskBlob.toString('utf-8') });
+        }
+        if (disk?.stored && !diskBlob) {
+          skipped.push({ file, reason: 'conflict: the disk version recorded with the conflict is missing from the store, so it was not searched' });
+        }
+        if (changed) {
+          if (report.diskNow === 'file') {
+            skipped.push({ file, reason: 'conflict: disk changed since the conflict was recorded; grep searches stored text, so the file disk holds now was not searched' });
+          }
+        } else if (disk && !disk.stored) {
+          skipped.push({ file, reason: 'conflict: the disk version is binary or over the size limit, never stored', size: disk.size });
+        }
+      }
+    });
+    return { skipped, incomplete };
+  }
+
+  /**
+   * The texts a direct mount's grep searches beneath `start`, or in the
+   * single file `relativePath` names, as namesFile judges it beneath `root`,
+   * the root grep's parse resolved, those `keep` lets through, each handed
+   * to `each` in path order: each file its walk took (diskWalk), read from
+   * disk as it is now, DIRECT_READS_AT_ONCE at a time. A file over the size
+   * limit, a binary one and one the mount doesn't take are in `skipped`,
+   * each with why, as a 'chronicle' mount's grep lists what it never stored;
+   * one gone since the walk listed it isn't there to search.
+   */
+  private async textsFromDisk(
+    mount: MountState,
+    relativePath: string,
+    root: string,
+    start: string,
+    keep: (path: string) => boolean,
+    each: (text: GrepText) => void,
+  ): Promise<{ skipped: GrepSkip[]; incomplete: Array<{ path: string; reason: string }> }> {
+    const name = mount.config.name;
+    const fileScope = await this.namesFile(mount, relativePath, root);
+    const { view, rootReal, taken, incomplete } = fileScope
+      ? { ...(await this.diskView(mount)), taken: [relativePath], incomplete: [] }
+      : await this.diskWalk(mount, start, true);
+    const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    const skipped: GrepSkip[] = [];
+    await inOrder(taken.filter(keep), DIRECT_READS_AT_ONCE, (path) => readBytes(view, rootReal, path, maxSize), (read, path) => {
+      const file = `${name}/${path}`;
+      if (read.kind === 'absent') return;
+      if (read.kind === 'unobserved') {
+        skipped.push({ file, reason: read.reason });
+        return;
+      }
+      const mimeType = sniffImageMime(read.head);
+      const what = { size: read.size, ...(mimeType ? { mimeType } : {}) };
+      if (read.bytes === null) skipped.push({ file, reason: `over the size limit (${maxSize} bytes)`, ...what });
+      else if (looksBinary(read.head)) skipped.push({ file, reason: 'binary: a NUL in its first 8 KB', ...what });
+      else each({ file, version: 'disk', text: read.bytes.toString('utf-8') });
+    });
+    return { skipped, incomplete: incomplete.map((region) => ({ path: `${name}/${region.path}`, reason: region.reason })) };
+  }
+
   private async handleStatus(input: StatusInput): Promise<ToolResult> {
     const store = this.getStore();
     const status: Record<string, unknown> = {};
@@ -3538,25 +4900,30 @@ export class WorkspaceModule implements Module {
 
     for (const [name, mount] of this.mounts) {
       if (input.mount !== undefined && name !== input.mount) continue;
-      const entries = store.treeList(mount.treeStateId);
+      if (mount.direct) {
+        // A direct mount keeps nothing to count: its kind, and the ignore
+        // list its walks go by, whose default no config shows.
+        status[name] = { path: mount.config.path, mode: mount.config.mode, backend: 'direct', ignore: this.ignoreOf(mount) };
+        continue;
+      }
+      // What the workspace's history holds outside the mount's include isn't the mount's,
+      // and nor is what it holds in a nested mount's directory that mount's include leaves
+      // out (withinIncludes), which no listing names either.
+      const listable = { include: mount.config.include, nested: this.nestedOf(name) };
+      const entries = store.treeList(mount.treeStateId).filter((e) => withinIncludes(listable, e.path));
       const currentSeq = store.currentSequence();
-      const own = this.ownPaths(mount);
-      const intents = this.intents.get(name)!.list().filter(([p]) => own(p));
-      const conflictPaths = intents.filter(([, bi]) => bi.conflict).map(([p]) => p);
-      // A workspace deletion is pending until a push confirms it on disk:
-      // left there without applyDeletions, or unlinked but unconfirmed.
-      const deletionPaths = intents.filter(([, bi]) => bi.tombstone).map(([p]) => p);
-      // Pending is what disk owes by the evidence: every entry it doesn't
-      // show on disk (a refused or failed push stays owed), conflicts and
-      // deletions. An entry from before the evidence isn't counted until a
-      // listing or a materialize checks it: unchecked isn't unpushed.
-      const pending = new Set([...conflictPaths, ...deletionPaths, ...this.entriesByEvidence(mount).owed]);
+      const { conflicts: conflictPaths, deletions: deletionPaths, owed } = this.heldChanges(mount);
+      const pending = new Set([...conflictPaths, ...deletionPaths, ...owed]);
 
       const currentBranch = store.currentBranch();
       status[name] = {
         path: mount.config.path,
         mode: mount.config.mode,
-        watch: mount.config.watch ?? 'always',
+        // A mount configured direct runs as 'chronicle' this session
+        // (chooseKinds), by the direct kind's ignore list where its config
+        // names none.
+        ...(mount.config.backend === 'direct' ? { backend: 'chronicle', ignore: this.ignoreOf(mount) } : {}),
+        watch: watchOf(mount.config),
         fileCount: entries.length,
         lastMaterializedSeq: mount.lastMaterializedSeq,
         currentSeq,
@@ -3574,6 +4941,37 @@ export class WorkspaceModule implements Module {
     return { success: true, data: status };
   }
 
+  /**
+   * What the store holds of a mount that disk lacks, on the selected branch,
+   * among the mount's own paths. Status counts the first three as pending:
+   * recorded conflicts; workspace deletions, pending until a push confirms
+   * them on disk (left there without applyDeletions, or unlinked but
+   * unconfirmed); and what disk owes by the evidence (entriesByEvidence's
+   * `owed`: every entry it doesn't show on disk, a refused or failed push's
+   * included). An entry from before the evidence isn't among them until a
+   * listing or a materialize checks it: unchecked isn't unpushed. A
+   * tombstone beside an entry that's still there, left by a deletion or a
+   * write that stopped partway (commitToolChanges), is no deletion: it holds
+   * no change disk lacks, and its entry is judged by the evidence as any
+   * other is. The fourth, intents that can't be read, may hold a deletion
+   * or a conflict, so a mount configured direct counts them too (initStore).
+   * Each lies where the mount's include covers, as status counts them: what
+   * the workspace's history holds outside it is no change of the mount's,
+   * and no push writes it to disk (pushUnlocked).
+   */
+  private heldChanges(mount: MountState): { conflicts: string[]; deletions: string[]; owed: string[]; unreadable: string[] } {
+    const store = this.getStore();
+    const own = this.ownPaths(mount);
+    // What the workspace's history holds outside the mount's include isn't the mount's.
+    const intents = this.intents.get(mount.config.name)!.list().filter(([p]) => insideMount(p, mount.config.include) && own(p));
+    return {
+      conflicts: intents.filter(([, bi]) => bi.conflict).map(([p]) => p),
+      deletions: intents.filter(([p, bi]) => bi.tombstone && !store.treeGet(mount.treeStateId, p)).map(([p]) => p),
+      owed: this.entriesByEvidence(mount).owed,
+      unreadable: intents.filter(([, bi]) => bi.unreadable !== undefined).map(([p]) => p),
+    };
+  }
+
   /**
    * What a materialize of `mount` should consider: a named file, or every
    * tracked path beneath a named directory; otherwise what the evidence says
@@ -3600,17 +4998,26 @@ export class WorkspaceModule implements Module {
 
     const { owed, unchecked, agreed } = this.entriesByEvidence(mount);
     for (const path of [...owed, ...unchecked]) selected.add(path);
-    for (const [p, bi] of intents) if (bi.conflict || bi.tombstone) selected.add(p);
+    // A tombstone is a deletion only where its entry is gone: one beside an
+    // entry that's still there, left by a change that stopped partway
+    // (commitToolChanges), would select an agreed entry, and a forced push
+    // would write it over a newer disk copy. A deletion or conflict held
+    // outside the mount's include isn't the mount's, as status counts it:
+    // not taken up, so not reported skipped.
+    for (const [p, bi] of intents) {
+      if ((bi.conflict || (bi.tombstone && !store.treeGet(mount.treeStateId, p))) && insideMount(p, mount.config.include)) selected.add(p);
+    }
     return { paths: [...selected], inPlace: agreed > 0 };
   }
 
   /**
    * Whether a path of the mount is its own to push and to count as owed:
    * not in another mount's directory nested in it. Copies the mount's tree
-   * holds there (stored before the nesting) stay in its history and its
-   * listings (and in status's fileCount, which counts the tree), passed over
-   * by its syncs, and left out of what it pushes and of status's pending
-   * changes, conflicts and workspace deletions.
+   * holds there (stored before the nesting) stay in its history, and in its
+   * listings and status's fileCount where that mount's include covers them
+   * (withinIncludes). Its syncs pass over them, and
+   * they're left out of what it pushes and of status's pending changes,
+   * conflicts and workspace deletions.
    */
   private ownPaths(mount: MountState): (path: string) => boolean {
     const others = this.othersOf(mount.config.name);
@@ -3639,7 +5046,9 @@ export class WorkspaceModule implements Module {
     let agreed = 0;
     const own = this.ownPaths(mount);
     for (const e of store.treeList(mount.treeStateId)) {
-      if (!own(e.path)) continue;
+      // Outside the mount's include, or in another mount's directory nested
+      // in it: neither owed to disk nor counted as on it.
+      if (!insideMount(e.path, mount.config.include) || !own(e.path)) continue;
       const p = agreement.get(name, e.path);
       if (p === undefined) (intents.get(e.path)?.origin === 'store' ? owed : unchecked).push(e.path);
       else if (p.kind !== 'content' || p.hash !== e.blobHash) owed.push(e.path);
@@ -3660,7 +5069,16 @@ export class WorkspaceModule implements Module {
     const modesKept: Array<{ mount: string; path: string; reason: string }> = [];
 
     let explicit: { mount: MountState; relativePath: string } | null = null;
-    if (input.path) explicit = await this.parsePath(input.path);
+    if (input.path) {
+      const parsed = await this.parsePath(input.path);
+      explicit = parsed;
+      // A path outside the mount's include that's no scope (refusesAsOutside)
+      // is refused; beneath a directory, the push leaves out what the include
+      // doesn't cover.
+      if (await this.refusesAsOutside(parsed.mount, parsed.relativePath, parsed.moved, parsed.root)) {
+        return { success: false, error: new OutsideIncludeError(input.path, explicit.mount.config).message, isError: true };
+      }
+    }
 
     let mountsToMaterialize: Array<{ name: string; mount: MountState }>;
     if (explicit) {
@@ -3686,6 +5104,10 @@ export class WorkspaceModule implements Module {
     // whatever branch is current when its turn comes, unguarded. The push
     // then writes nothing if the branch changes after that.
     const blocked: Array<{ mount: string; reason: string }> = [];
+    // What the push left because the mount's include doesn't cover it is
+    // counted, as a sync's passedOver counts it, and not named: no tool names
+    // a file outside the include.
+    const passedOver: Array<{ mount: string; reason: string; count: number }> = [];
     const guarded: string[] = [];
     let proceeded = 0;
 
@@ -3731,10 +5153,13 @@ export class WorkspaceModule implements Module {
       for (const p of pushed.pendingDeletions) pendingDeletions.push({ mount: name, path: p });
       // Refusals ride the same skipped list as branch blocks: divergence must
       // be visible, not resolved silently either way.
+      let outside = 0;
       for (const s of pushed.skipped) {
+        if (s.reason === OUTSIDE_INCLUDE) { outside++; continue; }
         const reason = s.reason === NOT_PUSHED_IN_OTHER_MOUNT ? this.otherMountNote(name, s.path, 'push') : s.reason;
         blocked.push({ mount: name, reason: `${s.path}: ${reason}` });
       }
+      if (outside > 0) passedOver.push({ mount: name, reason: OUTSIDE_INCLUDE, count: outside });
       // Written paths whose mode stayed as disk had it: no refusal, so not
       // among what was skipped.
       for (const k of pushed.modesKept) modesKept.push({ mount: name, ...k });
@@ -3780,6 +5205,7 @@ export class WorkspaceModule implements Module {
           }
           : {}),
         ...(blocked.length > 0 ? { skipped: blocked } : {}),
+        ...(passedOver.length > 0 ? { passedOver } : {}),
         ...(modesKept.length > 0 ? { modesKept } : {}),
       },
       // What disk lost, then what it was written: kept in the stub if the
@@ -3846,7 +5272,13 @@ export class WorkspaceModule implements Module {
     // A path names its own mount; otherwise the given mount, or every mount.
     let targets: Array<{ name: string; mount: MountState; relativePath: string }>;
     if (input.path) {
-      const { mount, relativePath } = await this.parsePath(input.path);
+      const { mount, relativePath, moved, root } = await this.parsePath(input.path);
+      // A path outside the mount's include that's no scope (refusesAsOutside)
+      // is refused; beneath a directory, the walk passes over what the include
+      // doesn't cover.
+      if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
+        return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+      }
       targets = [{ name: mount.config.name, mount, relativePath }];
     } else if (input.mount) {
       const m = this.mounts.get(input.mount);
@@ -3859,6 +5291,12 @@ export class WorkspaceModule implements Module {
     }
 
     for (const { name, mount, relativePath } of targets) {
+      // A direct mount's tools read disk as it is, so a sync has nothing to
+      // take in there, and says it didn't look rather than that nothing changed.
+      if (mount.direct) {
+        allSkipped.push({ mount: name, path: relativePath, reason: DIRECT_SYNC_SKIPPED });
+        continue;
+      }
       const pass = await this.withMount(mount, async () => {
         if (input.acceptRoot && await this.acceptRootUnlocked(mount)) rootsAccepted.push(name);
         if (!relativePath) {
@@ -3931,7 +5369,7 @@ export class WorkspaceModule implements Module {
       // without a path passes over it, so nothing else keeps it current
       // (agent-framework #276). A path in another mount's directory isn't
       // synced at all, and the note says so.
-      const passedOver = passedOverAt(relativePath, mount.config.ignore ?? [], this.othersOf(name));
+      const passedOver = passedOverAt(relativePath, this.ignoreOf(mount), this.othersOf(name));
       if (passedOver !== undefined) {
         allIgnored.push({
           mount: name,
@@ -3995,11 +5433,14 @@ export class WorkspaceModule implements Module {
    * The watcher's ops only choose which paths to look at: each path is
    * observed again and decided under the three-way rule, so an event that
    * arrives late or out of order can't delete or revert anything by itself.
+   * A path outside the mount (insideMount), such as one its include doesn't
+   * cover, is no pass's to decide (gather), so a batch of nothing else takes
+   * no turn of the mount.
    */
   private async handleFsChanges(mountName: string, changes: FsChange[]): Promise<void> {
     const mount = this.mounts.get(mountName);
     if (!this.store || !this.running() || !mount) return;
-    const paths = [...new Set(changes.map((c) => c.path))];
+    const paths = [...new Set(changes.map((c) => c.path))].filter((p) => insideMount(p, mount.config.include));
     if (paths.length === 0) return;
     await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'paths', paths }));
   }
@@ -4020,7 +5461,7 @@ export class WorkspaceModule implements Module {
   async onToolBatchComplete(_agentName?: string): Promise<void> {
     // Every agent's workspace is the store's current branch, so the agent
     // that ran the batch doesn't choose what is scanned.
-    const mounts = [...this.mounts.values()].filter((m) => m.config.watch === 'on-agent-action');
+    const mounts = [...this.mounts.values()].filter((m) => watchOf(m.config) === 'on-agent-action');
     if (mounts.length === 0 || !this.store || !this.running()) return;
     const deadlineMs = this.agentActionScanDeadlineMs();
     await Promise.all(mounts.map(async (mount) => {
@@ -4169,6 +5610,72 @@ export class WorkspaceModule implements Module {
 
 }
 
+/**
+ * A text grep searches (textsFromStore, textsFromDisk): its mount-prefixed
+ * file, which copy it is, and on a 'chronicle' mount, the path's state.
+ */
+interface GrepText {
+  file: string;
+  state?: string;
+  version: 'workspace' | 'conflicting-disk' | 'recorded-disk' | 'disk';
+  text: string;
+}
+
+/** A file, or a copy of one, grep doesn't search, with why. */
+type GrepSkip = { file: string; reason: string; size?: number; mimeType?: string };
+
+/** What a listing shows of a directory scope (listingOf). */
+interface Listing {
+  /** Each file it shows, by mount-relative path, in order, with what a listing says of it beyond its name. */
+  files: Array<{ path: string } & Record<string, unknown>>;
+  /** For a listing that doesn't descend, the directories directly beneath the scope, mount-relative; none for one that does. */
+  dirs: string[];
+  /** The regions it couldn't see, mount-relative, each with why. */
+  incomplete: Array<{ path: string; reason: string }>;
+}
+
+/**
+ * Run `work` on each item, at most `width` at once, and hand each result to
+ * `each` in the items' order, as soon as it and those before it are done.
+ * A result handed on is let go, so what's held at once is at most `width`
+ * results, as a direct grep's file contents are. A `work` that rejects
+ * rejects this when its turn comes; any started after it finish unheard.
+ * Exported for its tests.
+ */
+export async function inOrder<T, R>(items: readonly T[], width: number, work: (item: T) => Promise<R>, each: (result: R, item: T) => void): Promise<void> {
+  const waiting: Array<Promise<R>> = [];
+  let started = 0;
+  for (let i = 0; i < items.length; i++) {
+    while (started < items.length && started < i + width) {
+      const running = work(items[started]!);
+      // Handled from the start, so a rejection that comes before its turn
+      // isn't an unhandled one; awaiting it below still throws it.
+      running.catch(() => {});
+      waiting.push(running);
+      started++;
+    }
+    each(await waiting.shift()!, items[i]!);
+  }
+}
+
+/** read_image's answer for an image, wherever it was read from. */
+function imageResult(path: string, image: { bytes: Buffer; mimeType: SupportedImageMimeType }): ToolResult {
+  return {
+    success: true,
+    data: [
+      {
+        type: 'text',
+        text: `Path: ${path}\nMIME: ${image.mimeType}\nBytes: ${image.bytes.byteLength}`,
+      },
+      {
+        type: 'image',
+        data: image.bytes.toString('base64'),
+        mimeType: image.mimeType,
+      },
+    ],
+  };
+}
+
 /** What a listing shows of a path beyond its name. */
 function stateView(report: PathReport): Record<string, unknown> {
   return {
@@ -4187,6 +5694,122 @@ function stateView(report: PathReport): Record<string, unknown> {
 /** A lone UTF-16 surrogate, which UTF-8 can't store: in `u` mode, a pair is one code point. */
 const LONE_SURROGATE = /\p{Cs}/u;
 
+/** Why a direct mount's read stopped when it found another directory put at its root as it opened the file. */
+const DIRECT_ROOT_REPLACED = 'the mount root was replaced as the file was opened: reading it again reads the directory there now';
+
+/**
+ * How the alert that a mount configured direct runs as 'chronicle' names an
+ * intent the workspace can't read. A sync of its path settles it, with
+ * disk's copy, or with none where disk has none, and where disk's file
+ * can't be read it skips the path and says why. Materialize settles one
+ * only where the workspace holds a copy there: a plain one skips it and says
+ * to sync, a forced one writes the copy, and where the workspace holds none
+ * it neither selects nor names it.
+ */
+const UNREADABLE_INTENT = "its workspace intent can't be read; a sync of the path settles it or says why not";
+
+/**
+ * A mount's watch mode as it runs. A mount configured direct watches
+ * nothing, whichever kind it runs as this session: its config takes no
+ * other mode (directRefusals), and leaving it out means 'never' there.
+ */
+function watchOf(config: MountConfig): 'always' | 'on-agent-action' | 'never' {
+  return config.watch ?? (config.backend === 'direct' ? 'never' : 'always');
+}
+
+/**
+ * What a direct mount's config sets that would never act there, each with
+ * the way out (MountConfig.backend): a direct mount is read-only, and has no
+ * watcher to tune, no change event to wake on and no push to make.
+ */
+function directRefusals(mount: MountConfig): string[] {
+  const refused: string[] = [];
+  if (mount.mode !== 'read-only') {
+    refused.push(mount.mode === undefined ? "mode must be 'read-only' (left out, it's 'read-write')" : `mode must be 'read-only', not ${shownValue(mount.mode)}`);
+  }
+  if (mount.watch !== undefined && mount.watch !== 'never') refused.push(`watch ${shownValue(mount.watch)} would watch nothing (leave it out, or set 'never')`);
+  for (const key of ['watchDebounceMs', 'watchRootPollMs'] as const) {
+    if (mount[key] !== undefined) refused.push(`${key} would tune no watcher (leave it out)`);
+  }
+  const wake = mount.wakeOnChange;
+  if (wake === true || (Array.isArray(wake) && wake.length > 0)) refused.push('wakeOnChange would never wake (leave it out)');
+  if (mount.autoMaterialize === true) refused.push('autoMaterialize would never push (leave it out)');
+  return refused;
+}
+
+/** A change commitToolChanges makes to one path's tree entry. */
+type ToolChange = { kind: 'set'; blobHash: string; size: number; mode?: number } | { kind: 'remove'; previousHash: string };
+
+/** A file an edit or edit_many call edits: one stored path, and every edit naming it. */
+interface EditTarget {
+  /** Its path in its mount, as disk spells it: the store's key for it. */
+  relativePath: string;
+  /** Its mount-prefixed path as disk spells it, which its answer uses. */
+  path: string;
+  /** Every edit naming it, by index, and the specs of those fit to be matched. */
+  edits: number[];
+  specs: EditSpec[];
+}
+
+/**
+ * Whether a tree entry is what a change leaves: for a set, an entry with its
+ * blob, size and mode; for a removal, none.
+ */
+function holds(entry: ReturnType<JsStore['treeGet']>, change: ToolChange): boolean {
+  return change.kind === 'set'
+    ? entry !== null && entry.blobHash === change.blobHash && entry.size === change.size && entry.mode === (change.mode ?? 0o644)
+    : entry === null;
+}
+
+/**
+ * Whether a store's set that threw recorded the changes anyway: every path
+ * holds what its change leaves. The changes given are those the tree didn't
+ * hold before the set, and one record takes all of them or none, so their
+ * holding shows the record is in. Reading them back can fail too, and then
+ * whether they're stored isn't known (CommitUnknownError).
+ */
+function changesLanded(
+  store: JsStore,
+  treeStateId: string,
+  changes: Array<{ path: string; change: ToolChange }>,
+  setError: unknown,
+): boolean {
+  try {
+    return changes.every(({ path, change }) => holds(store.treeGet(treeStateId, path), change));
+  } catch (readError) {
+    throw new CommitUnknownError(setError, readError);
+  }
+}
+
+/**
+ * A store's set threw, and reading its entries back threw too, so whether the
+ * change is stored isn't known. Its message says so after both errors.
+ */
+class CommitUnknownError extends Error {
+  readonly setError: string;
+  readonly readError: string;
+  constructor(setError: unknown, readError: unknown) {
+    const text = (error: unknown) => (error instanceof Error ? error.message : String(error));
+    super(`${text(setError)}; reading its entries back failed too (${text(readError)}), so whether the change is stored isn't known`);
+    this.name = 'CommitUnknownError';
+    this.setError = text(setError);
+    this.readError = text(readError);
+  }
+}
+
+/**
+ * A store's set that threw after recording the change (changesLanded): the
+ * entries are set and their intents follow, and the store's error goes on in
+ * place of the push. `pushes` says whether the mount would have pushed the
+ * change to disk, and `notes` are commitToolChanges' own, by path.
+ */
+class StoredThenFailed extends Error {
+  constructor(storeError: unknown, readonly pushes: boolean, readonly notes: Map<string, string>) {
+    super(storeError instanceof Error ? storeError.message : String(storeError));
+    this.name = 'StoredThenFailed';
+  }
+}
+
 /**
  * The answer to a write, edit or delete that the workspace stored but
  * couldn't finish: its push to disk didn't complete, or what follows the tree
@@ -4195,12 +5818,13 @@ const LONE_SURROGATE = /\p{Cs}/u;
  * and sending it again could apply it twice. The push's reason says what disk
  * holds and the way out, as materialize takes it. The text carries all of it,
  * since an error's data reaches neither the model nor a code_execution
- * script. An edit's note on which copy it applied to comes last.
+ * script. A note comes last: an edit's on which copy it applied to, or a
+ * deletion's that it unlinked nothing.
  */
 function storedButUnfinished(
   tool: 'write' | 'edit' | 'delete',
   path: string,
-  outcome: { refused: string } | { threw: string },
+  outcome: { refused: string } | { threw: string } | { storeFailed: string; pushes: boolean },
   note: string | null = null,
 ): ToolResult {
   const change = tool === 'delete' ? 'deletion' : tool;
@@ -4208,7 +5832,12 @@ function storedButUnfinished(
     + (tool === 'edit' ? ': a second edit can apply the change twice.' : '.');
   const rest = 'refused' in outcome
     ? ` Its push to disk didn't complete: ${outcome.refused}.`
-    : ` The rest of the call failed: ${outcome.threw}. ls shows the path's state.`;
+    : 'storeFailed' in outcome
+      ? ` The store failed after recording it: ${outcome.storeFailed}.` + (!outcome.pushes ? ''
+        : tool === 'delete'
+          ? ' Its push to disk didn\'t run, so disk keeps the file until a materialize of the path with applyDeletions deletes it.'
+          : ' Its push to disk didn\'t run, so disk lacks the change until a materialize of the path writes it.')
+      : ` The rest of the call failed: ${outcome.threw}. ls shows the path's state.`;
   return { success: false, isError: true, error: stored + rest + (note !== null ? ` ${note}` : '') };
 }
 
@@ -4230,16 +5859,19 @@ function linesOf(content: string): string[] {
 const INPUT_MINIMUMS: Record<string, Record<string, number>> = {
   read: { offset: 1, limit: 1, offsetChars: 0, limitChars: 1 },
   grep: { contextBefore: 0, contextAfter: 0 },
+  edit_many: { occurrences: 1 },
 };
 
 /**
  * Why a tool call's input doesn't fit its tool's schema, or null when it does:
  * an object, each required field present, and each field its schema calls a
  * string, a boolean or an integer of that type, an integer at least its
- * minimum. The workspace's schemas use no other types. Without it, an edit
- * missing `newString` wrote the word "undefined", and an offset of 1.5
- * numbered lines 1.5, 2.5 and on. A field the schema doesn't describe is left
- * to its handler.
+ * minimum. A field it calls an array of objects is an array, and each of its
+ * items is checked the same way against the items' schema, with the same
+ * minimums (edit_many's edits). The workspace's schemas use no other types.
+ * Without it, an edit missing `newString` wrote the word "undefined", and an
+ * offset of 1.5 numbered lines 1.5, 2.5 and on. A field the schema doesn't
+ * describe is left to its handler.
  */
 function inputProblem(
   schema: { properties?: Record<string, unknown>; required?: string[] },
@@ -4254,17 +5886,28 @@ function inputProblem(
     if (fields[name] === undefined) return `"${name}" is required`;
   }
   for (const [name, value] of Object.entries(fields)) {
-    const type = (schema.properties?.[name] as { type?: string } | undefined)?.type;
+    const property = schema.properties?.[name] as { type?: string; items?: { type?: string } } | undefined;
+    const type = property?.type;
     if (value === undefined || type === undefined) continue;
     const minimum = minimums[name];
     const fits = type === 'string' ? typeof value === 'string'
       : type === 'boolean' ? typeof value === 'boolean'
       : type === 'integer'
         ? Number.isSafeInteger(value) && (minimum === undefined || (value as number) >= minimum)
+      : type === 'array' ? Array.isArray(value)
         : true;
+    if (fits && type === 'array' && property?.items?.type === 'object') {
+      for (const [i, item] of (value as unknown[]).entries()) {
+        const problem = item !== null && typeof item === 'object' && !Array.isArray(item)
+          ? inputProblem(property.items as Parameters<typeof inputProblem>[0], item, minimums)
+          : 'it must be an object of the fields its schema lists';
+        if (problem !== null) return `"${name}" item ${i + 1}: ${problem}`;
+      }
+    }
     if (!fits) {
       const wanted = type === 'string' ? 'a string'
         : type === 'boolean' ? 'true or false'
+        : type === 'array' ? 'an array'
         : minimum === undefined ? 'a whole number' : `a whole number of at least ${minimum}`;
       const got = value === null ? 'null'
         : typeof value === 'number' ? String(value)