@animalabs/agent-framework 0.26.2 → 0.28.0

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

@@ -9,15 +9,24 @@ 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, LEAVES_MOUNT, NONBLOCK, NOT_FOLLOWED, NOT_REGULAR, OTHER_MOUNT, OUTSIDE_INCLUDE, ROOT_REPLACED, ROOT_UNAVAILABLE, beneathRoot, checkDir, checkRoot, confirmAbsent, coversLanding, directoryAt, diskSpelling, filesystemTrustsCtime, foldsCase, inOtherMount, insideMount, leadsInto, linkOnTheWay, linkRefusal, linkWords, locateRoot, looksBinary, namesHolder, nestedAtReal, nestedGuess, nestedHolder, nestedStep, observePath, parsedSpelling, passedOverAt, pathSegments, patternRefusal, readBytes, readPrefix, 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';
 import { cutLine, editList, editReceipt, fitted, refusalText } from './edit-text.js';
+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 { EffectFailed, unlinkContained } from './effects.js';
+import { AWAITS_REOPEN, ROOT_RECHECK, ROOT_UNCHECKED, Refusal, changesFiles, didNothing, errnoCode, errnoWayOn, errnoWords, hostFix, onlyTheHost, systemWords, unexpectedAnswer } from './answers.js';
+import { unknownToolMessage } from '../unknown-tool.js';
+import { closestNames } from '../../closest-names.js';
+import { RecordJournal } from '../../record-journal.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;
 /**
@@ -30,10 +39,15 @@ const AGENT_ACTION_SCAN_DEADLINE_MS = 20_000;
 const CATCH_UP_BOUND_MS = 30_000;
 /** Why a call is refused once the module has stopped. */
 const NOT_RUNNING = 'The workspace has stopped: it takes no more work until it starts again';
+/** writeBinary's refusal when the store's branch is no longer the one its file is for. */
+const BRANCH_LEFT = 'the workspace had left the branch this file is for';
 /** The workspace's own deadline must end before the framework's hook bound. */
 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
