@animalabs/agent-framework 0.28.0 → 0.29.0

package/src/modules/workspace/effects.ts

@@ -45,12 +45,16 @@ import { constants as fsConstants } from 'node:fs';
 import { lstat, open, realpath, stat, unlink } from 'node:fs/promises';
 import type { FileHandle } from 'node:fs/promises';
 import {
+  type Cause,
   type CheckedDir,
   type MountView,
+  DIRECTORY,
   LEAVES_MOUNT,
+  LINK_TO_DIRECTORY,
   NONBLOCK,
   NOT_A_DIRECTORY,
   NOT_FOLLOWED,
+  NOT_REGULAR,
   OUTSIDE_PARENT,
   ROOT_REPLACED,
   contained,
@@ -63,6 +67,7 @@ import {
   nestedAtReal,
   parentOf,
 } from './observe.js';
+import { errnoCode, systemWords } from './answers.js';
 
 /** What a write or unlink may find at its path when it acts. */
 export type Expect =
@@ -79,12 +84,18 @@ export class EffectFailed extends Error {
   /** Whether the path's entry was touched before the failure. */
   readonly touched: boolean;
 
-  constructor(message: string, touched: boolean) {
+  constructor(message: string, touched: boolean, readonly detail: Cause = {}) {
     super(message);
     this.touched = touched;
   }
 }
 
+export function callFailed(what: string, err: unknown, touched: boolean, sep: 'paren' | 'colon' = 'paren'): EffectFailed {
+  const code = errnoCode(err);
+  const words = systemWords(code, err);
+  return new EffectFailed(sep === 'paren' ? `${what} (${words})` : `${what}: ${words}`, touched, code !== undefined ? { errno: code } : {});
+}
+
 const CHANGED = 'disk changed since it was checked';
 const MODE_CHANGED = 'disk\'s mode changed since it was checked; a sync takes it in';
 /**
@@ -115,10 +126,6 @@ const HARD_LINKED = 'a file with other hard links, which writing it in place wou
   + 'this; to write this path alone, give it a copy of its own first (copy it to a new name, then move that over it) '
   + 'and materialize again';
 
-function message(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
-
 function noFollowFlag(view: MountView): number {
   return !view.followSymlinks && typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
 }
@@ -134,9 +141,9 @@ function noFollowFlag(view: MountView): number {
  */
 async function parentFor(view: MountView, rootReal: string, rel: string, create: boolean) {
   const root = await checkRoot(view, rootReal);
-  if ('reason' in root) throw new EffectFailed(root.reason, false);
+  if ('reason' in root) throw new EffectFailed(root.reason, false, root.errno !== undefined ? { errno: root.errno } : {});
   const checked = await checkDir(view, rootReal, parentOf(rel), { create });
-  if (checked.kind === 'unobserved') throw new EffectFailed(checked.outside ? OUTSIDE_PARENT : checked.reason, false);
+  if (checked.kind === 'unobserved') throw new EffectFailed(checked.outside ? OUTSIDE_PARENT : checked.reason, false, checked.errno !== undefined ? { errno: checked.errno } : {});
   return { ...checked, root: root.dir };
 }
 
@@ -171,11 +178,11 @@ async function hashAt(target: string, id: { dev: bigint; ino: bigint }, flags: n
   try {
     handle = await open(target, fsConstants.O_RDONLY | NONBLOCK | flags);
   } catch (err) {
-    throw new EffectFailed(`cannot verify the disk copy (${errno(err) ?? message(err)})`, false);
+    throw callFailed('cannot verify the disk copy', err, false);
   }
   try {
     const info = await handle.stat({ bigint: true });
-    if (info.dev !== id.dev || info.ino !== id.ino) throw new EffectFailed(CHANGED, false);
+    if (info.dev !== id.dev || info.ino !== id.ino) throw new EffectFailed(CHANGED, false, { again: true });
     const hash = createHash('sha256');
     const chunk = Buffer.alloc(1 << 20);
     for (let offset = 0; ;) {
@@ -185,6 +192,9 @@ async function hashAt(target: string, id: { dev: bigint; ino: bigint }, flags: n
       offset += bytesRead;
     }
     return hash.digest('hex');
+  } catch (err) {
+    if (err instanceof EffectFailed) throw err;
+    throw callFailed('cannot verify the disk copy', err, false);
   } finally {
     await handle.close();
   }
@@ -266,10 +276,10 @@ export async function writeContained(
         const leads = link ? await stat(target).then(() => 'somewhere', (e: unknown) => errno(e)) : null;
         throw new EffectFailed(leads === 'ENOENT' || leads === 'ENOTDIR'
           ? 'a symlink that leads nowhere is at this path, and a push makes a file only where nothing is, forced or not; '
-            + 'whoever runs this host can remove the link or make it lead to a file, and a materialize then writes it'
-          : 'something appeared at this path since it was checked', false);
+            + 'whoever runs this host can remove the link, and materializing again then gets past it'
+          : 'something appeared at this path since it was checked', false, leads === 'ENOENT' || leads === 'ENOTDIR' ? {} : { again: true });
       }
-      throw new EffectFailed(`cannot create the file (${errno(err) ?? message(err)})`, false);
+      throw callFailed('cannot create the file', err, false);
     }
   };
   let handle: FileHandle;
@@ -282,11 +292,11 @@ export async function writeContained(
     } catch (err) {
       const code = errno(err);
       if (code === 'ENOENT' && expect.kind === 'any') handle = await create();
-      else if (code === 'ENOENT') throw new EffectFailed('the file was removed since it was checked', false);
+      else if (code === 'ENOENT') throw new EffectFailed('the file was removed since it was checked', false, { again: true });
       else if (code === 'ELOOP' && !view.followSymlinks) throw new EffectFailed(NOT_FOLLOWED, false);
-      else if (code === 'EISDIR') throw new EffectFailed('a directory', false);
-      else if (code === 'ENXIO') throw new EffectFailed('not a regular file', false); // a FIFO with no reader
-      else throw new EffectFailed(`cannot open the file (${code ?? message(err)})`, false);
+      else if (code === 'EISDIR') throw new EffectFailed((await lstat(target).catch(() => null))?.isSymbolicLink() === true ? LINK_TO_DIRECTORY : DIRECTORY, false);
+      else if (code === 'ENXIO') throw new EffectFailed(NOT_REGULAR, false); // a FIFO with no reader
+      else throw callFailed('cannot open the file', err, false);
     }
   }
 
