@animalabs/agent-framework 0.21.1 → 0.22.0

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

@@ -0,0 +1,368 @@
+/**
+ * The workspace's disk effects — a materialize's writes and unlinks, and the
+ * barriers that make them durable — under the mount boundary.
+ *
+ * Each effect is bound at its point of use, not at planning time: the parent
+ * directory is checked (located inside the mount, see observe.ts), the file is
+ * reached through it, and before anything is changed the effect checks that
+ * it acts on what was decided on — a regular file inside the mount, at this
+ * path, still holding the bytes planning saw (unless `force`, which overrides
+ * that freshness but never the boundary). Content is written only through a
+ * descriptor whose own location was confirmed inside the mount first, and
+ * only into a file with no other hard links: a write in place changes the
+ * file under every name it has, and the others may lie outside the mount (a
+ * package store's, say), so such a file is refused. Unlinking one name
+ * changes no other, so an unlink needs no such check.
+ *
+ * What an effect reports matters to the caller's evidence: a failure that
+ * never touched the path's entry leaves disk as planning saw it, so the
+ * path's evidence can be put back as it was; once the entry was touched
+ * (created, truncated, written or unlinked) the outcome is for the next
+ * observation to resolve. Directories created for a write don't touch the
+ * path's entry; they stay, empty, if the write is refused.
+ *
+ * Node has no openat, so a create, mkdir or unlink still resolves its path by
+ * name after the parent was checked: a parent replaced concurrently in that
+ * window can redirect that one operation, leaving an empty file or directory
+ * outside the mount or unlinking a same-named file there. Nor is there an
+ * unlink bound to an inode: an unlink checks the entry's identity again just
+ * before it, and a file replaced at its path after that check is the one
+ * unlinked. Content writes stay bound to the descriptor verified before
+ * modification: inside the mount, with no other hard links (a link another
+ * process makes to it after that check shares the write). The hash, which
+ * reads the whole file, comes before the checks of where the file is, and
+ * the root is checked again beside the parent, since the parent is found by
+ * path beneath the root's. A last look at the file (its descriptor's stat
+ * before a write, its entry's lstat before an unlink) refuses one written
+ * since it was first seen, so only an edit made in the moment between that
+ * look and the effect is overwritten or removed.
+ */
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { lstat, open, realpath, stat, unlink } from 'node:fs/promises';
+import { NONBLOCK, NOT_FOLLOWED, OUTSIDE_PARENT, ROOT_REPLACED, contained, errno, checkDir, checkRoot, nameOf, parentOf, } from './observe.js';
+/** Errors with which an unlink refuses outright, leaving the entry as it was. */
+const UNLINK_REFUSALS = new Set(['EACCES', 'EPERM', 'EROFS', 'EBUSY']);
+export class EffectFailed extends Error {
+    /** Whether the path's entry was touched before the failure. */
+    touched;
+    constructor(message, touched) {
+        super(message);
+        this.touched = touched;
+    }
+}
+const CHANGED = 'disk changed since it was checked';
+const MOVED = 'the directory changed since it was checked';
+const HARD_LINKED = 'a file with other hard links, which writing it in place would change too — force does not override '
+    + 'this; to write this path alone, give it a copy of its own first (copy it to a new name, then move that over it) '
+    + 'and materialize again';
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function noFollowFlag(view) {
+    return !view.followSymlinks && typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
+}
+/**
+ * The parent of a path, checked for an effect; proven absent; or why neither;
+ * with the root. The root comes first: still a directory, and still the one
+ * disk last agreed under, as any observation of it checks. An effect under a
+ * replaced root acts on nothing, whatever its caller checked before, and the
+ * parent is found by path beneath the root's path, so whoever acts checks the
+ * root again with the parent (`moved`): a root replaced after it was
+ * checked would otherwise lend the effect its replacement's directory.
+ */
+async function parentFor(view, rootReal, rel, create) {
+    const root = await checkRoot(view, rootReal);
+    if ('reason' in root)
+        throw new EffectFailed(root.reason, false);
+    const checked = await checkDir(view, rootReal, parentOf(rel), { create });
+    if (checked.kind === 'unobserved')
+        throw new EffectFailed(checked.outside ? OUTSIDE_PARENT : checked.reason, false);
+    return { ...checked, root: root.dir };
+}
+/**
+ * Why the parent, or the root it was found beneath, is no longer the
+ * directory its path names; null while each still is. The root is asked
+ * first, so a replaced root reads the same wherever it's found.
+ */
+async function moved(root, parent) {
+    if (!(await root.stillHere()))
+        return ROOT_REPLACED;
+    return (await parent.stillHere()) ? null : MOVED;
+}
+/**
+ * Whether the file at `target` is still the one `before` described: the same
+ * file, with the same size and stamps, so nothing wrote it since. Read just
+ * before an effect, after the slower checks, so an edit made while the file
+ * was hashed is never overwritten or deleted unseen; what remains is the
+ * moment between this and the effect, which Node can't close (see the header).
+ */
+function unchanged(before, now) {
+    return now !== null && now.dev === before.dev && now.ino === before.ino && now.size === before.size
+        && now.mtimeNs === before.mtimeNs && now.ctimeNs === before.ctimeNs;
+}
+/** The hash of what `target` holds, read through a descriptor that must be the file `id` names. */
+async function hashAt(target, id, flags) {
+    let handle;
+    try {
+        handle = await open(target, fsConstants.O_RDONLY | NONBLOCK | flags);
+    }
+    catch (err) {
+        throw new EffectFailed(`cannot verify the disk copy (${errno(err) ?? message(err)})`, false);
+    }
+    try {
+        const info = await handle.stat({ bigint: true });
+        if (info.dev !== id.dev || info.ino !== id.ino)
+            throw new EffectFailed(CHANGED, false);
+        const hash = createHash('sha256');
+        const chunk = Buffer.alloc(1 << 20);
+        for (let offset = 0;;) {
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, offset);
+            if (bytesRead === 0)
+                break;
+            hash.update(chunk.subarray(0, bytesRead));
+            offset += bytesRead;
+        }
+        return hash.digest('hex');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Write `bytes` at a mount-relative path, creating missing parent
+ * directories, and make the file durable (its directories are synced by the
+ * caller, after all of a push's effects: syncDirectories).
+ */
+export async function writeContained(view, rootReal, rel, bytes, expect) {
+    const checked = await parentFor(view, rootReal, rel, true);
+    if (checked.kind !== 'checked')
+        throw new EffectFailed('a parent path is not a directory', false);
+    const parent = checked.dir;
+    const root = checked.root;
+    const target = parent.at(nameOf(rel));
+    const noFollow = noFollowFlag(view);
+    if (!view.followSymlinks && !noFollow) {
+        // No O_NOFOLLOW (Windows): refuse a symlink by lstat before opening.
+        if ((await lstat(target).catch(() => null))?.isSymbolicLink())
+            throw new EffectFailed(NOT_FOLLOWED, false);
+    }
+    let touched = false;
+    const create = async () => {
+        try {
+            // Exclusive: never follows a symlink, never takes over a file that
+            // appeared since planning saw none.
+            const handle = await open(target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o644);
+            touched = true;
+            return handle;
+        }
+        catch (err) {
+            // O_EXCL refuses any entry: a file, a directory or a link.
+            if (errno(err) === 'EEXIST')
+                throw new EffectFailed('something appeared at this path since it was checked', false);
+            throw new EffectFailed(`cannot create the file (${errno(err) ?? message(err)})`, false);
+        }
+    };
+    let handle;
+    if (expect.kind === 'absent') {
+        handle = await create();
+    }
+    else {
+        try {
+            // Opened without truncating: nothing changes until it is located.
+            handle = await open(target, fsConstants.O_WRONLY | NONBLOCK | noFollow);
+        }
+        catch (err) {
+            const code = errno(err);
+            if (code === 'ENOENT' && expect.kind === 'any')
+                handle = await create();
+            else if (code === 'ENOENT')
+                throw new EffectFailed('the file was removed since it was checked', false);
+            else if (code === 'ELOOP' && !view.followSymlinks)
+                throw new EffectFailed(NOT_FOLLOWED, false);
+            else if (code === 'EISDIR')
+                throw new EffectFailed('a directory', false);
+            else if (code === 'ENXIO')
+                throw new EffectFailed('not a regular file', false); // a FIFO with no reader
+            else
+                throw new EffectFailed(`cannot open the file (${code ?? message(err)})`, false);
+        }
+    }
+    let stage = 'write the file';
+    try {
+        // Before any byte: a regular file, and — unless forced — still holding
+        // what was decided on. The hash reads the whole file, so it comes first,
+        // and the checks of where the file is follow it.
+        const info = await handle.stat({ bigint: true });
+        if (!info.isFile())
+            throw new EffectFailed('not a regular file', touched);
+        if (expect.kind === 'content' && (await hashAt(target, info, noFollow)) !== expect.hash)
+            throw new EffectFailed(CHANGED, touched);
+        // Then: canonically inside the mount, the one this path names (and not a
+        // symlink, where the mount follows none and the open couldn't refuse
+        // one), with no other names, in the directory still at its path beneath
+        // the root still at its own.
+        const real = await realpath(target).catch(() => null);
+        if (real === null)
+            throw new EffectFailed(CHANGED, touched);
+        if (!contained(rootReal, real))
+            throw new EffectFailed(view.followSymlinks ? 'a symlink that leaves the mount' : OUTSIDE_PARENT, touched);
+        const named = await stat(real, { bigint: true }).catch(() => null);
+        if (named === null || named.dev !== info.dev || named.ino !== info.ino)
+            throw new EffectFailed(CHANGED, touched);
+        if (!view.followSymlinks) {
+            const entry = await lstat(target, { bigint: true }).catch(() => null);
+            if (entry?.isSymbolicLink())
+                throw new EffectFailed(NOT_FOLLOWED, touched);
+            if (entry === null || !entry.isFile() || entry.dev !== info.dev || entry.ino !== info.ino)
+                throw new EffectFailed(CHANGED, touched);
+        }
+        if (info.nlink > 1n)
+            throw new EffectFailed(HARD_LINKED, touched);
+        const gone = await moved(root, parent);
+        if (gone !== null)
+            throw new EffectFailed(gone, touched);
+        // Nothing wrote it while those ran.
+        if (!unchanged(info, await handle.stat({ bigint: true }).catch(() => null)))
+            throw new EffectFailed(CHANGED, touched);
+        touched = true;
+        await handle.truncate(0);
+        await handle.writeFile(bytes);
+        stage = 'make the write durable (file fsync)';
+        await handle.sync();
+    }
+    catch (err) {
+        if (err instanceof EffectFailed)
+            throw err;
+        throw new EffectFailed(`could not ${stage}: ${message(err)}`, touched);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Unlink a mount-relative file, or confirm it gone (`absent` expected: a
+ * file found there is never removed). Returns the mount directory whose
+ * entries make the absence durable, for the caller's barrier: the file's
+ * parent, or — when the parent itself is gone — the directory proven to lack
+ * it, since that removal may not be durable either.
+ */
+export async function unlinkContained(view, rootReal, rel, expect) {
+    const checked = await parentFor(view, rootReal, rel, false);
+    if (checked.kind === 'absent') {
+        // No directory, so no file: proven beneath a root still at its path.
+        if (!(await checked.root.stillHere()))
+            throw new EffectFailed(ROOT_REPLACED, false);
+        return checked.by;
+    }
+    const parent = checked.dir;
+    const root = checked.root;
+    const target = parent.at(nameOf(rel));
+    let info;
+    try {
+        info = await lstat(target, { bigint: true });
+    }
+    catch (err) {
+        if (errno(err) === 'ENOENT') {
+            const gone = await moved(root, parent);
+            if (gone !== null)
+                throw new EffectFailed(gone, false);
+            return parent.rel;
+        }
+        throw new EffectFailed(`cannot stat (${errno(err) ?? message(err)})`, false);
+    }
+    // Confirming an unlink that already happened never removes a file that
+    // appeared since.
+    if (expect.kind === 'absent') {
+        const kind = info.isDirectory() ? 'a directory' : info.isSymbolicLink() ? 'a symlink' : 'a file';
+        throw new EffectFailed(`${kind} appeared at this path since it was checked`, false);
+    }
+    let file = info;
+    if (info.isSymbolicLink()) {
+        // The link itself is what is removed; a followed one must still lie inside.
+        if (!view.followSymlinks)
+            throw new EffectFailed(NOT_FOLLOWED, false);
+        const real = await realpath(target).catch(() => null);
+        if (real === null || !contained(rootReal, real))
+            throw new EffectFailed('a symlink that leaves the mount', false);
+        const through = await stat(real, { bigint: true }).catch(() => null);
+        if (through === null)
+            throw new EffectFailed(CHANGED, false);
+        file = through;
+    }
+    else if (info.isDirectory()) {
+        throw new EffectFailed('a directory', false);
+    }
+    if (expect.kind === 'content' && (await hashAt(target, file, noFollowFlag(view))) !== expect.hash)
+        throw new EffectFailed(CHANGED, false);
+    const gone = await moved(root, parent);
+    if (gone !== null)
+        throw new EffectFailed(gone, false);
+    // The entry checked is still the one at the path, unwritten since it was
+    // hashed, as close to the unlink as Node allows (see the header): a file
+    // replaced or edited while it was hashed isn't removed.
+    const again = await lstat(target, { bigint: true }).catch(() => null);
+    const named = again?.isSymbolicLink() ? await stat(target, { bigint: true }).catch(() => null) : again;
+    if (!unchanged(file, named))
+        throw new EffectFailed(CHANGED, false);
+    try {
+        await unlink(target);
+    }
+    catch (err) {
+        const code = errno(err);
+        // An unlink is all or nothing: one refused outright changed nothing, so
+        // the path's evidence can go back as it was. Anything else may have
+        // landed (a network filesystem's EIO, say): the next observation resolves it.
+        if (code !== 'ENOENT')
+            throw new EffectFailed(`could not unlink the file: ${message(err)}`, !UNLINK_REFUSALS.has(code ?? ''));
+    }
+    return parent.rel;
+}
+/**
+ * Sync each mount directory (mount-relative), deepest first, so the entries
+ * a push created or removed in them are durable. Each is checked first and the
+ * directory it holds is the one synced — never a replacement at its path.
+ * Returns the ones that failed, with why. Where directories can't be synced
+ * at all (Windows, or a filesystem answering EINVAL/ENOTSUP), there is
+ * nothing to wait for.
+ */
+export async function syncDirectories(view, rootReal, rels) {
+    const failed = new Map();
+    const depth = (rel) => (rel === '' ? 0 : rel.split('/').length);
+    const sorted = [...new Set(rels)].sort((a, b) => depth(b) - depth(a));
+    // Each directory is found by path beneath the root's path: under a root
+    // that isn't the one disk agreed under, or that is replaced while they're
+    // synced, none of them is the mount's.
+    const root = await checkRoot(view, rootReal);
+    if ('reason' in root) {
+        for (const rel of sorted)
+            failed.set(rel, root.reason);
+        return failed;
+    }
+    for (const rel of sorted) {
+        const checked = await checkDir(view, rootReal, rel);
+        if (checked.kind !== 'checked') {
+            failed.set(rel, checked.kind === 'absent' ? 'the directory is gone' : checked.reason);
+            continue;
+        }
+        try {
+            await checked.dir.sync();
+            if (!(await root.dir.stillHere()))
+                failed.set(rel, ROOT_REPLACED);
+        }
+        catch (err) {
+            failed.set(rel, message(err));
+        }
+    }
+    return failed;
+}
+/** The directories whose entries make a written file reachable: its parent up to the mount root. */
+export function chainOf(rel) {
+    const chain = [];
+    for (let dir = parentOf(rel);; dir = parentOf(dir)) {
+        chain.push(dir);
+        if (dir === '')
+            return chain;
+    }
+}
+//# sourceMappingURL=effects.js.map

package/dist/src/modules/workspace/effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.js","sourceRoot":"","sources":["../../../../src/modules/workspace/effects.ts"],"names":[],"mappings":"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"}

package/dist/src/modules/workspace/index.d.ts

@@ -58,9 +58,22 @@ export declare class WorkspaceModule implements Module {
     readonly name = "workspace";
     private ctx;
     private store;
+    /** Set once stop has drained and saved, cleared by start (running()). */
+    private stopped;
     private config;
     private mounts;
     private watchers;
+    /** What disk last agreed with (global records); created with the store. */
+    private agreement;
+    /** Branch-local intent per mount. */
+    private intents;
+    /** Each mount's turn: the tail of its serialized passes and writes. */
+    private mountTurns;
+    /** Whether an over-bound agentActionScanDeadlineMs has been warned about. */
+    private warnedScanDeadline;
+    /** 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;
     /** 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
@@ -77,6 +90,21 @@ export declare class WorkspaceModule implements Module {
      * second. `ensureRunning()` gates on `ctx && mounts-populated`.
      */
     initStore(store: JsStore): void;
+    /**
+     * 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;
+    private agreementOrThrow;
+    /** The view reconciliation needs of a mount, refreshed per pass. */
+    private runtime;
+    /** One disk→store pass; the caller holds the mount's turn. Emits its events. */
+    private passUnlocked;
+    /** One store→disk push; the caller holds the mount's turn. */
+    private pushUnlocked;
     start(ctx: ModuleContext): Promise<void>;
     /**
      * Apply persisted per-mount state once both halves of the lifecycle have
@@ -130,6 +158,12 @@ export declare class WorkspaceModule implements Module {
         mode: 'read-write' | 'read-only';
     }>;
     getTools(): ToolDefinition[];
+    private generatedTextFiles;
+    /** Compare the same normalized physical path for registration and tool access. */
+    private generatedFileKey;
+    private findGeneratedTextFile;
+    /** Generated files bypass stored blobs so every read reflects current definitions. */
+    registerGeneratedTextFile(path: string, read: () => string, agentName: string): void;
     handleToolCall(call: ToolCall): Promise<ToolResult>;
     onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse>;
     /**
@@ -153,8 +187,25 @@ export declare 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.
      */
-    writeBinary(mountPrefixedPath: string, data: Buffer, mimeType: string): Promise<ToolResult>;
+    writeBinary(mountPrefixedPath: string, data: Buffer, mimeType: string, options?: {
+        branch?: string;
+    }): Promise<ToolResult>;
     /**
      * Read a file's raw bytes from a mount (through the Chronicle tree, synced
      * first like the `read` tool). Public API for the framework's synthesized
@@ -192,6 +243,15 @@ export declare class WorkspaceModule implements Module {
      * Parse a mount-prefixed path into (mountName, relativePath).
      */
     private parsePath;
+    /**
+     * 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;
     private getStore;
     private validateImageBytes;
     private tryReadImageFromTree;
@@ -238,22 +298,39 @@ export declare class WorkspaceModule implements Module {
     private imageErrorFromRead;
     private readImageFromFilesystem;
     /**
-     * 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 commitToolChange;
+    /**
+     * 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 autoMaterialize;
+    private settleBeforeMutation;
     /**
-     * Ensure a file is synced from filesystem if not yet in tree (lazy sync).
+     * 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 ensureSynced;
+    /** Why the workspace holds no entry at a path, when disk explains it. */
+    private notInWorkspace;
     private handleRead;
     private handleReadImage;
     private handleWrite;
@@ -263,6 +340,29 @@ export declare class WorkspaceModule implements Module {
     private handleGlob;
     private handleGrep;
     private handleStatus;
+    /**
+     * 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;
+    /**
+     * 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;
     private handleMaterialize;
     /**
      * Programmatically materialize a mount's files from Chronicle tree to filesystem.
@@ -271,17 +371,55 @@ export declare class WorkspaceModule implements Module {
      */
     materializeMount(mountName: string): Promise<string[]>;
     private handleSync;
+    /**
+     * 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 acceptRootUnlocked;
     /**
      * 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 handleFsChanges;
     /**
-     * Group synced paths by op and push one ProcessEvent per non-empty op.
+     * After an agent's completed tool batch, before anything continues its turn:
+     * scan every `watch: 'on-agent-action'` mount, so what the batch's tools did
+     * on disk (a shell command's files, a deletion) is in the workspace when the
+     * agent next looks. A scan that outlasts the deadline stops holding the
+     * round: the miss is recorded on the mount's status and pushed as a
+     * `workspace:agent-action-scan-incomplete` event, and the scan continues,
+     * deciding on the branch selected when it applies.
+     */
+    onToolBatchComplete(_agentName?: string): Promise<void>;
+    /**
+     * 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;
+    /** A batch's scan missed its deadline, or failed: said on status and as an event. */
+    private agentActionScanMissed;
+    /**
+     * 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;
+    /** The scan deadline, kept below the framework's hook bound (warned once). */
+    private agentActionScanDeadlineMs;
+    /**
+     * 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;
 }