@@ -44,16 +58,25 @@ const DIRECT_MOUNT_IGNORE = ['node_modules', 'dist', '.git', 'build', 'coverage'
 const DIRECT_READS_AT_ONCE = 16;
 /** Why sync passes over a direct mount, as its result's `skipped` says. */
 const DIRECT_SYNC_SKIPPED = "a direct mount: its tools read disk as it is, so there's nothing to take in";
-class WorkspaceImageReadError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
+/** 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 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.');
@@ -64,9 +87,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;
     }
 }
 /**
@@ -88,6 +119,22 @@ 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 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
@@ -102,23 +149,9 @@ function errnoOf(err) {
         ? 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]);
@@ -134,9 +167,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);
 }
@@ -170,7 +200,7 @@ async function linkReadError(mount, found, mountPrefixedPath, relativePath, nest
     const reason = `${mountPrefixedPath}: ${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');
 }
@@ -201,28 +231,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;
@@ -288,7 +317,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) {
@@ -624,21 +653,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);
@@ -646,9 +675,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';
@@ -674,14 +703,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. */
@@ -707,6 +733,23 @@ export class WorkspaceModule {
      * ensureRunning to say once both halves of the lifecycle have run.
      */
     notDirect = new Map();
+    /**
+     * Each agent's latest direct write on each mount it wrote direct, P, with
+     * the notice of its departure from it, N (DirectHead), by mount, then by
+     * agent. Saved at stop() in a global record (headsJournal), not the
+     * module's branch state: they describe disk, which doesn't rewind with a
+     * branch, so a restart on another branch, such as one an offline rollback
+     * made, still finds them.
+     */
+    directHeads = new Map();
+    /** Where directHeads is saved and loaded (DIRECT_HEADS_RECORD_TYPE), once initStore() has read it. */
+    headsJournal = null;
+    /** The record initStore() read, as saved text, so a stop that would save the same adds none; null where there's one to replace. */
+    loadedHeads = null;
+    /** Saved entries this session doesn't take up (another root, a mount not configured direct, or none), kept for the next save. */
+    carriedHeads = [];
+    /** Whether an agent's history holds a message, as the framework hands it over (useHistory). */
+    historyLookup = null;
     constructor(config) {
         for (const mount of config.mounts) {
             const cap = mount.walkCap;
@@ -721,20 +764,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}`);
+                    }
                 }
             }
         }
@@ -755,8 +797,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`);
             }
@@ -830,9 +872,64 @@ export class WorkspaceModule {
         this.agreement = new DiskAgreement(store, { modesObserved: () => this.modesObserved });
         this.agreement.open(this.config.mounts.filter((m) => intents.has(m.name)).map((m) => ({ name: m.name, root: resolve(m.path) })));
         this.chooseKinds();
+        this.loadDirectHeads(store);
         this.applySavedState();
         this.ensureRunning();
     }
+    /**
+     * The positions stop() last saved (directHeads), before any call can
+     * write: each saved entry is a mount's positions at one root, and a mount
+     * this session configures direct gets the entry at its own root. Every
+     * other entry, a mount configured at another root, not direct, or not at
+     * all, is kept for the next save (carriedHeads), since its writes are
+     * still on disk beneath that root; a mount removed for good, and each
+     * root a mount has moved from, leave that small entry behind. A record
+     * the store can't read is logged, and this session starts with none and
+     * saves none, so the record stands for a session that can read it. One
+     * read but not of the shape saved is logged too, and this session starts
+     * with none and its stop replaces it, so a damaged record doesn't keep
+     * every later session from saving. Either way, a move away from the
+     * writes before it goes untold, as after a crash.
+     */
+    loadDirectHeads(store) {
+        const journal = new RecordJournal(store, { type: DIRECT_HEADS_RECORD_TYPE });
+        const restored = new Map();
+        const carried = [];
+        let loaded;
+        try {
+            loaded = journal.load().snapshot;
+        }
+        catch (err) {
+            console.error('[workspace] could not read the saved direct-write positions:', err);
+            return;
+        }
+        let snapshot;
+        let text;
+        try {
+            snapshot = checkedHeads(loaded === null || loaded === undefined ? [] : loaded);
+            text = canonicalHeads(snapshot);
+        }
+        catch (err) {
+            console.error("[workspace] the saved direct-write positions aren't of the shape saved, so this session starts with none and its stop replaces them:", err);
+            snapshot = [];
+            text = null;
+        }
+        for (const saved of snapshot) {
+            // Only a direct mount's writes are the agent's on disk, and a
+            // store-backed one's disk follows its store.
+            const mount = this.mounts.get(saved.mount);
+            if (!mount || mount.config.backend !== 'direct' || saved.root !== resolve(mount.config.path)) {
+                carried.push(saved);
+                continue;
+            }
+            restored.set(saved.mount, new Map(Object.entries(saved.agents).map(([agent, head]) => [agent, { branchId: head.branchId, after: head.after, notice: head.notice ?? null }])));
+        }
+        this.headsJournal = journal;
+        this.loadedHeads = text;
+        this.carriedHeads = carried;
+        for (const [name, heads] of restored)
+            this.directHeads.set(name, heads);
+    }
     /**
      * Whether each mount configured direct runs direct: not while the store
      * holds changes there that disk lacks, on the branch selected then, so
@@ -985,7 +1082,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')
@@ -1043,11 +1140,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();
@@ -1160,7 +1256,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
@@ -1318,8 +1415,8 @@ export class WorkspaceModule {
         const message = (one
             ? "A mount configured direct runs as 'chronicle' this session. To start it direct, settle each held change, then start it again: "
             : "Mounts configured direct run as 'chronicle' this session. To start a mount direct, settle each change held at it, then start it again: ") +
-            "sync its path to take disk's copy, or configure the mount 'chronicle' and read-write, materialize it, " +
-            `follow the answer, and restore its direct config. ${intents}${which}: ${held.slice(0, 10).join(', ')}` +
+            "sync its path to take disk's copy, or materialize it by name, a read-only one configured read-write first, " +
+            `and follow the answer. Meanwhile it takes no writes. ${intents}${which}: ${held.slice(0, 10).join(', ')}` +
             `${held.length > 10 ? `, and ${held.length - 10} more` : ''}.`;
         console.warn(`[workspace] ${message}`);
         this.ctx?.notifyOps?.('workspace-mount-not-direct', 'framework', message, { held: Object.fromEntries(mounts.map(([name, paths]) => [name, paths.length])) });
@@ -1388,26 +1485,76 @@ export class WorkspaceModule {
             }
             this.ctx.setState(state);
         }
+        this.saveDirectHeads();
         this.ctx = null;
     }
-    /** Mount names + modes, and each mount's include where it sets one, for
-     *  peer callers (framework spill/journal paths) that need a mount for files
-     *  of their own, the first writable one without an include
-     *  (firstWritableMountName), without reaching into private state. */
+    /**
+     * Save directHeads as one global record, the latest of which the next
+     * start loads (loadDirectHeads): each mount's positions with the root
+     * they were made under, and the entries this session didn't take up
+     * (carriedHeads), unchanged. Only when that differs from what the
+     * start loaded, so a session that changed nothing, or a store no direct
+     * write reached, adds no record, and always where the record read wasn't
+     * of the shape saved, which this replaces. Nothing where the store couldn't
+     * read the record, so it stands. A save that fails is logged, and the next
+     * start finds the positions of the last save that landed, as after a
+     * crash.
+     */
+    saveDirectHeads() {
+        if (!this.headsJournal)
+            return;
+        const snapshot = [
+            ...this.carriedHeads,
+            ...[...this.directHeads].filter(([, heads]) => heads.size > 0).map(([name, heads]) => ({
+                mount: name,
+                root: resolve(this.mounts.get(name).config.path),
+                agents: Object.fromEntries([...heads].map(([agent, { branchId, after, notice }]) => [agent, { branchId, after, ...(notice !== null ? { notice } : {}) }])),
+            })),
+        ];
+        const text = canonicalHeads(snapshot);
+        if (text === this.loadedHeads)
+            return;
+        try {
+            this.headsJournal.checkpoint(snapshot);
+            this.loadedHeads = text;
+        }
+        catch (err) {
+            console.error('[workspace] could not save the direct-write positions:', err);
+        }
+    }
+    /** Mount names + modes, each mount's include where it sets one, and
+     *  `backend: 'direct'` for one configured direct, whether it runs direct
+     *  this session or, while the store holds work there disk lacks, as
+     *  'chronicle': either way it's a directory agents write directly when it
+     *  runs direct, whose files an undo leaves. For the
+     *  framework's tool-result spills, saved payloads and fetched references,
+     *  which need a mount for files of their own: the first writable one
+     *  without an include that isn't direct (firstWritableMountName), without
+     *  reaching into private state. */
     getMounts() {
         return [...this.mounts.values()].map((m) => ({
             name: m.config.name,
-            mode: m.config.mode === 'read-only' ? 'read-only' : 'read-write',
+            // Read-only where this session takes no writes there (writeRefusal).
+            mode: writeRefusal(m) === null ? 'read-write' : 'read-only',
             ...(m.config.include ? { include: [...m.config.include] } : {}),
+            ...(m.config.backend === 'direct' ? { backend: 'direct' } : {}),
         }));
     }
     // ==========================================================================
     // Tool Definitions
     // ==========================================================================
+    /**
+     * Whether any of this host's mounts runs direct. The tools' descriptions
+     * and grep's notes mention direct mounts only on such a host, so both ask
+     * this one question.
+     */
+    anyRunsDirect() {
+        return [...this.mounts.values()].some((m) => m.direct);
+    }
     getTools() {
         // Where a mount runs direct, four descriptions say what that changes.
         // A host with none keeps them as they were, and its residents' caches.
-        const direct = [...this.mounts.values()].some((m) => m.direct);
+        const direct = this.anyRunsDirect();
         const lsDirect = direct
             ? ' A direct mount (ls without a path says which, with its ignore list) lists disk\'s files as they are now: each with '
                 + 'its size and no state, or a note where the mount doesn\'t take it. A path its ignore list covers is listed when you name it.'
@@ -1418,6 +1565,23 @@ export class WorkspaceModule {
             : '';
         const globDirect = direct ? ' On a direct mount, a match carries its size, or a note where the mount doesn\'t take it, and no state.' : '';
         const syncDirect = direct ? ' A direct mount is listed under `skipped`: its tools read disk as it is, so there\'s nothing to take in.' : '';
+        // Where a direct mount is writable, the four writing tools say what a
+        // write is there: on disk when it answers, and left there by a head move.
+        const writable = [...this.mounts.values()].some((m) => m.direct && m.config.mode !== 'read-only');
+        const writeDirect = writable
+            ? ' On a direct mount, the file is on disk, whole and with its mode kept, when the call answers, and an undo or other head move leaves it there.'
+            : '';
+        const editDirect = writable
+            ? " On a direct mount, the edit applies to disk's text as it is now and is on disk when the call answers; a change another writer makes "
+                + 'meanwhile is kept, with the edit applied again on top of it, and an undo or other head move leaves the edit on disk.'
+            : '';
+        const editManyDirect = writable
+            ? " On a direct mount, every edit is checked against disk's text before any file is written, and then the files are written one by one: "
+                + "if a write fails partway, the answer names which files were written and which weren't, and nothing puts the written ones back. "
+                + 'An undo or other head move leaves them on disk.'
+            : '';
+        const deleteDirect = writable ? ' On a direct mount, the file is removed from disk at once, and an undo or other head move doesn\'t bring it back.' : '';
+        const materializeDirect = writable ? ' A direct mount writes its files to disk as they\'re made, so materialize passes over it, under `skipped` where you name it.' : '';
         return [
             {
                 name: 'read',
@@ -1451,7 +1615,7 @@ export class WorkspaceModule {
             },
             {
                 name: 'write',
-                description: 'Create or overwrite a file in the workspace.',
+                description: 'Create or overwrite a file in the workspace.' + writeDirect,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1472,7 +1636,7 @@ export class WorkspaceModule {
                     + "Only the replaced text changes, and the new text's line ends take those of the text it replaces. "
                     + 'A change disk made to the file is taken in first, and the answer says so. '
                     + 'The answer shows the changed region, numbered, a long line from shortly before the change on it, as its length allows. '
-                    + 'For several edits at once, in one file or across files, applied all or none, use edit_many.',
+                    + 'For several edits at once, in one file or across files, applied all or none, use edit_many.' + editDirect,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1494,7 +1658,8 @@ export class WorkspaceModule {
                     + "A refusal names the problems it finds, each by its edit's number in the list (from 1). "
                     + 'All or none holds in the workspace: on a mount that writes to disk, disk can still refuse a file, '
                     + "and the answer then says every edit is stored and names each file disk refused, with its push's reason. "
-                    + "The answer shows each edit's first changed region, numbered, a long line from shortly before each change on it, as its length allows.",
+                    + "The answer shows each edit's first changed region, numbered, a long line from shortly before each change on it, as its length allows."
+                    + editManyDirect,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1523,7 +1688,7 @@ export class WorkspaceModule {
                 name: 'delete',
                 description: 'Delete a file from the workspace. On a mount without autoMaterialize the disk copy stays, '
                     + 'listed as workspace-deleted (no scan brings it back), until materialize with applyDeletions removes it '
-                    + 'or a sync of the path restores it.',
+                    + 'or a sync of the path restores it.' + deleteDirect,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1576,7 +1741,7 @@ export class WorkspaceModule {
                     properties: {
                         pattern: { type: 'string', description: 'Regular expression pattern' },
                         path: { type: 'string', description: 'File or directory to search (mount-prefixed, optional)' },
-                        glob: { type: 'string', description: 'Glob pattern to filter files, relative to the mount root (e.g., "src/**/*.ts"); in the mount its first segment names, read mount-prefixed (e.g., "project/src/**/*.ts"), and in every other mount, as written' },
+                        glob: { type: 'string', description: 'Glob pattern to filter files: one with a "/" is matched from the mount\'s root, whatever the path (e.g., "src/**/*.ts"), and in the mount its first segment names, read mount-prefixed (e.g., "project/src/**/*.ts"), in every other mount as written; one with no "/" also matches a file\'s name at any depth (e.g., "*.ts")' },
                         contextBefore: { type: 'integer', description: 'Context lines before match' },
                         contextAfter: { type: 'integer', description: 'Context lines after match' },
                     },
@@ -1598,7 +1763,7 @@ export class WorkspaceModule {
                 description: 'Write workspace files to the real filesystem. Use after writing/editing to push changes to disk. '
                     + 'Never deletes disk files unless applyDeletions is given; lists workspace deletions it left on disk. '
                     + 'On a mount with an include, what the include doesn\'t cover is never written, and one naming a '
-                    + 'directory counts what it left beneath it under `passedOver`, by mount and reason, without naming it.',
+                    + 'directory counts what it left beneath it under `passedOver`, by mount and reason, without naming it.' + materializeDirect,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1716,7 +1881,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.
@@ -1726,20 +1896,25 @@ export class WorkspaceModule {
                 return { success: false, isError: true, error: `The ${call.name} call did nothing: ${problem}.` };
             }
             const input = call.input;
-            const generated = typeof input?.path === 'string' ? this.findGeneratedTextFile(input.path) : undefined;
+            // The most of this call's result that can reach its caller whole: past
+            // it, a model's result spills into a file, and a script gets
+            // 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 = 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, generated.read());
+                    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);
+                case 'read': return await this.handleRead(input, resultMaxChars);
                 case 'read_image': return await this.handleReadImage(input);
-                case 'write': return await this.handleWrite(input);
-                case 'edit': return await this.handleEdit(input, call.resultMaxChars);
+                case 'write': return await this.handleWrite(input, call.callerAgentName);
+                case 'edit': return await this.handleEdit(input, call.resultMaxChars, call.callerAgentName);
                 case 'edit_many': return await this.handleEditMany(input, call.resultMaxChars, call.callerAgentName);
-                case 'delete': return await this.handleDelete(input);
+                case 'delete': return await this.handleDelete(input, call.callerAgentName);
                 case 'ls': return await this.handleLs(input);
                 case 'glob': return await this.handleGlob(input);
                 case 'grep': return await this.handleGrep(input);
@@ -1747,12 +1922,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.
@@ -1800,7 +2003,7 @@ export class WorkspaceModule {
             text = `[workspace event · ${op} · ${paths.length} files in ${mountName}/]\n${list}`;
         }
         if (conflicts && conflicts.length > 0) {
-            text += `\n[conflicts: ${conflicts.join(', ')}]`;
+            text += `\n[conflicts with disk: ${conflicts.join(', ')}; reading each shows how to settle it]`;
         }
         return {
             requestInference: true,
@@ -1848,16 +2051,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 {
@@ -1879,6 +2081,15 @@ export class WorkspaceModule {
      * withheld original this way, for the branch its stub is on
      * (agent-framework #277).
      *
+     * On a mount running direct, the bytes go to disk as a direct `write`'s
+     * do, whole or not at all, and nothing goes into the store: `branch` is
+     * checked before the write starts and again just before its rename, and
+     * `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
@@ -1906,20 +2117,36 @@ export class WorkspaceModule {
                 isError: true,
             };
         }
-        if (mount.config.mode === 'read-only') {
-            return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
-        }
+        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),
+        // as the caller's agent's write, where it names one. A branch it names
+        // is checked just before the rename, since disk is no branch's.
+        if (mount.direct) {
+            // Checked first too, so a request already for a left branch makes no
+            // directory and stages nothing.
+            if (options.branch !== undefined && store.currentBranch().name !== options.branch) {
+                return { success: false, error: BRANCH_LEFT, isError: true, data: { branchLeft: true } };
+            }
+            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, disk: 'done', ...(written.note ? { note: written.note } : {}) } };
+        }
         return this.withMount(mount, async () => {
             await this.settleBeforeMutation(mount, relativePath);
             // Checked inside the mount's turn, after anything the write waited on:
             // commitToolChange sets the tree entry before it first yields.
             if (options.branch !== undefined && store.currentBranch().name !== options.branch) {
-                return { success: false, error: 'the workspace had left the branch this file is for', isError: true, data: { branchLeft: true } };
+                return { success: false, error: BRANCH_LEFT, isError: true, data: { branchLeft: true } };
             }
             const blobHash = store.storeBlob(data, mimeType);
             // An overwrite keeps the file's mode, as the write tool's does.
@@ -1927,9 +2154,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}.`;
             }
@@ -1938,10 +2167,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
@@ -1951,16 +2183,20 @@ 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 } : {}) },
             };
         });
     }
     /**
-     * Read a file's raw bytes from a mount (through the Chronicle tree, synced
-     * first like the `read` tool; on a direct mount, from disk as
-     * readBinaryFromDisk reads it, at most the mount's `maxFileSize`). Public
-     * API for the framework's synthesized `read_image` tool and other peer
-     * callers that need binary content.
+     * Read a file's raw bytes from a mount: through the Chronicle tree, a path
+     * the workspace doesn't hold observed first (ensureSynced); or, on a direct
+     * mount, from disk as readBinaryFromDisk reads it, at most the mount's
+     * `maxFileSize`. A path the workspace holds is read as the workspace holds
+     * it, not settled as the `read` tool settles it: the tree takes in no
+     * binary disk copy, so a pass over a held binary file that disk changed
+     * would drop the workspace's copy. Public API for the framework's
+     * synthesized `read_image` tool, where the workspace module doesn't serve
+     * read_image itself, and other peer callers that need binary content.
      */
     async readBinary(mountPrefixedPath) {
         if (!this.running())
@@ -1983,12 +2219,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 };
         });
     }
     /**
@@ -2066,9 +2303,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
@@ -2083,13 +2320,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).
@@ -2116,15 +2348,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`);
                 }
             }
         }
@@ -2132,10 +2365,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
@@ -2169,8 +2402,10 @@ export class WorkspaceModule {
      * mount nested by its directories alone, since its real root holds this
      * one, is judged by the parse's nesting, so a root repointed between a
      * read's parse and its open can have it serve a path in that mount's
-     * directory. Each mount is placed as a start places it (placementOf), from
-     * where its real root and the directories above its configured path lie on
+     * directory, and one repointed between a direct write's parse and its
+     * staging can have the write land there. Each mount is placed as a start
+     * places it (placementOf), from where its real root and the directories
+     * above its configured path lie on
      * disk. For a mount configured at this mount's own path or beneath it,
      * that's where they lie now: beneath `rootReal` where they lie beneath this
      * mount's path, and the directories above this mount's path as resolving
@@ -2235,12 +2470,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;
     }
@@ -2249,15 +2485,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;
@@ -2265,20 +2495,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
@@ -2286,10 +2511,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}`;
     }
     /**
@@ -2308,7 +2533,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
@@ -2350,7 +2575,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;
@@ -2369,26 +2596,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);
         }
@@ -2434,7 +2660,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;
@@ -2509,20 +2735,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
@@ -2544,11 +2762,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,
@@ -2573,25 +2787,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('/');
@@ -2605,10 +2819,37 @@ 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)))}`;
+    }
+    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,
@@ -2627,25 +2868,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
@@ -2661,20 +2900,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 {
@@ -2683,9 +2916,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 };
@@ -2693,7 +2933,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,
@@ -2707,7 +2947,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
@@ -2797,7 +3037,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 {
@@ -2828,7 +3068,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;
@@ -2866,13 +3106,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)
@@ -2941,7 +3181,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)) {
@@ -2956,11 +3198,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');
@@ -2990,93 +3233,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();
@@ -3108,13 +3283,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
@@ -3129,9 +3305,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();
@@ -3280,7 +3457,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 };
         }
@@ -3298,8 +3475,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,
@@ -3321,7 +3499,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
@@ -3343,15 +3521,19 @@ export class WorkspaceModule {
         await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true });
     }
     /**
-     * Before a read: a path the workspace doesn't hold is observed under the
-     * three-way rule, which ingests a new disk file but never brings back a
-     * workspace deletion or a file absent from this branch. The pass names the
-     * path, as a file tool names the one it acts on: a path the mount passes
-     * over by design is observed, as a sync naming it would observe it (#276),
-     * while a path in another mount's directory is refused before this, and
-     * passed over by any pass. Answers the pass's report on the path, and why
-     * the pass decided nothing where it did (undecidedOf), which leaves disk
-     * unchecked. The caller holds the mount's turn.
+     * Before a deletion, and for readBinary: a path the workspace doesn't hold
+     * is observed under the three-way rule, which ingests a new disk file but
+     * never brings back a workspace deletion or a file absent from this branch.
+     * A path it holds is left alone. For a deletion, as for a write, taking
+     * disk's change in first would let the push remove that change unseen; for
+     * readBinary, a pass would drop a held binary file that disk changed, since
+     * the tree takes in no binary disk copy. The pass names the path, as a file
+     * tool names the one it acts on: a path the mount passes over by design is
+     * observed, as a sync naming it would observe it (#276), while a path in
+     * another mount's directory is refused before this, and passed over by any
+     * pass. Answers the pass's report on the path, and why the pass decided
+     * nothing where it did (undecidedOf), which leaves disk unchecked. The
+     * caller holds the mount's turn.
      */
     async ensureSynced(mount, relativePath) {
         const store = this.getStore();
@@ -3366,46 +3548,79 @@ 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);
             default:
-                return `File not found: ${path}`;
+                return missing ?? `there's no file at ${shown}. ls or glob lists the files that exist.`;
         }
     }
     /**
-     * A file's bytes for read, from where the mount keeps what it reads: the
-     * workspace's copy, taken in from disk first where it holds none
-     * (ensureSynced); or, on a direct mount, disk's file as it is now
-     * (bytesOnDisk). An error says why there are none to read.
+     * A file's bytes for read, and the notes that say which copy they are. On a
+     * 'chronicle' mount it's the workspace's copy, after a pass over the path
+     * takes disk's change to it in first. On a direct mount it's disk's file as
+     * it is now (bytesOnDisk), with no notes, since nothing else is kept. An
+     * error says why there are none to read.
      */
     async bytesOf(mount, relativePath, path) {
-        if (mount.direct)
-            return this.bytesOnDisk(mount, relativePath, path);
+        if (mount.direct) {
+            const read = await this.bytesOnDisk(mount, relativePath, path);
+            return 'error' in read ? read : { bytes: read.bytes, notes: [] };
+        }
         const store = this.getStore();
         return this.withMount(mount, async () => {
-            const { report } = await this.ensureSynced(mount, relativePath);
+            // A read shows the path as disk holds it now: a change on disk to a
+            // file the workspace holds is taken in first, by the rule a listing
+            // uses, as an edit's is. Where the stored copy is a draft and disk
+            // changed too, the read shows the draft and names the conflict. The
+            // pass names the path, as a file tool names the one it acts on, so a
+            // path the mount passes over by design is observed, as a sync naming
+            // it would observe it (#276).
+            const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true });
+            // A pass that decided nothing (undecidedOf: the selected branch kept
+            // changing) leaves no report. It's read as a copy disk couldn't be
+            // checked, with its reason, so the answer says the check didn't finish.
+            const undecided = undecidedOf(pass);
+            const report = pass.reports.get(relativePath)
+                ?? (undecided !== null ? { path: relativePath, state: 'unverified', note: undecided } : undefined);
+            // A check that decided nothing may well finish on the next read, as
+            // grep's answer to the same says of grep.
+            const again = undecided !== null ? ['Read again to check it.'] : [];
+            // A mode taken in alone isn't a change to the text, so it leaves the
+            // read nothing to say, as it leaves an edit nothing.
+            const took = (op) => pass.ops.some((o) => o.path === relativePath && o.op === op && !o.modeOnly);
             const entry = store.treeGet(mount.treeStateId, relativePath);
-            if (!entry)
-                return { error: this.notInWorkspace(path, report) };
-            const blob = store.getBlob(entry.blobHash);
-            if (!blob)
-                return { error: `Blob not found for: ${path}` };
-            return { bytes: blob };
+            if (!entry) {
+                // 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' ? deletedOnDisk(path)
+                        : undecided !== null ? this.notCheckedYet(path, undecided)
+                            : this.notInWorkspace(path, report, mount),
+                };
+            }
+            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] };
         });
     }
     /**
@@ -3418,152 +3633,203 @@ 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.
-            const bare = err instanceof WorkspaceReadError && err.errno !== undefined && err.message === `Unable to read file: ${path}`;
-            return { error: bare ? `${err.message} (${err.errno})` : err instanceof Error ? err.message : String(err) };
+            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 (typeof proof !== 'string')
+            return 'none';
+        return { unreadable: proof === CHANGED ? containedRefusal(err, path) : proof };
+    }
+    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
     // ==========================================================================
-    async handleRead(input, generatedContent) {
+    /**
+     * A read's page, held to `maxChars`, the most of this call's result that
+     * can reach its caller whole. A call that carries none, made in process,
+     * takes the data itself: its page holds to its line limit alone, with every
+     * line whole, as it did before pages had a budget.
+     */
+    async handleRead(input, maxChars, generatedContent) {
         const characterPaging = input.offsetChars !== undefined || input.limitChars !== undefined;
-        const offsetChars = input.offsetChars ?? 0;
-        const limitChars = input.limitChars ?? 2000;
         // 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 content = generatedContent;
-        if (content === undefined) {
+        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 };
-            content = found.bytes.toString('utf-8');
-        }
-        if (characterPaging) {
-            const start = Math.min(offsetChars, content.length);
-            const splitsPair = (at) => at > 0 && at < content.length
-                && content.charCodeAt(at - 1) >= 0xd800 && content.charCodeAt(at - 1) <= 0xdbff
-                && content.charCodeAt(at) >= 0xdc00 && content.charCodeAt(at) <= 0xdfff;
-            if (splitsPair(start)) {
-                return { success: false, isError: true, error: 'offsetChars splits a surrogate pair; use nextOffsetChars from the previous page.' };
-            }
-            let end = start + Math.min(limitChars, content.length - start);
-            if (splitsPair(end))
-                end++;
-            return {
-                success: true,
-                data: {
-                    path: input.path,
-                    totalChars: content.length,
-                    offsetChars: start,
-                    nextOffsetChars: end < content.length ? end : null,
-                    content: content.slice(start, end),
-                },
-            };
+                return { success: false, error: didNothing('read', found.error), isError: true };
+            file = fileText(found.bytes);
+            notes = found.notes;
         }
