@animalabs/agent-framework 0.22.4 → 0.23.1

package/src/modules/workspace/observe.ts

@@ -39,14 +39,16 @@
 import { createHash } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
 import type { BigIntStats } from 'node:fs';
-import { lstat, mkdir, open, readdir, realpath, stat, statfs } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, readlink, realpath, stat, statfs } from 'node:fs/promises';
 import type { FileHandle } from 'node:fs/promises';
-import { dirname, join, posix, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { sameRootIdentity, type Fingerprint, type RootIdentity } from './disk-agreement.js';
 
 export interface MountView {
   /** Mount root as configured. */
   root: string;
+  /** The mount's name, which a tool puts before a path in the mount. */
+  name: string;
   /**
    * The root directory disk last agreed under, once the mount has evidence.
    * A root that resolves to any other directory is unavailable.
@@ -61,15 +63,38 @@ export interface MountView {
    * pass passes over them, named or not, as another mount's directory.
    */
   others: readonly string[];
+  /**
+   * The same mounts, each by its directory, its name and, where it has one,
+   * its real root (NestedMount), for a refusal that names the mount a path
+   * leads into: through a symlink this mount doesn't follow (linkWords), or
+   * through one it follows, or a root configured through one (nestedAtReal).
+   * Without it, no path is refused for where its links lead, and a link's
+   * refusal names no mount.
+   */
+  nested?: readonly NestedMount[];
 }
 
+/**
+ * A mount nested in another: its directory in one of its spellings,
+ * mount-relative and `/`-separated, its name, and its real root, which
+ * every spelling shares. The real root is the root as realpath resolves it
+ * (the nearest existing directory's, where the root isn't made yet) once
+ * the module's start has read it, and the root as configured until then.
+ * There's none where it's this mount's own or holds it: the mount is nested
+ * by its configured path alone, since through its real root it would claim
+ * this mount's every path.
+ */
+export type NestedMount = { dir: string; name: string; real?: string };
+
 export type StatFingerprint = Omit<Fingerprint, 'hashedAt'>;
 
 /**
- * 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;
 
@@ -141,6 +166,494 @@ function lexicalOf(view: MountView, rel: string): string {
   return rel === '' ? view.root : join(view.root, rel);
 }
 
+/**
+ * What linkOnTheWay found on a path's way beneath the mount's root: a
+ * symlink (`link`, mount-relative), or a directory there the walk couldn't
+ * ask (`unsure`, with the errno it got).
+ */
+export type LinkFound = { link: string } | { unsure: string; code: string };
+
+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: Pick<MountView, 'root' | 'followSymlinks'>,
+  rel: string,
+  through: 'path' | 'parents' = 'path',
+): Promise<LinkFound | null> {
+  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: Pick<MountView, 'root' | 'followSymlinks'>,
+  rootReal: string,
+  rel: string,
+  real: string,
+  through: 'path' | 'parents' = 'path',
+): Promise<LinkFound | null> {
+  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);
+}
+
+/**
+ * Where a symlink the walk found leads, for its refusal: to a path inside
+ * the mount (mount-relative, and whether it's a directory), outside the
+ * mount, or nowhere it can be resolved to. One realpath and one stat, made
+ * only when refusing.
+ */
+export type LinkLeads = { kind: 'inside'; target: string; directory: boolean } | { kind: 'outside' } | { kind: 'nowhere' };
+
+export async function linkLeads(root: string, rootReal: string, link: string): Promise<LinkLeads> {
+  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: string, nested: readonly { dir: string; name: string }[]): { dir: string; name: string } | undefined {
+  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: string, found: LinkFound, leads: LinkLeads | null, nested: readonly { dir: string; name: string }[] = []): string {
+  const spell = (rel: string) => `"${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: Pick<MountView, 'root' | 'name' | 'nested'>, rootReal: string, found: LinkFound): Promise<string> {
+  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: string, nested: readonly NestedMount[] = []): { name: string; use: string } | undefined {
+  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: string, rel: string, holder: { name: string; use: string }): string {
+  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: BigIntStats, b: BigIntStats): boolean => 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: string): string => (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: string): string =>
+  [...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: string): string => 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: string): string => name.normalize('NFC').toLowerCase().toUpperCase().toLowerCase();
+
+/** What the workspace holds of a mount, as the spelling step reads it (diskSpelling). */
+export interface WorkspaceEntries {
+  /**
+   * Whether the workspace holds an entry at exactly this path, or records an
+   * intent there, such as a deletion disk hasn't been given yet.
+   */
+  has(path: string): boolean;
+  /** The paths of the entries under `prefix`, a directory's path and `/`, or `''` for every entry. */
+  under(prefix: string): string[];
+  /**
+   * The nested mount whose directory holds this path, by the nested-mount
+   * checks' own reading of it, or undefined where the path is the mount's
+   * own.
+   */
+  holder(path: string): string | undefined;
+  /** Whether the mount's root folds case (foldsCase). */
+  rootFoldsCase: boolean;
+}
+
+/**
+ * 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: string): Promise<boolean> {
+  const holder = dirname(dir);
+  let listed: Set<string>;
+  try {
+    listed = new Set(await readdir(dir));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && holder !== dir) return foldsCase(holder);
+    listed = new Set();
+  }
+  const look = (path: string) => 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: string) => 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: string): string =>
+  [...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: readonly string[], prefix: string, segment: string): string | null {
+  const want = lowered(segment);
+  let found: string | null = null;
+  let previous: string | null = 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: string, segment: string, given: BigIntStats | null): Promise<{ name: string; found: boolean; caseFolds: boolean | null }> {
+  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: boolean | null = 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: string) => ({ 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: string, relativePath: string, entries?: WorkspaceEntries): Promise<string> {
+  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: string[] = [];
+  const folding: (boolean | null)[] = [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: number): void => {
+    // The nearest directory, from the one reached up, that told.
+    let folds: boolean | null = 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('/');
+}
+
 // ===========================================================================
 // Checked directories
 // ===========================================================================
@@ -201,7 +714,11 @@ export class CheckedDir {
    */
   async sync(): Promise<void> {
     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) throw new Error(CHANGED);
@@ -235,14 +752,27 @@ async function locateDir(view: MountView, rootReal: string, rel: string): Promis
   } catch (err) {
     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.
     if (real !== rootReal) return { kind: 'unobserved', reason: ROOT_UNAVAILABLE };
   } 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) {
@@ -303,6 +833,10 @@ async function createDir(view: MountView, rootReal: string, rel: string): Promis
   if (base === null) 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]!));
     } catch (err) {
@@ -312,7 +846,13 @@ async function createDir(view: MountView, rootReal: string, rel: string): Promis
     // 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) return { kind: 'unobserved', reason: 'a parent path is not a directory' };
+    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 };
@@ -326,10 +866,12 @@ async function createDir(view: MountView, rootReal: string, rel: string): Promis
  * 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: MountView, rootReal: string, rel: string, target: 'entry' | 'beneath' = 'entry'): Promise<{ by: string } | string> {
   const root = await locateDir(view, rootReal, '');
@@ -364,6 +906,8 @@ export async function confirmAbsent(view: MountView, rootReal: string, rel: stri
     }
     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;
       if (last) return CHANGED; // a directory there after all
@@ -455,15 +999,24 @@ export async function filesystemTrustsCtime(root: string): Promise<boolean> {
 /**
  * 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: string, lexical: string): Promise<'inside' | 'gone' | { reason: string }> {
+async function parentPlacement(view: MountView, rootReal: string, relativePath: string): Promise<'inside' | 'gone' | { reason: string }> {
   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)})` };
   }
 }
@@ -476,7 +1029,7 @@ async function parentPlacement(rootReal: string, lexical: string): Promise<'insi
  */
 export async function observePath(view: MountView, rootReal: string, relativePath: string): Promise<Observation> {
   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') return { kind: 'unobserved', reason: placement.reason };
   let info;
@@ -502,6 +1055,8 @@ export async function observePath(view: MountView, rootReal: string, relativePat
       return { kind: 'unobserved', reason: `a symlink that cannot be resolved (${errno(err) ?? String(err)})` };
     }
     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' };
     }
@@ -516,9 +1071,10 @@ export async function observePath(view: MountView, rootReal: string, relativePat
 
 /**
  * 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: MountView,
@@ -540,19 +1096,32 @@ async function openContained(
   } catch (err) {
     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)})` };
   }
   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' };