@animalabs/agent-framework 0.22.1 → 0.22.3

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

@@ -4,19 +4,28 @@
  * Provides a unified workspace with mount-based filesystem access,
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
+import { isUtf8 } from 'node:buffer';
 import { constants as fsConstants } from 'node:fs';
-import { open, readFile, stat, lstat, realpath } from 'node:fs/promises';
-import { join, resolve, relative, sep } from 'node:path';
+import { open, readFile, readdir, stat, lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, 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 { BranchIntents } from './branch-intent.js';
-import { coveredByIgnore, filesystemTrustsCtime, locateRoot } from './observe.js';
-import { TOOL_BATCH_HOOK_TIMEOUT_MS } from '../../module-registry.js';
-import { pushPaths, reconcilePass, settleAdoptionBeforeMutation, } from './reconcile.js';
+import { IGNORED, OTHER_MOUNT, checkDir, filesystemTrustsCtime, inOtherMount, locateRoot, passedOverAt, readPrefix } from './observe.js';
+import { TOOL_BATCH_HOOK_TIMEOUT_MS, ensureStateRegistered } from '../../module-registry.js';
+import { NOT_PUSHED_IN_OTHER_MOUNT, WALK_CAP, entryMode, pushPaths, reconcilePass, settleAdoptionBeforeMutation, } from './reconcile.js';
 /** Default for how long the after-batch scan may hold the agent's next inference. */
 const AGENT_ACTION_SCAN_DEADLINE_MS = 20_000;
+/**
+ * How long a mount's catch-up pass waits for its watcher to become ready
+ * before it starts anyway (ensureRunning). In a probe on Linux at a load near
+ * 40, chokidar's first scan of 10,000 entries took 1.3 s, about a twentieth of
+ * this. A scan slower than the bound has the pass started beside it, and the
+ * watcher's ready runs the pass again once the scan ends.
+ */
+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';
 /** The workspace's own deadline must end before the framework's hook bound. */
@@ -29,6 +38,16 @@ class WorkspaceImageReadError extends Error {
         this.name = 'WorkspaceImageReadError';
     }
 }
+/**
+ * A file operation's path lies in another mount's directory nested in the
+ * 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) {
+        super(`"${path}" lies in mount "${holder}", nested in mount "${mount}", which neither reads nor writes it: use "${use}".`);
+    }
+}
 /**
  * Thrown by `WorkspaceModule.readFileFromDisk()`. Messages carry the
  * mount-prefixed path only — never absolute filesystem paths — so they can be
@@ -53,6 +72,10 @@ function errnoOf(err) {
         ? err.code
         : undefined;
 }
+/** 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}`);
+}
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff]);
 const GIF87A_SIGNATURE = Buffer.from('GIF87a', 'ascii');
@@ -465,15 +488,37 @@ export class WorkspaceModule {
     /** Whether a mount root's filesystem maintains ctime, by canonical root. */
     /** Per canonical root: the device of its filesystem when that maintains ctime, else null. */
     ctimeTrust = new Map();
