@animalabs/agent-framework 0.27.0 → 0.29.0

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

@@ -44,6 +44,7 @@ import { constants as fsConstants } from 'node:fs';
 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';
+import { OUTSIDE_STEP, UNFOLLOWED_STEP, errnoClause, errnoCode, systemWords } from './answers.js';
 /**
  * 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:
@@ -61,15 +62,26 @@ export const HEAD_BYTES = 8192;
 export const RACY_WINDOW_MS = 2000;
 export const OUTSIDE_PARENT = 'a parent directory resolves outside the mount';
 export const NOT_FOLLOWED = 'a symlink, which this mount does not follow';
+export const DIRECTORY = 'a directory';
+export const NOT_REGULAR = 'not a regular file';
+export const LEAVES_MOUNT = 'a symlink that leaves the mount';
+export const NOT_A_DIRECTORY = 'a parent path is not a directory';
 export const ROOT_UNAVAILABLE = 'the mount root is unavailable';
 export const ROOT_REPLACED = 'the mount root is not the directory disk last agreed with (an unmounted drive, or a replaced directory): ' +
     'reconnect it; if it was replaced on purpose, sync the mount with acceptRoot to take it as it is now';
-const CHANGED = 'it changed while it was observed';
-const CHANGED_WALK = 'the directory changed while the walk ran';
-const BENEATH_SYMLINK = 'beneath a symlink that does not lead to a directory inside the mount';
+export const CHANGED = 'it changed while it was observed';
+export const CHANGED_WALK = 'the directory changed while the walk ran';
+export const FILE_CHANGED = 'the file changed while it was read';
+export const RESOLVES_OUTSIDE = 'the directory resolves outside the mount';
+export const LINK_TO_DIRECTORY = 'a symlink to a directory, not walked';
+export const BENEATH_SYMLINK = 'beneath a symlink that does not lead to a directory inside the mount';
 export function errno(err) {
     return err?.code;
 }
+function failedOn(what, err) {
+    const code = errno(err);
+    return { reason: `${what} (${systemWords(code, err)})`, ...(code !== undefined ? { errno: code } : {}) };
+}
 export function contained(rootReal, candidate) {
     return candidate === rootReal || candidate.startsWith(rootReal.endsWith(sep) ? rootReal : rootReal + sep);
 }
@@ -152,9 +164,14 @@ export async function linkRefusal(view, rootReal, rel, real, through = 'path') {
     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' };
+    let leads;
+    try {
+        leads = await realpath(join(root, link));
+    }
+    catch (err) {
+        const code = errno(err);
+        return code === 'ENOENT' || code === 'ENOTDIR' || code === 'ELOOP' ? { kind: 'nowhere' } : null;
+    }
     if (!contained(rootReal, leads))
         return { kind: 'outside' };
     const directory = await stat(leads).then((info) => info.isDirectory(), () => false);
@@ -166,19 +183,19 @@ export async function linkLeads(root, rootReal, link) {
  * 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];
+    return nestedHolders(target, nested)[0];
 }
-/**
- * Whether a link's refusal names `holder`, the nested mount whose directory
- * holds the link's target. The target's path is one of that mount's own, so
- * its include decides: the refusal names a directory, or a file the include
- * covers. A refusal's code follows the same test (linkReadError's
- * `other_mount`), so the code says no more than the message.
- */
-export function namesHolder(leads, holder) {
-    return namesNestedPlace(leads.target.slice(holder.dir.length + 1), holder.include, leads.directory);
+function nestedHolders(target, nested) {
+    const segments = target.split('/');
+    return mayHold(nested.filter((n) => beneathNested(segments, n)), (n) => n.dir.split('/').length, (n) => !n.guessed && surelyBeneath(segments, n.dir.split('/')));
+}
+function mayHold(holders, depth, sure) {
+    const sorted = [...holders].sort((a, b) => depth(b) - depth(a) || Number(sure(b)) - Number(sure(a)));
+    const surely = sorted.findIndex(sure);
+    return surely === -1 ? sorted : sorted.slice(0, surely + 1);
+}
+export function namesHolder(leads, nested) {
+    return nestedHolders(leads.target, nested).every((holder) => namesNestedPlace(restBeneath(leads.target, holder), holder.include, leads.directory));
 }
 /**
  * Whether a refusal names a place in a nested mount's directory, `rest`
@@ -195,19 +212,13 @@ export function namesHolder(leads, holder) {
 export function namesNestedPlace(rest, include, directory) {
     return directory || insideMount(rest, include);
 }
-/**
- * Whether a path of a mount is one its passes decide and its listings may
- * name: inside its include, and, in a nested mount's directory, a place
- * that mount names (namesNestedPlace), its directory included. History the
- * mount took in before another was nested there, which that mount's
- * include leaves out, is no mount's, so no pass decides it, and no listing
- * names it or a directory only it implies.
- */
 export function withinIncludes(view, path) {
     if (!insideMount(path, view.include))
         return false;
-    const holder = nestedHolder(path, view.nested ?? []);
-    return holder === undefined || path === holder.dir || namesNestedPlace(path.slice(holder.dir.length + 1), holder.include, false);
+    return nestedHolders(path, view.nested ?? []).every((holder) => {
+        const rest = restBeneath(path, holder);
+        return rest === '' || namesNestedPlace(rest, holder.include, false);
+    });
 }
 /**
  * The path a mount's include judges for `given`, one of the mount's paths,
@@ -279,16 +290,23 @@ export async function coversLanding(view, rootReal, real, given) {
 }
 /**
  * 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
+ * leads (linkLeads), and the way on. For a link, the link is the subject,
+ * with where it leads: for a link inside the mount, its target, as the path
+ * to use in its place, and for a link to a directory there, the setting
+ * whoever runs the host can change too; for a link to something that isn't
+ * a directory, that nothing lies beneath it (the link stands among the
+ * path's directories, so following it can't make the path beneath it
+ * exist); for one leading outside the mount, that it does, and that
+ * whoever runs the host can mount what it leads to, or a directory that
+ * holds it; for one leading nowhere, that whoever runs the host can remove it or make
+ * it lead to what it stood for; for one whose target the refusal doesn't
+ * tell, what whoever runs the host can do wherever it leads
+ * (UNFOLLOWED_STEP).
+ * 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, the answer it got, and the errno's way on (errnoClause). Paths
  * are spelled as the tools take them, from the mount's name. On a mount with
  * an include, an inside target is named only where a tool could name it: a
  * file the include covers, or a directory, which a listing names whatever
@@ -299,27 +317,37 @@ export async function coversLanding(view, rootReal, real, given) {
  */
 export function linkWords(name, found, leads, nested = [], include) {
     const spell = (rel) => `"${rel === '' ? name : `${name}/${rel}`}"`;
-    if (!('link' in found))
-        return `${UNSURE_PREFIX}${name}/${found.unsure}" is a symlink (${found.code})`;
+    if (!('link' in found)) {
+        const code = errnoCode({ code: found.code });
+        return `${UNSURE_PREFIX}${name}/${found.unsure}" is a symlink (${systemWords(code, found.code)}); ${errnoClause(code, 'calling again', 'calling again then gets past it')}`;
+    }
     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 unknown = `${link}, which this mount does not follow; ${UNFOLLOWED_STEP}`;
+    if (leads === null)
+        return unknown;
+    if (leads.kind === 'nowhere') {
+        return `${link} that leads nowhere, which this mount does not follow; whoever runs this host can remove it or make it lead to what it stood for`;
+    }
+    if (leads.kind === 'outside') {
+        return `${link} leading outside the mount, which this mount does not follow; followed or not, ${OUTSIDE_STEP}`;
+    }
     const holder = nestedHolder(leads.target, nested);
     if (holder) {
-        if (!namesHolder(leads, holder))
-            return `${link}, which this mount does not follow`;
-        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)}`;
+        if (!namesHolder(leads, nested))
+            return unknown;
+        const rest = restBeneath(leads.target, holder);
+        const guess = nestedGuess(name, leads.target.split('/'), holder);
+        return `${link} to ${spell(leads.target)}, which this mount does not follow; it ${guess === undefined ? 'lies' : 'may lie'} in mount ` +
+            `"${holder.name}", nested in mount "${name}": ${nestedStep({ name: holder.name, use: rest ? `${holder.name}/${rest}` : holder.name, guess }, { after: ` in place of ${spell(found.link)}` })}`;
     }
     if (!leads.directory && !insideMount(leads.target, include))
-        return `${link}, which this mount does not follow`;
-    // Following it serves only what the include covers where it leads (judgedAt).
-    const setting = !leads.directory ? '' : include === undefined ? "; the mount's host can set followSymlinks: true"
-        : "; the mount's host can set followSymlinks: true, for what the include covers where it leads";
-    return `${link} to ${spell(leads.target)}, which this mount does not follow${setting}`;
+        return unknown;
+    if (!leads.directory)
+        return `${link} to ${spell(leads.target)}, which this mount does not follow; that isn't a directory, so nothing lies beneath it`;
+    // Either way serves only what the include covers where it leads (judgedAt).
+    const covered = include === undefined ? '' : '; either way, the mount reaches only what its include covers there';
+    return `${link} to ${spell(leads.target)}, which this mount does not follow; use ${spell(leads.target)} in place of ${spell(found.link)}, ` +
+        `or whoever runs this host can set followSymlinks: true on mount "${name}"${covered}`;
 }
 /**
  * Where a link linkOnTheWay found leads, as its refusal may tell it
@@ -335,25 +363,83 @@ export async function shownLeads(root, rootReal, found, include) {
 }
 /** Why a path is refused for what linkOnTheWay found (linkWords, with where the link leads, as shownLeads tells it). */
 export async function linkReason(view, rootReal, found) {
-    return linkWords(view.name, found, await shownLeads(view.root, rootReal, found, view.include), view.nested, view.include);
+    return { reason: linkWords(view.name, found, await shownLeads(view.root, rootReal, found, view.include), view.nested, view.include), ownStep: true };
+}
+export function realSegments(path) {
+    return path.split(sep).filter((segment, i) => i === 0 || segment !== '');
+}
+export function beneathRoot(path, root) {
+    const segments = realSegments(path);
+    const top = realSegments(root);
+    return segments.length > top.length && beginsWith(segments, top) ? segments.slice(top.length).join('/') : undefined;
+}
+export function sameRoot(path, root) {
+    const segments = realSegments(path);
+    const top = realSegments(root);
+    return segments.length === top.length && beginsWith(segments, top);
+}
+export function surelyAtRoot(path, root) {
+    return surelyBeneath(realSegments(path), realSegments(root));
+}
+export function nestedRootAtReal(real, nested = []) {
+    return nestedRootsAtReal(real, nested)[0];
+}
+function nestedRootsAtReal(real, nested) {
+    // realpath keeps the spelling it's given where disk folds it on Linux, as
+    // from a link's target, so a real root is compared as loosely as a path.
+    const segments = realSegments(real);
+    const holders = nested.flatMap((n) => {
+        if (n.real === undefined)
+            return [];
+        const root = realSegments(n.real);
+        return beginsWith(segments, root) ? [{ mount: n, depth: root.length, sure: surelyBeneath(segments, root) }] : [];
+    });
+    return mayHold(holders, (h) => h.depth, (h) => h.sure);
 }
 /**
  * The nested mount whose root holds `real`, a canonical path, the innermost,
- * with the path to use there, the path beneath its root (`rest`) and its
- * include; undefined when none does. A path the lexical checks pass
+ * with the path to use there and the path beneath its root (`rest`);
+ * 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, and names the mount only where
- * namesNestedPlace says the place is that mount's.
+ * 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, include: n.include }] : []))
-        .sort((a, b) => b.real.length - a.real.length)[0];
+export async function nestedAtReal(real, nested = [], at) {
+    const holders = nestedRootsAtReal(real, nested);
+    const holder = holders[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, rest, include: holder.include };
+    const segments = realSegments(real);
+    // realpath keeps a link target's spelling beneath the root too, so the
+    // rest is read as disk spells it, for each mount's include to judge.
+    const rests = await Promise.all(holders.map(async (h) => {
+        const given = segments.slice(h.depth).join('/');
+        return given === '' ? '' : await diskSpelling(h.mount.real, given);
+    }));
+    const rest = rests[0];
+    const { name } = holder.mount;
+    const root = realSegments(holder.mount.real);
+    const found = {
+        name,
+        use: rest ? `${name}/${rest}` : name,
+        rest,
+        judgedByInclude: holders.some((h) => h.mount.include !== undefined),
+        names: (directory) => holders.every((h, i) => namesNestedPlace(rests[i], h.mount.include, directory)),
+    };
+    if (surelyBeneath(segments, root))
+        return found;
+    if (at === undefined)
+        return { ...found, guess: null };
+    const top = realSegments(at.rootReal);
+    if (segments.length <= top.length || root.length <= top.length || !top.every((t, i) => segments[i] === t))
+        return { ...found, guess: null };
+    const within = segments.slice(top.length);
+    const below = root.slice(top.length);
+    const guess = guessFor(at.name, within, below);
+    const leads = guess === undefined ? [at.name, ...within].join('/') : [guess.given, ...within.slice(below.length)].join('/');
+    if (!surelyBeneath(root.slice(0, top.length), top))
+        return { ...found, guess: { ...placedGuess(at.name, within.slice(0, below.length), guess), leads } };
+    return { ...found, guess: guess === undefined ? null : { ...guess, leads } };
 }
 /**
  * Why a mount-relative path that resolves into a nested mount's directory is
@@ -361,7 +447,8 @@ export function nestedAtReal(real, nested = []) {
  * 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`;
+    const verb = holder.guess === undefined ? 'leads' : 'may lead';
+    return `"${rel === '' ? name : `${name}/${rel}`}" ${verb} into mount "${holder.name}", nested in mount "${name}": ${nestedStep(holder, { after: ' in its place' })}`;
 }
 // ===========================================================================
 // Disk's spelling of a path
@@ -371,9 +458,8 @@ const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
 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.
+ * letter whose own other case is the letter again. `ß`, 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);
@@ -388,6 +474,15 @@ const folded = (name) => name.normalize('NFC').toLowerCase();
  * the same-file check keeps that from naming another file.
  */
 export const foldedLoosely = (name) => name.normalize('NFC').toLowerCase().toUpperCase().toLowerCase();
