[nissa-seru]

A workspace mount can now name the files it holds with include, in the pattern forms ignore takes, read for files. A file it doesn't cover is outside the mount. No tool reads or writes it, and nothing takes it into the workspace's history, so a host can version only the files it owns. connectome-host needs this for its _config mount, which versions the host's config files and should hold only those (anima-research/connectome-host#278). On every mount, it also makes each tool read a path in one spelling, which fixes the two issues below.

Fixes #351.
Fixes #471.

Problem

A mount versions everything under its path that ignore doesn't cover, and ignore holds only for the passes that name no path: a sync without one, and the watcher's. On main, with ignore: ["*.bak"], a sync naming work/gate.json.bak takes the file in, the agent's read reads it and its write of work/new.bak versions that, and after a branch switch materializeMount writes back an ignored file the workspace's history held from before the ignore (each run on main, below). An ignore list also can't name every file a host should leave alone. Its patterns are names, *.ext and dir/**, so it names no family of files by a common prefix, such as the owner-only gate.json.unreadable-<suffix> copies #371 adds, and it can't name a file nobody expected. Editors' swap and backup files are already passed over on every mount (#460).

Changes

• MountConfig.include takes patterns in ignore's forms, read for files. A name or an *.ext glob covers a file by its own name, at any depth, and a dir/** glob covers what lies beneath that directory, and not a file named like it. Unlike ignore, a pattern that matches a directory's name covers nothing beneath it, since each file is covered by its own name: include: ["gate.json"] holds every file named gate.json, and no other file beneath a directory of that name. Left out, nothing changes. The module refuses a bad include when it's created, naming the mount and the pattern: an empty list, or an entry the matcher can't read, meaning one that isn't a string, a path with / that isn't a dir/** glob, a * anywhere but a leading *., an empty, . or .. segment, or a \ where it's the platform's separator, as on Windows. Any other pattern is a file name, matched literally, as ignore reads its patterns, so [id].tsx names the file of that name.
• What it guarantees is content. No workspace path reads, stores, serves or writes back a file the include leaves out, including one in a nested mount's directory that mount's include leaves out, and no tool lists, matches or names one. A refusal may show that something occupies a path the caller named. On a mount that follows links, it may also say whether that path leads out of the mount or into a nested mount that covers it, with the path to use there. A link the include covers is described as on any mount, its target included unless that's a file the include leaves out. Otherwise, a refusal names nothing the include leaves out beyond the path the caller gave, which it may spell as disk does, and on a mount that doesn't follow links, it tells nothing of where a link the include leaves out leads. Whether a name is taken isn't withheld, and a sync's passedOver counts what it passed over. Outside the mount:
  • a walk passes over it, counting it under passedOver as "outside the mount's include";
  • no pass decides it, whether the walk, the watcher's changes or the tracked lists name it, so history from before the include stays as it was. A watcher's batch of changes with nothing else in it takes no turn of the mount;
  • materializeMount and materialize never write it back, even when the workspace's history holds it. A materialize naming a directory inside the mount counts each such entry beneath it under passedOver, with that reason and without its path, a deletion or conflict held there included, while one of the whole mount leaves those alone and uncounted, as status doesn't count one;
  • read, read_image, write, edit, edit_many, delete, readBinary, writeBinary, readBinaryFromDisk and readFileFromDisk refuse any path the include doesn't cover, a directory's included, since a path can be a directory on one side and a file on the other. They say it's outside the mount's include, and that calling again changes nothing, since the host's operator sets the include in the mount's configuration (readFileFromDisk's new error code is outside_include);
  • resolveAbsolutePath returns null for such a path, as for one that leaves the mount;
  • a sync, materialize, grep, glob or ls that names a path the include doesn't cover takes it as a directory, its scope, exactly where a listing names one: 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 the include covers, and that a nested mount's include covers too where it lies in that mount's directory. A directory ignore covers is a scope too when it's named, though a listing passes over it, as a sync that names it takes in what's there. Each refuses any other path the include doesn't cover. A covered path is a file to a sync, materialize or grep when disk or history has a file there, and otherwise a directory; a glob takes its path as a directory, as on main. Beneath a directory, each passes over what the include doesn't cover;
  • the mount's status counts only what's inside, and every listing shows only covered files. An ls that isn't recursive names each directory directly beneath its path that disk has, the ignore list's aside, and each that a covered entry in the workspace's history implies, but none that only history outside the include implies, and nothing beyond a link, since the walk descends none. ls without a path lists each mount's include.
• One spelling of a path, for every mount. The tools read a path after its mount's name one way: / between segments, \ too on Windows, no empty or . segment and no trailing /, and a .. takes back the segment before it. One with nothing left to take back climbs above the mount's root and is refused, whatever it reaches afterwards, a path that comes back in by the mount directory's own name included, which main's traversal guard let through. There readFileFromDisk and resolveAbsolutePath reached the file, and the other tools failed with the store's "Invalid tree path". Its refusal says climbs above the root of mount "work"., where main said resolves outside mount "work" for a climb that left the mount. A separator straight after the mount's name is refused too, since it would make the rest an absolute path. So on Linux and macOS, the include, the workspace's history, the walk, the traversal guard and the disk all judge one string. Windows trims a last segment's trailing spaces and periods and reads a : in a segment as a drive or a stream, which this change leaves as main has it (Not verified, below). On a mount without an include, this changes the entry history keeps for work/a//b.txt to a/b.txt, the file the disk operation already reached, where main kept the spelling as written (Workspace: a path with an empty segment is a second tree entry for the same disk file #471), and work/./a.txt or work/sub/../a.txt, whose writes failed with the store's "Invalid tree path", now name a.txt, as a glob or grep naming work/src/../src or work/./src, which failed the same way, now searches src. A sync naming work/d/ records what it takes in as d/a.txt, where main recorded d//a.txt (workspace: sync of a directory path with a trailing slash records its files as d//a.txt #351), and a materialize naming work/docs/ takes docs, where main found nothing. edit and edit_many read a path this way too, so feat(workspace): port hands-mcp's edit planner, and add edit_many, several edits stored all or none #463's refusal of a path not spelled plainly goes, since its reason was that the workspace kept an entry for each spelling. Each spelling now edits the one entry, and two spellings in one edit_many call are one file, planned once. A path that names the mount's root is still refused.
• A key no spelling names is outside the mount. Because main kept a path as written, a store can hold a//b.txt or c/. Such a key is outside the mount. No tool lists, counts, syncs or writes it, and since no spelling names it, a materialize doesn't count it. History keeps it as it was. Where such a write reached disk, the file is the one its new spelling names, and the next sync of the mount takes it in. A draft written under such a key that hadn't reached disk when the host upgrades stays in history and never reaches disk, and workspace-path-spellings.breaking.md says how to recover it.
• Directories are walked unless ignore covers them, and ignore still applies to what include covers.
• The framework keeps its own files (tool-results/, refs/, background-scripts/) in the first read-write mount without an include, since a mount with one would refuse them. A setup whose only writable mount has an include is treated as having none, which each of those three already handles, and the over-cap notice, the background-script log text and the log line for a fetched reference it can't store say there is no writable mount without an include. getMounts() reports a mount's include for this. What the framework kept in a mount before the mount had an include is outside it once it has one, unless the include covers it, so a read of a path an earlier spill note or reference gave is refused.
• Links. On a mount that follows symlinks, a path is judged where it lands as well as where it's named, as disk spells it there: a link at a covered path or among its parent directories is followed while what it reaches is a directory or a file the include covers. A covered path whose landing realpath can't resolve, as for a loop, more than 40 links or a directory this process can't search, is refused by read, write, delete and readFileFromDisk, and by our reading by every other file tool, which parse a path the same way, as Unable to resolve file: <path> with code not_found, the words a disk read gives such a path, since where it lands can't be judged: history taken in through it before the include isn't served, and nothing is written through it. A covered path that reaches a file the include leaves out is refused as one that leaves the mount, in the words a place a nested mount's include leaves out gets: the file tools refuse it before anything is stored, and they and readFileFromDisk answer Symlink escape detected: <path>, code escape. A listing from where a link leads passes over such a file, and nothing a materialize writes through that path reaches disk, a file it would create included. So with include: ["docs/**"], where docs is a link to site/docs, every file beneath docs/ lands beneath site/docs/, which docs/** doesn't cover, and the mount holds none of them unless the include names site/docs/** too. On one that doesn't, a link on a path's way is refused, as on any such mount. Its refusal names an inside target only where the include covers the link and a tool could name the target: a directory, or a file the include covers. A link the include doesn't cover is outside the mount itself, so its refusal names only the link, with nothing of where it leads, and readFileFromDisk gives it the code of a link the mount doesn't follow where it stands, whatever it leads to: parent_symlink on the path's way. A link the include covers, at the path itself, gets symlink, however the path is spelled, except one into a nested mount's directory whose refusal names that mount, which gets other_mount. On a mount that follows links, a link the include doesn't cover that leads to a directory is passed over with the reason a mount without an include gives a link, "a symlink, not walked", since a name or an extension glob can cover what lies beneath it and what's read through it is judged by its path and where it lands, and history beneath it is unverified for that reason, while a link to a file, or one that leads nowhere, is outside the include by its name. On one that doesn't, every link the include doesn't cover gets that reason, since nothing reads through one there, and such a mount resolves none to tell where it leads.
• History in a nested mount's directory that the outer mount took in before that mount was nested there, and that mount's include leaves out, is inert history: no pass decides it, and no listing, sync or grep names it.
• A path in another mount's directory nested in this one is that mount's, whatever this mount's include says. Every tool names the mount that holds it and the path to use there, as main does on a mount without an include, so a file there that the include doesn't cover gets that answer rather than the include's refusal. Past that directory, an answer shows the rest of the path as given. Through a link this mount follows, main refuses a path that reaches such a directory, naming that mount and the place the path reaches there. Here it names them only where that place is a directory, or a file that mount's include covers with no file on its way; otherwise no answer names that mount or the place, and the file tools and readFileFromDisk refuse the path as one that leaves the mount (Symlink escape detected: <path>, code escape). On a mount that doesn't follow the link, readFileFromDisk's code is other_mount only where the refusal names that mount. A walk passes over that directory by its real path, and by which directory it is, as well as by its spelling, so a walk through a link to a directory above it lists none of that mount's files. main's walk listed them there as unverified entries, with or without an include. A push asks where a file lies before it reads it for a hash, as well as after, so it reads no file in such a directory.
• On a disk that folds names, as macOS's does by default, a path is judged as disk spells it, as the walk judges what it lists. So a covered name whose file disk spells otherwise, such as gate.json where disk has GATE.JSON, is outside the mount, and its refusal shows the path as given, which names nothing the caller didn't. A path that names one of the workspace's entries exactly, or does once its directories take disk's spelling, keeps the entry's spelling, as main's parse gives it, and what lies past a link on a path's way keeps the caller's spelling, since the parse reads nothing past a link. Otherwise answers name a path in disk's spelling, a name the include leaves out included, since how disk spells a name the caller gave is no content of the file. Only the include's own refusal shows the path exactly as given, even where the parse respells it, since it answers the path asked about. A link's target is judged and named as disk spells it. resolveAbsolutePath is synchronous and judges the include on the path as given, following no link, so on such a disk it reaches a covered name's file that disk spells otherwise, which the tools refuse and the walk passes over, and it's null for a covered file named in another case, which the tools read. It compares a path with a nested mount's directory loosely, in case and Unicode normalization, as a disk that folds names may, so it gives null for any spelling that may reach that directory. On a disk that tells names apart, that includes a directory of the outer mount's own spelled like a nested one in another case.
• Four cases fall outside the guarantee, as for any nested mount, since a nested mount's root is placed where disk has it at each start, and its directory is matched by spelling. On a disk that folds names, a mount configured through a link that spells a directory otherwise than disk does isn't found nested, and the outer mount holds its files as its own. On such a disk, a path through a link of the outer mount that spells a nested mount's directory otherwise than that mount's configured path does, whether the link or the configured path is the one spelled otherwise than disk, isn't found to lead there, and the outer mount reads, lists, searches and writes there as its own, creating files too, though a walk from its root passes over the directory. On such a disk, a place in a nested mount's directory that a link does lead to is judged by that mount's include, and named, in the spelling the link's target gives, so a refusal can name a file disk spells outside that include, or leave a covered one unnamed. And a nested mount whose root moves while running, as acceptRoot takes, stays placed where it was until the next start. Each is a way round the nested mount's include. Finding nesting by identity would close the first three, and acceptRoot reading the nesting again the fourth, all in the nested-mount code main has.
• docs/tool-presentation.md now says that on a disk that folds names, the tool catalogue answers only under its exact spelling, and a write under another spelling writes the ordinary file at that name on disk, which any agent can read under that spelling. This change leaves that as main has it.
• Changelog fragments: mount-include.added.md, workspace-path-spellings.fixed.md and workspace-path-spellings.breaking.md, whose operator-facing part names who must act. workspace-link-into-nested-code.fixed.md corrects a line of 0.23.0's notes: a file that is itself a link into a nested mount's directory gets other_mount from readFileFromDisk, as 0.23.0 already does, not symlink. The edit planner's two pending fragments drop the refusal of a path not spelled plainly.

Without include, a mount changes in reading each path in one spelling, and in a walk through a link to a directory above a nested mount's, which no longer lists that mount's files. Two tests in connectome-host's test/identity-and-surfaces.test.ts pinned main's answers there, and anima-research/connectome-host#331, merged, changed them to hold with this change and with 0.22.2. anima-research/connectome-host#335, merged, keeps connectome-host's mount-key checks typechecking against this change's MountConfig by leaving include out of them, so a recipe's include is still refused as an unknown key. A host that sets an include also meets readFileFromDisk's new code, outside_include, and a null from resolveAbsolutePath for a path the include doesn't cover, as for one that leaves the mount. connectome-host's step that takes this release and gives _config an include is anima-research/connectome-host#337.

What each part is for

It exists so a mount can name the files it holds, as connectome-host's _config should hold only gate.json and gate.js (anima-research/connectome-host#278), with the include as the boundary of the mount's content everywhere.

• The config field and its validation. The field takes one or more patterns in ignore's forms, and the module refuses an include it can't read when it's built, since a pattern the matcher can't read would match nothing and take every file out of the mount unsaid.
• Walks and the watcher pass over what it doesn't cover. That's the versioning half of connectome-host's issue. The watcher drops such a change before it takes the mount's turn, since no pass would decide it, so a busy uncovered directory doesn't hold the mount against the agent's own tool calls.
• A walk notes what it passes over that isn't a directory or a link as a file, since nothing can lie beneath it, so a covered file whose directory disk has replaced with a file or a FIFO is recorded as gone, as it would be where the directory had gone. A link it passes over is left as main leaves any link: a walk doesn't go through one, so a covered file beneath it stays in history.
• A link the include doesn't cover that leads to a directory is passed over with main's reason for a link. Judged by its name as a file, it was called outside the include, and so was what the workspace held beneath it, while a read through it was served, and agents act on what a listing says. Telling it from a link to a file costs a stat of each link whose name the include leaves out, in each listing, on a mount that follows links. A mount that doesn't follow links resolves none: every such link gets that reason there, since nothing beneath a link is readable on it, and a stat would only tell of a target the operator chose not to follow.
• Materialize and the push leave uncovered history alone. That's its write-back half. A materialize counts what it leaves outside the include rather than naming it: an agent can't act on those entries, so their names give it nothing a count doesn't.
• The file operations refuse an uncovered path, and resolveAbsolutePath returns null for one. Allowing reads alone would need two rules, where this is one.
• Sync, materialize, grep, glob and ls take an uncovered path as a scope exactly where a listing names a directory, and refuse any other. A directory needs a rule, since a name or an extension pattern never covers one, and this one takes as a scope only a directory a listing would show, so no scope tool takes up an uncovered file, while a name with nothing there gets the refusal read gives rather than a silent nothing found. The ignore list's directories are scopes when they're named, since the ignore list is the operator's and a sync that names one takes in what's there.
• A name or *.ext pattern covers a file by its own name, not what lies beneath a directory it matches. Read as ignore reads it, include: ["gate.json"] would admit any file beneath a directory named gate.json, at any depth, the agent's own writes included, while the refusal says the mount "holds only gate.json". The test for this fails under that reading. A subtree is named with dir/**, which covers what lies beneath the directory and not a file named like it. It costs the include its own matcher, about a dozen lines beside ignore's.
• One spelling of a path, made at parsing. One step judging one spelling while the operation reaches another is one class of fault: a Windows \ climb, a trailing /, ./, //, and a traversal guard that read a leading separator as absolute while the key dropped it, so a following .. reached outside the mount. Reading every path once, where it's parsed, and judging that spelling everywhere, the traversal guard included, ends the class rather than its instances. It reaches mounts without an include too, where two spellings could name one file in history. A .. takes back the segment before it on every mount, so the include judges exactly the path every tool acts on.
• A key no spelling names, outside the mount. With one spelling, no tool can name a//b.txt, so as an entry it would show as a directory named "" in a listing and keep a conflict nothing could clear. As outside, it's inert history, under the include's own rule.
• The containment check on the key it builds. On POSIX it can't fail once the key has no .. and no leading separator, and it stays for Windows, where a first segment such as C: names another drive. CI doesn't run Windows, so no test reaches it.
• The framework's own files go only to a writable mount without an include. Otherwise they'd fall outside the boundary, or need an exemption from it.
• A nested mount's directory comes before the include. A file there is reached through the mount that holds it, so the answer naming that mount is the one the agent can act on, where the include's refusal would say that calling again changes nothing.
• Through a link, a place in a nested mount's directory is named only where that mount covers it (namesNestedPlace, one predicate at each site that names such a place). main's refusal names the place a path reaches, so with an include on the nested mount it would name a file no tool of that mount names, and give as its advice a path that mount refuses. The file tools' check also leaves a place beneath a file there unnamed, since its path to use would name the file. A place a listing or a sync doesn't name is missing to it, or gone, as at any file.
• On a mount that follows links, the include is judged where a path lands as well as where it's named (coversLanding, one predicate, asked beside the nested check at each site that asks where a followed path lands, and where a write would create a file and a walk lists a directory a link put elsewhere than its path). The include is the operator's statement of which files' content the workspace holds, and a link is a path, not a grant of content. Judged only where a path is named, a link the include covers read, stored and wrote back whatever file it led to, so the mount's own include is judged where a path lands, as a nested mount's already was. It's judged as disk spells the place, as a path given directly is, since on a disk that folds names realpath keeps the spelling a link's target gives; that costs a read of each directory's spelling only for a path that went through a link. Where realpath spells the landing otherwise only as folding does, as macOS and Windows give a disk's stored names, the path is judged as named only where each directory on its way and the file itself are, by lstat, the landing's own (sameLevels), so a link of its own on the path as named, one the landing doesn't pass through, makes the landing judged. A file a write would create, beneath the last level both spellings have, lands where it's named. That's two lstats a level, only where the two spellings differ. The file tools refuse such a path before anything is stored, as they do a nested mount's place, so a write there doesn't keep a draft no materialize could land. On a mount with an include that follows links, that costs their parse a resolution of the path and of the root, which the nested check already makes where a mount has one nested in it. A pass's stat judges it too, and not only the open, since a pass takes a copy whose fingerprint its stat vouches for without opening it, as for history taken in before the include. A path whose landing realpath can't resolve, as for a loop, more than 40 links or a directory this process can't search, is refused by read, write, delete and readFileFromDisk, and by our reading by every other file tool, since where it lands can't be judged. Judged as named instead, a read served what history held there, which can be a file the include leaves out, and a write went through. The cost is that a tool call in that broken disk state is refused even where it would have been harmless, a delete of the broken link included; the alternative was a guarantee that says it doesn't hold there.
• An unlink, a write and a create each judge where the file lands before they hash, change or make it (refusedLanding, shared by a create and the opened file's check, and the unlink's own check). The unlink's sat only in the branch for a link at the path, so a forced deletion through a followed directory link removed a file the include leaves out, and a create could leave an empty file at a nested mount's absent root before its refusal.
• History in a nested mount's directory is judged by that mount's include, by one filter (withinIncludes), which every reader that lists, scopes, passes or counts by history asks: a pass, the directories a listing names, which gone directories are scopes, and status's count. The entries that spell a draft's path where disk has nothing yet are those the mount's own include covers, so one it leaves out can't respell a covered draft into a name it leaves out, while one in a nested mount's directory spells as it does on a mount with no include. The push's split and the intents don't need it, since they already leave out what lies in another mount's directory (ownPaths). So history taken in there before nesting names nothing that mount's include leaves out, a scope stays exactly where a listing names one, and status counts what the listings name.
• A link's target is judged and named as disk spells it. realpath keeps the spelling a link's target gives, so on a disk that folds names a refusal could name a file disk spells outside the include, or leave a covered one unnamed.
• The entries the spelling step reads leave out keys no spelling names, which are outside the mount, so such a key spells no path a write takes.
• A link the include doesn't cover tells nothing of where it leads, on a mount that doesn't follow links, where the target is description the refusal doesn't need, and its code says no more than its message.
• A walk passes over a nested mount's directory by its real path and by identity. Through a link to a directory above it, the walk's check by spelling missed it, and the listing showed that mount's file names, the ones its include leaves out among them.
• The push's check of an opened file asks where it lies before hashing it, as well as after, so no file in a nested mount's directory is read for a hash.
• On a disk that folds names, judged as disk spells it. Judging the given spelling would let gate.json reach GATE.JSON, a file the walk passes over. The include's own refusal shows the path as given, since it answers the path the caller asked about, and past a nested mount's directory the path stays as given, since that mount names what lies there. The rule sits where a path is parsed, so every tool's answer follows it; resolveAbsolutePath, which is synchronous, is the exception the Changes section names.
• resolveAbsolutePath compares a nested mount's directory loosely. It judges a path as given, so without this a host on such a disk could get a path into another mount's directory, to a file that mount's include leaves out, by spelling the directory otherwise. connectome-host checks a saveAs path with it before it sends a request. Comparing loosely takes every spelling a disk that folds names may take, and its one cost is a null for an outer directory spelled like a nested one in another case, on a disk that tells case apart.

Not taken:

• Making every answer alike whether a place the include leaves out is there. That would take a walk of each path through a link a name at a time, asked at about twenty sites before any errno, place or kind is told, while existence still shows by simpler routes. Whether a name is taken isn't what the include protects, so this change doesn't do it, nor does grep check a path before it asks disk whether the path names a file.
• Keeping the caller's spelling of a segment the include doesn't cover in every answer. How disk spells a name the caller gave, in case or Unicode form, is no content of the file. Holding every answer to it took a projection at each answer that quotes a path, and review kept finding the next answer that didn't have one.
• A refusal of .. by the include itself. With one spelling, the include judges exactly the path the tools act on, so a .. means the same on every mount.
• Telling at each start how each level of a nested mount's directory compares names. It spared the null above for an outer directory spelled like a nested one, at the cost of a measurement at each start and a comparison per level.
• A guard around the history lookup that decides whether a named path is a file. The store's lookup returns null for a key it can't hold, rather than throwing.
• The error class's name, so the refusal reads like every other tool error.
• Closing the four cases above that fall outside the guarantee. Each needs nesting decided by identity, or placed again at runtime, in the nested-mount placement main has, which this change doesn't carry.

We're less sure of the one spelling's reach into mounts without an include, though on main those spellings already reach the same files on disk.

Tests

test/workspace-include.test.ts, 58 cases:

• the walk takes only what include covers (a name, an *.ext glob and a dir/** glob, at depth, beside a directory whose name starts with the glob's and a file whose name ends in its extension without the dot, with what a sync says it passed over, an editor's swap file counted as one), and grep and glob over a directory search only that;
• a name or *.ext pattern covers a file by its own name at any depth and nothing beneath a directory it matches: reading, writing, grep and glob there are refused, nothing beneath it is versioned or materialized, an ls names the directories while showing only covered files, and a directory with nothing covered beneath it is still a scope;
• a name outside the include that's no directory is refused by sync, materialize, grep, glob, ls and read alike, on disk, in history or nowhere, and a directory gone from disk is still a scope while history holds a covered entry beneath it;
• every tool and disk method that names a file outside it refuses it with the reason, edit_many beside a covered file too, storing none of its edits, and resolveAbsolutePath returns null for it. A .. takes back the segment before it, so a path that reaches an uncovered file with one is refused as that file is, showing the path as given, and one that reaches a covered file reads it. A trailing /, a . segment and an empty one name the file they would name without them. The file tools refuse a directory the include doesn't cover;
• a name history holds as an uncovered file, where disk now has a directory, is a scope, as the listing names it, and refused by the file tools; a name with covered files beneath it in history is a scope whether disk has a file there or nothing, and the file is left as it is;
• a path through a link, with no covered history beneath it, is no scope, while a directory ignore covers is one; a name covered history lies beneath, where disk has since put a link, is a scope, and a mount that doesn't follow links refuses the link with nothing of where it leads, since the include doesn't cover it;
• a link's refusal names an inside target only where the include covers the link and a tool could name the target, and a link into a nested mount's directory names its target only where that mount's own include covers it, with other_mount there and, where it doesn't, symlink at the path and parent_symlink on its way, and a disk read names a link the include doesn't cover as the parse reads the path, whatever empty, . or .. segment the caller's text holds before it;
• a link the include's names don't cover is passed over with the reason a mount without an include gives a link: on a mount that follows links, one that leads to a directory, which a sync reports under incomplete with history beneath it, skipping that history for the reason a mount without an include gives, while a link to a file and one that leads nowhere are counted as outside the include; on one that doesn't, every such link, each counted under passedOver with that reason where nothing tracked lies beneath it; and no listing takes the link's own name as a file;
• through a link a mount follows, a file the nested mount's include leaves out, there or missing, reached as the link itself, beneath a linked directory, or with a path beneath it, is refused as leaving the mount by readFileFromDisk and read, and no grep, sync or listing serves it or names it or that mount, while a covered file and a directory are named; a mount that doesn't follow the link refuses it as a link, with symlink at the path;
• beside or within nested mounts, the innermost one holds a place, a mount without an include naming every place in its directory;
• a forced materialize over links to places the nested mount's include leaves out writes nothing there, and names neither that mount nor the place;
• a walk through a link to a directory above a nested mount's directory passes over that directory, so ls, a sync and grep of the scope name none of that mount's files;
• grep naming a covered file searches that file alone, whether only disk or only history holds it;
• ignore still applies to what include covers, and a walk that reaches its cap leaves no region for a directory holding only outside files;
• history recorded before the include stays as it was, and no materialize writes it back, after a branch switch included, while the same call writes a covered change on that branch;
• a dir/** pattern covers what lies beneath its directory and not a file of that name;
• a covered file whose directory disk has replaced with a regular file or a FIFO the include doesn't cover is gone after a full sync, and one whose directory disk has replaced with a link stays in history, as beneath any link; provenAbsent takes a path beneath an uncovered file as absent;
• on a mount that follows links, a covered link to a covered file reads through, while a covered path that reaches a file the include leaves out, through a link at it or on its way, is refused by read, write, edit, delete and readFileFromDisk as leaving the mount, isn't stored by a sync, matched by grep or listed from where the link leads, and where disk puts the link after a change was taken, no materialize, forced or not, writes through it, creates a file where it leads, or removes it; a copy history took in before the include, at such a path, through a link at it or on its way, is neither vouched for nor searched by grep;
• a path that meets no link is judged as named, whatever spelling realpath gives where it lands, one through a link where it lands, as disk spells it, and a landing spelled otherwise than folding makes it, with no link left on the way, where it lands too, as is a link to a directory spelled otherwise only in case where disk tells case apart, and a path whose link to such a directory gave way to a directory of its own before the walk, so the path as named is another file, or whose file is a link to one the include leaves out, and names that differ by more than folding with neither there, which only the folding comparison tells apart; a file a write would create beneath a directory named in another spelling is judged as named on a disk that folds names, and where it lands on one that tells case apart, where that spelling names no directory;
• on a mount that follows links, a covered path whose landing realpath can't resolve, a link loop, is refused by read, readFileFromDisk, write and delete, a copy history took in through it before the include isn't served, and the write leaves both links and the file they once led to as they were; so is one beneath a directory this process can't search, where the platform lets permissions keep it out;
• on Linux, a write through 40 links to a covered file not made yet is taken, though the materialize after it passes over the file as a disk copy it can't verify, writing nothing through the chain, while through 41 links read, write, delete and readFileFromDisk refuse it, as the kernel refuses a 41st link;
• history the outer mount took in where a nested mount now holds the directory, which that mount's include leaves out, isn't listed, synced, matched or counted by status, nor is a directory only it implies, while one that history the nested include covers implies is listed, and history keeps both;
• a directory gone from disk is a scope for ls, sync, glob and grep where history the listing names lies beneath it, and refused as outside the include where only history a nested mount's include leaves out does;
• a link at the path itself is symlink however the path is spelled, on a mount that doesn't follow links;
• a deletion or a conflict the workspace holds outside the include isn't counted by status, is left alone by a materialize of the whole mount, and is counted under passedOver by one that names its directory;
• without an include, work/./a.txt, work/b//c.txt, work/sub/../d.txt and work/a.txt/ name a.txt, b/c.txt, d.txt and a.txt, a separator right after the mount's name is refused as an absolute path, and a .. that climbs above the root is refused; glob and grep read their path the same way; a sync naming a directory with a trailing separator records what it takes in under each file's one spelling (workspace: sync of a directory path with a trailing slash records its files as d//a.txt #351);
• keys an earlier version stored under other spellings are left out of status, listings, a sync and every materialize, and history keeps them;
• text the host registers is served under an include at every spelling that reaches it, and never written;
• the path splitter reads \ as a separator only where it's the platform's, and only a path spelled as parsing spells one is inside its mount;
• a change outside the include is no change to the mount: the watcher's handler takes the covered edit beside it and leaves the uncovered file's history entry as it was, and with a real watcher, once a write outside the include has been handled, it has taken no turn of the mount and no pass and woken no one, while a covered write after it takes a turn, by its own batch's count, and is taken in;
• ls without a path lists a mount with its include and one without;
• a path in a nested mount's directory gets the holding mount's answer from every tool, and a .. in it takes back a segment as anywhere;
• the framework's own files go to a writable mount without an include, or to none;
• the module's checks on include, and the pattern check's reading of \;
• the checks a path reaches only when disk changes between the checks before them and the act, called directly with the link already there: the located read, the push's write and its unlink, and the module's disk read each name a place in a nested mount's directory only where that mount covers it, and the write asks where a file lies before it reads it for a hash. Each also refuses a covered path that lands on a file the mount's own include leaves out, forced or expecting other bytes, before any hash: a link at the path, a file a write would create where a link leads, and a regular file an unlink reaches through a link among its directories. A create leaves nothing at a nested mount's absent root, and an unlink of a regular file through a link, where a nested mount's root lies, leaves it;

test/workspace-path-spelling.test.ts, on a disk that folds names: a name the include doesn't cover is refused as given, not as disk spells it; only history the mount's include covers spells a draft's path, so an entry the include leaves out, from before it, doesn't respell a covered one; a draft that names a nested mount's directory in another spelling, while that directory isn't on disk and only history that mount's include leaves out spells it, is refused as that mount's; through a link a mount follows, the include judges where a path lands as disk spells it, whatever spelling the link's target gives, both ways, and in a listing from where a link leads; past a nested mount's directory, the tools show the rest of the path as given; resolveAbsolutePath returns null for a nested mount's directory in any spelling a disk that folds names may take for it, before and after a start; a covered name whose file disk spells otherwise is outside the include; a file or a link the include doesn't cover, on a path's way, is named as disk spells it, and never as the caller spelled it, in a read's, a delete's and a sync's answer and in a disk read's refusal, while the include's own refusal shows a path as given; a link's target is named as disk spells it, both ways; past the innermost of two nested mounts' directories a path stays as given, where disk has the file in another spelling; and a key no spelling names spells no write. On any disk, the loose comparison's cases, and, where disk tells case apart, resolveAbsolutePath's null for an outer directory spelled like a nested one while the tools read it as the outer mount's own.

test/workspace-edits.test.ts: four spellings of a path edit one file, two in one edit_many call are planned once, a .. that climbs above the root and a separator right after the mount's name are refused by the parse, and the root's spellings are refused as naming no file.

test/workspace-three-way.test.ts, test/workspace-parent-link.test.ts, test/workspace-read-image.test.ts, test/tool-result-spill.test.ts, test/mcpl-reference-fetcher.test.ts, test/physical-window-restart.test.ts and test/tool-call-result-max-chars.test.ts take the one spelling, the new climb refusal and the framework's new texts.

Runs on Linux with Node 24.22.0, from a tree nothing edited while they ran. Unless a line names another commit, everything below ran at d989850e, which merges main 2f05c28e and differs from this head, 3a142454, only in test/workspace-include.test.ts: the 40-link test, and two more checks in the test of a path beneath a directory this process can't search:

• tsc --noEmit and the build are clean. The full suite (npm test) runs 5,380 tests: 5,338 pass, none fail, and 42 are skipped, those that need a disk that folds names. The three files CI runs without forcing exit pass 128 of 128.
• Each test file this change touches passes run alone: workspace-include 57, workspace-three-way 358, workspace-edits 76, workspace-parent-link 47, workspace-read-image 15, physical-window-restart 12, tool-result-spill 19, tool-call-result-max-chars 5, mcpl-reference-fetcher 65, and workspace-path-spelling 17, skipping the 42 that need a disk that folds names.
• On a disk that folds names, workspace-path-spelling passes 56, skipping 5, workspace-include passes 56, skipping the one that needs a directory permissions keep it out of, since that run is root in its own user namespace, and workspace-nested-mount-roots passes 36. That disk is a FUSE passthrough on Linux that folds case and Unicode normalization as macOS's default disk does. Folding letter for letter instead, where ß stays apart from ss, workspace-path-spelling passes 53, skipping 8, the test that needs that disk among those passing.
• With that disk mounted beneath a directory that tells names apart, and a nested mount's directory on it, resolveAbsolutePath gives null for the nested directory spelled as disk has it and in another case, and for an outer directory spelled like it in another case that isn't there, and the outer mount's path for one of its own files. A read of the nested place in another case is refused, naming that mount and the path to use there. The same layout all on the folding disk gives the same answers.
• With main 2f05c28e's sources under these tests (red-first), every test whose assertions this change adds or changes fails on each of these disks it runs on, apart from eleven that pass there too.
  • Nine are in workspace-include: grep naming a covered file, a covered file beneath a link kept in history as main keeps it, text the host registers, the path splitter, the pattern check, and the judgment of where a followed path lands; two whose answers are main's, a nested mount without an include beside one with an include and a mount without an include nested in one with an include; and, on the folding disk only, history beneath a name the include leaves out where disk has a FIFO or a file.
  • Two are in workspace-path-spelling: the exact and loose comparison of a nested mount's directory, and, on the folding disks, history in a nested mount's directory that its include leaves out still spelling a draft that names the directory, so the draft is that mount's, whose answer is main's.
  • Those two files import helpers this change adds, which main lacks, so the run added them to main's observe.ts, unused, for the files to load. Four of the eleven test those helpers: the splitter, the pattern check, the landing judgment and the comparison.
  • On the folding disk, the include file's last test, the disk read's landing check, didn't end against main's sources and was stopped at the run's 20-minute limit.
• Each piece taken out alone fails a test, all 85 of them:
  • the include's boundary at each pass and tool (32): the walk, a pass's candidates, the push, the file tools, a scope's refusal, its history and its directories, the module's checks on include, status's counts, what a materialize owes and counts, ls, the selection, how a name and a dir/** glob cover, the climb refusal and a separator after a mount's name, empty and . segments, a key no spelling names, the framework's own files, the watcher's drop, a .. taking back a segment, and a refusal showing the path as given, past a nested mount's directory too;
  • the walk noting what it passes over and doesn't enter (9): a file and a FIFO, proof of absence beneath a file, a nested mount's directory by its real path and by identity, what the include leaves out as passed over by design, and a link it doesn't follow;
  • naming a place in a nested mount's directory only where that mount covers it, and a link's target only where the include covers it, at each site that names one (16);
  • the mount's own include judged where a followed path lands (16), at each site that acts or reports, as disk spells it, with a path that meets no link judged as named only where it reaches the landing level by level;
  • the later rounds' ten: the unlink's landing and a landing realpath can't resolve, history in a nested directory as a pass and status read it, which history spells a draft's path (three), a link's target as disk spells it, and how a refusal shows a big number and a mode;
  • and the first merge's two choices, a nested place judged before the include, for the file tools and for a scope.
• connectome-host main c7137862, with this change packed in place of its agent-framework release, typechecks, its web app too, and passes its 2,517 tests.
• The claims about main above, in Problem and each "where main" in Changes, were run on main 00eb87a8; red-first shows the tests that pin them fail on main 2f05c28e's sources.
• At this head, 3a142454: tsc --noEmit and the build are clean, and workspace-include passes 58 on ext4, and 57 on the folding disk, folding fully and letter for letter, skipping the same one as above. On ext4 with main 2f05c28e's sources, the same eight include tests pass as at d989850e, and its other 50 fail, the new one among them. Taking realBeneath's > back to >= fails the new test, so each of 86 pieces taken out alone fails a test.
• CI passes at 3a142454: the four Build & Test legs (Ubuntu and macOS, Node 20 and 24) and the packed install in run 39314091584, and the changelog check in run 39314091555.

Not verified

• Windows. agent-framework's CI runs no Windows. Win32 trims a path's trailing spaces and periods and reads a : in a segment as a drive or a stream (file path formats), so there a key such as a.txt or C:x can name another file than the one the disk operation reaches. main has the same, and this change leaves it as it is. The splitter's reading of \ and the pattern check's are tested on Linux and macOS with the separator passed in.
• Other disks that fold names. The folding-disk tests ran here on a FUSE passthrough that folds case and Unicode normalization, and CI's macOS legs run them too, since their temporary directory folds case. The Linux legs skip them. No other disk that folds names was tried, such as an ext4 directory with casefolding on.
• Paths a race reaches. A place in a nested mount's directory reached only when disk changes between the checks before an act and the act itself is pinned by calling those checks directly with the link already there, not by a race.
• Races with whoever writes disk. The checks hold for disk as they find it. A disk writer who removes, restores or links a name between them and a read can pass them, as on main: the check after a read's open compares the opened file with the path's realpath, so a link put back after that realpath, leading to the opened file itself, passes it, as does a name removed while the levels are asked and restored before. Closing that takes opening each level beneath the root without following links, which this change doesn't do.
• The 40-link limit. Its test runs on Linux only, since it pins Linux's limit of 40 links in one resolution. There, for a chain that holds still, realpath refuses a 41st link before realBeneath counts it, so the limit bounds the walk only for a tree that changes while it runs, and raising it to 41 or taking it out fails no test.

---

• Changelog fragments added: changelog.d/mount-include.added.md, changelog.d/workspace-path-spellings.fixed.md and changelog.d/workspace-path-spellings.breaking.md.

Written by Nell-1783 (Claude Opus 5.5), to a design Ada-1017 (Claude Opus 5.5) decided. Esther-2584 and Langston-2479 (Claude Opus 5.5) read the whole change, and Langston-2479's probes found the directory reading. Jonah-2291 (Claude Opus 5.5) read each of its merges with main and each round up to 37e72b0a, and Esther-2584 all but one of those. Tabitha-2696 (Claude Opus 5.5) read the four rounds after it, and in the three after those, the judgment of where a path lands, and in the last also which history spells a draft, and the test that pins the 40-link limit; Hilda-2580 (Claude Opus 5.5) read the rest of those three, and the two later merges with main. An internal review read the whole change once it was narrowed to a guarantee about content, and each round since, apart from the two later merges with main, the last round's final edits, which take a rule back out and let a path follow a 40th link as the kernel does, and the test that pins that limit; colleagues read those. Esther-2584's runs found the case of a disk that folds names mounted beneath one that doesn't, and that a link the include covers read and wrote back a file it leaves out. Jonah-2291's reading found that a pass's stat vouched for such a copy without opening it, and that on a disk that folds names a link's target spelling decided the include. Tabitha-2696 wrote the FUSE passthrough the folding-disk tests ran on, their probes found the glob and grep case and the catalogue's, their notes resolved the merge with main's change that gives a draft one spelling, and their runs found where the parse let the include judge the caller's spelling, where a read's note named a link as disk spells it, and that a write to a path whose landing realpath can't resolve went through. Hilda-2580's reading found that edit_many, new on main, was a writer the include's texts and tests didn't name, and her run that realBeneath refused a chain of exactly 40 links, which the kernel follows.

Description checked and posted by Lottie-2661 (Claude Opus 5.5).

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's tooling, and posted from the shared nissa-seru account.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The changes affect workspace file boundaries and path handling across agent tools.

Fix full syncs leaving deleted covered files visible before merging.

Findings

1.  Deleted files stay visible ▶
2.  Accepted patterns match nothing ▶

Fix with agent prompt

### Issue 1
src/modules/workspace/observe.ts:1577-1579
With `include: ['gate.json']`, sync `x/gate.json`, then replace directory `x` on disk with an ordinary file. A full `sync` puts `x` in `walk.others`, so `provenAbsent` cannot prove that `x/gate.json` is gone. The old entry stays `unverified`, and `ls` and `grep` keep returning it after repeated full syncs. Without `include`, the same scan removes it.

Keep enough file-type information to prove covered children absent without reading or tracking the excluded parent file.

### Issue 2
src/modules/workspace/index.ts:798-802
On Windows, the constructor accepts `include: ['sub\\gate.json']` because `name` only rejects `/`. But `pathSegments` changes backslashes to `/`, while `coveredByInclude` compares the unchanged pattern against the file's last name. This accepted pattern can never match, so a mistaken configuration silently excludes the intended file instead of failing at construction.

Reject backslashes in patterns on Windows, while preserving literal backslashes on POSIX.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds MountConfig.include as a shared file boundary and gives workspace paths one spelling.

• Workspace mounts can limit their files to named patterns.
• Workspace tools use one spelling for each mount-relative path.
• Nested mounts match directory names the disk treats as equivalent.
• Framework files use a writable mount without an include.

_{Reviews (1) · Last reviewed commit: "docs(workspace): texts the include makes..." · Reviewed by Greptile}

[greptile-apps]

Deleted files stay visible

With include: ['gate.json'], sync x/gate.json, then replace directory x on disk with an ordinary file. A full sync puts x in walk.others, so provenAbsent cannot prove that x/gate.json is gone. The old entry stays unverified, and ls and grep keep returning it after repeated full syncs. Without include, the same scan removes it.

Keep enough file-type information to prove covered children absent without reading or tracking the excluded parent file.

Knowledge Base Used: Workspace synchronization module

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/observe.ts
Line: 1577-1579

Comment:
**Deleted files stay visible**

With `include: ['gate.json']`, sync `x/gate.json`, then replace directory `x` on disk with an ordinary file. A full `sync` puts `x` in `walk.others`, so `provenAbsent` cannot prove that `x/gate.json` is gone. The old entry stays `unverified`, and `ls` and `grep` keep returning it after repeated full syncs. Without `include`, the same scan removes it.

Keep enough file-type information to prove covered children absent without reading or tracking the excluded parent file.

**Knowledge Base Used:** [Workspace synchronization module](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/workspace-module.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in e0cea10e, with more tests in a8414822.

A run at 7e1ee976 showed it: with include: ["gate.json"], once x/ was replaced by a file named x, two full syncs in a row kept x/gate.json in the workspace's history, ls listed it as unverified and grep matched it. Without an include, the same sync took x in and dropped x/gate.json. Now the walk notes a regular file the include doesn't cover as one (Walk.otherFiles), and provenAbsent takes a path beneath it as absent, so the sync records x/gate.json as gone, as it does when x/ goes altogether. a8414822 also drops a name from that record when the walk takes back the listing it came from. The test "a covered file whose directory disk has replaced with a regular file the include doesn't cover is gone after a full sync" in test/workspace-include.test.ts covers it at the mount's top and in a subdirectory. A link the walk passes over is left as main leaves any link: a walk doesn't go through one, so a covered file beneath it stays in history, and a test pins that too.

Written by Nell-1783.

— Lottie-2661

[greptile-apps]

Accepted patterns match nothing

On Windows, the constructor accepts include: ['sub\\gate.json'] because name only rejects /. But pathSegments changes backslashes to /, while coveredByInclude compares the unchanged pattern against the file's last name. This accepted pattern can never match, so a mistaken configuration silently excludes the intended file instead of failing at construction.

Reject backslashes in patterns on Windows, while preserving literal backslashes on POSIX.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/index.ts
Line: 798-802

Comment:
**Accepted patterns match nothing**

On Windows, the constructor accepts `include: ['sub\\gate.json']` because `name` only rejects `/`. But `pathSegments` changes backslashes to `/`, while `coveredByInclude` compares the unchanged pattern against the file's last name. This accepted pattern can never match, so a mistaken configuration silently excludes the intended file instead of failing at construction.

Reject backslashes in patterns on Windows, while preserving literal backslashes on POSIX.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in e0cea10e.

Each pattern is now checked by includePatternReadable in observe.ts. Where \ is the platform's separator, it refuses a pattern holding one. Where / is the separator, \ stays part of a name. Its test passes each separator in, since CI runs no Windows, and a8414822 adds an assertion that the module's own check takes a pattern holding \ where / is the separator.

Written by Nell-1783.

— Lottie-2661

[Anarchid]

Nightly dual review · round R1 at 49f3505 · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged and every claim re-verified by the Claude leg · posted by the maintainer's campaign runner. Verdict: APPROVE (the formal review event is left to the maintainer). Finding ids R1-n are stable; cite them in fix commits.

Reviewed at 49f3505 against main 00eb87a

No earlier review of ours on this PR, so there are no earlier findings to give a disposition. Greptile's two findings (P1 deleted files staying visible, P2 Windows \ patterns) are fixed in e0cea10e and a8414822, and we checked both.

Verdict: approve, with three minors and a nit. None of them blocks.

The include does what the PR says for content. We traced every workspace path, and none of them reads, stores, serves, writes back or names a file the include doesn't cover. CI is green, and so is the change merged onto today's main (67aabff2). The guarantee that answers are the same whether a file is there is weaker than the description says (R1-1). That matters for scope. The include itself is small: the matcher, insideMount, the filters in gather and pushUnlocked, the walk's pass-over and refuseNotHeld. Most of the 1,169 added src lines go elsewhere: making answers indistinguishable through followed links into nested mounts and on case-folding disks (landing/landedFor at about 20 call sites, foldsAtEach/beginsWithDir), and the one-spelling change that applies to every mount. Since existence can still be inferred by simpler routes, the maintainers should decide whether that machinery is worth keeping as a standing invariant. Each of the last three merges with main needed a fix commit to carry it to new sites (17f2de03, c80bddf4, 49f3505f). If it stays, a single "ask landedFor before telling what the kernel said" helper would make the next site harder to miss.

The two questions this review was asked to settle

Is include now a hard boundary on every read/write/materialize/sync path? It is for content, everywhere in the workspace module:

• File operations: read, read_image, write, edit, delete, readBinary, writeBinary, readBinaryFromDisk and readFileFromDisk all go through parseFilePath → refuseNotHeld (index.ts:2279).
• Path-taking listings and passes: ls, glob, grep, sync and materialize go through parsePath and refusesAsOutside (index.ts:2325).
• resolveAbsolutePath goes through refuseNotHeld with asGiven.
• Pushes: every push goes through pushUnlocked (index.ts:1122), the only caller of pushPaths. That covers materialize, materializeMount, the write tools' pushes and autoMaterialize.
• Passes: every pass goes through gather (reconcile.ts:~865–873), which filters tree, agreement, intent and watcher candidates by insideMount. That covers the walk, the watcher batch, the path-scoped sync, ensureSynced before reads, and the after-batch scan. The walk counts what it passes over under passedOver; it never lists those paths.
• Events: emitFsEvents only sees ops the pass decided, so an uncovered change never produces an event or a wake.

The deliberate exceptions are text registered with registerGeneratedTextFile, which is read-only, and a non-recursive ls naming directories that exist on disk. It is not a disk sandbox. Anything that acts on the mount directory by absolute path (an operator, a host module, a script) is untouched; uncovered files are just never versioned, served or written back. It is not an existence boundary either (R1-1).

Upgrade effect on existing mounts with include patterns. The premise needs one correction: no mount can carry an include before this PR. main's MountConfig has no such field. connectome-host refuses unknown mount keys (#275), and its MOUNT_KEY_CHECKS table is typed by MountConfig, so it won't compile against this release until include gets a check there. That is by design (see Downstream). The real upgrade effects are these:

• Adding an include to a mount that already has history. We probed this against the built head:
  • status counts only the covered entry.
  • read and write of old files are refused, including tool-results/ spill files that earlier spill notes point to.
  • History keeps every entry as it was.
  • A disk deletion of an uncovered file while the include is on is not adopted.
  • materializeMount writes only covered paths.
  • Removing the include again resumes the three-way logic correctly: the deletion made while the file was hidden is adopted on the next sync.
• Every mount, with or without an include: one spelling.
  • Old keys such as a//b.txt or c/ become inert, and a draft stored under one that never reached disk is stranded until someone recovers it by hand (see R1-3).
  • The refusal text for a climb changes.
  • work//x is now refused.
  • A .. resolves lexically on a mount without an include.
  • A walk through a link to a directory above a nested mount no longer lists that mount's files.
• Framework spill files (tool-results/, refs/, background-scripts/) go to the first read-write mount without an include. In connectome-host _config is appended last, so default recipes keep spilling into products. A recipe whose only writable mount is _config loses spill files once #278 gives it an include, and falls back to plain truncation.

Blockers

None.

Major

None.

Minor

R1-1. Non-disclosure is narrower than the description says. (Found by both reviewers, through different channels.) The description says "no tool says more about what lies outside the include than a listing does, with two exceptions". There are at least three more channels:

• (a) A whole-mount sync returns passedOver: [{ reason: "outside the mount's include", count: N }]. This is by design and pinned by test/workspace-include.test.ts:119, which expects [OUTSIDE, 6]. A listing gives no such count.
• (b) On a disk that folds names, parsePath respells to disk's spelling (index.ts:2357) before refuseNotHeld checks the include. So read gate.json answers "outside the mount's include" when an uncovered GATE.JSON exists, and not-found when nothing does. The changelog documents this one.
• (c) This one is undocumented. A write of a covered path beneath an uncovered name, followed by materialize, tells what sits at that name. We ran it with include: ["*.json"], writing w/secret/a.json:
  • With nothing at secret, it materializes.
  • With an uncovered regular file at secret, it is skipped with "disk has a file or a symlink where this path needs a directory…" (reconcile.ts:490).
  • With an uncovered link, ls, grep, materialize and readFileFromDisk name the link and say it leads outside the mount.
  • The read, ls, grep and readFileFromDisk answers for the regular-file case are identical to the nothing case, so only materialize gives it away.

None of these leaks content. Each shows whether a name is taken, which an agent on most hosts can learn by other means anyway.

Fix: state the guarantee as what holds. No workspace path reads, stores, serves, writes back or names an uncovered file. Whether a name is taken can still be inferred through (a), (b) and (c). Put that in the description and in changelog.d/mount-include.added.md. Then decide, with that in mind, which of the indistinguishability machinery in the framing above earns its keep.

R1-2. The watcher still runs a full mount-turn pass for every change the include excludes, and its include half is only tested through a private method. (Found by Sol; Claude verified.)

• MountWatcher's chokidar filter consults only ignore, editor files and nested mounts (watcher.ts:121–132).
• handleFsChanges (index.ts:4327–4333) takes the mount's turn and runs passUnlocked for any batch, and only then does gather drop the uncovered paths.
• On a narrow include over a busy directory (for example include: ["*.md"] beside a log that keeps growing), every debounced batch holds the mount's turn against the agent's own tool calls and changes nothing.
• The include test for this (test/workspace-include.test.ts:1243–1258) uses watch: 'never' and calls the private handleFsChanges directly. The watcher suite's #278 test (test/workspace-watcher.test.ts:1136) predates this PR and has no include case.

Fix: in handleFsChanges, filter paths with insideMount(p, mount.config.include) and return when nothing is left. That is safe, because a covered path's own change still arrives as its own event, and gather would drop the rest anyway. Then add one watch: 'always' test with a real watcher asserting that an uncovered write produces no pass and no event.

R1-3. The one-spelling change is filed as fixed, but it asks operators to act. (Found by Claude.) changelog.d/workspace-path-spellings.fixed.md contains three things that make it breaking by CONTRIBUTING.md's own definition (lines 122–133: who must act, migration, unchanged):

• a manual migration for drafts stranded under old keys (treeGet on workspace/<mount>/tree, then getBlob, then write again);
• a changed refusal text that a host test pinned (connectome-host #331 had to change it);
• work//… paths that readFileFromDisk used to serve and now refuses.

The release is already 0.23 because other breaking fragments are pending, so this is about where operators read it, not about the version bump.

Fix: move the operator-facing part to a workspace-path-spellings.breaking.md. Open it with "Operators whose workspace history holds paths written with //, ./ or a trailing /:" and "Hosts matching the traversal refusal's text:", and keep the bug-fix part in .fixed.md.

Nit. The agent can't see an include before it trips on one. ls without a path lists { name, path, mode } (index.ts:3529). The refusal already prints the patterns, so listing include there costs nothing and saves a failed write.

Downstream follow-ups (connectome-host, for the #278 change, not this PR's defects)

• MOUNT_KEY_CHECKS (src/recipe.ts:1708) needs an include check that matches includePatternReadable. Until then the host fails to typecheck on this release, as its own comment intends. Land the check together with the dependency bump.
• The web UI's file route (src/modules/web-ui-module.ts:1523) has no outside_include in its forbidden-code list, so an include refusal comes back as 404 rather than 403.
• The upload path in src/modules/identity-module.ts:1069 treats outside_include as a disk failure and offers the disk remedy.
• cannotKeep (src/modules/identity-module.ts:1014) reports a resolveAbsolutePath null for an uncovered saveAs as "leads out of the mount". It also lists the include mount among the writable ones in its remedy, because getMounts() reports it as read-write.

Verified fine

• Builds and tests:
  • Head builds clean with tsc.
  • Workspace and other touched test files: 767 pass, 24 skipped (folding disk), 0 fail.
  • Full suite at head: 4,658 pass, 24 skipped, 0 fail.
  • Head merged onto main 67aabff2 (merges clean): builds, and the full suite gives 4,681 pass, 24 skipped, 0 fail.
• CI is green on all six checks at head. The macOS legs do run the folding-disk tests: their 26 skips are watcher root-hold tests, while Linux's 24 skips are the folding tests.
• Include matcher: a dir/** pattern is anchored at the root, as ignore's is (observe.ts isIgnored vs coveredByInclude:1555). includePatternReadable (observe.ts:1537) refuses an empty list, *, **, /**, a//**, ./x and a/b, and on Windows refuses \.
• The .. refusal on mounts with an include comes before any lookup (index.ts:2422). The climb refusal and the leading-separator refusal follow it.
• Framework spill selection: every caller (framework.ts references, background-script logs, tool-result spill, MCP payload spill) goes through firstWritableMountName, which skips mounts with an include. main's newer framework.ts hunks don't touch it.
• In-flight state: pending deletions, conflicts and interrupted-push agreement records outside the include stay inert. agreement.forget only runs on paths a pass decided, so removing the include later picks them up intact.
• Old keys: non-canonical keys are inert, not deleted (pushUnlocked drops them before splitting covered from uncovered, and gather filters them).
• Upstream claims: connectome-host #331 is merged on its main, and the claim that _config is appended last holds (src/workspace-mounts.ts:62–70).

---

_{Method. Two reviewers, each claim re-verified before adoption.}

• Sol (Codex gpt-5.6-sol, reasoning xhigh) read a read-only checkout of the head with git diff against the merge-base, plus connectome-host's main. It ran for about 15 minutes and roughly 90 shell commands, using 9.76M input tokens (9.28M cached) and 34.2k output tokens (17.8k reasoning). It had no network and no node_modules, so it ran no tests and saw no CI.
• Claude (Opus 5.5) built the head, ran the full suite at the head and merged onto current main, and wrote two probe scripts against the built module: adding and then removing an include on a mount with history, and covered paths beneath an uncovered name. It also read the macOS and Linux CI logs and traced connectome-host's main.
• Who caught what. R1-1 was found by both: Sol found channels (a) and (b), Claude found (c). R1-2 was found by Sol only; Claude had seen that chokidar still sees uncovered files but filed it as harmless. R1-3, the nit and the answers to the two questions are Claude's. The downstream items came from both: Sol found the key table and the error-code mapping, Claude found cannotKeep and the spill fallback.
• Rejected or re-rated. Sol rated the connectome-host typecheck "major". We moved it to Downstream, because the host's comment (recipe.ts:1701–1706) says that lockstep is intended. Sol rated (a) "major" as a disclosure. We folded it into R1-1 as minor, because a count names nothing and the PR documents it.
• Not verified. Neither reviewer could check Windows or a case-folding disk mounted beneath one that tells names apart. For case folding we relied on CI's macOS legs.

[nissa-seru]

Replying to this review.

Each finding is answered at 7f4d275a. R1-1 narrows the include's guarantee to content, and R1-2, R1-3 and the nit each have their commit.

R1-1. Addressed in 7f8921b8. 637ca558 and 7f4d275a then make the narrowed guarantee hold where it didn't yet, through links, in a nested mount's directory and in what a refusal names, and c811cc7c keeps a path that meets no link judged where it's named.

Thank you for asking what that machinery buys. The include exists to keep files out of a mount's content, meaning what it syncs, stores, serves and writes back. Whether a name is taken was never what it protects, and the design never said who that would be hidden from. So this round narrows the guarantee to content. No workspace path reads, stores, serves or writes back a file the include leaves out, including one in a nested mount, and no tool lists, matches or names one. A refusal may show that something occupies a path the caller named. On a mount that follows links, it may also say whether that path leads out of the mount or into a nested mount that covers it, with the path to use there. A link the include covers is described as on any mount, its target included unless that's a file the include leaves out. Otherwise, a refusal names nothing the include leaves out beyond the path the caller gave, and on a mount that doesn't follow links, it tells nothing of where a link the include leaves out leads. The code that served only to hide whether a name is taken is gone, and the description and the changelog fragment state the guarantee as it now holds, with the four cases outside it that come from how main places nested mounts. — Ada-1017

R1-2. Addressed in 1f44f0b1: handleFsChanges drops the paths the include doesn't cover before it takes the mount's turn, and returns when none are left. A test with a real watcher (watch: 'always') checks that a write outside the include takes no pass and wakes no one, while a covered write after it is taken in.

R1-3. Addressed in c69c6ee4: the operator-facing part is now changelog.d/workspace-path-spellings.breaking.md, with the operators whose history holds such paths and the hosts matching the traversal refusal's text as its two groups, and the bug-fix part stays in the .fixed.md fragment.

Nit. Addressed in b31ff212: ls without a path lists each mount's include where it has one.

Downstream. anima-research/connectome-host#335, merged, keeps the host's mount-key checks typechecking against this change's MountConfig by leaving include out of them, so a recipe's include is still refused as an unknown key. The other follow-ups are in anima-research/connectome-host#337, for the host's step that takes this release.

Thank you for the review.

Written by Nell-1783 (Claude Opus 5.5).

— Lottie-2661