+    /**
+     * Each mount's directories that are other mounts nested inside it:
+     * mount-relative, `/`-separated, with each mount's name and resolved root.
+     */
+    otherMounts = new Map();
+    /**
+     * Whether a file's mode is observed, taken in and applied (MountRuntime's
+     * `modesObserved`): not on Windows, which reports no POSIX modes. A test
+     * sets it false to run that case anywhere.
+     */
+    modesObserved = process.platform !== 'win32';
     /** Persisted state decoded in start(), held until mounts exist to apply it
      *  to — in the Host ordering start() runs before initStore() creates the
      *  mounts, so restoration must be second-callback-safe like watcher
      *  startup already is (issue #72). Cleared after application. */
     savedState = null;
     constructor(config) {
-        // Detect overlapping mount paths: if mount A contains mount B,
-        // auto-add an ignore rule on A for B's path to prevent syncing
-        // the sub-mount's directory through the super-mount.
+        for (const mount of config.mounts) {
+            const cap = mount.walkCap;
+            if (cap !== undefined && !(Number.isSafeInteger(cap) && cap > 0)) {
+                // Numbers as JavaScript writes them (JSON would say null for NaN), anything else as JSON.
+                const shown = typeof cap === 'number' ? String(cap) : typeof cap === 'bigint' ? `${cap}n` : JSON.stringify(cap) ?? String(cap);
+                throw new Error(`[workspace] Mount "${mount.name}": walkCap must be a positive integer no larger than ${Number.MAX_SAFE_INTEGER}, not ${shown}`);
+            }
+        }
+        // Detect overlapping mount paths: a mount nested inside another is that
+        // mount's directory, which the outer mount passes over in every pass,
+        // named or not, and in its watcher (OTHER_MOUNT). It's kept apart from
+        // the outer mount's ignore list, which a sync that names a path sets
+        // aside for what it names (#276), so no sync of the outer mount takes in
+        // the inner one's files.
         for (const outer of config.mounts) {
             for (const inner of config.mounts) {
                 if (outer === inner)
@@ -481,15 +526,17 @@ export class WorkspaceModule {
                 const outerPath = resolve(outer.path);
                 const innerPath = resolve(inner.path);
                 const rel = relative(outerPath, innerPath);
-                if (rel && !rel.startsWith('..') && !rel.startsWith('/')) {
-                    // inner is nested under outer — add ignore rule
-                    outer.ignore = outer.ignore ?? [];
-                    const pattern = rel + '/**';
-                    if (!outer.ignore.includes(pattern) && !outer.ignore.includes(rel)) {
-                        outer.ignore.push(rel);
-                        console.warn(`[workspace] Mount "${outer.name}" contains mount "${inner.name}" ` +
-                            `(${rel}/) — auto-ignoring to prevent overlap`);
-                    }
+                // Outside the outer mount, `relative` gives a path that climbs with a
+                // `..` segment, or an absolute one across Windows drives. A name that
+                // only begins with two dots, such as `..cache`, is inside it.
+                if (rel && rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)) {
+                    // inner is nested under outer: passed over as exactly that
+                    // directory, read against `/`-separated paths, whatever the
+                    // platform's.
+                    const relPath = rel.split(sep).join('/');
+                    this.otherMounts.set(outer.name, [...(this.otherMounts.get(outer.name) ?? []), { dir: relPath, name: inner.name, root: innerPath }]);
+                    console.warn(`[workspace] Mount "${outer.name}" contains mount "${inner.name}" ` +
+                        `at ${relPath}/ — passing over it as another mount's directory`);
                 }
             }
         }
@@ -505,26 +552,25 @@ export class WorkspaceModule {
      * second. `ensureRunning()` gates on `ctx && mounts-populated`.
      */
     initStore(store) {
-        this.store = store;
+        // Every mount's states are registered before the module takes the store
+        // or any mount, so a registration that fails leaves the module as it was
+        // before the call, knowing no mount, and a later initStore starts clean.
+        const mounts = new Map();
+        const intents = new Map();
         // Register tree states for each mount: the workspace tree, and the
         // branch-local intent that qualifies it.
         for (const mount of this.config.mounts) {
             const treeStateId = `workspace/${mount.name}/tree`;
             const intentTreeStateId = `workspace/${mount.name}/intent`;
             for (const id of [treeStateId, intentTreeStateId]) {
-                try {
-                    store.registerState({
-                        id,
-                        strategy: 'tree',
-                        deltaSnapshotEvery: this.config.deltaSnapshotEvery ?? 50,
-                        fullSnapshotEvery: this.config.fullSnapshotEvery ?? 10,
-                    });
-                }
-                catch {
-                    // State already registered (restart scenario)
-                }
+                ensureStateRegistered(store, {
+                    id,
+                    strategy: 'tree',
+                    deltaSnapshotEvery: this.config.deltaSnapshotEvery ?? 50,
+                    fullSnapshotEvery: this.config.fullSnapshotEvery ?? 10,
+                });
             }
-            const mountState = {
+            mounts.set(mount.name, {
                 config: mount,
                 treeStateId,
                 intentTreeStateId,
@@ -534,13 +580,17 @@ export class WorkspaceModule {
                 lastMaterializedBranchId: null,
                 watcherReadyAt: null,
                 watcherError: null,
-            };
-            this.mounts.set(mount.name, mountState);
-            this.intents.set(mount.name, new BranchIntents(store, intentTreeStateId));
+            });
+            intents.set(mount.name, new BranchIntents(store, intentTreeStateId));
         }
+        this.store = store;
+        for (const [name, state] of mounts)
+            this.mounts.set(name, state);
+        for (const [name, intent] of intents)
+            this.intents.set(name, intent);
         // What disk last agreed with, per mount and path: global records, so a
         // branch switch never rewinds it.
-        this.agreement = new DiskAgreement(store);
+        this.agreement = new DiskAgreement(store, { modesObserved: () => this.modesObserved });
         this.agreement.open(this.config.mounts.map((m) => ({ name: m.name, root: resolve(m.path) })));
         this.applySavedState();
         this.ensureRunning();
@@ -585,19 +635,66 @@ export class WorkspaceModule {
                 followSymlinks: mount.config.followSymlinks === true,
                 maxFileSize: mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE,
                 ignore: mount.config.ignore ?? [],
+                others: this.othersOf(mount.config.name),
             },
             rootReal,
             ctimeTrustedDev: trustedDev,
             treeStateId: mount.treeStateId,
             intents: this.intents.get(mount.config.name),
             readOnly: mount.config.mode === 'read-only',
+            walkCap: mount.config.walkCap ?? WALK_CAP,
+            catchUpScan: (mount.config.watch ?? 'always') === 'always',
+            modesObserved: this.modesObserved,
         };
     }
+    /**
+     * Where a search's walk starts: `base`, its path as given, then each
+     * segment of `beneath` while disk lists it, in the directory reached so
+     * far, as a directory with exactly that spelling. The walk names what it
+     * finds from its start's spelling, and a case-insensitive disk would let
+     * it go on under a spelling disk doesn't list, taking files in under that
+     * spelling beside their own. So the start stops before a segment spelled
+     * any other way, not there, or not a directory, and before a link, which
+     * a walk of the whole mount doesn't go through either. It lists only
+     * directories it has checked lie inside the mount, and none the mount
+     * passes over by design, which the walk then answers for.
+     */
+    async walkStart(mount, base, beneath) {
+        if (beneath === '')
+            return base;
+        const { view, rootReal } = await this.runtime(mount);
+        let start = base;
+        for (const segment of beneath.split('/')) {
+            if (start !== '' && passedOverAt(start, view.ignore, view.others) !== undefined)
+                break;
+            const here = await checkDir(view, rootReal, start);
+            if (here.kind !== 'checked')
+                break;
+            const entry = (await readdir(here.dir.real, { withFileTypes: true }).catch(() => [])).find((e) => e.name === segment);
+            if (entry === undefined || !entry.isDirectory())
+                break;
+            start = start ? `${start}/${segment}` : segment;
+        }
+        return start;
+    }
     /** One disk→store pass; the caller holds the mount's turn. Emits its events. */
     async passUnlocked(mount, scope, opts = {}) {
         const result = await reconcilePass(this.getStore(), this.agreementOrThrow(), await this.runtime(mount), scope, opts);
         if (scope.kind === 'dir' && scope.dir === '' && scope.recursive)
             mount.initialSyncDone = true;
+        // What a pass says is another mount's directory names that mount and
+        // the path to use there, as the file operations' refusal does: a copy's
+        // note, and the region of a scope that lies there. The pass's counts
+        // keep the bare reason.
+        const name = mount.config.name;
+        for (const report of result.reports.values()) {
+            if (report.note === OTHER_MOUNT)
+                report.note = this.otherMountNote(name, report.path, 'list');
+        }
+        for (const region of result.incomplete) {
+            if (region.reason === OTHER_MOUNT)
+                region.reason = this.otherMountNote(name, region.path, 'list');
+        }
         this.emitFsEvents(mount.config.name, result.ops, result.newConflicts);
         return result;
     }
@@ -748,12 +845,54 @@ export class WorkspaceModule {
                 continue;
             const watchMode = mount.config.watch ?? 'always';
             if (watchMode === 'always') {
-                const watcher = new MountWatcher(mount.config, (changes) => {
+                // Chokidar is started with ignoreInitial:true, so changes made while
+                // the session was down would be invisible. A catch-up pass takes them
+                // in under the three-way rule: only real differences produce tree
+                // changes and events. It takes its turn with the mount's bare syncs,
+                // so on a mount over its walkCap it covers the walkCap entries after
+                // where the last turn stopped, and a change elsewhere waits for the
+                // rotation to reach it, or for a sync of its path.
+                //
+                // The pass runs at each of the watcher's readies, its first and each
+                // re-attach's, when chokidar has called fs.watch on every entry, so a
+                // change made after the pass has looked at a file reaches the watcher.
+                // Started beside chokidar's scan, the pass could finish with a file
+                // before chokidar watched it, and a change between the two reached
+                // neither. A watcher that isn't ready within CATCH_UP_BOUND_MS (from
+                // its start or its re-attach) has the pass started at the bound, and
+                // its ready, if it comes, runs the pass again. Within the mount's
+                // walkCap, that pass covers what the early one missed. Over it, the
+                // pass continues the rotation, and what the early one missed waits for
+                // the rotation to come back, as any change outside a pass's window
+                // does. An error doesn't start the pass: chokidar goes on scanning
+                // after one, and the bound covers a watcher that never becomes ready.
+                // On macOS, a new entry written after ready but before libuv's
+                // FSEventStream exists isn't reported until a later change in its
+                // directory, which this doesn't change.
+                let watcher;
+                let bound = null;
+                const catchUp = () => {
+                    if (bound)
+                        clearTimeout(bound);
+                    bound = null;
+                    // A watcher the module has since stopped or replaced starts no pass.
+                    if (this.watchers.get(name) !== watcher)
+                        return;
+                    void this.initialScan(name);
+                };
+                const awaitReady = () => {
+                    if (bound)
+                        clearTimeout(bound);
+                    bound = setTimeout(catchUp, CATCH_UP_BOUND_MS);
+                    bound.unref?.();
+                };
+                watcher = new MountWatcher(mount.config, (changes) => {
                     this.handleFsChanges(name, changes);
                 }, {
                     onReady: () => {
                         mount.watcherReadyAt = Date.now();
                         mount.watcherError = null;
+                        catchUp();
                     },
                     onError: (err) => {
                         mount.watcherError = err.message;
@@ -766,21 +905,17 @@ export class WorkspaceModule {
                     },
                     onReattach: () => {
                         mount.watcherError = null;
-                        void this.initialScan(name);
+                        awaitReady();
                         this.ctx?.pushEvent({
                             type: 'workspace:watcher-reattached',
                             mount: name,
                             path: mount.config.path,
                         });
                     },
-                });
+                }, this.othersOf(name));
+                awaitReady();
                 watcher.start();
                 this.watchers.set(name, watcher);
-                // Chokidar is started with ignoreInitial:true, so changes made while
-                // the session was down would be invisible. One full pass catches up
-                // under the three-way rule: only real differences produce tree
-                // changes and events.
-                void this.initialScan(name);
             }
             this.ctx.pushEvent({
                 type: 'workspace:mounted',
@@ -797,7 +932,7 @@ export class WorkspaceModule {
         try {
             // A full pass under the three-way rule: deletions on disk are confirmed
             // where nothing newer is pending, and nothing unvisited is touched.
-            await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }));
+            await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }, { resume: true }));
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -812,11 +947,13 @@ export class WorkspaceModule {
         // No new watcher-driven passes, then let every pass and write finish
         // before the store goes away — including any queued behind the ones in
         // flight (a tool call, a scan continuing past its deadline): drained
-        // until no new tail appears.
-        for (const watcher of this.watchers.values()) {
+        // until no new tail appears. The watchers leave this.watchers before they
+        // stop, so a watcher's ready or catch-up bound starts no pass meanwhile.
+        const stopping = [...this.watchers.values()];
+        this.watchers.clear();
+        for (const watcher of stopping) {
             await watcher.stop();
         }
-        this.watchers.clear();
         for (;;) {
             const tails = [...this.mountTurns.values()];
             await Promise.all(tails);
@@ -827,9 +964,16 @@ export class WorkspaceModule {
         // Nothing is queued now, and nothing more is taken: what follows saves
         // the pins and watermarks as the last work left them.
         this.stopped = true;
-        // Persist state
-        if (this.ctx) {
-            const activeBranchId = this.store ? this.store.currentBranch().id : undefined;
+        // Persist state, once initStore() has run and the state start() was
+        // handed has been applied (savedState is cleared then). Before that this
+        // session has made no pass or write, so it has nothing to save, and the
+        // stored state stays as it was: saving would put empty or default mounts
+        // over the saved pins. A create() that fails after starting this module
+        // stops it before the host can call initStore() (#389), and an
+        // initStore() that throws after taking the store leaves the state
+        // unapplied.
+        if (this.ctx && this.store && this.savedState === null) {
+            const activeBranchId = this.store.currentBranch().id;
             const state = { mounts: {}, activeBranchId };
             for (const [name, mount] of this.mounts) {
                 state.mounts[name] = {
@@ -867,8 +1011,8 @@ export class WorkspaceModule {
                     type: 'object',
                     properties: {
                         path: { type: 'string', description: 'File path (mount-prefixed, e.g., "project/src/main.ts")' },
-                        offset: { type: 'number', description: 'Starting line number (1-indexed)' },
-                        limit: { type: 'number', description: 'Maximum number of lines to return (default 2000)' },
+                        offset: { type: 'integer', description: 'Starting line number (1-indexed)' },
+                        limit: { type: 'integer', description: 'Maximum number of lines to return (default 2000)' },
                         offsetChars: { type: 'integer', description: 'Character paging: zero-based UTF-16 offset (default 0); use nextOffsetChars to continue' },
                         limitChars: { type: 'integer', description: 'Character paging: code units to return (default 2000), plus at most one to keep a surrogate pair intact. Use the limit suggested by a spill notice.' },
                     },
@@ -932,7 +1076,8 @@ export class WorkspaceModule {
                     + 'still on disk); not-in-branch (on disk, absent from this branch\'s workspace); disk-only (binary or over '
                     + 'the size limit, never stored — shown with size and image type); conflict, with its kind (disk and the '
                     + 'workspace both changed; disk holds a different copy and nothing records which is newer; or a write was '
-                    + 'interrupted) — sync the path to take disk, or materialize that path with force to take the workspace; '
+                    + 'interrupted) — sync the path to take disk, or materialize that path with force to take the workspace, '
+                    + 'with applyDeletions too where the workspace deleted it; '
                     + 'disk-missing-provenance-unknown; unverified (disk could not be checked). `incomplete` names regions '
                     + 'the listing could not see.',
                 inputSchema: {
@@ -968,8 +1113,8 @@ export class WorkspaceModule {
                         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' },
-                        contextBefore: { type: 'number', description: 'Context lines before match' },
-                        contextAfter: { type: 'number', description: 'Context lines after match' },
+                        contextBefore: { type: 'integer', description: 'Context lines before match' },
+                        contextAfter: { type: 'integer', description: 'Context lines after match' },
                     },
                     required: ['pattern'],
                 },
@@ -1001,7 +1146,12 @@ export class WorkspaceModule {
             {
                 name: 'sync',
                 description: 'Bring disk changes into the workspace. Without a path, every mount (or the given one) is '
-                    + 'rechecked in full and nothing pending in the workspace is discarded. With a path (file or directory), '
+                    + 'rechecked and nothing pending in the workspace is discarded. A sync takes up to the mount\'s walk '
+                    + 'cap of entries, files, links and the like (5000 unless configured). Past it, what this one didn\'t reach is listed under '
+                    + '`incomplete`, and the walk takes turns: the next sync of the same mount or directory picks up where '
+                    + 'the last turn stopped, so repeated syncs cover it all. On a mount watched continuously, its own catch-up '
+                    + 'scan, at start and when its watcher reattaches, takes turns with its whole-mount syncs. With a '
+                    + 'path (file or directory), '
                     + 'the workspace takes disk\'s state there explicitly: it restores a workspace-deleted file, resolves '
                     + 'conflicts toward disk, replaces a workspace draft, and removes a workspace file disk does not have. '
                     + 'Each workspace change it gives up is listed under `discarded`, with the state it had and, as `op`, '
@@ -1011,13 +1161,18 @@ export class WorkspaceModule {
                     + 'directory) is unavailable and listed under `incomplete`. Reconnect the drive; acceptRoot is for a '
                     + 'directory replaced on purpose, or a drive back under a new device number, never for one still '
                     + 'unplugged, whose empty mountpoint would become the root. What the scan passed over by design and '
-                    + 'reported nowhere else is counted under `passedOver`, by mount and reason: entries the mount\'s '
-                    + 'ignore list covers that hold nothing the workspace tracks (an ignored directory counts once). So a '
+                    + 'reported nowhere else is counted under `passedOver`, by mount and reason: another mount\'s '
+                    + 'directory nested in this one, entries the mount\'s ignore list covers, and entries with an '
+                    + 'editor\'s swap or backup file name (`.name.swp` and `.name.swx` as the whole name, names ending '
+                    + 'in `~` or in `.subl…tmp`), that hold nothing the workspace tracks (such a directory counts once, '
+                    + 'with what lies beneath it). So a '
                     + 'total of 0, with no conflicts and nothing under `passedOver`, `incomplete` or `skipped`, means the '
-                    + 'sync looked everywhere and nothing had changed. A path the mount ignores is synced when you name '
-                    + 'it, and listed under `ignored`: a sync without a path passes over it. Naming an ignored directory '
-                    + 'sets aside the patterns that cover it or a directory above it; one that covers only something '
-                    + 'inside it still applies, and what it covers is passed over.',
+                    + 'sync looked everywhere and nothing had changed. A path the mount ignores, or an editor\'s file, is '
+                    + 'synced when you name it, and listed under `ignored`: a sync without a path passes over it. A path '
+                    + 'in another mount\'s directory isn\'t synced even when you name it: use the mount that holds it. Naming '
+                    + 'an ignored directory sets aside the patterns that cover it or a directory above it; one that '
+                    + 'covers only something inside it still applies, and what it covers is passed over, as are editors\' '
+                    + 'files inside it.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1048,8 +1203,10 @@ export class WorkspaceModule {
         const mount = this.config.mounts.find(m => m.name === mountName);
         if (!mount)
             throw new Error(`Unknown mount: "${mountName}"`);
-        const resolved = resolve(mount.path, slash < 0 ? '' : path.slice(slash + 1));
-        if (!isContainedPath(mount.path, resolved))
+        // Against the resolved root, as parsePath judges it.
+        const root = resolve(mount.path);
+        const resolved = resolve(root, slash < 0 ? '' : path.slice(slash + 1));
+        if (!isContainedPath(root, resolved))
             throw new Error(`Path traversal detected: "${path}"`);
         return resolved;
     }
@@ -1077,6 +1234,13 @@ export class WorkspaceModule {
         if (!this.running())
             return { success: false, isError: true, error: NOT_RUNNING };
         try {
+            // Every handler reads its input as its schema describes it; a call
+            // that sends something else is refused here, before anything is read.
+            const schema = this.getTools().find((tool) => tool.name === call.name)?.inputSchema;
+            const problem = schema ? inputProblem(schema, call.input, INPUT_MINIMUMS[call.name]) : null;
+            if (problem !== null) {
+                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;
             if (generated) {
@@ -1103,7 +1267,7 @@ export class WorkspaceModule {
             }
         }
         catch (err) {
-            return { success: false, error: String(err), isError: true };
+            return { success: false, error: err instanceof Error ? err.message : String(err), isError: true };
         }
     }
     async onProcess(event, _state) {
@@ -1192,7 +1356,7 @@ export class WorkspaceModule {
      */
     resolveAbsolutePath(mountPrefixedPath) {
         try {
-            const { mount, relativePath } = this.parsePath(mountPrefixedPath);
+            const { mount, relativePath } = this.parseFilePath(mountPrefixedPath);
             return resolve(mount.config.path, relativePath);
         }
         catch {
@@ -1226,7 +1390,7 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+            ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
         }
         catch (error) {
             return {
@@ -1251,12 +1415,16 @@ export class WorkspaceModule {
                 return { success: false, error: 'the workspace had left the branch this file is for', isError: true, data: { branchLeft: true } };
             }
             const blobHash = store.storeBlob(data, mimeType);
+            // An overwrite keeps the file's mode, as the write tool's does.
+            const existing = store.treeGet(mount.treeStateId, relativePath);
             let committed = false;
             let failure;
+            let modeKept = null;
             try {
-                const materializeError = await this.commitToolChange(mount, relativePath, { kind: 'set', blobHash, size: data.byteLength }, () => { committed = true; });
-                failure = materializeError === null ? null
-                    : `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`;
+                const answer = await this.commitToolChange(mount, relativePath, { kind: 'set', blobHash, size: data.byteLength, ...(existing ? { mode: existing.mode } : {}) }, () => { committed = true; });
+                modeKept = answer.modeKept;
+                failure = answer.refused === null ? null
+                    : `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${answer.refused}.`;
             }
             catch (error) {
                 if (!committed)
@@ -1271,7 +1439,7 @@ export class WorkspaceModule {
             }
             return {
                 success: true,
-                data: { path: mountPrefixedPath, size: data.byteLength, mimeType },
+                data: { path: mountPrefixedPath, size: data.byteLength, mimeType, ...(modeKept ? { modeKept } : {}) },
             };
         });
     }
@@ -1286,7 +1454,7 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+            ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
         }
         catch (error) {
             return { error: error instanceof Error ? error.message : String(error) };
@@ -1322,7 +1490,7 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+            ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
         }
         catch (error) {
             return { error: error instanceof Error ? error.message : String(error) };
@@ -1344,10 +1512,65 @@ export class WorkspaceModule {
             return { error: error instanceof Error ? error.message : String(error) };
         }
     }
+    /** The directories of the mounts nested inside a mount, mount-relative. */
+    othersOf(mountName) {
+        return (this.otherMounts.get(mountName) ?? []).map((o) => o.dir);
+    }
+    /**
+     * The innermost mount nested in `mountName` whose directory holds a path
+     * 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.
+     */
+    holderOf(mountName, relativePath) {
+        const mount = this.mounts.get(mountName);
+        if (!mount)
+            return undefined;
+        const resolved = resolve(mount.config.path, relativePath);
+        const holder = (this.otherMounts.get(mountName) ?? [])
+            .filter((o) => isContainedPath(o.root, resolved))
+            .sort((a, b) => b.root.length - a.root.length)[0];
+        if (!holder)
+            return undefined;
+        const rest = relative(holder.root, resolved).split(sep).join('/');
+        return { name: holder.name, use: rest ? `${holder.name}/${rest}` : holder.name };
+    }
+    /**
+     * Why a mount leaves a path in a nested mount's directory, naming that
+     * mount and the path to use: for a sync or a push, which of them leaves
+     * it; for a listing, whose the path is.
+     */
+    otherMountNote(mountName, relativePath, by) {
+        const holder = this.holderOf(mountName, relativePath);
+        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 lies in another mount's directory${what}`;
+    }
+    /**
+     * parsePath for the file operations (read, write, edit, delete, and the
+     * module's binary and disk reads and writes). A path in another mount's
+     * directory nested in this one is that mount's: this mount's passes don't
+     * observe it and its pushes don't write it, so its file operations refuse
+     * it, naming the innermost mount that holds it and the path to use there.
+     */
+    parseFilePath(path) {
+        const parsed = this.parsePath(path);
+        const holder = this.holderOf(parsed.mount.config.name, parsed.relativePath);
+        if (holder)
+            throw new NestedMountError(path, parsed.mount.config.name, holder.name, holder.use);
+        return parsed;
+    }
     /**
      * Parse a mount-prefixed path into (mountName, relativePath).
      */
     parsePath(path) {
+        // 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.`);
+        }
         const slashIdx = path.indexOf('/');
         const mountName = slashIdx >= 0 ? path.slice(0, slashIdx) : path;
         const relativePath = slashIdx >= 0 ? path.slice(slashIdx + 1) : '';
@@ -1359,8 +1582,11 @@ export class WorkspaceModule {
         // Containment must compare with the PLATFORM separator (isContainedPath):
         // resolve() emits backslashes on Windows, so a '/'-suffixed root never
         // prefix-matches there and every in-mount path was rejected as traversal.
-        const resolved = resolve(mount.config.path, relativePath);
-        if (!isContainedPath(mount.config.path, resolved)) {
+        // Against the resolved root, so a root configured with a trailing
+        // separator, or relative, contains its own paths, the root included.
+        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}"`);
         }
         return { mount, relativePath };
@@ -1385,9 +1611,8 @@ export class WorkspaceModule {
         if (bytes.byteLength === 0) {
             throw new WorkspaceImageReadError('empty', `Image file is empty: ${mountPrefixedPath}`);
         }
-        if (bytes.byteLength > maxSize) {
-            throw new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
-        }
+        if (bytes.byteLength > maxSize)
+            throw imageTooLarge(maxSize, mountPrefixedPath);
         return {
             bytes,
             mimeType: detectImageMimeType(bytes, mountPrefixedPath),
@@ -1544,11 +1769,16 @@ export class WorkspaceModule {
      * - With symlinks allowed, the canonical target must stay beneath the
      *   canonical mount root; a sibling-prefix root (`/mount-other`) does not count.
      * - `maxBytes` performs a bounded prefix read: at most `maxBytes` bytes are
-     *   ever loaded, and `truncated` reports that the file was larger.
+     *   kept, and one byte past them is read to tell whether the file goes on
+     *   (`truncated`). The reads decide where the file ends, not the size fstat
+     *   gave at the open, so the bound holds for a file that grows while it's
+     *   read.
      *
      * Throws {@link WorkspaceReadError} with a `code` distinguishing unknown
-     * mount, lexical traversal, unavailable mount, missing file, directory,
-     * policy-denied symlink, outside-mount target, and file-changed-during-read.
+     * mount, lexical traversal, a path in another mount's directory nested in
+     * the one named (`other_mount`), unavailable mount, missing file,
+     * directory, policy-denied symlink, outside-mount target, and
+     * file-changed-during-read.
      */
     async readFileFromDisk(mountPrefixedPath, options = {}) {
         if (options.maxBytes !== undefined && !(Number.isInteger(options.maxBytes) && options.maxBytes >= 0)) {
@@ -1557,11 +1787,12 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+            ({ mount, relativePath } = this.parseFilePath(mountPrefixedPath));
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            const code = message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
+            const code = err instanceof NestedMountError ? 'other_mount'
+                : message.startsWith('Unknown mount') ? 'unknown_mount' : 'traversal';
             throw new WorkspaceReadError(code, message, 'parse');
         }
         if (!relativePath) {
@@ -1569,26 +1800,18 @@ export class WorkspaceModule {
         }
         const { handle, fileStat, realFilePath } = await this.openContainedFile(mount, relativePath, mountPrefixedPath);
         try {
-            const size = fileStat.size;
             const cap = options.maxBytes;
             let bytes;
             let truncated = false;
-            if (cap !== undefined && size > cap) {
-                truncated = true;
-                bytes = Buffer.alloc(cap);
-                let offset = 0;
-                while (offset < cap) {
-                    const { bytesRead } = await handle.read(bytes, offset, cap - offset, offset);
-                    if (bytesRead === 0)
-                        break;
-                    offset += bytesRead;
-                }
-                if (offset < cap)
-                    bytes = bytes.subarray(0, offset);
+            if (cap === undefined) {
+                bytes = await handle.readFile();
             }
             else {
-                bytes = await handle.readFile();
+                ({ bytes, more: truncated } = await readPrefix(handle, cap, fileStat.size));
             }
+            // What the read found, not what the fstat before it said, so `size`,
+            // `bytes` and `truncated` agree even for a file that changed in between.
+            const size = truncated ? Math.max((await handle.stat()).size, bytes.length + 1) : bytes.length;
             return { bytes, size, truncated, mtimeMs: fileStat.mtimeMs, realPath: realFilePath, mount: mount.config.name };
         }
         catch (err) {
@@ -1635,9 +1858,8 @@ export class WorkspaceModule {
                 if (fileStat.size === 0) {
                     throw new WorkspaceImageReadError('empty', `Image file is empty: ${mountPrefixedPath}`);
                 }
-                if (fileStat.size > maxSize) {
-                    throw new WorkspaceImageReadError('too_large', `Image file exceeds max size (${maxSize} bytes): ${mountPrefixedPath}`);
-                }
+                if (fileStat.size > maxSize)
+                    throw imageTooLarge(maxSize, mountPrefixedPath);
             });
         }
         catch (err) {
@@ -1650,9 +1872,13 @@ export class WorkspaceModule {
             }
             throw new WorkspaceImageReadError('not_found', `Unable to read image file: ${mountPrefixedPath}`);
         }
-        const { handle } = opened;
+        const { handle, fileStat } = opened;
         try {
-            const bytes = await handle.readFile();
+            // 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);
             return this.validateImageBytes(bytes, mountPrefixedPath, maxSize);
         }
         catch (err) {
@@ -1667,6 +1893,13 @@ export class WorkspaceModule {
             await handle.close();
         }
     }
+    /**
+     * Whether a tool's change on this mount goes to disk as it commits: the
+     * push commitToolChange makes, and what an edit's answer says of it.
+     */
+    pushesOnCommit(mount) {
+        return mount.config.autoMaterialize === true && mount.config.mode !== 'read-only';
+    }
     /**
      * Commit a tool's write or delete to the workspace tree, with the branch
      * intent it implies (store origin for a path disk never agreed with; a
@@ -1676,10 +1909,13 @@ export class WorkspaceModule {
      * The push follows materialize's rule: a disk copy that changed since it
      * last agreed is not overwritten or unlinked, and the refusal says why.
      *
-     * Returns the reason when the change reached the workspace but not disk, so
-     * callers surface it in the tool result: the autoMaterialize contract is
-     * that disk is the source of truth for downstream agents. The caller holds
-     * the mount's turn and has settled the path first (settleBeforeMutation).
+     * Answers, so callers surface them in the tool result, the reason when the
+     * change reached the workspace but not disk (`refused`): the
+     * autoMaterialize contract is that disk is the source of truth for
+     * downstream agents. And, apart from it, why a write whose bytes reached
+     * disk left the file's mode as disk had it (`modeKept`). 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 store = this.getStore();
@@ -1707,21 +1943,22 @@ export class WorkspaceModule {
         }
         else {
             store.treeRemove(mount.treeStateId, relativePath);
+            onCommitted?.();
             intents.update(relativePath, (cur) => {
                 const next = { ...cur, tombstone: { hash: change.previousHash } };
                 delete next.origin;
                 return next;
             });
         }
-        if (!mount.config.autoMaterialize || mount.config.mode === 'read-only')
-            return null;
+        if (!this.pushesOnCommit(mount))
+            return { refused: null, modeKept: null };
         const pushed = await this.pushUnlocked(mount, [relativePath], {
             applyDeletions: change.kind === 'remove',
             branchId: store.currentBranch().id,
         });
         const refused = pushed.skipped.find((s) => s.path === relativePath);
         if (!refused)
-            return null;
+            return { refused: null, modeKept: pushed.modesKept.find((k) => k.path === relativePath)?.reason ?? null };
         this.ctx?.pushEvent({
             type: 'workspace:materialize-failed',
             mount: mount.config.name,
@@ -1729,7 +1966,7 @@ export class WorkspaceModule {
             op: change.kind === 'set' ? 'write' : 'delete',
             error: refused.reason,
         });
-        return refused.reason;
+        return { refused: refused.reason, modeKept: null };
     }
     // ==========================================================================
     // Lazy Sync
@@ -1740,25 +1977,30 @@ export class WorkspaceModule {
      * disk now holds (an edit sees a disk change the settled adoption took in).
      * The pass may not settle it (a branch that keeps changing, an unreadable
      * disk copy); the precondition that matters is enforced again,
-     * synchronously, where the change commits (commitToolChange). The caller
-     * holds the mount's turn.
+     * synchronously, where the change commits (commitToolChange). 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 there, as a sync naming it would
+     * observe it (#276). The caller holds the mount's turn.
      */
     async settleBeforeMutation(mount, relativePath) {
         if (this.agreementOrThrow().get(mount.config.name, relativePath)?.kind !== 'pending')
             return;
-        await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] });
+        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 caller holds
-     * the mount's turn.
+     * 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. The caller holds the mount's turn.
      */
     async ensureSynced(mount, relativePath) {
         const store = this.getStore();
         if (store.treeGet(mount.treeStateId, relativePath))
             return undefined;
-        const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] });
+        const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true });
         return pass.reports.get(relativePath);
     }
     /** Why the workspace holds no entry at a path, when disk explains it. */
@@ -1787,19 +2029,14 @@ export class WorkspaceModule {
         const characterPaging = input.offsetChars !== undefined || input.limitChars !== undefined;
         const offsetChars = input.offsetChars ?? 0;
         const limitChars = input.limitChars ?? 2000;
-        if (characterPaging) {
-            if (input.offset !== undefined || input.limit !== undefined) {
-                return { success: false, isError: true, error: 'Use either offset/limit (lines) or offsetChars/limitChars (characters), not both.' };
-            }
-            if (!Number.isSafeInteger(offsetChars) || offsetChars < 0
-                || !Number.isSafeInteger(limitChars) || limitChars < 1
-                || input.offsetChars === null || input.limitChars === null) {
-                return { success: false, isError: true, error: 'offsetChars must be a non-negative safe integer and limitChars a positive safe integer.' };
-            }
+        // 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.' };
         }
         let content = generatedContent;
         if (content === undefined) {
-            const { mount, relativePath } = this.parsePath(input.path);
+            const { mount, relativePath } = this.parseFilePath(input.path);
             const store = this.getStore();
             const found = await this.withMount(mount, async () => {
                 const report = await this.ensureSynced(mount, relativePath);
@@ -1837,13 +2074,29 @@ export class WorkspaceModule {
                 },
             };
         }
-        const lines = content.split('\n');
+        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: '',
+                },
+            };
+        }
         const effectiveLimit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
         const endLine = startLine + effectiveLimit;
         const slice = lines.slice(startLine, endLine);
@@ -1870,7 +2123,7 @@ export class WorkspaceModule {
         let mount;
         let relativePath;
         try {
-            ({ mount, relativePath } = this.parsePath(input.path));
+            ({ mount, relativePath } = this.parseFilePath(input.path));
         }
         catch (err) {
             return {
@@ -1939,7 +2192,10 @@ export class WorkspaceModule {
         }
     }
     async handleWrite(input) {
-        const { mount, relativePath } = this.parsePath(input.path);
+        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.' };
+        }
+        const { mount, relativePath } = this.parseFilePath(input.path);
         if (mount.config.mode === 'read-only') {
             return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
         }
@@ -1949,112 +2205,204 @@ export class WorkspaceModule {
             return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
         }
         const buffer = Buffer.from(input.content, 'utf-8');
-        const materializeError = await this.withMount(mount, async () => {
-            await this.settleBeforeMutation(mount, relativePath);
-            const blobHash = store.storeBlob(buffer, 'text/plain');
-            return this.commitToolChange(mount, relativePath, { kind: 'set', blobHash, size: buffer.byteLength });
-        });
-        if (materializeError) {
-            return {
-                success: false,
-                error: `Wrote to Chronicle but failed to materialize "${input.path}" to disk: ${materializeError}. Downstream agents will not see this change until the next materialize call.`,
-                isError: true,
-            };
+        const receipt = { path: input.path, size: buffer.byteLength, hash: hashContent(input.content) };
+        let committed = false;
+        let refused;
+        let modeKept;
+        try {
+            ({ refused, modeKept } = 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.
+                const existing = store.treeGet(mount.treeStateId, relativePath);
+                return this.commitToolChange(mount, relativePath, { kind: 'set', blobHash, size: buffer.byteLength, ...(existing ? { mode: existing.mode } : {}) }, () => { committed = true; });
+            }));
         }
-        return {
-            success: true,
-            data: {
-                path: input.path,
-                size: Buffer.byteLength(input.content),
-                hash: hashContent(input.content),
-            },
-        };
+        catch (error) {
+            if (!committed)
+                throw error;
+            return storedButUnfinished('write', input.path, { threw: error instanceof Error ? error.message : String(error) });
+        }
+        if (refused !== null)
+            return storedButUnfinished('write', input.path, { refused });
+        return { success: true, data: { ...receipt, ...(modeKept ? { modeKept } : {}) } };
     }
     async handleEdit(input) {
-        const { mount, relativePath } = this.parsePath(input.path);
+        // Refused before anything is read: an empty oldString matches between
+        // every character, and UTF-8 can't store a lone surrogate.
+        if (input.oldString === '') {
+            return { success: false, isError: true, error: 'The edit did nothing: "oldString" is empty, and an empty string matches between every character. Give the text to replace.' };
+        }
+        for (const field of ['oldString', 'newString']) {
+            if (LONE_SURROGATE.test(input[field])) {
+                return { success: false, isError: true, error: `The edit did nothing: "${field}" holds a lone UTF-16 surrogate, which UTF-8 can't store.` };
+            }
+        }
+        const { mount, relativePath } = this.parseFilePath(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();
-        return this.withMount(mount, async () => {
-            const report = await this.ensureSynced(mount, relativePath);
-            await this.settleBeforeMutation(mount, relativePath); // before the edit reads the entry
-            const entry = store.treeGet(mount.treeStateId, relativePath);
-            if (!entry) {
-                return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
-            }
-            const blob = store.getBlob(entry.blobHash);
-            if (!blob) {
-                return { success: false, error: `Blob not found for: ${input.path}`, isError: true };
-            }
-            let content = blob.toString('utf-8');
-            // Validate uniqueness
-            if (!input.replaceAll) {
-                const count = content.split(input.oldString).length - 1;
+        let committed = false;
+        let appliedNote = null;
+        try {
+            return await this.withMount(mount, async () => {
+                // The edit applies to 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. The pass settles a pending intent on the path too, as
+                // settleBeforeMutation's would, and the commit enforces the rest
+                // (commitToolChange). A write passes over its path only to settle a
+                // pending intent, since it replaces the whole file. As every file
+                // tool's pass does, it names the path 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: [relativePath] }, { named: true });
+                const report = pass.reports.get(relativePath);
+                // 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 edit then
+                // writes at the mode disk has, so it leaves nothing to say.
+                const took = (op) => pass.ops.some((o) => o.path === relativePath && o.op === op && !o.modeOnly);
+                // Which copy the edit 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
+                // workspace didn't hold has no older copy, so taking it in needs no
+                // word.
+                const whichCopy = (verb) => took('modified')
+                    ? `Disk's copy had changed since the workspace last agreed with it, so it was taken in first, and the edit ${verb} that text.`
+                    : report?.state === 'unverified'
+                        ? `The path couldn't be checked against disk (${report.note ?? 'not observed'}), so the edit ${verb} the workspace's copy.`
+                        : report?.state === 'disk-missing-provenance-unknown'
+                            ? `Disk has no copy of this file, and nothing records whether it was deleted there, so the edit ${verb} the workspace's copy.`
+                            : null;
+                // A conflict the pass found is named when the edit is refused for the
+                // text it found, on either kind of mount, and on a success where the
+                // mount doesn't push, since such a mount keeps the conflict until
+                // materialize or sync settles it. A pushing mount's success met none
+                // (below). A stored edit that couldn't finish leaves it to the push's
+                // reason, which names the conflict, or to ls, which its answer points to.
+                const conflict = report?.state === 'conflict' ? report.conflict?.kind ?? 'both-changed' : null;
+                // Where disk has no copy now, whatever the conflict's kind, a sync of
+                // the path takes disk's deletion and a forced materialize writes the
+                // workspace's copy back. Where it has one, a sync keeps it and gives
+                // up the workspace's, whether or not the workspace can hold disk's
+                // copy: one it can't hold stays on disk alone.
+                const conflictNote = (where) => conflict === null ? null
+                    : `The path is in conflict with disk (${conflict}): the edit ${where} the workspace's copy. ` + (report?.diskNow === 'absent'
+                        ? "Sync the path to take disk's deletion, which removes the workspace's copy, or materialize it with force to write the workspace's copy back to disk."
+                        : "Sync the path to keep disk's copy and give up the workspace's, or materialize it with force to write the workspace's over disk's.");
+                const suffix = [whichCopy('looked in'), conflictNote('looked in')].filter((n) => n !== null).map((n) => ` ${n}`).join('');
+                appliedNote = whichCopy('applied to');
+                const entry = store.treeGet(mount.treeStateId, relativePath);
+                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.
+                    const error = took('deleted') && report?.state !== 'disk-only'
+                        ? `File not found: ${input.path}. Disk's copy was deleted since the workspace last agreed with it, and that was taken in first.`
+                        : this.notInWorkspace(input.path, report);
+                    return { success: false, error, isError: true };
+                }
+                const blob = store.getBlob(entry.blobHash);
+                if (!blob) {
+                    return { success: false, error: `Blob not found for: ${input.path}`, isError: true };
+                }
+                // Decoding would turn each invalid sequence into U+FFFD, and writing
+                // the text back would change bytes the edit never named.
+                if (!isUtf8(blob)) {
+                    return {
+                        success: false,
+                        isError: true,
+                        error: `The edit did nothing: ${input.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.${suffix}`,
+                    };
+                }
+                let content = blob.toString('utf-8');
+                // An edit that would replace nothing is refused, replaceAll or not;
+                // without replaceAll, the text must occur once, and the refusal says
+                // how often it does. With replaceAll, whether it occurs is enough.
+                const count = input.replaceAll
+                    ? Number(content.includes(input.oldString))
+                    : content.split(input.oldString).length - 1;
                 if (count === 0) {
-                    return { success: false, error: `String not found in ${input.path}`, isError: true };
+                    return { success: false, error: `String not found in ${input.path}.${suffix}`, isError: true };
                 }
-                if (count > 1) {
+                if (count > 1 && !input.replaceAll) {
                     return {
                         success: false,
-                        error: `String found ${count} times in ${input.path}. Use replaceAll: true or provide more context.`,
+                        error: `String found ${count} times in ${input.path}. Use replaceAll: true or provide more context.${suffix}`,
                         isError: true,
                     };
                 }
-            }
-            content = input.replaceAll
-                ? content.replaceAll(input.oldString, input.newString)
-                : content.replace(input.oldString, input.newString);
-            const newBuffer = Buffer.from(content, 'utf-8');
-            const newBlobHash = store.storeBlob(newBuffer, 'text/plain');
-            const materializeError = await this.commitToolChange(mount, relativePath, {
-                kind: 'set',
-                blobHash: newBlobHash,
-                size: newBuffer.byteLength,
-                mode: entry.mode,
-            });
-            if (materializeError) {
+                // A replacer function, so that the new text goes in as given: in a
+                // replacement string, $&, $$, $' and $` are patterns.
+                content = input.replaceAll
+                    ? content.replaceAll(input.oldString, () => input.newString)
+                    : content.replace(input.oldString, () => input.newString);
+                const newBuffer = Buffer.from(content, 'utf-8');
+                const newBlobHash = store.storeBlob(newBuffer, 'text/plain');
+                const { refused, modeKept } = await this.commitToolChange(mount, relativePath, {
+                    kind: 'set',
+                    blobHash: newBlobHash,
+                    size: newBuffer.byteLength,
+                    mode: entry.mode,
+                }, () => { committed = true; });
+                if (refused !== null)
+                    return storedButUnfinished('edit', input.path, { refused }, appliedNote);
+                // The edit makes the path the workspace's own change (commitToolChange),
+                // so a file disk lacked goes back with this edit's push, or with the
+                // next materialize where the mount doesn't push. A push that didn't
+                // complete answers above, with its reason. One that completed met no
+                // conflict, since this push, unforced, stops at one: the edit made the
+                // two copies agree, which settles it, or there was none. So only a
+                // mount that doesn't push still holds the conflict the pass found.
+                const pushes = this.pushesOnCommit(mount);
+                const backOnDisk = report?.state === 'disk-missing-provenance-unknown'
+                    ? `${pushes ? 'Its push put the file back on disk' : 'A materialize of the path puts it back on disk'}; if it was deleted there on purpose, delete it here too.`
+                    : null;
+                const notes = [appliedNote, backOnDisk, pushes ? null : conflictNote('is in')].filter((n) => n !== null);
                 return {
-                    success: false,
-                    error: `Edited Chronicle but failed to materialize "${input.path}" to disk: ${materializeError}. Downstream agents will not see this change until the next materialize call.`,
-                    isError: true,
+                    success: true,
+                    data: {
+                        path: input.path,
+                        size: newBuffer.byteLength,
+                        ...(notes.length > 0 ? { note: notes.join(' ') } : {}),
+                        ...(modeKept ? { modeKept } : {}),
+                    },
                 };
-            }
-            return {
-                success: true,
-                data: {
-                    path: input.path,
-                    size: newBuffer.byteLength,
-                },
-            };
-        });
+            });
+        }
+        catch (error) {
+            if (!committed)
+                throw error;
+            return storedButUnfinished('edit', input.path, { threw: error instanceof Error ? error.message : String(error) }, appliedNote);
+        }
     }
     async handleDelete(input) {
-        const { mount, relativePath } = this.parsePath(input.path);
+        const { mount, relativePath } = this.parseFilePath(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();
-        return this.withMount(mount, async () => {
-            const report = await this.ensureSynced(mount, relativePath);
-            await this.settleBeforeMutation(mount, relativePath);
-            const entry = store.treeGet(mount.treeStateId, relativePath);
-            if (!entry) {
-                return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
-            }
-            const materializeError = await this.commitToolChange(mount, relativePath, { kind: 'remove', previousHash: entry.blobHash });
-            if (materializeError) {
-                return {
-                    success: false,
-                    error: `Removed from Chronicle but did not unlink "${input.path}" from disk: ${materializeError}. ` +
-                        'The disk copy stays (ls shows its state) until materialize with applyDeletions removes it.',
-                    isError: true,
-                };
-            }
-            // 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 }, keepWhenWithheld: ['path', 'deleted'] };
-        });
+        let committed = false;
+        try {
+            return await this.withMount(mount, async () => {
+                const report = await this.ensureSynced(mount, relativePath);
+                await this.settleBeforeMutation(mount, relativePath);
+                const entry = store.treeGet(mount.treeStateId, relativePath);
+                if (!entry) {
+                    return { success: false, error: this.notInWorkspace(input.path, report), isError: true };
+                }
+                const { refused } = 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 }, keepWhenWithheld: ['path', 'deleted'] };
+            });
+        }
+        catch (error) {
+            if (!committed)
+                throw error;
+            return storedButUnfinished('delete', input.path, { threw: error instanceof Error ? error.message : String(error) });
+        }
     }
     async handleLs(input) {
         const store = this.getStore();
@@ -2118,8 +2466,13 @@ export class WorkspaceModule {
         const mountsToSearch = input.path
             ? [this.parsePath(input.path)]
             : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
+        // 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.
+        const patternDir = literalDirOf(input.pattern);
         for (const { mount, relativePath } of mountsToSearch) {
-            const pass = await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }));
+            const start = await this.walkStart(mount, relativePath, patternDir);
+            const pass = await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: start, recursive: true }));
             for (const report of [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path))) {
                 const testPath = relativePath ? report.path.slice(relativePath.length + 1) : report.path;
                 if (regex.test(testPath)) {
@@ -2147,9 +2500,14 @@ export class WorkspaceModule {
             regex = new RegExp(input.pattern);
         }
         catch (e) {
-            return { success: false, error: `Invalid regex: ${input.pattern}`, isError: true };
+            // 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 };
         }
         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`.
+        const filterDir = input.glob ? literalDirOf(input.glob) : '';
         const contextBefore = input.contextBefore ?? 0;
         const contextAfter = input.contextAfter ?? 0;
         const mountsToSearch = input.path
@@ -2159,7 +2517,7 @@ export class WorkspaceModule {
         const skipped = [];
         const incomplete = [];
         const search = (content) => {
-            const lines = content.split('\n');
+            const lines = linesOf(content);
             const found = [];
             for (let i = 0; i < lines.length; i++) {
                 if (regex.test(lines[i])) {
@@ -2175,6 +2533,19 @@ export class WorkspaceModule {
             return found;
         };
         for (const { mount, relativePath } 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.
+            if (this.holderOf(mount.config.name, relativePath)) {
+                incomplete.push({ path: `${mount.config.name}/${relativePath}`, reason: this.otherMountNote(mount.config.name, relativePath, 'list') });
+                continue;
+            }
+            // A `path` and a filter whose directories don't overlap leave no file
+            // the filter can let through, so nothing is searched.
+            const deeper = deeperOf(relativePath, filterDir);
+            if (deeper === null)
+                continue;
+            const start = await this.walkStart(mount, relativePath, deeper === relativePath ? '' : deeper.slice(relativePath ? relativePath.length + 1 : 0));
             await this.withMount(mount, async () => {
                 // A `path` naming a single file greps just that file; otherwise it is a
                 // directory prefix. (A file path once produced the prefix "notes.md/"
@@ -2190,7 +2561,7 @@ export class WorkspaceModule {
                 for (let attempt = 0; attempt < 3 && pass === null; attempt++) {
                     const next = await this.passUnlocked(mount, fileScope
                         ? { kind: 'paths', paths: [relativePath] }
-                        : { kind: 'dir', dir: relativePath, recursive: true });
+                        : { kind: 'dir', dir: start, recursive: true });
                     if (next.branchId === undefined || next.branchId === store.currentBranch().id)
                         pass = next;
                 }
@@ -2218,6 +2589,11 @@ export class WorkspaceModule {
                         });
                         continue;
                     }
+                    // A path in another mount's directory is that mount's: grep gives
+                    // none of this mount's copy of it, as read refuses it. Beneath a
+                    // scope it's passed over by design, like the directory.
+                    if (inOtherMount(report.path, this.othersOf(mount.config.name)))
+                        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;
@@ -2280,7 +2656,8 @@ export class WorkspaceModule {
                 continue;
             const entries = store.treeList(mount.treeStateId);
             const currentSeq = store.currentSequence();
-            const intents = this.intents.get(name).list();
+            const own = this.ownPaths(mount);
+            const intents = this.intents.get(name).list().filter(([p]) => own(p));
             const conflictPaths = intents.filter(([, bi]) => bi.conflict).map(([p]) => p);
             // A workspace deletion is pending until a push confirms it on disk:
             // left there without applyDeletions, or unlinked but unconfirmed.
@@ -2323,13 +2700,15 @@ export class WorkspaceModule {
      */
     materializeSelection(mount, explicitPath) {
         const store = this.getStore();
-        const intents = new Map(this.intents.get(mount.config.name).list(explicitPath));
+        const own = this.ownPaths(mount);
+        const intents = new Map(this.intents.get(mount.config.name).list(explicitPath).filter(([p]) => own(p)));
         const selected = new Set();
         if (explicitPath !== '') {
-            if (store.treeGet(mount.treeStateId, explicitPath))
+            if (store.treeGet(mount.treeStateId, explicitPath) && own(explicitPath))
                 selected.add(explicitPath);
             for (const e of store.treeList(mount.treeStateId, explicitPath + '/'))
-                selected.add(e.path);
+                if (own(e.path))
+                    selected.add(e.path);
             for (const [p, bi] of intents)
                 if (bi.tombstone || bi.conflict)
                     selected.add(p);
@@ -2343,10 +2722,24 @@ export class WorkspaceModule {
                 selected.add(p);
         return { paths: [...selected], inPlace: agreed > 0 };
     }
+    /**
+     * Whether a path of the mount is its own to push and to count as owed:
+     * not in another mount's directory nested in it. Copies the mount's tree
+     * holds there (stored before the nesting) stay in its history and its
+     * listings (and in status's fileCount, which counts the tree), passed over
+     * by its syncs, and left out of what it pushes and of status's pending
+     * changes, conflicts and workspace deletions.
+     */
+    ownPaths(mount) {
+        const others = this.othersOf(mount.config.name);
+        return (path) => !inOtherMount(path, others);
+    }
     /**
      * The workspace entries by what the evidence says of disk. `owed`: P
-     * differs from the entry (a draft, or a push still pending), or there is no
-     * P and the entry came from the workspace (a draft disk never had).
+     * differs from the entry (a draft, or a push still pending), the entry
+     * records a mode other than the one P agreed (a mode owed to disk), or
+     * there is no P and the entry came from the workspace (a draft disk never
+     * had).
      * `unchecked`: no P and no workspace origin, an entry from before the
      * evidence; a push agrees it, writes it where disk lacks it, or refuses it
      * as a conflict. `agreed`: how many have P = S, so disk holds them. Status
@@ -2361,12 +2754,19 @@ export class WorkspaceModule {
         const owed = [];
         const unchecked = [];
         let agreed = 0;
+        const own = this.ownPaths(mount);
         for (const e of store.treeList(mount.treeStateId)) {
+            if (!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)
+                owed.push(e.path);
             else
                 agreed++;
         }
@@ -2377,6 +2777,7 @@ export class WorkspaceModule {
         const allWritten = [];
         const allDeleted = [];
         const pendingDeletions = [];
+        const modesKept = [];
         let explicit = null;
         if (input.path)
             explicit = this.parsePath(input.path);
@@ -2414,6 +2815,13 @@ export class WorkspaceModule {
                 blocked.push({ mount: name, reason: 'a read-only mount: materialize writes nothing to it' });
                 continue;
             }
+            // A path named in another mount's directory, as holderOf resolves it,
+            // is that mount's: nothing of this mount's is pushed there, and the
+            // caller is told whose it is.
+            if (explicit && this.holderOf(name, explicit.relativePath)) {
+                blocked.push({ mount: name, reason: `${explicit.relativePath}: ${this.otherMountNote(name, explicit.relativePath, 'push')}` });
+                continue;
+            }
             const turn = await this.withMount(mount, async () => {
                 const branchId = store.currentBranch().id;
                 const reason = this.mountMaterializeBlockReason(store, mount);
@@ -2446,8 +2854,13 @@ export class WorkspaceModule {
             // Refusals ride the same skipped list as branch blocks: divergence must
             // be visible, not resolved silently either way.
             for (const s of pushed.skipped) {
-                blocked.push({ mount: name, reason: `${s.path}: ${s.reason}` });
+                const reason = s.reason === NOT_PUSHED_IN_OTHER_MOUNT ? this.otherMountNote(name, s.path, 'push') : s.reason;
+                blocked.push({ mount: name, reason: `${s.path}: ${reason}` });
             }
+            // Written paths whose mode stayed as disk had it: no refusal, so not
+            // among what was skipped.
+            for (const k of pushed.modesKept)
+                modesKept.push({ mount: name, ...k });
             // What disk still owes is kept by its evidence, so the watermark and
             // the pin only feed the branch guard. Both are the push's own: what it
             // planned from is what disk now reflects, whatever branch was selected
@@ -2488,10 +2901,11 @@ export class WorkspaceModule {
                     }
                     : {}),
                 ...(blocked.length > 0 ? { skipped: blocked } : {}),
+                ...(modesKept.length > 0 ? { modesKept } : {}),
             },
             // What disk lost, then what it was written: kept in the stub if the
-            // guard withholds the result (agent-framework #277). What was left or
-            // skipped, and why, is in the full result.
+            // guard withholds the result (agent-framework #277). What was left,
+            // skipped or written at disk's mode, and why, is in the full result.
             keepWhenWithheld: ['deleted', 'materialized'],
         };
     }
@@ -2562,7 +2976,8 @@ export class WorkspaceModule {
                     rootsAccepted.push(name);
                 if (!relativePath) {
                     // A full recheck: every file rehashed, nothing pending discarded.
-                    return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }, { rehash: true });
+                    // Past the mount's walkCap, it resumes where the last one stopped.
+                    return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }, { rehash: true, resume: true });
                 }
                 // An explicit path: the workspace takes disk's state there.
                 const prefix = relativePath + '/';
@@ -2575,7 +2990,7 @@ export class WorkspaceModule {
                 const opts = { rehash: true, adopt: () => true, branchId: askedOn, named: true };
                 if (!isDir)
                     return this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
-                const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, opts);
+                const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, { ...opts, resume: true });
                 // Something at the path itself is no part of a directory scope: a file
                 // disk has where the workspace holds a directory, or a workspace file
                 // where disk has a directory. Its own pass takes disk's state there
@@ -2629,13 +3044,20 @@ export class WorkspaceModule {
             for (const [reason, count] of pass.passedOver)
                 allPassedOver.push({ mount: name, reason, count });
             // A path named explicitly is synced even where the mount's ignore list
-            // covers it, and the result says so: a sync without a path passes
-            // over it, so nothing else keeps it current (agent-framework #276).
-            if (coveredByIgnore(relativePath, mount.config.ignore ?? [])) {
+            // or an editor's file name covers it, and the result says so: a sync
+            // 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, mount.config.ignore ?? [], this.othersOf(name));
+            if (passedOver !== undefined) {
                 allIgnored.push({
                     mount: name,
                     path: relativePath,
-                    note: 'this mount\'s ignore list covers it, so a sync without a path won\'t maintain it',
+                    note: passedOver === OTHER_MOUNT
+                        ? this.otherMountNote(name, relativePath, 'sync')
+                        : passedOver === IGNORED
+                            ? 'this mount\'s ignore list covers it, so a sync without a path won\'t maintain it'
+                            : 'it has an editor\'s swap or backup file name, or lies under one, so a sync without a path won\'t maintain it',
                 });
             }
         }
@@ -2704,10 +3126,14 @@ export class WorkspaceModule {
      * After an agent's completed tool batch, before anything continues its turn:
      * scan every `watch: 'on-agent-action'` mount, so what the batch's tools did
      * on disk (a shell command's files, a deletion) is in the workspace when the
-     * agent next looks. 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.
+     * 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
+     * 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.
      */
     async onToolBatchComplete(_agentName) {
         // Every agent's workspace is the store's current branch, so the agent
@@ -2774,6 +3200,10 @@ export class WorkspaceModule {
         const pass = this.withMount(mount, () => {
             if (mount.agentActionScanWaiting === scan)
                 mount.agentActionScanWaiting = undefined;
+            // From the mount's root, keeping no place, as a listing keeps none:
+            // on a mount over its walkCap, every batch's scan takes the first
+            // walkCap entries in the walk's order, and the place that syncs and
+            // catch-up scans resume from stays theirs.
             return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true });
         });
         scan.settled = pass.then((result) => {
@@ -2815,9 +3245,11 @@ export class WorkspaceModule {
         return AGENT_ACTION_SCAN_DEADLINE_MAX_MS;
     }
     /**
-     * Push one ProcessEvent per op for a pass's tree changes and new conflicts.
-     * A conflict rides the event for the disk change behind it (modified, or
-     * deleted for a disk deletion of a file with newer workspace changes).
+     * Push one ProcessEvent per op for a pass's tree changes and new conflicts,
+     * apart from an op that changes only a file's mode, which brings nothing
+     * new to read and makes none. A conflict rides the event for the disk
+     * change behind it (modified, or deleted for a disk deletion of a file with
+     * newer workspace changes).
      */
     emitFsEvents(mountName, ops, newConflicts = []) {
         if (!this.ctx || (ops.length === 0 && newConflicts.length === 0))
@@ -2832,8 +3264,12 @@ export class WorkspaceModule {
                 group.conflicts.push(full);
             byOp.set(op, group);
         };
-        for (const { path, op } of ops)
-            add(op, path, false);
+        // A path whose mode alone changed, on bytes already held, makes no
+        // event: it brings nothing new to read, and a `chmod -R` over a tree
+        // would otherwise reach every policy that matches its paths.
+        for (const { path, op, modeOnly } of ops)
+            if (!modeOnly)
+                add(op, path, false);
         for (const { path, op } of newConflicts)
             add(op, path, true);
         for (const [op, { paths, conflicts }] of byOp) {
@@ -2860,8 +3296,92 @@ function stateView(report) {
 // ==========================================================================
 // Utilities
 // ==========================================================================
+/** A lone UTF-16 surrogate, which UTF-8 can't store: in `u` mode, a pair is one code point. */
+const LONE_SURROGATE = /\p{Cs}/u;
+/**
+ * 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
+ * entry threw. It stays an error, since part of the call failed, but it leads
+ * with what the caller must know before acting on it: the change is stored,
+ * and sending it again could apply it twice. The push's reason says what disk
+ * holds and the way out, as materialize takes it. The text carries all of it,
+ * since an error's data reaches neither the model nor a code_execution
+ * script. An edit's note on which copy it applied to comes last.
+ */
+function storedButUnfinished(tool, path, outcome, note = null) {
+    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.' : '.');
+    const rest = 'refused' in outcome
+        ? ` Its push to disk didn't complete: ${outcome.refused}.`
+        : ` 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}` : '') };
+}
 /**
- * Convert a glob pattern to a RegExp.
+ * 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.
+ */
+function linesOf(content) {
+    const lines = content.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * The least each tool's whole-number fields may be, beside their schemas,
+ * whose type (membrane's ToolParameter) has no `minimum`.
+ */
+const INPUT_MINIMUMS = {
+    read: { offset: 1, limit: 1, offsetChars: 0, limitChars: 1 },
+    grep: { contextBefore: 0, contextAfter: 0 },
+};
+/**
+ * Why a tool call's input doesn't fit its tool's schema, or null when it does:
+ * an object, each required field present, and each field its schema calls a
+ * string, a boolean or an integer of that type, an integer at least its
+ * minimum. The workspace's schemas use no other types. Without it, an edit
+ * missing `newString` wrote the word "undefined", and an offset of 1.5
+ * numbered lines 1.5, 2.5 and on. A field the schema doesn't describe is left
+ * to its handler.
+ */
+function inputProblem(schema, input, minimums = {}) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return 'its input must be an object of the fields its schema lists';
+    }
+    const fields = input;
+    for (const name of schema.required ?? []) {
+        if (fields[name] === undefined)
+            return `"${name}" is required`;
+    }
+    for (const [name, value] of Object.entries(fields)) {
+        const type = schema.properties?.[name]?.type;
+        if (value === undefined || type === undefined)
+            continue;
+        const minimum = minimums[name];
+        const fits = type === 'string' ? typeof value === 'string'
+            : type === 'boolean' ? typeof value === 'boolean'
+                : type === 'integer'
+                    ? Number.isSafeInteger(value) && (minimum === undefined || value >= minimum)
+                    : true;
+        if (!fits) {
+            const wanted = type === 'string' ? 'a string'
+                : type === 'boolean' ? 'true or false'
+                    : minimum === undefined ? 'a whole number' : `a whole number of at least ${minimum}`;
+            const got = value === null ? 'null'
+                : typeof value === 'number' ? String(value)
+                    : Array.isArray(value) ? 'an array'
+                        : typeof value === 'object' ? 'an object'
+                            : `a ${typeof value}`;
+            return `"${name}" must be ${wanted}, not ${got}`;
+        }
+    }
+    return null;
+}
+/**
+ * Convert a glob pattern to a RegExp. Throws, naming the pattern, for a brace
+ * group it can't read: a "{" that never closes, a group inside another, or a
+ * group with no ",".
  */
 function globToRegex(pattern) {
     // Split pattern into segments, handling {a,b,c} alternation
@@ -2869,13 +3389,36 @@ function globToRegex(pattern) {
     let i = 0;
     while (i < pattern.length) {
         if (pattern[i] === '{') {
-            const closeIdx = pattern.indexOf('}', i);
-            if (closeIdx > i) {
-                const alternatives = pattern.slice(i + 1, closeIdx).split(',');
-                regex += '(?:' + alternatives.map(a => globPartToRegex(a)).join('|') + ')';
-                i = closeIdx + 1;
-                continue;
-            }
+            // A brace form this can't read is refused. A `{` that never closes, read
+            // as a literal, would almost always answer with no matches, and with it
+            // refused, each pass of this loop moves past at least one character. A
+            // group closes at the `}` that brings the braces open since its `{` back
+            // to none, so a `{` that never closes is named as that, even with a
+            // closed group after it. A group inside another would be split at the
+            // inner `}`, so `{a,{b,c}}` would match `a}` but not `a`, and a group
+            // with no `,` would lose its braces, so `{name}` would match `name` and
+            // never a file named `{name}`, and `{1..3}` would match only `1..3`.
+            let depth = 0;
+            let closeIdx = -1;
+            for (let j = i; j < pattern.length && closeIdx < 0; j++) {
+                if (pattern[j] === '{')
+                    depth++;
+                else if (pattern[j] === '}' && --depth === 0)
+                    closeIdx = j;
+            }
+            if (closeIdx < 0)
+                throw new Error(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'));
+            }
+            if (!group.includes(',')) {
+                throw new Error(braceRefusal(pattern, 'has a "{" group with no ","; a group needs two or more alternatives, separated by ","'));
+            }
+            const alternatives = group.split(',');
+            regex += '(?:' + alternatives.map(a => globPartToRegex(a)).join('|') + ')';
+            i = closeIdx + 1;
+            continue;
         }
         // Accumulate non-brace characters, convert as a chunk
         let chunk = '';
@@ -2889,6 +3432,36 @@ function globToRegex(pattern) {
     }
     return new RegExp(`^${regex}$`);
 }
+/**
+ * The directory a glob pattern names before its first wildcard, beneath
+ * which every path it matches lies: its leading segments that hold none of
+ * globToRegex's wildcards (`*`, `?`, `{`), short of the last segment, which
+ * names the files. '' when the pattern starts with a wildcard or has a
+ * single segment. A segment that's empty, `.` or `..`, which no path
+ * matched holds, is one no directory listing holds either, so walkStart
+ * stops before it.
+ */
+function literalDirOf(pattern) {
+    const dir = [];
+    for (const segment of pattern.split('/').slice(0, -1)) {
+        if (/[*?{]/.test(segment))
+            break;
+        dir.push(segment);
+    }
+    return dir.join('/');
+}
+/** The deeper of two mount-relative directories, '' being the root, or null when neither holds the other. */
+function deeperOf(a, b) {
+    if (a === '' || b === a || b.startsWith(a + '/'))
+        return b;
+    if (b === '' || a.startsWith(b + '/'))
+        return a;
+    return null;
+}
+/** A glob's refusal of a brace form it can't read, with the way to match a literal "{". */
+function braceRefusal(pattern, problem) {
+    return `glob pattern ${JSON.stringify(pattern)} ${problem}. To match a "{" in a name, put "?" in its place.`;
+}
 function globPartToRegex(part) {
     return part
         .replace(/[.+^$()|[\]\\]/g, '\\$&')