@animalabs/agent-framework 0.22.3 → 0.23.0

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

@@ -37,14 +37,16 @@
  */
 import { createHash } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
-import { lstat, mkdir, open, readdir, realpath, stat, statfs } from 'node:fs/promises';
-import { dirname, join, posix, sep } from 'node:path';
+import { lstat, mkdir, open, readdir, readlink, realpath, stat, statfs } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { sameRootIdentity } from './disk-agreement.js';
 /**
- * Opened with every read or write of a workspace path, where the platform has
- * it: for a regular file it changes nothing, and a FIFO or other special file
- * swapped in at the path neither blocks the open nor passes the regular-file
- * check that follows.
+ * Opened with every open of a workspace path that may already be there, a
+ * read, a write in place or a directory's sync, where the platform has it:
+ * for a regular file or a directory it changes nothing, and a FIFO or other
+ * special file swapped in at the path neither blocks the open nor passes the
+ * check of its kind that follows. A create needs none: O_CREAT | O_EXCL fails
+ * at once on anything already at the path.
  */
 export const NONBLOCK = typeof fsConstants.O_NONBLOCK === 'number' ? fsConstants.O_NONBLOCK : 0;
 /** Bytes hashed per read when streaming a file larger than the read limit. */
@@ -79,6 +81,467 @@ export function nameOf(relativePath) {
 function lexicalOf(view, rel) {
     return rel === '' ? view.root : join(view.root, rel);
 }
+const UNSURE_PREFIX = 'cannot tell whether "';
+/**
+ * On a mount that doesn't follow symlinks, what is on the way to a
+ * mount-relative path: the first directory, from beneath the mount's root
+ * down to the path itself (or, `through` 'parents', down to its parent), that
+ * is a symlink, or one the walk couldn't ask. Null when there is none, or
+ * when the mount follows symlinks. The path is
+ * walked as the lookups that follow resolve it, with `.` and `..` taken out,
+ * so a `..` after a name that isn't there hides nothing beyond it, and the
+ * root, which is the configured path whatever it resolves to, is never on the
+ * way, even where the path names it on its way back into the mount. Each
+ * directory is asked only whether it is a link, by readlink, from the root
+ * down. EINVAL means it isn't, and the walk goes on. Nothing there, a file in
+ * the way, or a directory this user can't search (ENOENT, ENOTDIR, EACCES)
+ * ends it with nothing found, since nothing beneath is reached through a link
+ * and the caller's own lookup meets the same answer. Any other answer, EPERM
+ * included, leaves it unsure of what's beneath, and the path is refused for
+ * that.
+ */
+export async function linkOnTheWay(view, rel, through = 'path') {
+    if (view.followSymlinks)
+        return null;
+    const resolved = relative(resolve(view.root), resolve(view.root, rel));
+    if (resolved === '' || resolved === '..' || resolved.startsWith(`..${sep}`) || isAbsolute(resolved))
+        return null;
+    const parts = resolved.split(sep);
+    const last = through === 'path' ? parts.length : parts.length - 1;
+    for (let i = 1; i <= last; i++) {
+        const at = parts.slice(0, i).join('/');
+        try {
+            await readlink(join(view.root, at));
+            return { link: at };
+        }
+        catch (err) {
+            const code = errno(err);
+            if (code === 'EINVAL')
+                continue; // not a link: on to the next directory
+            if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EACCES')
+                return null;
+            return { unsure: at, code: code ?? String(err) };
+        }
+    }
+    return null;
+}
+/**
+ * On a mount that doesn't follow symlinks, what refuses the mount-relative
+ * `rel`, which realpath resolved to `real` (or, `through` 'parents', whose
+ * parent it resolved to `real`): the first symlink on its way, or a
+ * directory there the walk couldn't ask. Null when the mount follows
+ * symlinks, or there's none. Where `real` is the root's canonical path joined
+ * with what was resolved (`rel`, or with `through` 'parents', its parent),
+ * nothing beneath the root resolved through a link, and nothing more is
+ * asked: that is every path through ordinary directories, at no cost
+ * per path. Otherwise each directory is asked in turn (linkOnTheWay), since a
+ * name spelled otherwise than disk spells it, on a file system that ignores
+ * case or Unicode normalization, also resolves to another string, and isn't
+ * a link.
+ */
+export async function linkRefusal(view, rootReal, rel, real, through = 'path') {
+    if (view.followSymlinks)
+        return null;
+    const resolvedAt = through === 'path' ? rel : parentOf(rel);
+    if (resolvedAt === '' || real === join(rootReal, resolvedAt))
+        return null;
+    return linkOnTheWay(view, rel, through);
+}
+export async function linkLeads(root, rootReal, link) {
+    const leads = await realpath(join(root, link)).catch(() => null);
+    if (leads === null)
+        return { kind: 'nowhere' };
+    if (!contained(rootReal, leads))
+        return { kind: 'outside' };
+    const directory = await stat(leads).then((info) => info.isDirectory(), () => false);
+    return { kind: 'inside', target: relative(rootReal, leads).split(sep).join('/'), directory };
+}
+/**
+ * The nested mount whose directory holds `target` (mount-relative), the
+ * innermost where nested mounts nest, as #460 picks one; undefined when none
+ * does.
+ */
+export function nestedHolder(target, nested) {
+    return nested
+        .filter((n) => target === n.dir || target.startsWith(`${n.dir}/`))
+        .sort((a, b) => b.dir.length - a.dir.length)[0];
+}
+/**
+ * Why a path is refused for what linkOnTheWay found, given where a link
+ * leads (linkLeads). For a link, the link is the subject, with where it
+ * leads: for a link inside the mount, its target, and for a link to a
+ * directory there, the setting the mount's host can change (the link stands
+ * among the path's directories, so following a link to a file can't make the
+ * path beneath it exist); for one leading outside the mount, that it does;
+ * for one that can't be resolved, nothing more. A target in a nested mount's
+ * directory (`nested`) is that mount's: the refusal names the mount and the
+ * path to use there in place of the link, and offers no setting, since
+ * following the link would only reach into another mount's directory. For a
+ * directory the walk couldn't ask, which one, and the answer it got. Paths
+ * are spelled as the tools take them, from the mount's name.
+ */
+export function linkWords(name, found, leads, nested = []) {
+    const spell = (rel) => `"${rel === '' ? name : `${name}/${rel}`}"`;
+    if (!('link' in found))
+        return `${UNSURE_PREFIX}${name}/${found.unsure}" is a symlink (${found.code})`;
+    const link = `${spell(found.link)} is a symlink`;
+    if (leads === null || leads.kind === 'nowhere')
+        return `${link}, which this mount does not follow`;
+    if (leads.kind === 'outside')
+        return `${link} leading outside the mount, which this mount does not follow`;
+    const holder = nestedHolder(leads.target, nested);
+    if (holder) {
+        const rest = leads.target.slice(holder.dir.length + 1);
+        return `${link} to ${spell(leads.target)}, which this mount does not follow; it lies in mount "${holder.name}", ` +
+            `nested in mount "${name}": use "${rest ? `${holder.name}/${rest}` : holder.name}" in place of ${spell(found.link)}`;
+    }
+    const setting = leads.directory ? "; the mount's host can set followSymlinks: true" : '';
+    return `${link} to ${spell(leads.target)}, which this mount does not follow${setting}`;
+}
+/** Why a path is refused for what linkOnTheWay found (linkWords, with where the link leads). */
+export async function linkReason(view, rootReal, found) {
+    return linkWords(view.name, found, 'link' in found ? await linkLeads(view.root, rootReal, found.link) : null, view.nested);
+}
+/**
+ * The nested mount whose root holds `real`, a canonical path, the innermost,
+ * with the path to use there; undefined when none does. A path the lexical
+ * checks pass (inOtherMount, the tools' holderOf) reaches another mount's
+ * directory this way through a symlink the mount follows, so each check that
+ * resolves a path canonically asks this too.
+ */
+export function nestedAtReal(real, nested = []) {
+    const holder = nested
+        .flatMap((n) => (n.real !== undefined && contained(n.real, real) ? [{ name: n.name, real: n.real }] : []))
+        .sort((a, b) => b.real.length - a.real.length)[0];
+    if (!holder)
+        return undefined;
+    const rest = relative(holder.real, real).split(sep).join('/');
+    return { name: holder.name, use: rest ? `${holder.name}/${rest}` : holder.name };
+}
+/**
+ * Why a mount-relative path that resolves into a nested mount's directory is
+ * refused (nestedAtReal): what it leads into, and the path to use in its
+ * place. Spelled as the tools take paths, from the mount's name.
+ */
+export function leadsInto(name, rel, holder) {
+    return `"${rel === '' ? name : `${name}/${rel}`}" leads into mount "${holder.name}", nested in mount "${name}": use "${holder.use}" in its place`;
+}
+// ===========================================================================
+// Disk's spelling of a path
+// ===========================================================================
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+/** A letter's other case: its upper case if it's in lower case, else its lower case. */
+const otherCase = (c) => (c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase());
+/**
+ * The name with each letter's case flipped, where its other case is one
+ * letter whose own other case is the letter again, so the flip changes only
+ * pairs that any folding disk folds together. `ß`, whose upper case is `SS`,
+ * and dotless `ı`, whose upper case `I` lowers to `i`, stay as they are.
+ */
+const flippedCase = (name) => [...name].map((c) => {
+    const other = otherCase(c);
+    return [...other].length === 1 && otherCase(other) === c ? other : c;
+}).join('');
+/** Names compared as NFC in lower case. */
+const folded = (name) => name.normalize('NFC').toLowerCase();
+/**
+ * Names compared more loosely, through upper case and back, which also folds
+ * `ß` with `ss`, `ſ` with `s` and `ς` with `σ`, as a disk that folds fully
+ * does. It also folds dotless `ı` with `i`, which a disk may keep apart;
+ * the same-file check keeps that from naming another file.
+ */
+export const foldedLoosely = (name) => name.normalize('NFC').toLowerCase().toUpperCase().toLowerCase();
+/**
+ * Whether `dir` folds case, told without writing: by looking up flipped a
+ * name it lists whose flipped spelling it doesn't list too (a name with no
+ * letter to flip is its own flipped spelling, and two hard links that differ
+ * only in case are one file on any disk). Where no name it lists tells, or
+ * it can't be listed, the directory holding it is asked instead, where both
+ * are on one device, each as a link to it leads: its own name looked up
+ * flipped there, or, for a name with no letter to flip, that directory's own
+ * folding. A directory on a device of its own is taken to tell case apart. A
+ * directory not there yet folds as the one it would be made in. Where
+ * nothing tells, it's taken to tell case apart.
+ */
+export async function foldsCase(dir) {
+    const holder = dirname(dir);
+    let listed;
+    try {
+        listed = new Set(await readdir(dir));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' && holder !== dir)
+            return foldsCase(holder);
+        listed = new Set();
+    }
+    const look = (path) => lstat(path, { bigint: true }).catch(() => null);
+    const name = [...listed].find((n) => !listed.has(flippedCase(n)));
+    if (name !== undefined) {
+        const [named, flipped] = await Promise.all([look(join(dir, name)), look(join(dir, flippedCase(name)))]);
+        return named != null && flipped != null && sameFile(named, flipped);
+    }
+    if (holder === dir)
+        return false;
+    // The directory and its holder are looked up through links, so a root
+    // that is one, or is reached through one, is compared by the device it
+    // lies on. Whether the holder folds is told by its own entries, the root's
+    // name and the flipped name, each looked up without following a link
+    // there: a link at the flipped name to the root is another file, and a
+    // root that is a link is found as itself.
+    const see = (path) => stat(path, { bigint: true }).catch(() => null);
+    const own = basename(dir);
+    const [self, held, entry, flipped] = await Promise.all([see(dir), see(holder), look(dir), look(join(holder, flippedCase(own)))]);
+    if (self == null || held == null || self.dev !== held.dev)
+        return false;
+    if (flippedCase(own) === own)
+        return foldsCase(holder);
+    return entry != null && flipped != null && sameFile(entry, flipped);
+}
+/**
+ * A name in simple case folding, letter by letter: each letter as the lower
+ * case of its upper case, so `Σ` and a word's last `ς` are both `σ`, `ſ` is
+ * `s` and `µ` is `μ`. A letter whose upper case is more than one letter
+ * takes its own lower case instead, as the Greek `ᾈ` takes `ᾀ` and `ß` stays
+ * `ß`. A letter whose lower case is more than one letter too, as `İ`'s is,
+ * stays as it is, and so does dotless `ı`, whose upper case `I` lowers to
+ * `i`, which case folding keeps apart from it. Unicode normalization is left
+ * alone, and so are letters only a fuller folding joins, such as `ß` with
+ * `ss`: no listing shows two such names to be one file, and a disk that
+ * folds case needn't join them.
+ */
+export const lowered = (name) => [...name].map((c) => {
+    if (c === '\u0131')
+        return c;
+    const upper = c.toUpperCase();
+    const lower = [...upper].length === 1 ? upper.toLowerCase() : c.toLowerCase();
+    return [...lower].length === 1 ? lower : c;
+}).join('');
+/**
+ * The name `segment` takes among the workspace's entries directly under the
+ * directory `prefix` (its path and `/`, or `''` for the mount's root): the
+ * segment itself where an entry is there under it, else the first name, in
+ * the order given, equal to it in simple case folding (lowered), else null.
+ * A name is compared again only where another name came between its entries,
+ * as `N.txt` comes between `N` and `N/x` in path order, so the step doesn't
+ * fold a name once for every entry beneath it.
+ */
+function entryName(paths, prefix, segment) {
+    const want = lowered(segment);
+    let found = null;
+    let previous = null;
+    for (const path of paths) {
+        if (!path.startsWith(prefix))
+            continue;
+        const rest = path.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        const name = slash === -1 ? rest : rest.slice(0, slash);
+        if (name === previous)
+            continue;
+        previous = name;
+        if (name === segment)
+            return segment;
+        if (found === null && lowered(name) === want)
+            found = name;
+    }
+    return found;
+}
+/**
+ * The name `dir` lists for `segment`: `segment` itself, unless disk folds it
+ * there and lists it otherwise. `dir` is listed only where a variant of
+ * `segment`, its case flipped or its other Unicode normalization form, finds
+ * the same file (device and inode) as `given`, the segment's own entry, as
+ * on a disk that folds names. The last segment isn't looked up as given, so
+ * for it any variant found leads to the listing: on a disk that tells
+ * spellings apart, that's only where `dir` holds a variant as a name of its
+ * own. The name as given wins if it's listed; otherwise the segment takes
+ * the listed name that folds to it and is the same file, so the name
+ * returned reaches the file the segment does, or is the segment as given.
+ * Names are compared as NFC in lower case first, and only where none of
+ * those is the file, more loosely (foldedLoosely). A directory that can't be
+ * listed, or a name that can't be looked up, leaves the segment as given. A
+ * segment with no variant at all, no letter to flip and one normalization
+ * form, is looked up as given and keeps its spelling; for a last segment
+ * with a letter that case maps, such as `ς`, the listing then says whether
+ * disk lists it as given. `found` says whether the lookups found disk's
+ * file: for a directory, its own lookup; for a last segment, whether a
+ * variant was found, which on a disk that tells spellings apart may be
+ * another file, or for one with no variant, whether disk has it as given, by
+ * the listing where it was read. `caseFolds` says what looking the segment
+ * up with its case flipped showed of `dir`: that it folds case, that it
+ * tells case apart, or nothing (null), for a segment with no letter to flip.
+ * For a segment not looked up as given (`given` null), `caseFolds` is set
+ * from whatever file the flipped spelling finds, which tells nothing of
+ * `dir`; diskSpelling reads it only for directories, which are looked up as
+ * given.
+ */
+async function listedName(dir, segment, given) {
+    const flipped = flippedCase(segment);
+    const variants = new Set([flipped, segment.normalize('NFC'), segment.normalize('NFD')]);
+    variants.delete(segment);
+    // A segment with no variant to try, such as `2024` or `ς`, is looked up
+    // as given, the only way to learn that disk has it. A last segment with a
+    // letter that case maps, as `ς` does, can reach a file disk lists in
+    // another spelling, such as `σ`, on a disk that folds more than case
+    // pairs, so there the listing settles whether disk lists it as given.
+    if (variants.size === 0) {
+        const own = given ?? await lstat(join(dir, segment), { bigint: true }).catch(() => null);
+        if (given !== null || own === null || (segment.toLowerCase() === segment && segment.toUpperCase() === segment)) {
+            return { name: segment, found: own !== null, caseFolds: null };
+        }
+        const listed = await readdir(dir).catch(() => null);
+        return { name: segment, found: listed?.includes(segment) ?? true, caseFolds: null };
+    }
+    let folds = false;
+    let caseFolds = flipped === segment ? null : false;
+    for (const variant of variants) {
+        const other = await lstat(join(dir, variant), { bigint: true }).catch(() => null);
+        if (other !== null && (given === null || sameFile(other, given))) {
+            folds = true;
+            if (variant === flipped)
+                caseFolds = true;
+            break;
+        }
+    }
+    const as = (name) => ({ name, found: folds, caseFolds });
+    if (!folds)
+        return as(segment);
+    const listed = await readdir(dir).catch(() => null);
+    if (listed === null || listed.includes(segment))
+        return as(segment);
+    const target = given ?? await lstat(join(dir, segment), { bigint: true }).catch(() => null);
+    if (target === null)
+        return as(segment);
+    for (const fold of [folded, foldedLoosely]) {
+        for (const name of listed) {
+            if (fold(name) !== fold(segment))
+                continue;
+            const info = await lstat(join(dir, name), { bigint: true }).catch(() => null);
+            if (info !== null && sameFile(info, target))
+                return as(name);
+        }
+    }
+    return as(segment);
+}
+/**
+ * `relativePath` as disk spells it. On a disk that folds names, as macOS's
+ * does by default (case and Unicode normalization), `SRC/a.ts` reaches
+ * `src/a.ts`, and whatever names what it finds from the spelling it was
+ * given takes the file in a second time, under a name disk doesn't list. So
+ * each segment, from the mount's root down, takes the name its directory
+ * lists for it (listedName). The walk goes on beneath a segment only if it's
+ * a directory, a symlink not included, so nothing past a link is read. It
+ * passes over an empty or `.` segment, which names the directory reached,
+ * and goes back up at `..`, to the directory it came from. At the mount's
+ * root a `..` stops it, keeping the rest as given: a path can climb above
+ * the root and come back in, as `../proj/x` does for a root named `proj`, and
+ * walking that would list the directory above the root. An absolute path
+ * keeps its spelling too: it names a place from the filesystem's root, not
+ * the mount's, so walking it from the mount's root would respell it against
+ * other directories, and the path returned could lead outside the mount.
+ *
+ * Given the workspace's `entries`, an entry not yet on disk spells its path
+ * as its file will. A path the workspace holds an entry at exactly keeps its
+ * spelling whole, and so does a last segment where the workspace holds an
+ * entry at exactly that path once its directories have taken disk's
+ * spelling, so an entry that disk lists in another spelling, or in a
+ * directory disk lists in another, stays reachable by its own path. `has`
+ * counts a path the workspace records an intent at, such as a deletion disk
+ * hasn't been given yet, so that's reached by its own path too. And where
+ * the directory reached folds case, each segment disk has nothing for takes
+ * the name of an entry it equals in simple case folding (entryName), as the
+ * disk will once that entry is written: a second draft spelled in another
+ * case is the first one. None of this applies where disk's spelling puts the
+ * path in a nested mount's directory, by the nested-mount checks' own
+ * reading (`holder`): there the path keeps disk's spelling, so they refuse
+ * at least what they refuse without the entries. The root's folding is read
+ * at start (`rootFoldsCase`), and a directory beneath it is taken to fold as
+ * the directory holding it did when its name was looked up with its case
+ * flipped, or, for a name with no letter to flip, as the nearest directory
+ * above that told, so the step reads nothing more of disk for this.
+ */
+export async function diskSpelling(root, relativePath, entries) {
+    if (relativePath === '' || isAbsolute(relativePath))
+        return relativePath;
+    // A path that names an entry exactly keeps its spelling, read before the
+    // walk awaits disk, so the entries' walk needn't run for it.
+    const exact = entries?.has(relativePath) ?? false;
+    // The path as disk spells it, and as the workspace's entries spell it.
+    const segments = relativePath.split('/');
+    const spelled = [...segments];
+    // The directories walked into, the mount's root first; their names below
+    // the root, as returned; and whether each folds case: the root's as read at
+    // start, and beneath it, whether looking its name up with its case flipped
+    // found it in the directory holding it (null for a name with no letter to
+    // flip).
+    const dirs = [root];
+    const names = [];
+    const folding = [entries?.rootFoldsCase ?? null];
+    // From segment `from` on, disk has nothing: each segment takes an entry's
+    // name, where the directory reached folds case, passing over an empty or
+    // `.` segment, and the rest keeps its spelling from the first segment no
+    // entry has a name for, a `..` included.
+    const fromEntries = (from) => {
+        // The nearest directory, from the one reached up, that told.
+        let folds = null;
+        for (let k = folding.length - 1; folds === null && k >= 0; k--)
+            folds = folding[k];
+        if (!entries || exact || !folds)
+            return;
+        let prefix = names.length === 0 ? '' : `${names.join('/')}/`;
+        const paths = entries.under(prefix);
+        for (let j = from; j < spelled.length; j++) {
+            const segment = spelled[j];
+            if (segment === '' || segment === '.')
+                continue;
+            const name = entryName(paths, prefix, segment);
+            if (name === null)
+                return;
+            spelled[j] = name;
+            prefix = `${prefix}${name}/`;
+        }
+    };
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (dirs.length === 1)
+                break;
+            dirs.pop();
+            names.pop();
+            folding.pop();
+            continue;
+        }
+        const dir = dirs[dirs.length - 1];
+        if (i === segments.length - 1) {
+            const { name, found } = await listedName(dir, segment, null);
+            segments[i] = name;
+            if (!exact && !entries?.has([...names, segment].join('/'))) {
+                spelled[i] = name;
+                if (!found)
+                    fromEntries(i);
+            }
+            break;
+        }
+        const given = await lstat(join(dir, segment), { bigint: true }).catch(() => null);
+        if (given === null) {
+            fromEntries(i);
+            break;
+        }
+        const { name, caseFolds } = await listedName(dir, segment, given);
+        segments[i] = name;
+        spelled[i] = name;
+        if (!given.isDirectory())
+            break;
+        dirs.push(join(dir, name));
+        names.push(name);
+        folding.push(caseFolds);
+    }
+    const asDisk = segments.join('/');
+    if (!entries || entries.holder(asDisk) !== undefined)
+        return asDisk;
+    return exact ? relativePath : spelled.join('/');
+}
 /** Errors meaning a directory can't be synced on this filesystem, not that syncing it failed. */
 const DIRECTORY_SYNC_UNSUPPORTED = new Set(['EINVAL', 'ENOTSUP']);
 /**
@@ -128,7 +591,11 @@ export class CheckedDir {
     async sync() {
         if (process.platform === 'win32')
             return;
-        const handle = await open(this.real, 'r');
+        // NONBLOCK: a FIFO put at its path since it was checked opens at once,
+        // and is refused below as not this directory, instead of holding the
+        // open, and with it the mount's turn, until something opens it for
+        // writing.
+        const handle = await open(this.real, fsConstants.O_RDONLY | NONBLOCK);
         try {
             const info = await handle.stat({ bigint: true });
             if (!info.isDirectory() || info.dev !== this.dev || info.ino !== this.ino)
@@ -167,8 +634,18 @@ async function locateDir(view, rootReal, rel) {
         const code = errno(err);
         if (code === 'ENOENT' || code === 'ENOTDIR')
             return rel === '' ? { kind: 'unobserved', reason: ROOT_UNAVAILABLE } : { kind: 'missing' };
+        // A link on the way that can't be resolved, such as a loop, is still a
+        // link this mount doesn't follow.
+        const found = rel === '' ? null : await linkOnTheWay(view, rel);
+        if (found !== null)
+            return { kind: 'unobserved', reason: await linkReason(view, rootReal, found) };
         return { kind: 'unobserved', reason: `cannot resolve the directory (${code ?? String(err)})` };
     }
+    // A mount that doesn't follow symlinks goes through none on the way to a
+    // directory, inside the mount or out of it.
+    const found = await linkRefusal(view, rootReal, rel, real);
+    if (found !== null)
+        return { kind: 'unobserved', reason: await linkReason(view, rootReal, found) };
     if (rel === '') {
         // The root is whatever the configured path names, and it must still be
         // the root the pass was given.
@@ -178,6 +655,13 @@ async function locateDir(view, rootReal, rel) {
     else if (!contained(rootReal, real)) {
         return { kind: 'unobserved', reason: OUTSIDE_PARENT, outside: true };
     }
+    else {
+        // Through a link this mount follows, a directory can be a nested
+        // mount's, which the mount neither reads nor writes.
+        const holder = nestedAtReal(real, view.nested);
+        if (holder)
+            return { kind: 'unobserved', reason: leadsInto(view.name, rel, holder) };
+    }
     const checked = await checkedAt(view, rel, real);
     if (checked) {
         // A root that isn't the directory disk last agreed under proves nothing
@@ -238,6 +722,11 @@ async function createDir(view, rootReal, rel) {
         return { kind: 'unobserved', reason: ROOT_UNAVAILABLE };
     for (let i = depth; i < parts.length; i++) {
         const childRel = parts.slice(0, i + 1).join('/');
+        // Nothing is made in a nested mount's directory, its root included where
+        // it isn't made yet, by a path that reaches it through a link.
+        const holder = nestedAtReal(base.at(parts[i]), view.nested);
+        if (holder)
+            return { kind: 'unobserved', reason: leadsInto(view.name, childRel, holder) };
         try {
             await mkdir(base.at(parts[i]));
         }
@@ -249,8 +738,14 @@ async function createDir(view, rootReal, rel) {
         // Made, or there already (made meanwhile, or not a directory): it must
         // be a real directory now, never a symlink or file in its place.
         const checked = await checkedAt(view, childRel, base.at(parts[i]));
-        if (!checked)
+        if (!checked) {
+            // A symlink in the way, such as one that leads nowhere, on a mount that
+            // doesn't follow symlinks, is named as one.
+            const there = view.followSymlinks ? null : await lstat(base.at(parts[i])).catch(() => null);
+            if (there?.isSymbolicLink())
+                return { kind: 'unobserved', reason: await linkReason(view, rootReal, { link: childRel }) };
             return { kind: 'unobserved', reason: 'a parent path is not a directory' };
+        }
         base = checked;
     }
     return { kind: 'checked', dir: base };
@@ -263,10 +758,12 @@ async function createDir(view, rootReal, rel) {
  * which nothing can exist. Either proves it only while every directory the
  * walk went through, the root included, is still the one its path names
  * afterwards: a root or parent replaced during the walk would otherwise lend
- * its replacement's absence to the original's path. Symlinked directories
- * inside the mount are followed as parents; any other symlink proves
- * nothing. Returns the directory whose entries prove it, or why absence
- * couldn't be shown.
+ * its replacement's absence to the original's path. On a mount that follows
+ * symlinks, symlinked directories inside the mount are followed as parents;
+ * on one that doesn't, a symlinked directory on the way proves nothing, and
+ * the reason says so (linkReason). Any other symlink proves nothing.
+ * Returns the directory whose entries prove it, or why absence couldn't be
+ * shown.
  */
 export async function confirmAbsent(view, rootReal, rel, target = 'entry') {
     const root = await locateDir(view, rootReal, '');
@@ -309,6 +806,9 @@ export async function confirmAbsent(view, rootReal, rel, target = 'entry') {
         if (info.isSymbolicLink()) {
             if (last && target === 'entry')
                 return CHANGED; // present: the link itself
+            // A mount that doesn't follow symlinks goes through none on the way.
+            if (!view.followSymlinks)
+                return linkReason(view, rootReal, { link: childRel });
             const located = await locateDir(view, rootReal, childRel);
             if (located.kind !== 'checked')
                 return BENEATH_SYMLINK;
@@ -397,17 +897,29 @@ export async function filesystemTrustsCtime(root) {
 /**
  * Where a path's parent directory canonically lies: inside the mount, gone
  * (absence is then proven separately), or somewhere a no-follow open would
- * still reach through — O_NOFOLLOW guards only the final component.
+ * still reach through — O_NOFOLLOW guards only the final component — which
+ * on a mount that doesn't follow symlinks is any symlink on the way.
  */
-async function parentPlacement(rootReal, lexical) {
+async function parentPlacement(view, rootReal, relativePath) {
     try {
-        const parent = await realpath(dirname(lexical));
-        return contained(rootReal, parent) ? 'inside' : { reason: OUTSIDE_PARENT };
+        const parent = await realpath(dirname(join(view.root, relativePath)));
+        const found = await linkRefusal(view, rootReal, relativePath, parent, 'parents');
+        if (found !== null)
+            return { reason: await linkReason(view, rootReal, found) };
+        if (!contained(rootReal, parent))
+            return { reason: OUTSIDE_PARENT };
+        const holder = nestedAtReal(parent, view.nested);
+        return holder ? { reason: leadsInto(view.name, parentOf(relativePath), holder) } : 'inside';
     }
     catch (err) {
         const code = errno(err);
         if (code === 'ENOENT' || code === 'ENOTDIR')
             return 'gone';
+        // A link on the way that can't be resolved, such as a loop, is still a
+        // link this mount doesn't follow.
+        const found = await linkOnTheWay(view, relativePath, 'parents');
+        if (found !== null)
+            return { reason: await linkReason(view, rootReal, found) };
         return { reason: `cannot resolve the parent directory (${code ?? String(err)})` };
     }
 }
@@ -419,7 +931,7 @@ async function parentPlacement(rootReal, lexical) {
  */
 export async function observePath(view, rootReal, relativePath) {
     const lexical = join(view.root, relativePath);
-    const placement = await parentPlacement(rootReal, lexical);
+    const placement = await parentPlacement(view, rootReal, relativePath);
     if (placement === 'gone')
         return absence(view, rootReal, relativePath);
     if (placement !== 'inside')
@@ -453,6 +965,9 @@ export async function observePath(view, rootReal, relativePath) {
         }
         if (!contained(rootReal, real))
             return { kind: 'unobserved', reason: 'a symlink that leaves the mount' };
+        const holder = nestedAtReal(real, view.nested);
+        if (holder)
+            return { kind: 'unobserved', reason: leadsInto(view.name, relativePath, holder) };
         if (!target.isFile()) {
             return { kind: 'unobserved', reason: target.isDirectory() ? 'a symlink to a directory, not walked' : 'not a regular file' };
         }
@@ -468,9 +983,10 @@ export async function observePath(view, rootReal, relativePath) {
 }
 /**
  * Open a mount-relative file for reading, located: a regular file that
- * canonically lies inside the mount — whatever the symlink policy, since a
- * symlinked parent escapes O_NOFOLLOW — and is the file the canonical path
- * names now. The handle is the caller's to close.
+ * canonically lies inside the mount, whatever the symlink policy, since
+ * O_NOFOLLOW guards only the final component; on a mount that doesn't follow
+ * symlinks, reached through no symlinked directory either (linkRefusal); and
+ * the file the canonical path names now. The handle is the caller's to close.
  */
 async function openContained(view, rootReal, relativePath) {
     const lexical = join(view.root, relativePath);
@@ -491,8 +1007,11 @@ async function openContained(view, rootReal, relativePath) {
         const code = errno(err);
         if (code === 'ENOENT' || code === 'ENOTDIR')
             return absence(view, rootReal, relativePath);
-        if (code === 'ELOOP' && !view.followSymlinks)
-            return { kind: 'unobserved', reason: NOT_FOLLOWED };
+        if (code === 'ELOOP' && !view.followSymlinks) {
+            // The link at the path, or a looping one on its way.
+            const found = await linkOnTheWay(view, relativePath, 'parents');
+            return { kind: 'unobserved', reason: found === null ? NOT_FOLLOWED : await linkReason(view, rootReal, found) };
+        }
         if (code === 'EISDIR')
             return { kind: 'unobserved', reason: 'a directory' };
         return { kind: 'unobserved', reason: `cannot open (${code ?? String(err)})` };
@@ -500,14 +1019,25 @@ async function openContained(view, rootReal, relativePath) {
     let keep = false;
     try {
         const info = await handle.stat({ bigint: true });
-        if (!info.isFile())
-            return { kind: 'unobserved', reason: info.isDirectory() ? 'a directory' : 'not a regular file' };
         const real = await realpath(lexical).catch(() => null);
         if (real === null)
             return { kind: 'unobserved', reason: 'the file changed while it was read' };
+        // O_NOFOLLOW guards only the final component: a mount that doesn't
+        // follow symlinks goes through none among the directories on the way
+        // either. Asked of what the path resolved to after the open, which the
+        // check below holds to the descriptor's file, and before what the
+        // descriptor holds, so a link gets its own answer whatever it leads to.
+        const found = await linkRefusal(view, rootReal, relativePath, real);
+        if (found !== null)
+            return { kind: 'unobserved', reason: await linkReason(view, rootReal, found) };
+        if (!info.isFile())
+            return { kind: 'unobserved', reason: info.isDirectory() ? 'a directory' : 'not a regular file' };
         if (!contained(rootReal, real)) {
             return { kind: 'unobserved', reason: view.followSymlinks ? 'a symlink that leaves the mount' : OUTSIDE_PARENT };
         }
+        const holder = nestedAtReal(real, view.nested);
+        if (holder)
+            return { kind: 'unobserved', reason: leadsInto(view.name, relativePath, holder) };
         const named = await stat(real, { bigint: true }).catch(() => null);
         if (named === null || named.dev !== info.dev || named.ino !== info.ino) {
             return { kind: 'unobserved', reason: 'the file changed while it was read' };