@animalabs/agent-framework 0.27.0 → 0.29.0

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

@@ -4,15 +4,16 @@
  * Provides a unified workspace with mount-based filesystem access,
  * 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 { open, readdir, readlink, stat, lstat, realpath } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, parse, resolve, relative, sep } from 'node:path';
 import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher } from './watcher.js';
-import { hashContent, DEFAULT_MAX_FILE_SIZE } from './sync.js';
-import { DiskAgreement, sameRootIdentity } from './disk-agreement.js';
+import { hashContent, storedBytes, DEFAULT_MAX_FILE_SIZE } from './sync.js';
+import { DiskAgreement, EvidenceUnavailable, callGate, sameRootIdentity } from './disk-agreement.js';
 import { BranchIntents } from './branch-intent.js';
-import { IGNORED, NONBLOCK, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beginsWithDir, checkDir, checkRoot, coversLanding, diskSpelling, filesystemTrustsCtime, foldsCase, includePatternReadable, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, namesNestedPlace, nestedAtReal, nestedHolder, observePath, parsedSpelling, passedOverAt, pathSegments, readBytes, readPrefix, shownLeads, sniffImageMime, walkScope, withinIncludes } from './observe.js';
+import { CHANGED, 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, restBeneath, rootAbsence, sameRoot, shownLeads, sniffImageMime, surelyAtRoot, walkScope, withinIncludes } 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 { countBudget, decodeForEdit, hintBudget, planFile } from './edit-plan.js';
@@ -20,10 +21,13 @@ import { cutLine, editList, editReceipt, fitted, refusalText } from './edit-text
 import { fileText } from './text.js';
 import { DEFAULT_READ_LINE_LIMIT, characterPage, linePage } from './read-page.js';
 import { grepText, textAnswer } from './result-text.js';
-import { NOT_PUSHED_IN_OTHER_MOUNT, WALK_CAP, entryMode, pushPaths, reconcilePass, settleAdoptionBeforeMutation, } from './reconcile.js';
+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, 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';
-import { FileChanged, ROOT_MOVED, checkUnchanged, directWriteTestSeam, discard, identityOf, placedStill, renameInto, sameIdentity, stageContained, } from './direct-write.js';
+import { FileChanged, ROOT_MOVED, WriteRefused, checkUnchanged, directWriteTestSeam, discard, identityOf, placedStill, renameInto, sameIdentity, stageContained, } from './direct-write.js';
 /** Default for how long the after-batch scan may hold the agent's next inference. */
 const AGENT_ACTION_SCAN_DEADLINE_MS = 20_000;
 /**
@@ -42,6 +46,9 @@ const BRANCH_LEFT = 'the workspace had left the branch this file is for';
 const AGENT_ACTION_SCAN_DEADLINE_MAX_MS = TOOL_BATCH_HOOK_TIMEOUT_MS - 1_000;
 /** A direct mount's ignore list when its config names none (MountConfig.ignore). */
 const DIRECT_MOUNT_IGNORE = ['node_modules', 'dist', '.git', 'build', 'coverage', 'target', '__pycache__', '.venv'];
+const PATTERN_FORMS = 'The list reads these of gitignore\'s forms: a name, matched at any depth, with "*" and "?" within it; '
+    + 'a trailing "/" to match only directories; a leading or inner "/" for a path from the mount\'s root; '
+    + 'a leading "**/" before one name; and a trailing "/**" for what lies beneath a directory.';
 /**
  * How many files a direct mount's grep reads, and its listings look at, at
  * once. Over a layout of seven checkouts, 5,929 files, a direct grep reading
@@ -54,16 +61,23 @@ const DIRECT_READS_AT_ONCE = 16;
 const DIRECT_SYNC_SKIPPED = "a direct mount: its tools read disk as it is, so there's nothing to take in";
 /** Why materialize passes over a writable direct mount, as its result's `skipped` says. */
 const DIRECT_MATERIALIZE_SKIPPED = "a direct mount: its writes are on disk as they're made, so there's nothing to write";
-class WorkspaceImageReadError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
+class WorkspaceImageReadError extends Refusal {
+    reason;
+    constructor(reason, wayOn) {
+        super(wayOn === null ? sentence(reason) : `${reason}. ${wayOn}`);
+        this.reason = reason;
         this.name = 'WorkspaceImageReadError';
     }
 }
+const IMAGE_STAYS = "Calling again won't change that; only a whole image in its place would.";
+function truncatedImage(mountPrefixedPath) {
+    return new WorkspaceImageReadError(`${JSON.stringify(mountPrefixedPath)} is too short to be an image: it ends inside an image format's signature`, IMAGE_STAYS);
+}
+function emptyImage(mountPrefixedPath) {
+    return new WorkspaceImageReadError(`${JSON.stringify(mountPrefixedPath)} is empty, so there's no image in it`, IMAGE_STAYS);
+}
 /** A path the mount's `include` doesn't cover: outside the mount. */
