@animalabs/agent-framework 0.23.3 → 0.24.1

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

@@ -8,7 +8,7 @@ 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 { WorkspaceConfig } from './types.js';
-export type { WorkspaceConfig, MountConfig, MountState, WorkspaceModuleState, ReadInput, ReadImageInput, WriteInput, EditInput, DeleteInput, LsInput, GlobInput, GrepInput, StatusInput, MaterializeInput, SyncInput, } from './types.js';
+export type { WorkspaceConfig, MountConfig, MountState, WorkspaceModuleState, ReadInput, ReadImageInput, WriteInput, EditInput, EditManyInput, DeleteInput, LsInput, GlobInput, GrepInput, StatusInput, MaterializeInput, SyncInput, } from './types.js';
 /**
  * Why a workspace-owned filesystem read was refused. Distinguishes the cases a
  * peer needs to react to differently: a path that never resolved inside the
@@ -24,13 +24,25 @@ export type { WorkspaceConfig, MountConfig, MountState, WorkspaceModuleState, Re
  * link and, where it leads somewhere, its target, a symlink whose canonical
  * target lands outside the canonical mount root, or one among the path's
  * directories leading out of it (`escape`), a file swapped underneath the read
- * (`changed`), and a path in another mount's directory nested in the one
- * named, or reached through a symlink among the path's directories leading
- * there (`other_mount`), whose message names the mount that holds it and the
- * path to use there. A `mount_unavailable` for a root whose realpath or stat
- * fails otherwise carries that errno, such as EACCES.
+ * (`changed`), a path the mount's `include` doesn't cover (`outside_include`),
+ * and a path in another mount's directory nested in the one named
+ * (`other_mount`), whose message names the mount that holds it and the path
+ * to use there. A symlink leading into such a directory is `other_mount`
+ * only where its refusal names that mount: a directory, or a file that
+ * mount's include covers. Anywhere else, on a mount that doesn't follow
+ * symlinks, it gets the code of a link where it stands, `symlink` at the
+ * path itself and `parent_symlink` on its way, and on one that does,
+ * `escape`, as a path that leaves the mount. On a mount with an include, a
+ * link's message names its target only where a tool could name it: a
+ * directory, or a file the include covers. A link the include doesn't cover
+ * is outside the mount, and its message tells nothing of where it leads, so
+ * on a path's way its code is `parent_symlink` wherever it leads; named
+ * itself, it's refused as outside the include (`outside_include`), as any
+ * path the include doesn't cover is.
+ * A `mount_unavailable` for a root whose realpath or stat fails otherwise
+ * carries that errno, such as EACCES.
  */
-export type WorkspaceReadErrorCode = 'unknown_mount' | 'traversal' | 'other_mount' | 'mount_unavailable' | 'not_found' | 'directory' | 'symlink' | 'parent_symlink' | 'escape' | 'changed';
+export type WorkspaceReadErrorCode = 'unknown_mount' | 'traversal' | 'outside_include' | 'other_mount' | 'mount_unavailable' | 'not_found' | 'directory' | 'symlink' | 'parent_symlink' | 'escape' | 'changed';
 /** Where in the open sequence a `WorkspaceReadError` originated (diagnostics). */
 export type WorkspaceReadStage = 'parse'
 /** The mount root's check: a directory, the one the workspace was using. */
