@animalabs/agent-framework 0.21.1 → 0.22.1

package/src/modules/workspace/index.ts

@@ -7,12 +7,13 @@
 
 import { constants as fsConstants } from 'node:fs';
 import type { Stats } from 'node:fs';
-import { open, readFile, stat, access, 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 type { JsStore } from '@animalabs/chronicle';
 import type { Module, ModuleContext, ProcessState, EventResponse } from '../../types/module.js';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from '../../types/events.js';
 import type {
+  AgentActionScan,
   WorkspaceConfig,
   MountConfig,
   MountState,
@@ -35,7 +36,31 @@ import type {
 } from './types.js';
 import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher, type FsChange } from './watcher.js';
-import { syncFromFs, materializeToFs, hashContent, isBinary, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } 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 { coveredByIgnore, filesystemTrustsCtime, locateRoot } from './observe.js';
+import { TOOL_BATCH_HOOK_TIMEOUT_MS } from '../../module-registry.js';
+import {
+  type MountRuntime,
+  type PassOptions,
+  type PassResult,
+  type PathReport,
+  type PushOptions,
+  type PushResult,
+  type Scope,
+  type TreeOp,
+  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;
 
 export type {
   WorkspaceConfig,
@@ -603,9 +628,22 @@ export class WorkspaceModule implements Module {
 
   private ctx: ModuleContext | null = null;
   private store: JsStore | null = null;
+  /** Set once stop has drained and saved, cleared by start (running()). */
+  private stopped = false;
   private config: WorkspaceConfig;
   private mounts = new Map<string, MountState>();
   private watchers = new Map<string, MountWatcher>();
+  /** What disk last agreed with (global records); created with the store. */
+  private agreement: DiskAgreement | null = null;
+  /** Branch-local intent per mount. */
+  private intents = new Map<string, BranchIntents>();
+  /** Each mount's turn: the tail of its serialized passes and writes. */
+  private mountTurns = new Map<string, Promise<void>>();
+  /** Whether an over-bound agentActionScanDeadlineMs has been warned about. */
+  private 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. */
+  private ctimeTrust = new Map<string, string | null>();
   /** 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
@@ -651,40 +689,119 @@ export class WorkspaceModule implements Module {
   initStore(store: JsStore): void {
     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: 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.
+   */
+  private withMount<T>(mount: MountState, fn: () => Promise<T>): Promise<T> {
+    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;
+  }
+
+  private agreementOrThrow(): DiskAgreement {
+    if (!this.agreement) throw new Error('Workspace store not initialized');
+    return this.agreement;
+  }
+
+  /** The view reconciliation needs of a mount, refreshed per pass. */
+  private async runtime(mount: MountState): Promise<MountRuntime> {
+    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. */
+  private async passUnlocked(mount: MountState, scope: Scope, opts: PassOptions = {}): Promise<PassResult> {
+    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. */
+  private async pushUnlocked(mount: MountState, paths: string[], opts: PushOptions = {}): Promise<PushResult> {
+    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: ModuleContext): Promise<void> {
     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.
@@ -709,9 +826,18 @@ export class WorkspaceModule implements Module {
 
     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.
@@ -855,12 +981,10 @@ export class WorkspaceModule implements Module {
         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);
       }
 
@@ -878,9 +1002,9 @@ export class WorkspaceModule implements Module {
     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);
       this.ctx?.pushEvent({
@@ -892,6 +1016,24 @@ export class WorkspaceModule implements Module {
   }
 
   async stop(): Promise<void> {
+    // 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;
@@ -906,12 +1048,6 @@ export class WorkspaceModule implements Module {
       }
       this.ctx.setState(state);
     }
-
-    // Stop watchers
-    for (const watcher of this.watchers.values()) {
-      await watcher.stop();
-    }
-    this.watchers.clear();
     this.ctx = null;
   }
 
@@ -988,7 +1124,9 @@ export class WorkspaceModule implements Module {
       },
       {
         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' as const,
           properties: {
@@ -999,7 +1137,14 @@ export class WorkspaceModule implements Module {
       },
       {
         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' as const,
           properties: {
@@ -1010,7 +1155,7 @@ export class WorkspaceModule implements Module {
       },
       {
         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' as const,
           properties: {
@@ -1022,7 +1167,11 @@ export class WorkspaceModule implements Module {
       },
       {
         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' as const,
           properties: {
@@ -1047,24 +1196,52 @@ export class WorkspaceModule implements Module {
       },
       {
         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' as const,
           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. What the scan passed over by design and '
+          + 'reported nowhere else is counted under `passedOver`, by mount and reason: entries the mount\'s '
+          + 'ignore list covers that hold nothing the workspace tracks (an ignored directory counts once). So a '
+          + 'total of 0, with no conflicts and nothing under `passedOver`, `incomplete` or `skipped`, means the '
+          + 'sync looked everywhere and nothing had changed. A path the mount ignores is synced when you name '
+          + 'it, and listed under `ignored`: a sync without a path passes over it. Naming an ignored directory '
+          + 'sets aside the patterns that cover it or a directory above it; one that covers only something '
+          + 'inside it still applies, and what it covers is passed over.',
         inputSchema: {
           type: 'object' as const,
           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.',
+            },
           },
         },
       },
@@ -1075,9 +1252,49 @@ export class WorkspaceModule implements Module {
   // Tool Dispatch
   // ==========================================================================
 
+  private generatedTextFiles = new Map<string, {read: () => string; agentName: string}>();
+
+  /** Compare the same normalized physical path for registration and tool access. */
+  private generatedFileKey(path: string): string {
+    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;
+  }
+
+  private findGeneratedTextFile(path: string) {
+    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: string, read: () => string, agentName: string): void {
+    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: ToolCall): Promise<ToolResult> {
+    if (!this.running()) return { success: false, isError: true, error: NOT_RUNNING };
     try {
       const input = call.input as Record<string, unknown>;
+      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 as unknown as ReadInput, generated.read());
+      }
+
       switch (call.name) {
         case 'read': return await this.handleRead(input as unknown as ReadInput);
         case 'read_image': return await this.handleReadImage(input as unknown as ReadImageInput);
@@ -1197,12 +1414,29 @@ export class WorkspaceModule implements Module {
    * 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: string,
     data: Buffer,
     mimeType: string,
+    options: { branch?: string } = {},
   ): Promise<ToolResult> {
+    if (!this.running()) return { success: false, isError: true, error: NOT_RUNNING };
     let mount: MountState;
     let relativePath: string;
     try {
@@ -1222,24 +1456,36 @@ export class WorkspaceModule implements Module {
       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: string | null;
+      try {
+        const materializeError = await this.commitToolChange(mount, relativePath,
+          { kind: 'set', blobHash, size: data.byteLength }, () => { committed = true; });
+        failure = materializeError === null ? null
+          : `Wrote to Chronicle but failed to materialize "${mountPrefixedPath}" to disk: ${materializeError}.`;
+      } 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 },
-    };
+    });
   }
 
   /**
@@ -1250,6 +1496,7 @@ export class WorkspaceModule implements Module {
   async readBinary(
     mountPrefixedPath: string,
   ): Promise<{ data: Buffer } | { error: string }> {
+    if (!this.running()) return { error: NOT_RUNNING };
     let mount: MountState;
     let relativePath: string;
     try {
@@ -1258,12 +1505,14 @@ export class WorkspaceModule implements Module {
       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 };
+    });
   }
 
   /**
@@ -1332,6 +1581,18 @@ export class WorkspaceModule implements Module {
     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.
+   */
+  private running(): boolean {
+    return !this.stopped;
+  }
+
   private getStore(): JsStore {
     if (!this.store) throw new Error('WorkspaceModule: store not initialized. Call initStore() first.');
     return this.store;
@@ -1653,55 +1914,70 @@ export class WorkspaceModule implements Module {
   }
 
   /**
-   * 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).
    */
-  private async autoMaterialize(
+  private async commitToolChange(
     mount: MountState,
     relativePath: string,
-    op: 'write' | 'delete',
-    content?: Buffer,
+    change: { kind: 'set'; blobHash: string; size: number; mode?: number } | { kind: 'remove'; previousHash: string },
+    onCommitted?: () => void,
   ): Promise<string | null> {
-    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 as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
-        }
-        mount.materializedHashes.delete(relativePath);
-      }
-      return null;
-    } 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,
-      } as ProcessEvent);
-      return msg;
+    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;
+      });
+    } else {
+      store.treeRemove(mount.treeStateId, relativePath);
+      intents.update(relativePath, (cur) => {
+        const next = { ...cur, tombstone: { hash: change.previousHash } };
+        delete next.origin;
+        return next;
+      });
     }
+    if (!mount.config.autoMaterialize || mount.config.mode === 'read-only') return null;
+
+    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,
+    } as ProcessEvent);
+    return refused.reason;
   }
 
   // ==========================================================================
@@ -1709,36 +1985,49 @@ export class WorkspaceModule implements Module {
   // ==========================================================================
 
   /**
-   * 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.
    */
-  private async ensureSynced(mount: MountState, relativePath: string): Promise<void> {
-    const store = this.getStore();
-    const existing = store.treeGet(mount.treeStateId, relativePath);
-    if (existing) return; // Already in tree
+  private async settleBeforeMutation(mount: MountState, relativePath: string): Promise<void> {
+    if (this.agreementOrThrow().get(mount.config.name, relativePath)?.kind !== 'pending') return;
+    await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] });
+  }
 
-    // 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
+  /**
+   * 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.
+   */
+  private async ensureSynced(mount: MountState, relativePath: string): Promise<PathReport | undefined> {
+    const store = this.getStore();
+    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. */
+  private notInWorkspace(path: string, report: PathReport | undefined): string {
+    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}`;
     }
   }
 
@@ -1746,7 +2035,7 @@ export class WorkspaceModule implements Module {
   // Tool Handlers
   // ==========================================================================
 
-  private async handleRead(input: ReadInput): Promise<ToolResult> {
+  private async handleRead(input: ReadInput, generatedContent?: string): Promise<ToolResult> {
     const characterPaging = input.offsetChars !== undefined || input.limitChars !== undefined;
     const offsetChars = input.offsetChars ?? 0;
     const limitChars = input.limitChars ?? 2000;
@@ -1760,22 +2049,21 @@ export class WorkspaceModule implements Module {
         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 (): Promise<{ text: string } | { error: string }> => {
+        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: number): boolean =>
@@ -1916,13 +2204,11 @@ export class WorkspaceModule implements Module {
     }
 
     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,
@@ -1948,62 +2234,65 @@ export class WorkspaceModule implements Module {
     }
 
     const store = this.getStore();
-    await this.ensureSynced(mount, relativePath);
+    return this.withMount(mount, async (): Promise<ToolResult> => {
+      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: `File not found: ${input.path}`, isError: true };
-    }
+      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 };
-    }
+      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');
+      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 };
+      // 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),
-      },
-    };
+    });
   }
 
   private async handleDelete(input: DeleteInput): Promise<ToolResult> {
@@ -2013,22 +2302,28 @@ export class WorkspaceModule implements Module {
     }
 
     const store = this.getStore();
-    const entry = store.treeGet(mount.treeStateId, relativePath);
-    if (!entry) {
-      return { success: false, error: `File not found: ${input.path}`, isError: true };
-    }
+    return this.withMount(mount, async (): Promise<ToolResult> => {
+      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 };
+      }
 
-    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,
-      };
-    }
+      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 } };
+      // Its whole receipt is what it changed: kept in the stub if the guard
+      // withholds the result (agent-framework #277).
+      return { success: true, data: { path: input.path, deleted: true }, keepWhenWithheld: ['path', 'deleted'] };
+    });
   }
 
   private async handleLs(input: LsInput): Promise<ToolResult> {
@@ -2045,63 +2340,55 @@ export class WorkspaceModule implements Module {
     }
 
     const { mount, relativePath } = this.parsePath(input.path);
+    const recursive = input.recursive === true;
 
-    // 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;
-    }
+    // 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 (): Promise<ToolResult> => {
+      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 } : {};
 
-    const prefix = relativePath ? relativePath + '/' : '';
-    const entries = store.treeList(mount.treeStateId, prefix || undefined);
+      if (recursive) {
+        return {
+          success: true,
+          data: {
+            path: input.path,
+            entries: reports.map((r) => ({ path: r.path, ...stateView(r) })),
+            count: reports.length,
+            ...incomplete,
+          },
+        };
+      }
 
-    if (input.recursive) {
+      // 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: Array<Record<string, unknown>> = [
+        ...[...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<string>();
-    const children: Array<{ name: string; type: 'file' | 'directory' }> = [];
-
-    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,
-      },
-    };
+    });
   }
 
   private async handleGlob(input: GlobInput): Promise<ToolResult> {
-    const store = this.getStore();
     const regex = globToRegex(input.pattern);
-    const matches: string[] = [];
+    const matches: Array<Record<string, unknown>> = [];
+    const incomplete: Array<{ path: string; reason: string }> = [];
 
     // Search across mounts
     const mountsToSearch = input.path
@@ -2109,20 +2396,17 @@ export class WorkspaceModule implements Module {
       : [...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 {
@@ -2131,6 +2415,7 @@ export class WorkspaceModule implements Module {
         pattern: input.pattern,
         matches,
         count: matches.length,
+        ...(incomplete.length > 0 ? { incomplete } : {}),
       },
     };
   }
@@ -2152,61 +2437,107 @@ export class WorkspaceModule implements Module {
       ? [this.parsePath(input.path)]
       : [...this.mounts.values()].map(m => ({ mount: m, relativePath: '' }));
 
-    const results: Array<{ file: string; matches: Array<{ line: number; text: string; context?: string[] }> }> = [];
-
-    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: Array<{ path: string; blobHash: string }>;
-      const fileNode = relativePath
-        ? (store.treeGet(mount.treeStateId, relativePath) as { blobHash?: string } | null)
-        : null;
-      if (fileNode && fileNode.blobHash) {
-        entries = [{ path: relativePath, blobHash: fileNode.blobHash }];
-      } else {
-        const prefix = relativePath ? relativePath + '/' : undefined;
-        entries = store.treeList(mount.treeStateId, prefix);
+    type GrepMatch = { line: number; text: string; context?: string[] };
+    const results: Array<{ file: string; state: string; version: 'workspace' | 'conflicting-disk' | 'recorded-disk'; matches: GrepMatch[] }> = [];
+    const skipped: Array<{ file: string; reason: string; size?: number; mimeType?: string }> = [];
+    const incomplete: Array<{ path: string; reason: string }> = [];
+
+    const search = (content: string): GrepMatch[] => {
+      const lines = content.split('\n');
+      const found: GrepMatch[] = [];
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) {
+          const match: GrepMatch = { 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 entry of entries) {
-        if (fileGlob && !fileGlob.test(entry.path)) continue;
+    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: PassResult | null = 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 (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 blob = store.getBlob(entry.blobHash);
-        if (!blob) continue;
-
-        const content = blob.toString('utf-8');
-        const lines = content.split('\n');
-        const fileMatches: Array<{ line: number; text: string; context?: string[] }> = [];
-
-        for (let i = 0; i < lines.length; i++) {
-          if (regex.test(lines[i])) {
-            const match: { line: number; text: string; context?: string[] } = {
-              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);
+        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' });
             }
-            fileMatches.push(match);
+          } 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 });
           }
         }
-
-        if (fileMatches.length > 0) {
-          results.push({
-            file: `${mount.config.name}/${entry.path}`,
-            matches: fileMatches,
-          });
-        }
-      }
+      });
     }
 
     return {
@@ -2215,20 +2546,33 @@ export class WorkspaceModule implements Module {
         pattern: input.pattern,
         results,
         totalMatches: results.reduce((sum, r) => sum + r.matches.length, 0),
+        ...(skipped.length > 0 ? { skipped } : {}),
+        ...(incomplete.length > 0 ? { incomplete } : {}),
       },
     };
   }
 
-  private async handleStatus(_input: StatusInput): Promise<ToolResult> {
+  private async handleStatus(input: StatusInput): Promise<ToolResult> {
     const store = this.getStore();
     const status: Record<string, unknown> = {};
+    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] = {
@@ -2238,24 +2582,90 @@ export class WorkspaceModule implements Module {
         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.
+   */
+  private materializeSelection(mount: MountState, explicitPath: string): { paths: string[]; inPlace: boolean } {
+    const store = this.getStore();
+    const intents = new Map(this.intents.get(mount.config.name)!.list(explicitPath));
+    const selected = new Set<string>();
+
+    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.
+   */
+  private entriesByEvidence(mount: MountState): { owed: string[]; unchecked: string[]; agreed: number } {
+    const store = this.getStore();
+    const agreement = this.agreementOrThrow();
+    const name = mount.config.name;
+    const intents = this.intents.get(name)!;
+    const owed: string[] = [];
+    const unchecked: string[] = [];
+    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 };
+  }
+
   private async handleMaterialize(input: MaterializeInput): Promise<ToolResult> {
     const store = this.getStore();
 
     const allWritten: Array<{ mount: string; path: string }> = [];
+    const allDeleted: Array<{ mount: string; path: string }> = [];
+    const pendingDeletions: Array<{ mount: string; path: string }> = [];
+
+    let explicit: { mount: MountState; relativePath: string } | null = null;
+    if (input.path) explicit = this.parsePath(input.path);
 
     let mountsToMaterialize: Array<{ name: string; mount: MountState }>;
-    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 };
@@ -2270,67 +2680,100 @@ export class WorkspaceModule implements Module {
     // 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: Array<{ mount: string; reason: string }> = [];
-    for (const { name, mount } of mountsToMaterialize) {
-      const reason = this.mountMaterializeBlockReason(store, mount);
-      if (!reason) 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 });
-      }
-    }
-    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,
-      };
-    }
+    const guarded: string[] = [];
+    let proceeded = 0;
 
     for (const { name, mount } of mountsToMaterialize) {
-
-      let paths: string[] | undefined;
-      if (input.path) {
-        const { relativePath } = this.parsePath(input.path);
-        paths = relativePath ? [relativePath] : undefined;
+      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;
       }
-
-      // 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);
-        allWritten.push({ mount: name, path: p });
+      const turn = await this.withMount(mount, async (): Promise<{ blocked: string } | { pushed: PushResult; inPlace: boolean }> => {
+        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;
+      }
+      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 } : {}),
       },
+      // What disk lost, then what it was written: kept in the stub if the
+      // guard withholds the result (agent-framework #277). What was left or
+      // skipped, and why, is in the full result.
+      keepWhenWithheld: ['deleted', 'materialized'],
     };
   }
 
@@ -2340,6 +2783,7 @@ export class WorkspaceModule implements Module {
    * Resets branch tracking to allow cross-branch materialization.
    */
   async materializeMount(mountName: string): Promise<string[]> {
+    if (!this.running()) return [];
     const store = this.getStore();
     const mount = this.mounts.get(mountName);
     if (!mount || mount.config.mode === 'read-only') return [];
@@ -2348,57 +2792,136 @@ export class WorkspaceModule implements Module {
     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;
   }
 
   private async handleSync(input: SyncInput): Promise<ToolResult> {
     const store = this.getStore();
-    const allResults: Array<{ mount: string; synced: string[]; conflicts: ConflictInfo[] }> = [];
+    // A path sync adopts on the branch it was asked on, read before any await.
+    const askedOn = store.currentBranch().id;
+    const allResults: Array<{
+      mount: string;
+      synced: string[];
+      conflicts: Array<{ path: string; kind: string; diskCopy: string }>;
+      /** A path sync's workspace changes given up for disk's state, each with the state it had,
+       *  and what that did to the workspace copy (absent when nothing). */
+      discarded?: Array<{ path: string; was: string; op?: string }>;
+    }> = [];
     const allSkipped: Array<{ mount: string; path: string; reason: string }> = [];
-
-    let mountsToSync: Array<{ name: string; mount: MountState }>;
-    if (input.mount) {
+    const allIncomplete: Array<{ mount: string; path: string; reason: string }> = [];
+    const allPassedOver: Array<{ mount: string; reason: string; count: number }> = [];
+    const allIgnored: Array<{ mount: string; path: string; note: string }> = [];
+    const rootsAccepted: string[] = [];
+    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: Array<{ name: string; mount: MountState; relativePath: string }>;
+    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 }));
+      targets = [...this.mounts.entries()].map(([name, mount]) => ({ name, mount, relativePath: '' }));
     }
 
-    for (const { name, mount } of mountsToSync) {
-
-      let paths: string[] | undefined;
-      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;
+    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));
+        // named: ignore patterns covering the path asked for don't apply
+        // beneath it (a directory scope's walk; a path scope doesn't walk).
+        const opts: PassOptions = { rehash: true, adopt: () => true, branchId: askedOn, named: true };
+        if (!isDir) return this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
+        const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, opts);
+        // 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);
+        const passedOver = new Map(beneath.passedOver);
+        for (const [reason, count] of itself.passedOver) passedOver.set(reason, (passedOver.get(reason) ?? 0) + count);
+        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],
+          passedOver,
+          dirs: beneath.dirs,
+          branchId: itself.branchId ?? beneath.branchId,
+        };
+      });
 
-      if (result.synced.length > 0 || result.conflicts.length > 0) {
+      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 });
+      for (const [reason, count] of pass.passedOver) allPassedOver.push({ mount: name, reason, count });
+      // A path named explicitly is synced even where the mount's ignore list
+      // covers it, and the result says so: a sync without a path passes
+      // over it, so nothing else keeps it current (agent-framework #276).
+      if (coveredByIgnore(relativePath, mount.config.ignore ?? [])) {
+        allIgnored.push({
+          mount: name,
+          path: relativePath,
+          note: 'this mount\'s ignore list covers it, so a sync without a path won\'t maintain it',
+        });
       }
     }
 
@@ -2409,10 +2932,39 @@ export class WorkspaceModule implements Module {
         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 } : {}),
+        ...(allPassedOver.length > 0 ? { passedOver: allPassedOver } : {}),
+        ...(allIgnored.length > 0 ? { ignored: allIgnored } : {}),
+        ...(rootsAccepted.length > 0 ? { rootsAccepted } : {}),
       },
+      // What the workspace took from disk, gave up, or now holds as a
+      // conflict, per mount, and any root it accepted: kept in the stub if
+      // the guard withholds the result (agent-framework #277). What the scan
+      // skipped or couldn't see is in the full result.
+      // A root it accepted is short and telling: first, so a long results
+      // list can't cut it away.
+      keepWhenWithheld: ['rootsAccepted', 'results'],
     };
   }
 
+  /**
+   * 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.
+   */
+  private async acceptRootUnlocked(mount: MountState): Promise<boolean> {
+    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
   // ==========================================================================
@@ -2420,74 +2972,163 @@ export class WorkspaceModule implements Module {
   /**
    * 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.
    */
   private async handleFsChanges(mountName: string, changes: FsChange[]): Promise<void> {
-    const store = this.store;
     const mount = this.mounts.get(mountName);
-    if (!store || !mount) return;
+    if (!this.store || !this.running() || !mount) return;
+    const paths = [...new Set(changes.map((c) => c.path))];
+    if (paths.length === 0) return;
+    await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'paths', paths }));
+  }
 
-    const touchedPaths = changes.filter(c => c.op !== 'deleted').map(c => c.path);
-    const deletedPaths = changes.filter(c => c.op === 'deleted').map(c => c.path);
+  /**
+   * 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.
+   */
+  async onToolBatchComplete(_agentName?: string): Promise<void> {
+    // 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 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: ReturnType<typeof setTimeout> | undefined;
+      const deadline = new Promise<'late'>((resolveDeadline) => {
+        timer = setTimeout(() => resolveDeadline('late'), deadlineMs);
+      });
+      const outcome = await Promise.race([scan.settled.then(() => 'done' as const), deadline]);
+      clearTimeout(timer);
+      if (outcome === 'late') {
+        this.agentActionScanLateUntil(mount, scan);
+        this.agentActionScanMissed(mount, `deadline exceeded (${deadlineMs} ms); the scan continues`);
+      }
+    }));
+  }
 
-    const syncResult = touchedPaths.length > 0
-      ? await syncFromFs(store, mount, touchedPaths)
-      : { synced: [], conflicts: [], skipped: [] };
+  /**
+   * 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.
+   */
+  private agentActionScanLateUntil(mount: MountState, scan: AgentActionScan): void {
+    scan.late = true;
+    const settled = scan.settled;
+    mount.agentActionScanLate = settled;
+    void settled.then(() => { if (mount.agentActionScanLate === settled) mount.agentActionScanLate = undefined; });
+  }
 
-    // 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' });
-      }
-    }
+  /** A batch's scan missed its deadline, or failed: said on status and as an event. */
+  private agentActionScanMissed(mount: MountState, reason: string): void {
+    mount.lastAgentActionScan = { at: Date.now(), complete: false, withinDeadline: false, reason };
+    this.ctx?.pushEvent({ type: 'workspace:agent-action-scan-incomplete', mount: mount.config.name, reason } as ProcessEvent);
+  }
 
-    this.emitFsEvents(mountName, syncResult.synced, syncResult.conflicts);
+  /**
+   * 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.
+   */
+  private agentActionScan(mount: MountState): AgentActionScan {
+    if (mount.agentActionScanWaiting) return mount.agentActionScanWaiting;
+    const scan: AgentActionScan = { 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,
+          } as ProcessEvent);
+        }
+        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: unknown) => {
+        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 } as ProcessEvent);
+      },
+    );
+    mount.agentActionScanWaiting = scan;
+    mount.agentActionScanLatest = scan;
+    return scan;
+  }
+
+  /** The scan deadline, kept below the framework's hook bound (warned once). */
+  private agentActionScanDeadlineMs(): number {
+    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;
   }
 
   /**
-   * Group synced paths by op and push one ProcessEvent per non-empty op.
+   * 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).
    */
   private emitFsEvents(
     mountName: string,
-    synced: Array<{ path: string; op: WorkspaceFsOp }>,
-    conflicts: ConflictInfo[],
+    ops: Array<{ path: string; op: TreeOp }>,
+    newConflicts: Array<{ path: string; op: TreeOp }> = [],
   ): void {
-    if (!this.ctx || synced.length === 0) return;
-
-    const byOp = new Map<WorkspaceFsOp, string[]>();
-    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<string, ConflictInfo>();
-    for (const c of conflicts) conflictsByPath.set(c.path, c);
-
-    for (const [op, paths] of byOp) {
-      const type = opToEventType(op);
-      let eventConflicts: string[] | undefined;
-      if (op === 'modified' && conflictsByPath.size > 0) {
-        const matched = paths.filter(p => conflictsByPath.has(p.slice(mountName.length + 1)));
-        if (matched.length > 0) eventConflicts = matched;
-      }
+    if (!this.ctx || (ops.length === 0 && newConflicts.length === 0)) return;
+
+    const byOp = new Map<WorkspaceFsOp, { paths: string[]; conflicts: string[] }>();
+    const add = (op: TreeOp, path: string, conflict: boolean): void => {
+      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 } : {}),
       } as WorkspaceCreatedEvent | WorkspaceModifiedEvent | WorkspaceDeletedEvent;
       this.ctx.pushEvent(event as ProcessEvent);
     }
@@ -2495,6 +3136,17 @@ export class WorkspaceModule implements Module {
 
 }
 
+/** What a listing shows of a path beyond its name. */
+function stateView(report: PathReport): Record<string, unknown> {
+  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
 // ==========================================================================