+/**
+ * Linux's casefold, which ext4 and f2fs set per directory, drops
+ * default-ignorable code points (on every kernel but 6.12 to 6.12.4) and
+ * compares names decomposed, in full case folding, and HFS+ passes over some
+ * of those code points too. Case mapped on the decomposed name joins marks
+ * that come in another order around a combining ypogegrammeni (U+0345),
+ * whose upper case is a letter.
+ */
+const foldedFully = (name) => name.replace(/\p{Default_Ignorable_Code_Point}/gu, '').normalize('NFD').toLowerCase().toUpperCase().toLowerCase().normalize('NFD');
 /**
  * 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
@@ -482,19 +577,73 @@ function entryName(paths, prefix, segment) {
     }
     return found;
 }
-/**
- * Whether a path's segments begin with a directory's: exactly, or, with
- * `loosely`, with each segment compared as loosely as listedName compares
- * names (foldedLoosely), as a disk that folds names may compare them. That
- * errs toward the directory: on a disk that tells some of those spellings
- * apart, such as case, or `ß` from `ss`, a distinct directory spelled one of
- * them matches too, and resolveAbsolutePath, the one caller that compares
- * loosely, gives null for a path beneath it.
- */
-export function beginsWithDir(segments, dir, loosely) {
-    if (segments.length < dir.length)
-        return false;
-    return dir.every((d, i) => segments[i] === d || (loosely && foldedLoosely(segments[i]) === foldedLoosely(d)));
+function sameLevel(given, name) {
+    return given === name || (given !== '' && foldedFully(given) === foldedFully(name));
+}
+function beginsWith(segments, dir) {
+    return segments.length >= dir.length && dir.every((d, i) => sameLevel(segments[i], d));
+}
+export function beneathNested(segments, nested) {
+    return beginsWith(segments, nested.dir.split('/'));
+}
+export function restBeneath(path, nested) {
+    // By segments, since a name that matches can be another length, as `SS`
+    // is beside `ß`.
+    return path.split('/').slice(nested.dir.split('/').length).join('/');
+}
+function surelyBeneath(segments, dir) {
+    return segments.length >= dir.length && dir.every((d, i) => segments[i] === d);
+}
+function shownByCodePoints(name) {
+    return [...name].map((c) => {
+        const code = c.codePointAt(0);
+        if (c === '\\')
+            return '\\\\';
+        return code < 0x80 ? c : code > 0xffff ? `\\u{${code.toString(16)}}` : `\\u${code.toString(16).padStart(4, '0')}`;
+    }).join('');
+}
+function guessFor(mount, given, dir) {
+    if (surelyBeneath(given, dir))
+        return undefined;
+    const levels = given.slice(0, dir.length);
+    const plain = (a, b) => a === b || !/[^\x00-\x7f]/.test(a + b);
+    const shown = (name, other) => (plain(name, other) ? name : shownByCodePoints(name));
+    return {
+        given: [mount, ...levels.map((g, i) => shown(g, dir[i]))].join('/'),
+        dir: [mount, ...dir.map((d, i) => shown(d, levels[i]))].join('/'),
+    };
+}
+export function nestedGuess(mount, segments, nested) {
+    const dir = nested.dir.split('/');
+    const guess = guessFor(mount, segments, dir);
+    return nested.guessed ? placedGuess(mount, segments.slice(0, dir.length), guess) : guess;
+}
+function placedGuess(mount, levels, guess) {
+    return guess === undefined ? { placed: [mount, ...levels].join('/') } : { placed: guess.given, dir: guess.dir };
+}
+export function nestedStep(holder, opts = {}) {
+    const { guess } = holder;
+    const after = opts.after ?? '';
+    if (guess === undefined)
+        return `use "${holder.use}"${after}`;
+    if (guess === null) {
+        return `this workspace can't tell whether where it leads is that mount's directory. ` +
+            `If you meant that mount's directory, use "${holder.use}"${after}; if not, ask whoever runs this workspace`;
+    }
+    const leads = guess.leads === undefined ? '' : `it leads to "${guess.leads}", and `;
+    if ('placed' in guess) {
+        const check = 'ask whoever runs this workspace to check where the two mounts are configured';
+        const outside = guess.dir === undefined ? `"${guess.placed}"` : `"${guess.placed}" and "${guess.dir}"`;
+        return `${leads}this workspace can't tell whether "${guess.placed}" is mount "${holder.name}"'s directory, since the two mounts' roots are configured in ` +
+            `spellings it can't tell apart. If you meant that mount's directory, use "${holder.use}"${after}. ` +
+            (opts.named ? `If you meant one of this mount's own, for a new file use a path outside ${outside}, and for one already there ${check}` : `If not, ${check}`);
+    }
+    const remedy = `rename one of "${guess.given}" and "${guess.dir}"`;
+    const own = opts.named
+        ? `If you meant one of this mount's own, for a new file use a path outside "${guess.given}" and "${guess.dir}", and for one already there ask whoever runs this workspace to ${remedy}`
+        : `If not, ask whoever runs this workspace to ${remedy}`;
+    return `${leads}this workspace can't tell "${guess.given}" from "${guess.dir}", ` +
+        `mount "${holder.name}"'s directory. If you meant that mount's directory, use "${holder.use}"${after}. ${own}`;
 }
 /**
  * The name `dir` lists for `segment`: `segment` itself, unless disk folds it
@@ -707,20 +856,26 @@ export class CheckedDir {
     lexical;
     dev;
     ino;
+    born;
     constructor(
     /** Mount-relative path ('' for the root). */
     rel, 
     /** Its canonical location when checked. */
-    real, lexical, dev, ino) {
+    real, lexical, dev, ino, born) {
         this.rel = rel;
         this.real = real;
         this.lexical = lexical;
         this.dev = dev;
         this.ino = ino;
+        this.born = born;
     }
     /** Which directory it is. */
     identity() {
-        return { dev: String(this.dev), ino: String(this.ino) };
+        return {
+            dev: String(this.dev),
+            ino: String(this.ino),
+            ...(this.born > 0n ? { born: String(this.born) } : {}),
+        };
     }
     /** A path that reaches `name` in this directory. */
     at(name) {
@@ -764,12 +919,26 @@ export class CheckedDir {
         }
     }
 }
