@animalabs/agent-framework 0.21.0 → 0.22.0

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

@@ -5,11 +5,22 @@
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
 import { constants as fsConstants } from 'node:fs';
-import { open, readFile, stat, writeFile, unlink, mkdir, lstat, realpath } from 'node:fs/promises';
-import { join, resolve, relative, dirname, sep } from 'node:path';
+import { open, readFile, stat, lstat, realpath } from 'node:fs/promises';
+import { join, resolve, relative, sep } from 'node:path';
 import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher } from './watcher.js';
-import { syncFromFs, materializeToFs, hashContent, isBinary, DEFAULT_MAX_FILE_SIZE } from './sync.js';
+import { hashContent, DEFAULT_MAX_FILE_SIZE } from './sync.js';
+import { DiskAgreement, sameRootIdentity } from './disk-agreement.js';
+import { BranchIntents } from './branch-intent.js';
+import { filesystemTrustsCtime, locateRoot } from './observe.js';
+import { TOOL_BATCH_HOOK_TIMEOUT_MS } from '../../module-registry.js';
+import { 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;
+/** 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. */
+const AGENT_ACTION_SCAN_DEADLINE_MAX_MS = TOOL_BATCH_HOOK_TIMEOUT_MS - 1_000;
 class WorkspaceImageReadError extends Error {
     code;
     constructor(code, message) {
@@ -438,9 +449,22 @@ export class WorkspaceModule {
     name = 'workspace';
     ctx = null;
     store = null;
+    /** Set once stop has drained and saved, cleared by start (running()). */
+    stopped = false;
     config;
     mounts = new Map();
     watchers = new Map();
+    /** What disk last agreed with (global records); created with the store. */
+    agreement = null;
+    /** Branch-local intent per mount. */
+    intents = new Map();
+    /** Each mount's turn: the tail of its serialized passes and writes. */
+    mountTurns = new Map();
+    /** Whether an over-bound agentActionScanDeadlineMs has been warned about. */
+    warnedScanDeadline = false;
+    /** 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();
     /** 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
@@ -482,38 +506,112 @@ export class WorkspaceModule {
      */
     initStore(store) {
         this.store = store;
-        // Register tree states for each mount
+        // 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`;
-            try {
-                store.registerState({
-                    id: treeStateId,
-                    strategy: 'tree',
-                    deltaSnapshotEvery: this.config.deltaSnapshotEvery ?? 50,
-                    fullSnapshotEvery: this.config.fullSnapshotEvery ?? 10,
-                });
-            }
-            catch {
-                // State already registered (restart scenario)
+            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)
+                }
             }
             const mountState = {
                 config: mount,
                 treeStateId,
+                intentTreeStateId,
                 lastMaterializedSeq: 0,
                 suppressedPaths: new Set(),
                 initialSyncDone: false,
                 lastMaterializedBranchId: null,
-                materializedHashes: new Map(),
                 watcherReadyAt: null,
                 watcherError: null,
             };
             this.mounts.set(mount.name, mountState);
+            this.intents.set(mount.name, new BranchIntents(store, intentTreeStateId));
         }
+        // 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.open(this.config.mounts.map((m) => ({ name: m.name, root: resolve(m.path) })));
         this.applySavedState();
         this.ensureRunning();
     }
+    // ==========================================================================
+    // Reconciliation plumbing
+    // ==========================================================================
+    /**
+     * Run `fn` with the mount to itself: observation, decision and effect never
+     * interleave with another pass or a tool write on the same mount (a disk
+     * observation taken before an autoMaterialize write and applied after it
+     * would ingest old bytes over the new entry). Not re-entrant: code holding
+     * a mount's turn calls the unlocked helpers.
+     */
+    withMount(mount, fn) {
+        const name = mount.config.name;
+        const previous = this.mountTurns.get(name) ?? Promise.resolve();
+        const run = previous.then(fn, fn);
+        this.mountTurns.set(name, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    agreementOrThrow() {
+        if (!this.agreement)
+            throw new Error('Workspace store not initialized');
+        return this.agreement;
+    }
+    /** The view reconciliation needs of a mount, refreshed per pass. */
+    async runtime(mount) {
+        const root = resolve(mount.config.path);
+        const rootReal = await realpath(root).catch(() => root);
+        let trustedDev = this.ctimeTrust.get(rootReal);
+        if (trustedDev === undefined) {
+            const dev = (await stat(rootReal, { bigint: true }).catch(() => null))?.dev;
+            trustedDev = dev !== undefined && (await filesystemTrustsCtime(rootReal)) ? dev.toString() : null;
+            this.ctimeTrust.set(rootReal, trustedDev);
+        }
+        return {
+            name: mount.config.name,
+            view: {
+                root,
+                rootIdentity: this.agreementOrThrow().rootIdentity(mount.config.name),
+                followSymlinks: mount.config.followSymlinks === true,
+                maxFileSize: mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE,
+                ignore: mount.config.ignore ?? [],
+            },
+            rootReal,
+            ctimeTrustedDev: trustedDev,
+            treeStateId: mount.treeStateId,
+            intents: this.intents.get(mount.config.name),
+            readOnly: mount.config.mode === 'read-only',
+        };
+    }
+    /** 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;
+        this.emitFsEvents(mount.config.name, result.ops, result.newConflicts);
+        return result;
+    }
+    /** One store→disk push; the caller holds the mount's turn. */
+    async pushUnlocked(mount, paths, opts = {}) {
+        const watcher = this.watchers.get(mount.config.name);
+        return pushPaths(this.getStore(), this.agreementOrThrow(), await this.runtime(mount), paths, {
+            ...opts,
+            beforeEffect: (p) => watcher?.suppress(p),
+        });
+    }
     async start(ctx) {
         this.ctx = ctx;
+        this.stopped = false;
         // Decode persisted state if restarting; application waits until mounts
         // exist (see applySavedState) — in the Host ordering they don't yet.
         if (ctx.isRestart) {
@@ -535,9 +633,18 @@ export class WorkspaceModule {
             return;
         for (const [name, meta] of Object.entries(this.savedState.mounts)) {
             const mount = this.mounts.get(name);
-            if (mount) {
+            // A mount materialized this session already (a call between initStore
+            // and start) has a pin and watermark newer than anything saved.
+            if (mount && mount.lastMaterializedBranchId === null && mount.lastMaterializedSeq === 0) {
                 mount.lastMaterializedSeq = meta.lastMaterializedSeq;
                 mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
+                // A store that ran #169's stop-time baselines (#109) saved them here
+                // too. They aren't carried over as evidence: #169 recorded no root,
+                // so nothing binds them to the directory they describe, and an empty
+                // mountpoint at the next start would read as every file deleted.
+                // Such a store gains its evidence from its first pass instead: a
+                // file disk agrees with is recorded, and anything else is a conflict
+                // or unknown provenance, never an adoption.
                 // watcherReadyAt intentionally not restored — each session must
                 // observe its own watcher attach, otherwise a stale timestamp
                 // would hide a new-session attach failure.
@@ -669,12 +776,10 @@ export class WorkspaceModule {
                 });
                 watcher.start();
                 this.watchers.set(name, watcher);
-                // Chokidar is started with ignoreInitial:true, so files already on
-                // disk at session start would be invisible. Trigger one syncFromFs
-                // pass — syncFromFs diffs disk against the tree state, so only files
-                // new-to-this-session's-tree fire workspace:created events. Fresh
-                // sessions see the existing catalog; restarts only see what appeared
-                // while the session was down.
+                // 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({
@@ -690,9 +795,9 @@ export class WorkspaceModule {
         if (!store || !mount)
             return;
         try {
-            const result = await syncFromFs(store, mount);
-            mount.initialSyncDone = true;
-            this.emitFsEvents(mountName, result.synced, result.conflicts);
+            // 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 }));
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -704,6 +809,24 @@ export class WorkspaceModule {
         }
     }
     async stop() {
+        // 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()) {
+            await watcher.stop();
+        }
+        this.watchers.clear();
+        for (;;) {
+            const tails = [...this.mountTurns.values()];
+            await Promise.all(tails);
+            const now = [...this.mountTurns.values()];
+            if (now.length === tails.length && now.every((tail, i) => tail === tails[i]))
+                break;
+        }
+        // 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;
@@ -718,11 +841,6 @@ export class WorkspaceModule {
             }
             this.ctx.setState(state);
         }
-        // Stop watchers
-        for (const watcher of this.watchers.values()) {
-            await watcher.stop();
-        }
-        this.watchers.clear();
         this.ctx = null;
     }
     /** Mount names + modes, for peer callers (framework spill/journal paths)
@@ -796,7 +914,9 @@ export class WorkspaceModule {
             },
             {
                 name: 'delete',
-                description: 'Delete a file from the workspace.',
+                description: 'Delete a file from the workspace. On a mount without autoMaterialize the disk copy stays, '
+                    + 'listed as workspace-deleted (no scan brings it back), until materialize with applyDeletions removes it '
+                    + 'or a sync of the path restores it.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -807,7 +927,14 @@ export class WorkspaceModule {
             },
             {
                 name: 'ls',
-                description: 'List directory contents from the workspace tree.',
+                description: 'List a directory, checked against disk first. Each file has a state: synced; '
+                    + 'workspace-draft (the workspace has changes disk lacks); workspace-deleted (deleted in the workspace, '
+                    + '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; '
+                    + 'disk-missing-provenance-unknown; unverified (disk could not be checked). `incomplete` names regions '
+                    + 'the listing could not see.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -818,7 +945,7 @@ export class WorkspaceModule {
             },
             {
                 name: 'glob',
-                description: 'Find files matching a glob pattern in the workspace.',
+                description: 'Find files matching a glob pattern, checked against disk first; each match carries its state, as ls describes.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -830,7 +957,11 @@ export class WorkspaceModule {
             },
             {
                 name: 'grep',
-                description: 'Search file contents with a regex pattern.',
+                description: 'Search stored file text with a regex pattern, checked against disk first. Each result says '
+                    + 'which version matched: the workspace\'s (with its state); the disk version kept with a conflict '
+                    + '(conflicting-disk); or, once disk has changed since the conflict was recorded, that recorded version '
+                    + '(recorded-disk). Disk versions it could not search are listed as skipped: disk-only files (binary or '
+                    + 'over the size limit), and a conflict\'s disk version that is binary, oversize, or newer than the one recorded.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -855,24 +986,45 @@ export class WorkspaceModule {
             },
             {
                 name: 'materialize',
-                description: 'Write workspace files to the real filesystem. Use after writing/editing to push changes to disk.',
+                description: 'Write workspace files to the real filesystem. Use after writing/editing to push changes to disk. '
+                    + 'Never deletes disk files unless applyDeletions is given; lists workspace deletions it left on disk.',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        path: { type: 'string', description: 'Specific path to materialize (optional — defaults to all changed)' },
+                        path: { type: 'string', description: 'Specific path to materialize (optional — defaults to what disk still owes: workspace edits, conflicts, workspace deletions, and files never checked against disk)' },
                         mount: { type: 'string', description: 'Specific mount (optional)' },
-                        force: { type: 'boolean', description: 'Materialize even if the current branch has diverged from the branch last written to disk (default false). Only needed for genuine divergence — descendant branches pass automatically.' },
+                        force: { type: 'boolean', description: 'Overwrite files whose disk copy changed since it last agreed with the workspace (another writer, or a conflict), and materialize even if the current branch has diverged from the branch last written to disk (default false). Without it, divergent files are skipped and listed. A file the workspace has not changed is left as disk has it unless you name its path.' },
+                        applyDeletions: { type: 'boolean', description: 'Also delete from disk the files deleted in the workspace whose disk copy is one the workspace holds (default false). With force, also those whose disk copy changed since.' },
                     },
                 },
             },
             {
                 name: 'sync',
-                description: 'Pull filesystem state into the workspace. Detects user changes on disk.',
+                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), '
+                    + '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`, '
+                    + 'what that did to the workspace copy (absent when it changed none: a deletion or conflict given up for '
+                    + 'a disk copy the workspace can\'t hold). '
+                    + 'A mount whose root is not the directory disk last agreed with (an unmounted drive, a replaced '
+                    + '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.',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        path: { type: 'string', description: 'Specific path to sync (optional — defaults to all)' },
+                        path: { type: 'string', description: 'Specific path to take from disk (optional — defaults to a full recheck)' },
                         mount: { type: 'string', description: 'Specific mount (optional)' },
+                        acceptRoot: {
+                            type: 'boolean',
+                            description: 'Take each mount\'s root as it is now when it is not the directory disk last agreed with: '
+                                + 'a directory replaced on purpose, or a drive that came back under a new device number (default false). '
+                                + 'What was recorded about the old one is set aside, so every file is compared afresh: a file disk '
+                                + 'and the workspace agree on agrees again, a differing one is a conflict, and a workspace file the '
+                                + 'root lacks stays in the workspace. Not with path. Leave it off while a drive is merely unplugged: '
+                                + 'its empty mountpoint would become the root.',
+                        },
                     },
                 },
             },
@@ -881,9 +1033,52 @@ export class WorkspaceModule {
     // ==========================================================================
     // Tool Dispatch
     // ==========================================================================
+    generatedTextFiles = new Map();
+    /** Compare the same normalized physical path for registration and tool access. */
+    generatedFileKey(path) {
+        const slash = path.indexOf('/');
+        const mountName = slash < 0 ? path : path.slice(0, slash);
+        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))
+            throw new Error(`Path traversal detected: "${path}"`);
+        return resolved;
+    }
+    findGeneratedTextFile(path) {
+        if (!this.generatedTextFiles.size)
+            return undefined;
+        try {
+            return this.generatedTextFiles.get(this.generatedFileKey(path));
+        }
+        catch {
+            // Not an alias of a valid generated file. Let the selected tool return
+            // its established validation error (including image-specific errors).
+            return undefined;
+        }
+    }
+    /** Generated files bypass stored blobs so every read reflects current definitions. */
+    registerGeneratedTextFile(path, read, agentName) {
+        const [mount, ...parts] = path.split('/');
+        if (!this.config.mounts.some(m => m.name === mount) || !parts.length
+            || parts.some(p => !p || p === '.' || p === '..') || this.generatedTextFiles.has(this.generatedFileKey(path)))
+            throw new Error(`Duplicate/invalid generated path: ${path}`);
+        this.generatedTextFiles.set(this.generatedFileKey(path), { read, agentName });
+    }
     async handleToolCall(call) {
+        if (!this.running())
+            return { success: false, isError: true, error: NOT_RUNNING };
         try {
             const input = call.input;
+            const generated = typeof input?.path === 'string' ? this.findGeneratedTextFile(input.path) : undefined;
+            if (generated) {
+                if (call.callerAgentName !== generated.agentName)
+                    return { success: false, isError: true, error: 'Generated file belongs to another agent' };
+                if (call.name !== 'read')
+                    return { success: false, isError: true, error: 'Generated file is read-only; edit the presentation configuration instead' };
+                return await this.handleRead(input, generated.read());
+            }
             switch (call.name) {
                 case 'read': return await this.handleRead(input);
                 case 'read_image': return await this.handleReadImage(input);
@@ -1002,8 +1197,25 @@ export class WorkspaceModule {
      * mount, through the same Chronicle-tree + auto-materialize path as the
      * `write` tool. Public API for the framework's synthesized `save_image`
      * tool and other peer callers that hold bytes rather than text.
+     *
+     * `branch`, when given, ties the write to that branch: the store's current
+     * branch is checked where the tree entry is set, nothing yielding between
+     * the check and the entry, so the file's tree entry lands on that branch or
+     * the write is refused, with `data: { branchLeft: true }`. A mount has one
+     * directory on disk, so with autoMaterialize the file's copy there is
+     * written like any other write's. The tool-result guard writes a
+     * withheld original this way, for the branch its stub is on
+     * (agent-framework #277).
+     *
+     * A write whose tree entry is set but that then fails returns success
+     * false with `data: { inChronicle: true }`: its copy on disk was refused, or
+     * something after the entry (recording its intent, the event, the push)
+     * threw. The workspace's tools read the file from the tree, so it is there
+     * for them, on the branch that was current when the entry was set.
      */
-    async writeBinary(mountPrefixedPath, data, mimeType) {
+    async writeBinary(mountPrefixedPath, data, mimeType, options = {}) {
+        if (!this.running())
+            return { success: false, isError: true, error: NOT_RUNNING };
         let mount;
         let relativePath;
         try {
@@ -1024,24 +1236,37 @@ export class WorkspaceModule {
             return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
         }
         const store = this.getStore();
-        const blobHash = store.storeBlob(data, mimeType);
-        store.treeSet(mount.treeStateId, relativePath, {
-            blobHash,
-            size: data.byteLength,
-            mode: 0o644,
-        });
-        const materializeError = await this.autoMaterialize(mount, relativePath, 'write', data);
-        if (materializeError) {
+        return this.withMount(mount, async () => {
+            await this.settleBeforeMutation(mount, relativePath);
+            // Checked inside the mount's turn, after anything the write waited on:
+            // commitToolChange sets the tree entry before it first yields.
+            if (options.branch !== undefined && store.currentBranch().name !== options.branch) {
+                return { success: false, error: 'the workspace had left the branch this file is for', isError: true, data: { branchLeft: true } };
+            }
+            const blobHash = store.storeBlob(data, mimeType);
+            let committed = false;
+            let failure;
+            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}.`;
+            }
+            catch (error) {
+                if (!committed)
+                    throw error;
+                failure = `Stored "${mountPrefixedPath}" in Chronicle, but the rest of the write failed: ${error instanceof Error ? error.message : String(error)}.`;
+            }
+            if (failure !== null) {
+                // The file is in the Chronicle tree, where the workspace's tools read
+                // it. `inChronicle` lets a caller that needs the file readable tell
+                // this from a write that never happened (agent-framework #281).
+                return { success: false, error: failure, isError: true, data: { inChronicle: true } };
+            }
             return {
-                success: false,
-                error: `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`,
-                isError: true,
+                success: true,
+                data: { path: mountPrefixedPath, size: data.byteLength, mimeType },
             };
-        }
-        return {
-            success: true,
-            data: { path: mountPrefixedPath, size: data.byteLength, mimeType },
-        };
+        });
     }
     /**
      * Read a file's raw bytes from a mount (through the Chronicle tree, synced
@@ -1049,6 +1274,8 @@ export class WorkspaceModule {
      * `read_image` tool and other peer callers that need binary content.
      */
     async readBinary(mountPrefixedPath) {
+        if (!this.running())
+            return { error: NOT_RUNNING };
         let mount;
         let relativePath;
         try {
@@ -1058,14 +1285,16 @@ export class WorkspaceModule {
             return { error: error instanceof Error ? error.message : String(error) };
         }
         const store = this.getStore();
-        await this.ensureSynced(mount, relativePath);
-        const entry = store.treeGet(mount.treeStateId, relativePath);
-        if (!entry)
-            return { error: `File not found: ${mountPrefixedPath}` };
-        const blob = store.getBlob(entry.blobHash);
-        if (!blob)
-            return { error: `Blob not found for: ${mountPrefixedPath}` };
-        return { data: blob };
+        return this.withMount(mount, async () => {
+            await this.ensureSynced(mount, relativePath);
+            const entry = store.treeGet(mount.treeStateId, relativePath);
+            if (!entry)
+                return { error: `File not found: ${mountPrefixedPath}` };
+            const blob = store.getBlob(entry.blobHash);
+            if (!blob)
+                return { error: `Blob not found for: ${mountPrefixedPath}` };
+            return { data: blob };
+        });
     }
     /**
      * Read a file's raw bytes straight from the mount's filesystem, bypassing
@@ -1129,6 +1358,17 @@ export class WorkspaceModule {
         }
         return { mount, relativePath };
     }
+    /**
+     * Whether the module takes work: stop hasn't finished. Work admitted while
+     * stop drains still runs; once stop has saved the pins and watermarks,
+     * nothing more changes them, so it takes nothing until it starts again. A
+     * call before start is taken, as it always was (a generated file's read
+     * needs no store at all): in the host's order, start runs first, and
+     * initStore applies the saved pins.
+     */
+    running() {
+        return !this.stopped;
+    }
     getStore() {
         if (!this.store)
             throw new Error('WorkspaceModule: store not initialized. Call initStore() first.');
@@ -1421,96 +1661,122 @@ export class WorkspaceModule {
         }
     }
     /**
-     * Persist a single write/edit/delete to disk when the mount opts in via
-     * `autoMaterialize`. Required for cross-agent pipelines — another agent's
-     * chokidar watcher on the same directory only sees real filesystem events.
-     * The local watcher's `suppress()` absorbs the echo so we don't self-wake.
+     * 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
+     * tombstone for a deletion), and push it to disk when the mount opts in via
+     * `autoMaterialize` — required for cross-agent pipelines, since another
+     * agent's watcher on the same directory only sees real filesystem events.
+     * 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 an error string on failure so callers can surface it in the tool
-     * result. The autoMaterialize contract is specifically "disk is the source
-     * of truth for downstream agents", so a silent disk-write failure with a
-     * Chronicle commit would defeat the whole purpose. No-op cases (flag off,
-     * read-only mount) return null (success).
+     * 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).
      */
-    async autoMaterialize(mount, relativePath, op, content) {
-        if (!mount.config.autoMaterialize)
-            return null;
-        if (mount.config.mode === 'read-only')
-            return null;
-        const absolutePath = join(mount.config.path, relativePath);
-        const watcher = this.watchers.get(mount.config.name);
-        watcher?.suppress(relativePath);
-        try {
-            if (op === 'write' && content) {
-                await mkdir(dirname(absolutePath), { recursive: true });
-                await writeFile(absolutePath, content);
-                mount.materializedHashes.set(relativePath, hashContent(content));
-            }
-            else if (op === 'delete') {
-                try {
-                    await unlink(absolutePath);
-                }
-                catch (err) {
-                    if (err.code !== 'ENOENT')
-                        throw err;
-                }
-                mount.materializedHashes.delete(relativePath);
-            }
-            return null;
+    async commitToolChange(mount, relativePath, change, onCommitted) {
+        const store = this.getStore();
+        const intents = this.intents.get(mount.config.name);
+        // The mutation's precondition, enforced here, synchronously with the
+        // commit: whatever settleBeforeMutation's pass could or couldn't settle.
+        settleAdoptionBeforeMutation(store, this.agreementOrThrow(), { name: mount.config.name, treeStateId: mount.treeStateId }, relativePath);
+        const known = this.agreementOrThrow().get(mount.config.name, relativePath) !== undefined;
+        if (change.kind === 'set') {
+            store.treeSet(mount.treeStateId, relativePath, { blobHash: change.blobHash, size: change.size, mode: change.mode ?? 0o644 });
+            // A later intent update or disk push can throw; the tree entry is
+            // already set, on the branch current now. If the active branch changes
+            // during the push, that branch's tree has the file and the new one may
+            // not.
+            onCommitted?.();
+            intents.update(relativePath, (cur) => {
+                const next = { ...cur };
+                delete next.tombstone;
+                // Disk has never agreed with this path: a missing disk copy is a draft
+                // not yet materialized, not a deletion.
+                if (!known)
+                    next.origin = 'store';
+                return next;
+            });
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            this.ctx?.pushEvent({
-                type: 'workspace:materialize-failed',
-                mount: mount.config.name,
-                path: relativePath,
-                op,
-                error: msg,
+        else {
+            store.treeRemove(mount.treeStateId, relativePath);
+            intents.update(relativePath, (cur) => {
+                const next = { ...cur, tombstone: { hash: change.previousHash } };
+                delete next.origin;
+                return next;
             });
-            return msg;
         }
+        if (!mount.config.autoMaterialize || mount.config.mode === 'read-only')
+            return 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;
+        this.ctx?.pushEvent({
+            type: 'workspace:materialize-failed',
+            mount: mount.config.name,
+            path: relativePath,
+            op: change.kind === 'set' ? 'write' : 'delete',
+            error: refused.reason,
+        });
+        return refused.reason;
     }
     // ==========================================================================
     // Lazy Sync
     // ==========================================================================
     /**
-     * Ensure a file is synced from filesystem if not yet in tree (lazy sync).
+     * Before a tool reads or changes a path's workspace entry, a pending intent
+     * on that path is settled by a pass over it, so the tool works from what
+     * 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.
+     */
+    async settleBeforeMutation(mount, relativePath) {
+        if (this.agreementOrThrow().get(mount.config.name, relativePath)?.kind !== 'pending')
+            return;
+        await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] });
+    }
+    /**
+     * 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.
      */
     async ensureSynced(mount, relativePath) {
         const store = this.getStore();
-        const existing = store.treeGet(mount.treeStateId, relativePath);
-        if (existing)
-            return; // Already in tree
-        // Try to read from filesystem
-        const absolutePath = join(mount.config.path, relativePath);
-        try {
-            const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
-            const fileStat = await stat(absolutePath);
-            if (!fileStat.isFile() || fileStat.size > maxSize)
-                return;
-            const buffer = await readFile(absolutePath);
-            // Binaries are never synced into the tree (mirrors syncFromFs): the old
-            // utf-8 round-trip here silently replaced non-UTF-8 bytes with U+FFFD,
-            // permanently mangling images in the blob store. Binary reads are served
-            // straight from disk (readImageFromFilesystem / read_image fallback).
-            if (isBinary(buffer))
-                return;
-            const content = buffer.toString('utf-8');
-            const blobHash = store.storeBlob(Buffer.from(content, 'utf-8'), 'text/plain');
-            store.treeSet(mount.treeStateId, relativePath, {
-                blobHash,
-                size: buffer.length,
-                mode: 0o644,
-            });
-        }
-        catch {
-            // File doesn't exist on disk — that's fine
+        if (store.treeGet(mount.treeStateId, relativePath))
+            return undefined;
+        const pass = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] });
+        return pass.reports.get(relativePath);
+    }
+    /** Why the workspace holds no entry at a path, when disk explains it. */
+    notInWorkspace(path, report) {
+        switch (report?.state) {
+            case 'workspace-deleted':
+                return `${path} was deleted in the workspace; disk still has a copy. Sync this path to restore it.`;
+            case 'not-in-branch':
+                return `${path} is not in this branch's workspace; disk has a copy. Sync this path to add it.`;
+            case 'disk-only':
+                return `${path} is on disk but not stored in the workspace (binary or over the size limit)` +
+                    (report.mimeType?.startsWith('image/') ? '; read it with read_image.' : '.');
+            case 'conflict':
+                return `${path} is in conflict: the workspace deleted it and disk changed it since. ` +
+                    'Sync this path to take the disk version.';
+            case 'unverified':
+                return `${path} is not in the workspace, and disk could not be checked (${report.note ?? 'not observed'}).`;
+            default:
+                return `File not found: ${path}`;
         }
     }
     // ==========================================================================
     // Tool Handlers
     // ==========================================================================
-    async handleRead(input) {
+    async handleRead(input, generatedContent) {
         const characterPaging = input.offsetChars !== undefined || input.limitChars !== undefined;
         const offsetChars = input.offsetChars ?? 0;
         const limitChars = input.limitChars ?? 2000;
@@ -1524,18 +1790,24 @@ export class WorkspaceModule {
                 return { success: false, isError: true, error: 'offsetChars must be a non-negative safe integer and limitChars a positive safe integer.' };
             }
         }
-        const { mount, relativePath } = this.parsePath(input.path);
-        const store = this.getStore();
-        await this.ensureSynced(mount, relativePath);
-        const entry = store.treeGet(mount.treeStateId, relativePath);
-        if (!entry) {
-            return { success: false, error: `File not found: ${input.path}`, isError: true };
-        }
-        const blob = store.getBlob(entry.blobHash);
-        if (!blob) {
-            return { success: false, error: `Blob not found for: ${input.path}`, isError: true };
+        let content = generatedContent;
+        if (content === undefined) {
+            const { mount, relativePath } = this.parsePath(input.path);
+            const store = this.getStore();
+            const found = await this.withMount(mount, async () => {
+                const report = await this.ensureSynced(mount, relativePath);
+                const entry = store.treeGet(mount.treeStateId, relativePath);
+                if (!entry)
+                    return { error: this.notInWorkspace(input.path, report) };
+                const blob = store.getBlob(entry.blobHash);
+                if (!blob)
+                    return { error: `Blob not found for: ${input.path}` };
+                return { text: blob.toString('utf-8') };
+            });
+            if ('error' in found)
+                return { success: false, error: found.error, isError: true };
+            content = found.text;
         }
-        const content = blob.toString('utf-8');
         if (characterPaging) {
             const start = Math.min(offsetChars, content.length);
             const splitsPair = (at) => at > 0 && at < content.length
@@ -1670,13 +1942,11 @@ 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 blobHash = store.storeBlob(buffer, 'text/plain');
-        store.treeSet(mount.treeStateId, relativePath, {
-            blobHash,
-            size: Buffer.byteLength(input.content),
-            mode: 0o644,
+        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 });
         });
-        const materializeError = await this.autoMaterialize(mount, relativePath, 'write', buffer);
         if (materializeError) {
             return {
                 success: false,
@@ -1699,55 +1969,58 @@ export class WorkspaceModule {
             return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
         }
         const store = this.getStore();
-        await this.ensureSynced(mount, relativePath);
-        const entry = store.treeGet(mount.treeStateId, relativePath);
-        if (!entry) {
-            return { success: false, error: `File not found: ${input.path}`, 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;
-            if (count === 0) {
-                return { success: false, error: `String not found in ${input.path}`, isError: true };
+        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;
+                if (count === 0) {
+                    return { success: false, error: `String not found in ${input.path}`, isError: true };
+                }
+                if (count > 1) {
+                    return {
+                        success: false,
+                        error: `String found ${count} times in ${input.path}. Use replaceAll: true or provide more context.`,
+                        isError: true,
+                    };
+                }
             }
-            if (count > 1) {
+            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) {
                 return {
                     success: false,
-                    error: `String found ${count} times in ${input.path}. Use replaceAll: true or provide more context.`,
+                    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,
                 };
             }
-        }
-        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');
-        store.treeSet(mount.treeStateId, relativePath, {
-            blobHash: newBlobHash,
-            size: Buffer.byteLength(content),
-            mode: entry.mode,
-        });
-        const materializeError = await this.autoMaterialize(mount, relativePath, 'write', newBuffer);
-        if (materializeError) {
             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,
+                },
             };
-        }
-        return {
-            success: true,
-            data: {
-                path: input.path,
-                size: Buffer.byteLength(content),
-            },
-        };
+        });
     }
     async handleDelete(input) {
         const { mount, relativePath } = this.parsePath(input.path);
@@ -1755,20 +2028,24 @@ export class WorkspaceModule {
             return { success: false, error: `Mount "${mount.config.name}" is read-only`, isError: true };
         }
         const store = this.getStore();
-        const entry = store.treeGet(mount.treeStateId, relativePath);
-        if (!entry) {
-            return { success: false, error: `File not found: ${input.path}`, isError: true };
-        }
-        store.treeRemove(mount.treeStateId, relativePath);
-        const materializeError = await this.autoMaterialize(mount, relativePath, 'delete');
-        if (materializeError) {
-            return {
-                success: false,
-                error: `Removed from Chronicle but failed to unlink "${input.path}" from disk: ${materializeError}. Downstream agents will still see the stale file until manual cleanup.`,
-                isError: true,
-            };
-        }
-        return { success: true, data: { path: input.path, deleted: true } };
+        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,
+                };
+            }
+            return { success: true, data: { path: input.path, deleted: true } };
+        });
     }
     async handleLs(input) {
         const store = this.getStore();
@@ -1782,74 +2059,67 @@ export class WorkspaceModule {
             return { success: true, data: { mounts } };
         }
         const { mount, relativePath } = this.parsePath(input.path);
-        // Ensure initial sync — always sync on first access regardless of watch mode,
-        // so that ls/glob/grep see filesystem contents even for unwatched mounts
-        if (!mount.initialSyncDone) {
-            await syncFromFs(store, mount);
-            mount.initialSyncDone = true;
-        }
-        const prefix = relativePath ? relativePath + '/' : '';
-        const entries = store.treeList(mount.treeStateId, prefix || undefined);
-        if (input.recursive) {
+        const recursive = input.recursive === true;
+        // Every listing checks the paths it shows against disk first, under the
+        // three-way rule, whatever the mount's watch mode.
+        return this.withMount(mount, async () => {
+            const pass = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive });
+            const reports = [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path));
+            const incomplete = pass.incomplete.length > 0 ? { incomplete: pass.incomplete } : {};
+            if (recursive) {
+                return {
+                    success: true,
+                    data: {
+                        path: input.path,
+                        entries: reports.map((r) => ({ path: r.path, ...stateView(r) })),
+                        count: reports.length,
+                        ...incomplete,
+                    },
+                };
+            }
+            // Non-recursive: the scope's files, and the directories beneath it that
+            // disk or the workspace has.
+            const prefix = relativePath ? relativePath + '/' : '';
+            const dirNames = new Set(pass.dirs.map((d) => d.slice(prefix.length)));
+            for (const entry of store.treeList(mount.treeStateId, prefix || undefined)) {
+                const slash = entry.path.indexOf('/', prefix.length);
+                if (slash >= 0)
+                    dirNames.add(entry.path.slice(prefix.length, slash));
+            }
+            const children = [
+                ...[...dirNames].sort().map((name) => ({ name, type: 'directory' })),
+                ...reports.map((r) => ({ name: r.path.slice(prefix.length), type: 'file', ...stateView(r) })),
+            ];
             return {
                 success: true,
                 data: {
                     path: input.path,
-                    entries: entries.map(e => ({
-                        path: e.path,
-                        size: e.size,
-                    })),
-                    count: entries.length,
+                    entries: children,
+                    count: children.length,
+                    ...incomplete,
                 },
             };
-        }
-        // Non-recursive: deduplicate to show immediate children only
-        const seen = new Set();
-        const children = [];
-        for (const entry of entries) {
-            const rest = entry.path.slice(prefix.length);
-            const slashIdx = rest.indexOf('/');
-            if (slashIdx >= 0) {
-                const dirName = rest.slice(0, slashIdx);
-                if (!seen.has(dirName)) {
-                    seen.add(dirName);
-                    children.push({ name: dirName, type: 'directory' });
-                }
-            }
-            else {
-                children.push({ name: rest, type: 'file' });
-            }
-        }
-        return {
-            success: true,
-            data: {
-                path: input.path,
-                entries: children,
-                count: children.length,
-            },
-        };
+        });
     }
     async handleGlob(input) {
-        const store = this.getStore();
         const regex = globToRegex(input.pattern);
         const matches = [];
+        const incomplete = [];
         // Search across mounts
         const mountsToSearch = input.path
             ? [this.parsePath(input.path)]
             : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
         for (const { mount, relativePath } of mountsToSearch) {
-            if (!mount.initialSyncDone) {
-                await syncFromFs(store, mount);
-                mount.initialSyncDone = true;
-            }
-            const prefix = relativePath ? relativePath + '/' : undefined;
-            const entries = store.treeList(mount.treeStateId, prefix);
-            for (const entry of entries) {
-                const testPath = relativePath ? entry.path.slice(relativePath.length + 1) : entry.path;
+            const pass = await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: relativePath, 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)) {
-                    matches.push(`${mount.config.name}/${entry.path}`);
+                    matches.push({ path: `${mount.config.name}/${report.path}`, ...stateView(report) });
                 }
             }
+            for (const region of pass.incomplete) {
+                incomplete.push({ path: `${mount.config.name}/${region.path}`, reason: region.reason });
+            }
         }
         return {
             success: true,
@@ -1857,6 +2127,7 @@ export class WorkspaceModule {
                 pattern: input.pattern,
                 matches,
                 count: matches.length,
+                ...(incomplete.length > 0 ? { incomplete } : {}),
             },
         };
     }
@@ -1876,56 +2147,107 @@ export class WorkspaceModule {
             ? [this.parsePath(input.path)]
             : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
         const results = [];
-        for (const { mount, relativePath } of mountsToSearch) {
-            if (!mount.initialSyncDone) {
-                await syncFromFs(store, mount);
-                mount.initialSyncDone = true;
-            }
-            // If `path` points at a single FILE, grep just that file. Otherwise treat
-            // `path` as a directory prefix (the original behaviour). Previously a file
-            // path produced an empty prefix like "notes.md/" and matched nothing, so
-            // grepping a specific file silently returned zero results.
-            let entries;
-            const fileNode = relativePath
-                ? store.treeGet(mount.treeStateId, relativePath)
-                : null;
-            if (fileNode && fileNode.blobHash) {
-                entries = [{ path: relativePath, blobHash: fileNode.blobHash }];
-            }
-            else {
-                const prefix = relativePath ? relativePath + '/' : undefined;
-                entries = store.treeList(mount.treeStateId, prefix);
-            }
-            for (const entry of entries) {
-                if (fileGlob && !fileGlob.test(entry.path))
-                    continue;
-                const blob = store.getBlob(entry.blobHash);
-                if (!blob)
-                    continue;
-                const content = blob.toString('utf-8');
-                const lines = content.split('\n');
-                const fileMatches = [];
-                for (let i = 0; i < lines.length; i++) {
-                    if (regex.test(lines[i])) {
-                        const match = {
-                            line: i + 1,
-                            text: lines[i],
-                        };
-                        if (contextBefore > 0 || contextAfter > 0) {
-                            const start = Math.max(0, i - contextBefore);
-                            const end = Math.min(lines.length, i + contextAfter + 1);
-                            match.context = lines.slice(start, end);
-                        }
-                        fileMatches.push(match);
+        const skipped = [];
+        const incomplete = [];
+        const search = (content) => {
+            const lines = content.split('\n');
+            const found = [];
+            for (let i = 0; i < lines.length; i++) {
+                if (regex.test(lines[i])) {
+                    const match = { line: i + 1, text: lines[i] };
+                    if (contextBefore > 0 || contextAfter > 0) {
+                        const start = Math.max(0, i - contextBefore);
+                        const end = Math.min(lines.length, i + contextAfter + 1);
+                        match.context = lines.slice(start, end);
                     }
+                    found.push(match);
+                }
+            }
+            return found;
+        };
+        for (const { mount, relativePath } of mountsToSearch) {
+            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/"
+                // and silently matched nothing.)
+                const fileScope = relativePath !== '' && (store.treeGet(mount.treeStateId, relativePath) !== null ||
+                    await lstat(join(mount.config.path, relativePath)).then((s) => !s.isDirectory(), () => false));
+                // What follows reads the tree and branch intent to go with the pass's
+                // reports, synchronously. They must be the branch the pass decided
+                // on: one selected in between would label its content with the other
+                // branch's states. So a pass whose branch is no longer selected runs
+                // again, and a branch that keeps changing leaves the scope unsearched.
+                let pass = null;
+                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 });
+                    if (next.branchId === undefined || next.branchId === store.currentBranch().id)
+                        pass = next;
                 }
-                if (fileMatches.length > 0) {
-                    results.push({
-                        file: `${mount.config.name}/${entry.path}`,
-                        matches: fileMatches,
+                if (pass === null) {
+                    incomplete.push({
+                        path: `${mount.config.name}/${relativePath}`,
+                        reason: 'the selected branch kept changing while grep ran; nothing here was searched — grep again',
                     });
+                    return;
                 }
-            }
+                for (const region of pass.incomplete) {
+                    incomplete.push({ path: `${mount.config.name}/${region.path}`, reason: region.reason });
+                }
+                const intents = this.intents.get(mount.config.name);
+                for (const report of [...pass.reports.values()].sort((a, b) => a.path.localeCompare(b.path))) {
+                    if (fileGlob && !fileGlob.test(report.path))
+                        continue;
+                    const file = `${mount.config.name}/${report.path}`;
+                    if (report.state === 'disk-only') {
+                        skipped.push({
+                            file,
+                            reason: 'disk-only: binary or over the size limit, never stored',
+                            ...(report.size !== undefined ? { size: report.size } : {}),
+                            ...(report.mimeType ? { mimeType: report.mimeType } : {}),
+                        });
+                        continue;
+                    }
+                    // The workspace's version, labelled with the path's state.
+                    const entry = store.treeGet(mount.treeStateId, report.path);
+                    const blob = entry ? store.getBlob(entry.blobHash) : null;
+                    if (blob) {
+                        const found = search(blob.toString('utf-8'));
+                        if (found.length > 0)
+                            results.push({ file, state: report.state, version: 'workspace', matches: found });
+                    }
+                    else if (entry) {
+                        skipped.push({ file, reason: 'the workspace copy is missing from the store, so it was not searched' });
+                    }
+                    if (report.state !== 'conflict')
+                        continue;
+                    // A conflict's disk side. The version recorded with the conflict is
+                    // disk's only while disk still holds it; once disk has changed
+                    // since, it is labelled as recorded, and a file disk holds now
+                    // (never stored) is listed as not searched. A binary or oversize
+                    // disk version was never stored either.
+                    const disk = intents.get(report.path)?.conflict?.disk;
+                    const changed = report.conflict?.diskChangedSinceRecorded === true;
+                    const diskBlob = disk?.stored ? store.getBlob(disk.stored) : null;
+                    if (diskBlob) {
+                        const found = search(diskBlob.toString('utf-8'));
+                        if (found.length > 0)
+                            results.push({ file, state: report.state, version: changed ? 'recorded-disk' : 'conflicting-disk', matches: found });
+                    }
+                    if (disk?.stored && !diskBlob) {
+                        skipped.push({ file, reason: 'conflict: the disk version recorded with the conflict is missing from the store, so it was not searched' });
+                    }
+                    if (changed) {
+                        if (report.diskNow === 'file') {
+                            skipped.push({ file, reason: 'conflict: disk changed since the conflict was recorded; grep searches stored text, so the file disk holds now was not searched' });
+                        }
+                    }
+                    else if (disk && !disk.stored) {
+                        skipped.push({ file, reason: 'conflict: the disk version is binary or over the size limit, never stored', size: disk.size });
+                    }
+                }
+            });
         }
         return {
             success: true,
@@ -1933,18 +2255,32 @@ export class WorkspaceModule {
                 pattern: input.pattern,
                 results,
                 totalMatches: results.reduce((sum, r) => sum + r.matches.length, 0),
+                ...(skipped.length > 0 ? { skipped } : {}),
+                ...(incomplete.length > 0 ? { incomplete } : {}),
             },
         };
     }
-    async handleStatus(_input) {
+    async handleStatus(input) {
         const store = this.getStore();
         const status = {};
+        if (input.mount !== undefined && !this.mounts.has(input.mount)) {
+            return { success: false, error: `Unknown mount: ${input.mount}`, isError: true };
+        }
         for (const [name, mount] of this.mounts) {
+            if (input.mount !== undefined && name !== input.mount)
+                continue;
             const entries = store.treeList(mount.treeStateId);
             const currentSeq = store.currentSequence();
-            const changes = mount.lastMaterializedSeq > 0
-                ? store.treeDiff(mount.treeStateId, mount.lastMaterializedSeq, currentSeq)
-                : [];
+            const intents = this.intents.get(name).list();
+            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.
+            const deletionPaths = intents.filter(([, bi]) => bi.tombstone).map(([p]) => p);
+            // Pending is what disk owes by the evidence: every entry it doesn't
+            // show on disk (a refused or failed push stays owed), conflicts and
+            // deletions. An entry from before the evidence isn't counted until a
+            // listing or a materialize checks it: unchecked isn't unpushed.
+            const pending = new Set([...conflictPaths, ...deletionPaths, ...this.entriesByEvidence(mount).owed]);
             const currentBranch = store.currentBranch();
             status[name] = {
                 path: mount.config.path,
@@ -1953,20 +2289,93 @@ export class WorkspaceModule {
                 fileCount: entries.length,
                 lastMaterializedSeq: mount.lastMaterializedSeq,
                 currentSeq,
-                pendingChanges: changes.length,
+                pendingChanges: pending.size,
+                conflicts: conflictPaths.length,
+                pendingWorkspaceDeletions: deletionPaths.length,
                 initialSyncDone: mount.initialSyncDone,
                 currentBranch: currentBranch.name,
                 lastMaterializedBranch: mount.lastMaterializedBranchId,
                 canMaterialize: this.mountMaterializeBlockReason(store, mount) === null,
+                ...(mount.lastAgentActionScan ? { lastAgentActionScan: mount.lastAgentActionScan } : {}),
             };
         }
         return { success: true, data: status };
     }
+    /**
+     * What a materialize of `mount` should consider: a named file, or every
+     * tracked path beneath a named directory; otherwise what the evidence says
+     * disk still owes, the entries never checked against disk, recorded
+     * conflicts, and workspace deletions still on disk (applied with
+     * `applyDeletions`, listed without it). The watermark plays no part: it is
+     * lost at an unclean restart, and an entry the evidence shows on disk has
+     * nothing to push. If disk changed since, a sync adopts that; a bare
+     * materialize, forced or not, never reverts it (naming the path with force
+     * does). `inPlace` says whether any tree entry was left out for that reason.
+     */
+    materializeSelection(mount, explicitPath) {
+        const store = this.getStore();
+        const intents = new Map(this.intents.get(mount.config.name).list(explicitPath));
+        const selected = new Set();
+        if (explicitPath !== '') {
+            if (store.treeGet(mount.treeStateId, explicitPath))
+                selected.add(explicitPath);
+            for (const e of store.treeList(mount.treeStateId, explicitPath + '/'))
+                selected.add(e.path);
+            for (const [p, bi] of intents)
+                if (bi.tombstone || bi.conflict)
+                    selected.add(p);
+            return { paths: [...selected], inPlace: false };
+        }
+        const { owed, unchecked, agreed } = this.entriesByEvidence(mount);
+        for (const path of [...owed, ...unchecked])
+            selected.add(path);
+        for (const [p, bi] of intents)
+            if (bi.conflict || bi.tombstone)
+                selected.add(p);
+        return { paths: [...selected], inPlace: agreed > 0 };
+    }
+    /**
+     * 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).
+     * `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
+     * counts the owed as pending; a materialize without a path takes up the
+     * owed and the unchecked.
+     */
+    entriesByEvidence(mount) {
+        const store = this.getStore();
+        const agreement = this.agreementOrThrow();
+        const name = mount.config.name;
+        const intents = this.intents.get(name);
+        const owed = [];
+        const unchecked = [];
+        let agreed = 0;
+        for (const e of store.treeList(mount.treeStateId)) {
+            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);
+            else
+                agreed++;
+        }
+        return { owed, unchecked, agreed };
+    }
     async handleMaterialize(input) {
         const store = this.getStore();
         const allWritten = [];
+        const allDeleted = [];
+        const pendingDeletions = [];
+        let explicit = null;
+        if (input.path)
+            explicit = this.parsePath(input.path);
         let mountsToMaterialize;
-        if (input.mount) {
+        if (explicit) {
+            mountsToMaterialize = [{ name: explicit.mount.config.name, mount: explicit.mount }];
+        }
+        else if (input.mount) {
             const m = this.mounts.get(input.mount);
             if (!m) {
                 return { success: false, error: `Unknown mount: ${input.mount}`, isError: true };
@@ -1981,59 +2390,94 @@ export class WorkspaceModule {
         // Branch guard, scoped to the mounts actually being materialized: a
         // linear continuation (current branch descends from the pinned branch at
         // or after the pinned seq) passes; genuine divergence refuses unless
-        // force. One mount's stale pin must never block another mount.
+        // force. One mount's stale pin must never block another mount. It is
+        // judged inside the mount's turn, on the same branch the selection is
+        // made on: a materialize queued behind a pass would otherwise select on
+        // whatever branch is current when its turn comes, unguarded. The push
+        // then writes nothing if the branch changes after that.
         const blocked = [];
+        const guarded = [];
+        let proceeded = 0;
         for (const { name, mount } of mountsToMaterialize) {
-            const reason = this.mountMaterializeBlockReason(store, mount);
-            if (!reason)
+            if (mount.config.mode === 'read-only') {
+                // Only a mount the caller named gets here read-only (a bare
+                // materialize takes the read-write ones): say why nothing was written.
+                blocked.push({ mount: name, reason: 'a read-only mount: materialize writes nothing to it' });
                 continue;
-            if (input.force) {
-                // Disk reflects another line of history, so an incremental diff from
-                // the pinned seq is meaningless — reset tracking and re-materialize
-                // the full tree, exactly like materializeMount() after a deliberate
-                // branch switch.
-                mount.lastMaterializedSeq = 0;
-                mount.lastMaterializedBranchId = null;
             }
-            else {
-                blocked.push({ mount: name, reason });
+            const turn = await this.withMount(mount, async () => {
+                const branchId = store.currentBranch().id;
+                const reason = this.mountMaterializeBlockReason(store, mount);
+                // Force passes a divergence. The selection follows the evidence, which
+                // is per path and kept across branches, so nothing needs resetting:
+                // the push re-pins to this branch.
+                if (reason && !input.force)
+                    return { blocked: reason };
+                const { paths, inPlace } = this.materializeSelection(mount, explicit?.relativePath ?? '');
+                return {
+                    inPlace,
+                    pushed: await this.pushUnlocked(mount, paths, {
+                        force: input.force, named: explicit !== null, applyDeletions: input.applyDeletions, branchId,
+                    }),
+                };
+            });
+            if ('blocked' in turn) {
+                blocked.push({ mount: name, reason: turn.blocked });
+                guarded.push(name);
+                continue;
             }
-        }
-        mountsToMaterialize = mountsToMaterialize.filter(({ name }) => !blocked.some((b) => b.mount === name));
-        if (mountsToMaterialize.length === 0 && blocked.length > 0) {
-            return {
-                success: false,
-                error: `Cannot materialize: ${blocked.map((b) => `[${b.mount}] ${b.reason}`).join('; ')}`,
-                isError: true,
-            };
-        }
-        for (const { name, mount } of mountsToMaterialize) {
-            let paths;
-            if (input.path) {
-                const { relativePath } = this.parsePath(input.path);
-                paths = relativePath ? [relativePath] : undefined;
-            }
-            // Suppress watcher for paths we're about to write
-            const watcher = this.watchers.get(name);
-            const written = await materializeToFs(store, mount, paths);
-            for (const p of written) {
-                watcher?.suppress(p);
+            proceeded++;
+            const pushed = turn.pushed;
+            for (const p of pushed.written)
                 allWritten.push({ mount: name, path: p });
-            }
+            for (const p of pushed.deleted)
+                allDeleted.push({ mount: name, path: p });
+            for (const p of pushed.pendingDeletions)
+                pendingDeletions.push({ mount: name, path: p });
+            // 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}` });
+            }
+            // 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
+            // while it wrote. A push that planned nothing (the selected branch
+            // changed after its paths were chosen) left disk as it was, so it
+            // leaves both as they were too.
+            if (pushed.branchId === undefined || pushed.sequence === undefined)
+                continue;
+            mount.lastMaterializedSeq = pushed.sequence;
             // Track which branch we materialized on. Re-pin on a clean empty
             // materialize too (previously-pinned mount, nothing pending): disk
             // already reflects the current branch's tree, and leaving the old pin
             // would keep force required forever after a cross-branch materialize
-            // that happened to write nothing.
-            if (written.length > 0 || mount.lastMaterializedBranchId !== null) {
-                mount.lastMaterializedBranchId = store.currentBranch().id;
+            // that happened to write nothing. A first materialize pins once files
+            // of this branch are in place, whether it found them on disk or the
+            // evidence shows them there: disk holds this branch's tree.
+            if (pushed.written.length > 0 || pushed.unchanged.length > 0 || turn.inPlace || mount.lastMaterializedBranchId !== null) {
+                mount.lastMaterializedBranchId = pushed.branchId;
             }
         }
+        if (proceeded === 0 && guarded.length > 0 && guarded.length === mountsToMaterialize.length) {
+            return {
+                success: false,
+                error: `Cannot materialize: ${blocked.map((b) => `[${b.mount}] ${b.reason}`).join('; ')}`,
+                isError: true,
+            };
+        }
         return {
             success: true,
             data: {
                 materialized: allWritten,
                 count: allWritten.length,
+                ...(allDeleted.length > 0 ? { deleted: allDeleted } : {}),
+                ...(pendingDeletions.length > 0
+                    ? {
+                        workspaceDeletionsLeftOnDisk: pendingDeletions,
+                        note: 'Files deleted in the workspace were left on disk; materialize with applyDeletions to remove them.',
+                    }
+                    : {}),
                 ...(blocked.length > 0 ? { skipped: blocked } : {}),
             },
         };
@@ -2044,6 +2488,8 @@ export class WorkspaceModule {
      * Resets branch tracking to allow cross-branch materialization.
      */
     async materializeMount(mountName) {
+        if (!this.running())
+            return [];
         const store = this.getStore();
         const mount = this.mounts.get(mountName);
         if (!mount || mount.config.mode === 'read-only')
@@ -2051,53 +2497,114 @@ export class WorkspaceModule {
         // Reset tracking — we're deliberately materializing on the new branch
         mount.lastMaterializedBranchId = null;
         mount.lastMaterializedSeq = 0;
-        const watcher = this.watchers.get(mountName);
-        const written = await materializeToFs(store, mount);
-        for (const p of written) {
-            watcher?.suppress(p);
-        }
-        if (written.length > 0) {
-            mount.lastMaterializedBranchId = store.currentBranch().id;
+        // force: this path only runs after a deliberate undo/redo/branch switch
+        // on the framework's own _config mount — restoring disk to the branch
+        // state IS the operator intent, so the freshness guard yields. named:
+        // the whole tree is that deliberate scope, entries without evidence too.
+        const pushed = await this.withMount(mount, () => {
+            const branchId = store.currentBranch().id;
+            return this.pushUnlocked(mount, store.treeList(mount.treeStateId).map((e) => e.path), { force: true, named: true, branchId });
+        });
+        // A push that planned nothing leaves the reset tracking as it is.
+        if (pushed.branchId !== undefined && pushed.sequence !== undefined) {
+            mount.lastMaterializedSeq = pushed.sequence;
+            if (pushed.written.length > 0 || pushed.unchanged.length > 0) {
+                mount.lastMaterializedBranchId = pushed.branchId;
+            }
         }
-        return written;
+        return pushed.written;
     }
     async handleSync(input) {
         const store = this.getStore();
+        // A path sync adopts on the branch it was asked on, read before any await.
+        const askedOn = store.currentBranch().id;
         const allResults = [];
         const allSkipped = [];
-        let mountsToSync;
-        if (input.mount) {
+        const allIncomplete = [];
+        const rootsAccepted = [];
+        if (input.acceptRoot && input.path) {
+            return { success: false, error: 'acceptRoot takes a whole mount\'s root: give mount, or nothing, not path', isError: true };
+        }
+        // A path names its own mount; otherwise the given mount, or every mount.
+        let targets;
+        if (input.path) {
+            const { mount, relativePath } = this.parsePath(input.path);
+            targets = [{ name: mount.config.name, mount, relativePath }];
+        }
+        else if (input.mount) {
             const m = this.mounts.get(input.mount);
             if (!m) {
                 return { success: false, error: `Unknown mount: ${input.mount}`, isError: true };
             }
-            mountsToSync = [{ name: input.mount, mount: m }];
+            targets = [{ name: input.mount, mount: m, relativePath: '' }];
         }
         else {
-            mountsToSync = [...this.mounts.entries()].map(([name, mount]) => ({ name, mount }));
-        }
-        for (const { name, mount } of mountsToSync) {
-            let paths;
-            if (input.path) {
-                const { relativePath } = this.parsePath(input.path);
-                // Empty relativePath means mount root — sync entire mount, not a single path
-                paths = relativePath ? [relativePath] : undefined;
-            }
-            const result = await syncFromFs(store, mount, paths);
-            mount.initialSyncDone = true;
-            if (result.synced.length > 0 || result.conflicts.length > 0) {
+            targets = [...this.mounts.entries()].map(([name, mount]) => ({ name, mount, relativePath: '' }));
+        }
+        for (const { name, mount, relativePath } of targets) {
+            const pass = await this.withMount(mount, async () => {
+                if (input.acceptRoot && await this.acceptRootUnlocked(mount))
+                    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 });
+                }
+                // An explicit path: the workspace takes disk's state there.
+                const prefix = relativePath + '/';
+                const isDir = await lstat(join(mount.config.path, relativePath)).then((s) => s.isDirectory(), () => false) ||
+                    store.treeList(mount.treeStateId, prefix).length > 0 ||
+                    this.agreementOrThrow().paths(name, relativePath).some(([p]) => p.startsWith(prefix)) ||
+                    this.intents.get(name).list(relativePath).some(([p]) => p.startsWith(prefix));
+                const opts = { rehash: true, adopt: () => true, branchId: askedOn };
+                if (!isDir)
+                    return this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
+                const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, opts);
+                // 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
+                // too, after what lies beneath, so a file never sits over entries it
+                // replaced.
+                const onDisk = await lstat(join(mount.config.path, relativePath)).catch(() => null);
+                const atPath = (onDisk !== null && !onDisk.isDirectory())
+                    || store.treeGet(mount.treeStateId, relativePath) !== null
+                    || this.agreementOrThrow().get(name, relativePath) !== undefined
+                    || this.intents.get(name).get(relativePath) !== null;
+                if (!atPath)
+                    return beneath;
+                const itself = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
+                return {
+                    ops: [...beneath.ops, ...itself.ops],
+                    discarded: [...beneath.discarded, ...itself.discarded],
+                    newConflicts: [...beneath.newConflicts, ...itself.newConflicts],
+                    reports: new Map([...beneath.reports, ...itself.reports]),
+                    incomplete: [...beneath.incomplete, ...itself.incomplete],
+                    dirs: beneath.dirs,
+                    branchId: itself.branchId ?? beneath.branchId,
+                };
+            });
+            const conflicts = [...pass.reports.values()]
+                .filter((r) => r.state === 'conflict')
+                .map((r) => ({ path: r.path, kind: r.conflict?.kind ?? 'both-changed', diskCopy: r.conflict?.diskCopy ?? 'referenced' }));
+            if (pass.ops.length > 0 || conflicts.length > 0 || pass.discarded.length > 0) {
                 allResults.push({
                     mount: name,
-                    synced: result.synced.map(s => s.path),
-                    conflicts: result.conflicts,
+                    synced: pass.ops.map((o) => o.path),
+                    conflicts,
+                    ...(pass.discarded.length > 0 ? { discarded: pass.discarded } : {}),
                 });
-                this.emitFsEvents(name, result.synced, result.conflicts);
             }
-            // Skips were previously computed and dropped, so "nothing synced" and
-            // "your file was refused" looked identical from the outside. Say which.
-            for (const s of result.skipped) {
-                allSkipped.push({ mount: name, path: s.path, reason: s.reason });
+            // Say why a path wasn't taken in, so "nothing synced" and "your file was
+            // refused" don't look identical from the outside.
+            for (const r of pass.reports.values()) {
+                if (r.state === 'unverified') {
+                    allSkipped.push({ mount: name, path: r.path, reason: `disk could not be checked: ${r.note ?? 'not observed'}` });
+                }
+                else if (r.state === 'disk-only') {
+                    allSkipped.push({ mount: name, path: r.path, reason: 'disk-only: binary or over the size limit, never stored' });
+                }
             }
+            for (const region of pass.incomplete)
+                allIncomplete.push({ mount: name, ...region });
         }
         return {
             success: true,
@@ -2106,80 +2613,208 @@ export class WorkspaceModule {
                 totalSynced: allResults.reduce((sum, r) => sum + r.synced.length, 0),
                 totalConflicts: allResults.reduce((sum, r) => sum + r.conflicts.length, 0),
                 ...(allSkipped.length > 0 ? { skipped: allSkipped } : {}),
+                ...(allIncomplete.length > 0 ? { incomplete: allIncomplete } : {}),
+                ...(rootsAccepted.length > 0 ? { rootsAccepted } : {}),
             },
         };
     }
+    /**
+     * Take the mount's root as it is now (acceptRoot), when it is a directory
+     * other than the one disk last agreed under. Its evidence is set aside:
+     * it described another directory. Returns whether a root was accepted.
+     */
+    async acceptRootUnlocked(mount) {
+        const runtime = await this.runtime(mount);
+        const found = await locateRoot({ ...runtime.view, rootIdentity: undefined }, runtime.rootReal);
+        if ('reason' in found)
+            return false; // still missing: the pass says so
+        const agreement = this.agreementOrThrow();
+        const recorded = agreement.rootIdentity(mount.config.name);
+        if (recorded && sameRootIdentity(recorded, found.identity))
+            return false;
+        if (recorded)
+            agreement.acceptRoot(mount.config.name, found.identity);
+        else
+            agreement.recordRootIdentity(mount.config.name, found.identity);
+        agreement.barrier();
+        return true;
+    }
     // ==========================================================================
     // Internal: Filesystem Change Handling
     // ==========================================================================
     /**
      * Handle filesystem changes detected by watcher (watch: 'always' mode).
      *
-     * The watcher carries the op per path. For created/modified we call
-     * syncFromFs to pull content into the tree; for deleted we strip the tree
-     * entry directly (the file is gone, nothing to read). We emit one event per
-     * op type.
+     * The watcher's ops only choose which paths to look at: each path is
+     * observed again and decided under the three-way rule, so an event that
+     * arrives late or out of order can't delete or revert anything by itself.
      */
     async handleFsChanges(mountName, changes) {
-        const store = this.store;
         const mount = this.mounts.get(mountName);
-        if (!store || !mount)
+        if (!this.store || !this.running() || !mount)
             return;
-        const touchedPaths = changes.filter(c => c.op !== 'deleted').map(c => c.path);
-        const deletedPaths = changes.filter(c => c.op === 'deleted').map(c => c.path);
-        const syncResult = touchedPaths.length > 0
-            ? await syncFromFs(store, mount, touchedPaths)
-            : { synced: [], conflicts: [], skipped: [] };
-        // Strip deleted entries from the tree so downstream consumers see a
-        // coherent state. syncFromFs would also do this if we passed the paths in,
-        // but the op from the watcher is authoritative — skip the access() probe.
-        for (const p of deletedPaths) {
-            const existing = store.treeGet(mount.treeStateId, p);
-            if (existing) {
-                store.treeRemove(mount.treeStateId, p);
-                syncResult.synced.push({ path: p, op: 'deleted' });
-            }
-        }
-        this.emitFsEvents(mountName, syncResult.synced, syncResult.conflicts);
+        const paths = [...new Set(changes.map((c) => c.path))];
+        if (paths.length === 0)
+            return;
+        await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'paths', paths }));
     }
     /**
-     * Group synced paths by op and push one ProcessEvent per non-empty op.
+     * 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.
      */
-    emitFsEvents(mountName, synced, conflicts) {
-        if (!this.ctx || synced.length === 0)
+    async onToolBatchComplete(_agentName) {
+        // Every agent's workspace is the store's current branch, so the agent
+        // that ran the batch doesn't choose what is scanned.
+        const mounts = [...this.mounts.values()].filter((m) => m.config.watch === 'on-agent-action');
+        if (mounts.length === 0 || !this.store || !this.running())
             return;
-        const byOp = new Map();
-        for (const { path, op } of synced) {
-            const list = byOp.get(op) ?? [];
-            list.push(`${mountName}/${path}`);
-            byOp.set(op, list);
-        }
-        // Conflicts by definition require a prior tree entry (sync detected that
-        // the agent-side version diverged from the filesystem baseline), which
-        // means the path is being re-synced as a modification. Attach conflicts
-        // only to the workspace:modified event, intersected with its paths — a
-        // created/deleted batch can't carry a meaningful conflict.
-        const conflictsByPath = new Map();
-        for (const c of conflicts)
-            conflictsByPath.set(c.path, c);
-        for (const [op, paths] of byOp) {
-            const type = opToEventType(op);
-            let eventConflicts;
-            if (op === 'modified' && conflictsByPath.size > 0) {
-                const matched = paths.filter(p => conflictsByPath.has(p.slice(mountName.length + 1)));
-                if (matched.length > 0)
-                    eventConflicts = matched;
+        const deadlineMs = this.agentActionScanDeadlineMs();
+        await Promise.all(mounts.map(async (mount) => {
+            const runningLate = mount.agentActionScanLate !== undefined;
+            const scan = this.agentActionScan(mount);
+            if (runningLate) {
+                // An earlier batch's scan outlasted its deadline and still runs: this
+                // round isn't held as well. Its own scan is queued after that one,
+                // and records its outcome when it finishes. It is late from the
+                // start, so a batch that comes while it runs isn't held either.
+                this.agentActionScanLateUntil(mount, scan);
+                this.agentActionScanMissed(mount, 'an earlier scan is still running past its deadline; this batch is scanned after it');
+                return;
+            }
+            let timer;
+            const deadline = new Promise((resolveDeadline) => {
+                timer = setTimeout(() => resolveDeadline('late'), deadlineMs);
+            });
+            const outcome = await Promise.race([scan.settled.then(() => 'done'), deadline]);
+            clearTimeout(timer);
+            if (outcome === 'late') {
+                this.agentActionScanLateUntil(mount, scan);
+                this.agentActionScanMissed(mount, `deadline exceeded (${deadlineMs} ms); the scan continues`);
             }
+        }));
+    }
+    /**
+     * Mark a scan late, and the mount as running late until it settles. The
+     * marker follows the newest late scan: a mount's scans run one after
+     * another, so the newest is the last to settle, and a batch that comes
+     * while any late scan of the chain still runs isn't held.
+     */
+    agentActionScanLateUntil(mount, scan) {
+        scan.late = true;
+        const settled = scan.settled;
+        mount.agentActionScanLate = settled;
+        void settled.then(() => { if (mount.agentActionScanLate === settled)
+            mount.agentActionScanLate = undefined; });
+    }
+    /** A batch's scan missed its deadline, or failed: said on status and as an event. */
+    agentActionScanMissed(mount, reason) {
+        mount.lastAgentActionScan = { at: Date.now(), complete: false, withinDeadline: false, reason };
+        this.ctx?.pushEvent({ type: 'workspace:agent-action-scan-incomplete', mount: mount.config.name, reason });
+    }
+    /**
+     * The mount's after-batch scan: one may run and one wait behind it. A batch
+     * that comes while one waits shares it, since it starts after the batch's
+     * tools ran. Each scan records its own outcome when it settles: on status
+     * while it is the mount's newest scan (a scan queued behind it describes a
+     * later batch), and as an event for regions it couldn't observe (the file
+     * cap, an unreadable or changing region, a branch that kept changing) or a
+     * failure, whichever scan it is.
+     */
+    agentActionScan(mount) {
+        if (mount.agentActionScanWaiting)
+            return mount.agentActionScanWaiting;
+        const scan = { late: false, settled: Promise.resolve() };
+        const pass = this.withMount(mount, () => {
+            if (mount.agentActionScanWaiting === scan)
+                mount.agentActionScanWaiting = undefined;
+            return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true });
+        });
+        scan.settled = pass.then((result) => {
+            if (result.incomplete.length > 0) {
+                this.ctx?.pushEvent({
+                    type: 'workspace:agent-action-scan-incomplete',
+                    mount: mount.config.name,
+                    reason: 'the scan finished, but some regions could not be observed',
+                    incomplete: result.incomplete,
+                });
+            }
+            if (mount.agentActionScanLatest !== scan)
+                return;
+            const incomplete = result.incomplete.length > 0 ? { incomplete: result.incomplete } : {};
+            mount.lastAgentActionScan = scan.late
+                ? { at: Date.now(), complete: true, withinDeadline: false, reason: 'finished after the deadline', ...incomplete }
+                : { at: Date.now(), complete: true, withinDeadline: true, ...incomplete };
+        }, (err) => {
+            const reason = `scan failed: ${err instanceof Error ? err.message : String(err)}`;
+            if (mount.agentActionScanLatest === scan)
+                this.agentActionScanMissed(mount, reason);
+            else
+                this.ctx?.pushEvent({ type: 'workspace:agent-action-scan-incomplete', mount: mount.config.name, reason });
+        });
+        mount.agentActionScanWaiting = scan;
+        mount.agentActionScanLatest = scan;
+        return scan;
+    }
+    /** The scan deadline, kept below the framework's hook bound (warned once). */
+    agentActionScanDeadlineMs() {
+        const configured = this.config.agentActionScanDeadlineMs ?? AGENT_ACTION_SCAN_DEADLINE_MS;
+        if (configured <= AGENT_ACTION_SCAN_DEADLINE_MAX_MS)
+            return configured;
+        if (!this.warnedScanDeadline) {
+            this.warnedScanDeadline = true;
+            console.warn(`[workspace] agentActionScanDeadlineMs ${configured} leaves less than 1 s before the framework's ` +
+                `${TOOL_BATCH_HOOK_TIMEOUT_MS} ms bound on a tool-batch hook; using ${AGENT_ACTION_SCAN_DEADLINE_MAX_MS} ms`);
+        }
+        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).
+     */
+    emitFsEvents(mountName, ops, newConflicts = []) {
+        if (!this.ctx || (ops.length === 0 && newConflicts.length === 0))
+            return;
+        const byOp = new Map();
+        const add = (op, path, conflict) => {
+            const group = byOp.get(op) ?? { paths: [], conflicts: [] };
+            const full = `${mountName}/${path}`;
+            if (!group.paths.includes(full))
+                group.paths.push(full);
+            if (conflict)
+                group.conflicts.push(full);
+            byOp.set(op, group);
+        };
+        for (const { path, op } of ops)
+            add(op, path, false);
+        for (const { path, op } of newConflicts)
+            add(op, path, true);
+        for (const [op, { paths, conflicts }] of byOp) {
             const event = {
-                type,
+                type: opToEventType(op),
                 paths,
                 mount: mountName,
-                ...(eventConflicts ? { conflicts: eventConflicts } : {}),
+                ...(conflicts.length > 0 ? { conflicts } : {}),
             };
             this.ctx.pushEvent(event);
         }
     }
 }
+/** What a listing shows of a path beyond its name. */
+function stateView(report) {
+    return {
+        state: report.state,
+        ...(report.size !== undefined ? { size: report.size } : {}),
+        ...(report.mimeType ? { mimeType: report.mimeType } : {}),
+        ...(report.conflict ? { conflict: report.conflict } : {}),
+        ...(report.note ? { note: report.note } : {}),
+    };
+}
 // ==========================================================================
 // Utilities
 // ==========================================================================