-        const lines = linesOf(content);
-        // Apply offset/limit. An unlimited read of a large file would inject the
-        // whole thing into the turn (a 2MB file ≈ 600k tokens → the request blows
-        // past the model context and 400s), so an omitted limit falls back to a
-        // default cap; the result reports total/from/to so the agent can page.
-        const DEFAULT_READ_LINE_LIMIT = 2000;
-        const startLine = (input.offset ?? 1) - 1; // Convert to 0-indexed
-        if (startLine >= lines.length) {
-            // Nothing to show: an empty file, or an offset past the last line. No
-            // range is claimed, and the line count says where the file ends.
-            return {
-                success: true,
-                data: {
-                    path: input.path,
-                    totalLines: lines.length,
-                    // Reading an empty file from its start is reading it whole.
-                    ...(startLine > 0
-                        ? { note: `Line ${startLine + 1} is past the end: the file has ${lines.length} line${lines.length === 1 ? '' : 's'}.` }
-                        : {}),
-                    content: '',
-                },
-            };
+        else {
+            file = fileText(Buffer.from(generatedContent, 'utf-8'));
         }
-        const effectiveLimit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
-        const endLine = startLine + effectiveLimit;
-        const slice = lines.slice(startLine, endLine);
-        const truncated = endLine < lines.length;
-        // Format with line numbers (cat -n style)
-        const formatted = slice
-            .map((line, i) => `${String(startLine + i + 1).padStart(6)}\t${line}`)
-            .join('\n');
-        return {
-            success: true,
-            data: {
-                path: input.path,
-                totalLines: lines.length,
-                fromLine: startLine + 1,
-                toLine: Math.min(endLine, lines.length),
-                ...(truncated
-                    ? { note: `Truncated at ${effectiveLimit} lines (file has ${lines.length}). Use offset/limit to read more.` }
-                    : {}),
-                content: formatted,
-            },
-        };
+        // An unlimited read of a large file would inject the whole thing into the
+        // turn (a 2MB file ≈ 600k tokens → the request blows past the model
+        // context and 400s), so an omitted limit falls back to a default, and a
+        // page stops at the call's result limit where it has one.
+        return characterPaging
+            ? characterPage(input.path, file, input.offsetChars ?? 0, input.limitChars ?? 2000, maxChars, notes)
+            : 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) {
@@ -3576,39 +3842,56 @@ 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) {
+    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 };
-        if (mount.config.mode === 'read-only') {
-            return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
-        }
+        const refusal = writeRefusal(mount, this.writableNames());
+        if (refusal)
+            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) };
+        // A direct mount's bytes go to disk, whole, or nowhere (writeDirect).
+        if (mount.direct) {
+            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, 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.
@@ -3618,22 +3901,22 @@ 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) {
+    async handleEdit(input, maxChars = DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, callerAgentName) {
         return this.applyEdits('edit', [{
                 path: input.path,
                 oldString: input.oldString,
                 newString: input.newString,
                 expected: input.replaceAll ? 'all' : 1,
-            }], maxChars);
+            }], maxChars, callerAgentName);
     }
     async handleEditMany(input, maxChars = DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, callerAgentName) {
         if (input.edits.length === 0) {
@@ -3665,12 +3948,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.
@@ -3705,7 +3990,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)
@@ -3750,6 +4035,10 @@ export class WorkspaceModule {
             return refuse(problems);
         if (!mount || mounts.size > 1)
             return refuse(problems);
+        // A direct mount's edits apply to disk's text as it is now, and land on
+        // disk or don't happen (applyDirectEdits).
+        if (mount.direct)
+            return this.applyDirectEdits(tool, mount, [...targets.values()], problems, given.length, maxChars, callerAgentName);
         const store = this.getStore();
         // Whether the commit set the call's entries, all of them at once.
         let committed = false;
@@ -3763,7 +4052,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.
@@ -3783,7 +4096,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
@@ -3847,61 +4160,33 @@ 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 });
-                        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 });
+                            ? deletedOnDisk(target.path)
+                            : this.notInWorkspace(target.path, report, mount);
+                        problems.push({ kind: 'file', edits: target.edits, path: target.path, text, whole: false });
                         continue;
                     }