+/**
+ * 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.
+ */
+export async function rootAbsence(root) {
+    try {
+        return (await stat(root)).isDirectory() ? undefined : 'ENOTDIR';
+    }
+    catch (err) {
+        return errno(err);
+    }
+}
 /** Check the directory at a canonical location, if one is there. */
 async function checkedAt(view, rel, real) {
     const info = await lstat(real, { bigint: true }).catch(() => null);
     if (!info?.isDirectory())
         return null;
-    return new CheckedDir(rel, real, lexicalOf(view, rel), info.dev, info.ino);
+    return new CheckedDir(rel, real, lexicalOf(view, rel), info.dev, info.ino, info.birthtimeNs);
 }
 /**
  * Where a mount directory is now: checked; missing — nothing there, or not a
@@ -784,19 +953,19 @@ async function locateDir(view, rootReal, rel) {
     catch (err) {
         const code = errno(err);
         if (code === 'ENOENT' || code === 'ENOTDIR')
-            return rel === '' ? { kind: 'unobserved', reason: ROOT_UNAVAILABLE } : { kind: 'missing' };
+            return rel === '' ? { kind: 'unobserved', reason: ROOT_UNAVAILABLE, errno: code } : { 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)})` };
+            return { kind: 'unobserved', ...(await linkReason(view, rootReal, found)) };
+        return { kind: 'unobserved', ...failedOn('cannot resolve the directory', 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) };
+        return { kind: 'unobserved', ...(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.
@@ -811,10 +980,10 @@ async function locateDir(view, rootReal, rel) {
         // mount's, which the mount neither reads nor writes. A place there that
         // mount's include leaves out is no mount's, and holds nothing beneath it,
         // as at any file (namesNestedPlace).
-        const holder = nestedAtReal(real, view.nested);
+        const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
         if (holder) {
-            const directory = holder.include !== undefined && await stat(real).then((info) => info.isDirectory(), () => false);
-            return namesNestedPlace(holder.rest, holder.include, directory) ? { kind: 'unobserved', reason: leadsInto(view.name, rel, holder) } : { kind: 'missing' };
+            const directory = holder.judgedByInclude && await stat(real).then((info) => info.isDirectory(), () => false);
+            return holder.names(directory) ? { kind: 'unobserved', reason: leadsInto(view.name, rel, holder), ownStep: true } : { kind: 'missing' };
         }
     }
     const checked = await checkedAt(view, rel, real);
@@ -842,7 +1011,10 @@ export async function checkRoot(view, rootReal) {
     const found = await locateDir(view, rootReal, '');
     if (found.kind === 'checked')
         return { dir: found.dir };
-    return { reason: found.kind === 'unobserved' ? found.reason : ROOT_UNAVAILABLE };
+    const reason = found.kind === 'unobserved' ? found.reason : ROOT_UNAVAILABLE;
+    // What is at the root's path now says whether the directory is gone from it.
+    const code = found.kind === 'unobserved' && found.errno !== undefined ? found.errno : reason === ROOT_UNAVAILABLE ? await rootAbsence(view.root) : undefined;
+    return { reason, ...(code !== undefined ? { errno: code } : {}) };
 }
 /**
  * Check the directory at a mount-relative path. With `create`, missing
@@ -858,7 +1030,7 @@ export async function checkDir(view, rootReal, rel, opts = {}) {
     if (opts.create)
         return createDir(view, rootReal, rel);
     const proof = await confirmAbsent(view, rootReal, rel, 'beneath');
-    return typeof proof === 'string' ? { kind: 'unobserved', reason: proof } : { kind: 'absent', by: proof.by };
+    return 'reason' in proof ? { kind: 'unobserved', ...proof } : { kind: 'absent', by: proof.by };
 }
 async function createDir(view, rootReal, rel) {
     const parts = rel.split('/');
@@ -879,16 +1051,16 @@ async function createDir(view, rootReal, rel) {
         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);
+        const holder = await nestedAtReal(base.at(parts[i]), view.nested, { name: view.name, rootReal });
         if (holder)
-            return { kind: 'unobserved', reason: leadsInto(view.name, childRel, holder) };
+            return { kind: 'unobserved', reason: leadsInto(view.name, childRel, holder), ownStep: true };
         try {
             await mkdir(base.at(parts[i]));
         }
         catch (err) {
             const code = errno(err);
             if (code !== 'EEXIST')
-                return { kind: 'unobserved', reason: `cannot create the directory ${childRel} (${code ?? String(err)})` };
+                return { kind: 'unobserved', ...failedOn(`cannot create the directory ${childRel}`, err) };
         }
         // 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.
@@ -898,8 +1070,8 @@ async function createDir(view, rootReal, rel) {
             // 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' };
+                return { kind: 'unobserved', ...(await linkReason(view, rootReal, { link: childRel })) };
+            return { kind: 'unobserved', reason: NOT_A_DIRECTORY };
         }
         base = checked;
     }
@@ -923,14 +1095,14 @@ async function createDir(view, rootReal, rel) {
 export async function confirmAbsent(view, rootReal, rel, target = 'entry') {
     const root = await locateDir(view, rootReal, '');
     if (root.kind !== 'checked')
-        return ROOT_UNAVAILABLE;
+        return { reason: ROOT_UNAVAILABLE };
     let cur = root.dir;
     /** Every directory the walk went through, the root first. */
     const walked = [cur];
     const proven = async () => {
         for (const dir of walked)
             if (!(await dir.stillHere()))
-                return CHANGED;
+                return { reason: CHANGED };
         return { by: cur.rel };
     };
     const parts = rel.split('/');