@@ -379,7 +389,7 @@ export async function writeContained(
     return { perm: Number((await handle.stat({ bigint: true })).mode & 0o777n), widenRefused, modeKept };
   } catch (err) {
     if (err instanceof EffectFailed) throw err;
-    throw new EffectFailed(`could not ${stage}: ${message(err)}`, touched);
+    throw callFailed(`could not ${stage}`, err, touched, 'colon');
   } finally {
     await handle.close();
   }
@@ -429,30 +439,30 @@ async function checkOpened(
   touched: boolean,
 ): Promise<void> {
   const info = await handle.stat({ bigint: true });
-  if (!info.isFile()) throw new EffectFailed('not a regular file', touched);
+  if (!info.isFile()) throw new EffectFailed(NOT_REGULAR, touched);
   const located = async (): Promise<string> => {
     const real = await realpath(target).catch(() => null);
-    if (real === null) throw new EffectFailed(CHANGED, touched);
+    if (real === null) throw new EffectFailed(CHANGED, touched, { again: true });
     const refused = await refusedLanding(view, rootReal, rel, real);
     if (refused !== null) throw new EffectFailed(refused, touched);
     return real;
   };
   if (expect.kind === 'content') {
     await located();
-    if ((await hashAt(target, info, noFollow)) !== expect.hash) throw new EffectFailed(CHANGED, touched);
+    if ((await hashAt(target, info, noFollow)) !== expect.hash) throw new EffectFailed(CHANGED, touched, { again: true });
   }
   const real = await located();
   const named = await stat(real, { bigint: true }).catch(() => null);
-  if (named === null || named.dev !== info.dev || named.ino !== info.ino) throw new EffectFailed(CHANGED, touched);
+  if (named === null || named.dev !== info.dev || named.ino !== info.ino) throw new EffectFailed(CHANGED, touched, { again: true });
   if (!view.followSymlinks) {
     const entry = await lstat(target, { bigint: true }).catch(() => null);
     if (entry?.isSymbolicLink()) throw new EffectFailed(NOT_FOLLOWED, touched);
-    if (entry === null || !entry.isFile() || entry.dev !== info.dev || entry.ino !== info.ino) throw new EffectFailed(CHANGED, touched);
+    if (entry === null || !entry.isFile() || entry.dev !== info.dev || entry.ino !== info.ino) throw new EffectFailed(CHANGED, touched, { again: true });
   }
   if (info.nlink > 1n) throw new EffectFailed(HARD_LINKED, touched);
   const gone = await moved(root, parent);
-  if (gone !== null) throw new EffectFailed(gone, touched);
-  if (!unchanged(info, await handle.stat({ bigint: true }).catch(() => null))) throw new EffectFailed(CHANGED, touched);
+  if (gone !== null) throw new EffectFailed(gone, touched, gone === MOVED ? { again: true } : {});
+  if (!unchanged(info, await handle.stat({ bigint: true }).catch(() => null))) throw new EffectFailed(CHANGED, touched, { again: true });
 }
 
 /** The sticky bit, the one special bit the chmod before a write's bytes keeps. */
