@animalabs/agent-framework 0.22.4 → 0.23.1

package/src/modules/workspace/index.ts

@@ -8,8 +8,8 @@
 import { isUtf8 } from 'node:buffer';
 import { constants as fsConstants } from 'node:fs';
 import type { Stats } from 'node:fs';
-import { open, readFile, readdir, stat, lstat, realpath } from 'node:fs/promises';
-import { isAbsolute, join, resolve, relative, sep } from 'node:path';
+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 { Module, ModuleContext, ProcessState, EventResponse } from '../../types/module.js';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from '../../types/events.js';
@@ -40,7 +40,7 @@ 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, OTHER_MOUNT, checkDir, filesystemTrustsCtime, inOtherMount, locateRoot, passedOverAt, readPrefix } from './observe.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 { TOOL_BATCH_HOOK_TIMEOUT_MS, ensureStateRegistered } from '../../module-registry.js';
 import {
   type MountRuntime,
@@ -101,6 +101,8 @@ class WorkspaceImageReadError extends Error {
       | 'not_found'
       | 'directory'
       | 'symlink'
+      | 'parent_symlink'
+      | 'other_mount'
       | 'escape'
       | 'changed'
       | 'empty'
@@ -119,13 +121,23 @@ class WorkspaceImageReadError extends Error {
 /**
  * Why a workspace-owned filesystem read was refused. Distinguishes the cases a
  * peer needs to react to differently: a path that never resolved inside the
- * mount (`unknown_mount`, `traversal`), a mount whose root is gone
- * (`mount_unavailable`), an ordinary missing file (`not_found`), a directory
- * (`directory`), a symlink refused by the mount's `followSymlinks` policy
- * (`symlink`), a symlink whose canonical target lands outside the canonical
- * mount root (`escape`), a file swapped underneath the read (`changed`), 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.
+ * mount (`unknown_mount`, `traversal`), a mount whose root is gone, isn't a
+ * directory, or isn't the directory the workspace was using
+ * (`mount_unavailable`: with errno ENOENT or ENOTDIR when no directory is
+ * there at all, with none for another directory), an ordinary missing file
+ * or one that isn't a regular file, such as a FIFO (`not_found`), a directory
+ * (`directory`), a file that is itself a symlink, refused by the mount's
+ * `followSymlinks` policy (`symlink`), a symlink among the path's directories
+ * on a mount that doesn't follow symlinks, leading to a directory or a file
+ * inside the mount, or nowhere (`parent_symlink`), whose message names the
+ * 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.
  */
 export type WorkspaceReadErrorCode =
   | 'unknown_mount'
@@ -135,12 +147,16 @@ export type WorkspaceReadErrorCode =
   | 'not_found'
   | 'directory'
   | 'symlink'
+  | 'parent_symlink'
   | 'escape'
   | 'changed';
 
 /** Where in the open sequence a `WorkspaceReadError` originated (diagnostics). */
 export type WorkspaceReadStage =
   | 'parse'
+  /** The mount root's check: a directory, the one the workspace was using. */
+  | 'root'
+  | 'readlink'
   | 'lstat'
   | 'realpath_root'
   | 'open'
@@ -156,8 +172,8 @@ export type WorkspaceReadStage =
  * use there.
  */
 class NestedMountError extends Error {
-  constructor(path: string, mount: string, holder: string, use: string) {
-    super(`"${path}" lies in mount "${holder}", nested in mount "${mount}", which neither reads nor writes it: use "${use}".`);
+  constructor(path: string, mount: string, holder: string, use: string, how: 'lies in' | 'leads into' = 'lies in') {
+    super(`"${path}" ${how} mount "${holder}", nested in mount "${mount}", which neither reads nor writes it: use "${use}".`);
   }
 }
 
@@ -221,6 +237,20 @@ function errnoOf(err: unknown): string | undefined {
     : undefined;
 }
 
+/**
+ * What is at a mount root's path now, followed as the root is: for a
+ * directory, undefined; for anything else, ENOTDIR; and where the path
+ * can't be followed to anything, the errno its stat failed with, ENOENT
+ * when nothing is there.
+ */
+async function rootAbsence(root: string): Promise<string | undefined> {
+  try {
+    return (await stat(root)).isDirectory() ? undefined : 'ENOTDIR';
+  } catch (err) {
+    return errnoOf(err);
+  }
+}
+
 /** read_image's refusal of a file over the mount's size limit, wherever it's found to be. */
 function imageTooLarge(maxSize: number, mountPrefixedPath: string): WorkspaceImageReadError {
   return new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
@@ -253,6 +283,96 @@ function matchesPartialPrefix(buffer: Buffer, prefix: Buffer): boolean {
   return buffer.length > 0 && prefix.subarray(0, buffer.length).equals(buffer);
 }
 
+/**
+ * A disk reader's refusal for what linkOnTheWay found on a path's way: the
+ * 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:
+ * `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.
+ */
+async function linkReadError(
+  mount: { config: { name: string; path: string } },
+  found: LinkFound,
+  mountPrefixedPath: string,
+  nested: readonly { dir: string; name: 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';
+  return new WorkspaceReadError(code, reason, 'readlink');
+}
+
+/**
+ * `to` beneath `from`, mount-relative and `/`-separated, whatever the
+ * platform's separator; undefined where it isn't beneath it. Outside,
+ * `relative` gives a path that climbs with a `..` segment, or an absolute one
+ * across Windows drives. A name that only begins with two dots, such as
+ * `..cache`, is inside.
+ */
+function nestedDir(from: string, to: string): string | undefined {
+  const rel = relative(from, to);
+  if (!rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) return undefined;
+  return rel.split(sep).join('/');
+}
+
+/** A mount nested in another, as the outer mount's otherMounts holds it. */
+interface NestedMountEntry {
+  name: string;
+  /**
+   * Its real root, as realBeneath places it once a start has read it, and
+   * its root as resolved until then. None where it's the outer mount's own
+   * or holds it (NestedMount).
+   */
+  real?: string;
+  /** Its directory as configured and as the real roots place it. */
+  fromRoots: Array<{ dir: string; root: string }>;
+  /** Those, and each as disk spells it where that differs. */
+  spellings: Array<{ dir: string; root: string }>;
+}
+
+/** How many links realBeneath follows to a place not made yet before it stops, as the kernel's limit does. */
+const LINKS_FOLLOWED = 40;
+
+/**
+ * An absolute path, a mount root's or one beneath it, as realpath resolves
+ * 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
+ * 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.
+ */
+async function realBeneath(given: string, links = 0): 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);
+  let absolute = given;
+  while (absolute.length > root.length && (absolute.endsWith('/') || absolute.endsWith(sep))) absolute = absolute.slice(0, -1);
+  try {
+    return await realpath(absolute);
+  } 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);
+    const target = await readlink(absolute).catch(() => null);
+    if (target !== null) return realBeneath(isAbsolute(target) ? target : `${place}${sep}${target}`, links + 1);
+    return join(place, basename(absolute));
+  }
+}
+
 function isContainedPath(root: string, candidate: string): boolean {
   if (candidate === root) return true;
   const normalizedRoot = root.endsWith(sep) ? root : root + sep;
@@ -676,6 +796,8 @@ export class WorkspaceModule implements Module {
   private store: JsStore | null = null;
   /** Set once stop has drained and saved, cleared by start (running()). */
   private stopped = false;
+  /** Stops begun, so a start that read disk meanwhile can tell that one came. */
+  private stopsBegun = 0;
   private config: WorkspaceConfig;
   private mounts = new Map<string, MountState>();
   private watchers = new Map<string, MountWatcher>();
@@ -691,10 +813,19 @@ export class WorkspaceModule implements Module {
   /** Per canonical root: the device of its filesystem when that maintains ctime, else null. */
   private ctimeTrust = new Map<string, string | null>();
   /**
-   * Each mount's directories that are other mounts nested inside it:
-   * mount-relative, `/`-separated, with each mount's name and resolved root.
+   * Each mount's directories that are other mounts nested inside it, with
+   * each mount's name and real root, in each spelling that names the
+   * directory: as configured; as the real roots place it, where that differs
+   * (`fromRoots`); and as disk spells each of those where that differs.
+   * Each spelling is mount-relative and `/`-separated, with its root beneath
+   * the mount's resolved root. The constructor nests by configured path,
+   * with each root as resolved standing for its real one, and each start
+   * reads it all again with the roots placed where disk has them
+   * (readNesting).
    */
-  private otherMounts = new Map<string, Array<{ dir: string; name: string; root: string }>>();
+  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>();
   /**
    * Whether a file's mode is observed, taken in and applied (MountRuntime's
    * `modesObserved`): not on Windows, which reports no POSIX modes. A test
@@ -723,27 +854,22 @@ export class WorkspaceModule implements Module {
     // named or not, and in its watcher (OTHER_MOUNT). It's kept apart from
     // the outer mount's ignore list, which a sync that names a path sets
     // aside for what it names (#276), so no sync of the outer mount takes in
-    // the inner one's files.
+    // the inner one's files. Here by configured path, before any path is
+    // parsed; each start places the roots where disk has them too
+    // (readNesting).
     for (const outer of config.mounts) {
       for (const inner of config.mounts) {
         if (outer === inner) continue;
         const outerPath = resolve(outer.path);
         const innerPath = resolve(inner.path);
-        const rel = relative(outerPath, innerPath);
-        // Outside the outer mount, `relative` gives a path that climbs with a
-        // `..` segment, or an absolute one across Windows drives. A name that
-        // only begins with two dots, such as `..cache`, is inside it.
-        if (rel && rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)) {
-          // inner is nested under outer: passed over as exactly that
-          // directory, read against `/`-separated paths, whatever the
-          // platform's.
-          const relPath = rel.split(sep).join('/');
-          this.otherMounts.set(outer.name, [...(this.otherMounts.get(outer.name) ?? []), { dir: relPath, name: inner.name, root: innerPath }]);
-          console.warn(
-            `[workspace] Mount "${outer.name}" contains mount "${inner.name}" ` +
-            `at ${relPath}/ — passing over it as another mount's directory`,
-          );
-        }
+        const dir = nestedDir(outerPath, innerPath);
+        if (dir === undefined) continue;
+        const configured = [{ dir, root: innerPath }];
+        this.otherMounts.set(outer.name, [...(this.otherMounts.get(outer.name) ?? []), { name: inner.name, real: innerPath, fromRoots: configured, spellings: [...configured] }]);
+        console.warn(
+          `[workspace] Mount "${outer.name}" contains mount "${inner.name}" ` +
+          `at ${dir}/ — passing over it as another mount's directory`,
+        );
       }
     }
     this.config = config;
@@ -830,6 +956,25 @@ export class WorkspaceModule implements Module {
     return this.agreement;
   }
 
+  /**
+   * 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.
+   */
+  private viewOf(mount: MountState, rootIdentity: MountView['rootIdentity']): MountView {
+    return {
+      root: resolve(mount.config.path),
+      name: mount.config.name,
+      rootIdentity,
+      followSymlinks: mount.config.followSymlinks === true,
+      maxFileSize: mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE,
+      ignore: mount.config.ignore ?? [],
+      others: this.othersOf(mount.config.name),
+      nested: this.nestedOf(mount.config.name),
+    };
+  }
+
   /** The view reconciliation needs of a mount, refreshed per pass. */
   private async runtime(mount: MountState): Promise<MountRuntime> {
     const root = resolve(mount.config.path);
@@ -842,14 +987,7 @@ export class WorkspaceModule implements Module {
     }
     return {
       name: mount.config.name,
-      view: {
-        root,
-        rootIdentity: this.agreementOrThrow().rootIdentity(mount.config.name),
-        followSymlinks: mount.config.followSymlinks === true,
-        maxFileSize: mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE,
-        ignore: mount.config.ignore ?? [],
-        others: this.othersOf(mount.config.name),
-      },
+      view: this.viewOf(mount, this.agreementOrThrow().rootIdentity(mount.config.name)),
       rootReal,
       ctimeTrustedDev: trustedDev,
       treeStateId: mount.treeStateId,
@@ -862,14 +1000,14 @@ export class WorkspaceModule implements Module {
   }
 
   /**
-   * Where a search's walk starts: `base`, its path as given, then each
-   * segment of `beneath` while disk lists it, in the directory reached so
-   * far, as a directory with exactly that spelling. The walk names what it
-   * finds from its start's spelling, and a case-insensitive disk would let
-   * it go on under a spelling disk doesn't list, taking files in 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
+   * Where a search's walk starts: `base`, its path as parsePath spells it,
+   * then each segment of `beneath` while disk lists it, in the directory
+   * reached so far, as a directory with exactly that spelling. The walk names
+   * what it finds from its start's spelling, and a case-insensitive disk
+   * would let it go on under a spelling disk doesn't list, taking files in
+   * 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.
    */
@@ -917,6 +1055,20 @@ export class WorkspaceModule implements Module {
   }
 
   async start(ctx: ModuleContext): Promise<void> {
+    // Which mounts are nested where, with the roots placed where disk has
+    // them and each nested mount's directory as disk spells it, and whether
+    // each mount's root folds case, read where disk has it, before this start
+    // sets anything, so a restart takes no call and walks or watches nothing
+    // 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 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.ctx = ctx;
     this.stopped = false;
 
@@ -1168,6 +1320,7 @@ export class WorkspaceModule implements Module {
   }
 
   async stop(): Promise<void> {
+    this.stopsBegun++;
     // No new watcher-driven passes, then let every pass and write finish
     // before the store goes away — including any queued behind the ones in
     // flight (a tool call, a scan continuing past its deadline): drained
@@ -1178,11 +1331,13 @@ export class WorkspaceModule implements Module {
     for (const watcher of stopping) {
       await watcher.stop();
     }
+    // A call under way can await disk (parsePath) before it takes its turn,
+    // so the calls are waited for as well as the turns.
     for (;;) {
       const tails = [...this.mountTurns.values()];
-      await Promise.all(tails);
+      await Promise.allSettled([...this.callsUnderWay, ...tails]);
       const now = [...this.mountTurns.values()];
-      if (now.length === tails.length && now.every((tail, i) => tail === tails[i])) break;
+      if (this.callsUnderWay.size === 0 && now.length === tails.length && now.every((tail, i) => tail === tails[i])) break;
     }
     // Nothing is queued now, and nothing more is taken: what follows saves
     // the pins and watermarks as the last work left them.
@@ -1460,6 +1615,25 @@ export class WorkspaceModule implements Module {
 
   async handleToolCall(call: ToolCall): Promise<ToolResult> {
     if (!this.running()) return { success: false, isError: true, error: NOT_RUNNING };
+    return this.underWay(this.runToolCall(call));
+  }
+
+  /**
+   * Tool calls, and the public reads and writes that take a mount's turn,
+   * under way. Each can await disk (parsePath) before it takes its turn, so
+   * stop waits for these as well as for the turns.
+   */
+  private callsUnderWay = new Set<Promise<unknown>>();
+
+  /** `work`, recorded as under way until it settles (callsUnderWay). */
+  private underWay<T>(work: Promise<T>): Promise<T> {
+    this.callsUnderWay.add(work);
+    const done = (): void => { this.callsUnderWay.delete(work); };
+    work.then(done, done);
+    return work;
+  }
+
+  private async runToolCall(call: ToolCall): Promise<ToolResult> {
     try {
       // Every handler reads its input as its schema describes it; a call
       // that sends something else is refused here, before anything is read.
@@ -1583,7 +1757,10 @@ export class WorkspaceModule implements Module {
    */
   resolveAbsolutePath(mountPrefixedPath: string): string | null {
     try {
-      const { mount, relativePath } = this.parseFilePath(mountPrefixedPath);
+      // 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 });
       return resolve(mount.config.path, relativePath);
     } catch {
       return null;
@@ -1618,10 +1795,19 @@ export class WorkspaceModule implements Module {
     options: { branch?: string } = {},
   ): Promise<ToolResult> {
     if (!this.running()) return { success: false, isError: true, error: NOT_RUNNING };
+    return this.underWay(this.writeBinaryUnderWay(mountPrefixedPath, data, mimeType, options));
+  }
+
+  private async writeBinaryUnderWay(
+    mountPrefixedPath: string,
+    data: Buffer,
+    mimeType: string,
+    options: { branch?: string },
+  ): Promise<ToolResult> {
     let mount: MountState;
     let relativePath: string;
     try {
-      ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
+      ({ mount, relativePath, path: mountPrefixedPath } = await this.parseFilePath(mountPrefixedPath));
     } catch (error) {
       return {
         success: false,
@@ -1682,10 +1868,16 @@ export class WorkspaceModule implements Module {
     mountPrefixedPath: string,
   ): Promise<{ data: Buffer } | { error: string }> {
     if (!this.running()) return { error: NOT_RUNNING };
+    return this.underWay(this.readBinaryUnderWay(mountPrefixedPath));
+  }
+
+  private async readBinaryUnderWay(
+    mountPrefixedPath: string,
+  ): Promise<{ data: Buffer } | { error: string }> {
     let mount: MountState;
     let relativePath: string;
     try {
-      ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
+      ({ mount, relativePath, path: mountPrefixedPath } = await this.parseFilePath(mountPrefixedPath));
     } catch (error) {
       return { error: error instanceof Error ? error.message : String(error) };
     }
@@ -1712,8 +1904,16 @@ export class WorkspaceModule implements Module {
    * permanent cost to send something once is the wrong trade.
    *
    * Same mount boundary and traversal guard as every other path here: only
-   * declared mounts, nothing above their root. Deliberately does NOT sync,
-   * register, or hash anything — it reads and returns.
+   * declared mounts, nothing above their root, and the file reached as
+   * readFileFromDisk reaches it (openContainedFile), so the mount's
+   * `followSymlinks` holds for the file and the directories on its way, and
+   * what it reaches stays canonically inside the mount. Deliberately does NOT
+   * sync, register, or hash anything — it reads and returns.
+   *
+   * `maxBytes` refuses a larger file as "File too large", having loaded at
+   * most `maxBytes` bytes and one more: the reads decide where the file ends,
+   * not the size fstat gave at the open, so the bound holds for a file that
+   * grows while it's read.
    */
   async readBinaryFromDisk(
     mountPrefixedPath: string,
@@ -1722,28 +1922,129 @@ export class WorkspaceModule implements Module {
     let mount: MountState;
     let relativePath: string;
     try {
-      ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
+      ({ mount, relativePath, path: mountPrefixedPath } = await this.parseFilePath(mountPrefixedPath));
     } catch (error) {
       return { error: error instanceof Error ? error.message : String(error) };
     }
     const absolutePath = resolve(mount.config.path, relativePath);
+    const maxBytes = opts.maxBytes;
+    let tooLarge: string | undefined;
     try {
-      const info = await stat(absolutePath);
-      if (!info.isFile()) return { error: `Not a file: ${mountPrefixedPath}` };
-      if (opts.maxBytes !== undefined && info.size > opts.maxBytes) {
-        return { error: `File too large: ${info.size} > ${opts.maxBytes} bytes` };
+      const { handle, fileStat } = await this.openContainedFile(mount, relativePath, mountPrefixedPath, (fileStat) => {
+        if (maxBytes !== undefined && fileStat.size > maxBytes) {
+          tooLarge = `File too large: ${fileStat.size} > ${maxBytes} bytes`;
+          throw new Error(tooLarge);
+        }
+      });
+      try {
+        if (maxBytes === undefined) return { data: await handle.readFile(), absolutePath };
+        // 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 };
+      } finally {
+        await handle.close();
       }
-      return { data: await readFile(absolutePath), absolutePath };
     } catch (error) {
-      const code = (error as { code?: string }).code;
-      if (code === 'ENOENT') return { error: `File not found on disk: ${mountPrefixedPath}` };
+      if (tooLarge !== undefined) return { error: tooLarge };
+      // A directory, or a file that isn't regular (the reader's refusal of
+      // one carries no errno), and a missing file keep this reader's words.
+      if (error instanceof WorkspaceReadError && (error.code === 'directory' || (error.code === 'not_found' && error.errno === undefined))) {
+        return { error: `Not a file: ${mountPrefixedPath}` };
+      }
+      if (error instanceof WorkspaceReadError && error.code === 'not_found' && (error.errno === 'ENOENT' || error.errno === 'ENOTDIR')) {
+        return { error: `File not found on disk: ${mountPrefixedPath}` };
+      }
       return { error: error instanceof Error ? error.message : String(error) };
     }
   }
 
-  /** The directories of the mounts nested inside a mount, mount-relative. */
+  /** The directories of the mounts nested inside a mount, mount-relative, in each spelling. */
   private othersOf(mountName: string): string[] {
-    return (this.otherMounts.get(mountName) ?? []).map((o) => o.dir);
+    return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => s.dir));
+  }
+
+  /**
+   * Which mounts are nested in which, read afresh at each start. A mount is
+   * nested in another where its configured path lies beneath the other's
+   * root, as configured or as it lies on disk, whatever links the path
+   * reaches that root through, or where its real root lies beneath the
+   * other's. Each root, and each directory above a configured path, is
+   * placed by realBeneath, awaited, so a root on a share that stops
+   * answering holds this start and not the process, and a root moved while
+   * the module was stopped is placed where it is now. A mount whose real
+   * root is the other's own, or holds it, is nested by its configured path
+   * alone, with no real root, since through it it would claim the other's
+   * every path.
+   *
+   * Each way it lies there is a spelling of its directory (`fromRoots`), and
+   * so is the spelling disk lists each of those by, where that differs. On a
+   * disk that folds names, the outer mount's walks name the directory as
+   * disk does, and so does a path parsePath has respelled, while a path given
+   * 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.
+   */
+  private async readNesting(): Promise<{ nesting: Map<string, NestedMountEntry[]>; reals: Map<string, 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
+    // one under macOS's /var reaches /private/var, is still read beneath it.
+    const above = new Map<string, Array<{ dir: string; real: string }>>();
+    for (const mount of this.config.mounts) {
+      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;
+      }
+      above.set(mount.name, dirs);
+    }
+    const nesting = new Map<string, NestedMountEntry[]>();
+    for (const outer of this.config.mounts) {
+      const outerPath = resolve(outer.path);
+      const outerReal = reals.get(outer.name)!;
+      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);
+        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) {
+          console.warn(
+            `[workspace] Mount "${outer.name}" contains mount "${inner.name}" where it lies on disk, ` +
+            `at ${placed.map((s) => `${s.dir}/`).join(' and ')} — passing over it as another mount's directory`,
+          );
+        }
+      }
+    }
+    return { nesting, reals };
+  }
+
+  /** The mounts nested in `mountName`, by directory, name and real root where it has one (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 })));
   }
 
   /**
@@ -1758,7 +2059,7 @@ export class WorkspaceModule implements Module {
     if (!mount) return undefined;
     const resolved = resolve(mount.config.path, relativePath);
     const holder = (this.otherMounts.get(mountName) ?? [])
-      .filter((o) => isContainedPath(o.root, resolved))
+      .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];
     if (!holder) return undefined;
     const rest = relative(holder.root, resolved).split(sep).join('/');
@@ -1785,17 +2086,98 @@ export class WorkspaceModule implements Module {
    * 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.
    */
-  private parseFilePath(path: string): { mount: MountState; relativePath: string } {
-    const parsed = this.parsePath(path);
+  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);
+    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.
+   */
+  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;
+    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);
+    }
+    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);
-    if (holder) throw new NestedMountError(path, parsed.mount.config.name, holder.name, holder.use);
+    if (holder) throw new NestedMountError(parsed.path, parsed.mount.config.name, holder.name, holder.use);
     return parsed;
   }
 
   /**
-   * Parse a mount-prefixed path into (mountName, relativePath).
+   * 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.
+   * 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.
+   */
+  private async parsePath(path: string): Promise<{ mount: MountState; relativePath: string; path: string }> {
+    const given = this.parsePathAsGiven(path);
+    const relativePath = await diskSpelling(resolve(given.mount.config.path), given.relativePath, this.entriesOf(given.mount));
+    return {
+      mount: given.mount,
+      relativePath,
+      path: relativePath === given.relativePath ? path : `${given.mount.config.name}/${relativePath}`,
+    };
+  }
+
+  /**
+   * 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
+   * root folds case as the last start read it (false before the first), and
+   * which nested mount's directory holds a path, by holderOf, as the
+   * nested-mount checks read it. diskSpelling keeps disk's spelling of a
+   * path that lies in a nested mount's directory as disk spells it, so the
+   * checks refuse at least what they would refuse without the entries.
+   */
+  private entriesOf(mount: MountState): WorkspaceEntries {
+    const store = this.getStore();
+    const intents = this.intents.get(mount.config.name)!;
+    return {
+      // An intent recorded at a path, such as a deletion disk hasn't been
+      // 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),
+      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.
    */
-  private parsePath(path: string): { mount: MountState; relativePath: string } {
+  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
     // store would keep one name and disk another.
     if (LONE_SURROGATE.test(path)) {
@@ -1875,35 +2257,137 @@ export class WorkspaceModule implements Module {
     return this.validateImageBytes(blob, mountPrefixedPath, maxSize);
   }
 
+  /**
+   * The mount root a disk read reads beneath: resolved, then checked as
+   * observation checks it (checkRoot), so the read and the evidence agree on
+   * which directory the mount is. Once the workspace has recorded the root's
+   * identity, a root that resolves to any other directory is refused, in
+   * ROOT_REPLACED's words; with none recorded yet, it need only be a
+   * directory there. A refusal where no directory is at the root's path
+   * carries the errno that gives (rootAbsence: ENOENT when nothing is there
+   * and ENOTDIR when something else is, which a caller can read as no file,
+   * or the errno the root's stat failed with otherwise, such as EACCES). A
+   * root whose realpath fails carries realpath's errno, and one that is
+   * another directory carries none. The identity is rootIdentityForRead's,
+   * 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.
+   */
+  private async readRoot(mount: MountState): Promise<{ real: string; dir: CheckedDir }> {
+    const name = mount.config.name;
+    const root = resolve(mount.config.path);
+    let real: string;
+    try {
+      real = await realpath(root);
+    } catch (err) {
+      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));
+    }
+    const checked = await checkRoot(this.viewOf(mount, rootIdentity), real);
+    if ('dir' in checked) return { real, dir: checked.dir };
+    // Another directory is no absence. For any other refusal, what is at the
+    // root's path now decides: nothing, something that isn't a directory, or
+    // a directory the path has come to name since it was resolved (no errno).
+    const errno = checked.reason === ROOT_REPLACED ? undefined : await rootAbsence(root);
+    throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${name}: ${checked.reason}`, 'root', errno);
+  }
+
+  /**
+   * The refusal for a root that stopped being the directory a read checked,
+   * 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.
+   */
+  private async rootMoved(mount: MountState): Promise<WorkspaceReadError> {
+    const errno = await rootAbsence(resolve(mount.config.path));
+    const reason = errno === undefined ? ROOT_REPLACED : ROOT_UNAVAILABLE;
+    return new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}: ${reason}`, 'root', errno);
+  }
+
   /**
    * Open a mount-relative file for reading with the mount boundary enforced on
    * the *filesystem*, not just the path string:
    *
-   * 1. `lstat` the lexical path — refuse directories; refuse a final-component
-   *    symlink when the mount does not `followSymlinks`.
-   * 2. Open with `O_NOFOLLOW` where the platform has it (POSIX) so the refusal
+   * 0. Check the root (readRoot) before anything beneath it: under a root
+   *    that isn't the mount's directory, no path says anything about the
+   *    mount's files, an absence included.
+   * 1. On a mount that does not `followSymlinks`, refuse a path with a symlink
+   *    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.
+   * 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.
+   * 3. Open with `O_NOFOLLOW` where the platform has it (POSIX) so the refusal
    *    holds against a symlink swapped in between lstat and open; where it
-   *    doesn't (Windows), re-`lstat` after opening instead.
-   * 3. `realpath` both the mount root and the opened path and require canonical
-   *    containment — this is what catches an *intermediate* symlinked
-   *    directory escaping the mount, and a followed symlink whose target lands
-   *    outside, on every platform (junctions included).
-   * 4. Confirm the descriptor and the canonical path are the same inode.
+   *    doesn't (Windows), re-`lstat` after opening instead. `O_NONBLOCK`, so a
+   *    FIFO swapped in meanwhile doesn't wait for a writer.
+   * 4. `realpath` the opened path. On a mount that does not `followSymlinks`,
+   *    refuse it again for a symlinked directory on its way, which catches one
+   *    swapped in since step 1 (linkRefusal). Then require canonical
+   *    containment in the root step 0 resolved — this is what catches an
+   *    *intermediate* symlinked directory escaping the mount, and a followed
+   *    symlink whose target lands outside, on every platform (junctions
+   *    included).
+   * 5. Confirm the descriptor and the canonical path are the same inode, and
+   *    the root still the directory step 0 checked.
    *
-   * `inspect` runs right after the descriptor is stat'd and before the
-   * containment work, so callers can impose size policy in the same order the
-   * image reader always has. The returned handle is the caller's to close.
+   * Whatever steps 1 to 5 refuse, a missing file included, is said of the
+   * mount's files only while the root is still that directory. If it isn't,
+   * the read is refused with the code and errno step 0 gives what is at the
+   * root's path then (rootMoved), as step 5's own check of the root does.
+   *
+   * `inspect` runs last, after the boundary's checks, so a caller's own check
+   * of the file, such as a size limit, never answers for a file the boundary
+   * refuses. The returned handle is the caller's to close.
    */
   private async openContainedFile(
     mount: MountState,
     relativePath: string,
     mountPrefixedPath: string,
     inspect?: (fileStat: Stats) => void,
+  ): Promise<{ handle: Awaited<ReturnType<typeof open>>; fileStat: Stats; realFilePath: string }> {
+    const root = await this.readRoot(mount);
+    try {
+      return await this.openBeneathRoot(mount, root, relativePath, mountPrefixedPath, inspect);
+    } catch (err) {
+      if (err instanceof WorkspaceReadError && err.code !== 'mount_unavailable' && !(await root.dir.stillHere())) {
+        throw await this.rootMoved(mount);
+      }
+      throw err;
+    }
+  }
+
+  /** Steps 1 to 5 of openContainedFile, beneath the root that step 0 checked. */
+  private async openBeneathRoot(
+    mount: MountState,
+    { real: realMountRoot, dir: rootDir }: { real: string; dir: CheckedDir },
+    relativePath: string,
+    mountPrefixedPath: string,
+    inspect?: (fileStat: Stats) => void,
   ): Promise<{ handle: Awaited<ReturnType<typeof open>>; fileStat: Stats; realFilePath: string }> {
     const lexicalPath = resolve(mount.config.path, relativePath);
     const follow = mount.config.followSymlinks === true;
     const useNoFollow = !follow && typeof fsConstants.O_NOFOLLOW === 'number';
 
+    // Before anything resolves the path, so a link's own answer comes first: a
+    // 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 };
+    const onTheWay = await linkOnTheWay(linkView, relativePath, 'parents');
+    if (onTheWay !== null) throw await linkReadError(mount, onTheWay, mountPrefixedPath, this.nestedOf(mount.config.name));
+
     let fileInfo: Awaited<ReturnType<typeof lstat>>;
     try {
       fileInfo = await lstat(lexicalPath);
@@ -1920,17 +2404,16 @@ export class WorkspaceModule implements Module {
     if (fileInfo.isSymbolicLink() && !follow) {
       throw new WorkspaceReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`, 'lstat');
     }
-
-    let realMountRoot: string;
-    try {
-      realMountRoot = await realpath(mount.config.path);
-    } catch (err) {
-      throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}`, 'realpath_root', errnoOf(err));
+    if (!fileInfo.isFile() && !fileInfo.isSymbolicLink()) {
+      // A FIFO, socket or device is never opened.
+      throw new WorkspaceReadError('not_found', `Not a regular file: ${mountPrefixedPath}`, 'lstat');
     }
 
     let handle: Awaited<ReturnType<typeof open>>;
     try {
-      handle = await open(lexicalPath, fsConstants.O_RDONLY | (useNoFollow ? fsConstants.O_NOFOLLOW : 0));
+      // O_NONBLOCK: a FIFO swapped in since the lstat opens at once instead of
+      // waiting for a writer, and the regular-file check below refuses it.
+      handle = await open(lexicalPath, fsConstants.O_RDONLY | NONBLOCK | (useNoFollow ? fsConstants.O_NOFOLLOW : 0));
     } catch (err) {
       const code = errnoOf(err);
       if (code === 'ENOENT' || code === 'ENOTDIR') {
@@ -1959,9 +2442,8 @@ export class WorkspaceModule implements Module {
         throw new WorkspaceReadError('directory', `Path is a directory: ${mountPrefixedPath}`, 'fstat');
       }
       if (!fileStat.isFile()) {
-        throw new WorkspaceReadError('not_found', `File not found: ${mountPrefixedPath}`, 'fstat');
+        throw new WorkspaceReadError('not_found', `Not a regular file: ${mountPrefixedPath}`, 'fstat');
       }
-      inspect?.(fileStat);
 
       if (!follow && !useNoFollow) {
         let postOpenInfo: Awaited<ReturnType<typeof lstat>>;
@@ -1990,9 +2472,16 @@ export class WorkspaceModule implements Module {
         throw new WorkspaceReadError('not_found', `Unable to resolve file: ${mountPrefixedPath}`, 'realpath', code);
       }
 
+      // A directory swapped for a link since the walk above is caught here, by
+      // what the path resolved to after the open.
+      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)) {
         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;
       try {
@@ -2007,7 +2496,16 @@ export class WorkspaceModule implements Module {
       if (pathStat.dev !== fileStat.dev || pathStat.ino !== fileStat.ino) {
         throw new WorkspaceReadError('changed', `File changed during read: ${mountPrefixedPath}`, 'stat');
       }
-
+      // Containment compares paths, so it can't see another directory put at
+      // the root's own path since step 0 (a drive unmounted mid-read): the
+      // root is asked again, as an effect asks it (effects.ts moved()). This
+      // sees the root as it is now, so a root replaced and put back before it
+      // isn't seen (observe.ts's header says why no check can be sure).
+      if (!(await rootDir.stillHere())) throw await this.rootMoved(mount);
+
+      // The caller's checks of the file, such as a size limit, come after the
+      // boundary's, so they never answer for a file the boundary refuses.
+      inspect?.(fileStat);
       return { handle, fileStat, realFilePath };
     } catch (err) {
       await handle.close();
@@ -2031,11 +2529,20 @@ export class WorkspaceModule implements Module {
    *   (`truncated`). The reads decide where the file ends, not the size fstat
    *   gave at the open, so the bound holds for a file that grows while it's
    *   read.
+   * - 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
+   *   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
+   *   errno for another directory. The file's bytes are then read through
+   *   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 file,
-   * directory, policy-denied symlink, outside-mount target, and
+   * 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(
@@ -2048,8 +2555,10 @@ export class WorkspaceModule implements Module {
     let mount: MountState;
     let relativePath: string;
     try {
-      ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
+      ({ mount, relativePath, path: mountPrefixedPath } = await this.parseFilePath(mountPrefixedPath));
     } catch (err) {
+      // 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'
         : message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
@@ -2086,17 +2595,39 @@ export class WorkspaceModule implements Module {
     const p = mountPrefixedPath;
     switch (err.code) {
       case 'mount_unavailable':
-        return new WorkspaceImageReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}`);
+        // With why, where the root's check says, such as a directory that
+        // isn't the mount's.
+        return new WorkspaceImageReadError('mount_unavailable', err.message);
       case 'directory':
         return new WorkspaceImageReadError('directory', `Path is a directory: ${p}`);
       case 'symlink':
-        return new WorkspaceImageReadError('symlink', `Symlinks are not allowed: ${p}`);
+        // The core reader's own words for a link at the path: "Symlinks are not
+        // allowed: <path>".
+        return new WorkspaceImageReadError('symlink', err.message);
+      case 'parent_symlink':
+        // The core reader's own words for a link on its way: which link and
+        // where it leads, with the setting for a link to a directory.
+        return new WorkspaceImageReadError('parent_symlink', err.message);
+      case 'other_mount':
+        // The core reader's own words for a path a link takes into a nested
+        // mount's directory: that mount and the path to use there. (#460's
+        // own other_mount, a path in that directory, is refused at parse,
+        // and so is a link found there before the read.)
+        return new WorkspaceImageReadError('other_mount', err.message);
       case 'escape':
-        return new WorkspaceImageReadError('escape', `Symlink escape detected: ${p}`);
+        // The core reader's own words: "Symlink escape detected: <path>" for a
+        // followed link that resolves outside the mount, and for a link on the
+        // way that leads outside a mount that doesn't follow links, which link.
+        return new WorkspaceImageReadError('escape', err.message);
       case 'changed':
         return new WorkspaceImageReadError('changed', `Image file changed during read: ${p}`);
       case 'not_found':
       default:
+        // The core reader's own words for a file that isn't regular, and for
+        // a directory on the way it couldn't ask about.
+        if (err.message.startsWith('Not a regular file') || err.stage === 'readlink') {
+          return new WorkspaceImageReadError('not_found', err.message);
+        }
         if (err.message.startsWith('File not found')) {
           return new WorkspaceImageReadError('not_found', `File not found: ${p}`);
         }
@@ -2160,8 +2691,10 @@ 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; a
-   * tombstone for a deletion), and push it to disk when the mount opts in via
+   * 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
+   * 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
    * `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
@@ -2171,22 +2704,25 @@ export class WorkspaceModule implements Module {
    * change reached the workspace but not disk (`refused`): the
    * autoMaterialize contract is that disk is the source of truth for
    * downstream agents. And, apart from it, why a write whose bytes reached
-   * disk left the file's mode as disk had it (`modeKept`). The caller holds
-   * the mount's turn and has settled the path first (settleBeforeMutation, or
-   * a pass over the path, as an edit makes).
+   * disk left the file's mode as disk had it (`modeKept`), and, for a
+   * deletion that cleared a conflict naming a disk file the workspace never
+   * took in, that nothing was unlinked (`note`). The caller holds the mount's
+   * turn and has settled the path first (settleBeforeMutation, or a pass over
+   * the path, as an edit makes).
    */
   private async commitToolChange(
     mount: MountState,
     relativePath: string,
     change: { kind: 'set'; blobHash: string; size: number; mode?: number } | { kind: 'remove'; previousHash: string },
     onCommitted?: () => void,
-  ): Promise<{ refused: string | null; modeKept: string | null }> {
+  ): Promise<{ refused: string | null; modeKept: string | null; note: string | null }> {
     const store = this.getStore();
     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 known = this.agreementOrThrow().get(mount.config.name, relativePath) !== undefined;
+    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
@@ -2205,20 +2741,49 @@ export class WorkspaceModule implements Module {
     } 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) => {
-        const next = { ...cur, tombstone: { hash: change.previousHash } };
-        delete next.origin;
-        return next;
+        agreed = !(evidence?.kind === 'absent' || (evidence === undefined && cur.origin === 'store'));
+        if (agreed) {
+          const next = { ...cur, tombstone: { hash: change.previousHash } };
+          delete next.origin;
+          return next;
+        }
+        // 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.
+        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`;
+        }
+        return {};
       });
+      if (!agreed) return { refused: null, modeKept: null, note };
     }
-    if (!this.pushesOnCommit(mount)) return { refused: null, modeKept: null };
+    if (!this.pushesOnCommit(mount)) return { refused: null, modeKept: null, note: null };
 
     const pushed = await this.pushUnlocked(mount, [relativePath], {
       applyDeletions: 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 };
+    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,
@@ -2226,7 +2791,7 @@ export class WorkspaceModule implements Module {
       op: change.kind === 'set' ? 'write' : 'delete',
       error: refused.reason,
     } as ProcessEvent);
-    return { refused: refused.reason, modeKept: null };
+    return { refused: refused.reason, modeKept: null, note: null };
   }
 
   // ==========================================================================
@@ -2300,7 +2865,8 @@ export class WorkspaceModule implements Module {
     }
     let content = generatedContent;
     if (content === undefined) {
-      const { mount, relativePath } = this.parseFilePath(input.path);
+      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);
@@ -2388,7 +2954,9 @@ export class WorkspaceModule implements Module {
     let mount: MountState;
     let relativePath: string;
     try {
-      ({ mount, relativePath } = this.parseFilePath(input.path));
+      let path: string;
+      ({ mount, relativePath, path } = await this.parseFilePath(input.path));
+      input = { ...input, path };
     } catch (err) {
       return {
         success: false,
@@ -2460,7 +3028,8 @@ export class WorkspaceModule implements Module {
     if (LONE_SURROGATE.test(input.content)) {
       return { success: false, isError: true, error: 'The write did nothing: "content" holds a lone UTF-16 surrogate, which UTF-8 can\'t store.' };
     }
-    const { mount, relativePath } = this.parseFilePath(input.path);
+    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 };
     }
@@ -2505,7 +3074,8 @@ export class WorkspaceModule implements Module {
         return { success: false, isError: true, error: `The edit did nothing: "${field}" holds a lone UTF-16 surrogate, which UTF-8 can't store.` };
       }
     }
-    const { mount, relativePath } = this.parseFilePath(input.path);
+    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 };
     }
@@ -2649,7 +3219,8 @@ export class WorkspaceModule implements Module {
   }
 
   private async handleDelete(input: DeleteInput): Promise<ToolResult> {
-    const { mount, relativePath } = this.parseFilePath(input.path);
+    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 };
     }
@@ -2665,13 +3236,17 @@ export class WorkspaceModule implements Module {
           return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
         }
 
-        const { refused } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash },
+        const { refused, note } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash },
           () => { committed = true; });
         if (refused !== null) return storedButUnfinished('delete', input.path, { refused });
 
         // Its whole receipt is what it changed: kept in the stub if the guard
         // withholds the result (agent-framework #277).
-        return { success: true, data: { path: input.path, deleted: true }, keepWhenWithheld: ['path', 'deleted'] };
+        return {
+          success: true,
+          data: { path: input.path, deleted: true, ...(note ? { note } : {}) },
+          keepWhenWithheld: ['path', 'deleted', 'note'],
+        };
       });
     } catch (error) {
       if (!committed) throw error;
@@ -2692,7 +3267,8 @@ export class WorkspaceModule implements Module {
       return { success: true, data: { mounts } };
     }
 
-    const { mount, relativePath } = this.parsePath(input.path);
+    const { mount, relativePath, path } = await this.parsePath(input.path);
+    input = { ...input, path };
     const recursive = input.recursive === true;
 
     // Every listing checks the paths it shows against disk first, under the
@@ -2745,7 +3321,7 @@ export class WorkspaceModule implements Module {
 
     // Search across mounts
     const mountsToSearch = input.path
-      ? [this.parsePath(input.path)]
+      ? [await this.parsePath(input.path)]
       : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
 
     // Every match lies beneath the pattern's literal directory, so the walk
@@ -2797,7 +3373,7 @@ export class WorkspaceModule implements Module {
     const contextAfter = input.contextAfter ?? 0;
 
     const mountsToSearch = input.path
-      ? [this.parsePath(input.path)]
+      ? [await this.parsePath(input.path)]
       : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
 
     type GrepMatch = { line: number; text: string; context?: string[] };
@@ -2848,12 +3424,29 @@ export class WorkspaceModule implements Module {
         // 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 });
-          if (next.branchId === undefined || next.branchId === store.currentBranch().id) pass = next;
+          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({
@@ -2883,6 +3476,11 @@ export class WorkspaceModule implements Module {
           // 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;
@@ -3062,7 +3660,7 @@ 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 = this.parsePath(input.path);
+    if (input.path) explicit = await this.parsePath(input.path);
 
     let mountsToMaterialize: Array<{ name: string; mount: MountState }>;
     if (explicit) {
@@ -3248,7 +3846,7 @@ 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 } = this.parsePath(input.path);
+      const { mount, relativePath } = await this.parsePath(input.path);
       targets = [{ name: mount.config.name, mount, relativePath }];
     } else if (input.mount) {
       const m = this.mounts.get(input.mount);