@@ -945,48 +1117,51 @@ export async function confirmAbsent(view, rootReal, rel, target = 'entry') {
         catch (err) {
             const code = errno(err);
             if (code === 'ENOTDIR')
-                return CHANGED;
+                return { reason: CHANGED };
             if (code !== 'ENOENT')
-                return `cannot stat (${code ?? String(err)})`;
+                return failedOn('cannot stat', err);
             // Absent from a directory that, like each above it, is still the one its path names.
             return proven();
         }
         if (info.isDirectory()) {
             if (last)
-                return CHANGED; // present after all
-            cur = new CheckedDir(childRel, cur.at(name), lexicalOf(view, childRel), info.dev, info.ino);
+                return { reason: CHANGED }; // present after all
+            cur = new CheckedDir(childRel, cur.at(name), lexicalOf(view, childRel), info.dev, info.ino, info.birthtimeNs);
             walked.push(cur);
             continue;
         }
         if (info.isSymbolicLink()) {
             if (last && target === 'entry')
-                return CHANGED; // present: the link itself
+                return { reason: 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 === 'unobserved' && located.outside !== true) {
+                return { reason: located.reason, ...(located.errno !== undefined ? { errno: located.errno } : {}), ...(located.ownStep === true ? { ownStep: true } : {}) };
+            }
             if (located.kind !== 'checked')
-                return BENEATH_SYMLINK;
+                return { reason: BENEATH_SYMLINK };
             if (last)
-                return CHANGED; // a directory there after all
+                return { reason: CHANGED }; // a directory there after all
             cur = located.dir;
             walked.push(cur);
             continue;
         }
         if (last && target === 'entry')
-            return CHANGED; // present after all
+            return { reason: CHANGED }; // present after all
         // A non-directory: nothing can exist beneath it, while it is still this
         // same one, in the directory still at its path.
         const again = await lstat(cur.at(name), { bigint: true }).catch(() => null);
         if (again === null || again.isDirectory() || again.isSymbolicLink() || again.dev !== info.dev || again.ino !== info.ino)
-            return CHANGED;
+            return { reason: CHANGED };
         return proven();
     }