@@ -490,7 +500,7 @@ export async function chmodContained(
   view: MountView, rootReal: string, rel: string, mode: number, expect: Expect, from?: number,
 ): Promise<{ refused: boolean; narrowing: boolean }> {
   const checked = await parentFor(view, rootReal, rel, false);
-  if (checked.kind !== 'checked') throw new EffectFailed('the file was removed since it was checked', false);
+  if (checked.kind !== 'checked') throw new EffectFailed('the file was removed since it was checked', false, { again: true });
   const parent = checked.dir;
   const root = checked.root;
   const target = parent.at(nameOf(rel));
@@ -503,9 +513,9 @@ export async function chmodContained(
     handle = await open(target, fsConstants.O_RDONLY | NONBLOCK | noFollow);
   } catch (err) {
     const code = errno(err);
-    if (code === 'ENOENT') throw new EffectFailed('the file was removed since it was checked', false);
+    if (code === 'ENOENT') throw new EffectFailed('the file was removed since it was checked', false, { again: true });
     if (code === 'ELOOP' && !view.followSymlinks) throw new EffectFailed(NOT_FOLLOWED, false);
-    throw new EffectFailed(`cannot open the file (${code ?? message(err)})`, false);
+    throw callFailed('cannot open the file', err, false);
   }
   let touched = false;
   let stage = 'set the file\'s mode';
@@ -526,7 +536,7 @@ export async function chmodContained(
     return { refused: false, narrowing };
   } catch (err) {
     if (err instanceof EffectFailed) throw err;
-    throw new EffectFailed(`could not ${stage}: ${message(err)}`, touched);
+    throw callFailed(`could not ${stage}`, err, touched, 'colon');
   } finally {
     await handle.close();
   }
@@ -559,16 +569,16 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
   } catch (err) {
     if (errno(err) === 'ENOENT') {
       const gone = await moved(root, parent);
-      if (gone !== null) throw new EffectFailed(gone, false);
+      if (gone !== null) throw new EffectFailed(gone, false, gone === MOVED ? { again: true } : {});
       return parent.rel;
     }
-    throw new EffectFailed(`cannot stat (${errno(err) ?? message(err)})`, false);
+    throw callFailed('cannot stat', err, false);
   }
   // Confirming an unlink that already happened never removes a file that
   // appeared since.
   if (expect.kind === 'absent') {
     const kind = info.isDirectory() ? 'a directory' : info.isSymbolicLink() ? 'a symlink' : info.isFile() ? 'a file' : 'a pipe, socket or device';
-    throw new EffectFailed(`${kind} appeared at this path since it was checked`, false);
+    throw new EffectFailed(`${kind} appeared at this path since it was checked`, false, { again: true });
   }
   let file = info;
   if (info.isSymbolicLink()) {
@@ -586,21 +596,21 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
       throw new EffectFailed(holder.names(directory) ? leadsInto(view.name, rel, holder) : LEAVES_MOUNT, false);
     }
     const through = await stat(real, { bigint: true }).catch(() => null);
-    if (through === null) throw new EffectFailed(CHANGED, false);
+    if (through === null) throw new EffectFailed(CHANGED, false, { again: true });
     // A followed link stands for the file it leads to, so it's removed only
     // for a regular one, as the file the workspace deleted. This refusal,
     // and the one below for what isn't a regular file at the path, use
     // observation's words for the path, so the push answers a forced unlink
     // and an unforced one alike (reconcile.ts inTheWay).