@@ -119,6 +131,10 @@ export declare class WorkspaceModule implements Module {
     private otherMounts;
     /** Whether each mount's root folds case (foldsCase), where disk has it, as the last start read it. */
     private rootFoldsCase;
+    /** Where the last start placed each mount's root (readNesting's `reals`). */
+    private placedRoots;
+    /** Each directory above each mount's configured path, with where the last start found it on disk (readNesting's `above`). */
+    private placedAbove;
     /**
      * Whether a file's mode is observed, taken in and applied (MountRuntime's
      * `modesObserved`): not on Windows, which reports no POSIX modes. A test
@@ -130,6 +146,12 @@ export declare class WorkspaceModule implements Module {
      *  mounts, so restoration must be second-callback-safe like watcher
      *  startup already is (issue #72). Cleared after application. */
     private savedState;
+    /**
+     * The mounts configured direct that run as 'chronicle' this session, with
+     * the changes the store held there that disk lacked (chooseKinds), for
+     * ensureRunning to say once both halves of the lifecycle have run.
+     */
+    private notDirect;
     constructor(config: WorkspaceConfig);
     /**
      * Inject the Chronicle store. Must be called after framework creation.
@@ -141,6 +163,16 @@ export declare class WorkspaceModule implements Module {
      * second. `ensureRunning()` gates on `ctx && mounts-populated`.
      */
     initStore(store: JsStore): void;
+    /**
+     * Whether each mount configured direct runs direct: not while the store
+     * holds changes there that disk lacks, on the branch selected then, so
+     * they stay in view (MountConfig.backend); it runs as 'chronicle' instead,
+     * and ensureRunning says so. Decided when initStore gives the store, and
+     * again at each start, which knows how the mounts nest, so a start that
+     * finds none held starts the mount direct. A path held more than one way
+     * is named for the last way set here.
+     */
+    private chooseKinds;
     /**
      * 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
@@ -154,9 +186,28 @@ export declare class WorkspaceModule implements Module {
      * A mount as observation reads it, with the root identity the workspace
      * recorded for it, if any: what a pass reads beneath (runtime), with
      * rootIdentity's, and what a disk read checks its root against (readRoot),
-     * with rootIdentityForRead's.
+     * with rootIdentityForRead's. A direct mount's has none (diskView).
      */
     private viewOf;
+    /**
+     * A mount's ignore list: its config's, or, for a mount configured direct
+     * that names none, the direct kind's default (MountConfig.ignore), whichever
+     * kind it runs as this session, as its watch mode goes by its config
+     * (watchOf).
+     */
+    private ignoreOf;
+    /**
+     * A direct mount as its tools read it: its view, with no root identity,
+     * since it promises what's at its root now and keeps no evidence to check
+     * that against (MountConfig.backend), and its root as realpath resolves it,
+     * or as given where that fails, as a pass's runtime takes it. The view
+     * reads beneath that root, so a walk, a listing and grep's reads judge
+     * and open their files beneath one root, however its configured path is
+     * repointed meanwhile. A read of one file goes through openContainedFile
+     * instead, which refuses it once its root is no longer the directory it
+     * checked.
+     */
+    private diskView;
     /** The view reconciliation needs of a mount, refreshed per pass. */
     private runtime;
     /**
@@ -168,8 +219,11 @@ export declare class WorkspaceModule implements Module {
      * under that spelling beside their own. So the start stops before a segment
      * spelled any other way, not there, or not a directory, and before a link,
      * which a walk of the whole mount doesn't go through either. It lists only
-     * directories it has checked lie inside the mount, and none the mount
-     * passes over by design, which the walk then answers for.
+     * directories it has checked lie inside the mount, and, on a 'chronicle'
+     * mount, none it passes over by design, which the walk then answers for.
+     * A direct mount walks a path its tools name whatever its ignore list or
+     * an editor's file name covers there (MountConfig.ignore), so there it
+     * lists such directories too, and only another mount's it doesn't.
      */
     private walkStart;
     /** One disk→store pass; the caller holds the mount's turn. Emits its events. */
@@ -217,16 +271,32 @@ export declare class WorkspaceModule implements Module {
     /**
      * Start chokidar watchers and emit workspace:mounted events.
      * Idempotent: safe to call from both start() and initStore(), fires once
-     * per mount regardless of which runs second.
+     * per mount regardless of which runs second. Once both have run, it
+     * decides again which mounts configured direct run direct, now that the
+     * mounts' nesting is known, and says which don't, once for this start.
      */
     private ensureRunning;
+    /**
+     * Say, for whoever runs the host, which mounts configured direct run as
+     * 'chronicle' this session (chooseKinds), what the workspace holds there
+     * that keeps them so, and the two ways to start one direct: on stderr,
+     * and as one ops alert for them all (the framework's failures log, its
+     * `ops:alert` trace and, where one is set, its webhook, which posts one
+     * alert of a kind per cooldown and keeps only the start and end of a long
+     * one). So the words of fixed length, what's happening and the ways out,
+     * come first, and the mounts and what they hold after them.
+     */
+    private sayNotDirect;
     private initialScan;
     stop(): Promise<void>;
-    /** Mount names + modes, for peer callers (framework spill/journal paths)
-     *  that need a writable mount without reaching into private state. */
+    /** Mount names + modes, and each mount's include where it sets one, for
+     *  peer callers (framework spill/journal paths) that need a mount for files
+     *  of their own, the first writable one without an include
+     *  (firstWritableMountName), without reaching into private state. */
     getMounts(): Array<{
         name: string;
         mode: 'read-write' | 'read-only';
+        include?: readonly string[];
     }>;
     getTools(): ToolDefinition[];
     private generatedTextFiles;
@@ -248,8 +318,11 @@ export declare class WorkspaceModule implements Module {
     onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse>;
     /**
      * Resolve a mount-prefixed path (e.g. "tickets/2026-04-22-foo.md") to its
-     * absolute filesystem path. Returns null if the mount is unknown or the
-     * resolved path escapes the mount root.
+     * absolute filesystem path. Returns null if the mount is unknown or
+     * doesn't hold the path: one that leaves the mount's directory, lies in
+     * another mount's directory nested in it, or falls outside its include, or
+     * one that can't name a file of it, with a separator right after the
+     * mount's name or a lone UTF-16 surrogate.
      *
      * **Lexical containment only.** The guard reasons about `..` segments in the
      * path string; it knows nothing about what is on disk. A symlink inside the
@@ -258,6 +331,10 @@ export declare class WorkspaceModule implements Module {
      * path for resolution-only purposes (write targets, nonexistent paths,
      * display); for reading file content, use {@link readFileFromDisk}, which
      * enforces the mount's `followSymlinks` policy and canonical containment.
+     * It judges other mounts' directories by where the last start placed them,
+     * so for a direct mount whose root has moved since, it can differ from
+     * `readFileFromDisk`, which takes the nesting where the root lies now
+     * (movedNesting), about which paths lie in another mount's directory.
      *
      * @deprecated for direct filesystem reads — call `readFileFromDisk()`.
      */
@@ -278,10 +355,13 @@ export declare class WorkspaceModule implements Module {
      * (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.
+     * false with `data: { inChronicle: true }`: its copy on disk was refused,
+     * the store failed after recording the entry, which skips the push where
+     * the mount pushes, 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. A set that threw and couldn't be read back throws, saying
+     * that whether the entry is set isn't known.
      */
     writeBinary(mountPrefixedPath: string, data: Buffer, mimeType: string, options?: {
         branch?: string;
@@ -289,8 +369,10 @@ export declare class WorkspaceModule implements Module {
     private writeBinaryUnderWay;
     /**
      * 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
-     * `read_image` tool and other peer callers that need binary content.
+     * first like the `read` tool; on a direct mount, from disk as
+     * readBinaryFromDisk reads it, at most the mount's `maxFileSize`). Public
+     * API for the framework's synthesized `read_image` tool and other peer
+     * callers that need binary content.
      */
     readBinary(mountPrefixedPath: string): Promise<{
         data: Buffer;
@@ -329,6 +411,8 @@ export declare class WorkspaceModule implements Module {
     } | {
         error: string;
     }>;
+    /** A file's bytes as readBinaryFromDisk reads them, once its path is parsed. */
+    private bytesFromDisk;
     /** The directories of the mounts nested inside a mount, mount-relative, in each spelling. */
     private othersOf;
     /**
@@ -351,17 +435,77 @@ export declare class WorkspaceModule implements Module {
      * as configured still names it as configured (resolveAbsolutePath). A
      * directory not on disk keeps the spellings the roots give alone. Each
      * mount's real root comes back beside the nesting (`reals`), for what
-     * start reads there.
+     * start reads there, and each directory above each configured path with
+     * where it lies on disk (`above`), for a direct mount whose root moves
+     * (movedNesting).
      */
     private readNesting;
-    /** The mounts nested in `mountName`, by directory, name and real root where it has one (MountView's `nested`), in each spelling known. */
+    /**
+     * The mounts nested in `mountName`, by directory, name, real root where it
+     * has one, and include (MountView's `nested`), in each spelling known.
+     */
     private nestedOf;
+    /**
+     * The mounts nested in `mount` as a call of it that resolved its root to
+     * `rootReal` sees them: movedNesting where that differs from where the
+     * last start placed it, the start's placement (nestedOf) otherwise.
+     */
+    private nestedFor;
+    /**
+     * The mounts nested in a direct mount whose root a check resolved to
+     * `rootReal`, where that's elsewhere than the last start placed it, as when
+     * a link it's configured through is repointed; null where the start's
+     * placement holds, or where nothing is at `rootReal`: there the parse's
+     * checks keep the start's placement, and a read says the root is gone. A
+     * direct mount reads beneath whatever directory is at its root, so a check
+     * judges which mount a path is by the root it resolved. A tool's parse
+     * resolves it once, and its respelling and its checks of the path it's
+     * given (parseFilePath's, refusesAsOutside, grep's) read disk beneath that
+     * root and judge by the nesting there. A read and a walk each resolve it
+     * for themselves, and judge the include and the nesting again beneath it.
+     * So a root repointed during a call can change which answer or refusal a
+     * path gets, but nothing a read or a walk serves is a file the include
+     * leaves out, nothing a walk serves lies in another mount's directory as
+     * its own nesting places it, and nothing a read serves lies in the
+     * directory of a mount its own nesting claims by real root. Whoever writes
+     * the disk can race a read in two ways, as a rename during a call can on
+     * any mount. On a disk that folds names, a read judges the include by the
+     * path as its parse spelled it, so a root repointed between the two can
+     * have it serve a file the new root spells otherwise (sameLevels). And a
+     * mount nested by its directories alone, since its real root holds this
+     * one, is judged by the parse's nesting, so a root repointed between a
+     * read's parse and its open can have it serve a path in that mount's
+     * directory. Each mount is placed as a start places it (placementOf), from
+     * where its real root and the directories above its configured path lie on
+     * disk. For a mount configured at this mount's own path or beneath it,
+     * that's where they lie now: beneath `rootReal` where they lie beneath this
+     * mount's path, and the directories above this mount's path as resolving
+     * that path finds them. For any other mount, it's where the last start
+     * found them. Each carries its own include, as nestedOf gives it. It
+     * resolves nothing but the directories on this mount's own configured path
+     * and those beneath its root, so a share elsewhere that doesn't answer
+     * holds only its own calls, unless such a directory is a link into it,
+     * where that mount's files lie. What it leaves to the next start: a mount
+     * configured elsewhere whose own root has moved since, as when a link on
+     * its configured path is repointed, this mount's own reached through
+     * another link among them, that mount's spellings through other links, and
+     * the other mounts' own placements, so a direct root moved into another
+     * mount's directory is that mount's too, as a nested mount's root moved
+     * while running stays placed.
+     */
+    private movedNesting;
     /**
      * The innermost mount nested in `mountName` whose directory holds a path
      * of that mount, judged lexically where the path lands (`.`, `..` and
      * repeated separators resolved, as for the traversal guard; a link of the
      * outer mount isn't followed), with the path to use there; undefined when
-     * no nested mount's directory holds it.
+     * no nested mount's directory holds it. A path parsePath has respelled is
+     * compared with the directory's spellings exactly. One judged as given
+     * (`asGiven`, resolveAbsolutePath's) is compared loosely, as a disk that
+     * folds names may compare it (beginsWithDir), so it can't reach that
+     * mount's directory by spelling a segment otherwise. On a disk that tells
+     * names apart, that takes a directory of this mount's own spelled like the
+     * nested one in another way as that mount's too.
      */
     private holderOf;
     /**
@@ -372,41 +516,119 @@ export declare class WorkspaceModule implements Module {
     private otherMountNote;
     /**
      * parsePath for the file operations (read, write, edit, delete, and the
-     * module's binary and disk reads and writes). A path in another mount's
-     * directory nested in this one is that mount's: this mount's passes don't
-     * observe it and its pushes don't write it, so its file operations refuse
-     * it, naming the innermost mount that holds it and the path to use there.
+     * module's binary and disk reads and writes), refused where the mount
+     * doesn't hold the path. A path in another mount's directory nested in
+     * this one is that mount's: this mount's passes don't observe it and its
+     * pushes don't write it, so the refusal names the innermost mount that
+     * holds it and the path to use there. A path the mount's include doesn't
+     * cover is outside the mount, whatever disk or the workspace's history has
+     * there. A directory is checked the same way, since a path can be a
+     * directory on one side and a file on the other.
      */
     private parseFilePath;
     /**
      * The refusal for a path of `mount` that reaches a nested mount's directory
-     * through a symlink on its way (nestedAtReal), or null where it doesn't. On
-     * a mount that doesn't follow the link, the refusal is the link's own
-     * (linkWords), as the readers and pushes give it. A mount with nothing
-     * nested has nothing to find, so it pays nothing.
+     * through a symlink on its way (nestedAtReal), or a file this mount's own
+     * include leaves out (coversLanding), or, on a mount that follows links
+     * with an include, one realpath can't resolve, or null where it doesn't.
+     * On a mount that doesn't follow the link, the refusal is the link's own
+     * (linkWords), as the readers and pushes give it. On one that does, it
+     * names the nested mount only where the place is that mount's
+     * (namesNestedPlace); anywhere else the place is no mount's, so the path
+     * leaves this one, in the disk readers' words, as it does where it lands
+     * on a file this mount's include leaves out. A mount with nothing nested,
+     * and without both an include and links followed, has nothing to find, so
+     * it pays nothing. The caller gives the nesting and the root to judge by
+     * (`nested`, `root`). A direct mount's file operation gives those its
+     * parse found, so where the path lands, and any link on its way, is judged
+     * beneath the root that parse resolved; any other caller gives the start's
+     * nesting and the configured path.
+     */
+    private landingRefusal;
+    /**
+     * A parsed path, refused where the mount doesn't hold it: in a nested
+     * mount's directory first, naming the mount that holds it, then outside
+     * the mount's include. Each is judged on the path as the caller parsed it:
+     * as disk spells it for parseFilePath, as given for resolveAbsolutePath,
+     * which is synchronous and says so (`asGiven`, so the nested-mount check
+     * folds where disk does). The include's refusal shows the path as given
+     * (`given`), since it answers the path the caller asked about.
+     */
+    private refuseNotHeld;
+    /**
+     * Whether a mount-relative path names a file, as grep decides what a path
+     * it's given names: for a path the include covers, a file in the
+     * workspace's history, or anything but a directory on disk. Grep takes it
+     * as a directory only when neither side has a file there, and filters what
+     * it finds beneath it by the mount's include. A path the include doesn't
+     * cover names no file of the mount's, whatever disk or history holds
+     * there, so one refusesAsOutside lets through is a directory. A direct
+     * mount has no history: what a run of it as 'chronicle' left in the store
+     * isn't its own, so disk alone decides. Disk is read beneath `root`: a
+     * direct mount's is the root its parse resolved, a store-backed mount's
+     * its configured path.
+     */
+    private namesFile;
+    /**
+     * Whether sync, materialize, grep, glob or ls refuses a path it's given as
+     * outside the mount's include. A path the include doesn't cover is a scope
+     * exactly where a listing names a directory: where disk has a directory
+     * reached from the mount's root through directories, with no link among
+     * them, or the workspace's history holds an entry beneath it that's the
+     * mount's own to list (withinIncludes). The one exception is a directory
+     * the ignore list covers, which a listing passes over and which is still a
+     * scope when it's named, since a sync that names it takes in what's there
+     * (#276). Anything else is refused, a file at the path included, which no
+     * scope tool takes up. The walk descends no link it meets. Where covered
+     * history makes a name a scope and disk has since put a link there, a
+     * mount that doesn't follow symlinks refuses the link, as it refuses any
+     * link on a path's way, and on a mount that does, a pass of the scope
+     * follows the link, and its answer shows whether the link leads out of the
+     * mount. A
+     * path in another mount's directory nested in this one is that mount's,
+     * whatever this mount's include says, so it isn't refused here: each tool
+     * names the mount that holds it, as the file operations do. A direct mount
+     * has no history, as namesFile says, and is judged beneath the root its
+     * parse resolved (`root`), by the nesting there (`moved`, movedNesting).
      */
-    private leadsIntoNested;
-    /** A parsed path, refused if it lies in a nested mount's directory (parseFilePath). */
-    private refuseNested;
+    private refusesAsOutside;
     /**
      * Parse a mount-prefixed path into its mount and mount-relative path, as
-     * disk spells it (diskSpelling), with `path` the mount-prefixed path so
-     * spelled. On a disk that folds names, a path spelled otherwise reaches
-     * disk's file, so every tool takes it by disk's name: one name per file,
-     * and the names its answers give are disk's, except that a path that names
-     * a workspace entry exactly, or does once its directories take disk's
-     * spelling, keeps the entry's spelling. A path the workspace records an
-     * intent at, such as a deletion disk hasn't been given yet, counts as an
-     * entry here, so the calls that settle it reach it. The workspace's
-     * entries (entriesOf) stand in for disk where it has nothing yet, so a
-     * draft has one name too. Neither applies to a path that disk's spelling
-     * puts in a nested mount's directory.
+     * disk spells it (diskSpelling). `path` is the mount-prefixed path in that
+     * spelling where it differs from the one spelling, and otherwise the path
+     * as the caller gave it. The path is read in its one spelling first
+     * (parsePathAsGiven), so the respelling only ever sees a path with no
+     * empty, `.` or `..` segment and no separator before its first. On a disk
+     * that folds names, a path spelled otherwise reaches disk's file, so every
+     * tool takes it by disk's name: one name per file, and the names its
+     * answers give are disk's, except that a path that names a workspace entry
+     * exactly, or does once its directories take disk's spelling, keeps the
+     * entry's spelling, and what lies past a link on the way keeps the
+     * caller's, since the step reads nothing past a link. A path the workspace
+     * records an intent at, such as a deletion disk hasn't been given yet,
+     * counts as an entry here, so the calls that settle it reach it. The
+     * workspace's entries (entriesOf) stand in for disk where it has nothing
+     * yet, so a draft has one name too. Neither applies to a path that disk's
+     * spelling puts in a nested mount's directory. A direct mount holds no
+     * entries, so its paths take disk's spelling alone. Past a nested mount's
+     * directory the path stays as given, since what lies there is that mount's
+     * to name. Every answer shows `path`, a name the include leaves out
+     * included, since how disk spells a name the caller gave is no content of
+     * that file, except the include's own refusal, which shows the path
+     * exactly as given (refuseNotHeld), since it answers the path asked about.
      * A handler that must read something at the moment it's asked, as
      * handleSync reads the branch a path sync adopts on, reads it before
-     * calling this, since this awaits disk. The entries are read when the
-     * step needs them, some after those awaits, from the branch current then.
+     * calling this, since this awaits disk. The entries are read when the step
+     * needs them, some after those awaits, from the branch current then.
      */
     private parsePath;
+    /**
+     * How many segments the innermost nested mount's directory that holds
+     * `relativePath` has, in a spelling it's known by (othersOf), or, for a
+     * direct mount whose root has moved, in the nesting there (`moved`);
+     * undefined when no nested mount's directory holds it.
+     */
+    private nestedDepth;
     /**
      * A mount's entries on the current branch, and the paths it records an
      * intent at there, as diskSpelling reads them when it does, whether its
@@ -418,7 +640,19 @@ export declare class WorkspaceModule implements Module {
      */
     private entriesOf;
     /**
-     * Parse a mount-prefixed path into (mountName, relativePath), as spelled.
+     * Parse a mount-prefixed path into its mount and the one mount-relative
+     * path every later step reads, as given, before disk's spelling
+     * (parsePath): `/` between segments (`\` read as `/` where it's the
+     * platform's separator), with no empty or `.` segment and no trailing `/`,
+     * and '' for the mount's root. So the traversal guard here and every later
+     * step judge one spelling of the path, which parsePath then respells name
+     * by name as disk lists them. A `..` segment takes back the segment before
+     * it, before anything looks the path up, so a mount's include judges the
+     * path every tool acts on, and one with nothing left to take back climbs
+     * above the mount's root and is refused, whatever it reaches afterwards. A
+     * separator straight after the mount's name would make the rest an
+     * absolute path, so that is refused too, and every reader that takes a
+     * path refuses it here, a disk reader included.
      */
     private parsePathAsGiven;
     /**
@@ -448,6 +682,8 @@ export declare class WorkspaceModule implements Module {
      * which answers while the evidence awaits reopening; where even it can't
      * be read, as when the evidence was never read back whole, the read is
      * refused too, with an errno only where no directory is at the root's path.
+     * A direct mount's root is checked against no identity, and its read reads
+     * no evidence: it promises what's at its root now (diskView).
      */
     private readRoot;
     /**
@@ -455,7 +691,9 @@ export declare class WorkspaceModule implements Module {
      * with the code and errno readRoot gives what is at its path now (its stage
      * and words are this check's): gone, or not a directory, with ENOENT or
      * ENOTDIR, so a caller reads a root gone mid-read as one gone before it; or
-     * another directory, with none.
+     * another directory, with none. A direct mount reads whatever directory is
+     * at its root (MountConfig.backend), so for it, another directory there is
+     * one the next read reads.
      */
     private rootMoved;
     /**
@@ -469,7 +707,8 @@ export declare class WorkspaceModule implements Module {
      *    among the directories on its way beneath the mount's root, wherever it
      *    leads (linkOnTheWay), before anything resolves it: as `escape` for a
      *    link leading outside the mount, as `other_mount` for one into a nested
-     *    mount's directory, and as `parent_symlink` for any other.
+     *    mount's directory where its refusal names that mount, and as
+     *    `parent_symlink` for any other.
      * 2. `lstat` the lexical path — refuse directories; refuse a final-component
      *    symlink when the mount does not `followSymlinks`; refuse anything else
      *    that isn't a regular file, such as a FIFO, without opening it.
@@ -518,7 +757,9 @@ export declare class WorkspaceModule implements Module {
      * - Once the workspace has recorded the mount root's identity, with the
      *   first evidence it gathers there, a root that is another directory is
      *   an unavailable mount: a replaced directory, a link swapped in for it,
-     *   or an unmounted drive's mountpoint. In any mount, recorded or not, a
+     *   or an unmounted drive's mountpoint. A direct mount's reads check no
+     *   recorded identity: they read beneath whatever directory is at its
+     *   root (MountConfig.backend). In any mount, recorded or not, a
      *   root that stops being the directory the read checked until the file
      *   has been opened and checked is unavailable too: with ENOENT or
      *   ENOTDIR where no directory is there, as before the read, and with no
@@ -526,9 +767,10 @@ export declare class WorkspaceModule implements Module {
      *   the descriptor that was checked.
      *
      * Throws {@link WorkspaceReadError} with a `code` distinguishing unknown
-     * mount, lexical traversal, a path in another mount's directory nested in
-     * the one named (`other_mount`), unavailable mount, missing or non-regular
-     * file, directory, policy-denied symlink, outside-mount target, and
+     * mount, lexical traversal, a path the mount's include doesn't cover
+     * (`outside_include`), a path in another mount's directory nested in the one named
+     * (`other_mount`), unavailable mount, missing or non-regular file,
+     * directory, policy-denied symlink, outside-mount target, and
      * file-changed-during-read.
      */
     readFileFromDisk(mountPrefixedPath: string, options?: ReadFileFromDiskOptions): Promise<WorkspaceDiskReadResult>;
@@ -543,9 +785,11 @@ export declare class WorkspaceModule implements Module {
     /**
      * 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; for a
-     * deletion, a tombstone, unless the evidence holds no agreed disk copy (P
+     * deletion, a tombstone, written before the entry is removed, unless the
+     * agreement's evidence for the path, P, holds no agreed disk copy (P
      * absent, or no P and store origin), when it clears the path's intent and
-     * pushes nothing. It pushes the change to disk when the mount opts in via
+     * pushes nothing. It pushes the change 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
@@ -562,6 +806,24 @@ export declare class WorkspaceModule implements Module {
      * the path, as an edit makes).
      */
     private commitToolChange;
+    /**
+     * commitToolChange for several paths of one mount at once, as edit_many
+     * commits its files: every path's precondition is enforced before any entry
+     * is set, then a deletion's tombstone is written, then every entry is set
+     * in one record of the store, which takes all of them or none, then each
+     * other path's intent, by the rule commitToolChange's doc gives, which the
+     * code below applies, with no await between, and one push takes the paths
+     * to disk, but for a deletion that clears its path's intent. `onCommitted`
+     * is told of each path once the entries are set, also when the store throws
+     * after setting them, whose error then goes on in place of the push
+     * (changesLanded).
+     * Answers, by path, the reason for each that reached the workspace but not
+     * disk (`refused`), and, apart from it, why one whose bytes reached disk
+     * left the file's mode as disk had it (`modeKept`), and that a deletion
+     * clearing a conflict that named a disk file unlinked nothing (`notes`), as
+     * commitToolChange answers them for one path.
+     */
+    private commitToolChanges;
     /**
      * 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
@@ -581,20 +843,176 @@ export declare class WorkspaceModule implements Module {
      * path, as a file tool names the one it acts on: a path the mount passes
      * over by design is observed, as a sync naming it would observe it (#276),
      * while a path in another mount's directory is refused before this, and
-     * passed over by any pass. The caller holds the mount's turn.
+     * passed over by any pass. Answers the pass's report on the path, and why
+     * the pass decided nothing where it did (undecidedOf), which leaves disk
+     * unchecked. The caller holds the mount's turn.
      */
     private ensureSynced;
+    /**
+     * Why the workspace holds no entry at a path, after a pass over it that
+     * decided nothing: disk wasn't checked, so it may have a copy, and the same
+     * call made again checks it.
+     */
+    private notCheckedYet;
     /** Why the workspace holds no entry at a path, when disk explains it. */
     private notInWorkspace;
+    /**
+     * A file's bytes for read, from where the mount keeps what it reads: the
+     * workspace's copy, taken in from disk first where it holds none
+     * (ensureSynced); or, on a direct mount, disk's file as it is now
+     * (bytesOnDisk). An error says why there are none to read.
+     */
+    private bytesOf;
+    /**
+     * A direct mount's file for read: its bytes on disk as they are now,
+     * through the mount's boundary as readFileFromDisk reaches them
+     * (openContainedFile), whose refusals are the answer. What a 'chronicle'
+     * mount never stores, it doesn't show either: a file over the mount's
+     * size limit, and a binary one, with a NUL in its first 8 KB, which
+     * read_image reads where it's an image.
+     */
+    private bytesOnDisk;
     private handleRead;
     private handleReadImage;
     private handleWrite;
     private handleEdit;
+    private handleEditMany;
+    /**
+     * A call's edits, all or none, applied to the stored copies of their files:
+     * edit's one, or edit_many's in the files of one mount. Each edit is matched
+     * in its file's text as this call reads it, never in another edit's result
+     * (edit-plan.ts), and any problem refuses the call with none of its edits
+     * stored: edit names its first problem, and edit_many every problem found.
+     *
+     * Each edit's own input is checked first, and each path's mount. A problem
+     * there refuses edit at once, before any file's text is read, and edit_many
+     * when its edits name more than one mount, which no one pass settles.
+     * Otherwise edit_many goes on to settle and plan the rest, so its one
+     * refusal names the problems it finds; the settling is what a read or a
+     * listing of its files would take in from disk, and the refusal says what
+     * it took in. A failure before the commit sets the entries stores none of
+     * them, and edit_many's answer to it says so. A store that throws as it
+     * sets them is read back (commitToolChanges), so the answer says they're
+     * stored where its record landed, and that it can't tell where they
+     * couldn't be read back.
+     * Under the mount's turn, one pass settles every path with disk, by the
+     * rule a listing uses, so the edits apply to what disk now holds. That pass
+     * is the only step that awaits before the commit: every file is then read,
+     * every edit planned, and every entry set (commitToolChanges) with no turn
+     * of the event loop between, so no pass, branch change or other call moves
+     * the tree between a file's read and its set. Disk then takes what it can
+     * of the stored change.
+     *
+     * The answer is held to `maxChars`, the length the call's result may have
+     * (ToolCall.resultMaxChars), as edit-text.ts describes.
+     */
+    private applyEdits;
+    /**
+     * Where an edit's path is in its mount, or why the call can't edit it: a
+     * path no mount holds, one outside its mount or holding a lone surrogate
+     * (parsePath), one a nested mount holds or that leads into one through a
+     * link (parseFilePath), a path that names its mount's root, a read-only
+     * mount, or for edit_many a generated file. edit's
+     * generated file is refused before it gets here, by the same rule
+     * (handleToolCall checks a call's `path`, which edit_many's input lacks).
+     */
+    private editablePath;
+    /**
+     * Why a call can't change a generated file: another agent's is that agent's,
+     * and the agent's own is read-only, since it shows the agent's tool
+     * presentation, which set_tool_visibility and set_tool_description change.
+     */
+    private generatedFileRefusal;
+    /**
+     * The answer to edits stored but not finished: the commit set every file's
+     * entry, and then disk refused some of their pushes, or the store failed
+     * after recording them, so their push didn't run, or the rest of the call
+     * failed. It stays an error, since part of the call failed, and leads with
+     * what is stored, which must not be sent again: a second call can apply
+     * those edits twice. edit's is the answer write and delete give, one path's;
+     * edit_many's lists the files disk refused, each with its push's reason,
+     * notes each file disk took with its mode left as disk had it, as the
+     * success answer's `modeKept` does, within `maxChars`, and never says to
+     * send the call again. Where the store failed after recording the edits,
+     * which stand as on a success, it names each conflict the success answer
+     * would (`conflicts`, found only where the mount doesn't push).
+     */
+    private editsStoredButUnfinished;
     private handleDelete;
     private handleLs;
+    /**
+     * What a listing shows of a directory scope, from where the mount keeps
+     * what it reads: the store-backed kind's pass (listingFromStore), or, on a
+     * direct mount, disk (listingFromDisk). `keep` chooses the files shown.
+     */
+    private listingOf;
+    /**
+     * A 'chronicle' mount's listing: a pass over the scope under the three-way
+     * rule, each path it decided with its state, and the directories beneath
+     * the scope that disk or the workspace has.
+     */
+    private listingFromStore;
+    /**
+     * A direct mount's listing: its walk of the scope (diskWalk), with each
+     * entry it took as disk has it now, observed as a pass observes it: a
+     * file's size, or why the mount doesn't take it (a link it doesn't follow,
+     * one that leaves the mount, what isn't a regular file). A file gone since
+     * the walk listed it is no longer there to show.
+     */
+    private listingFromDisk;
+    /**
+     * A direct mount's walk of a scope, from its view (diskView): the entries
+     * it took that aren't directories (files, links and the like), in path
+     * order; the directories directly beneath a scope it doesn't descend; and
+     * the regions it couldn't see that a pass reports beside no tracked file:
+     * what it couldn't list, what the cap left, and a scope in another mount's
+     * directory, said as a listing says it. A path the walk names is walked
+     * whatever the mount's ignore list or an editor's file name covers there
+     * (MountConfig.ignore), as a path sync's walk is.
+     */
+    private diskWalk;
     private handleGlob;
     private handleGrep;
+    /**
+     * The texts a 'chronicle' mount's grep searches beneath `start`, or in the
+     * single file `relativePath` names, those `keep` lets through, each handed
+     * to `each` in path order: a pass over the scope, then each path's
+     * workspace copy, labelled with its state, and a conflict's disk side.
+     * What it doesn't search is in `skipped`, and what it couldn't see in
+     * `incomplete`, each mount-prefixed.
+     */
+    private textsFromStore;
+    /**
+     * The texts a direct mount's grep searches beneath `start`, or in the
+     * single file `relativePath` names, as namesFile judges it beneath `root`,
+     * the root grep's parse resolved, those `keep` lets through, each handed
+     * to `each` in path order: each file its walk took (diskWalk), read from
+     * disk as it is now, DIRECT_READS_AT_ONCE at a time. A file over the size
+     * limit, a binary one and one the mount doesn't take are in `skipped`,
+     * each with why, as a 'chronicle' mount's grep lists what it never stored;
+     * one gone since the walk listed it isn't there to search.
+     */
+    private textsFromDisk;
     private handleStatus;
+    /**
+     * What the store holds of a mount that disk lacks, on the selected branch,
+     * among the mount's own paths. Status counts the first three as pending:
+     * recorded conflicts; workspace deletions, pending until a push confirms
+     * them on disk (left there without applyDeletions, or unlinked but
+     * unconfirmed); and what disk owes by the evidence (entriesByEvidence's
+     * `owed`: every entry it doesn't show on disk, a refused or failed push's
+     * included). An entry from before the evidence isn't among them until a
+     * listing or a materialize checks it: unchecked isn't unpushed. A
+     * tombstone beside an entry that's still there, left by a deletion or a
+     * write that stopped partway (commitToolChanges), is no deletion: it holds
+     * no change disk lacks, and its entry is judged by the evidence as any
+     * other is. The fourth, intents that can't be read, may hold a deletion
+     * or a conflict, so a mount configured direct counts them too (initStore).
+     * Each lies where the mount's include covers, as status counts them: what
+     * the workspace's history holds outside it is no change of the mount's,
+     * and no push writes it to disk (pushUnlocked).
+     */
+    private heldChanges;
     /**
      * What a materialize of `mount` should consider: a named file, or every
      * tracked path beneath a named directory; otherwise what the evidence says
@@ -610,10 +1028,11 @@ export declare class WorkspaceModule implements Module {
     /**
      * Whether a path of the mount is its own to push and to count as owed:
      * not in another mount's directory nested in it. Copies the mount's tree
-     * holds there (stored before the nesting) stay in its history and its
-     * listings (and in status's fileCount, which counts the tree), passed over
-     * by its syncs, and left out of what it pushes and of status's pending
-     * changes, conflicts and workspace deletions.
+     * holds there (stored before the nesting) stay in its history, and in its
+     * listings and status's fileCount where that mount's include covers them
+     * (withinIncludes). Its syncs pass over them, and
+     * they're left out of what it pushes and of status's pending changes,
+     * conflicts and workspace deletions.
      */
     private ownPaths;
     /**
@@ -649,6 +1068,9 @@ export declare class WorkspaceModule implements Module {
      * 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.
+     * A path outside the mount (insideMount), such as one its include doesn't
+     * cover, is no pass's to decide (gather), so a batch of nothing else takes
+     * no turn of the mount.
      */
     private handleFsChanges;
     /**
@@ -695,4 +1117,13 @@ export declare class WorkspaceModule implements Module {
      */
     private emitFsEvents;
 }
+/**
+ * Run `work` on each item, at most `width` at once, and hand each result to
+ * `each` in the items' order, as soon as it and those before it are done.
+ * A result handed on is let go, so what's held at once is at most `width`
+ * results, as a direct grep's file contents are. A `work` that rejects
+ * rejects this when its turn comes; any started after it finish unheard.
+ * Exported for its tests.
+ */
+export declare function inOrder<T, R>(items: readonly T[], width: number, work: (item: T) => Promise<R>, each: (result: R, item: T) => void): Promise<void>;
 //# sourceMappingURL=index.d.ts.map