-    return CHANGED;
+    return { reason: CHANGED };
 }
 async function absence(view, rootReal, rel) {
     const proof = await confirmAbsent(view, rootReal, rel);
-    return typeof proof === 'string' ? { kind: 'unobserved', reason: proof } : { kind: 'absent' };
+    return 'reason' in proof ? { kind: 'unobserved', ...proof } : { kind: 'absent' };
 }
 // ===========================================================================
 // Fingerprints
@@ -1061,16 +1236,16 @@ async function parentPlacement(view, rootReal, relativePath) {
         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) };
+            return linkReason(view, rootReal, found);
         if (!contained(rootReal, parent))
             return { reason: OUTSIDE_PARENT };
-        const holder = nestedAtReal(parent, view.nested);
+        const holder = await nestedAtReal(parent, view.nested, { name: view.name, rootReal });
         if (!holder)
             return { inside: parent };
         // A place there that the nested mount's include leaves out is no mount's,
         // and holds nothing beneath it, as beneath any file (namesNestedPlace).
-        const directory = holder.include !== undefined && await stat(parent).then((info) => info.isDirectory(), () => false);
-        return namesNestedPlace(holder.rest, holder.include, directory) ? { reason: leadsInto(view.name, parentOf(relativePath), holder) } : 'gone';
+        const directory = holder.judgedByInclude && await stat(parent).then((info) => info.isDirectory(), () => false);
+        return holder.names(directory) ? { reason: leadsInto(view.name, parentOf(relativePath), holder), ownStep: true } : 'gone';
     }
     catch (err) {
         const code = errno(err);
@@ -1080,8 +1255,8 @@ async function parentPlacement(view, rootReal, relativePath) {
         // 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)})` };
+            return linkReason(view, rootReal, found);
+        return failedOn('cannot resolve the parent directory', err);
     }
 }
 /**
@@ -1096,7 +1271,7 @@ export async function observePath(view, rootReal, relativePath) {
     if (placement === 'gone')
         return absence(view, rootReal, relativePath);
     if ('reason' in placement)
-        return { kind: 'unobserved', reason: placement.reason };
+        return { kind: 'unobserved', ...placement };
     let info;
     try {
         info = await lstat(lexical, { bigint: true });
@@ -1105,7 +1280,7 @@ export async function observePath(view, rootReal, relativePath) {
         const code = errno(err);
         if (code === 'ENOENT' || code === 'ENOTDIR')
             return absence(view, rootReal, relativePath);
-        return { kind: 'unobserved', reason: `cannot stat (${code ?? String(err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot stat', err) };
     }
     if (info.isSymbolicLink()) {
         if (!view.followSymlinks)
@@ -1115,43 +1290,43 @@ export async function observePath(view, rootReal, relativePath) {
             target = await stat(lexical, { bigint: true });
         }
         catch (err) {
-            return { kind: 'unobserved', reason: `a symlink whose target cannot be read (${errno(err) ?? String(err)})` };
+            return { kind: 'unobserved', ...failedOn('a symlink whose target cannot be read', err) };
         }
         let real;
         try {
             real = await realpath(lexical);
         }
         catch (err) {
-            return { kind: 'unobserved', reason: `a symlink that cannot be resolved (${errno(err) ?? String(err)})` };
+            return { kind: 'unobserved', ...failedOn('a symlink that cannot be resolved', err) };
         }
         if (!contained(rootReal, real))
-            return { kind: 'unobserved', reason: 'a symlink that leaves the mount' };
-        const holder = nestedAtReal(real, view.nested);
+            return { kind: 'unobserved', reason: LEAVES_MOUNT };
+        const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
         // A place a nested mount's include leaves out is no mount's, so the link
         // leaves this one (namesNestedPlace).
         if (holder) {
-            return { kind: 'unobserved', reason: namesNestedPlace(holder.rest, holder.include, target.isDirectory()) ? leadsInto(view.name, relativePath, holder) : 'a symlink that leaves the mount' };
+            return holder.names(target.isDirectory()) ? { kind: 'unobserved', reason: leadsInto(view.name, relativePath, holder), ownStep: true } : { kind: 'unobserved', reason: LEAVES_MOUNT };
         }
         if (!target.isFile()) {
-            return { kind: 'unobserved', reason: target.isDirectory() ? 'a symlink to a directory, not walked' : 'not a regular file' };
+            return { kind: 'unobserved', reason: target.isDirectory() ? LINK_TO_DIRECTORY : NOT_REGULAR };
         }
         // A file this mount's own include leaves out where the link lands is no
         // file of this mount's (coversLanding). It's judged here, and not only
         // where the file is opened, since a pass takes a copy whose fingerprint
         // the stat vouches for without opening it.
         if (!(await coversLanding(view, rootReal, real, relativePath)))
-            return { kind: 'unobserved', reason: 'a symlink that leaves the mount' };
+            return { kind: 'unobserved', reason: LEAVES_MOUNT };
         info = target;
     }
     else if (info.isDirectory()) {
-        return { kind: 'unobserved', reason: 'a directory' };
+        return { kind: 'unobserved', reason: DIRECTORY };
     }
     else if (!info.isFile()) {
-        return { kind: 'unobserved', reason: 'not a regular file' };
+        return { kind: 'unobserved', reason: NOT_REGULAR };
     }
     else if (!(await coversLanding(view, rootReal, join(placement.inside, basename(lexical)), relativePath))) {
         // So is one reached through a link among its directories.
-        return { kind: 'unobserved', reason: 'a symlink that leaves the mount' };
+        return { kind: 'unobserved', reason: LEAVES_MOUNT };
     }
     return { kind: 'file', size: Number(info.size), mtimeMs: Number(info.mtimeMs), mode: Number(info.mode & 511n), fp: statFingerprint(info) };
 }
@@ -1184,18 +1359,18 @@ async function openContained(view, rootReal, relativePath) {
         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) };
+            return found === null ? { kind: 'unobserved', reason: NOT_FOLLOWED } : { kind: 'unobserved', ...(await linkReason(view, rootReal, found)) };
         }
         if (code === 'EISDIR')
-            return { kind: 'unobserved', reason: 'a directory' };
-        return { kind: 'unobserved', reason: `cannot open (${code ?? String(err)})` };
+            return { kind: 'unobserved', reason: DIRECTORY };
+        return { kind: 'unobserved', ...failedOn('cannot open', err) };
     }
     let keep = false;
     try {
         const info = await handle.stat({ bigint: true });
         const real = await realpath(lexical).catch(() => null);
         if (real === null)
-            return { kind: 'unobserved', reason: 'the file changed while it was read' };
+            return { kind: 'unobserved', reason: FILE_CHANGED };
         // 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
@@ -1203,23 +1378,23 @@ async function openContained(view, rootReal, relativePath) {
         // 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) };
+            return { kind: 'unobserved', ...(await linkReason(view, rootReal, found)) };
         if (!info.isFile())
-            return { kind: 'unobserved', reason: info.isDirectory() ? 'a directory' : 'not a regular file' };
-        const leaves = view.followSymlinks ? 'a symlink that leaves the mount' : OUTSIDE_PARENT;
+            return { kind: 'unobserved', reason: info.isDirectory() ? DIRECTORY : NOT_REGULAR };
+        const leaves = view.followSymlinks ? LEAVES_MOUNT : OUTSIDE_PARENT;
         if (!contained(rootReal, real))
             return { kind: 'unobserved', reason: leaves };
-        const holder = nestedAtReal(real, view.nested);
+        const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
         // A place a nested mount's include leaves out is no mount's. Reached
         // through a link this mount doesn't follow, the link is what's refused.
         if (holder)
-            return { kind: 'unobserved', reason: namesNestedPlace(holder.rest, holder.include, false) ? leadsInto(view.name, relativePath, holder) : view.followSymlinks ? leaves : NOT_FOLLOWED };
+            return holder.names(false) ? { kind: 'unobserved', reason: leadsInto(view.name, relativePath, holder), ownStep: true } : { kind: 'unobserved', reason: view.followSymlinks ? leaves : NOT_FOLLOWED };
         // So is a file this mount's own include leaves out (coversLanding).
         if (!(await coversLanding(view, rootReal, real, relativePath)))
             return { kind: 'unobserved', reason: view.followSymlinks ? leaves : NOT_FOLLOWED };
         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' };
+            return { kind: 'unobserved', reason: FILE_CHANGED };
         }
         if (!view.followSymlinks) {
             // Where no symlink is followed, the path itself must be the file the
@@ -1229,7 +1404,7 @@ async function openContained(view, rootReal, relativePath) {
             if (entry?.isSymbolicLink())
                 return { kind: 'unobserved', reason: NOT_FOLLOWED };
             if (entry === null || !entry.isFile() || entry.dev !== info.dev || entry.ino !== info.ino) {
-                return { kind: 'unobserved', reason: 'the file changed while it was read' };
+                return { kind: 'unobserved', reason: FILE_CHANGED };
             }
         }
         keep = true;
@@ -1239,7 +1414,7 @@ async function openContained(view, rootReal, relativePath) {
         const code = errno(err);
         if (code === 'ENOENT')
             return absence(view, rootReal, relativePath);
-        return { kind: 'unobserved', reason: `cannot read (${code ?? String(err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         if (!keep)
@@ -1340,7 +1515,7 @@ export async function readPath(view, rootReal, relativePath, limit) {
         const code = errno(err);
         if (code === 'ENOENT')
             return absence(view, rootReal, relativePath);
-        return { kind: 'unobserved', reason: `cannot read (${code ?? String(err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         await handle.close();
@@ -1382,7 +1557,7 @@ export async function readBytes(view, rootReal, relativePath, limit) {
         return { kind: 'bytes', size: bytes.byteLength, bytes, head: bytes.subarray(0, HEAD_BYTES) };
     }
     catch (err) {
-        return { kind: 'unobserved', reason: `cannot read (${errno(err) ?? String(err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         await handle.close();
@@ -1404,7 +1579,7 @@ export async function readHead(view, rootReal, relativePath) {
         return { kind: 'head', size: Number(info.size), mtimeMs: Number(info.mtimeMs), head: head.subarray(0, bytesRead) };
     }
     catch (err) {
-        return { kind: 'unobserved', reason: `cannot read (${errno(err) ?? String(err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         await handle.close();
@@ -1480,14 +1655,14 @@ function subtreeAgainst(dir, at) {
     return 'holds';
 }
 /**
- * Whether a mount's ignore list covers a mount-relative path: the path itself
- * or any directory above it, as the walk's own test reads each entry by its
- * path and name.
+ * Whether a mount's ignore list covers a mount-relative path: the path itself,
+ * a directory or not, or any directory above it, as the walk's own test reads
+ * each entry by its path and kind.
  */