-    if (!through.isFile()) throw new EffectFailed(through.isDirectory() ? 'a symlink to a directory, not walked' : 'not a regular file', false);
+    if (!through.isFile()) throw new EffectFailed(through.isDirectory() ? LINK_TO_DIRECTORY : NOT_REGULAR, false);
     // One leading to a file this mount's own include leaves out leaves the
     // mount too, and that file isn't read for a hash (coversLanding).
     if (!(await coversLanding(view, rootReal, real, rel))) throw new EffectFailed(LEAVES_MOUNT, false);
     file = through;
   } else if (info.isDirectory()) {
-    throw new EffectFailed('a directory', false);
+    throw new EffectFailed(DIRECTORY, false);
   } else if (!info.isFile()) {
-    throw new EffectFailed('not a regular file', false);
+    throw new EffectFailed(NOT_REGULAR, false);
   } else {
     // A regular file reached through a link among its directories lands
     // where the mount may not act: in a nested mount's directory, or on a
@@ -610,15 +620,15 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     const refused = await refusedLanding(view, rootReal, rel, target);
     if (refused !== null) throw new EffectFailed(refused, false);
   }
-  if (expect.kind === 'content' && (await hashAt(target, file, noFollowFlag(view))) !== expect.hash) throw new EffectFailed(CHANGED, false);
+  if (expect.kind === 'content' && (await hashAt(target, file, noFollowFlag(view))) !== expect.hash) throw new EffectFailed(CHANGED, false, { again: true });
   const gone = await moved(root, parent);
-  if (gone !== null) throw new EffectFailed(gone, false);
+  if (gone !== null) throw new EffectFailed(gone, false, gone === MOVED ? { again: true } : {});
   // The entry checked is still the one at the path, unwritten since it was
   // hashed, as close to the unlink as Node allows (see the header): a file
   // replaced or edited while it was hashed isn't removed.
   const again = await lstat(target, { bigint: true }).catch(() => null);
   const named = again?.isSymbolicLink() ? await stat(target, { bigint: true }).catch(() => null) : again;
-  if (!unchanged(file, named)) throw new EffectFailed(CHANGED, false);
+  if (!unchanged(file, named)) throw new EffectFailed(CHANGED, false, { again: true });
   try {
     await unlink(target);
   } catch (err) {
@@ -626,7 +636,7 @@ export async function unlinkContained(view: MountView, rootReal: string, rel: st
     // An unlink is all or nothing: one refused outright changed nothing, so
     // the path's evidence can go back as it was. Anything else may have
     // landed (a network filesystem's EIO, say): the next observation resolves it.
-    if (code !== 'ENOENT') throw new EffectFailed(`could not unlink the file: ${message(err)}`, !UNLINK_REFUSALS.has(code ?? ''));
+    if (code !== 'ENOENT') throw callFailed('could not unlink the file', err, !UNLINK_REFUSALS.has(code ?? ''), 'colon');
   }
   return parent.rel;
 }
@@ -661,7 +671,7 @@ export async function syncDirectories(view: MountView, rootReal: string, rels: I
       await checked.dir.sync();
       if (!(await root.dir.stillHere())) failed.set(rel, ROOT_REPLACED);
     } catch (err) {
-      failed.set(rel, message(err));
+      failed.set(rel, systemWords(errno(err), err));
     }
   }
   return failed;

package/src/modules/workspace/index.ts

@@ -5,6 +5,7 @@
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
 
+import { NOTICE_TAG } from '../../notice-tags.js';
 import { constants as fsConstants } from 'node:fs';
 import type { BigIntStats, Stats } from 'node:fs';
 import { open, readdir, readlink, stat, lstat, realpath } from 'node:fs/promises';
@@ -40,7 +41,7 @@ import { MountWatcher, type FsChange } from './watcher.js';
 import { hashContent, storedBytes, DEFAULT_MAX_FILE_SIZE, type StoredBytes } from './sync.js';
 import { DiskAgreement, EvidenceUnavailable, callGate, sameRootIdentity } from './disk-agreement.js';
 import { type BranchIntent, BranchIntents } from './branch-intent.js';
