@animalabs/agent-framework 0.22.2 → 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, 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' };
         }
@@ -464,13 +979,14 @@ export async function observePath(view, rootReal, relativePath) {
     else if (!info.isFile()) {
         return { kind: 'unobserved', reason: 'not a regular file' };
     }
-    return { kind: 'file', size: Number(info.size), mtimeMs: Number(info.mtimeMs), fp: statFingerprint(info) };
+    return { kind: 'file', size: Number(info.size), mtimeMs: Number(info.mtimeMs), mode: Number(info.mode & 511n), fp: statFingerprint(info) };
 }
 /**
  * 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' };
@@ -537,10 +1067,44 @@ async function openContained(view, rootReal, relativePath) {
             await handle.close();
     }
 }
+/**
+ * Read an open file from its start, at most `limit` bytes, and whether it
+ * goes on past them. Where the file ends is what the reads find: `sizeHint`,
+ * the size its fstat gave, only sizes the first buffer. Once a buffer is
+ * full, one byte read past it tells whether the file goes on. At the limit,
+ * that byte says it does, and isn't kept. Short of it, the file has grown
+ * since its fstat: the byte is kept, and the read goes on in a larger buffer,
+ * up to the limit. A file that has shrunk ends where the reads find its end.
+ * A fractional `limit` allows the whole bytes in it.
+ */
+export async function readPrefix(handle, limit, sizeHint) {
+    const cap = Math.floor(limit);
+    const next = Buffer.alloc(1);
+    let bytes = Buffer.alloc(Math.min(cap, sizeHint));
+    let length = 0;
+    for (;;) {
+        while (length < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, length, bytes.length - length, length);
+            if (bytesRead === 0)
+                return { bytes: bytes.subarray(0, length), more: false };
+            length += bytesRead;
+        }
+        if ((await handle.read(next, 0, 1, length)).bytesRead === 0)
+            return { bytes, more: false };
+        if (length === cap)
+            return { bytes, more: true };
+        // Longer than its fstat said: read on, up to the limit.
+        const grown = Buffer.alloc(Math.min(cap, Math.max(2 * length, length + 64 * 1024)));
+        bytes.copy(grown, 0, 0, length);
+        grown[length++] = next[0];
+        bytes = grown;
+    }
+}
 /**
  * Read and hash a mount-relative file through one located descriptor. The
- * whole file is returned when it is at most `limit` bytes; larger files are
- * hashed in chunks and only their head is kept.
+ * whole file is returned when it is at most `limit` bytes, both at its fstat
+ * and as read; any other file, including one that grew past `limit` since its
+ * fstat, is hashed in chunks and only its head is kept.
  */
 export async function readPath(view, rootReal, relativePath, limit) {
     const opened = await openContained(view, rootReal, relativePath);
@@ -551,12 +1115,18 @@ export async function readPath(view, rootReal, relativePath, limit) {
         const hashedAt = Date.now();
         const size = Number(info.size);
         const fp = { ...statFingerprint(info), hashedAt };
-        if (size <= limit) {
-            const bytes = await handle.readFile();
+        // A file within the limit at its fstat is read no further than the limit,
+        // so one that has grown past it since is hashed below, from its start,
+        // never loaded whole. One over the limit at its fstat is hashed below
+        // without that read.
+        const within = size <= limit ? await readPrefix(handle, limit, size) : null;
+        if (within && !within.more) {
+            const { bytes } = within;
             return {
                 kind: 'read',
                 size: bytes.byteLength,
                 mtimeMs: Number(info.mtimeMs),
+                mode: Number(info.mode & 511n),
                 fp: { ...fp, size: bytes.byteLength },
                 hash: createHash('sha256').update(bytes).digest('hex'),
                 bytes,
@@ -580,6 +1150,7 @@ export async function readPath(view, rootReal, relativePath, limit) {
             kind: 'read',
             size: offset,
             mtimeMs: Number(info.mtimeMs),
+            mode: Number(info.mode & 511n),
             fp: { ...fp, size: offset },
             hash: hash.digest('hex'),
             bytes: null,
@@ -700,6 +1271,98 @@ export function coveredByIgnore(relativePath, patterns) {
     }
     return false;
 }
+/**
+ * The ignore patterns a walk that names `scope` reads beneath it: a pattern
+ * covering the scope itself, or a directory above it, doesn't apply beneath
+ * it (#276); one covering only something inside it does.
+ */
+export function ignoreBeneath(scope, patterns) {
+    return patterns.filter((pattern) => !coveredByIgnore(scope, [pattern]));
+}
+/**
+ * Names editors give the files they keep beside the one being edited: vim's
+ * swap files (`.name.swp`, and `.name.swx` while it checks it can make one),
+ * backups ending in `~`, and Sublime Text's save-in-progress files, ending
+ * in `.subl…tmp`. A walk passes over an entry with such a name as it passes
+ * over what the ignore list covers, a directory with what lies beneath it,
+ * and the watcher ignores it; a sync that names one takes it in. They are
+ * the families chokidar's `atomic` option hid from the watcher, but that
+ * tested them against the whole path, unanchored, so it also hid
+ * `report.v2.swp`, and under a directory with a dot in its name, a plain
+ * `notes.swp`. Here each is matched against an entry's name, to its end,
+ * and vim's from its start.
+ */
+const EDITOR_FILE = /^\..+\.sw[px]$|~$|\.subl.*\.tmp$/;
+/** The walk's reason for an entry the mount's ignore list covers. */
+export const IGNORED = 'ignored by the mount';
+/** The walk's reason for an entry `EDITOR_FILE` names. */
+const EDITOR_FILE_REASON = "an editor's swap or backup file";
+/** Whether a reason the walk gave an entry is one it passes over by design. */
+export function passedOverByDesign(why) {
+    return why === IGNORED || why === EDITOR_FILE_REASON || why === OTHER_MOUNT;
+}
+/** Why a pass passes over a directory that another mount nested in this one holds, and what lies beneath it. */
+export const OTHER_MOUNT = "another mount's directory";
+/**
+ * Whether a mount-relative path is another mount's directory, or lies
+ * beneath one, read as a join reads it: `.` and `..` segments within the
+ * path and repeated or trailing separators resolved, links not followed. A
+ * stored key such as `a//b/x`, which chronicle accepts, is read as `a/b/x`.
+ * A leading `..` that climbs above the mount's root is left as written.
+ * Every nested-mount check (a pass's, a walk's, a push's, grep's) asks this.
+ */
+export function inOtherMount(relativePath, others) {
+    const lexical = posix.normalize(relativePath).replace(/\/+$/, '');
+    return others.some((dir) => lexical === dir || lexical.startsWith(dir + '/'));
+}
+/**
+ * Why a walk passes over an entry by design, by its mount-relative path and
+ * its name: another mount's directory, the ignore list, or an editor's file
+ * name. Undefined when none covers it.
+ */
+function passedOverBecause(relativePath, name, patterns, others) {
+    if (inOtherMount(relativePath, others))
+        return OTHER_MOUNT;
+    if (isIgnored(relativePath, name, patterns))
+        return IGNORED;
+    if (EDITOR_FILE.test(name))
+        return EDITOR_FILE_REASON;
+    return undefined;
+}
+/**
+ * Why a sync without a path, and the watcher, pass over a mount-relative
+ * path: the path itself or a directory above it is passed over by design, as
+ * the walk reads each entry by its path and name. A path in another mount's
+ * directory is that mount's, whatever else covers a directory above it.
+ * Undefined when nothing covers it.
+ */
+export function passedOverAt(relativePath, patterns, others) {
+    if (inOtherMount(relativePath, others))
+        return OTHER_MOUNT;
+    const segments = relativePath.split('/').filter(Boolean);
+    for (let i = 0; i < segments.length; i++) {
+        const why = passedOverBecause(segments.slice(0, i + 1).join('/'), segments[i], patterns, others);
+        if (why !== undefined)
+            return why;
+    }
+    return undefined;
+}
+/**
+ * Why a walk of `scope` passes over a directory between it and a path beneath
+ * it: the first directory strictly beneath the scope and above the path that
+ * the mount passes over by design, by its path and name, with the patterns
+ * the walk reads there. Undefined when none is.
+ */
+export function passedOverBetween(scope, relativePath, patterns, others) {
+    const segments = relativePath.split('/').filter(Boolean);
+    const from = scope === '' ? 0 : scope.split('/').filter(Boolean).length;
+    for (let i = from; i < segments.length - 1; i++) {
+        const why = passedOverBecause(segments.slice(0, i + 1).join('/'), segments[i], patterns, others);
+        if (why !== undefined)
+            return why;
+    }
+    return undefined;
+}
 /** Simple ignore patterns, as the watcher and the old walk read them. */
 export function isIgnored(relativePath, name, patterns) {
     for (const pattern of patterns) {
@@ -763,6 +1426,29 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
         files: new Set(), seen: new Set(), othersTaken: new Set(), dirs: new Set(), others: new Map(), complete: new Set(), missing: new Set(),
         incomplete: [],
     };
+    // A walk that isn't named passes over a scope the mount passes over by
+    // design, at it or a directory above it, as its parent's listing would pass
+    // over its entry: a name rule (a bare-name ignore entry, an editor's name)
+    // doesn't match what lies beneath, as a path rule (`cache/**`) does. So a
+    // listing, glob or grep there never starts tracking what the mount leaves
+    // out, and a stored copy beneath it is unobserved, as beneath any region
+    // passed over by design. Its region says how to take what's there in: a
+    // sync that names it, whose scope is walked (#276), below.
+    // Another mount's directory is passed over by every walk, named or not,
+    // and no sync of this mount takes it in, so its region gives no advice.
+    if (scope !== '' && inOtherMount(scope, view.others)) {
+        walk.others.set(scope, OTHER_MOUNT);
+        walk.incomplete.push({ path: scope, reason: OTHER_MOUNT, kind: 'ignored' });
+        return walk;
+    }
+    if (!opts.named && scope !== '') {
+        const why = passedOverAt(scope, view.ignore, view.others);
+        if (why !== undefined) {
+            walk.others.set(scope, why);
+            walk.incomplete.push({ path: scope, reason: `${why}: a sync that names this path takes in what's there, editors' files aside`, kind: 'ignored' });
+            return walk;
+        }
+    }
     const top = await checkDir(view, rootReal, scope);
     if (top.kind === 'absent') {
         walk.missing.add(scope);
@@ -775,9 +1461,11 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
     // A scope a path sync names is walked even where the ignore list covers
     // it: a pattern covering the scope itself, or a directory above it, doesn't
     // apply beneath it. So a named directory's contents are synced, as a named
-    // file is (agent-framework #276). A listing keeps the ignore: its pass
-    // would otherwise start tracking what it lists.
-    const ignore = opts.named ? view.ignore.filter((pattern) => !coveredByIgnore(scope, [pattern])) : view.ignore;
+    // file is (agent-framework #276), apart from what a pattern covering only
+    // something inside it covers, and editors' files, which are passed over
+    // there as anywhere. A listing keeps the ignore: its pass would otherwise
+    // start tracking what it lists.
+    const ignore = opts.named ? ignoreBeneath(scope, view.ignore) : view.ignore;
     // A position outside the scope, or for a walk that doesn't descend, is no
     // position in this walk's order.
     const after = recursive && opts.resumeAfter !== undefined && (scope === '' || opts.resumeAfter.startsWith(scope + '/'))
@@ -887,9 +1575,10 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
         const regions = [];
         for (const entry of entries) {
             const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-            if (isIgnored(childRel, entry.name, ignore)) {
-                others.push([childRel, 'ignored by the mount']);
-                regions.push({ path: childRel, reason: 'ignored by the mount', kind: 'ignored' });
+            const passedOver = passedOverBecause(childRel, entry.name, ignore, view.others);
+            if (passedOver !== undefined) {
+                others.push([childRel, passedOver]);
+                regions.push({ path: childRel, reason: passedOver, kind: 'ignored' });
                 continue;
             }
             if (entry.isDirectory()) {
@@ -998,7 +1687,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
     for (const f of walk.seen)
         holdingUntaken.add(parentOf(f));
     for (const [p, why] of walk.others)
-        if (why !== 'ignored by the mount' && !walk.othersTaken.has(p))
+        if (!passedOverByDesign(why) && !walk.othersTaken.has(p))
             holdingUntaken.add(parentOf(p));
     for (const d of holdingUntaken) {
         walk.incomplete.push({ path: d, reason: `${capped} before everything here was taken`, kind: 'cap' });
@@ -1015,7 +1704,8 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
     // The cap stopped the walk only if it left something: a walk whose last
     // file used up the cap covered its scope. A directory the walk didn't list
     // counts as left, even one that holds nothing it would take (empty, or
-    // only ignored names): telling them apart would take another read. Such a
+    // only names it passes over by design): telling them apart would take
+    // another read. Such a
     // walk keeps its place and reports the directory as not visited, and the
     // next one lists it on its way to the wrap.
     if (left === 0 && lastTaken !== undefined && (holdingUntaken.size > 0 || unlisted > 0))