@animalabs/agent-framework 0.22.4 → 0.23.1

package/dist/src/modules/workspace/index.js

@@ -6,14 +6,14 @@
  */
 import { isUtf8 } from 'node:buffer';
 import { constants as fsConstants } 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 { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher } 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 } from './observe.js';
 import { TOOL_BATCH_HOOK_TIMEOUT_MS, ensureStateRegistered } from '../../module-registry.js';
 import { NOT_PUSHED_IN_OTHER_MOUNT, WALK_CAP, entryMode, pushPaths, reconcilePass, settleAdoptionBeforeMutation, } from './reconcile.js';
 /** Default for how long the after-batch scan may hold the agent's next inference. */
@@ -44,8 +44,8 @@ class WorkspaceImageReadError extends Error {
  * use there.
  */
 class NestedMountError extends Error {
-    constructor(path, mount, holder, use) {
-        super(`"${path}" lies in mount "${holder}", nested in mount "${mount}", which neither reads nor writes it: use "${use}".`);
+    constructor(path, mount, holder, use, how = 'lies in') {
+        super(`"${path}" ${how} mount "${holder}", nested in mount "${mount}", which neither reads nor writes it: use "${use}".`);
     }
 }
 /**
@@ -72,6 +72,20 @@ function errnoOf(err) {
         ? err.code
         : 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) {
+    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, mountPrefixedPath) {
     return new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
@@ -99,6 +113,77 @@ function startsWithBytes(buffer, prefix) {
 function matchesPartialPrefix(buffer, prefix) {
     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, found, mountPrefixedPath, nested) {
+    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, to) {
+    const rel = relative(from, to);
+    if (!rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel))
+        return undefined;
+    return rel.split(sep).join('/');
+}
+/** 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, links = 0) {
+    // 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, candidate) {
     if (candidate === root)
         return true;
@@ -474,6 +559,8 @@ export class WorkspaceModule {
     store = null;
     /** Set once stop has drained and saved, cleared by start (running()). */
     stopped = false;
+    /** Stops begun, so a start that read disk meanwhile can tell that one came. */
+    stopsBegun = 0;
     config;
     mounts = new Map();
     watchers = new Map();
@@ -489,10 +576,19 @@ export class WorkspaceModule {
     /** Per canonical root: the device of its filesystem when that maintains ctime, else null. */
     ctimeTrust = new Map();
     /**
-     * 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).
      */
     otherMounts = new Map();
+    /** Whether each mount's root folds case (foldsCase), where disk has it, as the last start read it. */
+    rootFoldsCase = new Map();
     /**
      * Whether a file's mode is observed, taken in and applied (MountRuntime's
      * `modesObserved`): not on Windows, which reports no POSIX modes. A test
@@ -518,26 +614,22 @@ export class WorkspaceModule {
         // 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;
@@ -617,6 +709,24 @@ export class WorkspaceModule {
             throw new Error('Workspace store not initialized');
         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.
+     */
+    viewOf(mount, rootIdentity) {
+        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. */
     async runtime(mount) {
         const root = resolve(mount.config.path);
@@ -629,14 +739,7 @@ export class WorkspaceModule {
         }
         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,
@@ -648,14 +751,14 @@ export class WorkspaceModule {
         };
     }
     /**
-     * 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.
      */
@@ -707,6 +810,21 @@ export class WorkspaceModule {
         });
     }
     async start(ctx) {
+        // 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();
+        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;
         // Decode persisted state if restarting; application waits until mounts
@@ -944,6 +1062,7 @@ export class WorkspaceModule {
         }
     }
     async stop() {
+        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
@@ -954,11 +1073,13 @@ export class WorkspaceModule {
         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]))
+            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
@@ -1233,6 +1354,22 @@ export class WorkspaceModule {
     async handleToolCall(call) {
         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.
+     */
+    callsUnderWay = new Set();
+    /** `work`, recorded as under way until it settles (callsUnderWay). */
+    underWay(work) {
+        this.callsUnderWay.add(work);
+        const done = () => { this.callsUnderWay.delete(work); };
+        work.then(done, done);
+        return work;
+    }
+    async runToolCall(call) {
         try {
             // Every handler reads its input as its schema describes it; a call
             // that sends something else is refused here, before anything is read.
@@ -1356,7 +1493,10 @@ export class WorkspaceModule {
      */
     resolveAbsolutePath(mountPrefixedPath) {
         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 {
@@ -1387,10 +1527,13 @@ export class WorkspaceModule {
     async writeBinary(mountPrefixedPath, data, mimeType, options = {}) {
         if (!this.running())
             return { success: false, isError: true, error: NOT_RUNNING };
+        return this.underWay(this.writeBinaryUnderWay(mountPrefixedPath, data, mimeType, options));
+    }
+    async writeBinaryUnderWay(mountPrefixedPath, data, mimeType, options) {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
+            ({ mount, relativePath, path: mountPrefixedPath } = await this.parseFilePath(mountPrefixedPath));
         }
         catch (error) {
             return {
@@ -1451,10 +1594,13 @@ export class WorkspaceModule {
     async readBinary(mountPrefixedPath) {
         if (!this.running())
             return { error: NOT_RUNNING };
+        return this.underWay(this.readBinaryUnderWay(mountPrefixedPath));
+    }
+    async readBinaryUnderWay(mountPrefixedPath) {
         let mount;
         let relativePath;
         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) };
@@ -1483,38 +1629,150 @@ export class WorkspaceModule {
      * 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, opts = {}) {
         let mount;
         let relativePath;
         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;
         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.code;
-            if (code === 'ENOENT')
+            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. */
     othersOf(mountName) {
-        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.
+     */
+    async readNesting() {
+        const reals = new Map();
+        // 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();
+        for (const mount of this.config.mounts) {
+            const given = resolve(mount.path);
+            reals.set(mount.name, await realBeneath(given));
+            const dirs = [];
+            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();
+        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 = [];
+                // 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. */
+    nestedOf(mountName) {
+        return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => ({ dir: s.dir, name: o.name, real: o.real })));
     }
     /**
      * The innermost mount nested in `mountName` whose directory holds a path
@@ -1529,7 +1787,7 @@ export class WorkspaceModule {
             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;
@@ -1555,17 +1813,98 @@ export class WorkspaceModule {
      * 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.
      */
-    parseFilePath(path) {
-        const parsed = this.parsePath(path);
+    async parseFilePath(path) {
+        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.
+     */
+    async leadsIntoNested(mount, relativePath, path) {
+        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). */
+    refuseNested(parsed) {
         const holder = this.holderOf(parsed.mount.config.name, parsed.relativePath);
         if (holder)
-            throw new NestedMountError(path, parsed.mount.config.name, holder.name, holder.use);
+            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.
      */
-    parsePath(path) {
+    async parsePath(path) {
+        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.
+     */
+    entriesOf(mount) {
+        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.
+     */
+    parsePathAsGiven(path) {
         // 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)) {
@@ -1629,29 +1968,125 @@ export class WorkspaceModule {
         }
         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.
+     */
+    async readRoot(mount) {
+        const name = mount.config.name;
+        const root = resolve(mount.config.path);
+        let real;
+        try {
+            real = await realpath(root);
+        }
+        catch (err) {
+            throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${name}`, 'realpath_root', errnoOf(err));
+        }
+        let 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.
+     */
+    async rootMoved(mount) {
+        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.
      */
     async openContainedFile(mount, relativePath, mountPrefixedPath, inspect) {
+        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. */
+    async openBeneathRoot(mount, { real: realMountRoot, dir: rootDir }, relativePath, mountPrefixedPath, inspect) {
         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;
         try {
             fileInfo = await lstat(lexicalPath);
@@ -1669,16 +2104,15 @@ export class WorkspaceModule {
         if (fileInfo.isSymbolicLink() && !follow) {
             throw new WorkspaceReadError('symlink', `Symlinks are not allowed: ${mountPrefixedPath}`, 'lstat');
         }
-        let realMountRoot;
-        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;
         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);
@@ -1703,9 +2137,8 @@ export class WorkspaceModule {
                 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;
                 try {
@@ -1733,9 +2166,17 @@ export class WorkspaceModule {
                 }
                 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;
             try {
                 pathStat = await stat(realFilePath);
@@ -1750,6 +2191,16 @@ export class WorkspaceModule {
             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) {
@@ -1773,11 +2224,20 @@ export class WorkspaceModule {
      *   (`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(mountPrefixedPath, options = {}) {
@@ -1787,9 +2247,12 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         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 = err instanceof NestedMountError ? 'other_mount'
                 : message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
@@ -1828,17 +2291,39 @@ export class WorkspaceModule {
         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}`);
                 }
@@ -1902,8 +2387,10 @@ export class WorkspaceModule {
     }
     /**
      * 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
@@ -1913,9 +2400,11 @@ export class WorkspaceModule {
      * 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).
      */
     async commitToolChange(mount, relativePath, change, onCommitted) {
         const store = this.getStore();
@@ -1923,7 +2412,8 @@ export class WorkspaceModule {
         // 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
@@ -1944,21 +2434,51 @@ export class WorkspaceModule {
         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 = 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 };
+            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 };
+            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,
@@ -1966,7 +2486,7 @@ export class WorkspaceModule {
             op: change.kind === 'set' ? 'write' : 'delete',
             error: refused.reason,
         });
-        return { refused: refused.reason, modeKept: null };
+        return { refused: refused.reason, modeKept: null, note: null };
     }
     // ==========================================================================
     // Lazy Sync
@@ -2036,7 +2556,8 @@ export class WorkspaceModule {
         }
         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 () => {
                 const report = await this.ensureSynced(mount, relativePath);
@@ -2123,7 +2644,9 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parseFilePath(input.path));
+            let path;
+            ({ mount, relativePath, path } = await this.parseFilePath(input.path));
+            input = { ...input, path };
         }
         catch (err) {
             return {
@@ -2195,7 +2718,8 @@ export class WorkspaceModule {
         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 };
         }
@@ -2238,7 +2762,8 @@ export class WorkspaceModule {
                 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 };
         }
@@ -2376,7 +2901,8 @@ export class WorkspaceModule {
         }
     }
     async handleDelete(input) {
-        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 };
         }
@@ -2390,12 +2916,16 @@ export class WorkspaceModule {
                 if (!entry) {
                     return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
                 }
-                const { refused } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash }, () => { committed = true; });
+                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) {
@@ -2415,7 +2945,8 @@ export class WorkspaceModule {
             }));
             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
         // three-way rule, whatever the mount's watch mode.
@@ -2464,7 +2995,7 @@ export class WorkspaceModule {
         const incomplete = [];
         // 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
         // starts there: past the walk's cap, a walk of the whole scope can stop
@@ -2511,7 +3042,7 @@ export class WorkspaceModule {
         const contextBefore = input.contextBefore ?? 0;
         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: '' }));
         const results = [];
         const skipped = [];
@@ -2557,13 +3088,31 @@ export class WorkspaceModule {
                 // 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 = null;
+                let refused = new Map();
                 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)
+                    const asked = new Map();
+                    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({
@@ -2594,6 +3143,11 @@ export class WorkspaceModule {
                     // 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;
@@ -2780,7 +3334,7 @@ export class WorkspaceModule {
         const modesKept = [];
         let explicit = null;
         if (input.path)
-            explicit = this.parsePath(input.path);
+            explicit = await this.parsePath(input.path);
         let mountsToMaterialize;
         if (explicit) {
             mountsToMaterialize = [{ name: explicit.mount.config.name, mount: explicit.mount }];
@@ -2957,7 +3511,7 @@ export class WorkspaceModule {
         // A path names its own mount; otherwise the given mount, or every mount.
         let targets;
         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) {