@animalabs/agent-framework 0.28.0 → 0.29.0

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

@@ -44,7 +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 { errnoCode, systemWords } from './answers.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:
@@ -70,11 +70,18 @@ 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';
 export 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_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);
 }
@@ -157,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);
@@ -278,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
@@ -298,28 +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 (${systemWords(errnoCode({ code: found.code }), 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, nested))
-            return `${link}, which this mount does not follow`;
+            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,7 +363,7 @@ 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 !== '');
@@ -930,14 +958,14 @@ async function locateDir(view, rootReal, rel) {
         // 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 (${systemWords(code, err)})`, ...(code !== undefined ? { errno: code } : {}) };
+            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.
@@ -955,7 +983,7 @@ async function locateDir(view, rootReal, rel) {
         const holder = await nestedAtReal(real, view.nested, { name: view.name, rootReal });
         if (holder) {
             const directory = holder.judgedByInclude && await stat(real).then((info) => info.isDirectory(), () => false);
-            return holder.names(directory) ? { kind: 'unobserved', reason: leadsInto(view.name, rel, holder) } : { kind: 'missing' };
+            return holder.names(directory) ? { kind: 'unobserved', reason: leadsInto(view.name, rel, holder), ownStep: true } : { kind: 'missing' };
         }
     }
     const checked = await checkedAt(view, rel, real);
@@ -983,7 +1011,10 @@ export async function checkRoot(view, rootReal) {
     const found = await locateDir(view, rootReal, '');
     if (found.kind === 'checked')
         return { dir: found.dir };
-    return found.kind === 'unobserved' ? { reason: found.reason, ...(found.errno !== undefined ? { errno: found.errno } : {}) } : { 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
@@ -999,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('/');
@@ -1022,14 +1053,14 @@ async function createDir(view, rootReal, rel) {
         // it isn't made yet, by a path that reaches it through a link.
         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} (${systemWords(code, err)})`, ...(code !== undefined ? { errno: code } : {}) };
+                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.
@@ -1039,7 +1070,7 @@ 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', ...(await linkReason(view, rootReal, { link: childRel })) };
             return { kind: 'unobserved', reason: NOT_A_DIRECTORY };
         }
         base = checked;
@@ -1064,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('/');
@@ -1086,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 (${systemWords(code, 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
+                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
@@ -1202,7 +1236,7 @@ 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 = await nestedAtReal(parent, view.nested, { name: view.name, rootReal });
@@ -1211,7 +1245,7 @@ async function parentPlacement(view, rootReal, relativePath) {
         // 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.judgedByInclude && await stat(parent).then((info) => info.isDirectory(), () => false);
-        return holder.names(directory) ? { reason: leadsInto(view.name, parentOf(relativePath), holder) } : 'gone';
+        return holder.names(directory) ? { reason: leadsInto(view.name, parentOf(relativePath), holder), ownStep: true } : 'gone';
     }
     catch (err) {
         const code = errno(err);
@@ -1221,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 (${systemWords(code, err)})` };
+            return linkReason(view, rootReal, found);
+        return failedOn('cannot resolve the parent directory', err);
     }
 }
 /**
@@ -1237,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 });
@@ -1246,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 (${systemWords(code, err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot stat', err) };
     }
     if (info.isSymbolicLink()) {
         if (!view.followSymlinks)
@@ -1256,14 +1290,14 @@ 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 (${systemWords(errno(err), 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 (${systemWords(errno(err), err)})` };
+            return { kind: 'unobserved', ...failedOn('a symlink that cannot be resolved', err) };
         }
         if (!contained(rootReal, real))
             return { kind: 'unobserved', reason: LEAVES_MOUNT };
@@ -1271,10 +1305,10 @@ export async function observePath(view, rootReal, relativePath) {
         // 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: holder.names(target.isDirectory()) ? leadsInto(view.name, relativePath, holder) : LEAVES_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_REGULAR };
+            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
@@ -1325,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: DIRECTORY };
-        return { kind: 'unobserved', reason: `cannot open (${systemWords(code, err)})` };
+        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
@@ -1344,7 +1378,7 @@ 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() ? DIRECTORY : NOT_REGULAR };
         const leaves = view.followSymlinks ? LEAVES_MOUNT : OUTSIDE_PARENT;
@@ -1354,13 +1388,13 @@ async function openContained(view, rootReal, relativePath) {
         // 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: holder.names(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
@@ -1370,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;
@@ -1380,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 (${systemWords(code, err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         if (!keep)
@@ -1481,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 (${systemWords(code, err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         await handle.close();
@@ -1523,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 (${systemWords(errno(err), err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         await handle.close();
@@ -1545,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 (${systemWords(errno(err), err)})` };
+        return { kind: 'unobserved', ...failedOn('cannot read', err) };
     }
     finally {
         await handle.close();
@@ -1781,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,
@@ -1789,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;
@@ -1877,9 +1911,9 @@ async function checkChild(view, rootReal, parent, rel) {
     }
     catch (err) {
         if (errno(err) !== 'ENOENT')
-            return { kind: 'unobserved', reason: `cannot stat (${systemWords(errno(err), 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 };
@@ -1942,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
@@ -1967,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;
@@ -2047,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
@@ -2055,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));
@@ -2229,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) {
@@ -2244,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));
@@ -2251,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) {
@@ -2259,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