-                    // Decoding would turn each invalid sequence into U+FFFD, and writing
-                    // the text back would change bytes the edits never named.
-                    const file = decodeForEdit(blob);
-                    if (!file) {
+                    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: `${target.path} isn't valid UTF-8, so editing it would change bytes outside the text it replaces. `
-                                + 'Read shows each invalid byte sequence as U+FFFD, and a write replaces the whole file as UTF-8, so writing back what read shows puts U+FFFD in their place.',
-                            whole: false,
+                            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;
                     }
-                    if (!target.specs.length)
-                        continue;
-                    const planned = planFile(file, blob, target.specs, hints, maxSize, counts);
-                    if ('problems' in planned) {
-                        // One at a time: a call of many edits can have more problems
-                        // than a spread passes as arguments.
-                        for (const problem of planned.problems)
-                            problems.push({ ...problem, path: target.path });
-                        continue;
-                    }
-                    // The planner refuses a file its counts take past the limit before
-                    // building it, from the least its bytes can be; one it built past
-                    // the limit, as its CRs or multi-byte characters can take it, is
-                    // refused here.
-                    if ('tooLarge' in planned || planned.plan.bytes.length > maxSize) {
-                        const size = 'tooLarge' in planned ? `at least ${planned.tooLarge.toLocaleString('en-US')}` : planned.plan.bytes.length.toLocaleString('en-US');
-                        problems.push({
-                            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.",
-                            whole: false,
-                        });
+                    notes.push(...lookedIn);
+                    const plan = planTargetEdits(tool, target, stored.bytes, hints, maxSize, counts, problems);
+                    if (plan === null)
                         continue;
-                    }
                     plans.push({
                         target,
-                        plan: planned.plan,
+                        plan,
                         mode: entry.mode,
                         backOnDisk,
                         conflictNote: pushes ? null : conflictNote(tool === 'edit' || target.edits.length === 1 ? 'is in' : 'are in'),
@@ -3912,21 +4197,18 @@ 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; });
                 if (refused.size > 0)
                     return this.editsStoredButUnfinished(tool, [...targets.values()], applied, conflicts, { refused, modeKept }, maxChars);