-import { CHANGED, DIRECTORY, IGNORED, LEAVES_MOUNT, NONBLOCK, NOT_FOLLOWED, NOT_REGULAR, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beneathRoot, checkDir, checkRoot, confirmAbsent, coversLanding, directoryAt, diskSpelling, filesystemTrustsCtime, foldsCase, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, nestedAtReal, nestedGuess, nestedHolder, nestedStep, observePath, parsedSpelling, passedOverAt, pathSegments, patternRefusal, readBytes, readPrefix, realSegments, restBeneath, rootAbsence, sameRoot, shownLeads, sniffImageMime, surelyAtRoot, walkScope, withinIncludes, type CheckedDir, type LinkFound, type MountView, type NestedGuess, type NestedMount, type WorkspaceEntries } from './observe.js';
+import { CHANGED, type Cause, DIRECTORY, IGNORED, NONBLOCK, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beneathRoot, checkDir, checkRoot, confirmAbsent, coversLanding, directoryAt, diskSpelling, filesystemTrustsCtime, foldsCase, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, nestedAtReal, nestedGuess, nestedHolder, nestedStep, observePath, parsedSpelling, passedOverAt, pathSegments, patternRefusal, readBytes, readPrefix, realSegments, restBeneath, rootAbsence, sameRoot, shownLeads, sniffImageMime, surelyAtRoot, walkScope, withinIncludes, type CheckedDir, type LinkFound, type MountView, type NestedGuess, type NestedMount, type WorkspaceEntries } from './observe.js';
 import { TOOL_BATCH_HOOK_TIMEOUT_MS, ensureStateRegistered } from '../../module-registry.js';
 import { DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS } from '../../tool-result-history.js';
 import { type EditSpec, type FilePlan, countBudget, decodeForEdit, hintBudget, planFile } from './edit-plan.js';
@@ -60,12 +61,14 @@ import {
   NOT_PUSHED_IN_OTHER_MOUNT,
   WALK_CAP,
   entryMode,
+  explained,
   pushPaths,
   reconcilePass,
   settleAdoptionBeforeMutation,
+  wayOn,
 } from './reconcile.js';
 import { EffectFailed, unlinkContained } from './effects.js';
-import { AWAITS_REOPEN, ROOT_RECHECK, ROOT_UNCHECKED, Refusal, changesFiles, didNothing, errnoCode, errnoWayOn, errnoWords, hostFix, onlyTheHost, systemWords, unexpectedAnswer } from './answers.js';
+import { AWAITS_REOPEN, MOUNT_IT, ROOT_RECHECK, Refusal, UNFOLLOWED_STEP, changesFiles, didNothing, errnoCode, errnoWayOn, errnoWords, hostFix, onlyTheHost, systemWords, unexpectedAnswer } from './answers.js';
 import { unknownToolMessage } from '../unknown-tool.js';
 import { closestNames } from '../../closest-names.js';
 import { RecordJournal } from '../../record-journal.js';
@@ -270,6 +273,12 @@ class NotRegularFile extends WorkspaceReadError {
   }
 }
 