-export function coveredByIgnore(relativePath, patterns) {
+export function coveredByIgnore(relativePath, patterns, directory) {
     const segments = relativePath.split('/').filter(Boolean);
     for (let i = 0; i < segments.length; i++) {
-        if (isIgnored(segments.slice(0, i + 1).join('/'), segments[i], patterns))
+        if (isIgnored(segments.slice(0, i + 1).join('/'), patterns, i < segments.length - 1 || directory))
             return true;
     }
     return false;
@@ -1530,44 +1705,90 @@ export function insideMount(relativePath, include) {
         return true;
     return coveredByInclude(relativePath, include);
 }
-/**
- * Whether the include's matcher can read `pattern`: a name or an `*.ext` glob,
- * which covers a file by its own name, or a `dir/**` glob, with no empty, `.`
- * or `..` segment, since those name no entry a path reaches. Where `\` is the
- * platform's separator, as on Windows, a pattern holding one can't name a
- * file either, since every path is read with `\` as a separator
- * (pathSegments). A pattern the matcher can't read would match nothing, and
- * take every file out of the mount unsaid, so the module refuses it.
- */
-export function includePatternReadable(pattern, platformSep = sep) {
-    const segment = (s) => s.length > 0 && s !== '.' && s !== '..' && !(platformSep === '\\' && s.includes('\\'));
-    const name = (s) => segment(s) && !s.includes('/') &&
-        (!s.includes('*') || (s.startsWith('*.') && s.length > 2 && !s.slice(1).includes('*')));
-    return typeof pattern === 'string' &&
-        (pattern.endsWith('/**') ? pattern.length > 3 && pattern.slice(0, -3).split('/').every((s) => segment(s) && !s.includes('*')) : name(pattern));
+const readings = new Map();
+function readPattern(pattern) {
+    let reading = readings.get(pattern);
+    if (reading === undefined) {
+        reading = parsePattern(pattern);
+        readings.set(pattern, reading);
+    }
+    return reading;
+}
+function parsePattern(pattern) {
+    if (pattern.startsWith('!'))
+        return 'a leading "!" makes an exception in a .gitignore, and this list has none, so leave it out';
+    if (pattern.startsWith('#'))
+        return 'a leading "#" marks a comment in a .gitignore, so leave comments out of the list';
+    if (pattern.includes('\\'))
+        return '"\\" is an escape in a .gitignore and a separator on Windows, so no pattern here holds one, and "?" stands for one in a name';
+    if (pattern.endsWith(' '))
+        return 'a .gitignore drops trailing spaces, so remove them';
+    const anyDepth = pattern.startsWith('**/');
+    let body = anyDepth ? pattern.slice(3) : pattern;
+    const beneath = body.endsWith('/**');
+    const directory = beneath || body.endsWith('/');
+    body = body.slice(0, beneath ? -3 : directory ? -1 : undefined);
+    const anchored = (beneath && !anyDepth) || body.includes('/');
+    if (body.startsWith('/') && !anyDepth)
+        body = body.slice(1);
+    const segments = body.split('/');
+    if (segments.some((s) => s === '' || s === '.' || s === '..'))
+        return 'it has an empty, "." or ".." segment, which names no entry';
+    if (body.includes('**') || (anyDepth && anchored))
+        return '"**" is read only as a leading "**/" before one name, or a trailing "/**"';
+    const glob = (s) => /[*?]/.test(s)
+        ? new RegExp(`^${s.replace(/[.+^${}()|[\]*?]/g, (c) => (c === '*' ? '.*' : c === '?' ? '.' : `\\${c}`))}$`, 'su')
+        : s;
+    return { segments: segments.map(glob), anchored, directory };
+}
+function nameMatches(segment, name) {
+    return typeof segment === 'string' ? segment === name : segment.test(name);
+}
+function matchesEntry(pattern, segments, directory) {
+    if (pattern.directory && !directory)
+        return false;
+    if (!pattern.anchored)
+        return nameMatches(pattern.segments[0], segments[segments.length - 1]);
+    return segments.length === pattern.segments.length && pattern.segments.every((s, i) => nameMatches(s, segments[i]));
+}
+export function patternRefusal(pattern, list) {
+    if (typeof pattern !== 'string')
+        return "it isn't a string";
+    const reading = readPattern(pattern);
+    if (typeof reading === 'string')
+        return reading;
+    if (list === 'ignore' && pattern.includes('[')) {
+        return '"[" starts a character class in a .gitignore, which this list doesn\'t read, so write each name out, with "?" for a "[" in it';
+    }
+    return undefined;
+}
+export function directoryAt(path, followSymlinks) {
+    if (!followSymlinks)
+        return lstat(path).then((s) => s.isDirectory(), () => undefined);
+    return stat(path).then((s) => s.isDirectory(), () => lstat(path).then(() => false, () => undefined));
 }
 /**
- * Whether a mount's include covers a mount-relative path. Its patterns take
- * `ignore`'s forms, read for files: a name or `*.ext` pattern covers a path by
- * its own last segment, at any depth, and `dir/**` covers what lies beneath
- * `dir`, and not a file named `dir`. Unlike `ignore`, a pattern that matches
- * a directory's name covers nothing beneath it: each file is covered by its
- * own name, so `gate.json` covers `x/gate.json` and not `x/gate.json/run.sh`,
- * and a subtree is named with `dir/**`. A directory is no file, so it needs
- * no covering: where one is a scope, refusesAsOutside (index.ts) decides.
+ * Whether a mount's include covers a mount-relative path, read as a file: a
+ * pattern that matches only directories covers what lies beneath a directory
+ * it matches, and any other covers a file by its own name or path, and
+ * nothing beneath a directory it matches. So `gate.json` covers `x/gate.json`
+ * and not `x/gate.json/run.sh`, and a subtree is named with `dir/` or
+ * `dir/**`. A directory is no file, so it needs no covering: where one is a
+ * scope, refusesAsOutside (index.ts) decides.
  */
 function coveredByInclude(relativePath, include) {
-    const name = relativePath.slice(relativePath.lastIndexOf('/') + 1);
-    for (const pattern of include) {
-        if (pattern.endsWith('/**')) {
-            if (relativePath.startsWith(pattern.slice(0, -2)))
+    const segments = relativePath.split('/');
+    return include.some((p) => {
+        const pattern = readPattern(p);
+        if (typeof pattern === 'string')
+            return false;
+        if (!pattern.directory)
+            return matchesEntry(pattern, segments, false);
+        for (let k = 1; k < segments.length; k++)
+            if (matchesEntry(pattern, segments.slice(0, k), true))
                 return true;
-        }
-        else if (pattern === name || (pattern.startsWith('*.') && name.endsWith(pattern.slice(1)))) {
-            return true;
-        }
-    }
-    return false;
+        return false;
+    });
 }
 /**
  * The ignore patterns a walk that names `scope` reads beneath it: a pattern
@@ -1575,7 +1796,7 @@ function coveredByInclude(relativePath, include) {
  * it (#276); one covering only something inside it does.
  */
 export function ignoreBeneath(scope, patterns) {
-    return patterns.filter((pattern) => !coveredByIgnore(scope, [pattern]));
+    return patterns.filter((pattern) => !coveredByIgnore(scope, [pattern], true));
 }
 /**
  * Names editors give the files they keep beside the one being edited: vim's
@@ -1594,7 +1815,7 @@ 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";
+export const EDITOR_FILE_REASON = "an editor's swap or backup file";
 /**
  * The walk's reason for a link it doesn't enter. On a mount with an include,
  * a link the include's names don't cover is passed over with it, by design,
@@ -1602,7 +1823,7 @@ const EDITOR_FILE_REASON = "an editor's swap or backup file";
  * that follows links, one that leads to a directory, and on one that
  * doesn't, every one.
  */
-const LINK_NOT_WALKED = 'a symlink, not walked';
+export const LINK_NOT_WALKED = 'a symlink, not walked';
 /** 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 === OUTSIDE_INCLUDE || why === LINK_NOT_WALKED;
@@ -1618,18 +1839,18 @@ export const OTHER_MOUNT = "another mount's directory";
  * 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 + '/'));
+    const segments = posix.normalize(relativePath).replace(/\/+$/, '').split('/');
+    return others.some((dir) => beneathNested(segments, { 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.
+ * Why a walk passes over an entry by design, by its mount-relative path, its
+ * name and whether it's a directory: another mount's directory, the ignore
+ * list, or an editor's file name. Undefined when none covers it.
  */
-function passedOverBecause(relativePath, name, patterns, others) {
+function passedOverBecause(relativePath, name, patterns, others, directory) {
     if (inOtherMount(relativePath, others))
         return OTHER_MOUNT;
-    if (isIgnored(relativePath, name, patterns))
+    if (isIgnored(relativePath, patterns, directory))
         return IGNORED;
     if (EDITOR_FILE.test(name))
         return EDITOR_FILE_REASON;
@@ -1637,17 +1858,17 @@ function passedOverBecause(relativePath, name, patterns, others) {
 }
 /**
  * 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.
+ * path, a directory or not: the path itself or a directory above it is passed
+ * over by design, as the walk reads each entry by its path, name and kind. 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) {
+export function passedOverAt(relativePath, patterns, others, directory) {
     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);
+        const why = passedOverBecause(segments.slice(0, i + 1).join('/'), segments[i], patterns, others, i < segments.length - 1 || directory);
         if (why !== undefined)
             return why;
     }
@@ -1663,28 +1884,19 @@ 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);
+        const why = passedOverBecause(segments.slice(0, i + 1).join('/'), segments[i], patterns, others, true);
         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) {
-        if (pattern === name)
-            return true;
-        if (pattern.endsWith('/**')) {
-            const prefix = pattern.slice(0, -3);
-            if (relativePath === prefix || relativePath.startsWith(prefix + '/'))
-                return true;
-        }
-        if (!pattern.includes('/') && relativePath === pattern)
-            return true;
-        if (pattern.startsWith('*.') && name.endsWith(pattern.slice(1)))
-            return true;
-    }
-    return false;
+/** Whether an ignore pattern matches the entry at a mount-relative path, a directory or not, itself. */
+function isIgnored(relativePath, patterns, directory) {
+    const segments = relativePath.split('/');
+    return patterns.some((p) => {
+        const pattern = readPattern(p);
+        return typeof pattern !== 'string' && matchesEntry(pattern, segments, directory);
+    });
 }
 /**
  * A subdirectory a checked directory's listing showed, checked in turn: still a
@@ -1699,13 +1911,13 @@ async function checkChild(view, rootReal, parent, rel) {
     }
     catch (err) {
         if (errno(err) !== 'ENOENT')
-            return { kind: 'unobserved', reason: `cannot stat (${errno(err) ?? String(err)})` };
+            return { kind: 'unobserved', ...failedOn('cannot stat', err) };
         const proof = await confirmAbsent(view, rootReal, rel, 'beneath');
-        return typeof proof === 'string' ? { kind: 'unobserved', reason: proof } : { kind: 'absent', by: proof.by };
+        return 'reason' in proof ? { kind: 'unobserved', ...proof } : { kind: 'absent', by: proof.by };
     }
     if (!info.isDirectory())
         return { kind: 'unobserved', reason: CHANGED_WALK };
-    return { kind: 'checked', dir: new CheckedDir(rel, real, lexicalOf(view, rel), info.dev, info.ino) };
+    return { kind: 'checked', dir: new CheckedDir(rel, real, lexicalOf(view, rel), info.dev, info.ino, info.birthtimeNs) };
 }
 /**
  * List a directory scope ('' for the mount root), descending when recursive,
@@ -1734,12 +1946,11 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
     };
     // 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.
+    // over its entry. 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)) {
@@ -1748,7 +1959,11 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
         return walk;
     }
     if (!opts.named && scope !== '') {
-        const why = passedOverAt(scope, view.ignore, view.others);
+        let why = passedOverAt(scope, view.ignore, view.others, true);
+        if (why !== undefined && passedOverAt(scope, view.ignore, view.others, false) === undefined) {
+            if ((await directoryAt(join(rootReal, scope), view.followSymlinks)) === false)
+                why = undefined;
+        }
         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' });
@@ -1761,7 +1976,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
         return walk;
     }
     if (top.kind === 'unobserved') {
-        walk.incomplete.push({ path: scope, reason: top.outside ? 'the directory resolves outside the mount' : top.reason, kind: 'error' });
+        walk.incomplete.push({ path: scope, reason: top.outside ? RESOLVES_OUTSIDE : top.reason, kind: 'error', ...(top.errno !== undefined ? { errno: top.errno } : {}) });
         return walk;
     }
     // A scope a path sync names is walked even where the ignore list covers
@@ -1786,11 +2001,11 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
     const visited = new Set();
     /** Paths already reported as errors, so a second visit doesn't report them again. */
     const failed = new Set();
-    const fail = (path, reason) => {
+    const fail = (path, reason, code) => {
         if (failed.has(path))
             return;
         failed.add(path);
-        walk.incomplete.push({ path, reason, kind: 'error' });
+        walk.incomplete.push({ path, reason, kind: 'error', ...(code !== undefined ? { errno: code } : {}) });
     };
     let left = cap;
     let lastTaken;
@@ -1866,6 +2081,8 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
                 const proof = rel === '' ? ROOT_UNAVAILABLE : await confirmAbsent(view, rootReal, rel, 'beneath');
                 if (typeof proof === 'string')
                     fail(rel, proof);
+                else if ('reason' in proof)
+                    fail(rel, proof.reason, proof.errno);
                 else {
                     walk.missing.add(rel);
                     // Nothing was listed, so a later check that finds it again, on the
@@ -1874,7 +2091,8 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
                 }
                 return null;
             }
-            fail(rel, `cannot list (${code ?? String(err)})`);
+            const listed = failedOn('cannot list', err);
+            fail(rel, listed.reason, listed.errno);
             return null;
         }
         entries.sort((a, b) => compareNames(a.name, b.name));
@@ -1892,9 +2110,14 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
             const childRel = rel ? `${rel}/${entry.name}` : entry.name;
             // Another mount's directory is passed over by its real path too, so a
             // walk that reaches one through a link to a directory above it lists
-            // none of that mount's names (nestedAtReal).
-            const passedOver = passedOverBecause(childRel, entry.name, ignore, view.others)
-                ?? (entry.isDirectory() && nestedAtReal(dir.at(entry.name), view.nested) !== undefined ? OTHER_MOUNT : undefined);
+            // none of that mount's names (nestedRootAtReal).
+            let passedOver = passedOverBecause(childRel, entry.name, ignore, view.others, entry.isDirectory())
+                ?? (!entry.isSymbolicLink() && nestedRootAtReal(dir.at(entry.name), view.nested) !== undefined ? OTHER_MOUNT : undefined);
+            if (passedOver === undefined && view.followSymlinks && entry.isSymbolicLink()) {
+                const asDirectory = passedOverBecause(childRel, entry.name, ignore, view.others, true);
+                if (asDirectory !== undefined && (await directoryAt(dir.at(entry.name), true)) === true)
+                    passedOver = asDirectory;
+            }
             if (passedOver !== undefined) {
                 others.push([childRel, passedOver]);
                 regions.push({ path: childRel, reason: passedOver, kind: 'ignored' });
@@ -1937,7 +2160,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
             else {
                 const symlink = entry.isSymbolicLink();
                 leaves.push([childRel, false]);
-                others.push([childRel, symlink ? 'a symlink' : 'not a regular file']);
+                others.push([childRel, symlink ? 'a symlink' : NOT_REGULAR]);
                 if (symlink)
                     regions.push({ path: childRel, reason: LINK_NOT_WALKED, kind: 'symlink' });
             }
@@ -1971,10 +2194,10 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
         return at === 'holds' || at === (stretch === 'after' ? 'after' : 'before');
     };
     // Each nested root by which directory it is, read once, when the walk
-    // first descends: a directory the walk reaches through a link spelled
-    // otherwise than disk spells it, as a disk that folds names lets one, has
-    // a real path the check by path doesn't know, and is still another
-    // mount's directory.
+    // first descends: a directory the walk reaches by a path that no
+    // comparison of names places in the nested mount's directory, as through a
+    // bind mount, or on a disk whose folding goes past the comparison's, is
+    // still another mount's directory.
     let nestedRoots;
     const isNestedRoot = async (dir) => {
         if (!view.nested?.length)
@@ -2043,7 +2266,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
             if (child.kind === 'absent')
                 walk.missing.add(sub);
             else
-                fail(sub, child.reason);
+                fail(sub, child.reason, child.errno);
         }
     };
     if (after === undefined) {
@@ -2058,6 +2281,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
     // directories a listing showed that weren't listed. A walk that doesn't
     // descend leaves its subdirectories by design.
     const capped = `the walk cap (${cap}) was reached`;
+    const raise = "whoever runs this host can raise the mount's walkCap";
     const holdingUntaken = new Set();
     for (const f of walk.seen)
         holdingUntaken.add(parentOf(f));
@@ -2065,7 +2289,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
         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' });
+        walk.incomplete.push({ path: d, reason: `${capped} before everything here was taken; naming a path beneath it walks only that path, and ${raise}`, kind: 'cap' });
     }
     let unlisted = 0;
     if (recursive) {
@@ -2073,7 +2297,7 @@ export async function walkScope(view, rootReal, scope, recursive, cap, opts = {}
             if (visited.has(d) || walk.missing.has(d) || failed.has(d))
                 continue;
             unlisted++;
-            walk.incomplete.push({ path: d, reason: `not visited: ${capped}`, kind: 'cap' });
+            walk.incomplete.push({ path: d, reason: `not visited: ${capped}; naming this path walks only it, and ${raise}`, kind: 'cap' });
         }
     }
     // The cap stopped the walk only if it left something: a walk whose last