-                return {
-                    success: true,
-                    data: editReceipt(tool, plans.map(({ target, plan, backOnDisk, conflictNote }) => ({
-                        path: target.path,
-                        plan,
-                        notes: [applied.get(target) ?? null, backOnDisk, conflictNote].filter((note) => note !== null),
-                        modeKept: modeKept.get(target.relativePath) ?? null,
-                    })), given.length, maxChars),
-                };
+                return editReceipt(tool, plans.map(({ target, plan, backOnDisk, conflictNote }) => ({
+                    path: target.path,
+                    plan,
+                    notes: [applied.get(target) ?? null, backOnDisk, conflictNote].filter((note) => note !== null),
+                    modeKept: modeKept.get(target.relativePath) ?? null,
+                })), given.length, maxChars, furthestFromDisk(plans.map(({ target }) => disk.get(target.relativePath))));
             });
         }
         catch (error) {
@@ -3934,12 +4216,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,
@@ -3952,10 +4234,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);
         }
     }
     /**
@@ -3968,7 +4248,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
@@ -3978,16 +4258,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.`);
-            if (where.mount.config.mode === 'read-only')
-                return unusable(`Mount "${where.mount.config.name}" is read-only`);
+                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);
         }
     }
     /**
@@ -3995,10 +4280,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
@@ -4014,12 +4299,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,
@@ -4042,10 +4327,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) => {
@@ -4059,48 +4345,559 @@ export class WorkspaceModule {
         ];
         return { success: false, isError: true, error: fitted(head, parts, notes, maxChars, 'stored') };
     }
-    async handleDelete(input) {
-        const { mount, relativePath, path } = await this.parseFilePath(input.path);
-        input = { ...input, path };
-        if (mount.config.mode === 'read-only') {
-            return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
-        }
-        const store = this.getStore();
-        let committed = false;
-        try {
-            return await this.withMount(mount, async () => {
-                const { report, undecided } = await this.ensureSynced(mount, relativePath);
-                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 };
+    // ==========================================================================
+    // Direct writes
+    // ==========================================================================
+    /**
+     * A direct mount's write of a whole file: its bytes staged beside it and
+     * renamed over it (direct-write.ts), under the mount's turn, so the
+     * module's own calls take turns. Answers a note when the file had other
+     * hard links, which keep its old text, or why nothing was written. One
+     * that lands is the caller's latest write on the mount (recordDirectWrite).
+     * With `branch`, nothing is written once the store's branch is another,
+     * checked with no turn of the event loop before the rename (writeBinary's).
+     */
+    async writeDirect(mount, relativePath, path, bytes, agentName, branch) {
+        return this.withMount(mount, async () => {
+            const { view, rootReal } = await this.diskView(mount);
+            let staged;
+            try {
+                staged = await stageContained(view, rootReal, relativePath, bytes, { makeDirectory: true });
+            }
+            catch (error) {
+                return { error: directDidNothing('write', path, error) };
+            }
+            try {
+                await directWriteTestSeam.afterStage?.([staged.path]);
+                await placedStill(staged);
+                // A write reads nothing first, so it replaces whatever is there.
+                checkUnchanged(staged, null);
+                if (branch !== undefined && this.getStore().currentBranch().name !== branch) {
+                    await discard(staged);
+                    return { error: BRANCH_LEFT, branchLeft: true };
                 }
-                const { refused, note } = 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'],
-                };
-            });
-        }
-        catch (error) {
-            if (!committed)
-                throw 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)}.`);
+                renameInto(staged);
             }
-            return storedButUnfinished('delete', input.path, { threw: error instanceof Error ? error.message : String(error) });
-        }
-    }
-    async handleLs(input) {
+            catch (error) {
+                await discard(staged);
+                return { error: directDidNothing('write', path, error) };
+            }
+            this.recordDirectWrite(mount, agentName);
+            return { note: linksNote(path, staged, 'write') };
+        });
+    }
+    /**
+     * applyEdits on a direct mount, under the mount's turn, whose edits land
+     * on disk or don't happen. Each attempt reads every file from disk as it
+     * is now (directEditText), plans every edit against those bytes as on any
+     * mount (planTargetEdits), stages every file beside itself, checks every
+     * one unchanged since its read, and then renames each over its file in
+     * turn (direct-write.ts). A file another writer changed between its read
+     * and its check has the call read and planned again against its new
+     * text, three attempts in all (DIRECT_EDIT_ATTEMPTS), so edits that no
+     * longer apply to it, a file that changed at every attempt, or a file the
+     * next read refuses as any read would (now past the size limit, say) are
+     * refused, with nothing written. A rename that fails after others leaves
+     * those written and the rest as they were, and the answer names each
+     * file's outcome; nothing puts the written ones back.
+     */
+    async applyDirectEdits(tool, mount, targets, early, editCount, maxChars, agentName) {
+        const changedMeanwhile = new Set();
+        return this.withMount(mount, async () => {
+            for (let attempt = 1;; attempt++) {
+                const outcome = await this.attemptDirectEdits(tool, mount, targets, early, changedMeanwhile, editCount, maxChars, agentName);
+                if (outcome !== 'changed')
+                    return outcome;
+                if (attempt === DIRECT_EDIT_ATTEMPTS) {
+                    const changed = targets.filter((target) => changedMeanwhile.has(target)).map((target) => target.path);
+                    // Each attempt stops at the first file it finds changed, so these are
+                    // the files some attempt found changed, at most one per attempt.
+                    return {
+                        success: false,
+                        isError: true,
+                        error: tool === 'edit'
+                            ? `${changed[0]} kept changing on disk while this edit was being applied (${DIRECT_EDIT_ATTEMPTS} attempts), so nothing was written. Read it again before retrying.`
+                            : `Another writer kept changing this call's files on disk while it was being applied: each of its ${DIRECT_EDIT_ATTEMPTS} attempts `
+                                + `found one changed since its read (${listed(changed)}), so nothing was written. Read ${changed.length === 1 ? 'it' : 'them'} again before retrying.`,
+                    };
+                }
+            }
+        });
+    }
+    /**
+     * One attempt of applyDirectEdits: its answer, or 'changed' when another
+     * writer changed a file since its read, with nothing written. `early` are
+     * the problems found before any file was read, which a refusal names with
+     * the rest. The caller holds the mount's turn.
+     */
+    async attemptDirectEdits(tool, mount, targets, early, changedMeanwhile, editCount, maxChars, agentName) {
+        const problems = [...early];
+        const read = new Map();
+        for (const target of targets) {
+            const got = await this.directEditText(mount, target.relativePath, target.path);
+            if ('changed' in got) {
+                changedMeanwhile.add(target);
+                return 'changed';
+            }
+            if ('error' in got)
+                problems.push({ kind: 'file', edits: target.edits, path: target.path, text: got.error, whole: false });
+            else
+                read.set(target, got);
+        }
+        // Two paths that reach one file, through a link this mount follows, or
+        // as two hard links (a disk that folds case has its two spellings made
+        // one path by the parse, short of a directory link on the way, past
+        // which they're refused here as one file named twice): each
+        // would be planned against the same text and renamed over the same file
+        // or split from it, so one's edits would be lost or kept apart from the
+        // other's. They're refused. One file read twice has one identity here
+        // unless a writer changed it between the reads, and the check before the
+        // renames then sees that and reads again.
+        const byIdentity = new Map();
+        for (const [target, { identity }] of read) {
+            const key = `${identity.dev}:${identity.ino}:${identity.size}:${identity.mtimeNs}:${identity.ctimeNs}`;
+            const other = byIdentity.get(key);
+            if (!other) {
+                byIdentity.set(key, target);
+                continue;
+            }
+            problems.push({
+                kind: 'file',
+                edits: [...other.edits, ...target.edits].sort((a, b) => a - b),
+                path: other.path,
+                text: `${other.path} and ${target.path} are one file, reached through a link or as two hard links; name it one way, so its edits are matched in one text`,
+                whole: true,
+            });
+        }
+        const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+        const hints = hintBudget();
+        // As much as the largest file the call names holds, at least, so the
+        // budget is the same whatever order its files are planned in.
+        let largest = maxSize;
+        for (const { bytes } of read.values())
+            largest = Math.max(largest, bytes.length);
+        const counts = countBudget(largest);
+        const plans = [];
+        for (const target of targets) {
+            const got = read.get(target);
+            if (!got)
+                continue;
+            const plan = planTargetEdits(tool, target, got.bytes, hints, maxSize, counts, problems);
+            if (plan !== null)
+                plans.push({ target, plan });
+        }
+        // A file read again for another writer's change says so, whichever way
+        // its edits went.
+        const reread = (target, verb) => !changedMeanwhile.has(target) ? null
+            : `Disk's copy${tool === 'edit' ? '' : ` of ${target.path}`} changed while this call was being applied, so it was read again, `
+                + `and ${tool === 'edit' ? 'the edit' : editList(target.edits)} ${verb} its new text.`;
+        const refuse = (found) => ({
+            success: false,
+            isError: true,
+            error: refusalText(tool, found, targets.map((target) => reread(target, 'looked in')).filter((note) => note !== null), maxChars, 'wrote'),
+        });
+        if (problems.length)
+            return refuse(problems);
+        const { view, rootReal } = await this.diskView(mount);
+        const staged = [];
+        const discardAll = async (from = 0) => {
+            for (const { staged: file } of staged.slice(from))
+                await discard(file);
+        };
+        // A refusal before any file is renamed says so where the call names several.
+        const nothingWritten = (target, error) => refuse([{
+                kind: 'file',
+                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.' : '')
+                    + (directWayOn(error) !== null ? ` ${directWayOn(error)}` : ''),
+                whole: true,
+            }]);
+        for (const { target, plan } of plans) {
+            try {
+                staged.push({ target, staged: await stageContained(view, rootReal, target.relativePath, plan.bytes) });
+            }
+            catch (error) {
+                await discardAll();
+                if (error instanceof FileChanged) {
+                    changedMeanwhile.add(target);
+                    return 'changed';
+                }
+                return nothingWritten(target, error);
+            }
+        }
+        try {
+            await directWriteTestSeam.afterStage?.(staged.map(({ staged: file }) => file.path));
+        }
+        catch (error) {
+            await discardAll();
+            throw error;
+        }
+        for (const { target, staged: file } of staged) {
+            try {
+                await placedStill(file);
+            }
+            catch (error) {
+                await discardAll();
+                return nothingWritten(target, error);
+            }
+        }
+        // Every file is checked, then every file renamed, with no turn of the
+        // event loop between: a change to any of them before its check is seen
+        // before any is written, and one landing between its check and the last
+        // rename isn't (checkUnchanged).
+        for (const { target, staged: file } of staged) {
+            try {
+                checkUnchanged(file, read.get(target));
+            }
+            catch (error) {
+                await discardAll();
+                if (error instanceof FileChanged) {
+                    changedMeanwhile.add(target);
+                    return 'changed';
+                }
+                return nothingWritten(target, error);
+            }
+        }
+        for (const [i, { target, staged: file }] of staged.entries()) {
+            try {
+                renameInto(file);
+            }
+            catch (error) {
+                if (i === 0) {
+                    await discardAll();
+                    return nothingWritten(target, error);
+                }
+                // Read with no turn of the event loop since the last rename.
+                this.recordDirectWrite(mount, agentName);
+                await discardAll(i);
+                return { success: false, isError: true, error: this.directEditsPartway(staged, i, error, maxChars) };
+            }
+        }
+        this.recordDirectWrite(mount, agentName);
+        return editReceipt(tool, staged.map(({ target, staged: file }) => ({
+            path: target.path,
+            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, 'done');
+    }
+    /**
+     * The answer to an edit_many call on a direct mount whose rename of its
+     * `failed`th file failed after the ones before it were written: what was
+     * written, the failure, and that nothing puts them back, then each file's
+     * outcome, within `maxChars`, with the hard links a written one split
+     * from, as a full answer names them (linksNote).
+     */
+    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 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);
+        return fitted(head, parts, notes, maxChars, 'written');
+    }
+    /**
+     * A direct mount's file as an edit reads it: its bytes on disk as they are
+     * now, through the mount's boundary as read reaches them
+     * (openContainedFile), with the file's identity when the read began, which
+     * the write checks it against just before its rename. A file changed while
+     * it was read is `changed`, so the call reads it again. What the
+     * workspace doesn't show as text, it doesn't edit either: a file over the
+     * mount's size limit, and a binary one.
+     */
+    async directEditText(mount, relativePath, path) {
+        const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+        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 Refusal(over(fileStat.size.toLocaleString('en-US')));
+            });
+        }
+        catch (err) {
+            if (err instanceof WorkspaceReadError && err.code === 'changed')
+                return { changed: true };
+            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(`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) {
+            return { error: unreadable(JSON.stringify(path), errnoOf(err)) };
+        }
+        finally {
+            await opened.handle.close();
+        }
+    }
+    /**
+     * A direct mount's deletion: the file the read tools reach, by their
+     * refusals (openContainedFile), unlinked through the mount's boundary as
+     * a push's deletion unlinks one (unlinkContained). A followed link is the
+     * entry removed, as there. One that lands is the caller's latest write on
+     * the mount (recordDirectWrite).
+     */
+    async deleteDirect(mount, relativePath, path, agentName) {
+        return this.withMount(mount, async () => {
+            // One root for the call, by its identity as the call starts: the
+            // open's checks and the unlink's own refuse any other directory there,
+            // in ROOT_MOVED's words, so a root replaced after this stat is refused
+            // rather than taken, but in the instant between the unlink's last
+            // check and the unlink, which Node can't close (effects.ts's header).
+            // One that can't be read now is refused here.
+            const disk = await this.diskView(mount);
+            let rootStat;
+            try {
+                rootStat = await stat(disk.rootReal, { bigint: true });
+            }
+            catch (err) {
+                const code = errnoOf(err);
+                const why = code === 'ENOENT' || code === 'ENOTDIR'
+                    ? `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;
+            try {
+                const opened = await this.openContainedFile(mount, relativePath, path);
+                await opened.handle.close();
+            }
+            catch (err) {
+                // The open's own words for a replaced root speak of reading.
+                if (err instanceof RootUnavailable && err.reason === DIRECT_ROOT_REPLACED) {
+                    return { success: false, isError: true, error: didNothing('delete', `${ROOT_MOVED}.`, 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.
+            const since = this.positionNow();
+            try {
+                await unlinkContained(view, rootReal, relativePath, { kind: 'any' });
+            }
+            catch (error) {
+                // A failure after the unlink reached the file's entry can't say
+                // 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: directDidNothing('delete', path, error) };
+            }
+            this.recordDirectWrite(mount, agentName, since);
+            return { success: true, data: { path, deleted: true, disk: 'done' }, keepWhenWithheld: ['path', 'deleted', 'disk'] };
+        });
+    }
+    /**
+     * After a direct write lands: the agent's latest write on the mount, P,
+     * moves to it, where the agent's history holds P or the notice of its
+     * departure from P, N (historyHoldsWrites), and N clears. Otherwise P
+     * stays where it is: the head moved away from it under the call's turn,
+     * and the next start's notice covers what it left (headMoveNotice). P is
+     * the branch and the store's head as it is now, read with no turn of the
+     * event loop since the write, so no record that lands after the write is
+     * taken for one before it. A deletion, whose unlink is awaited, passes
+     * where the head was just before its unlink (`since`): where the branch
+     * changed meanwhile, the head moved under the call, and P is set there,
+     * so the next start judges the deletion by the branch its turn was on,
+     * unless the history doesn't hold P already, whose notice is owed. A write no agent
+     * made tells no one. The store's reads here come after the write landed,
+     * so one that throws is logged and P stays, as for a history that can't
+     * be read, and the write still answers that it landed.
+     */
+    recordDirectWrite(mount, agentName, since) {
+        if (agentName === undefined)
+            return;
+        try {
+            const store = this.getStore();
+            let heads = this.directHeads.get(mount.config.name);
+            if (!heads)
+                this.directHeads.set(mount.config.name, (heads = new Map()));
+            const head = heads.get(agentName);
+            const branchId = store.currentBranch().id;
+            if (since && since.branchId !== branchId) {
+                if (!head || this.historyHoldsWrites(agentName, head) === true)
+                    heads.set(agentName, { ...since, notice: null });
+                return;
+            }
+            if (head && this.historyHoldsWrites(agentName, head) !== true)
+                return;
+            heads.set(agentName, { branchId, after: store.currentSequence(), notice: null });
+        }
+        catch (err) {
+            console.error('[workspace] could not record a direct write\'s position:', err);
+        }
+    }
+    /** The store's branch and head now, or null where the store can't say. */
+    positionNow() {
+        try {
+            const store = this.getStore();
+            return { branchId: store.currentBranch().id, after: store.currentSequence() };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Whether an agent's history holds its latest direct write on a mount
+     * (holdsPosition), or the notice of its departure from it, judged by the
+     * notice's own presence there, through the lookup the framework hands the
+     * module (useHistory); null where that lookup threw, which is logged. A
+     * history that can't be read decides nothing: a write takes it as not
+     * held, so its position stays and the notice stays owed, and a start
+     * gives no notice, which may not be true of a history it can't read, and
+     * leaves the next start to decide (headMoveNotice).
+     */
+    historyHoldsWrites(agentName, head) {
+        if (this.holdsPosition(head))
+            return true;
+        if (head.notice === null)
+            return false;
+        try {
+            return this.historyLookup?.(agentName, head.notice) === true;
+        }
+        catch (err) {
+            console.error('[workspace] history lookup for the head-move notice failed:', err);
+            return null;
+        }
+    }
+    /**
+     * Whether the store's current branch holds what came before a direct
+     * write: it's the write's branch, or continues it with every fork point on
+     * the way after `after`, the store's head when the write landed. A fork at
+     * exactly `after` doesn't: an undo forks at its turn's sequenceBefore,
+     * which is the head at the write when nothing was recorded in the turn
+     * before it. A missing branch or one without fork metadata holds nothing,
+     * as for the materialize guard (isLinearContinuation).
+     */
+    holdsPosition({ branchId, after }) {
+        const store = this.getStore();
+        const current = store.currentBranch();
+        if (current.id === branchId)
+            return true;
+        const byId = new Map(store.listBranches().map((b) => [b.id, b]));
+        const visited = new Set();
+        let cursor = byId.get(current.id);
+        while (cursor && !visited.has(cursor.id)) {
+            visited.add(cursor.id);
+            if (cursor.id === branchId)
+                return true;
+            if (cursor.parentId === undefined || cursor.branchPoint === undefined || cursor.branchPoint <= after)
+                return false;
+            cursor = byId.get(cursor.parentId);
+        }
+        return false;
+    }
+    /**
+     * The framework's check at every start of an agent's turn, opening,
+     * continuing or resuming: the notice due for each mount the agent wrote
+     * direct where its history holds neither its latest write there nor the
+     * notice of its departure from it (historyHoldsWrites), with those
+     * mounts' names; or null, as on a head that hasn't moved. The framework
+     * stores the text in the agent's history before the turn's compile and
+     * hands its message id back (headMoveNoticeStored).
+     */
+    headMoveNotice(agentName) {
+        if (!this.store)
+            return null;
+        const due = [];
+        // Every mount where the agent wrote direct, whether it runs direct this
+        // session or as 'chronicle': the writes are on disk either way.
+        for (const name of this.mounts.keys()) {
+            const head = this.directHeads.get(name)?.get(agentName);
+            if (!head)
+                continue;
+            const held = this.historyHoldsWrites(agentName, head);
+            // A history that can't be read decides nothing at this start.
+            if (held === null)
+                return null;
+            if (!held)
+                due.push(name);
+        }
+        return due.length ? { text: headMoveText(due), mounts: due } : null;
+    }
+    /** The id of the message headMoveNotice's text was stored as, N, for each mount it named. */
+    headMoveNoticeStored(agentName, mounts, messageId) {
+        for (const name of mounts) {
+            const head = this.directHeads.get(name)?.get(agentName);
+            if (head)
+                head.notice = messageId;
+        }
+    }
+    /**
+     * How the module asks whether an agent's history holds a message, as the
+     * framework judges its own notices (`cm.getMessage(id) !== null`): handed
+     * over once, when the module is added. Without it, no notice is held.
+     */
+    useHistory(lookup) {
+        this.historyLookup = lookup;
+    }
+    async handleDelete(input, callerAgentName) {
+        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, this.writableNames());
+        if (refusal)
+            return { success: false, error: didNothing('delete', refusal), isError: true };
+        if (mount.direct)
+            return this.deleteDirect(mount, relativePath, input.path, callerAgentName);
+        const store = this.getStore();
+        let committed = false;
+        try {
+            return await this.withMount(mount, async () => {
+                const { report, undecided } = await this.ensureSynced(mount, relativePath);
+                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, mount);
+                    return { success: false, error: didNothing('delete', error), isError: 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, disk, ...(note ? { note } : {}) },
+                    keepWhenWithheld: ['path', 'deleted', 'disk', 'note'],
+                };
+            });
+        }
+        catch (error) {
+            if (!committed)
+                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)}.`, this.agreement?.awaitsReopen === true);
+            }
+            return storedButUnfinished('delete', input.path, { threw: error instanceof Error ? error.message : String(error) }, null, this.agreement?.awaitsReopen === true);
+        }
+    }
+    async handleLs(input) {
         if (!input.path) {
             // List all mounts, with the kind a mount configured direct runs as
             // this session and the ignore list it walks by, whose default no
@@ -4109,7 +4906,9 @@ export class WorkspaceModule {
             const mounts = [...this.mounts.entries()].map(([name, m]) => ({
                 name,
                 path: m.config.path,
-                mode: m.config.mode,
+                // A mount configured direct says its mode where its config names
+                // none, so a writable one shows as writable.
+                mode: m.config.backend === 'direct' ? m.config.mode ?? 'read-write' : m.config.mode,
                 ...(m.config.backend === 'direct' ? { backend: m.direct ? 'direct' : 'chronicle', ignore: this.ignoreOf(m) } : {}),
                 ...(m.config.include ? { include: [...m.config.include] } : {}),
             }));
@@ -4119,7 +4918,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;
@@ -4128,6 +4927,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,
@@ -4136,6 +4938,7 @@ export class WorkspaceModule {
                     entries: listing.files,
                     count: listing.files.length,
                     ...incomplete,
+                    ...noted,
                 },
             };
         }
@@ -4152,9 +4955,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
@@ -4256,23 +5084,33 @@ 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
         // starts there: past the walk's cap, a walk of the whole scope can stop
         // before it gets there. In the mount a pattern's first segment names, the
         // pattern is read mount-prefixed (prefixedGlob), from its rest's directory
-        // within `path`.
+        // within `path`. A `path` that directory can't overlap leaves no file the
+        // pattern can match, so the glob is refused, as grep's is, saying how
+        // the pattern is read, rather than answered with no matches; but a path
+        // in another mount's directory is that mount's, and is said so, as grep
+        // says it. Only a `path` can do either, and it names one mount, so
+        // nothing has been searched yet.
         const patternDir = literalDirOf(input.pattern);
-        for (const { mount, relativePath } of mountsToSearch) {
+        for (const { mount, relativePath, moved, root } of mountsToSearch) {
             const prefixed = prefixedGlob(input.pattern, mount.config.name);
             let start;
             let matched;
             if (prefixed) {
                 const dir = deeperOf(relativePath, prefixed.dir);
-                if (dir === null)
-                    continue;
+                if (dir === null) {
+                    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;
+                    }
+                    return { success: false, error: await this.disjointRefusal('glob', input.path, input.pattern, true, mount, relativePath, root), isError: true };
+                }
                 start = await this.walkStart(mount, relativePath, dir === relativePath ? '' : dir.slice(relativePath ? relativePath.length + 1 : 0));
                 matched = (path) => prefixed.regex.test(path);
             }
@@ -4303,15 +5141,31 @@ 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, so every file it lets through
-        // lies beneath its literal directory, and the walk starts at the deeper of
-        // that and `path`. In the mount a filter's first segment names, its
-        // mount-prefixed reading takes the filter's place (below).
+        // The filter matches mount-relative paths, from the mount's root whatever
+        // the `path`, so every file it lets through lies beneath its literal
+        // directory, and the walk starts at the deeper of that and `path`. In the
+        // mount a filter's first segment names, its mount-prefixed reading takes
+        // the filter's place (below). One with no "/" also matches a file's name,
+        // wherever the file lies, as ripgrep's --glob does: "*.ts" lets every .ts
+        // file through, where tested against the path alone it let through only
+        // those at the mount's root. The path is still tried, so a "**" in such a
+        // filter spans directories as it did, and nothing it let through before
+        // is lost. A filter read mount-prefixed always holds a "/" after the
+        // mount's name, so it never takes the name test.
         const filterDir = input.glob ? literalDirOf(input.glob) : '';
+        const byName = fileGlob !== null && !input.glob.includes('/');
         const contextBefore = input.contextBefore ?? 0;
         const contextAfter = input.contextAfter ?? 0;
         const mountsToSearch = input.path
@@ -4322,14 +5176,29 @@ 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 = [];
         const skipped = [];
         const incomplete = [];
-        const search = (content) => {
-            const lines = linesOf(content);
+        // Lines as read shows them (fileText): a CRLF end's CR is left out, for
+        // matching as well as display, unless the line's own text ends in a CR, so
+        // `foo$` finds a CRLF file's line, as it does under ripgrep's --crlf, and
+        // the line copies into an edit as read's do. ripgrep's --crlf still prints
+        // the line with its CR.
+        //
+        // Whether a file has CRLF ends or a BOM is a fact about the file, not a
+        // line, so each searched file that has either is kept here by its path,
+        // for the note on a pattern that names a CR or U+FEFF to name it. A
+        // conflict's disk version is kept, for each, only where the workspace's
+        // copy of its path doesn't have it, and is named as that version, since
+        // read doesn't show it.
+        const crlfFiles = new Map();
+        const bomFiles = new Map();
+        const search = (text) => {
+            const { lines, crlfEnds, lfEnds, bom } = fileText(text.bytes);
+            const lineEndings = crlfEnds > 0 ? (lfEnds > 0 ? 'mixed' : 'CRLF') : undefined;
             const found = [];
             for (let i = 0; i < lines.length; i++) {
                 if (regex.test(lines[i])) {
@@ -4342,60 +5211,104 @@ export class WorkspaceModule {
                     found.push(match);
                 }
             }
-            return 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;
             }
             // In the mount a filter's first segment names, the filter is read
             // mount-prefixed (prefixedGlob), from its rest's directory. A `path` and
-            // a filter whose directories don't overlap leave no file the filter can
-            // let through, so nothing is searched.
+            // a filter whose directories, in the reading this mount takes, don't
+            // overlap leave no file the filter can let through, so the grep is
+            // refused, saying how the filter is read, rather than answered with no
+            // matches: written relative to the `path`, as glob's pattern is, it
+            // names nothing there. Only a `path` can do this, and it names one
+            // mount, so nothing has been searched yet.
             const prefixed = input.glob ? prefixedGlob(input.glob, mount.config.name) : null;
             const deeper = deeperOf(relativePath, prefixed ? prefixed.dir : filterDir);
-            if (deeper === null)
-                continue;
+            if (deeper === null) {
+                return { success: false, error: await this.disjointRefusal('grep', input.path, input.glob, prefixed !== null, mount, relativePath, root), isError: true };
+            }
             const start = await this.walkStart(mount, relativePath, deeper === relativePath ? '' : deeper.slice(relativePath ? relativePath.length + 1 : 0));
             const searched = (text) => {
-                const matches = search(text.text);
-                if (matches.length > 0)
-                    results.push({ file: text.file, ...(text.state !== undefined ? { state: text.state } : {}), version: text.version, matches });
+                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);
+                : (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);
         }
-        return {
-            success: true,
-            data: {
-                pattern: input.pattern,
-                results,
-                totalMatches: results.reduce((sum, r) => sum + r.matches.length, 0),
-                ...(skipped.length > 0 ? { skipped } : {}),
-                ...(incomplete.length > 0 ? { incomplete } : {}),
-            },
+        const answer = {
+            pattern: input.pattern,
+            results,
+            totalMatches: results.reduce((sum, r) => sum + r.matches.length, 0),
+            // A pattern written for a CR can't find a CRLF end's, nor one written
+            // for U+FEFF a BOM, which lines as read shows them leave out, so the
+            // answer says why it didn't, and names the files that have them.
+            ...leftOutNote(input.pattern, crlfFiles, bomFiles, this.anyRunsDirect()),
+            ...(skipped.length > 0 ? { skipped } : {}),
+            ...(incomplete.length > 0 ? { incomplete } : {}),
         };
+        return textAnswer(grepText(answer, contextBefore), { ...answer });
+    }
+    /**
+     * Why a grep or a glob whose `path` (`given`, in the mount at
+     * `relativePath`) and filter or pattern can't overlap did nothing. grep's
+     * filter is matched from the mount's root, and in the mount its first
+     * segment names, either tool's is read mount-prefixed (`prefixed`), from
+     * that mount's root; either way no file at or beneath the path can pass
+     * it. Where the path isn't a file, it names the one that reaches beneath
+     * it, the one meant if it was written relative to the path, mount-prefixed
+     * as the tools write paths: the path's own `{`, `}`, `*` and `?` stand as
+     * `?`, which matches each of them, and since the search stays beneath the
+     * path, a `?` that would match a sibling's name too takes nothing in from
+     * outside it. One with an empty, `.` or `..` segment gets no suggestion,
+     * since no path holds such a segment. Segments are read as written, so one
+     * a brace group splits around isn't told apart.
+     */
+    async disjointRefusal(tool, given, filter, prefixed, mount, relativePath, root) {
+        const name = mount.config.name;
+        const rest = prefixed ? filter.slice(filter.indexOf('/') + 1) : filter;
+        const read = `The ${tool} did nothing: its ${tool === 'grep' ? 'glob' : 'pattern'} ${JSON.stringify(filter)} `
+            + (prefixed ? `is read mount-prefixed, from the root of mount ${JSON.stringify(name)}` : 'is matched against paths from the mount\'s root');
+        if (await this.namesFile(mount, relativePath, root))
+            return `${read}, so ${JSON.stringify(given)} doesn't match it.`;
+        const within = `${read}, so no file within ${JSON.stringify(given)} matches it.`;
+        if (rest.split('/').some((segment) => segment === '' || segment === '.' || segment === '..'))
+            return within;
+        const reaching = `${name}/${relativePath.replace(/[{}*?]/g, '?')}/${rest}`;
+        return `${within} To ${tool === 'grep' ? 'filter' : 'match'} beneath it, write ${JSON.stringify(reaching)}.`;
     }
     /**
      * 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 = [];
@@ -4448,17 +5361,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
@@ -4468,17 +5382,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', text: blob.toString('utf-8') });
-                }
-                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;
@@ -4489,22 +5402,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', text: diskBlob.toString('utf-8') });
-                }
-                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 };
     }
@@ -4541,7 +5472,7 @@ export class WorkspaceModule {
             else if (looksBinary(read.head))
                 skipped.push({ file, reason: 'binary: a NUL in its first 8 KB', ...what });
             else
-                each({ file, version: 'disk', text: read.bytes.toString('utf-8') });
+                each({ file, version: 'disk', bytes: read.bytes });
         });
         return { skipped, incomplete: incomplete.map((region) => ({ path: `${name}/${region.path}`, reason: region.reason })) };
     }
@@ -4549,7 +5480,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)
@@ -4557,7 +5488,7 @@ export class WorkspaceModule {
             if (mount.direct) {
                 // A direct mount keeps nothing to count: its kind, and the ignore
                 // list its walks go by, whose default no config shows.
-                status[name] = { path: mount.config.path, mode: mount.config.mode, backend: 'direct', ignore: this.ignoreOf(mount) };
+                status[name] = { path: mount.config.path, mode: mount.config.mode ?? 'read-write', backend: 'direct', ignore: this.ignoreOf(mount) };
                 continue;
             }
             // What the workspace's history holds outside the mount's include isn't the mount's,
@@ -4571,7 +5502,7 @@ export class WorkspaceModule {
             const currentBranch = store.currentBranch();
             status[name] = {
                 path: mount.config.path,
-                mode: mount.config.mode,
+                mode: mount.config.backend === 'direct' ? mount.config.mode ?? 'read-write' : mount.config.mode,
                 // A mount configured direct runs as 'chronicle' this session
                 // (chooseKinds), by the direct kind's ignore list where its config
                 // names none.
@@ -4691,9 +5622,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;
@@ -4703,20 +5631,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 = [];
@@ -4731,7 +5676,7 @@ export class WorkspaceModule {
             // 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;
@@ -4741,13 +5686,14 @@ export class WorkspaceModule {
         else if (input.mount) {
             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 }];
         }
         else {
+            // Not a mount running direct, whose writes are on disk already.
             mountsToMaterialize = [...this.mounts.entries()]
-                .filter(([, m]) => m.config.mode === 'read-write')
+                .filter(([, m]) => m.config.mode === 'read-write' && !m.direct)
                 .map(([name, mount]) => ({ name, mount }));
         }
         // Branch guard, scoped to the mounts actually being materialized: a
@@ -4766,6 +5712,12 @@ export class WorkspaceModule {
         const guarded = [];
         let proceeded = 0;
         for (const { name, mount } of mountsToMaterialize) {
+            // Only a writable direct mount the caller named gets here: it keeps no
+            // tree to push. A read-only one is named as any read-only mount is.
+            if (mount.direct && mount.config.mode !== 'read-only') {
+                blocked.push({ mount: name, reason: DIRECT_MATERIALIZE_SKIPPED });
+                continue;
+            }
             if (mount.config.mode === 'read-only') {
                 // Only a mount the caller named gets here read-only (a bare
                 // materialize takes the read-write ones): say why nothing was written.
@@ -4848,15 +5800,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
                     ? {
@@ -4884,7 +5841,8 @@ export class WorkspaceModule {
             return [];
         const store = this.getStore();
         const mount = this.mounts.get(mountName);
-        if (!mount || mount.config.mode === 'read-only')
+        // A direct mount keeps no tree to push: disk is its only copy.
+        if (!mount || mount.config.mode === 'read-only' || mount.direct)
             return [];
         // Reset tracking — we're deliberately materializing on the new branch
         mount.lastMaterializedBranchId = null;
@@ -4917,7 +5875,13 @@ 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;
@@ -4927,14 +5891,14 @@ export class WorkspaceModule {
             // 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) {
             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: '' }];
         }
@@ -4948,6 +5912,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);
@@ -4962,6 +5927,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 };
@@ -5025,7 +5991,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,
@@ -5038,10 +6004,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 } : {}),
@@ -5108,9 +6081,9 @@ export class WorkspaceModule {
      * on disk (a shell command's files, a deletion) is in the workspace when the
      * agent next looks. On a mount over its walkCap, that holds for the first
      * walkCap entries in the walk's order, which every batch's scan takes; files
-     * past them come in through syncs and the listings that reach them, while a
-     * read takes in only a file the workspace doesn't hold yet. A scan that
-     * outlasts the deadline stops holding the round: the miss is recorded on
+     * past them come in through syncs, the listings that reach them, and a read
+     * of the path, which takes disk's change in first as a listing does. A scan
+     * that outlasts the deadline stops holding the round: the miss is recorded on
      * the mount's status and pushed as a `workspace:agent-action-scan-incomplete`
      * event, and the scan continues, deciding on the branch selected when it
      * applies.
@@ -5287,13 +6260,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',
@@ -5338,16 +6311,35 @@ const UNREADABLE_INTENT = "its workspace intent can't be read; a sync of the pat
 function watchOf(config) {
     return config.watch ?? (config.backend === 'direct' ? 'never' : 'always');
 }
+/**
+ * Why a write, edit, deletion or peer module's writeBinary to this mount is
+ * refused, or null where it may go ahead: a read-only mount, and a mount
+ * configured direct that runs as 'chronicle' this session (chooseKinds),
+ * since the store holds changes there that disk lacks. A write there would
+ * stay in the store, beside an agent told the mount is its checkout, and
+ * 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, writable = []) {
+    const name = mount.config.name;
+    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, `
+            + `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.`;
+    }
+    return null;
+}
 /**
  * What a direct mount's config sets that would never act there, each with
- * the way out (MountConfig.backend): a direct mount is read-only, and has no
- * watcher to tune, no change event to wake on and no push to make.
+ * the way out (MountConfig.backend): a direct mount has no watcher to tune,
+ * no change event to wake on and no push to make. Either mode is its own.
  */
 function directRefusals(mount) {
     const refused = [];
-    if (mount.mode !== 'read-only') {
-        refused.push(mount.mode === undefined ? "mode must be 'read-only' (left out, it's 'read-write')" : `mode must be 'read-only', not ${shownValue(mount.mode)}`);
-    }
     if (mount.watch !== undefined && mount.watch !== 'never')
         refused.push(`watch ${shownValue(mount.watch)} would watch nothing (leave it out, or set 'never')`);
     for (const key of ['watchDebounceMs', 'watchRootPollMs']) {
@@ -5361,6 +6353,263 @@ function directRefusals(mount) {
         refused.push('autoMaterialize would never push (leave it out)');
     return refused;
 }
+/** The global record type directHeads is saved as: a checkpoint at a clean stop that changed it. */
+const DIRECT_HEADS_RECORD_TYPE = 'workspace/direct-heads';
+/**
+ * A saved record as saveDirectHeads writes it, or a throw naming what isn't:
+ * a list of entries, each a mount's name, root and agents, and each agent's
+ * branch, head and, where set, notice. Checked whole, carried entries
+ * included, so a record of another shape is refused at load rather than
+ * carried into the next save.
+ */
+function checkedHeads(value) {
+    const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+    if (!Array.isArray(value))
+        throw new Error("the record isn't of the shape saved");
+    for (const saved of value) {
+        if (!isObject(saved) || typeof saved.mount !== 'string' || typeof saved.root !== 'string' || !isObject(saved.agents)) {
+            throw new Error(`an entry isn't of the shape saved: ${JSON.stringify(saved)?.slice(0, 200)}`);
+        }
+        for (const [agent, head] of Object.entries(saved.agents)) {
+            if (!isObject(head) || typeof head.branchId !== 'string' || typeof head.after !== 'number'
+                || (head.notice !== undefined && typeof head.notice !== 'string')) {
+                throw new Error(`agent ${JSON.stringify(agent)}'s position on mount ${JSON.stringify(saved.mount)} isn't of the shape saved`);
+            }
+        }
+    }
+    return value;
+}
+/** A saved record's content, whatever order its mounts and agents were written in, to tell whether a save would change it. */
+function canonicalHeads(snapshot) {
+    return JSON.stringify(snapshot.map(({ mount, root, agents }) => [mount, root, Object.keys(agents).sort().map((agent) => {
+            const { branchId, after, notice } = agents[agent];
+            return [agent, branchId, after, notice ?? null];
+        })]).sort((a, b) => {
+        const [x, y] = [JSON.stringify(a.slice(0, 2)), JSON.stringify(b.slice(0, 2))];
+        return x < y ? -1 : x > y ? 1 : 0;
+    }));
+}
+/**
+ * How many times a direct edit reads and plans a file another writer keeps
+ * changing: enough to land on top of a writer that changes it now and then,
+ * such as a formatter or a build, and bounded for one that never stops.
+ */
+const DIRECT_EDIT_ATTEMPTS = 3;
+/** Why a direct write, edit or deletion did nothing, for its answer: a refusal's words, or any other failure's message. */
+function directReason(error) {
+    if (error instanceof FileChanged)
+        return 'it changed on disk while this call was being applied';
+    // A deletion's root check (unlinkContained) has a store-backed mount's
+    // words, whose remedy, a sync with acceptRoot, a direct mount has no use for.
+    if (error instanceof Error && error.message === ROOT_REPLACED)
+        return ROOT_MOVED;
+    return error instanceof Error ? error.message : String(error);
+}
+function directWayOn(error) {
+    return error instanceof FileChanged ? 'Calling again reads it afresh.' : error instanceof WriteRefused ? error.wayOn : 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)}`;
+}
+/**
+ * The note for a direct write that gave a hard-linked path a file of its
+ * own: the other links keep the old text. Null for a file with none.
+ */
+function linksNote(path, staged, tool) {
+    const n = staged.otherLinks;
+    if (n <= 0)
+        return null;
+    return `${path} had ${n === 1 ? 'another hard link' : `${n} other hard links`}, which ${n === 1 ? 'keeps' : 'keep'} its old text: `
+        + `the ${tool === 'write' ? 'write' : tool === 'edit' ? 'edit' : 'call'} gave this path a file of its own.`;
+}
+/**
+ * A refusal of openContainedFile's as a direct tool gives it: its message,
+ * and for one that names only the path, its errno too, as a direct read's
+ * answer gives it (bytesOnDisk).
+ */
+function containedRefusal(err, path) {
+    const bare = err instanceof WorkspaceReadError && err.errno !== undefined && err.message === `Unable to read file: ${path}`;
+    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) {
+    if (note === DIRECTORY)
+        return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
+    const on = note === ROOT_UNAVAILABLE ? ROOT_UNCHECKED
+        : note === ROOT_REPLACED ? null
+            : note === NOT_FOLLOWED ? "Calling again won't change that; if you know the file it leads to, name that file by its own path."
+                : note === LEAVES_MOUNT ? "Calling again won't change that; if a mount holds the file it leads to, name it by its path there."
+                    : note === NOT_REGULAR ? onlyTheHost('put a regular file there')
+                        : note === CHANGED ? 'Calling again checks it afresh.'
+                            : 'Calling again checks disk again; if the same reason comes back, whoever runs this host can fix it on disk.';
+    return `${shown} isn't in the workspace, and disk couldn't be checked: ${sentence(note ?? 'not observed')}${on !== null ? ` ${on}` : ''}`;
+}
+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.stage === 'readlink')
+        return sentence(err.message);
+    switch (err.code) {
+        case 'directory':
+            return `${shown} is a directory, not a file; ls ${shown} lists what's in it.`;
+        case 'symlink':
+            return `${shown} is a symlink, and its mount doesn't follow symlinks, so the workspace's tools don't go through it. `
+                + 'Calling again won\'t change that; if you know the file it leads to, name that file by its own path.';
+        case 'escape':
+            return `${shown} leads through a symlink to a place outside its mount, so the workspace's tools don't reach it. `
+                + 'Calling again won\'t change that; if a mount holds that file, name it by its path there.';
+        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
+ * turns the agent's history no longer holds. `git status` stands beside
+ * `git diff` because a departed turn's new file is untracked, which `git
+ * diff` doesn't show; and the warning says "unstaged", since `git checkout
+ * -- <file>` puts back a file's staged text, so a staged change survives it.
+ */
+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. `
+        + `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.';
+}
+/**
+ * One file's edits planned against its bytes, as both kinds of mount plan
+ * them: its text decoded, every edit matched in it (edit-plan.ts), and the
+ * result held to the mount's size limit. Each problem found goes into
+ * `problems`, and then, as for a file named only by edits whose own input
+ * was refused, there's no plan (null).
+ */
+function planTargetEdits(tool, target, bytes, hints, maxSize, counts, problems) {
+    // Decoding would turn each invalid sequence into U+FFFD, and writing
+    // the text back would change bytes the edits never named.
+    const file = decodeForEdit(bytes);
+    if (!file) {
+        problems.push({
+            kind: 'file',
+            edits: target.edits,
+            path: target.path,
+            text: `${target.path} isn't valid UTF-8, so editing it would change bytes outside the text it replaces. `
+                + 'Read shows each invalid byte sequence as U+FFFD, and a write replaces the whole file as UTF-8, so writing back what read shows puts U+FFFD in their place.',
+            whole: false,
+        });
+        return null;
+    }
+    if (!target.specs.length)
+        return null;
+    const planned = planFile(file, bytes, target.specs, hints, maxSize, counts);
+    if ('problems' in planned) {
+        // One at a time: a call of many edits can have more problems
+        // than a spread passes as arguments.
+        for (const problem of planned.problems)
+            problems.push({ ...problem, path: target.path });
+        return null;
+    }
+    // The planner refuses a file its counts take past the limit before
+    // building it, from the least its bytes can be; one it built past
+    // the limit, as its CRs or multi-byte characters can take it, is
+    // refused here.
+    if ('tooLarge' in planned || planned.plan.bytes.length > maxSize) {
+        const size = 'tooLarge' in planned ? `at least ${planned.tooLarge.toLocaleString('en-US')}` : planned.plan.bytes.length.toLocaleString('en-US');
+        problems.push({
+            kind: 'file',
+            edits: target.edits,
+            path: target.path,
+            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;
+    }
+    return planned.plan;
+}
 /**
  * Whether a tree entry is what a change leaves: for a set, an entry with its
  * blob, size and mode; for a removal, none.
@@ -5390,16 +6639,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
@@ -5416,6 +6687,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
@@ -5427,7 +6703,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.' : '.');
@@ -5436,21 +6712,53 @@ 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}` : '') };
 }
 /**
- * A text's lines, as read and grep number them: a final line end ends the
- * last line rather than starting an empty one, so "a\nb\n" is two lines,
- * and an empty text has none.
+ * What a read says about the copy it shows, when that isn't simply the one the
+ * workspace last agreed on with disk: disk's newer text, taken in first; the
+ * workspace's copy, because disk's couldn't be checked or disk has none that
+ * anything accounts for; or a draft in conflict with disk's change. A file
+ * the workspace didn't hold has no older copy, so taking it in needs no word.
+ * A conflict's note names the ways to settle it that work on the path's mount.
  */
-function linesOf(content) {
-    const lines = content.split('\n');
-    if (lines.at(-1) === '')
-        lines.pop();
-    return lines;
+function whichCopyRead(report, tookChange, readOnly) {
+    if (tookChange) {
+        return ['Disk\'s copy had changed since the workspace last agreed with it, so it was taken in first, and this read shows that text.'];
+    }
+    if (report?.state === 'unverified') {
+        return [`The path couldn't be checked against disk (${report.note ?? 'not observed'}), so this read shows the workspace's copy.`];
+    }
+    if (report?.state === 'disk-missing-provenance-unknown') {
+        return ['Disk has no copy of this file, and nothing records whether it was deleted there, so this read shows the workspace\'s copy.'];
+    }
+    if (report?.state === 'conflict') {
+        const kind = report.conflict?.kind ?? 'both-changed';
+        // A sync takes disk's state as it is now, which a recorded conflict's kind
+        // doesn't follow: where disk has no copy, the sync takes its deletion, and
+        // the workspace's copy goes with it. Where disk has one, the sync keeps it
+        // and gives up the workspace's, taking disk's in only where the workspace
+        // 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 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,
@@ -5517,6 +6825,81 @@ function inputProblem(schema, input, minimums = {}) {
     }
     return null;
 }
+/** How many files a grep note names before it gives the count of the rest. */
+const NOTE_FILES_MAX = 20;
+/**
+ * The files a grep note names, in the order grep searched them, as its
+ * results are: at most NOTE_FILES_MAX of them, then how many more and how to
+ * see them. Each is named by its mount-prefixed path, with what `detail` says
+ * of it.
+ */
+function namedFiles(files, detail) {
+    const names = [...files.keys()];
+    const shown = names.slice(0, NOTE_FILES_MAX).map((name) => `${name}${detail(files.get(name))}`);
+    const rest = names.length - shown.length;
+    return `${shown.join(', ')}${rest > 0 ? `, and ${rest} more; narrow with path or glob` : ''}`;
+}
+/** What a note says of a conflict's disk version, which read doesn't show. */
+const ofVersion = (version) => version === 'conflicting-disk' || version === 'recorded-disk' ? ` in its ${version} version` : '';
+/**
+ * grep's note for a pattern that names a character its lines leave out, where
+ * a file it searched has one: it says how many files searched have it and
+ * names them, so a search for a CR or a BOM still finds the files that have
+ * them. The CR note gives each file's ends, CRLF or mixed, and either note
+ * names a conflict's disk version as that version. The note says a
+ * character read shows it in the workspace's copy, since grep also searches a
+ * conflict's disk version, which read doesn't show. A direct mount keeps no
+ * workspace copy, and its read shows disk's file, so on a host with one
+ * (`direct`) the note names that too, as the tools' descriptions mention
+ * direct mounts only on such a host.
+ */
+function leftOutNote(pattern, crlfFiles, bomFiles, direct) {
+    if (crlfFiles.size === 0 && bomFiles.size === 0)
+        return {};
+    const named = namedLeftOut(pattern);
+    const onDisk = direct ? ', or in disk\'s file on a direct mount' : '';
+    const count = (n, one, many) => `${n} ${n === 1 ? `file searched ${one}` : `files searched ${many}`}`;
+    const notes = [
+        named.cr && crlfFiles.size > 0
+            ? `The pattern names a CR, and ${count(crlfFiles.size, 'has', 'have')} CRLF line ends: `
+                + `${namedFiles(crlfFiles, ({ ends, version }) => ` (${ends}${ofVersion(version)})`)}. Lines are matched as read shows them, `
+                + `which leaves out a CRLF end's CR unless the line's own text ends in a CR. read with offsetChars shows every CR in the workspace's copy${onDisk}.`
+            : null,
+        named.bom && bomFiles.size > 0
+            ? `The pattern names U+FEFF, and ${count(bomFiles.size, 'starts', 'start')} with a BOM: `
+                + `${namedFiles(bomFiles, (version) => (ofVersion(version) ? ` (${ofVersion(version).slice(1)})` : ''))}. Lines are matched as read shows them, `
+                + `and a BOM isn't part of the first line. read with offsetChars shows any BOM ${direct ? `in the workspace's copy${onDisk}` : 'the workspace\'s copy has'}.`
+            : null,
+    ].filter((n) => n !== null);
+    return notes.length ? { note: notes.join(' ') } : {};
+}
+/**
+ * Which of the characters grep's lines leave out a pattern names: a CR, as a
+ * literal one or as `\r`, `\x0d`, `\u000d`, `\cM`, `\015` or a backslash
+ * before a literal CR; and U+FEFF, as a literal one, `\uFEFF` or a backslash
+ * before a literal one. An escape counts only where its backslash isn't itself
+ * escaped. A pattern compiled without flags can match a CR other ways too,
+ * such as `\15` in a pattern of fewer than 15 groups or a class range that
+ * spans U+000D, and those go unnoticed.
+ */
+function namedLeftOut(pattern) {
+    const named = { cr: false, bom: false };
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] === '\r')
+            named.cr = true;
+        else if (pattern[i] === '\uFEFF')
+            named.bom = true;
+        else if (pattern[i] === '\\') {
+            const next = pattern.slice(i + 1, i + 6);
+            if (/^(?:r|\r|x0[dD]|u000[dD]|c[mM]|015)/.test(next))
+                named.cr = true;
+            else if (/^(?:u[fF][eE][fF][fF]|\uFEFF)/.test(next))
+                named.bom = true;
+            i++;
+        }
+    }
+    return named;
+}
 /**
  * A glob's reading in the mount its first segment names, in place of the
  * pattern as written there. Every path the tools take and return is
@@ -5568,13 +6951,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 `**`