+class LinkOnTheWay extends WorkspaceReadError {
+  constructor(code: WorkspaceReadErrorCode, message: string, readonly reason: string, errno?: string) {
+    super(code, message, 'readlink', errno);
+  }
+}
+
 class RootUnavailable extends WorkspaceReadError {
   constructor(readonly mount: string, readonly reason: string | null, stage: WorkspaceReadStage, errno?: string, readonly refusal?: Refusal) {
     super('mount_unavailable', reason === null ? `Mount unavailable: ${mount}` : `Mount unavailable: ${mount}: ${reason}`, stage, errno);
@@ -316,10 +325,10 @@ export interface ReadFileFromDiskOptions {
  * Why a pass decided nothing, or null where it decided its paths. A pass gives
  * up deciding, and reports no path, when the selected branch kept changing
  * while it gathered, or when a sync's branch was no longer selected; it then
- * carries no branchId, and the region it leaves incomplete says why.
+ * carries no branchId, and says why in `undecided`.
  */
 function undecidedOf(pass: PassResult): string | null {
-  return pass.branchId === undefined ? (pass.incomplete[0]?.reason ?? 'the pass decided nothing') : null;
+  return pass.branchId === undefined ? (pass.undecided ?? 'the pass decided nothing') : null;
 }
 
 function errnoOf(err: unknown): string | undefined {
@@ -385,15 +394,16 @@ async function linkReadError(
   rootReal: string,
 ): Promise<WorkspaceReadError> {
   if (!('link' in found)) {
-    return new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}: ${linkWords(mount.config.name, found, null)}`, 'readlink', found.code);
+    const reason = linkWords(mount.config.name, found, null);
+    return new LinkOnTheWay('not_found', `Unable to read file: ${mountPrefixedPath}: ${reason}`, reason, found.code);
   }
   const leads = await shownLeads(rootReal, rootReal, found, mount.config.include);
-  const reason = `${mountPrefixedPath}: ${linkWords(mount.config.name, found, leads, nested, mount.config.include)}`;
+  const reason = linkWords(mount.config.name, found, leads, nested, mount.config.include);
   const holder = leads?.kind === 'inside' ? nestedHolder(leads.target, nested) : undefined;
   const code = leads?.kind === 'outside' ? 'escape'
     : leads?.kind === 'inside' && holder && namesHolder(leads, nested) ? 'other_mount'
     : relativePath === found.link ? 'symlink' : 'parent_symlink';
-  return new WorkspaceReadError(code, reason, 'readlink');
+  return new LinkOnTheWay(code, `${mountPrefixedPath}: ${reason}`, reason);
 }
 
 /**
@@ -2290,13 +2300,13 @@ export class WorkspaceModule implements Module {
 
     let text: string;
     if (paths.length === 1) {
-      text = `[workspace event · ${op} · ${paths[0]}]`;
+      text = `[${NOTICE_TAG.workspaceEvent} · ${op} · ${paths[0]}]`;
     } else {
       const list = paths.map(p => `- ${p}`).join('\n');
-      text = `[workspace event · ${op} · ${paths.length} files in ${mountName}/]\n${list}`;
+      text = `[${NOTICE_TAG.workspaceEvent} · ${op} · ${paths.length} files in ${mountName}/]\n${list}`;
     }
     if (conflicts && conflicts.length > 0) {
-      text += `\n[conflicts with disk: ${conflicts.join(', ')}; reading each shows how to settle it]`;
+      text += `\n[${NOTICE_TAG.conflictsWithDisk}: ${conflicts.join(', ')}; reading each shows how to settle it]`;
     }
 
     return {
@@ -3133,6 +3143,14 @@ export class WorkspaceModule implements Module {
     return names.length === 0 ? 'this workspace has no mounts' : `the mounts are ${listed(names.map((name) => JSON.stringify(name)))}`;
   }
 
+  private emptyPathField(mount: string | undefined, bare: string): string {
+    const empty = '"path" is "", which names no file or directory.';
+    if (mount === undefined) return `${empty} Leaving "path" out ${bare}.`;
+    if (mount === '') return `${empty} "mount" is "" too; leaving both out ${bare}.`;
+    if (this.mounts.has(mount)) return `${empty} Leaving "path" out covers mount ${JSON.stringify(mount)}.`;
+    return `${empty} "mount" is ${JSON.stringify(mount)}, which is no mount's name; ${this.mountList()}. Leaving both out ${bare}.`;
+  }
+
   private noSuchMountField(given: string, bare: string): string {
     const [close] = closestNames(given, [...this.mounts.keys()], 1);
     return `"mount" is ${JSON.stringify(given)}, which is no mount's name; ${this.mountList()}.`
@@ -3896,7 +3914,7 @@ export class WorkspaceModule implements Module {
         return `${shown} is in conflict: the workspace deleted it and disk changed it since. ` +
           'Sync this path to take the disk version.';
       case 'unverified':
-        return uncheckedFile(shown, report.note);
+        return uncheckedFile(shown, report.note, report.noteCause ?? {});
       default:
         return missing ?? `there's no file at ${shown}. ls or glob lists the files that exist.`;
     }
@@ -4063,8 +4081,8 @@ export class WorkspaceModule implements Module {
     const rootReal = await realpath(root).catch(() => root);
     const view = this.viewOf(mount, this.agreementOrThrow().rootIdentityForRead(mount.config.name));
     const proof = await confirmAbsent(view, rootReal, relativePath);
-    if (typeof proof !== 'string') return 'none';
-    return { unreadable: proof === CHANGED ? containedRefusal(err, path) : proof };
+    if (!('reason' in proof)) return 'none';
+    return { unreadable: proof.reason === CHANGED ? containedRefusal(err, path) : proof.reason };
   }
 
   private async restoreEach<T extends { relativePath: string; file: string; hash: string; size: number; what: 'saved' | 'conflict-disk' }>(
@@ -5031,7 +5049,7 @@ export class WorkspaceModule implements Module {
         // whether the file is gone, so it's taken as the agent's write too.
         if (error instanceof EffectFailed && error.touched) {
           this.recordDirectWrite(mount, agentName, since);
-          return { success: false, isError: true, error: `The delete of ${path} failed after it reached the file, so the file may be gone: ${directReason(error)}. ls shows whether it is.` };
+          return { success: false, isError: true, error: `The delete of ${JSON.stringify(path)} failed after it reached the file, so the file may be gone: ${directReason(error)}. ls shows whether it is.` };
         }
         return { success: false, isError: true, error: directDidNothing('delete', path, error) };
       }
@@ -5384,7 +5402,8 @@ export class WorkspaceModule implements Module {
       .filter((region) => region.kind === 'error' || region.kind === 'cap' || (region.kind === 'ignored' && region.path === dir && dir !== ''))
       .map((region) => ({
         path: region.path,
-        reason: region.reason === OTHER_MOUNT ? this.otherMountNote(mount.config.name, region.path, 'list', moved) : region.reason,
+        reason: region.reason === OTHER_MOUNT ? this.otherMountNote(mount.config.name, region.path, 'list', moved)
+          : explained(region.reason, region.errno !== undefined ? { errno: region.errno } : {}, 'list'),
       }));
     return {
       view,
@@ -6003,7 +6022,10 @@ export class WorkspaceModule implements Module {
     const modesKept: Array<{ mount: string; path: string; reason: string }> = [];
 
     let explicit: { mount: MountState; relativePath: string } | null = null;
-    if (input.path) {
+    if (input.path !== undefined) {
+      if (input.path === '') {
+        return { success: false, error: didNothing('materialize', this.emptyPathField(input.mount, "covers every mount that takes writes and doesn't already write them straight to disk")), isError: true };
+      }
       const parsed = await this.parsePath(input.path);
       explicit = parsed;
       // A path outside the mount's include that's no scope (refusesAsOutside)
@@ -6017,7 +6039,7 @@ export class WorkspaceModule implements Module {
     let mountsToMaterialize: Array<{ name: string; mount: MountState }>;
     if (explicit) {
       mountsToMaterialize = [{ name: explicit.mount.config.name, mount: explicit.mount }];
-    } else if (input.mount) {
+    } else if (input.mount !== undefined) {
       const m = this.mounts.get(input.mount);
       if (!m) {
         return { success: false, error: didNothing('materialize', this.noSuchMountField(input.mount, "covers every mount that takes writes and doesn't already write them straight to disk")), isError: true };
@@ -6224,7 +6246,8 @@ export class WorkspaceModule implements Module {
 
     // A path names its own mount; otherwise the given mount, or every mount.
     let targets: Array<{ name: string; mount: MountState; relativePath: string }>;
-    if (input.path) {
+    if (input.path !== undefined) {
+      if (input.path === '') return { success: false, error: didNothing('sync', this.emptyPathField(input.mount, 'covers every mount')), isError: true };
       const { mount, relativePath, moved, root } = await this.parsePath(input.path);
       // A path outside the mount's include that's no scope (refusesAsOutside)
       // is refused; beneath a directory, the walk passes over what the include
@@ -6233,7 +6256,7 @@ export class WorkspaceModule implements Module {
         return { success: false, error: didNothing('sync', new OutsideIncludeError(input.path, mount.config).message), isError: true };
       }
       targets = [{ name: mount.config.name, mount, relativePath }];
-    } else if (input.mount) {
+    } else if (input.mount !== undefined) {
       const m = this.mounts.get(input.mount);
       if (!m) {
         return { success: false, error: didNothing('sync', this.noSuchMountField(input.mount, 'covers every mount')), isError: true };
@@ -6312,7 +6335,7 @@ export class WorkspaceModule implements Module {
       // refused" don't look identical from the outside.
       for (const r of pass.reports.values()) {
         if (r.state === 'unverified') {
-          allSkipped.push({ mount: name, path: r.path, reason: `disk could not be checked: ${r.note ?? 'not observed'}` });
+          allSkipped.push({ mount: name, path: r.path, reason: `disk could not be checked: ${explained(r.note ?? 'not observed', r.noteCause ?? {}, 'sync')}` });
         } else if (r.state === 'disk-only') {
           allSkipped.push({ mount: name, path: r.path, reason: 'disk-only: binary or over the size limit, never stored' });
         }
@@ -6799,7 +6822,13 @@ function directReason(error: unknown): string {
 }
 
 function directWayOn(error: unknown): string | null {
-  return error instanceof FileChanged ? 'Calling again reads it afresh.' : error instanceof WriteRefused ? error.wayOn : null;
+  if (error instanceof FileChanged) return 'Calling again reads it afresh.';
+  if (error instanceof WriteRefused) return error.wayOn;
+  if (error instanceof EffectFailed) {
+    if (error.detail.errno !== undefined) return errnoWayOn(error.detail.errno);
+    if (error.detail.again === true) return 'Calling again checks it afresh.';
+  }
+  return null;
 }
 
 function directDidNothing(tool: string, path: string, error: unknown): string {
@@ -6837,16 +6866,11 @@ function deletedOnDisk(path: string): string {
   return `there's no file at ${JSON.stringify(path)} any more: disk's copy was deleted since the workspace last agreed with it, and the workspace took that in first. ls or glob lists the files that exist.`;
 }
 
-function uncheckedFile(shown: string, note: string | undefined): string {
+function uncheckedFile(shown: string, note: string | undefined, cause: Cause): string {
   if (note === DIRECTORY) return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
-  const on = note === ROOT_UNAVAILABLE ? ROOT_UNCHECKED
-    : note === ROOT_REPLACED ? null
-      : note === NOT_FOLLOWED ? "Calling again won't change that; if you know the file it leads to, name that file by its own path."
-        : note === LEAVES_MOUNT ? "Calling again won't change that; if a mount holds the file it leads to, name it by its path there."
-          : note === NOT_REGULAR ? onlyTheHost('put a regular file there')
-            : note === CHANGED ? 'Calling again checks it afresh.'
-              : 'Calling again checks disk again; if the same reason comes back, whoever runs this host can fix it on disk.';
-  return `${shown} isn't in the workspace, and disk couldn't be checked: ${sentence(note ?? 'not observed')}${on !== null ? ` ${on}` : ''}`;
+  const on = note === ROOT_REPLACED || cause.ownStep === true ? null
+    : (note === undefined ? null : wayOn(note, cause, 'read')) ?? 'calling again checks disk again; if the same reason comes back, whoever runs this host can fix it on disk';
+  return `${shown} isn't in the workspace, and disk couldn't be checked: ${sentence(note ?? 'not observed')}${on !== null ? ` ${on[0]!.toUpperCase()}${sentence(on.slice(1))}` : ''}`;
 }
 
 function namesRoot(path: string, mount: string): string {
@@ -6887,16 +6911,16 @@ function readRefusal(err: WorkspaceReadError, path: string): string {
     }
     return `${shown} can't be read: ${sentence(err.reason)}`;
   }
-  if (err.stage === 'readlink') return sentence(err.message);
+  if (err instanceof LinkOnTheWay) return `${shown} can't be reached: ${sentence(err.reason)}`;
   switch (err.code) {
     case 'directory':
       return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
     case 'symlink':
       return `${shown} is a symlink, and its mount doesn't follow symlinks, so the workspace's tools don't go through it. `
-        + 'Calling again won\'t change that; if you know the file it leads to, name that file by its own path.';
+        + `Calling again won't change that; ${UNFOLLOWED_STEP}.`;
     case 'escape':
       return `${shown} leads through a symlink to a place outside its mount, so the workspace's tools don't reach it. `
-        + 'Calling again won\'t change that; if a mount holds that file, name it by its path there.';
+        + `Calling again won't change that; ${MOUNT_IT}.`;
     case 'changed':
       return `${shown} changed on disk while it was being read. Calling again reads it afresh.`;
     case 'not_found':
@@ -6970,7 +6994,7 @@ function remedyOfLost(lost: LostContents): string {
  */
 function headMoveText(mounts: readonly string[]): string {
   const one = mounts.length === 1;
-  return `[workspace] Writes to ${listed(mounts.map((name) => `\`${name}\``))} from turns the history no longer holds are still on disk. `
+  return `[${NOTICE_TAG.workspace}] Writes to ${listed(mounts.map((name) => `\`${name}\``))} from turns the history no longer holds are still on disk. `
     + `If ${one ? "it's a git checkout" : "they're git checkouts"}, \`git status\` and \`git diff\` show them; `
     + 'a `git checkout` of a file drops every unstaged change in it, including the ones the history still holds.';
 }