-class OutsideIncludeError extends Error {
+class OutsideIncludeError extends Refusal {
     constructor(shownPath, mount) {
         super(`"${shownPath}" is outside the mount's include: mount "${mount.name}" holds only ${(mount.include ?? []).join(', ')}. `
             + 'The host\'s operator sets the include in the mount\'s configuration, so calling again with this path changes nothing.');
@@ -74,9 +88,17 @@ class OutsideIncludeError extends Error {
  * mount it names. The message names the mount that holds it and the path to
  * use there.
  */
-class NestedMountError extends Error {
-    constructor(path, mount, holder, use, how = 'lies in') {
-        super(`"${path}" ${how} mount "${holder}", nested in mount "${mount}", which neither reads nor writes it: use "${use}".`);
+class NestedMountError extends Refusal {
+    constructor(path, mount, holder, how = 'lies in') {
+        const verb = holder.guess === undefined ? how : how === 'lies in' ? 'may lie in' : 'may lead into';
+        super(`"${path}" ${verb} mount "${holder.name}", nested in mount "${mount}", which neither reads nor writes it: ${nestedStep(holder, { named: how === 'lies in' })}.`);
+    }
+}
+class PathRefusal extends Refusal {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
     }
 }
 /**
@@ -98,37 +120,46 @@ export class WorkspaceReadError extends Error {
         this.name = 'WorkspaceReadError';
     }
 }
+class NotRegularFile extends WorkspaceReadError {
+    constructor(path, stage) {
+        super('not_found', `Not a regular file: ${path}`, stage);
+    }
+}
+class LinkOnTheWay extends WorkspaceReadError {
+    reason;
+    constructor(code, message, reason, errno) {
+        super(code, message, 'readlink', errno);
+        this.reason = reason;
+    }
+}
+class RootUnavailable extends WorkspaceReadError {
+    mount;
+    reason;
+    refusal;
+    constructor(mount, reason, stage, errno, refusal) {
+        super('mount_unavailable', reason === null ? `Mount unavailable: ${mount}` : `Mount unavailable: ${mount}: ${reason}`, stage, errno);
+        this.mount = mount;
+        this.reason = reason;
+        this.refusal = refusal;
+    }
+}
 /**
  * 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) {
-    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) {
     return typeof err === 'object' && err !== null && 'code' in err && typeof err.code === 'string'
         ? err.code
         : undefined;
 }
-/**
- * What is at a mount root's path now, followed as the root is: for a
- * directory, undefined; for anything else, ENOTDIR; and where the path
- * can't be followed to anything, the errno its stat failed with, ENOENT
- * when nothing is there.
- */
-async function rootAbsence(root) {
-    try {
-        return (await stat(root)).isDirectory() ? undefined : 'ENOTDIR';
-    }
-    catch (err) {
-        return errnoOf(err);
-    }
-}
 /** read_image's refusal of a file over the mount's size limit, wherever it's found to be. */
-function imageTooLarge(maxSize, mountPrefixedPath) {
-    return new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
+function imageTooLarge(maxSize, mountPrefixedPath, size) {
+    return new WorkspaceImageReadError(pastSizeLimit(`${JSON.stringify(mountPrefixedPath)} is ${size} bytes`, maxSize, "read_image doesn't show it", null), null);
 }
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]);
@@ -144,9 +175,6 @@ const JPEG_SOI = 0xd8;
 const JPEG_EOI = 0xd9;
 const JPEG_SOS = 0xda;
 const JPEG_TEM = 0x01;
-function isErrnoCode(err, code) {
-    return typeof err === 'object' && err !== null && 'code' in err && err.code === code;
-}
 function startsWithBytes(buffer, prefix) {
     return buffer.length >= prefix.length && buffer.subarray(0, prefix.length).equals(prefix);
 }
@@ -174,15 +202,16 @@ function matchesPartialPrefix(buffer, prefix) {
  */
 async function linkReadError(mount, found, mountPrefixedPath, relativePath, nested, rootReal) {
     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, holder) ? 'other_mount'
+        : 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);
 }
 /**
  * `to` beneath `from`, mount-relative and `/`-separated, whatever the
@@ -211,28 +240,27 @@ function ancestorsOf(path) {
  * directory as configured beneath the outer mount's configured path
  * (`outerPath`), beneath each directory above its configured path that is
  * the outer root on disk (`above`, each with where it lies on disk), and
- * where its real root (`real`) lies beneath the outer root (`outerReal`),
- * each also as disk spells it beneath `spellAt`. Its real root is claimed
- * where it doesn't hold the outer root, which it would otherwise claim
- * whole. Undefined where it's nested nowhere.
+ * where its real root (`real`) lies beneath the outer root (`outerReal`).
+ * Its real root is claimed where it doesn't hold the outer root, which it
+ * would otherwise claim whole. Undefined where it's nested nowhere.
  */
-async function placementOf(outerPath, outerReal, innerPath, real, above, spellAt) {
+function placementOf(outerPath, outerReal, innerPath, real, above) {
     const configured = nestedDir(outerPath, innerPath);
-    const throughRoot = above.filter((a) => a.real === outerReal).map((a) => nestedDir(a.dir, innerPath));
-    const fromRoots = [];
-    for (const dir of [configured, ...throughRoot, nestedDir(outerReal, real)]) {
-        if (dir !== undefined && !fromRoots.some((s) => s.dir === dir))
-            fromRoots.push({ dir, root: join(outerPath, ...dir.split('/')) });
-    }
-    if (fromRoots.length === 0)
+    const dirs = new Map();
+    const place = (dir, sure) => { if (dir !== undefined)
+        dirs.set(dir, (dirs.get(dir) ?? false) || sure); };
+    place(configured, true);
+    for (const a of above) {
+        if (sameRoot(a.real, outerReal))
+            place(nestedDir(a.dir, innerPath), surelyAtRoot(a.real, outerReal));
+    }
+    const below = beneathRoot(real, outerReal);
+    place(below, below !== undefined && surelyAtRoot(real, outerReal));
+    if (dirs.size === 0)
         return undefined;
-    const spellings = [...fromRoots];
-    for (const found of fromRoots) {
-        const dir = await diskSpelling(spellAt, found.dir);
-        if (!spellings.some((s) => s.dir === dir))
-            spellings.push({ dir, root: join(outerPath, ...dir.split('/')) });
-    }
-    return { configured, fromRoots, spellings, claims: !isContainedPath(real, outerReal) };
+    const fromRoots = [...dirs].map(([dir, sure]) => ({ dir, ...(sure ? {} : { guessed: true }) }));
+    const claims = !sameRoot(outerReal, real) && beneathRoot(outerReal, real) === undefined;
+    return { configured, fromRoots, claims };
 }
 /** How many links realBeneath follows to a place not made yet before it stops, as the kernel's limit does. */
 const LINKS_FOLLOWED = 40;
@@ -298,7 +326,7 @@ function isContainedPath(root, candidate) {
     return candidate.startsWith(normalizedRoot);
 }
 function invalidImage(format, mountPrefixedPath) {
-    throw new WorkspaceImageReadError('invalid', `Invalid ${format} image: ${mountPrefixedPath}`);
+    throw new WorkspaceImageReadError(`${JSON.stringify(mountPrefixedPath)} starts as a ${format} image, but its data doesn't hold together as one`, IMAGE_STAYS);
 }
 function requireBufferRange(bytes, start, length, format, mountPrefixedPath) {
     if (start < 0 || length < 0 || start + length > bytes.length) {
@@ -634,21 +662,21 @@ function detectImageMimeType(bytes, mountPrefixedPath) {
         return 'image/png';
     }
     if (matchesPartialPrefix(bytes, PNG_SIGNATURE)) {
-        throw new WorkspaceImageReadError('truncated', `Truncated image signature: ${mountPrefixedPath}`);
+        throw truncatedImage(mountPrefixedPath);
     }
     if (startsWithBytes(bytes, JPEG_SIGNATURE)) {
         validateJpeg(bytes, mountPrefixedPath);
         return 'image/jpeg';
     }
     if (matchesPartialPrefix(bytes, JPEG_SIGNATURE)) {
-        throw new WorkspaceImageReadError('truncated', `Truncated image signature: ${mountPrefixedPath}`);
+        throw truncatedImage(mountPrefixedPath);
     }
     if (startsWithBytes(bytes, GIF87A_SIGNATURE) || startsWithBytes(bytes, GIF89A_SIGNATURE)) {
         validateGif(bytes, mountPrefixedPath);
         return 'image/gif';
     }
     if (matchesPartialPrefix(bytes, GIF87A_SIGNATURE) || matchesPartialPrefix(bytes, GIF89A_SIGNATURE)) {
-        throw new WorkspaceImageReadError('truncated', `Truncated image signature: ${mountPrefixedPath}`);
+        throw truncatedImage(mountPrefixedPath);
     }
     if (bytes.length >= 12 && startsWithBytes(bytes, RIFF_SIGNATURE) && bytes.subarray(8, 12).equals(WEBP_SIGNATURE)) {
         validateWebp(bytes, mountPrefixedPath);
@@ -656,9 +684,9 @@ function detectImageMimeType(bytes, mountPrefixedPath) {
     }
     if ((bytes.length < RIFF_SIGNATURE.length && matchesPartialPrefix(bytes, RIFF_SIGNATURE))
         || (bytes.length >= RIFF_SIGNATURE.length && startsWithBytes(bytes, RIFF_SIGNATURE) && bytes.length < 12)) {
-        throw new WorkspaceImageReadError('truncated', `Truncated image signature: ${mountPrefixedPath}`);
+        throw truncatedImage(mountPrefixedPath);
     }
-    throw new WorkspaceImageReadError('unsupported', `Unsupported image format: ${mountPrefixedPath}`);
+    throw new WorkspaceImageReadError(`${JSON.stringify(mountPrefixedPath)} isn't a PNG, JPEG, GIF or WebP image, the formats read_image shows`, "read shows it, if it's text.");
 }
 export class WorkspaceModule {
     name = 'workspace';
@@ -684,14 +712,11 @@ export class WorkspaceModule {
     ctimeTrust = new Map();
     /**
      * Each mount's directories that are other mounts nested inside it, with
-     * each mount's name and real root, in each spelling that names the
-     * directory: as configured; as the real roots place it, where that differs
-     * (`fromRoots`); and as disk spells each of those where that differs.
-     * Each spelling is mount-relative and `/`-separated, with its root beneath
-     * the mount's resolved root. The constructor nests by configured path,
-     * with each root as resolved standing for its real one, and each start
-     * reads it all again with the roots placed where disk has them
-     * (readNesting).
+     * each mount's name and real root: as configured, and as the real roots
+     * place it, where that differs (`fromRoots`). Each is mount-relative and
+     * `/`-separated. The constructor nests by configured path, with each root
+     * as resolved standing for its real one, and each start reads it all again
+     * with the roots placed where disk has them (readNesting).
      */
     otherMounts = new Map();
     /** Whether each mount's root folds case (foldsCase), where disk has it, as the last start read it. */
@@ -748,20 +773,19 @@ export class WorkspaceModule {
             if (refused.length > 0) {
                 throw new Error(`[workspace] Mount "${mount.name}" is direct, which reads disk as it is with no store, watcher or push: ${refused.join('; ')}`);
             }
-            const include = mount.include;
-            if (include !== undefined) {
-                // A pattern the matcher can't read would match nothing, and take every
-                // file out of the mount unsaid (includePatternReadable).
-                if (!Array.isArray(include) || include.length === 0) {
-                    throw new Error(`[workspace] Mount "${mount.name}": include must be a non-empty list of names, "*.ext" globs or "dir/**" globs, not ${shownValue(include)}`);
+            for (const list of ['ignore', 'include']) {
+                const patterns = mount[list];
+                if (patterns === undefined)
+                    continue;
+                if (!Array.isArray(patterns) || (list === 'include' && patterns.length === 0)) {
+                    throw new Error(`[workspace] Mount "${mount.name}": ${list} must be a ${list === 'include' ? 'non-empty ' : ''}list of patterns, not ${shownValue(patterns)}`);
                 }
-                // By index: an entry that is itself undefined, or a hole, is unreadable too.
-                const at = include.findIndex((p) => !includePatternReadable(p));
-                if (at >= 0) {
-                    const unreadable = include[at];
-                    throw new Error(`[workspace] Mount "${mount.name}": include must be a non-empty list of names, "*.ext" globs or "dir/**" globs, `
-                        + `with no "." or ".." segment${sep === '\\' ? ' and no "\\", which this platform reads as a separator' : ''}; `
-                        + `${shownValue(unreadable)} is none of these`);
+                for (let i = 0; i < patterns.length; i++) {
+                    const pattern = patterns[i];
+                    const why = patternRefusal(pattern, list);
+                    if (why !== undefined) {
+                        throw new Error(`[workspace] Mount "${mount.name}": ${list} pattern ${shownValue(pattern)} isn't read: ${why}. ${PATTERN_FORMS}`);
+                    }
                 }
             }
         }
@@ -782,8 +806,8 @@ export class WorkspaceModule {
                 const dir = nestedDir(outerPath, innerPath);
                 if (dir === undefined)
                     continue;
-                const configured = [{ dir, root: innerPath }];
-                this.otherMounts.set(outer.name, [...(this.otherMounts.get(outer.name) ?? []), { name: inner.name, real: innerPath, fromRoots: configured, spellings: [...configured] }]);
+                const configured = [{ dir }];
+                this.otherMounts.set(outer.name, [...(this.otherMounts.get(outer.name) ?? []), { name: inner.name, real: innerPath, fromRoots: configured }]);
                 console.warn(`[workspace] Mount "${outer.name}" contains mount "${inner.name}" ` +
                     `at ${dir}/ — passing over it as another mount's directory`);
             }
@@ -1067,7 +1091,7 @@ export class WorkspaceModule {
         const { view, rootReal } = mount.direct ? await this.diskView(mount) : await this.runtime(mount);
         let start = base;
         for (const segment of beneath.split('/')) {
-            if (start !== '' && (mount.direct ? inOtherMount(start, view.others) : passedOverAt(start, view.ignore, view.others) !== undefined))
+            if (start !== '' && (mount.direct ? inOtherMount(start, view.others) : passedOverAt(start, view.ignore, view.others, true) !== undefined))
                 break;
             const here = await checkDir(view, rootReal, start);
             if (here.kind !== 'checked')
@@ -1125,11 +1149,10 @@ export class WorkspaceModule {
     }
     async start(ctx) {
         // Which mounts are nested where, with the roots placed where disk has
-        // them and each nested mount's directory as disk spells it, and whether
-        // each mount's root folds case, read where disk has it, before this start
-        // sets anything, so a restart takes no call and walks or watches nothing
-        // before they're known. A stop begun meanwhile stands, and this start then
-        // sets nothing.
+        // them, and whether each mount's root folds case, read where disk has
+        // it, before this start sets anything, so a restart takes no call
+        // and walks or watches nothing before they're known. A stop begun
+        // meanwhile stands, and this start then sets nothing.
         const stops = this.stopsBegun;
         const { nesting, reals, above } = await this.readNesting();
         const rootFoldsCase = new Map();
@@ -1242,7 +1265,8 @@ export class WorkspaceModule {
         const pinnedName = pinned ? `"${pinned.name}"` : `id ${mount.lastMaterializedBranchId} (branch no longer exists)`;
         return (`current branch "${current.name}" has diverged from the branch last materialized to disk ` +
             `(${pinnedName} at seq ${mount.lastMaterializedSeq}) — disk may hold state the current branch ` +
-            `never had. Pass force: true to overwrite disk from the current branch if it is canonical.`);
+            `never had. ls with path ${JSON.stringify(mount.config.name)} and recursive: true shows how each file of the current branch stands against disk; ` +
+            'if the current branch is what disk should hold, pass force: true to overwrite disk from it.');
     }
     /**
      * Re-pin mounts whose last-materialized branch is a proven ancestor of the
@@ -1866,7 +1890,12 @@ export class WorkspaceModule {
         work.then(done, done);
         return work;
     }
-    async runToolCall(call) {
+    runToolCall(call) {
+        const gate = { passed: false };
+        return callGate.run(gate, () => this.answerToolCall(call, gate));
+    }
+    async answerToolCall(call, gate) {
+        const reopenAtStart = this.agreement?.awaitsReopen === true;
         try {
             // Every handler reads its input as its schema describes it; a call
             // that sends something else is refused here, before anything is read.
@@ -1881,12 +1910,12 @@ export class WorkspaceModule {
             // ResultTooLarge in its place. A call made in process carries none and
             // takes the data itself, so its read pages by its line limit alone.
             const resultMaxChars = call.resultMaxChars;
-            const generated = typeof input?.path === 'string' ? this.findGeneratedTextFile(input.path) : undefined;
+            const generated = schema !== undefined && typeof input?.path === 'string' ? this.findGeneratedTextFile(input.path) : undefined;
             if (generated) {
                 if (call.name === 'read' && call.callerAgentName === generated.agentName) {
                     return await this.handleRead(input, resultMaxChars, generated.read());
                 }
-                return { success: false, isError: true, error: this.generatedFileRefusal(generated, call.callerAgentName) };
+                return { success: false, isError: true, error: didNothing(call.name, this.generatedFileRefusal(input.path, generated, call.callerAgentName)) };
             }
             switch (call.name) {
                 case 'read': return await this.handleRead(input, resultMaxChars);
@@ -1902,12 +1931,40 @@ export class WorkspaceModule {
                 case 'materialize': return await this.handleMaterialize(input);
                 case 'sync': return await this.handleSync(input);
                 default:
-                    return { success: false, error: `Unknown tool: ${call.name}, so nothing was done`, isError: true };
+                    return { success: false, error: unknownToolMessage(this.name, call.name, this.getTools()), isError: true };
             }
         }
         catch (err) {
-            return { success: false, error: err instanceof Error ? err.message : String(err), isError: true };
+            return { success: false, error: this.failureAnswer(call, err, reopenAtStart, gate.passed), isError: true };
+        }
+    }
+    failureAnswer(call, err, reopenAtStart, passedGate) {
+        const input = (typeof call.input === 'object' && call.input !== null ? call.input : {});
+        const path = typeof input.path === 'string' ? input.path : undefined;
+        const mountName = path !== undefined ? path.split('/')[0] : typeof input.mount === 'string' ? input.mount : undefined;
+        const subject = path !== undefined ? JSON.stringify(path) : typeof input.mount === 'string' ? `mount ${JSON.stringify(input.mount)}` : undefined;
+        const reopened = !reopenAtStart && this.agreement?.awaitsReopen === true;
+        if (err instanceof EvidenceUnavailable && passedGate && changesFiles(call.name)) {
+            return `The ${call.name}${subject !== undefined ? ` of ${subject}` : ''} stopped partway: ${err.message} Whether it changed anything before it stopped isn't known until then.`;
+        }
+        if (err instanceof Refusal)
+            return didNothing(call.name, err.message);
+        if (err instanceof WorkspaceReadError)
+            return didNothing(call.name, path !== undefined ? readRefusal(err, path) : sentence(err.message));
+        const look = call.name !== 'materialize' && call.name !== 'sync' ? undefined
+            : mountName !== undefined ? `ls with path ${JSON.stringify(mountName)} and recursive: true shows how each file there stands against disk now`
+                : 'ls of each mount, with recursive: true, shows how each file stands against disk now';
+        if (err instanceof NotStored || err instanceof AlreadyHeld) {
+            console.error(`[workspace] ${call.name} failed before it changed anything:`, err.thrown);
+            return unexpectedAnswer(call.name, subject, err.thrown, { stored: err instanceof NotStored ? 'not' : 'held', reopen: reopened });
+        }
+        console.error(`[workspace] ${call.name} failed:`, err);
+        if (err instanceof CommitUnknownError) {
+            return unexpectedAnswer(call.name, subject, err.setCause, {
+                said: `the store failed as it set the change (${storeWords(err.setCause)}), and reading it back failed too (${storeWords(err.readCause)})`, reopen: reopened, look,
+            });
         }
+        return unexpectedAnswer(call.name, subject, err, { reopen: reopened, look });
     }
     async onProcess(event, _state) {
         // Wake agents on filesystem events when the originating mount opted in.
@@ -1948,14 +2005,14 @@ export class WorkspaceModule {
             return { requestInference: true };
         let text;
         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: ${conflicts.join(', ')}]`;
+            text += `\n[${NOTICE_TAG.conflictsWithDisk}: ${conflicts.join(', ')}; reading each shows how to settle it]`;
         }
         return {
             requestInference: true,
@@ -2003,16 +2060,15 @@ export class WorkspaceModule {
     resolveAbsolutePath(mountPrefixedPath) {
         try {
             // Synchronous, so the path as given. The nested-mount check takes it
-            // in each spelling readNesting knows for the nested mount's directory,
-            // or in any spelling a disk that folds names may fold to one of them,
-            // erring toward that mount (holderOf's asGiven, beginsWithDir). The
-            // include judges it as given, so on a disk that
+            // in any spelling a disk that folds names may fold to the nested
+            // mount's directory, erring toward that mount (holderOf). The include
+            // judges it as given, so on a disk that
             // folds names a covered name whose file disk spells otherwise returns
             // that file's path, which the tools refuse, and a covered file named in
             // another case is null, which the tools read. A path the mount doesn't
             // hold, outside its include or in another mount's directory nested in
             // it, is null, as for a path that leaves the mount's directory.
-            const { mount, relativePath } = this.refuseNotHeld({ ...this.parsePathAsGiven(mountPrefixedPath), path: mountPrefixedPath }, mountPrefixedPath, true);
+            const { mount, relativePath } = this.refuseNotHeld({ ...this.parsePathAsGiven(mountPrefixedPath), path: mountPrefixedPath }, mountPrefixedPath);
             return resolve(mount.config.path, relativePath);
         }
         catch {
@@ -2040,6 +2096,9 @@ export class WorkspaceModule {
      * `agentName` names the agent whose write it is for the head-move notice
      * (a write naming none tells no agent).
      *
+     * A success's `disk` says where the file stands on disk as the workspace
+     * last saw it, as the write tool's answer does.
+     *
      * A write whose tree entry is set but that then fails returns success
      * false with `data: { inChronicle: true }`: its copy on disk was refused,
      * the store failed after recording the entry, which skips the push where
@@ -2067,12 +2126,14 @@ export class WorkspaceModule {
                 isError: true,
             };
         }
-        const refusal = writeRefusal(mount);
+        if (relativePath === '')
+            return { success: false, error: namesRoot(mountPrefixedPath, mount.config.name), isError: true };
+        const refusal = writeRefusal(mount, this.writableNames());
         if (refusal)
             return { success: false, error: refusal, isError: true };
         const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
         if (data.byteLength > maxSize) {
-            return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
+            return { success: false, error: tooLargeToWrite(mountPrefixedPath, data.byteLength, maxSize), isError: true };
         }
         const store = this.getStore();
         // A direct mount's bytes go to disk, whole, or nowhere (writeDirect),
@@ -2087,7 +2148,7 @@ export class WorkspaceModule {
             const written = await this.writeDirect(mount, relativePath, mountPrefixedPath, data, options.agentName, options.branch);
             if ('error' in written)
                 return { success: false, isError: true, error: written.error, ...(written.branchLeft ? { data: { branchLeft: true } } : {}) };
-            return { success: true, data: { path: mountPrefixedPath, size: data.byteLength, mimeType, ...(written.note ? { note: written.note } : {}) } };
+            return { success: true, data: { path: mountPrefixedPath, size: data.byteLength, mimeType, disk: 'done', ...(written.note ? { note: written.note } : {}) } };
         }
         return this.withMount(mount, async () => {
             await this.settleBeforeMutation(mount, relativePath);
@@ -2102,9 +2163,11 @@ export class WorkspaceModule {
             let committed = false;
             let failure;
             let modeKept = null;
+            let disk = null;
             try {
                 const answer = await this.commitToolChange(mount, relativePath, { kind: 'set', blobHash, size: data.byteLength, ...(existing ? { mode: existing.mode } : {}) }, () => { committed = true; });
                 modeKept = answer.modeKept;
+                disk = answer.disk;
                 failure = answer.refused === null ? null
                     : `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${answer.refused}.`;
             }
@@ -2113,10 +2176,13 @@ export class WorkspaceModule {
                     throw error;
                 // As write words it: a store that failed after recording the file
                 // skipped its push, so on a mount that pushes, disk lacks it.
+                const reopen = this.agreement?.awaitsReopen === true;
                 failure = error instanceof StoredThenFailed
                     ? `Stored "${mountPrefixedPath}" in Chronicle, but the store failed after recording it: ${error.message}.`
-                        + (error.pushes ? " Its push to disk didn't run, so disk lacks the change until a materialize of the path writes it." : '')
+                        + (error.pushes ? ` Its push to disk didn't run, so disk lacks the change until a materialize of the path writes it${reopen ? ONCE_REOPENED : ''}.` : '')
                     : `Stored "${mountPrefixedPath}" in Chronicle, but the rest of the write failed: ${error instanceof Error ? error.message : String(error)}.`;
+                if (reopen)
+                    failure += ` ${AWAITS_REOPEN}`;
             }
             if (failure !== null) {
                 // The file is in the Chronicle tree, where the workspace's tools read
@@ -2126,7 +2192,7 @@ export class WorkspaceModule {
             }
             return {
                 success: true,
-                data: { path: mountPrefixedPath, size: data.byteLength, mimeType, ...(modeKept ? { modeKept } : {}) },
+                data: { path: mountPrefixedPath, size: data.byteLength, mimeType, disk, ...(modeKept ? { modeKept } : {}) },
             };
         });
     }
@@ -2162,12 +2228,13 @@ export class WorkspaceModule {
         return this.withMount(mount, async () => {
             const { report, undecided } = await this.ensureSynced(mount, relativePath);
             const entry = store.treeGet(mount.treeStateId, relativePath);
-            if (!entry)
-                return { error: undecided !== null ? this.notCheckedYet(mountPrefixedPath, undecided) : this.notInWorkspace(mountPrefixedPath, report) };
-            const blob = store.getBlob(entry.blobHash);
-            if (!blob)
-                return { error: `Blob not found for: ${mountPrefixedPath}` };
-            return { data: blob };
+            if (!entry) {
+                return { error: undecided !== null ? this.notCheckedYet(mountPrefixedPath, undecided) : this.notInWorkspace(mountPrefixedPath, report, mount, `File not found: ${mountPrefixedPath}`) };
+            }
+            const contents = await this.contentsOf(mount, relativePath, mountPrefixedPath, entry);
+            if ('lost' in contents)
+                return { error: nothingToRead(contents.lost) };
+            return { data: contents.bytes };
         });
     }
     /**
@@ -2245,9 +2312,9 @@ export class WorkspaceModule {
             return { error: error instanceof Error ? error.message : String(error) };
         }
     }
-    /** The directories of the mounts nested inside a mount, mount-relative, in each spelling. */
+    /** The directories of the mounts nested inside a mount, mount-relative. */
     othersOf(mountName) {
-        return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => s.dir));
+        return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.fromRoots.map((s) => s.dir));
     }
     /**
      * Which mounts are nested in which, read afresh at each start. A mount is
@@ -2262,13 +2329,8 @@ export class WorkspaceModule {
      * alone, with no real root, since through it it would claim the other's
      * every path.
      *
-     * Each way it lies there is a spelling of its directory (`fromRoots`), and
-     * so is the spelling disk lists each of those by, where that differs. On a
-     * disk that folds names, the outer mount's walks name the directory as
-     * disk does, and so does a path parsePath has respelled, while a path given
-     * as configured still names it as configured (resolveAbsolutePath). A
-     * directory not on disk keeps the spellings the roots give alone. Each
-     * mount's real root comes back beside the nesting (`reals`), for what
+     * Each way it lies there is a spelling of its directory (`fromRoots`).
+     * Each mount's real root comes back beside the nesting (`reals`), for what
      * start reads there, and each directory above each configured path with
      * where it lies on disk (`above`), for a direct mount whose root moves
      * (movedNesting).
@@ -2295,15 +2357,16 @@ export class WorkspaceModule {
                 if (outer === inner)
                     continue;
                 const real = reals.get(inner.name);
-                const at = await placementOf(outerPath, outerReal, resolve(inner.path), real, above.get(inner.name), outerPath);
+                const at = placementOf(outerPath, outerReal, resolve(inner.path), real, above.get(inner.name));
                 if (at === undefined)
                     continue;
-                const { configured, fromRoots, spellings, claims } = at;
-                nesting.set(outer.name, [...(nesting.get(outer.name) ?? []), { name: inner.name, ...(claims ? { real } : {}), fromRoots, spellings }]);
+                const { configured, fromRoots, claims } = at;
+                nesting.set(outer.name, [...(nesting.get(outer.name) ?? []), { name: inner.name, ...(claims ? { real } : {}), fromRoots }]);
                 const placed = fromRoots.filter((s) => s.dir !== configured);
                 if (placed.length > 0) {
-                    console.warn(`[workspace] Mount "${outer.name}" contains mount "${inner.name}" where it lies on disk, ` +
-                        `at ${placed.map((s) => `${s.dir}/`).join(' and ')} — passing over it as another mount's directory`);
+                    const at = (sure) => placed.filter((s) => !s.guessed === sure).map((s) => `${s.dir}/`).join(' and ');
+                    const where = [at(true) && `where it lies on disk, at ${at(true)}`, at(false) && `where it may lie on disk, at ${at(false)}`].filter(Boolean).join(', and ');
+                    console.warn(`[workspace] Mount "${outer.name}" contains mount "${inner.name}" ${where} — passing over it as another mount's directory`);
                 }
             }
         }
@@ -2311,10 +2374,10 @@ export class WorkspaceModule {
     }
     /**
      * The mounts nested in `mountName`, by directory, name, real root where it
-     * has one, and include (MountView's `nested`), in each spelling known.
+     * has one, and include (MountView's `nested`).
      */
     nestedOf(mountName) {
-        return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => ({ dir: s.dir, name: o.name, real: o.real, include: this.mounts.get(o.name)?.config.include })));
+        return (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.fromRoots.map((s) => ({ dir: s.dir, ...(s.guessed ? { guessed: s.guessed } : {}), name: o.name, real: o.real, include: this.mounts.get(o.name)?.config.include })));
     }
     /**
      * The mounts nested in `mount` as a call of it that resolved its root to
@@ -2416,12 +2479,13 @@ export class WorkspaceModule {
                     continue;
                 above = placedAbove.get(inner.name) ?? [];
             }
-            const at = await placementOf(outerPath, rootReal, innerPath, real, above, rootReal);
+            const at = placementOf(outerPath, rootReal, innerPath, real, above);
             if (at === undefined)
                 continue;
             const include = this.mounts.get(inner.name)?.config.include;
-            for (const s of at.spellings)
-                nested.push({ dir: s.dir, name: inner.name, ...(at.claims ? { real } : {}), include });
+            for (const s of at.fromRoots) {
+                nested.push({ dir: s.dir, ...(s.guessed ? { guessed: s.guessed } : {}), name: inner.name, ...(at.claims ? { real } : {}), include });
+            }
         }
         return nested;
     }
@@ -2430,15 +2494,9 @@ export class WorkspaceModule {
      * of that mount, judged lexically where the path lands (`.`, `..` and
      * repeated separators resolved, as for the traversal guard; a link of the
      * outer mount isn't followed), with the path to use there; undefined when
-     * no nested mount's directory holds it. A path parsePath has respelled is
-     * compared with the directory's spellings exactly. One judged as given
-     * (`asGiven`, resolveAbsolutePath's) is compared loosely, as a disk that
-     * folds names may compare it (beginsWithDir), so it can't reach that
-     * mount's directory by spelling a segment otherwise. On a disk that tells
-     * names apart, that takes a directory of this mount's own spelled like the
-     * nested one in another way as that mount's too.
+     * no nested mount's directory holds it.
      */
-    holderOf(mountName, relativePath, asGiven = false, moved = null) {
+    holderOf(mountName, relativePath, moved = null) {
         const mount = this.mounts.get(mountName);
         if (!mount)
             return undefined;
@@ -2446,20 +2504,15 @@ export class WorkspaceModule {
         const resolved = resolve(root, relativePath);
         if (!isContainedPath(root, resolved))
             return undefined;
-        const segments = resolved === root ? [] : relative(root, resolved).split(sep);
+        const path = resolved === root ? '' : relative(root, resolved).split(sep).join('/');
         // A direct mount whose root a call found moved is judged by that call's
         // nesting (movedNesting), each directory beneath its configured path.
-        const dirs = moved !== null
-            ? moved.map((n) => ({ name: n.name, dir: n.dir }))
-            : (this.otherMounts.get(mountName) ?? []).flatMap((o) => o.spellings.map((s) => ({ name: o.name, dir: s.dir })));
-        const holder = dirs
-            .filter((s) => beginsWithDir(segments, s.dir.split('/'), asGiven))
-            .map((s) => ({ name: s.name, depth: s.dir.split('/').length }))
-            .sort((a, b) => b.depth - a.depth)[0];
+        const holder = nestedHolder(path, moved ?? this.nestedOf(mountName));
         if (!holder)
             return undefined;
-        const rest = segments.slice(holder.depth).join('/');
-        return { name: holder.name, use: rest ? `${holder.name}/${rest}` : holder.name };
+        const rest = restBeneath(path, holder);
+        const guess = nestedGuess(mountName, path.split('/'), holder);
+        return { name: holder.name, use: rest ? `${holder.name}/${rest}` : holder.name, ...(guess === undefined ? {} : { guess }) };
     }
     /**
      * Why a mount leaves a path in a nested mount's directory, naming that
@@ -2467,10 +2520,10 @@ export class WorkspaceModule {
      * it; for a listing, whose the path is.
      */
     otherMountNote(mountName, relativePath, by, moved = null) {
-        const holder = this.holderOf(mountName, relativePath, false, moved);
+        const holder = this.holderOf(mountName, relativePath, moved);
         const what = by === 'sync' ? ', which no sync of this mount takes in' : by === 'push' ? ', which no push of this mount writes' : '';
         return holder
-            ? `it lies in mount "${holder.name}", nested in this one${what}: use "${holder.use}"`
+            ? `it ${holder.guess === undefined ? 'lies' : 'may lie'} in mount "${holder.name}", nested in this one${what}: ${nestedStep(holder)}`
             : `it lies in another mount's directory${what}`;
     }
     /**
@@ -2489,7 +2542,7 @@ export class WorkspaceModule {
         // Both checks judge by the nesting the parse found, and the second reads
         // disk beneath the root the parse resolved.
         const { mount, root, moved } = spelled;
-        const parsed = this.refuseNotHeld(spelled, path, false, moved);
+        const parsed = this.refuseNotHeld(spelled, path, moved);
         // A path can also reach a nested mount's directory, or a file this
         // mount's own include leaves out, through a symlink on its way. No push
         // of this mount writes it there and no read reads it, so it's refused
@@ -2531,7 +2584,9 @@ export class WorkspaceModule {
         // whatever the place realpath stopped short of would say.
         if (judged && unresolved.code !== undefined)
             return new WorkspaceReadError('not_found', `Unable to resolve file: ${path}`, 'realpath', unresolved.code);
-        const holder = nestedAtReal(real, nested);
+        let holder = await nestedAtReal(real, nested);
+        if (holder?.guess === null)
+            holder = await nestedAtReal(real, nested, { name: mount.config.name, rootReal: await realBeneath(resolve(mount.config.path)) });
         if (!holder) {
             if (!judged)
                 return null;
@@ -2550,26 +2605,25 @@ export class WorkspaceModule {
         // on the place's way as that mount's, so a place beneath anything else
         // there, such as a file the include leaves out, isn't named; one beneath
         // a directory not there yet is.
-        const onItsWay = holder.include === undefined
+        const onItsWay = !holder.judgedByInclude
             || await stat(dirname(real)).then((info) => info.isDirectory(), (err) => errnoOf(err) === 'ENOENT');
-        const directory = holder.include !== undefined && await stat(real).then((info) => info.isDirectory(), () => false);
-        if (!onItsWay || !namesNestedPlace(holder.rest, holder.include, directory))
+        const directory = holder.judgedByInclude && await stat(real).then((info) => info.isDirectory(), () => false);
+        if (!onItsWay || !holder.names(directory))
             return new WorkspaceReadError('escape', `Symlink escape detected: ${path}`, 'realpath');
-        return new NestedMountError(path, mount.config.name, holder.name, holder.use, 'leads into');
+        return new NestedMountError(path, mount.config.name, holder, 'leads into');
     }
     /**
      * A parsed path, refused where the mount doesn't hold it: in a nested
      * mount's directory first, naming the mount that holds it, then outside
      * the mount's include. Each is judged on the path as the caller parsed it:
      * as disk spells it for parseFilePath, as given for resolveAbsolutePath,
-     * which is synchronous and says so (`asGiven`, so the nested-mount check
-     * folds where disk does). The include's refusal shows the path as given
+     * which is synchronous. The include's refusal shows the path as given
      * (`given`), since it answers the path the caller asked about.
      */
-    refuseNotHeld(parsed, given, asGiven = false, moved = null) {
-        const holder = this.holderOf(parsed.mount.config.name, parsed.relativePath, asGiven, moved);
+    refuseNotHeld(parsed, given, moved = null) {
+        const holder = this.holderOf(parsed.mount.config.name, parsed.relativePath, moved);
         if (holder)
-            throw new NestedMountError(parsed.path, parsed.mount.config.name, holder.name, holder.use);
+            throw new NestedMountError(parsed.path, parsed.mount.config.name, holder);
         if (!insideMount(parsed.relativePath, parsed.mount.config.include)) {
             throw new OutsideIncludeError(given, parsed.mount.config);
         }
@@ -2615,7 +2669,7 @@ export class WorkspaceModule {
      * parse resolved (`root`), by the nesting there (`moved`, movedNesting).
      */
     async refusesAsOutside(mount, relativePath, moved, root) {
-        if (this.holderOf(mount.config.name, relativePath, false, moved))
+        if (this.holderOf(mount.config.name, relativePath, moved))
             return false;
         if (insideMount(relativePath, mount.config.include))
             return false;
@@ -2690,20 +2744,12 @@ export class WorkspaceModule {
     }
     /**
      * How many segments the innermost nested mount's directory that holds
-     * `relativePath` has, in a spelling it's known by (othersOf), or, for a
-     * direct mount whose root has moved, in the nesting there (`moved`);
+     * `relativePath` has, or, for a direct mount whose root has moved, in the
+     * nesting there (`moved`);
      * undefined when no nested mount's directory holds it.
      */
     nestedDepth(mountName, relativePath, moved = null) {
-        let depth;
-        for (const dir of moved?.map((n) => n.dir) ?? this.othersOf(mountName)) {
-            if (relativePath !== dir && !relativePath.startsWith(`${dir}/`))
-                continue;
-            const segments = dir.split('/').length;
-            if (depth === undefined || segments > depth)
-                depth = segments;
-        }
-        return depth;
+        return nestedHolder(relativePath, moved ?? this.nestedOf(mountName))?.dir.split('/').length;
     }
     /**
      * A mount's entries on the current branch, and the paths it records an
@@ -2725,11 +2771,7 @@ export class WorkspaceModule {
             // Only an entry this mount's include covers spells a draft's path
             // (insideMount): not a key no spelling names, such as `c/` or `a//b.txt`
             // from an earlier version, nor one the include leaves out, which would
-            // respell a covered draft into a name the include leaves out. An entry
-            // in a nested mount's directory that this mount's include covers
-            // spells one whatever that mount's include says, so on a disk that
-            // folds names, a draft naming the directory in another spelling takes
-            // the entry's spelling and is judged as in it.
+            // respell a covered draft into a name the include leaves out.
             under: (prefix) => store.treeList(mount.treeStateId, prefix).map((entry) => entry.path).filter((path) => insideMount(path, mount.config.include)),
             holder: (path) => this.holderOf(mount.config.name, path)?.name,
             rootFoldsCase: this.rootFoldsCase.get(mount.config.name) ?? false,
@@ -2754,25 +2796,25 @@ export class WorkspaceModule {
         // A file's name on disk is UTF-8, which can't hold a lone surrogate: the
         // store would keep one name and disk another.
         if (LONE_SURROGATE.test(path)) {
-            throw new Error(`The path ${JSON.stringify(path)} holds a lone UTF-16 surrogate, which UTF-8 can't store, so no file on disk can have that name. Nothing was done.`);
+            throw new PathRefusal('traversal', `${JSON.stringify(path)} holds a lone UTF-16 surrogate, which UTF-8 can't store, so no file on disk can have that name. Give the name without it.`);
         }
         const slashIdx = path.indexOf('/');
         const mountName = slashIdx >= 0 ? path.slice(0, slashIdx) : path;
         const given = slashIdx >= 0 ? path.slice(slashIdx + 1) : '';
         const mount = this.mounts.get(mountName);
-        if (!mount) {
-            throw new Error(`Unknown mount: "${mountName}". Available: ${[...this.mounts.keys()].join(', ')}`);
-        }
+        if (!mount)
+            throw new PathRefusal('unknown_mount', this.noSuchMount(path, mountName));
         const segments = pathSegments(given);
         if (given.startsWith('/') || (sep === '\\' && given.startsWith('\\'))) {
-            throw new Error(`Path traversal detected: "${path}" has a separator right after mount "${mountName}", which makes it an absolute path: give it from the mount's root.`);
+            throw new PathRefusal('traversal', `${JSON.stringify(path)} has a separator right after mount "${mountName}", which makes it an absolute path: give it from the mount's root, as "${mountName}/<path>".`);
         }
         const kept = [];
         for (const segment of segments) {
             if (segment !== '..')
                 kept.push(segment);
             else if (kept.pop() === undefined) {
-                throw new Error(`Path traversal detected: "${path}" climbs above the root of mount "${mountName}".`);
+                throw new PathRefusal('traversal', `${JSON.stringify(path)} climbs above the root of mount "${mountName}" with "..", and a path can't leave its mount. `
+                    + `Name a file from its own mount's name; ${this.mountList()}.`);
             }
         }
         const relativePath = kept.join('/');
@@ -2786,10 +2828,47 @@ export class WorkspaceModule {
         const root = resolve(mount.config.path);
         const resolved = resolve(root, relativePath);
         if (!isContainedPath(root, resolved)) {
-            throw new Error(`Path traversal detected: "${path}" resolves outside mount "${mountName}"`);
+            throw new PathRefusal('traversal', `${JSON.stringify(path)} resolves outside mount "${mountName}", as a drive or root named in it does: give the path from the mount's root, as "${mountName}/<path>".`);
         }
         return { mount, relativePath };
     }
+    writableNames() {
+        return [...this.mounts.values()].filter((m) => writeRefusal(m) === null).map((m) => m.config.name);
+    }
+    mountList() {
+        const names = [...this.mounts.keys()];
+        return names.length === 0 ? 'this workspace has no mounts' : `the mounts are ${listed(names.map((name) => JSON.stringify(name)))}`;
+    }
+    emptyPathField(mount, bare) {
+        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}.`;
+    }
+    noSuchMountField(given, bare) {
+        const [close] = closestNames(given, [...this.mounts.keys()], 1);
+        return `"mount" is ${JSON.stringify(given)}, which is no mount's name; ${this.mountList()}.`
+            + (close !== undefined ? ` Did you mean ${JSON.stringify(close)}?` : '')
+            + ` Leaving "mount" out ${bare}.`;
+    }
+    noSuchMount(path, mountName) {
+        const names = [...this.mounts.keys()];
+        const rest = path.slice(mountName.length);
+        const unslashed = path.replace(/^[/\\]+/, '');
+        if (unslashed !== path && names.some((name) => unslashed === name || unslashed.startsWith(`${name}/`))) {
+            return `${JSON.stringify(path)} starts with "/", and a path starts with its mount's name: give ${JSON.stringify(unslashed)}.`;
+        }
+        if (mountName === '')
+            return `${JSON.stringify(path)} doesn't start with a mount's name, and a path starts with its mount's name; ${this.mountList()}.`;
+        const [close] = closestNames(mountName, names, 1);
+        const said = rest === '' ? `${JSON.stringify(path)} is no mount's name; ${this.mountList()}.`
+            : `${JSON.stringify(path)} starts with ${JSON.stringify(mountName)}, which is no mount's name, and a path starts with its mount's name; ${this.mountList()}.`;
+        return said + (close !== undefined ? ` Did you mean ${JSON.stringify(close + rest)}?` : '');
+    }
     /**
      * Whether the module takes work: stop hasn't finished. Work admitted while
      * stop drains still runs; once stop has saved the pins and watermarks,
@@ -2808,25 +2887,23 @@ export class WorkspaceModule {
     }
     validateImageBytes(bytes, mountPrefixedPath, maxSize) {
         if (bytes.byteLength === 0) {
-            throw new WorkspaceImageReadError('empty', `Image file is empty: ${mountPrefixedPath}`);
+            throw emptyImage(mountPrefixedPath);
         }
         if (bytes.byteLength > maxSize)
-            throw imageTooLarge(maxSize, mountPrefixedPath);
+            throw imageTooLarge(maxSize, mountPrefixedPath, bytes.byteLength.toLocaleString('en-US'));
         return {
             bytes,
             mimeType: detectImageMimeType(bytes, mountPrefixedPath),
         };
     }
-    tryReadImageFromTree(mount, relativePath, mountPrefixedPath, maxSize) {
-        const store = this.getStore();
-        const entry = store.treeGet(mount.treeStateId, relativePath);
+    async readImageFromTree(mount, relativePath, mountPrefixedPath, maxSize) {
+        const entry = this.getStore().treeGet(mount.treeStateId, relativePath);
         if (!entry)
             return null;
-        const blob = store.getBlob(entry.blobHash);
-        if (!blob) {
-            throw new WorkspaceImageReadError('blob_missing', `Blob not found for: ${mountPrefixedPath}`);
-        }
-        return this.validateImageBytes(blob, mountPrefixedPath, maxSize);
+        const contents = await this.contentsOf(mount, relativePath, mountPrefixedPath, entry);
+        if ('lost' in contents)
+            return contents;
+        return this.validateImageBytes(contents.bytes, mountPrefixedPath, maxSize);
     }
     /**
      * The mount root a disk read reads beneath: resolved, then checked as
@@ -2842,20 +2919,14 @@ export class WorkspaceModule {
      * another directory carries none. The identity is rootIdentityForRead's,
      * which answers while the evidence awaits reopening; where even it can't
      * be read, as when the evidence was never read back whole, the read is
-     * refused too, with an errno only where no directory is at the root's path.
+     * refused before its root is resolved, with an errno only where no
+     * directory is at the root's path.
      * A direct mount's root is checked against no identity, and its read reads
      * no evidence: it promises what's at its root now (diskView).
      */
     async readRoot(mount) {
         const name = mount.config.name;
         const root = resolve(mount.config.path);
-        let real;
-        try {
-            real = await realpath(root);
-        }
-        catch (err) {
-            throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${name}`, 'realpath_root', errnoOf(err));
-        }
         let rootIdentity;
         if (!mount.direct) {
             try {
@@ -2864,9 +2935,16 @@ export class WorkspaceModule {
             catch (err) {
                 // The evidence can't be read back, so neither can the check be made.
                 // Where no directory is at the root's path, its errno still says so.
-                throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${name}: ${err instanceof Error ? err.message : String(err)}`, 'root', await rootAbsence(root));
+                throw new RootUnavailable(name, err instanceof Error ? err.message : String(err), 'root', await rootAbsence(root), err instanceof Refusal ? err : undefined);
             }
         }
+        let real;
+        try {
+            real = await realpath(root);
+        }
+        catch (err) {
+            throw new RootUnavailable(name, null, 'realpath_root', errnoOf(err));
+        }
         const checked = await checkRoot(this.viewOf(mount, rootIdentity), real);
         if ('dir' in checked)
             return { real, dir: checked.dir };
@@ -2874,7 +2952,7 @@ export class WorkspaceModule {
         // root's path now decides: nothing, something that isn't a directory, or
         // a directory the path has come to name since it was resolved (no errno).
         const errno = checked.reason === ROOT_REPLACED ? undefined : await rootAbsence(root);
-        throw new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${name}: ${checked.reason}`, 'root', errno);
+        throw new RootUnavailable(name, checked.reason, 'root', errno);
     }
     /**
      * The refusal for a root that stopped being the directory a read checked,
@@ -2888,7 +2966,7 @@ export class WorkspaceModule {
     async rootMoved(mount) {
         const errno = await rootAbsence(resolve(mount.config.path));
         const reason = errno !== undefined ? ROOT_UNAVAILABLE : mount.direct ? DIRECT_ROOT_REPLACED : ROOT_REPLACED;
-        return new WorkspaceReadError('mount_unavailable', `Mount unavailable: ${mount.config.name}: ${reason}`, 'root', errno);
+        return new RootUnavailable(mount.config.name, reason, 'root', errno);
     }
     /**
      * Open a mount-relative file for reading with the mount boundary enforced on
@@ -2978,7 +3056,7 @@ export class WorkspaceModule {
         }
         if (!fileInfo.isFile() && !fileInfo.isSymbolicLink()) {
             // A FIFO, socket or device is never opened.
-            throw new WorkspaceReadError('not_found', `Not a regular file: ${mountPrefixedPath}`, 'lstat');
+            throw new NotRegularFile(mountPrefixedPath, 'lstat');
         }
         let handle;
         try {
@@ -3009,7 +3087,7 @@ export class WorkspaceModule {
                 throw new WorkspaceReadError('directory', `Path is a directory: ${mountPrefixedPath}`, 'fstat');
             }
             if (!fileStat.isFile()) {
-                throw new WorkspaceReadError('not_found', `Not a regular file: ${mountPrefixedPath}`, 'fstat');
+                throw new NotRegularFile(mountPrefixedPath, 'fstat');
             }
             if (!follow && !useNoFollow) {
                 let postOpenInfo;
@@ -3047,13 +3125,13 @@ export class WorkspaceModule {
             if (resolvedThrough !== null)
                 throw await linkReadError(mount, resolvedThrough, mountPrefixedPath, relativePath, nested, realMountRoot);
             const inside = isContainedPath(realMountRoot, realFilePath);
-            const holder = inside ? nestedAtReal(realFilePath, nested) : undefined;
+            const holder = inside ? await nestedAtReal(realFilePath, nested, { name: mount.config.name, rootReal: realMountRoot }) : undefined;
             // A place in a nested mount's directory that its include leaves out is
             // no mount's, so the path leaves this one (namesNestedPlace), and so
             // does one reaching a file this mount's own include leaves out
             // (coversLanding).
             const own = holder === undefined && inside && !(await coversLanding({ include: mount.config.include }, realMountRoot, realFilePath, relativePath));
-            if (!inside || own || (holder !== undefined && !namesNestedPlace(holder.rest, holder.include, false))) {
+            if (!inside || own || (holder !== undefined && !holder.names(false))) {
                 throw new WorkspaceReadError('escape', `Symlink escape detected: ${mountPrefixedPath}`, 'realpath');
             }
             if (holder)
@@ -3122,7 +3200,9 @@ export class WorkspaceModule {
      * (`outside_include`), a path in another mount's directory nested in the one named
      * (`other_mount`), unavailable mount, missing or non-regular file,
      * directory, policy-denied symlink, outside-mount target, and
-     * file-changed-during-read.
+     * file-changed-during-read. An error met while parsing the path that is
+     * none of these refusals, such as the store's, is thrown as it is, and a
+     * `maxBytes` that isn't a non-negative integer throws a `RangeError`.
      */
     async readFileFromDisk(mountPrefixedPath, options = {}) {
         if (options.maxBytes !== undefined && !(Number.isInteger(options.maxBytes) && options.maxBytes >= 0)) {
@@ -3137,11 +3217,12 @@ export class WorkspaceModule {
             // A link's refusal (parseFilePath) carries its own code.
             if (err instanceof WorkspaceReadError)
                 throw err;
-            const message = err instanceof Error ? err.message : String(err);
             const code = err instanceof OutsideIncludeError ? 'outside_include'
                 : err instanceof NestedMountError ? 'other_mount'
-                    : message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
-            throw new WorkspaceReadError(code, message, 'parse');
+                    : err instanceof PathRefusal ? err.code : null;
+            if (code === null)
+                throw err;
+            throw new WorkspaceReadError(code, err.message, 'parse');
         }
         if (!relativePath) {
             throw new WorkspaceReadError('directory', `Path is a directory: ${mountPrefixedPath}`, 'parse');
@@ -3171,93 +3252,25 @@ export class WorkspaceModule {
             await handle.close();
         }
     }
-    /** Map a core read refusal onto the image reader's historical error vocabulary and wording. */
-    imageErrorFromRead(err, mount, mountPrefixedPath) {
-        const p = mountPrefixedPath;
-        switch (err.code) {
-            case 'mount_unavailable':
-                // With why, where the root's check says, such as a directory that
-                // isn't the mount's.
-                return new WorkspaceImageReadError('mount_unavailable', err.message);
-            case 'directory':
-                return new WorkspaceImageReadError('directory', `Path is a directory: ${p}`);
-            case 'symlink':
-                // The core reader's own words for a link at the path: "Symlinks are not
-                // allowed: <path>".
-                return new WorkspaceImageReadError('symlink', err.message);
-            case 'parent_symlink':
-                // The core reader's own words for a link on its way: which link and
-                // where it leads, with the setting for a link to a directory.
-                return new WorkspaceImageReadError('parent_symlink', err.message);
-            case 'other_mount':
-                // The core reader's own words for a path a link takes into a nested
-                // mount's directory: that mount and the path to use there. (#460's
-                // own other_mount, a path in that directory, is refused at parse,
-                // and so is a link found there before the read.)
-                return new WorkspaceImageReadError('other_mount', err.message);
-            case 'escape':
-                // The core reader's own words: "Symlink escape detected: <path>" for a
-                // followed link that resolves outside the mount, and for a link on the
-                // way that leads outside a mount that doesn't follow links, which link.
-                return new WorkspaceImageReadError('escape', err.message);
-            case 'changed':
-                return new WorkspaceImageReadError('changed', `Image file changed during read: ${p}`);
-            case 'not_found':
-            default:
-                // The core reader's own words for a file that isn't regular, and for
-                // a directory on the way it couldn't ask about.
-                if (err.message.startsWith('Not a regular file') || err.stage === 'readlink') {
-                    return new WorkspaceImageReadError('not_found', err.message);
-                }
-                if (err.message.startsWith('File not found')) {
-                    return new WorkspaceImageReadError('not_found', `File not found: ${p}`);
-                }
-                if (err.stage === 'realpath') {
-                    return new WorkspaceImageReadError('not_found', `Unable to resolve image file: ${p}`);
-                }
-                if (err.stage === 'stat') {
-                    return new WorkspaceImageReadError('not_found', `Unable to stat image file: ${p}`);
-                }
-                return new WorkspaceImageReadError('not_found', `Unable to read image file: ${p}`);
-        }
-    }
     async readImageFromFilesystem(mount, relativePath, mountPrefixedPath, maxSize) {
-        let opened;
-        try {
-            opened = await this.openContainedFile(mount, relativePath, mountPrefixedPath, (fileStat) => {
-                if (fileStat.size === 0) {
-                    throw new WorkspaceImageReadError('empty', `Image file is empty: ${mountPrefixedPath}`);
-                }
-                if (fileStat.size > maxSize)
-                    throw imageTooLarge(maxSize, mountPrefixedPath);
-            });
-        }
-        catch (err) {
-            if (err instanceof WorkspaceImageReadError)
-                throw err;
-            if (err instanceof WorkspaceReadError)
-                throw this.imageErrorFromRead(err, mount, mountPrefixedPath);
-            if (isErrnoCode(err, 'ENOENT')) {
-                throw new WorkspaceImageReadError('not_found', `File not found: ${mountPrefixedPath}`);
-            }
-            throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
-        }
-        const { handle, fileStat } = opened;
+        const { handle, fileStat } = await this.openContainedFile(mount, relativePath, mountPrefixedPath, (fileStat) => {
+            if (fileStat.size === 0)
+                throw emptyImage(mountPrefixedPath);
+            if (fileStat.size > maxSize)
+                throw imageTooLarge(maxSize, mountPrefixedPath, fileStat.size.toLocaleString('en-US'));
+        });
         try {
             // No more than maxSize is loaded: a file grown past it since the fstat
             // above is refused here, as one already over it was there.
             const { bytes, more } = await readPrefix(handle, maxSize, fileStat.size);
             if (more)
-                throw imageTooLarge(maxSize, mountPrefixedPath);
+                throw imageTooLarge(maxSize, mountPrefixedPath, `at least ${(maxSize + 1).toLocaleString('en-US')}`);
             return this.validateImageBytes(bytes, mountPrefixedPath, maxSize);
         }
         catch (err) {
             if (err instanceof WorkspaceImageReadError)
                 throw err;
-            if (isErrnoCode(err, 'ENOENT')) {
-                throw new WorkspaceImageReadError('not_found', `File not found: ${mountPrefixedPath}`);
-            }
-            throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
+            throw new WorkspaceReadError('not_found', `Unable to read file: ${mountPrefixedPath}`, 'read', errnoOf(err));
         }
         finally {
             await handle.close();
@@ -3289,13 +3302,14 @@ export class WorkspaceModule {
      * downstream agents. And, apart from it, why a write whose bytes reached
      * disk left the file's mode as disk had it (`modeKept`), and, for a
      * deletion that cleared a conflict naming a disk file the workspace never
-     * took in, that nothing was unlinked (`note`). The caller holds the mount's
-     * turn and has settled the path first (settleBeforeMutation, or a pass over
-     * the path, as an edit makes).
+     * took in, that nothing was unlinked (`note`). And the answer's `disk` for
+     * the path, unless it was refused. The caller holds the mount's turn and has
+     * settled the path first (settleBeforeMutation, or a pass over the path, as
+     * an edit makes).
      */
     async commitToolChange(mount, relativePath, change, onCommitted) {
-        const { refused, modeKept, notes } = await this.commitToolChanges(mount, [{ path: relativePath, change }], onCommitted && (() => onCommitted()));
-        return { refused: refused.get(relativePath) ?? null, modeKept: modeKept.get(relativePath) ?? null, note: notes.get(relativePath) ?? null };
+        const { refused, modeKept, notes, disk } = await this.commitToolChanges(mount, [{ path: relativePath, change }], onCommitted && (() => onCommitted()));
+        return { refused: refused.get(relativePath) ?? null, modeKept: modeKept.get(relativePath) ?? null, note: notes.get(relativePath) ?? null, disk: disk.get(relativePath) ?? null };
     }
     /**
      * commitToolChange for several paths of one mount at once, as edit_many
@@ -3310,9 +3324,10 @@ export class WorkspaceModule {
      * (changesLanded).
      * Answers, by path, the reason for each that reached the workspace but not
      * disk (`refused`), and, apart from it, why one whose bytes reached disk
-     * left the file's mode as disk had it (`modeKept`), and that a deletion
-     * clearing a conflict that named a disk file unlinked nothing (`notes`), as
-     * commitToolChange answers them for one path.
+     * left the file's mode as disk had it (`modeKept`), that a deletion
+     * clearing a conflict that named a disk file unlinked nothing (`notes`),
+     * and the answer's `disk` for each path not refused, as commitToolChange
+     * answers them for one path.
      */
     async commitToolChanges(mount, changes, onCommitted) {
         const store = this.getStore();
@@ -3461,7 +3476,7 @@ export class WorkspaceModule {
             // nothing.
             if (changing.length === 0 || !changesLanded(store, mount.treeStateId, changing, error)) {
                 putBack();
-                throw error;
+                throw changing.length === 0 ? new AlreadyHeld(error) : error;
             }
             landedThenThrew = { error };
         }
@@ -3479,8 +3494,9 @@ export class WorkspaceModule {
             throw new StoredThenFailed(landedThenThrew.error, this.pushesOnCommit(mount) && pushing.length > 0, notes);
         const refused = new Map();
         const modeKept = new Map();
-        if (!this.pushesOnCommit(mount) || pushing.length === 0)
-            return { refused, modeKept, notes };
+        if (!this.pushesOnCommit(mount) || pushing.length === 0) {
+            return { refused, modeKept, notes, disk: new Map(changes.map(({ path }) => [path, this.diskOf(mount, path)])) };
+        }
         const pushed = await this.pushUnlocked(mount, pushing.map(({ path }) => path), {
             applyDeletions: pushing.some(({ change }) => change.kind === 'remove'),
             branchId: store.currentBranch().id,
@@ -3502,7 +3518,7 @@ export class WorkspaceModule {
                 error: skipped.reason,
             });
         }
-        return { refused, modeKept, notes };
+        return { refused, modeKept, notes, disk: new Map(changes.filter(({ path }) => !refused.has(path)).map(({ path }) => [path, 'done'])) };
     }
     // ==========================================================================
     // Lazy Sync
@@ -3551,25 +3567,29 @@ export class WorkspaceModule {
      * call made again checks it.
      */
     notCheckedYet(path, reason) {
-        return `${this.notInWorkspace(path, { path, state: 'unverified', note: reason })} Make the same call again, which checks disk first.`;
+        return `${JSON.stringify(path)} isn't in the workspace, and disk couldn't be checked: ${reason}. Make the same call again, which checks disk first.`;
     }
     /** Why the workspace holds no entry at a path, when disk explains it. */
-    notInWorkspace(path, report) {
+    notInWorkspace(path, report, mount, missing) {
+        const shown = JSON.stringify(path);
         switch (report?.state) {
             case 'workspace-deleted':
-                return `${path} was deleted in the workspace; disk still has a copy. Sync this path to restore it.`;
+                return `${shown} was deleted in the workspace; disk still has a copy. Sync this path to restore it.`;
             case 'not-in-branch':
-                return `${path} is not in this branch's workspace; disk has a copy. Sync this path to add it.`;
-            case 'disk-only':
-                return `${path} is on disk but not stored in the workspace (binary or over the size limit)` +
-                    (report.mimeType?.startsWith('image/') ? '; read it with read_image.' : '.');
+                return `${shown} is not in this branch's workspace; disk has a copy. Sync this path to add it.`;
+            case 'disk-only': {
+                const shows = report.mimeType?.startsWith('image/') === true && report.size !== undefined && report.size <= (mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE);
+                return `${shown} is on disk, but the workspace doesn't store it: it's binary, or over this mount's size limit. `
+                    + 'read, edit and delete act only on the files it stores, so calling again won\'t change that'
+                    + (shows ? '; read_image shows it, if its data holds together as an image.' : '.');
+            }
             case 'conflict':
-                return `${path} is in conflict: the workspace deleted it and disk changed it since. ` +
+                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 `${path} is not in the workspace, and disk could not be checked (${report.note ?? 'not observed'}).`;
+                return uncheckedFile(shown, report.note, report.noteCause ?? {});
             default:
-                return `File not found: ${path}`;
+                return missing ?? `there's no file at ${shown}. ls or glob lists the files that exist.`;
         }
     }
     /**
@@ -3611,15 +3631,15 @@ export class WorkspaceModule {
                 // A pass also drops a copy disk made binary or too large, which
                 // the disk-only answer describes; any other drop is disk's deletion.
                 return {
-                    error: took('deleted') && report?.state !== 'disk-only'
-                        ? `File not found: ${path}. Disk's copy was deleted since the workspace last agreed with it, and that was taken in first.`
-                        : [this.notInWorkspace(path, report), ...again].join(' '),
+                    error: took('deleted') && report?.state !== 'disk-only' ? deletedOnDisk(path)
+                        : undecided !== null ? this.notCheckedYet(path, undecided)
+                            : this.notInWorkspace(path, report, mount),
                 };
             }
-            const blob = store.getBlob(entry.blobHash);
-            if (!blob)
-                return { error: `Blob not found for: ${path}` };
-            return { bytes: blob, notes: [...whichCopyRead(report, took('modified'), mount.config.mode === 'read-only'), ...again] };
+            const contents = await this.contentsOf(mount, relativePath, path, entry);
+            if ('lost' in contents)
+                return { error: nothingToRead(contents.lost) };
+            return { bytes: contents.bytes, notes: [...whichCopyRead(report, took('modified'), mount.config.mode === 'read-only'), ...again] };
         });
     }
     /**
@@ -3632,37 +3652,145 @@ export class WorkspaceModule {
      */
     async bytesOnDisk(mount, relativePath, path) {
         const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
-        const over = `${path} is over the size limit (${maxSize} bytes), so read doesn't show it.`;
+        const over = (size) => pastSizeLimit(`${JSON.stringify(path)} is ${size} bytes`, maxSize, "read doesn't show it", null);
         let opened;
         try {
             opened = await this.openContainedFile(mount, relativePath, path, (fileStat) => {
                 if (fileStat.size > maxSize)
-                    throw new Error(over);
+                    throw new Refusal(over(fileStat.size.toLocaleString('en-US')));
             });
         }
         catch (err) {
-            // A refusal that names only the path says why with its errno, as a
-            // failed read below does.
-            return { error: containedRefusal(err, path) };
+            if (err instanceof Refusal)
+                return { error: err.message };
+            if (err instanceof WorkspaceReadError)
+                return { error: readRefusal(err, path) };
+            throw err;
         }
         try {
             // No more than the limit is loaded, as for a file over it at its fstat.
             const { bytes, more } = await readPrefix(opened.handle, maxSize, opened.fileStat.size);
             if (more)
-                return { error: over };
+                return { error: over(`at least ${(maxSize + 1).toLocaleString('en-US')}`) };
             if (looksBinary(bytes)) {
-                return { error: `${path} is binary, so read doesn't show it as text${sniffImageMime(bytes) ? '; read it with read_image.' : '.'}` };
+                return { error: `${JSON.stringify(path)} is binary, so read doesn't show it as text. ${sniffImageMime(bytes) ? 'read_image shows it, if its data holds together as an image.' : 'No tool shows it as text, so calling again won\'t change that.'}` };
             }
             return { bytes };
         }
         catch (err) {
-            const errno = errnoOf(err);
-            return { error: `Unable to read file: ${path}${errno ? ` (${errno})` : ''}` };
+            return { error: unreadable(JSON.stringify(path), errnoOf(err)) };
         }
         finally {
             await opened.handle.close();
         }
     }
+    async contentsOf(mount, relativePath, path, version, what = 'saved', tell = 'now') {
+        const store = this.getStore();
+        const stored = storedBytes(store, version.blobHash);
+        if ('bytes' in stored)
+            return stored;
+        const otherSize = new Error('other size');
+        let found;
+        try {
+            const opened = await this.openContainedFile(mount, relativePath, path, (fileStat) => {
+                if (fileStat.size !== version.size)
+                    throw otherSize;
+            });
+            try {
+                const read = await readPrefix(opened.handle, version.size, opened.fileStat.size);
+                found = !read.more && hashContent(read.bytes) === version.blobHash ? { bytes: read.bytes } : { disk: 'other' };
+            }
+            finally {
+                await opened.handle.close();
+            }
+        }
+        catch (err) {
+            found = { disk: err === otherSize ? 'other' : await this.diskLacks(mount, relativePath, path, err) };
+        }
+        const subject = contentsSubject(what, path);
+        const data = { mount: mount.config.name, path, blobHash: version.blobHash, ...('unreadable' in stored ? { storeError: stored.unreadable } : {}) };
+        if ('disk' in found) {
+            const now = storedBytes(store, version.blobHash);
+            if ('bytes' in now)
+                return now;
+            const lost = { path, store: now, disk: found.disk, writable: writeRefusal(mount) === null, reopen: this.agreementOrThrow().awaitsReopen };
+            if (tell === 'now')
+                this.tellLost(mount.config.name, what, version.blobHash, lost);
+            return { lost };
+        }
+        const { bytes } = found;
+        if ('bytes' in storedBytes(store, version.blobHash))
+            return { bytes };
+        let thrown = null;
+        try {
+            store.storeBlob(bytes, 'application/octet-stream');
+        }
+        catch (error) {
+            thrown = error instanceof Error ? error.message : String(error);
+        }
+        // Chronicle's storeBlob takes any file already at the hash's path as
+        // stored, so whether the bytes took is what a read of them gives now.
+        const now = storedBytes(store, version.blobHash);
+        if ('bytes' in now) {
+            this.ctx?.notifyOps?.('workspace-contents-restored', 'workspace', `Blob ${version.blobHash}: ${subject} were ${inTheStore(stored)}, and were stored again from disk's copy, whose bytes have their hash.`, data);
+        }
+        else {
+            const unstored = thrown ?? ('missing' in now ? 'the store has no file for them' : `the store can't read its file for them (${now.unreadable})`);
+            this.ctx?.notifyOps?.('workspace-contents-unstored', 'workspace', `Blob ${version.blobHash}: ${subject} are ${inTheStore(now)}. Disk's copy has their hash, so reads are answered from it, but storing it again didn't take: ${unstored}. `
+                + ('unreadable' in now
+                    ? "Each read does this again while that lasts. Chronicle keeps a blob file it can't read in place, so where the file is damaged, removing it lets the next read store them."
+                    : 'Each read does this again until the store takes them.'), { mount: mount.config.name, path, blobHash: version.blobHash, ...('unreadable' in now ? { storeError: now.unreadable } : {}), unstored });
+        }
+        return { bytes };
+    }
+    tellLost(mountName, what, blobHash, lost) {
+        this.ctx?.notifyOps?.('workspace-contents-lost', 'workspace', `Blob ${blobHash}: ${contentsSubject(what, lost.path)} are ${inTheStore(lost.store)}, and no copy with their hash could be read from disk to restore them from: ${lostOnDisk(lost)}. `
+            + "Putting back the store's blob file for that hash, from a copy of the store, brings them back.", { mount: mountName, path: lost.path, blobHash, ...('unreadable' in lost.store ? { storeError: lost.store.unreadable } : {}) });
+    }
+    async diskLacks(mount, relativePath, path, err) {
+        const absent = err instanceof WorkspaceReadError && err.code !== 'mount_unavailable' && (err.errno === 'ENOENT' || err.errno === 'ENOTDIR');
+        if (!absent)
+            return { unreadable: containedRefusal(err, path) };
+        const root = resolve(mount.config.path);
+        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 (!('reason' in proof))
+            return 'none';
+        return { unreadable: proof.reason === CHANGED ? containedRefusal(err, path) : proof.reason };
+    }
+    async restoreEach(mount, versions, each) {
+        const byHash = new Map();
+        for (const version of versions) {
+            const sharing = byHash.get(version.hash);
+            if (sharing)
+                sharing.push(version);
+            else
+                byHash.set(version.hash, [version]);
+        }
+        for (const [hash, sharing] of byHash) {
+            let bytes = null;
+            const lost = [];
+            for (const version of sharing) {
+                const contents = await this.contentsOf(mount, version.relativePath, version.file, { blobHash: hash, size: version.size }, version.what, 'later');
+                if ('bytes' in contents) {
+                    bytes = contents.bytes;
+                    break;
+                }
+                lost.push([version, contents.lost]);
+            }
+            if (bytes === null) {
+                for (const [version, found] of lost) {
+                    this.tellLost(mount.config.name, version.what, hash, found);
+                    each(version, { lost: found });
+                }
+            }
+            else {
+                for (const version of sharing)
+                    each(version, { bytes });
+            }
+        }
+    }
     // ==========================================================================
     // Tool Handlers
     // ==========================================================================
@@ -3677,16 +3805,18 @@ export class WorkspaceModule {
         // Each number is a whole number of at least its schema's minimum by now
         // (inputProblem).
         if (characterPaging && (input.offset !== undefined || input.limit !== undefined)) {
-            return { success: false, isError: true, error: 'Use either offset/limit (lines) or offsetChars/limitChars (characters), not both.' };
+            return { success: false, isError: true, error: didNothing('read', 'it was given both "offset"/"limit", which page by lines, and "offsetChars"/"limitChars", which page by characters. Give one pair.') };
         }
         let file;
         let notes = [];
         if (generatedContent === undefined) {
             const { mount, relativePath, path } = await this.parseFilePath(input.path);
+            if (relativePath === '')
+                return { success: false, error: didNothing('read', namesRoot(input.path, mount.config.name)), isError: true };
             input = { ...input, path };
             const found = await this.bytesOf(mount, relativePath, path);
             if ('error' in found)
-                return { success: false, error: found.error, isError: true };
+                return { success: false, error: didNothing('read', found.error), isError: true };
             file = fileText(found.bytes);
             notes = found.notes;
         }
@@ -3702,31 +3832,23 @@ export class WorkspaceModule {
             : linePage(input.path, file, input.offset ?? 1, input.limit ?? DEFAULT_READ_LINE_LIMIT, maxChars, notes);
     }
     async handleReadImage(input) {
-        let mount;
-        let relativePath;
-        try {
-            let path;
-            ({ mount, relativePath, path } = await this.parseFilePath(input.path));
-            input = { ...input, path };
-        }
-        catch (err) {
-            return {
-                success: false,
-                error: err instanceof Error ? err.message : String(err),
-                isError: true,
-            };
-        }
-        if (!relativePath) {
-            return { success: false, error: `Path is a directory: ${input.path}`, isError: true };
-        }
+        const given = input.path;
+        const refused = (body) => ({ success: false, isError: true, error: didNothing('read_image', body) });
+        const { mount, relativePath, path } = await this.parseFilePath(given);
+        if (!relativePath)
+            return refused(namesRoot(given, mount.config.name));
+        input = { ...input, path };
         const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
         let treeError = null;
+        let lost = null;
         // The workspace's copy first, where it holds one, then disk's. A direct
         // mount holds none, so its image is disk's.
         if (!mount.direct) {
             try {
-                const image = this.tryReadImageFromTree(mount, relativePath, input.path, maxSize);
-                if (image)
+                const image = await this.readImageFromTree(mount, relativePath, input.path, maxSize);
+                if (image && 'lost' in image)
+                    lost = image.lost;
+                else if (image)
                     return imageResult(input.path, image);
             }
             catch (err) {
@@ -3739,31 +3861,40 @@ export class WorkspaceModule {
             }
         }
         try {
-            return imageResult(input.path, await this.readImageFromFilesystem(mount, relativePath, input.path, maxSize));
+            const note = lost === null ? undefined
+                : `The workspace's copy of ${input.path} is ${lostInStore(lost)}, so this is disk's copy${lost.disk === 'other' ? ', which holds other contents' : ''}.`;
+            return imageResult(input.path, await this.readImageFromFilesystem(mount, relativePath, input.path, maxSize), note);
         }
         catch (err) {
-            if (err instanceof WorkspaceImageReadError) {
-                if (err.code === 'not_found' && treeError) {
-                    return { success: false, error: treeError.message, isError: true };
-                }
-                return { success: false, error: err.message, isError: true };
+            if (!(err instanceof WorkspaceImageReadError) && !(err instanceof WorkspaceReadError))
+                throw err;
+            const noFile = err instanceof WorkspaceReadError && err.code === 'not_found';
+            if (lost) {
+                const why = err instanceof WorkspaceImageReadError ? err.reason : containedRefusal(err, input.path);
+                return refused(noFile || lost.disk !== 'other' ? nothingToRead(lost)
+                    : `${lostText(lost, 'the')}, so it can't be restored, and disk's copy can't be shown (${why}). ${lostRemedy(lost)}`);
             }
-            throw err;
+            if (noFile && treeError)
+                return refused(treeError.message);
+            return refused(err instanceof WorkspaceImageReadError ? err.message : readRefusal(err, given));
         }
     }
     async handleWrite(input, callerAgentName) {
         if (LONE_SURROGATE.test(input.content)) {
-            return { success: false, isError: true, error: 'The write did nothing: "content" holds a lone UTF-16 surrogate, which UTF-8 can\'t store.' };
+            return { success: false, isError: true, error: 'The write did nothing: "content" holds a lone UTF-16 surrogate, which UTF-8 can\'t store. Give it without the surrogate, or with the other half of its pair.' };
         }
-        const { mount, relativePath, path } = await this.parseFilePath(input.path);
+        const { mount, relativePath, path } = await this.parseFilePath(input.path).catch((error) => { throw notStored(error); });
+        if (relativePath === '')
+            return { success: false, error: didNothing('write', namesRoot(input.path, mount.config.name)), isError: true };
         input = { ...input, path };
-        const refusal = writeRefusal(mount);
+        const refusal = writeRefusal(mount, this.writableNames());
         if (refusal)
-            return { success: false, error: refusal, isError: true };
+            return { success: false, error: didNothing('write', refusal), isError: true };
         const store = this.getStore();
         const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
-        if (Buffer.byteLength(input.content) > maxSize) {
-            return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
+        const bytes = Buffer.byteLength(input.content);
+        if (bytes > maxSize) {
+            return { success: false, error: didNothing('write', tooLargeToWrite(input.path, bytes, maxSize)), isError: true };
         }
         const buffer = Buffer.from(input.content, 'utf-8');
         const receipt = { path: input.path, size: buffer.byteLength, hash: hashContent(input.content) };
@@ -3772,13 +3903,14 @@ export class WorkspaceModule {
             const written = await this.writeDirect(mount, relativePath, input.path, buffer, callerAgentName);
             if ('error' in written)
                 return { success: false, isError: true, error: written.error };
-            return { success: true, data: { ...receipt, ...(written.note ? { note: written.note } : {}) } };
+            return { success: true, data: { ...receipt, disk: 'done', ...(written.note ? { note: written.note } : {}) } };
         }
         let committed = false;
         let refused;
         let modeKept;
+        let disk;
         try {
-            ({ refused, modeKept } = await this.withMount(mount, async () => {
+            ({ refused, modeKept, disk } = await this.withMount(mount, async () => {
                 await this.settleBeforeMutation(mount, relativePath);
                 const blobHash = store.storeBlob(buffer, 'text/plain');
                 // An overwrite keeps the file's mode, as an edit does.
@@ -3788,14 +3920,14 @@ export class WorkspaceModule {
         }
         catch (error) {
             if (!committed)
-                throw error;
+                throw notStored(error);
             return storedButUnfinished('write', input.path, error instanceof StoredThenFailed
                 ? { storeFailed: error.message, pushes: error.pushes }
-                : { threw: error instanceof Error ? error.message : String(error) });
+                : { threw: error instanceof Error ? error.message : String(error) }, null, this.agreement?.awaitsReopen === true);
         }
         if (refused !== null)
             return storedButUnfinished('write', input.path, { refused });
-        return { success: true, data: { ...receipt, ...(modeKept ? { modeKept } : {}) } };
+        return { success: true, data: { ...receipt, disk, ...(modeKept ? { modeKept } : {}) } };
     }
     async handleEdit(input, maxChars = DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, callerAgentName) {
         return this.applyEdits('edit', [{
@@ -3835,12 +3967,14 @@ export class WorkspaceModule {
      * stored where its record landed, and that it can't tell where they
      * couldn't be read back.
      * Under the mount's turn, one pass settles every path with disk, by the
-     * rule a listing uses, so the edits apply to what disk now holds. That pass
-     * is the only step that awaits before the commit: every file is then read,
-     * every edit planned, and every entry set (commitToolChanges) with no turn
-     * of the event loop between, so no pass, branch change or other call moves
-     * the tree between a file's read and its set. Disk then takes what it can
-     * of the stored change.
+     * rule a listing uses, so the edits apply to what disk now holds. Each
+     * file's stored contents are then read; where the store has lost some,
+     * they're restored from disk's matching copy (contentsOf) and the pass runs
+     * again, so the plan reads a pass taken after every await. From there
+     * nothing awaits before the commit: every edit is planned and every entry
+     * set (commitToolChanges) with no turn of the event loop between, so no
+     * pass, branch change or other call moves the tree between a file's read
+     * and its set. Disk then takes what it can of the stored change.
      *
      * The answer is held to `maxChars`, the length the call's result may have
      * (ToolCall.resultMaxChars), as edit-text.ts describes.
@@ -3875,7 +4009,7 @@ export class WorkspaceModule {
             }
             for (const field of ['oldString', 'newString']) {
                 if (LONE_SURROGATE.test(edit[field])) {
-                    problems.push({ kind: 'input', edit: index, text: `"${field}" holds a lone UTF-16 surrogate, which UTF-8 can't store.` });
+                    problems.push({ kind: 'input', edit: index, text: `"${field}" holds a lone UTF-16 surrogate, which UTF-8 can't store. Give it without the surrogate, or with the other half of its pair.` });
                 }
             }
             if (problems.length === found)
@@ -3937,7 +4071,31 @@ export class WorkspaceModule {
             return await this.withMount(mount, async () => {
                 // As every file tool's pass does, it names the paths it acts on, so a
                 // file the mount passes over by design is observed (see PassOptions.named).
-                const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [...targets.values()].map((target) => target.relativePath) }, { named: true });
+                let pass = await this.passUnlocked(mount, { kind: 'paths', paths: [...targets.values()].map((target) => target.relativePath) }, { named: true });
+                let ops = pass.ops;
+                const contents = new Map();
+                const lost = new Map();
+                const toRecover = [];
+                for (const target of targets.values()) {
+                    const entry = store.treeGet(mount.treeStateId, target.relativePath);
+                    if (!entry || contents.has(entry.blobHash))
+                        continue;
+                    const stored = storedBytes(store, entry.blobHash);
+                    if ('bytes' in stored)
+                        contents.set(entry.blobHash, stored.bytes);
+                    else
+                        toRecover.push({ relativePath: target.relativePath, file: target.path, hash: entry.blobHash, size: entry.size, what: 'saved' });
+                }
+                if (toRecover.length > 0) {
+                    await this.restoreEach(mount, toRecover, (version, found) => {
+                        if ('bytes' in found)
+                            contents.set(version.hash, found.bytes);
+                        else
+                            lost.set(version.relativePath, { blobHash: version.hash, lost: found.lost });
+                    });
+                    pass = await this.passUnlocked(mount, { kind: 'paths', paths: [...targets.values()].map((target) => target.relativePath) }, { named: true });
+                    ops = [...ops, ...pass.ops];
+                }
                 // A pass that decided nothing checked no file's disk copy.
                 const undecided = undecidedOf(pass);
                 // Nothing below awaits until the commit's push.
@@ -3957,7 +4115,7 @@ export class WorkspaceModule {
                     // A mode taken in alone isn't a change to the text: it brings nothing
                     // new to read, as it makes no event (emitFsEvents), and the edits
                     // then write at the mode disk has, so it leaves nothing to say.
-                    const took = (op) => pass.ops.some((o) => o.path === target.relativePath && o.op === op && !o.modeOnly);
+                    const took = (op) => ops.some((o) => o.path === target.relativePath && o.op === op && !o.modeOnly);
                     // Which copy the edits used, when it isn't the one the workspace
                     // last agreed on with disk: disk's newer text, or the workspace's
                     // copy because disk's couldn't be read or disk has none. A file the
@@ -4021,18 +4179,28 @@ export class WorkspaceModule {
                         // A pass also drops a copy disk made binary or too large, which
                         // the disk-only answer describes; any other drop is disk's deletion.
                         const text = took('deleted') && report?.state !== 'disk-only'
-                            ? `File not found: ${target.path}. Disk's copy was deleted since the workspace last agreed with it, and that was taken in first.`
-                            : this.notInWorkspace(target.path, report);
-                        problems.push({ kind: 'file', edits: target.edits, path: target.path, text, whole: true });
+                            ? deletedOnDisk(target.path)
+                            : this.notInWorkspace(target.path, report, mount);
+                        problems.push({ kind: 'file', edits: target.edits, path: target.path, text, whole: false });
                         continue;
                     }
-                    notes.push(...lookedIn);
-                    const blob = store.getBlob(entry.blobHash);
-                    if (!blob) {
-                        problems.push({ kind: 'file', edits: target.edits, path: target.path, text: `Blob not found for: ${target.path}`, whole: true });
+                    const known = contents.get(entry.blobHash);
+                    const stored = known !== undefined ? { bytes: known } : storedBytes(store, entry.blobHash);
+                    if (!('bytes' in stored)) {
+                        const found = lost.get(target.relativePath);
+                        problems.push({
+                            kind: 'file',
+                            edits: target.edits,
+                            path: target.path,
+                            text: found?.blobHash === entry.blobHash
+                                ? `${lostText(found.lost)}, so it can't be restored, and ${subject} changed nothing. ${lostRemedy(found.lost)}`
+                                : `The workspace's copy of ${target.path} changed while ${subject} restored lost contents from disk, and is ${lostInStore({ store: stored })} too, so ${subject} changed nothing. Make the same call again.`,
+                            whole: true,
+                        });
                         continue;
                     }
-                    const plan = planTargetEdits(tool, target, blob, hints, maxSize, counts, problems);
+                    notes.push(...lookedIn);
+                    const plan = planTargetEdits(tool, target, stored.bytes, hints, maxSize, counts, problems);
                     if (plan === null)
                         continue;
                     plans.push({
@@ -4048,7 +4216,7 @@ export class WorkspaceModule {
                 }
                 if (problems.length)
                     return refuse(problems, notes);
-                const { refused, modeKept } = await this.commitToolChanges(mount, plans.map(({ target, plan, mode }) => ({
+                const { refused, modeKept, disk } = await this.commitToolChanges(mount, plans.map(({ target, plan, mode }) => ({
                     path: target.relativePath,
                     change: { kind: 'set', blobHash: store.storeBlob(plan.bytes, 'text/plain'), size: plan.bytes.length, mode },
                 })), () => { committed = true; });
@@ -4059,7 +4227,7 @@ export class WorkspaceModule {
                     plan,
                     notes: [applied.get(target) ?? null, backOnDisk, conflictNote].filter((note) => note !== null),
                     modeKept: modeKept.get(target.relativePath) ?? null,
-                })), given.length, maxChars);
+                })), given.length, maxChars, furthestFromDisk(plans.map(({ target }) => disk.get(target.relativePath))));
             });
         }
         catch (error) {
@@ -4067,12 +4235,12 @@ export class WorkspaceModule {
             if (committed) {
                 return this.editsStoredButUnfinished(tool, [...targets.values()], applied, conflicts, error instanceof StoredThenFailed
                     ? { storeFailed: message, pushes: error.pushes }
-                    : { threw: message }, maxChars);
+                    : { threw: message }, maxChars, this.agreement?.awaitsReopen === true);
             }
             // A set that threw and couldn't be read back may have stored the edits,
             // and a second call could then apply them twice.
             if (error instanceof CommitUnknownError) {
-                const [set, read] = [cutLine(error.setError), cutLine(error.readError)];
+                const [set, read] = [storeWords(error.setCause), storeWords(error.readCause)];
                 return {
                     success: false,
                     isError: true,
@@ -4085,10 +4253,8 @@ export class WorkspaceModule {
             }
             // The commit sets every entry in one record or none, and a set that
             // threw was read back, so nothing is stored; or every change was one
-            // the tree already held, which leaves the tree as it was either way.
-            if (tool === 'edit_many')
-                return { success: false, isError: true, error: `The edit_many call stored none of its edits: ${cutLine(message)}` };
-            throw error;
+            // the tree already held (AlreadyHeld).
+            throw notStored(error);
         }
     }
     /**
@@ -4101,7 +4267,7 @@ export class WorkspaceModule {
      * (handleToolCall checks a call's `path`, which edit_many's input lacks).
      */
     async editablePath(tool, path, callerAgentName) {
-        const unusable = (text) => ({ kind: 'file', edits: [], path, text, whole: true });
+        const unusable = (text) => ({ kind: 'file', edits: [], path, text, whole: false });
         try {
             // In the one spelling every file tool reads, as disk spells it, so two
             // spellings of a file are one entry and, in one call, one plan
@@ -4111,17 +4277,21 @@ export class WorkspaceModule {
             // One that names the mount's root, its bare name included, names no
             // file.
             if (where.relativePath === '')
-                return unusable(`${path} names the root of mount "${where.mount.config.name}", which isn't a file; ls ${where.mount.config.name} lists the files in it.`);
-            const refusal = writeRefusal(where.mount);
+                return unusable(namesRoot(path, where.mount.config.name));
+            const refusal = writeRefusal(where.mount, this.writableNames());
             if (refusal)
                 return unusable(refusal);
             const generated = tool === 'edit_many' ? this.findGeneratedTextFile(path) : undefined;
             if (generated)
-                return unusable(`${path}: ${this.generatedFileRefusal(generated, callerAgentName)}.`);
+                return unusable(this.generatedFileRefusal(path, generated, callerAgentName));
             return where;
         }
         catch (error) {
-            return unusable(error instanceof Error ? error.message : String(error));
+            if (error instanceof Refusal)
+                return unusable(error.message);
+            if (error instanceof WorkspaceReadError)
+                return unusable(readRefusal(error, path));
+            throw notStored(error);
         }
     }
     /**
@@ -4129,10 +4299,10 @@ export class WorkspaceModule {
      * and the agent's own is read-only, since it shows the agent's tool
      * presentation, which set_tool_visibility and set_tool_description change.
      */
-    generatedFileRefusal(generated, callerAgentName) {
+    generatedFileRefusal(path, generated, callerAgentName) {
         return callerAgentName !== generated.agentName
-            ? 'Generated file belongs to another agent'
-            : 'Generated file is read-only; change the tool presentation it shows with set_tool_visibility or set_tool_description instead';
+            ? `${JSON.stringify(path)} is generated from another agent's tool presentation, and only that agent reads it. Calling again won't change that.`
+            : `${JSON.stringify(path)} is generated from your tool presentation, so it's read-only; set_tool_visibility and set_tool_description change what it shows.`;
     }
     /**
      * The answer to edits stored but not finished: the commit set every file's
@@ -4148,12 +4318,12 @@ export class WorkspaceModule {
      * which stand as on a success, it names each conflict the success answer
      * would (`conflicts`, found only where the mount doesn't push).
      */
-    editsStoredButUnfinished(tool, targets, applied, conflicts, outcome, maxChars) {
+    editsStoredButUnfinished(tool, targets, applied, conflicts, outcome, maxChars, reopen = false) {
         const conflictOf = (target) => ('storeFailed' in outcome ? conflicts.get(target) ?? null : null);
         if (tool === 'edit') {
             const [target] = targets;
             const note = [applied.get(target) ?? null, conflictOf(target)].filter((text) => text !== null).join(' ');
-            return storedButUnfinished('edit', target.path, 'refused' in outcome ? { refused: outcome.refused.get(target.relativePath) } : outcome, note || null);
+            return storedButUnfinished('edit', target.path, 'refused' in outcome ? { refused: outcome.refused.get(target.relativePath) } : outcome, note || null, reopen);
         }
         const stored = "Every edit of this call is stored in the workspace, so don't send the call again: a second call can apply its edits twice.";
         // The head is never cut, so what stands for the whole call goes in it,
@@ -4176,10 +4346,11 @@ export class WorkspaceModule {
         }
         else if ('storeFailed' in outcome) {
             head = `${stored}\n\nThe store failed after recording them: ${cutLine(outcome.storeFailed)}.`
-                + (outcome.pushes ? " Their push to disk didn't run, so disk lacks them until a materialize of their files writes them." : '');
+                + (outcome.pushes ? ` Their push to disk didn't run, so disk lacks them until a materialize of their files writes them${reopen ? ONCE_REOPENED : ''}.` : '')
+                + (reopen ? ` ${AWAITS_REOPEN}` : '');
         }
         else {
-            head = `${stored}\n\nThe rest of the call failed: ${cutLine(outcome.threw)}. ls shows each path's state.`;
+            head = `${stored}\n\nThe rest of the call failed: ${cutLine(outcome.threw)}.${reopen ? ` ${AWAITS_REOPEN}` : " ls shows each path's state."}`;
         }
         const kept = 'modeKept' in outcome
             ? targets.flatMap((target) => {
@@ -4213,7 +4384,7 @@ export class WorkspaceModule {
                 staged = await stageContained(view, rootReal, relativePath, bytes, { makeDirectory: true });
             }
             catch (error) {
-                return { error: `The write did nothing to ${path}: ${directReason(error)}.` };
+                return { error: directDidNothing('write', path, error) };
             }
             try {
                 await directWriteTestSeam.afterStage?.([staged.path]);
@@ -4228,7 +4399,7 @@ export class WorkspaceModule {
             }
             catch (error) {
                 await discard(staged);
-                return { error: `The write did nothing to ${path}: ${directReason(error)}.` };
+                return { error: directDidNothing('write', path, error) };
             }
             this.recordDirectWrite(mount, agentName);
             return { note: linksNote(path, staged, 'write') };
@@ -4288,7 +4459,7 @@ export class WorkspaceModule {
                 return 'changed';
             }
             if ('error' in got)
-                problems.push({ kind: 'file', edits: target.edits, path: target.path, text: got.error, whole: true });
+                problems.push({ kind: 'file', edits: target.edits, path: target.path, text: got.error, whole: false });
             else
                 read.set(target, got);
         }
@@ -4358,7 +4529,8 @@ export class WorkspaceModule {
                 edits: target.edits,
                 path: target.path,
                 text: `${target.path}: ${directReason(error)}, so ${tool === 'edit' ? 'the edit' : editList(target.edits)} changed nothing.`
-                    + (tool === 'edit_many' && plans.length > 1 ? ' No file was written.' : ''),
+                    + (tool === 'edit_many' && plans.length > 1 ? ' No file was written.' : '')
+                    + (directWayOn(error) !== null ? ` ${directWayOn(error)}` : ''),
                 whole: true,
             }]);
         for (const { target, plan } of plans) {
@@ -4428,7 +4600,7 @@ export class WorkspaceModule {
             plan: plans.find((p) => p.target === target).plan,
             notes: [reread(target, 'applied to'), linksNote(target.path, file, tool)].filter((note) => note !== null),
             modeKept: null,
-        })), editCount, maxChars);
+        })), editCount, maxChars, 'done');
     }
     /**
      * The answer to an edit_many call on a direct mount whose rename of its
@@ -4440,7 +4612,8 @@ export class WorkspaceModule {
     directEditsPartway(staged, failed, error, maxChars) {
         // The failed file is named among the outcomes, so the head stays as
         // long as its reason, whatever the paths' lengths.
-        const head = `The edit_many call wrote ${failed} of its ${staged.length} files before the next one's write failed: ${directReason(error)}. `
+        const can = error instanceof WriteRefused && error.errno !== undefined ? hostFix(error.errno) : undefined;
+        const head = `The edit_many call wrote ${failed} of its ${staged.length} files before the next one's write failed: ${directReason(error)}.${can !== undefined ? ` Whoever runs this host can ${can}.` : ''} `
             + "Nothing puts the written files back, so finish or revert them: in each written file, each of its edits replaced its oldString with its newString. Each file's outcome:";
         const parts = staged.map(({ target }, i) => `${target.path}: ${i < failed ? 'written' : i === failed ? 'not written, as it was (its write failed)' : 'not written, as it was'}`);
         const notes = staged.slice(0, failed).map(({ target, staged: file }) => linksNote(target.path, file, 'edit_many')).filter((note) => note !== null);
@@ -4457,33 +4630,37 @@ export class WorkspaceModule {
      */
     async directEditText(mount, relativePath, path) {
         const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
-        const over = `${path} is over the size limit (${maxSize} bytes), so the workspace doesn't edit it.`;
+        const over = (size) => pastSizeLimit(`${JSON.stringify(path)} is ${size} bytes`, maxSize, "the workspace doesn't edit it", null);
         let opened;
         try {
             opened = await this.openContainedFile(mount, relativePath, path, (fileStat) => {
                 if (fileStat.size > maxSize)
-                    throw new Error(over);
+                    throw new Refusal(over(fileStat.size.toLocaleString('en-US')));
             });
         }
         catch (err) {
             if (err instanceof WorkspaceReadError && err.code === 'changed')
                 return { changed: true };
-            return { error: containedRefusal(err, path) };
+            if (err instanceof Refusal)
+                return { error: err.message };
+            if (err instanceof WorkspaceReadError)
+                return { error: readRefusal(err, path) };
+            throw err;
         }
         try {
             const before = identityOf(await opened.handle.stat({ bigint: true }));
             const { bytes, more } = await readPrefix(opened.handle, maxSize, opened.fileStat.size);
             if (more)
-                return { error: over };
-            if (looksBinary(bytes))
-                return { error: `${path} is binary, so the workspace doesn't edit it as text.` };
+                return { error: over(`at least ${(maxSize + 1).toLocaleString('en-US')}`) };
+            if (looksBinary(bytes)) {
+                return { error: `${JSON.stringify(path)} is binary, so the workspace doesn't edit it as text. A write replaces the whole file, if that's what you mean to do.` };
+            }
             if (!sameIdentity(before, identityOf(await opened.handle.stat({ bigint: true }))))
                 return { changed: true };
             return { bytes, identity: before };
         }
         catch (err) {
-            const errno = errnoOf(err);
-            return { error: `Unable to read file: ${path}${errno ? ` (${errno})` : ''}` };
+            return { error: unreadable(JSON.stringify(path), errnoOf(err)) };
         }
         finally {
             await opened.handle.close();
@@ -4512,11 +4689,9 @@ export class WorkspaceModule {
             catch (err) {
                 const code = errnoOf(err);
                 const why = code === 'ENOENT' || code === 'ENOTDIR'
-                    ? `the mount root is gone (${code}), and calling again is refused the same way until whoever runs the host puts a directory back at the mount's path`
-                    : code === 'EACCES' || code === 'EPERM'
-                        ? `the mount root can't be read (${code}), and calling again is refused the same way until whoever runs the host makes it readable`
-                        : `the mount root can't be read (${code ?? String(err)})`;
-                return { success: false, isError: true, error: `The delete did nothing to ${path}: ${why}.` };
+                    ? `the mount root isn't on disk. ${onlyTheHost("put the mount's directory back at its path")}`
+                    : `the mount root can't be read: ${systemWords(code, err)}. ${errnoWayOn(code, ROOT_RECHECK, true)}`;
+                return { success: false, isError: true, error: didNothing('delete', why, path) };
             }
             const view = { ...disk.view, rootIdentity: { dev: String(rootStat.dev), ino: String(rootStat.ino) } };
             const { rootReal } = disk;
@@ -4526,10 +4701,12 @@ export class WorkspaceModule {
             }
             catch (err) {
                 // The open's own words for a replaced root speak of reading.
-                if (err instanceof WorkspaceReadError && err.message.endsWith(DIRECT_ROOT_REPLACED)) {
-                    return { success: false, isError: true, error: `The delete did nothing to ${path}: ${ROOT_MOVED}.` };
+                if (err instanceof RootUnavailable && err.reason === DIRECT_ROOT_REPLACED) {
+                    return { success: false, isError: true, error: didNothing('delete', `${ROOT_MOVED}.`, path) };
                 }
-                return { success: false, isError: true, error: containedRefusal(err, path) };
+                if (err instanceof WorkspaceReadError)
+                    return { success: false, isError: true, error: didNothing('delete', readRefusal(err, path)) };
+                throw err;
             }
             // The unlink is awaited, unlike a write's rename, so where the head
             // was just before it says whether the head moved while it ran.
@@ -4542,12 +4719,12 @@ export class WorkspaceModule {
                 // 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: `The delete did nothing to ${path}: ${directReason(error)}.` };
+                return { success: false, isError: true, error: directDidNothing('delete', path, error) };
             }
             this.recordDirectWrite(mount, agentName, since);
-            return { success: true, data: { path, deleted: true }, keepWhenWithheld: ['path', 'deleted'] };
+            return { success: true, data: { path, deleted: true, disk: 'done' }, keepWhenWithheld: ['path', 'deleted', 'disk'] };
         });
     }
     /**
@@ -4695,11 +4872,13 @@ export class WorkspaceModule {
         this.historyLookup = lookup;
     }
     async handleDelete(input, callerAgentName) {
-        const { mount, relativePath, path } = await this.parseFilePath(input.path);
+        const { mount, relativePath, path } = await this.parseFilePath(input.path).catch((error) => { throw notStored(error); });
+        if (relativePath === '')
+            return { success: false, error: didNothing('delete', namesRoot(input.path, mount.config.name)), isError: true };
         input = { ...input, path };
-        const refusal = writeRefusal(mount);
+        const refusal = writeRefusal(mount, this.writableNames());
         if (refusal)
-            return { success: false, error: refusal, isError: true };
+            return { success: false, error: didNothing('delete', refusal), isError: true };
         if (mount.direct)
             return this.deleteDirect(mount, relativePath, input.path, callerAgentName);
         const store = this.getStore();
@@ -4710,31 +4889,31 @@ export class WorkspaceModule {
                 await this.settleBeforeMutation(mount, relativePath);
                 const entry = store.treeGet(mount.treeStateId, relativePath);
                 if (!entry) {
-                    const error = undecided !== null ? this.notCheckedYet(input.path, undecided) : this.notInWorkspace(input.path, report);
-                    return { success: false, error, isError: true };
+                    const error = undecided !== null ? this.notCheckedYet(input.path, undecided) : this.notInWorkspace(input.path, report, mount);
+                    return { success: false, error: didNothing('delete', error), isError: true };
                 }
-                const { refused, note } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash }, () => { committed = true; });
+                const { refused, note, disk } = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash }, () => { committed = true; });
                 if (refused !== null)
                     return storedButUnfinished('delete', input.path, { refused });
                 // Its whole receipt is what it changed: kept in the stub if the guard
                 // withholds the result (agent-framework #277).
                 return {
                     success: true,
-                    data: { path: input.path, deleted: true, ...(note ? { note } : {}) },
-                    keepWhenWithheld: ['path', 'deleted', 'note'],
+                    data: { path: input.path, deleted: true, disk, ...(note ? { note } : {}) },
+                    keepWhenWithheld: ['path', 'deleted', 'disk', 'note'],
                 };
             });
         }
         catch (error) {
             if (!committed)
-                throw error;
+                throw notStored(error);
             if (error instanceof StoredThenFailed) {
                 // Its note, as the success answer's: a deletion that cleared a
                 // conflict naming a disk file unlinked nothing.
                 const note = error.notes.get(relativePath);
-                return storedButUnfinished('delete', input.path, { storeFailed: error.message, pushes: error.pushes }, note === undefined ? null : `${note.charAt(0).toUpperCase()}${note.slice(1)}.`);
+                return storedButUnfinished('delete', input.path, { storeFailed: error.message, pushes: error.pushes }, note === undefined ? null : `${note.charAt(0).toUpperCase()}${note.slice(1)}.`, this.agreement?.awaitsReopen === true);
             }
-            return storedButUnfinished('delete', input.path, { threw: error instanceof Error ? error.message : String(error) });
+            return storedButUnfinished('delete', input.path, { threw: error instanceof Error ? error.message : String(error) }, null, this.agreement?.awaitsReopen === true);
         }
     }
     async handleLs(input) {
@@ -4758,7 +4937,7 @@ export class WorkspaceModule {
         // A path outside the mount's include that's no scope (refusesAsOutside)
         // is refused, as glob refuses it, and shown as given.
         if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
-            return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+            return { success: false, error: didNothing('ls', new OutsideIncludeError(input.path, mount.config).message), isError: true };
         }
         input = { ...input, path };
         const recursive = input.recursive === true;
@@ -4767,6 +4946,9 @@ export class WorkspaceModule {
         // shows disk's.
         const listing = await this.listingOf(mount, relativePath, recursive);
         const incomplete = listing.incomplete.length > 0 ? { incomplete: listing.incomplete } : {};
+        const empty = relativePath !== '' && listing.files.length === 0 && listing.dirs.length === 0 && listing.incomplete.length === 0;
+        const note = empty ? await this.emptyScopeNote(mount, relativePath, path) : null;
+        const noted = note !== null ? { note } : {};
         if (recursive) {
             return {
                 success: true,
@@ -4775,6 +4957,7 @@ export class WorkspaceModule {
                     entries: listing.files,
                     count: listing.files.length,
                     ...incomplete,
+                    ...noted,
                 },
             };
         }
@@ -4791,9 +4974,34 @@ export class WorkspaceModule {
                 entries: children,
                 count: children.length,
                 ...incomplete,
+                ...noted,
             },
         };
     }
+    async emptyScopeNote(mount, relativePath, path) {
+        const shown = JSON.stringify(path);
+        const isFile = `${shown} is a file, not a directory, so there's nothing in it to list.`;
+        const { view, rootReal } = await this.diskView(mount);
+        const seen = await observePath(view, rootReal, relativePath);
+        if (seen.kind === 'file')
+            return isFile;
+        if (seen.kind !== 'absent')
+            return null;
+        if (!mount.direct && this.getStore().treeGet(mount.treeStateId, relativePath) !== null)
+            return isFile;
+        return this.holdsAnythingAt(mount, relativePath) ? null : `${shown} isn't a directory in the workspace or on disk, so there's nothing to list.`;
+    }
+    async absentOnDisk(mount, relativePath) {
+        const { view, rootReal } = await this.diskView(mount);
+        return (await observePath(view, rootReal, relativePath)).kind === 'absent';
+    }
+    holdsAnythingAt(mount, relativePath) {
+        if (mount.direct)
+            return false;
+        const store = this.getStore();
+        const trees = [mount.treeStateId, this.intents.get(mount.config.name)?.treeStateId].filter((tree) => tree !== undefined);
+        return trees.some((tree) => store.treeGet(tree, relativePath) !== null || store.treeList(tree, `${relativePath}/`).length > 0);
+    }
     /**
      * What a listing shows of a directory scope, from where the mount keeps
      * what it reads: the store-backed kind's pass (listingFromStore), or, on a
@@ -4870,7 +5078,8 @@ export class WorkspaceModule {
             .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,
@@ -4895,7 +5104,7 @@ export class WorkspaceModule {
         if (input.path) {
             const { mount, relativePath, moved, root } = mountsToSearch[0];
             if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
-                return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+                return { success: false, error: didNothing('glob', new OutsideIncludeError(input.path, mount.config).message), isError: true };
             }
         }
         // Every match lies beneath the pattern's literal directory, so the walk
@@ -4916,7 +5125,7 @@ export class WorkspaceModule {
             if (prefixed) {
                 const dir = deeperOf(relativePath, prefixed.dir);
                 if (dir === null) {
-                    if (this.holderOf(mount.config.name, relativePath, false, moved)) {
+                    if (this.holderOf(mount.config.name, relativePath, moved)) {
                         incomplete.push({ path: `${mount.config.name}/${relativePath}`, reason: this.otherMountNote(mount.config.name, relativePath, 'list', moved) });
                         continue;
                     }
@@ -4952,8 +5161,16 @@ export class WorkspaceModule {
             regex = new RegExp(input.pattern);
         }
         catch (e) {
-            // The parser's reason says where the pattern goes wrong.
-            return { success: false, error: `The grep did nothing: ${e instanceof Error ? e.message : String(e)}.`, isError: true };
+            // V8's message ends with the parser's reason, after the pattern: "Invalid
+            // regular expression: /foo(/: Unterminated group".
+            const message = e instanceof Error ? e.message : String(e);
+            const why = /: ([^:/]+)$/.exec(message)?.[1] ?? message;
+            return {
+                success: false,
+                isError: true,
+                error: didNothing('grep', `"pattern" ${JSON.stringify(input.pattern)} isn't a valid regular expression (${why}). `
+                    + 'To match a character such as "(", "[" or "*" as itself, put "\\" before it.'),
+            };
         }
         const fileGlob = input.glob ? globToRegex(input.glob) : null;
         // The filter matches mount-relative paths, from the mount's root whatever
@@ -4979,7 +5196,7 @@ export class WorkspaceModule {
         if (input.path) {
             const { mount, relativePath, moved, root } = mountsToSearch[0];
             if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
-                return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+                return { success: false, error: didNothing('grep', new OutsideIncludeError(input.path, mount.config).message), isError: true };
             }
         }
         const results = [];
@@ -5002,10 +5219,6 @@ export class WorkspaceModule {
         const search = (text) => {
             const { lines, crlfEnds, lfEnds, bom } = fileText(text.bytes);
             const lineEndings = crlfEnds > 0 ? (lfEnds > 0 ? 'mixed' : 'CRLF') : undefined;
-            if (lineEndings !== undefined && !crlfFiles.has(text.file))
-                crlfFiles.set(text.file, { ends: lineEndings, version: text.version });
-            if (bom && !bomFiles.has(text.file))
-                bomFiles.set(text.file, text.version);
             const found = [];
             for (let i = 0; i < lines.length; i++) {
                 if (regex.test(lines[i])) {
@@ -5018,14 +5231,14 @@ export class WorkspaceModule {
                     found.push(match);
                 }
             }
-            return { ...(lineEndings !== undefined ? { lineEndings } : {}), matches: found };
+            return { ...(lineEndings !== undefined ? { lineEndings } : {}), matches: found, bom };
         };
         for (const { mount, relativePath, moved, root } of mountsToSearch) {
             // A path named in another mount's directory, as holderOf resolves it,
             // is that mount's: grep searches nothing of this mount's there, and
             // says whose it is. A direct mount's is judged by the nesting its parse
             // found where its root lies now (movedNesting).
-            if (this.holderOf(mount.config.name, relativePath, false, moved)) {
+            if (this.holderOf(mount.config.name, relativePath, moved)) {
                 incomplete.push({ path: `${mount.config.name}/${relativePath}`, reason: this.otherMountNote(mount.config.name, relativePath, 'list', moved) });
                 continue;
             }
@@ -5044,16 +5257,23 @@ export class WorkspaceModule {
             }
             const start = await this.walkStart(mount, relativePath, deeper === relativePath ? '' : deeper.slice(relativePath ? relativePath.length + 1 : 0));
             const searched = (text) => {
-                const hits = search(text);
-                if (hits.matches.length > 0)
-                    results.push({ file: text.file, ...(text.state !== undefined ? { state: text.state } : {}), version: text.version, ...hits });
+                const { bom, ...hits } = search(text);
+                const { file, state, version } = text;
+                return () => {
+                    if (hits.lineEndings !== undefined && !crlfFiles.has(file))
+                        crlfFiles.set(file, { ends: hits.lineEndings, version });
+                    if (bom && !bomFiles.has(file))
+                        bomFiles.set(file, version);
+                    if (hits.matches.length > 0)
+                        results.push({ file, ...(state !== undefined ? { state } : {}), version, ...hits });
+                };
             };
             const kept = prefixed
                 ? (path) => prefixed.regex.test(path)
                 : (path) => fileGlob === null || fileGlob.test(path)
                     || (byName && fileGlob.test(path.slice(path.lastIndexOf('/') + 1)));
             const found = mount.direct
-                ? await this.textsFromDisk(mount, relativePath, root, start, kept, searched)
+                ? await this.textsFromDisk(mount, relativePath, root, start, kept, (text) => searched(text)())
                 : await this.textsFromStore(mount, relativePath, start, kept, searched);
             skipped.push(...found.skipped);
             incomplete.push(...found.incomplete);
@@ -5102,12 +5322,13 @@ export class WorkspaceModule {
     /**
      * The texts a 'chronicle' mount's grep searches beneath `start`, or in the
      * single file `relativePath` names, those `keep` lets through, each handed
-     * to `each` in path order: a pass over the scope, then each path's
-     * workspace copy, labelled with its state, and a conflict's disk side.
+     * to `search`, whose answers are recorded in path order: a pass over the
+     * scope, then each path's workspace copy, labelled with its state, and a
+     * conflict's disk side.
      * What it doesn't search is in `skipped`, and what it couldn't see in
      * `incomplete`, each mount-prefixed.
      */
-    async textsFromStore(mount, relativePath, start, keep, each) {
+    async textsFromStore(mount, relativePath, start, keep, search) {
         const store = this.getStore();
         const skipped = [];
         const incomplete = [];
@@ -5160,17 +5381,18 @@ export class WorkspaceModule {
                 incomplete.push({ path: `${mount.config.name}/${region.path}`, reason: region.reason });
             }
             const intents = this.intents.get(mount.config.name);
+            const found = [];
             for (const report of [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path))) {
                 if (!keep(report.path))
                     continue;
                 const file = `${mount.config.name}/${report.path}`;
                 if (report.state === 'disk-only') {
-                    skipped.push({
-                        file,
-                        reason: 'disk-only: binary or over the size limit, never stored',
-                        ...(report.size !== undefined ? { size: report.size } : {}),
-                        ...(report.mimeType ? { mimeType: report.mimeType } : {}),
-                    });
+                    found.push({ skip: {
+                            file,
+                            reason: 'disk-only: binary or over the size limit, never stored',
+                            ...(report.size !== undefined ? { size: report.size } : {}),
+                            ...(report.mimeType ? { mimeType: report.mimeType } : {}),
+                        } });
                     continue;
                 }
                 // A path in another mount's directory is that mount's: grep gives
@@ -5180,17 +5402,16 @@ export class WorkspaceModule {
                     continue;
                 const refusal = refused.get(report.path);
                 if (refusal !== undefined) {
-                    skipped.push({ file, reason: refusal });
+                    found.push({ skip: { file, reason: refusal } });
                     continue;
                 }
                 // The workspace's version, labelled with the path's state.
                 const entry = store.treeGet(mount.treeStateId, report.path);
-                const blob = entry ? store.getBlob(entry.blobHash) : null;
-                if (blob) {
-                    each({ file, state: report.state, version: 'workspace', bytes: blob });
-                }
-                else if (entry) {
-                    skipped.push({ file, reason: 'the workspace copy is missing from the store, so it was not searched' });
+                if (entry) {
+                    const stored = storedBytes(store, entry.blobHash);
+                    found.push('bytes' in stored
+                        ? { searched: search({ file, state: report.state, version: 'workspace', bytes: stored.bytes }) }
+                        : { lost: { file, state: report.state, version: 'workspace', relativePath: report.path, hash: entry.blobHash, size: entry.size, what: 'saved' } });
                 }
                 if (report.state !== 'conflict')
                     continue;
@@ -5201,22 +5422,40 @@ export class WorkspaceModule {
                 // disk version was never stored either.
                 const disk = intents.get(report.path)?.conflict?.disk;
                 const changed = report.conflict?.diskChangedSinceRecorded === true;
-                const diskBlob = disk?.stored ? store.getBlob(disk.stored) : null;
-                if (diskBlob) {
-                    each({ file, state: report.state, version: changed ? 'recorded-disk' : 'conflicting-disk', bytes: diskBlob });
-                }
-                if (disk?.stored && !diskBlob) {
-                    skipped.push({ file, reason: 'conflict: the disk version recorded with the conflict is missing from the store, so it was not searched' });
+                if (disk?.stored) {
+                    const version = changed ? 'recorded-disk' : 'conflicting-disk';
+                    const stored = storedBytes(store, disk.stored);
+                    found.push('bytes' in stored
+                        ? { searched: search({ file, state: report.state, version, bytes: stored.bytes }) }
+                        : { lost: { file, state: report.state, version, relativePath: report.path, hash: disk.stored, size: disk.size, what: 'conflict-disk' } });
                 }
                 if (changed) {
                     if (report.diskNow === 'file') {
-                        skipped.push({ file, reason: 'conflict: disk changed since the conflict was recorded; grep searches stored text, so the file disk holds now was not searched' });
+                        found.push({ skip: { file, reason: 'conflict: disk changed since the conflict was recorded; grep searches stored text, so the file disk holds now was not searched' } });
                     }
                 }
                 else if (disk && !disk.stored) {
-                    skipped.push({ file, reason: 'conflict: the disk version is binary or over the size limit, never stored', size: disk.size });
+                    found.push({ skip: { file, reason: `conflict: the disk version is binary or over the size limit, so the workspace never stored it, and grep searches only what it stores; ${settleConflict('file', mount.config.mode === 'read-only').replace(/\.$/, '')}`, size: disk.size } });
                 }
             }
+            const answers = new Map();
+            await this.restoreEach(mount, found.flatMap((item) => ('lost' in item ? [item.lost] : [])), (lost, contents) => {
+                const { file, state, version, what } = lost;
+                answers.set(lost, 'bytes' in contents
+                    ? { searched: search({ file, state, version, bytes: contents.bytes }) }
+                    : { skip: {
+                            file,
+                            reason: `${what === 'saved' ? "the workspace's copy" : 'conflict: the disk version recorded with the conflict'} is ${lostInStore(contents.lost)}, `
+                                + `and ${lostOnDisk(contents.lost)}, so it was not searched`,
+                        } });
+            });
+            for (const item of found) {
+                const answer = 'lost' in item ? answers.get(item.lost) : item;
+                if ('searched' in answer)
+                    answer.searched();
+                else
+                    skipped.push(answer.skip);
+            }
         });
         return { skipped, incomplete };
     }
@@ -5261,7 +5500,7 @@ export class WorkspaceModule {
         const store = this.getStore();
         const status = {};
         if (input.mount !== undefined && !this.mounts.has(input.mount)) {
-            return { success: false, error: `Unknown mount: ${input.mount}`, isError: true };
+            return { success: false, error: didNothing('status', this.noSuchMountField(input.mount, 'covers every mount')), isError: true };
         }
         for (const [name, mount] of this.mounts) {
             if (input.mount !== undefined && name !== input.mount)
@@ -5403,9 +5642,6 @@ export class WorkspaceModule {
      */
     entriesByEvidence(mount) {
         const store = this.getStore();
-        const agreement = this.agreementOrThrow();
-        const name = mount.config.name;
-        const intents = this.intents.get(name);
         const owed = [];
         const unchecked = [];
         let agreed = 0;
@@ -5415,20 +5651,37 @@ export class WorkspaceModule {
             // in it: neither owed to disk nor counted as on it.
             if (!insideMount(e.path, mount.config.include) || !own(e.path))
                 continue;
-            const p = agreement.get(name, e.path);
-            if (p === undefined)
-                (intents.get(e.path)?.origin === 'store' ? owed : unchecked).push(e.path);
-            else if (p.kind !== 'content' || p.hash !== e.blobHash)
-                owed.push(e.path);
-            // A mode the store records, other than the one disk last agreed with,
-            // where modes are observed: elsewhere no push applies one.
-            else if (this.modesObserved && p.mode !== undefined && (entryMode(e.mode) ?? p.mode) !== p.mode)
+            const kind = this.evidenceOf(mount, e);
+            if (kind === 'owed')
                 owed.push(e.path);
+            else if (kind === 'unchecked')
+                unchecked.push(e.path);
             else
                 agreed++;
         }
         return { owed, unchecked, agreed };
     }
+    evidenceOf(mount, e) {
+        const p = this.agreementOrThrow().get(mount.config.name, e.path);
+        if (p === undefined)
+            return this.intents.get(mount.config.name).get(e.path)?.origin === 'store' ? 'owed' : 'unchecked';
+        if (p.kind !== 'content' || p.hash !== e.blobHash)
+            return 'owed';
+        // A mode the store records, other than the one disk last agreed with,
+        // where modes are observed: elsewhere no push applies one.
+        if (this.modesObserved && p.mode !== undefined && (entryMode(e.mode) ?? p.mode) !== p.mode)
+            return 'owed';
+        return 'agreed';
+    }
+    diskOf(mount, relativePath) {
+        const intent = this.intents.get(mount.config.name).get(relativePath);
+        if (intent?.conflict)
+            return 'in conflict with disk';
+        const entry = this.getStore().treeGet(mount.treeStateId, relativePath);
+        if (!entry)
+            return intent?.tombstone ? 'waits for materialize with applyDeletions' : 'done';
+        return this.evidenceOf(mount, { ...entry, path: relativePath }) === 'agreed' ? 'done' : 'waits for materialize';
+    }
     async handleMaterialize(input) {
         const store = this.getStore();
         const allWritten = [];
@@ -5436,24 +5689,27 @@ export class WorkspaceModule {
         const pendingDeletions = [];
         const modesKept = [];
         let explicit = 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)
             // is refused; beneath a directory, the push leaves out what the include
             // doesn't cover.
             if (await this.refusesAsOutside(parsed.mount, parsed.relativePath, parsed.moved, parsed.root)) {
-                return { success: false, error: new OutsideIncludeError(input.path, explicit.mount.config).message, isError: true };
+                return { success: false, error: didNothing('materialize', new OutsideIncludeError(input.path, explicit.mount.config).message), isError: true };
             }
         }
         let mountsToMaterialize;
         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: `Unknown mount: ${input.mount}`, isError: true };
+                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 };
             }
             mountsToMaterialize = [{ name: input.mount, mount: m }];
         }
@@ -5567,15 +5823,20 @@ export class WorkspaceModule {
         if (proceeded === 0 && guarded.length > 0 && guarded.length === mountsToMaterialize.length) {
             return {
                 success: false,
-                error: `Cannot materialize: ${blocked.map((b) => `[${b.mount}] ${b.reason}`).join('; ')}`,
+                error: didNothing('materialize', blocked.map((b) => `mount ${JSON.stringify(b.mount)}: ${b.reason}`).join('; ')),
                 isError: true,
             };
         }
+        const held = explicit;
+        const heldNothing = held !== null && held.relativePath !== '' && !held.mount.direct
+            && allWritten.length === 0 && allDeleted.length === 0 && pendingDeletions.length === 0 && blocked.length === 0 && passedOver.length === 0
+            && !this.holdsAnythingAt(held.mount, held.relativePath);
         return {
             success: true,
             data: {
                 materialized: allWritten,
                 count: allWritten.length,
+                ...(heldNothing ? { note: `The workspace holds nothing at ${JSON.stringify(`${held.mount.config.name}/${held.relativePath}`)}, so there was nothing to write there.` } : {}),
                 ...(allDeleted.length > 0 ? { deleted: allDeleted } : {}),
                 ...(pendingDeletions.length > 0
                     ? {
@@ -5637,24 +5898,32 @@ export class WorkspaceModule {
         const allIgnored = [];
         const rootsAccepted = [];
         if (input.acceptRoot && input.path) {
-            return { success: false, error: 'acceptRoot takes a whole mount\'s root: give mount, or nothing, not path', isError: true };
+            const named = input.path.split('/')[0];
+            return {
+                success: false,
+                isError: true,
+                error: didNothing('sync', `acceptRoot takes a whole mount's root, so it isn't given with "path" (${JSON.stringify(input.path)}). `
+                    + `${this.mounts.has(named) ? `Give "mount" (${JSON.stringify(named)}) with acceptRoot to take that mount's root` : 'Give "mount", naming the mount whose root to take, with acceptRoot'}, or leave acceptRoot out to sync the path.`),
+            };
         }
         // A path names its own mount; otherwise the given mount, or every mount.
         let targets;
-        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
             // doesn't cover.
             if (await this.refusesAsOutside(mount, relativePath, moved, root)) {
-                return { success: false, error: new OutsideIncludeError(input.path, mount.config).message, isError: true };
+                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: `Unknown mount: ${input.mount}`, isError: true };
+                return { success: false, error: didNothing('sync', this.noSuchMountField(input.mount, 'covers every mount')), isError: true };
             }
             targets = [{ name: input.mount, mount: m, relativePath: '' }];
         }
@@ -5668,6 +5937,7 @@ export class WorkspaceModule {
                 allSkipped.push({ mount: name, path: relativePath, reason: DIRECT_SYNC_SKIPPED });
                 continue;
             }
+            let namedDirectory = false;
             const pass = await this.withMount(mount, async () => {
                 if (input.acceptRoot && await this.acceptRootUnlocked(mount))
                     rootsAccepted.push(name);
@@ -5682,6 +5952,7 @@ export class WorkspaceModule {
                     store.treeList(mount.treeStateId, prefix).length > 0 ||
                     this.agreementOrThrow().paths(name, relativePath).some(([p]) => p.startsWith(prefix)) ||
                     this.intents.get(name).list(relativePath).some(([p]) => p.startsWith(prefix));
+                namedDirectory = (await directoryAt(join(mount.config.path, relativePath), mount.config.followSymlinks === true)) ?? isDir;
                 // named: ignore patterns covering the path asked for don't apply
                 // beneath it (a directory scope's walk; a path scope doesn't walk).
                 const opts = { rehash: true, adopt: () => true, branchId: askedOn, named: true };
@@ -5730,7 +6001,7 @@ export class WorkspaceModule {
             // 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' });
@@ -5745,7 +6016,7 @@ export class WorkspaceModule {
             // without a path passes over it, so nothing else keeps it current
             // (agent-framework #276). A path in another mount's directory isn't
             // synced at all, and the note says so.
-            const passedOver = passedOverAt(relativePath, this.ignoreOf(mount), this.othersOf(name));
+            const passedOver = passedOverAt(relativePath, this.ignoreOf(mount), this.othersOf(name), namedDirectory);
             if (passedOver !== undefined) {
                 allIgnored.push({
                     mount: name,
@@ -5758,10 +6029,17 @@ export class WorkspaceModule {
                 });
             }
         }
+        const named = input.path !== undefined && input.path !== '' ? targets[0] : null;
+        const nothingThere = named !== null && named.relativePath !== '' && !named.mount.direct
+            && allResults.every((r) => r.synced.length === 0 && r.conflicts.length === 0 && (r.discarded?.length ?? 0) === 0)
+            && allSkipped.length === 0 && allIncomplete.length === 0 && allIgnored.length === 0
+            && !this.holdsAnythingAt(named.mount, named.relativePath)
+            && await this.absentOnDisk(named.mount, named.relativePath);
         return {
             success: true,
             data: {
                 results: allResults,
+                ...(nothingThere ? { note: `Neither the workspace nor disk has anything at ${JSON.stringify(`${named.name}/${named.relativePath}`)}, so there was nothing to sync.` } : {}),
                 totalSynced: allResults.reduce((sum, r) => sum + r.synced.length, 0),
                 totalConflicts: allResults.reduce((sum, r) => sum + r.conflicts.length, 0),
                 ...(allSkipped.length > 0 ? { skipped: allSkipped } : {}),
@@ -6007,13 +6285,13 @@ export async function inOrder(items, width, work, each) {
     }
 }
 /** read_image's answer for an image, wherever it was read from. */
-function imageResult(path, image) {
+function imageResult(path, image, note) {
     return {
         success: true,
         data: [
             {
                 type: 'text',
-                text: `Path: ${path}\nMIME: ${image.mimeType}\nBytes: ${image.bytes.byteLength}`,
+                text: `Path: ${path}\nMIME: ${image.mimeType}\nBytes: ${image.bytes.byteLength}${note === undefined ? '' : `\n${note}`}`,
             },
             {
                 type: 'image',
@@ -6067,14 +6345,16 @@ function watchOf(config) {
  * add to what keeps it off direct; refused, what's held only shrinks, and
  * the next start once none is held runs it direct.
  */
-function writeRefusal(mount) {
+function writeRefusal(mount, writable = []) {
     const name = mount.config.name;
-    if (mount.config.mode === 'read-only')
-        return `Mount "${name}" is read-only`;
+    if (mount.config.mode === 'read-only') {
+        return `mount "${name}" is read-only. ${onlyTheHost('make it read-write')}`
+            + (writable.length > 0 ? ` The mounts that take writes are ${listed(writable.map((other) => JSON.stringify(other)))}.` : '');
+    }
     if (mount.config.backend === 'direct' && !mount.direct) {
-        return `Mount "${name}" is configured direct, and runs as 'chronicle' this session because its start found the store holding changes there that disk lacks, `
+        return `mount "${name}" is configured direct, and runs as 'chronicle' this session because its start found the store holding changes there that disk lacks, `
             + `so it takes no writes this session, and calling again is refused the same way. To run it direct again, settle what's held `
-            + `(sync each held path to take disk's copy, or materialize mount "${name}" by name to write the store's copies to disk), and the host's next start runs it direct`;
+            + `(sync each held path to take disk's copy, or materialize mount "${name}" by name to write the store's copies to disk), and the host's next start runs it direct.`;
     }
     return null;
 }
@@ -6150,6 +6430,23 @@ function directReason(error) {
         return ROOT_MOVED;
     return error instanceof Error ? error.message : String(error);
 }
+function directWayOn(error) {
+    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, path, error) {
+    const on = directWayOn(error);
+    return didNothing(tool, `${directReason(error)}.${on !== null ? ` ${on}` : ''}`, path);
+}
 /** "a", "a and b", or "a, b and c". */
 function listed(items) {
     return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`;
@@ -6172,7 +6469,114 @@ function linksNote(path, staged, tool) {
  */
 function containedRefusal(err, path) {
     const bare = err instanceof WorkspaceReadError && err.errno !== undefined && err.message === `Unable to read file: ${path}`;
-    return bare ? `${err.message} (${err.errno})` : err instanceof Error ? err.message : String(err);
+    return bare ? `${err.message} (${errnoWords(err.errno)})` : err instanceof Error ? err.message : String(err);
+}
+function deletedOnDisk(path) {
+    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, note, cause) {
+    if (note === DIRECTORY)
+        return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
+    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, mount) {
+    return `${JSON.stringify(path)} names the root of mount "${mount}", which isn't a file; ls "${mount}" lists the files in it.`;
+}
+function tooLargeToWrite(path, bytes, maxSize) {
+    return pastSizeLimit(`${JSON.stringify(path)} would be ${bytes.toLocaleString('en-US')} bytes`, maxSize, "the workspace couldn't keep it", 'Content within the limit is written.');
+}
+function pastSizeLimit(what, maxSize, outcome, within) {
+    return `${what}, past the ${maxSize.toLocaleString('en-US')}-byte limit this mount sets on a file, so ${outcome}.${within !== null ? ` ${within}` : ''} `
+        + "The limit is the mount's maxFileSize setting, which only whoever runs the host can change.";
+}
+function sentence(text) {
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+function unreadable(shown, errno) {
+    return `${shown} can't be read from disk: ${errnoWords(errno)}. ${errnoWayOn(errno)}`;
+}
+function readRefusal(err, path) {
+    const shown = JSON.stringify(path);
+    if (err instanceof RootUnavailable) {
+        if (err.refusal)
+            return err.refusal.message;
+        const mount = JSON.stringify(err.mount);
+        if (err.reason === ROOT_UNAVAILABLE || err.reason === null) {
+            if (err.errno === 'ENOENT' || err.errno === 'ENOTDIR') {
+                return `the directory of mount ${mount} isn't on disk, so nothing in it can be read. ${onlyTheHost("put the mount's directory back at its path")}`;
+            }
+            if (err.errno !== undefined) {
+                return `the directory of mount ${mount} can't be read: ${errnoWords(err.errno)}. `
+                    + errnoWayOn(err.errno, ROOT_RECHECK, true);
+            }
+            return `the directory of mount ${mount} can't be checked at its path, so nothing in it can be read. ${ROOT_RECHECK}`;
+        }
+        return `${shown} can't be read: ${sentence(err.reason)}`;
+    }
+    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; ${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; ${MOUNT_IT}.`;
+        case 'changed':
+            return `${shown} changed on disk while it was being read. Calling again reads it afresh.`;
+        case 'not_found':
+            if (err.errno === 'ENOENT' || err.errno === 'ENOTDIR')
+                return `there's no file at ${shown}. ls or glob lists the files that exist.`;
+            if (err instanceof NotRegularFile) {
+                return `${shown} isn't a regular file (it's a pipe, a socket or a device), so the workspace doesn't read it. ${onlyTheHost('put a regular file there')}`;
+            }
+            if (err.stage === 'realpath')
+                return `where ${shown} leads on disk can't be resolved: ${errnoWords(err.errno)}. ${errnoWayOn(err.errno)}`;
+            return unreadable(shown, err.errno);
+        default:
+            return sentence(err.message);
+    }
+}
+function contentsSubject(what, path) {
+    return what === 'saved' ? `the saved contents of ${path}` : `the version of ${path} that its conflict recorded as disk's`;
+}
+function inTheStore(stored) {
+    return 'missing' in stored ? "missing from the workspace's store" : `unreadable in the workspace's store (${stored.unreadable})`;
+}
+function lostInStore(lost) {
+    return 'missing' in lost.store ? 'missing from the store' : `unreadable in the store (${lost.store.unreadable})`;
+}
+function lostOnDisk(lost) {
+    return lost.disk === 'other' ? "disk's copy holds other contents"
+        : lost.disk === 'none' ? 'disk has no copy'
+            : `disk's copy can't be read (${lost.disk.unreadable})`;
+}
+function lostText(lost, the = 'The') {
+    return `${the} workspace's copy of ${lost.path} is ${lostInStore(lost)}, and ${lostOnDisk(lost)}`;
+}
+function nothingToRead(lost) {
+    return `${lostText(lost, 'the')}, so it can't be restored or read. ${lostRemedy(lost)}`;
+}
+function lostRemedy(lost) {
+    const after = remedyOfLost(lost);
+    if (!lost.reopen)
+        return after;
+    return "Nothing you do clears this until the workspace's store is reopened, and calling again won't change that; whoever runs this host can reopen it with a restart. "
+        + `After that, ${after.charAt(0).toLowerCase()}${after.slice(1)}`;
+}
+function remedyOfLost(lost) {
+    const rewrite = lost.writable && 'missing' in lost.store;
+    if (lost.disk === 'other')
+        return `Sync the path to keep disk's copy and give up the workspace's${rewrite ? ', or write the file again' : ''}.`;
+    if (lost.writable)
+        return rewrite ? 'Write the file again, or delete it.' : 'Delete the file to clear it.';
+    return lost.disk === 'none'
+        ? "Sync the path to take disk's deletion, which removes the workspace's copy."
+        : "Once disk's copy can be read, read the file again, which reads it from disk's copy if that copy has the same contents, or sync the path to keep disk's copy and give up the workspace's.";
 }
 /**
  * The notice that writes an agent made direct remain on disk from
@@ -6183,7 +6587,7 @@ function containedRefusal(err, path) {
  */
 function headMoveText(mounts) {
     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.';
 }
@@ -6229,9 +6633,7 @@ function planTargetEdits(tool, target, bytes, hints, maxSize, counts, problems)
             kind: 'file',
             edits: target.edits,
             path: target.path,
-            text: `${target.path} would be ${size} bytes with ${tool === 'edit' ? 'this edit' : editList(target.edits)}, `
-                + `past the ${maxSize.toLocaleString('en-US')}-byte limit this mount sets on a file, so the workspace couldn't keep it. `
-                + "An edit that leaves the file within the limit applies. The limit is the mount's maxFileSize setting, which only whoever runs the host can change.",
+            text: pastSizeLimit(`${target.path} would be ${size} bytes with ${tool === 'edit' ? 'this edit' : editList(target.edits)}`, maxSize, "the workspace couldn't keep it", 'An edit that leaves the file within the limit applies.'),
             whole: false,
         });
         return null;
@@ -6267,16 +6669,38 @@ function changesLanded(store, treeStateId, changes, setError) {
  * change is stored isn't known. Its message says so after both errors.
  */
 class CommitUnknownError extends Error {
-    setError;
-    readError;
-    constructor(setError, readError) {
+    setCause;
+    readCause;
+    constructor(setCause, readCause) {
         const text = (error) => (error instanceof Error ? error.message : String(error));
-        super(`${text(setError)}; reading its entries back failed too (${text(readError)}), so whether the change is stored isn't known`);
+        super(`${text(setCause)}; reading its entries back failed too (${text(readCause)}), so whether the change is stored isn't known`);
+        this.setCause = setCause;
+        this.readCause = readCause;
         this.name = 'CommitUnknownError';
-        this.setError = text(setError);
-        this.readError = text(readError);
     }
 }
+function storeWords(error) {
+    const code = errnoCode(error);
+    return code !== undefined ? errnoWords(code) : cutLine(error instanceof Error ? error.message : String(error));
+}
+class NotStored extends Error {
+    thrown;
+    constructor(thrown) {
+        super('stopped before the change was stored');
+        this.thrown = thrown;
+    }
+}
+class AlreadyHeld extends Error {
+    thrown;
+    constructor(thrown) {
+        super(thrown instanceof Error ? thrown.message : String(thrown));
+        this.thrown = thrown;
+    }
+}
+function notStored(error) {
+    return error instanceof Refusal || error instanceof WorkspaceReadError || error instanceof CommitUnknownError || error instanceof AlreadyHeld || error instanceof NotStored
+        ? error : new NotStored(error);
+}
 /**
  * A store's set that threw after recording the change (changesLanded): the
  * entries are set and their intents follow, and the store's error goes on in
@@ -6293,6 +6717,11 @@ class StoredThenFailed extends Error {
         this.name = 'StoredThenFailed';
     }
 }
+const ONCE_REOPENED = ', once the store is reopened';
+const DISK_ORDER = ['in conflict with disk', 'waits for materialize with applyDeletions', 'waits for materialize', 'done'];
+function furthestFromDisk(values) {
+    return DISK_ORDER.find((state) => values.includes(state)) ?? 'done';
+}
 /**
  * The answer to a write, edit or delete that the workspace stored but
  * couldn't finish: its push to disk didn't complete, or what follows the tree
@@ -6304,7 +6733,7 @@ class StoredThenFailed extends Error {
  * script. A note comes last: an edit's on which copy it applied to, or a
  * deletion's that it unlinked nothing.
  */
-function storedButUnfinished(tool, path, outcome, note = null) {
+function storedButUnfinished(tool, path, outcome, note = null, reopen = false) {
     const change = tool === 'delete' ? 'deletion' : tool;
     const stored = `The ${change} of "${path}" is stored in the workspace, so don't send it again`
         + (tool === 'edit' ? ': a second edit can apply the change twice.' : '.');
@@ -6313,10 +6742,10 @@ function storedButUnfinished(tool, path, outcome, note = null) {
         : 'storeFailed' in outcome
             ? ` The store failed after recording it: ${outcome.storeFailed}.` + (!outcome.pushes ? ''
                 : tool === 'delete'
-                    ? ' Its push to disk didn\'t run, so disk keeps the file until a materialize of the path with applyDeletions deletes it.'
-                    : ' Its push to disk didn\'t run, so disk lacks the change until a materialize of the path writes it.')
-            : ` The rest of the call failed: ${outcome.threw}. ls shows the path's state.`;
-    return { success: false, isError: true, error: stored + rest + (note !== null ? ` ${note}` : '') };
+                    ? ` Its push to disk didn't run, so disk keeps the file until a materialize of the path with applyDeletions deletes it${reopen ? ONCE_REOPENED : ''}.`
+                    : ` Its push to disk didn't run, so disk lacks the change until a materialize of the path writes it${reopen ? ONCE_REOPENED : ''}.`)
+            : ` The rest of the call failed: ${outcome.threw}.${reopen ? '' : " ls shows the path's state."}`;
+    return { success: false, isError: true, error: stored + rest + (reopen ? ` ${AWAITS_REOPEN}` : '') + (note !== null ? ` ${note}` : '') };
 }
 /**
  * What a read says about the copy it shows, when that isn't simply the one the
@@ -6345,18 +6774,22 @@ function whichCopyRead(report, tookChange, readOnly) {
         // can hold it (not binary or too large). A read-only mount can hold a
         // copy disk doesn't, such as one a branch switch selected, but a
         // materialize, forced or not, writes nothing to it.
-        const sync = report.diskNow === 'absent'
-            ? 'Sync the path to take disk\'s deletion, which removes the workspace\'s copy'
-            : 'Sync the path to keep disk\'s copy and give up the workspace\'s';
-        const force = readOnly
-            ? '. The mount is read-only, so nothing writes the workspace\'s copy to disk.'
-            : report.diskNow === 'absent'
-                ? ', or materialize it with force to write the workspace\'s copy back to disk.'
-                : ', or materialize it with force to write the workspace\'s over disk\'s.';
-        return [`The path is in conflict with disk (${kind}): this read shows the workspace's copy. ${sync}${force}`];
+        const settle = settleConflict(report.diskNow, readOnly);
+        return [`The path is in conflict with disk (${kind}): this read shows the workspace's copy. ${settle[0].toUpperCase()}${settle.slice(1)}`];
     }
     return [];
 }
+function settleConflict(diskNow, readOnly) {
+    const sync = diskNow === 'absent'
+        ? 'sync the path to take disk\'s deletion, which removes the workspace\'s copy'
+        : 'sync the path to keep disk\'s copy and give up the workspace\'s';
+    const force = readOnly
+        ? '. The mount is read-only, so nothing writes the workspace\'s copy to disk.'
+        : diskNow === 'absent'
+            ? ', or materialize it with force to write the workspace\'s copy back to disk.'
+            : ', or materialize it with force to write the workspace\'s over disk\'s.';
+    return `${sync}${force}`;
+}
 /**
  * The least each tool's whole-number fields may be, beside their schemas,
  * whose type (membrane's ToolParameter) has no `minimum`.
@@ -6548,13 +6981,13 @@ function globToRegex(pattern) {
                     closeIdx = j;
             }
             if (closeIdx < 0)
-                throw new Error(braceRefusal(pattern, 'has a "{" with no closing "}"'));
+                throw new Refusal(braceRefusal(pattern, 'has a "{" with no closing "}"'));
             const group = pattern.slice(i + 1, closeIdx);
             if (group.includes('{')) {
-                throw new Error(braceRefusal(pattern, 'has a "{" group inside another; put all its alternatives in one group'));
+                throw new Refusal(braceRefusal(pattern, 'has a "{" group inside another; put all its alternatives in one group'));
             }
             if (!group.includes(',')) {
-                throw new Error(braceRefusal(pattern, 'has a "{" group with no ","; a group needs two or more alternatives, separated by ","'));
+                throw new Refusal(braceRefusal(pattern, 'has a "{" group with no ","; a group needs two or more alternatives, separated by ","'));
             }
             // A `/` right after the group goes into each alternative, as `{a,b}/x`
             // and `{a/,b/}x` name the same paths, so an alternative's own `**`