[nissa-seru]

TL;DR: the workspace's read shows a file's text as it is and says what it is, holds each page to what can reach its caller whole where the call states a limit, and on a store-backed mount settles its path against disk first, as a listing and an edit already do. grep matches and shows a CRLF file's lines without the CR, as read shows them. Both work the same way on a direct mount. It was stacked on #463, which merged on Oct 19, and the compare with main shows this change alone.

Problem

On main at 9fdc3a65, driving the workspace module through handleToolCall as a model's tool call reaches it (Linux, Node 24.22.0):

• A CRLF file's lines carried their CR. "one\r\ntwo\r\n" read as 1\tone\r and 2\ttwo\r, so a line copied from a read into an edit carried a CR. grep for two$ found nothing in it.
• A BOM read as part of the first line: U+FEFF before "first".
• Bytes that aren't UTF-8 showed as U+FFFD with no note, though edit refuses such a file.
• A page could be any size. 2,000 lines of an ordinary 3,000-line file came to 111,053 characters of JSON, and one 30,000-character line to 30,084. For a model's call the framework stores at most 24,000 characters whole by default. Past that it writes the whole result to a workspace file, where the agent has one, and stores only its start, cut mid-JSON.
• A direct mount, which main gained with feat(workspace): a read-only direct mount, reading disk as it is #564, reads the same way. A CRLF file's lines carry their CR, a 60,000-character line comes back as 60,083 characters of JSON with no note, and grep for two$ finds nothing.
• A read of a path the workspace held didn't look at disk. After another writer changed a file the workspace had read, a read showed the older copy: "v1", where disk held "v2 from another writer". Listings and edits already settle their paths first. A path the workspace didn't hold was observed, as it still is.

Changes

In src/modules/workspace/, using the resultMaxChars that #463 added to a tool call, with three doc comments and three other comments outside it.

• What the text is (text.ts's fileText, read-page.ts's textNotes). A line page shows a CRLF file's lines without the CR, and leaves out a BOM. A line whose own text ends in a CR shows its line end's CR too, as stored, so text copied from it matches in an edit. The page's note says when the file has CRLF ends or a BOM, counting a mix of CRLF and LF ends and the lines that show both CRs. It also says when the file isn't valid UTF-8: each invalid byte sequence shows as U+FFFD, edit refuses the file, and write replaces it whole. A character page still reads the stored text as it is, BOM and CRs included, and carries the UTF-8 note too.

• A long line is cut at 2,000 characters on a page for a call that carries a resultMaxChars, never inside a surrogate pair, with a marker that gives the offsetChars where its rest starts and the limitChars that reads the rest alone: [… read the rest with offsetChars=2000 and limitChars=500]. That offset is counted in the stored text as character paging reads it, BOM and CRs included.

• A bound on one page (linePage, characterPage). A line page is the longest page from its offset whose data, as JSON, fits the call's resultMaxChars, measured page by page, and a character page stops before its data would pass it. A call that carries none is made in process and takes the data itself, so its page holds to its line limit alone, with every line whole, as on main. Its note says where to continue: the offset after its last line, or the offsetChars a character page also gives as nextOffsetChars. A character page that stops short of what it was asked for gives the limitChars left of that too, so a reader that follows the notes ends where it asked to: "read the rest of what you asked for with offsetChars=X and limitChars=M". The read tool's description is main's, whose "Keep limitChars when continuing" holds for every other page. Where even a page's first line would pass, that line is cut shorter, at the most the page has room for. Where a page's last line is cut, by the 2,000-character cut or to fit, its note names the offsetChars and limitChars of that line's rest, before the next line's offset if the file goes on, since reading on in order starts there. A character page moves by whole characters, so it never stops inside a surrogate pair, and a range whose end would split one takes the pair whole. A page always moves on, so where its own fields (the path and its notes) and the least it can show pass a small cap, it passes the cap, and a character page that then holds all it was asked for names no stop. At 1,000 characters, with the first line cut to its least, that takes a path of about 680 characters with no notes, or of 93 to 129 beside all three notes on a file's text and a conflict's. A note saying disk couldn't be checked can name a symlink's target, and then takes as much room as the target is long.

• The disk check (bytesOf, on a store-backed mount). A read first settles its path against disk, under the three-way rule a listing uses, as handleEdit does:

  • Where disk changed and the stored copy didn't, the change is taken in, and the note says the read shows that text. A mode changed on disk alone is taken in with no note, as an edit takes it.
  • Where disk's copy couldn't be checked, or the check gave up because the selected branch kept changing, the note says why and that the read shows the workspace's copy. A read of a file the workspace doesn't hold answers instead that the file isn't in the workspace and that disk couldn't be checked, with why. Where the check gave up, either answer also says to read again.
  • Where disk has no copy and nothing records whether it was deleted there, the note says so, and that the read shows the workspace's copy, as edit's answer says.
  • A file disk deleted answers that disk deleted it and the deletion was taken in. A file disk made binary or too large answers that it's on disk but not stored.
  • Where the stored copy is a draft and disk changed or deleted it too, the read shows the draft, and the note names the conflict and the ways to settle it, by what disk holds now: where disk has a copy, a sync keeps it and gives up the workspace's; where disk deleted the file, a sync takes the deletion and removes the workspace's copy. A forced materialize writes the workspace's copy to disk, and the note offers it only on a mount that isn't read-only. A read-only mount can still hold a copy disk doesn't, such as one a branch switch selected.

  MountConfig.backend's doc for a store-backed mount now lists read among what takes disk's changes in.

  The pass names the path, as a file tool names the one it acts on, so a path the mount passes over by design, such as a file beneath an ignored directory, is observed as a sync naming it would observe it (workspace: bare mount-wide sync reports totalSynced: 0 while per-path sync on the same file works — bulk and per-path disagree about reality in both directions #276), as ensureSynced's pass is on main.

  readBinary still observes only a path the workspace doesn't hold, as does a deletion. A pass would drop a held binary file that disk changed, since the tree takes in no binary disk copy, and readBinary reads binary content. For a deletion, taking disk's change in first would let its push remove that change unseen, as for a write. ensureSynced's doc says both.

• Direct mounts (bytesOf, GrepText). A direct mount's read and grep show a file's text as a store-backed mount's do. bytesOf, which main added for direct mounts, now gives the read's notes with its bytes. On a store-backed mount it runs the disk check above in place of ensureSynced. On a direct mount it gives disk's bytes with no notes, since the mount keeps nothing else. handleRead sends both through fileText and linePage or characterPage. GrepText carries each file's bytes in place of a decoded string, so a direct mount's grep matches fileText's lines too, with lineEndings and the notes.

• grep searches fileText's lines, as read shows them, for matching as well as display: without a CRLF end's CR, except on a line whose own text ends in a CR, and without a BOM. It shows each line whole. So foo$ finds a CRLF file's line, as it does under ripgrep's --crlf, and a match copies into an edit as a read's line does. A file with CRLF ends says so in its result's lineEndings (CRLF, or mixed). The cost, which the changelog names, is that a pattern written to find the CR of a CRLF line end no longer matches, except on such a line. Where a pattern names a CR, a literal one or an escape for one such as \r or \x0d, and a file it searched has CRLF ends, the answer's note says how many files searched have CRLF ends and names them, each as CRLF or mixed, up to 20 and then how many more. It says that lines are matched as read shows them, which leaves out a CRLF end's CR unless the line's own text ends in a CR, and that a character read shows every CR in the workspace's copy. A pattern that names U+FEFF, over a file that starts with a BOM, gets a note that names the files that start with one and says a BOM isn't part of the first line. A conflict's disk version is named as that version. On a host with a direct mount, each note also names disk's file on a direct mount as where a character read shows the character, since a direct mount keeps no workspace copy.

• No tool's text changes. read's and grep's descriptions are main's, byte for byte. What this PR adds is said in each result where it applies: a line page's notes, the cut line's marker, a stopped character page's note, and grep's lineEndings and its notes on a pattern that names a CR or U+FEFF.

• fileText joins the text helpers feat(workspace): port hands-mcp's edit planner, and add edit_many, several edits stored all or none #463 added to text.ts (numberedLine, safeCut, hasBom, jsonLength), which the read's cut line and its budget use.

• Six comments outside the module. ToolCall.resultMaxChars (src/types/events.ts) says that for a call carrying none, the workspace's read holds its page to its line limit alone, while edit and edit_many answers keep the 24,000 default. executeToolCall's doc (src/framework.ts) names its one caller in the framework, the operator's puppet, which puts the agent's inline cap on the call. It named SubagentModule, which doesn't call it. The doc's reason for agent origin, and the comment by callTool's closure, now say its callers act for an agent: the puppet as the agent, and a host for the model it runs. executeToolCallFrom's comment on code_execution named SubagentModule's ephemerals as its callers too, and now names the puppet and a host through executeToolCall, and a module through callTool. Its comment on utils, and handleUtilsToolCall's doc, named code_execution scripts and ephemerals as reaching utilities through it. They now name the same callers as the comment on code_execution. The comment says that a call through executeToolCall reaches what its agent's allowedTools permits, as the model's does, and an unidentified caller is unrestricted, as executeToolCall's doc says, while a module's call is trusted and reaches every utility. The doc says that a script's calls take the model-facing dispatcher.

What each part is for

• The tools' text as on main. A model's request starts with its tool list, so a changed tool description makes every agent with the workspace's tools rewrite its whole cached context once, at its next request. Each thing this PR would have added to the descriptions is learned by calling, so the result says it, when the agent meets it.
• grep's notes on a pattern that names a CR or U+FEFF. With nothing in the description, a CR search that finds nothing in a CRLF file would read as a file without CRs, and a U+FEFF search on a file with a BOM, which on main was part of the first line, as a file without one. Each note comes only where that can mislead: a pattern that names its character, over a file that has it. A CR pattern over files without a CRLF end finds every CR, as on main. A pattern names a CR the usual ways it's written for a pattern compiled without flags: as a literal one, as \r, \x0d, \x0D, \u000d, \u000D, \cM, \cm or \015, or as a backslash before a literal CR. An escaped backslash before one doesn't count, so \\r gets no note. U+FEFF is named as a literal one, as \uFEFF in either case, or as a backslash before a literal one.
• The notes name the files. Whether a file has CRLF ends or a BOM is a fact about the file, not about a line, and grep matches what read shows, so \r$ and ^\uFEFF, which found those files on main, find no line here. The note on such a pattern is where an agent looks next, so it names the files, and the results stay matches. Past 20 files it gives the count of the rest and says to narrow with path or glob, so a large tree can't make the note large. A path is named once in each note, by the workspace's copy where that copy has the character. A conflict's disk version is named only where the workspace's copy lacks it, and then as that version, since read doesn't show it and the reader would otherwise look for the character where it isn't.
• The same reading on a direct mount. read and grep are one tool for one agent, so how a file's text is shown doesn't depend on where the mount keeps it. A direct mount changes where the bytes come from, not how they're shown. The disk check is a store-backed mount's alone, since a direct mount reads disk as it is.
• grep's notes name disk's file on a host with a direct mount. A direct mount keeps no workspace copy, so a note saying that a character read shows a CR or a BOM in the workspace's copy would point at nothing there. The notes keep naming the workspace's copy, since grep also searches a conflict's disk version, which read doesn't show. The wording follows the host, as the tools' descriptions mention direct mounts only on a host that has one (anyRunsDirect answers both), so a host without one keeps the notes as they were. On a host whose mounts are all direct, the second place is the one that applies. Choosing the wording by the mounts a call searched would be exact on a host with both kinds, but it would take more code for a mix that's rare.
• fileText, one reading of a file's lines for read and grep. Read, grep and the planner's matching then agree on what a line is, so text copied from either tool matches in an edit.
• A line whose own text ends in a CR shown as stored. edit reads a CR before a line feed in its old text as part of the line end. So a stored line x\r\r\n shown as x\r would lose its own CR when copied with the next line, and the copy would match elsewhere or nowhere. Showing such a line as stored, x\r\r, keeps a copy matching where it came from, and leaves every other line as it was.
• The notes rather than a second representation. A read shows lines as an edit matches them, and says what it left out: CRs, a BOM, bytes that aren't UTF-8. An agent that writes the file whole can see what its own text would change.
• A budget measured as the framework gives the result. jsonLength counts what JSON.stringify writes, so a page stops before it would pass any cap the framework sends, wherever the page's own fields and least content fit, and a script's read keeps its long pages.
• No budget for a call made in process. The budget fits a page to what its receiver keeps whole. A call made in process states none and takes the data itself, as connectome-host's file viewer does, with a byte cap of its own and no way to page, so its page is what main gives it.
• One rule for every call that states a limit. A script's line pages cut long lines and leave out CRs and a BOM, as a model's do. A character page gives the stored text exactly, and each cut line's marker names the offsetChars and limitChars that read its rest.
• The longest page that fits, measured page by page. A page's note changes with how it ends: the page that ends the file has no stop note, the one at the line limit a shorter one, and one whose last line is cut a longer one. So each candidate page is measured as it would go out, and the longest that fits is kept. The estimate this replaced stopped at the first page that didn't fit, so it cut a page short where a longer one fit. The search stops once a page passes the limit with only the notes every page carries, since a longer page shows more.
• The first line cut shorter, not refused. Every page moves on, and the note names where the cut line's rest starts.
• A cut last line named in the note. Reading on in order starts with that line's rest, so a note that named only the next line led a reader past it. An earlier cut line is named by its marker alone, since the page already shows the lines after it, and the marker gives both numbers that read its rest. The marker gives them in place of "N more chars", so the rest's length appears in it once, and the first-line cut's search keeps its bound. edit's excerpts, which nothing reads on from, keep their count. The note gives the rest's length as limitChars too, since a character read given offsetChars alone takes 2,000 code units and so reads on into lines the next page shows again. Where the rest runs past one character page, each page that stops for the result limit gives what's left of it as limitChars, so reading on as the notes say ends at the line's end, not the file's. It costs one clause in each note, the page that ends the file included, since a page whose toLine is the last line otherwise reads as complete. The first-line cut is now measured on the page itself, since the note depends on the cut, which takes a binary search of about eleven measurements of a one-line page. The rest's length is in the marker and in the note, so where one more character of cut drops a digit from it, the page can come out a character shorter, and the search alone can stop two characters short of the longest cut that fits. So the cuts up to four code units past the search's are measured too. The estimate it replaces reserved the longest note, so on a page that ends the file, which then carried none, the cut stopped short by that note's length. Leaving the rest to the line's own marker alone was the simpler choice, and an internal review's eleven findings on it showed it misleads.
• A conflict's way out read from what disk holds now (diskNow), not from the conflict's kind, since a recorded conflict keeps its kind after disk deletes the file. A sync there takes the deletion, so the note says so.
• The disk check, only for reads. A read of a path the workspace holds takes disk's change into the branch, as a listing already does; before, only a path it didn't hold was observed. A write and a deletion still don't, since each would then overwrite disk's change unseen, and neither does readBinary, which would lose a held binary copy. Anarchid's third review measured its cost. A held path that an earlier pass vouched for reads in about 0.2 ms, against 0.05 ms on main, flat from 500 to 4,000 files on the mount, and the first read of a path none vouched for writes one record of about 380 bytes, as ls does for such a file.
• storedOf in eight tests of workspace-three-way.test.ts. They read the store through read to see what a pass, a scan or a sync had or hadn't taken in, and a read now settles its own path, so it could take a change in itself. They read the store directly instead. Before, one of their assertions was that the read serves the store, which is the behaviour this PR changes.

Tests

On Linux, with Node 24.22.0 and npm 11.19.1, from a clean checkout with npm install as CI runs it.

At this head, b61d4e593, which has main 9fdc3a65 merged in:

• Each of its 58 commits since feat(workspace): port hands-mcp's edit planner, and add edit_many, several edits stored all or none #463's head e6556ad29 typechecks alone, its three merges of feat(workspace): port hands-mcp's edit planner, and add edit_many, several edits stored all or none #463 and its four merges of main included.
• The five workspace test files this change touches, with feat(workspace): port hands-mcp's edit planner, and add edit_many, several edits stored all or none #463's workspace-edits and workspace-edit-plan, pass 677 of 679, with 2 skipped: two tests in workspace-direct that run only where the temporary directory folds case. On Node 20.20.2, the five pass 557 of 559, with 2 skipped.
• New tests: one in test/workspace-text.test.ts, sixteen in test/workspace-read-text.test.ts, fifteen in test/workspace-file-tools.test.ts, ten in test/workspace-three-way.test.ts and three in test/workspace-direct.test.ts, with the 2,000-line default's test now run at a script's limit:
  • a CRLF file's lines without the CR, mixed ends counted, one line whose own text ends in a CR named in the singular, and a CR that doesn't end a line kept;
  • a BOM noted and not shown, and a file of only a BOM read as an empty file with one;
  • invalid UTF-8 noted on both kinds of page;
  • a long line cut before an emoji's surrogate pair, at a model's limit and at a script's, with an offsetChars that reads exactly the rest past a BOM and a CRLF, which the note names too where that line ends the page;
  • line pages within 24,000, 5,000 and 1,000 characters, one more line passing each, and the note's offset reading on;
  • a page that ends the file, a page at the line limit, and a page a line past a cut line, each fitting where the page a line shorter, with its stop note, doesn't;
  • a CRLF file's line pages and an invalid-UTF-8 file's character pages held to the limit with their notes, and a generated file read under a result limit;
  • a first line cut at the most that fits within 1,000, its note naming the rest, on a page that goes on and on a one-line file's page, which ends the file, and a one-line file whose whole page fits shown whole, where a cut one character shorter wouldn't fit;
  • a first line cut at the longest cut that fits at each limit from 700 to 760, across the cut where the rest's length loses a digit, and kept within 2,000 characters at a limit where a cut past it would fit;
  • a long line cut to fit as the first line of a page read from line 3, numbered as line 3, its rest's offsetChars counted past lines 1 and 2, with a note whose offsetChars and limitChars read exactly the rest of the line;
  • a page whose last line is cut, stopped by its limit, by the result limit and by the end of the file, naming that line's rest and its length, and a page that ends the file on a whole line with no note;
  • a cut line's 5,000-character rest read at a limit of 1,000 through several character pages, following only their notes, and ending exactly where the line does;
  • a call that carries no resultMaxChars paging by its line limit alone, with a 3,000-character line whole, and its character page giving 100,000 characters whole;
  • character pages of escape-heavy text within 24,000 and 1,000 that put the whole text back when each page's note is followed, and pages that never stop inside a pair and stay within each of four neighbouring limits;
  • grep's CRLF, mixed, LF and BOM files, and a pattern that names a CR finding nothing in a CRLF file, with a note saying why, for each spelling of a CR, over a directory where an LF file comes on each side of the CRLF one, and not where a glob passes over it and finds the file it takes; a CR inside a line found with no note, and identity escapes such as \X0D and \CM, and an escaped backslash, naming no CR;
  • a pattern that names U+FEFF finding nothing in a file that starts with a BOM, with a note saying why, over a directory where a file without one comes on each side of it too, and a U+FEFF inside a line found with no note, neither note given for the other's file, and a pattern that names both getting both notes;
  • fileText's lines, starts and counts for CRLF, LF, mixed ends, a lone CR, a line whose own text ends in a CR, a line ended by a bare LF with a CR before its last character, a BOM, an empty text and invalid UTF-8;
  • the disk check's answers (disk's newer text, a deletion, a file disk made binary, a conflict, a draft disk deleted, a conflict recorded as both-changed before disk deleted the file, a draft whose disk copy turned binary, an unchecked copy, a missing copy with no record), each on a line page, and the taken-in note on a character page too;
  • a sync and a forced materialize each doing what the deletion conflict's note says, and a sync doing what the note says where disk's copy turned binary: the draft goes, and disk keeps its bytes;
  • a read of a held file, and of a file only disk has, whose disk check gives up because the selected branch switches at every disk read, each saying to read again, and a read after the mount's root is gone, which doesn't;
  • readBinary serving a held binary file that disk changed as the workspace holds it;
  • a read of a held file beneath an ignored directory, and of one ignored by its own name, taking disk's change in first and then disk's deletion;
  • two lines copied from a read of a CRLF file with a BOM, and a line copied from a grep match, each matching in an edit, with the file keeping its CRLF ends and its BOM;
  • two lines whose own text ends in a CR, copied from a read, and such a line copied from a grep match, each editing the lines it came from;
  • a limit of 50, too small for a page's own fields, still moving a character page on, by both code units of a surrogate pair, and showing a first line's marker, and a character page that then holds all it was asked for with no stop note;
  • a read of a held file whose mode alone changed on disk, with no note;
  • a read of a conflict on a read-only mount, whose note names only the sync;
  • a direct mount's read of a CRLF file, a file with a BOM, one that isn't valid UTF-8, one with mixed ends and a line whose own text ends in a CR, a 60,000-character line and a 3,000-line file, as line and character pages at result limits of 24,000 and 1,000 and with none, and its grep over CRLF, mixed, LF and BOM files with the notes on a pattern for a CR or U+FEFF, each giving a store-backed mount's answers but for the notes' mention of disk's file on a host with a direct mount, and each page with a result limit a page that fits it;
  • grep's notes on a store-backed mount beside a direct one naming disk's file too;
  • grep's notes for \r$ and ^\uFEFF over a tree of LF, CRLF, mixed and BOM files naming exactly the CRLF, mixed and BOM files, with a binary file and one over the size limit, each with CRLF ends and a BOM, listed as skipped and named in neither note, 23 CRLF files named as the first 20 and 3 more, and a glob narrowing them to 3;
  • a conflict whose workspace copy and disk version both have CRLF ends and a BOM named once in each note, as the workspace's copy; one whose workspace copy starts with a BOM and whose disk version has CRLF ends named in each note for the version that has it; one whose disk version alone has CRLF ends named as that version; and a recorded disk version, once disk has changed again, named as the recorded one in each note;
  • a conflict's disk version with CRLF ends found by grep, with its lineEndings, and a CR pattern's note where only that disk version has CRLF ends, a U+FEFF pattern's note where only a conflict's disk version starts with a BOM, and the give-up note on a character page and on a line page under a result limit.
• fix(workspace): the watcher and a sync agree on what a mount passes over, and an outer mount leaves a nested mount's directory alone #460's three workspace: bare mount-wide sync reports totalSynced: 0 while per-path sync on the same file works — bulk and per-path disagree about reality in both directions #276 tests in test/workspace-three-way.test.ts, which read a file the mount passes over by design that the store doesn't hold, now cover read's own pass, with the two held-file tests above. On the rebased branch before eec578167, each workspace: bare mount-wide sync reports totalSynced: 0 while per-path sync on the same file works — bulk and per-path disagree about reality in both directions #276 read answered that disk "could not be checked", because the path was "ignored by the mount" or "an editor's swap or backup file". With { named: true } taken out, all five fail.
• Red-first: with the disk check undone in bytesOf, whose store branch then calls ensureSynced as on main, its fifteen read tests fail, and the other 427 tests in workspace-file-tools and workspace-three-way pass. readBinary's test is among those that pass, since it pins what readBinary did before this change.
• With a direct mount left on main's read and grep, and the rest of the merge as it is, the new read and grep tests in workspace-direct fail, and every other test in the five workspace files passes.
• Removals: each of 99 deliberate removals or breakages, made one at a time, fails a test that names it.
• On a direct mount that takes writes, which main gained with feat(workspace): a direct mount can be written, and a head move away from its writes is told once #719, and on a 'chronicle' one, an edit whose oldString is lines 2 and 3 as read shows them, in a file with CRLF ends, one with mixed ends, one with a BOM, one with lines whose own text ends in a CR and one with a lone CR, replaces those two lines and leaves the same bytes on disk on both kinds, at this head and on main.
• On a FUSE file system that folds case, on Linux, workspace-path-spelling passes 56 of 61. Of the other 5, four run only where the disk tells case apart, and one only where a disk that folds case keeps ß apart from ss.

With main 9fdc3a65, which this head holds (tree b35fc1e1dbf3), from a fresh install with no lockfile, as CI installs:

• tsc --noEmit and the build are clean.
• CI's npm test passes 6,597 of 6,641, with 44 skipped, in 219 s on a 12-CPU host at a load average between 8 and 19. CI's unforced step passes 132 of 132.
• Each of the 286 test files, run on its own without --test-force-exit, passes: 6,597 tests pass and 44 are skipped, as under CI's step.
• On Node 20.20.2, the five workspace test files this change touches pass 557 of 559, with 2 skipped.
• main has since moved to f4bcb1d1 (feat(retry): the framework is the one retry layer for its turns #728, the framework as its turns' one retry layer), which merges with this head with no conflict.

Out of scope

• read_image. The workspace serves it itself (handleReadImage), and the framework calls that handler rather than readBinary. It still reads a held image from the tree first, without settling, as before. This PR leaves images as they are.
• grep's answer isn't held to resultMaxChars. The page bound here is read's.
• A conflict on a path the workspace doesn't hold is still worded as the workspace having deleted the file and disk having changed it since (notInWorkspace, unchanged here). The rarer interrupted kind doesn't fit that wording.

Open pull requests this meets

Trial merges of each of the 55 other open pull requests, at their heads of 04:57Z on Oct 23, with main 9fdc3a65 and with this head, which holds that main:

• feat(lifecycle): add irreversible resident retirement primitive #116 conflicts with both in README.md, src/agent.ts and src/framework.ts. In src/framework.ts, this change's comment on code_execution in executeToolCallFrom falls inside one of its conflicts, and the four other comments it rewrites there merge cleanly.
• feat(workspace): direct backend (default), watch tool, write { append } #271 conflicts with both in src/modules/workspace/index.ts, src/modules/workspace/sync.ts and src/modules/workspace/types.ts. In index.ts, this change's two import lines and ensureSynced's doc fall inside its conflicts, and so do some of its lines in handleRead and by grep's note. Its other lines there merge cleanly. In types.ts, this change's two lines in MountConfig.backend's doc fall inside the conflict feat(workspace): direct backend (default), watch tool, write { append } #271 already has with main there.
• Each of the others conflicts with this change in the same places as with main, if anywhere. fix(workspace): glob and grep's glob filter take a mount-prefixed pattern #401, feat(workspace): a mount's include names the files it holds, and is its boundary #536, feat(workspace): a read-only direct mount, reading disk as it is #564 and feat(code-execution)!: code_execution runs JavaScript in the isolate, and the Python runner goes #608, which this change met before, have merged, and feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255 has closed.

Not verified

• Against a live provider: a model's actual reading of the notes and the cut-line marker, and whether it takes a stopped character page's limitChars over the description's "Keep limitChars when continuing".
• The rest of the suite on a case-insensitive disk.

---

Reviewed in the house: an internal review of the change and one of its fix round, a third of everything since, the rebases' resolutions included, a fourth of that review's fix round, a fifth of the whole change at 60e17484a, whose findings 723580051 answers, a sixth of the two rounds since, 60e17484a..bf379817f, whose findings dcb7968c1 answers, a seventh of what followed 694421a15, that answer and the round that leaves the tools' text as on main, whose findings 456e5db1b and 8db582022 answer, an eighth of that fix round, whose findings 7d02af8d7 and ac6f05d8f answer, a ninth of everything since, the merge of main included, whose findings 2a2b02ead, 2226bf1e5 and 677715d09 answer, a tenth of that fix round, whose findings 24b507d6b, 766f9fa75 and a40712ef3 answer, and an eleventh of the tenth's fix round and the answer to Anarchid's fourth review, whose findings 786cdc1b4 and deac5132c answer. The rebases onto #463's later heads changed this PR's code only where the two meet: the imports, the generated-file branch of handleToolCall, text.ts's header comment, where two tests sit, and, onto 4da02df83, the start of handleRead and the doc comments of ensureSynced and ToolCall.resultMaxChars. Its merges of #463's 8b039203c, 39d0151d4 and e6556ad29 resolve nothing by hand. Its merge of main at b0b13d3c1, 4c6171c0a, resolves four conflicts by hand, in readBinary's doc, the start of handleRead and two places in grep, so that a direct mount gets this change's read and grep. Its merge of main at 97ca7eba4, dd1dcd66a, resolves two conflicts by hand, both in comments: executeToolCallFrom's on code_execution, and ToolCall.resultMaxChars's doc, which keeps main's account of a script's limit with this change's last sentence. Its merge of main at 5834c2c4, 107406a95, resolves three by hand: ensureSynced's doc, which keeps both sides' sentences, bytesOf, which keeps this change's, and two sets of tests at one place, which keep both. Its merge of main at 9fdc3a65, b61d4e593, resolves one by hand, in MountConfig.backend's doc, which keeps this change's sentence for a store-backed mount and main's for a direct one, which now takes writes; handleGrep is main's, with its mount-prefixed reading of the glob filter (#401), with this change's lines on top. Cuthbert-2453 read its code and description at 244a0d360, each commit since then but the merges, and the last rebase's resolutions. cd7f83b83's doc comment and changelog sentence are his wording, taken after his read, and so is 22becb53d's doc comment for linePage, whose page he compared, on 40,000 generated files, with one found by measuring every page. The held-file tests in eec578167 are cases he probed. He checked the fifth review's fix for lines whose own text ends in a CR by copying such lines from reads of eight files and editing them back, and each edit landed where its text came from. For the answer to Anarchid's second review, 723580051..bf379817f, he ran its linePage beside a copy that tries every cut, on 106,640 generated cases, and the two gave the same page in each. He read the sixth review's fix round, and caught a wrong claim in one of its commit messages, reworded before the push. He read the round that leaves the tools' text as on main, checked both tools' entries against main's line for line, and ran its linePage beside the copy that tries every cut again, on 106,640 cases, with the same page in each. 813c60dd1 makes grep's CR note take the escapes for a CR that he found it missed. He read the fix round after it too, and ran its pattern check beside regexpp, a parser for JavaScript's regular expressions, on 278,593 generated patterns, and the two agreed on every one. He read the eighth review's fix round as well. He read the merge of main and its resolution, comparing bytesOf's store branch with the inline disk check it replaced line for line, and pointed out that the notes named a workspace copy that a direct mount doesn't keep. He read both fix rounds since. He read the answer to Anarchid's fourth review, checking that no file is named twice or missed across mounts, globs and conflicts, and caught a comment that described the disk version's rule wrongly. He read that round's fix round, and the merge of main at 97ca7eba4 with what follows it, where he caught a stale figure for a script's limit in the changelog. He read the merge of main at 5834c2c4 and its text after F341, and suggested 8b46eac2a, which has read decide that its pass decided nothing with main's undecidedOf, as the other file tools do, and read it too. For this change, he was the first to run workspace-path-spelling on Tabitha-2696's FUSE file system that folds case. Gordon-2414 read the merge of main at 9fdc3a65 against #401's grep and glob, and traced that the CRLF and BOM note names files in the order the results list them, on each kind of mount.

Written by Abigail-2676, from part 2 of Ada-1017's design for the workspace's file tools, split from #463 with Cuthbert-2453. Phoebe-2419 pointed out that a recorded conflict keeps its kind after disk deletes the file, which is why the conflict note's ways out follow what disk holds now, and her measurement of what a changed tool description costs an agent's prompt cache is why this change leaves the tools' text as on main.

🤖 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 file reading and editing within workspace workflows.

The PR appears safe to merge, with non-blocking improvements needed for edit speed and unfinished-read warnings.

Findings

1.  Clash checks repeat comparisons ▶
2.  Receipts repeatedly scan every change ▶
3.  Unfinished disk checks stay hidden ▶

Fix with agent prompt

### Issue 1
src/modules/workspace/edit-plan.ts:379-384
`planFile` keeps comparing overlapping spans after `named` has already recorded their clashes. For example, 100 edits matching `x` 10,000 times in a 20 KB file create 1,000,000 spans and 49,500,000 inner-loop passes to report just 99 problems. This work runs while other agents wait.

Use a single pass over the sorted spans, or bound the work before building them. Limiting reported clashes does not limit the comparisons.

### Issue 2
src/modules/workspace/edit-text.ts:329-334
`otherReplacements` filters all of `plan.changes` once per edit, even after collecting the 20 notes it will show. A successful batch with 500 edits and 100 replacements per edit scans 50,000 changes 500 times to prepare its receipt. That adds work after the files are already stored.

Group changes by `edit` in one pass and build the notes from those groups.

### Issue 3
src/modules/workspace/index.ts:2221-2224
When branches keep changing during a read, `reconcilePass` can return empty `reports` with an `incomplete` reason and take in nothing from disk. `handleRead` ignores that reason and returns stored text without a warning, or a plain not-found error. The caller cannot tell that the disk check did not finish.

Carry the reason into the read's note or error, or retry the check.

---

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

Summary

This PR gives tool calls a result budget and uses it to build bounded workspace reads and edit answers.

• Read and grep show the same clean lines from text files.
• Read pages fit the result size their callers can receive.
• Reads check held files against disk before showing their text.
• Workspace edits can plan exact replacements together, including across files.

_{Reviews (1) · Last reviewed commit: "docs(workspace): grep follows ripgrep's ..." · Reviewed by Greptile}

[greptile-apps]

Clash checks repeat comparisons

planFile keeps comparing overlapping spans after named has already recorded their clashes. For example, 100 edits matching x 10,000 times in a 20 KB file create 1,000,000 spans and 49,500,000 inner-loop passes to report just 99 problems. This work runs while other agents wait.

Use a single pass over the sorted spans, or bound the work before building them. Limiting reported clashes does not limit the comparisons.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/edit-plan.ts
Line: 379-384

Comment:
**Clash checks repeat comparisons**

`planFile` keeps comparing overlapping spans after `named` has already recorded their clashes. For example, 100 edits matching `x` 10,000 times in a 20 KB file create 1,000,000 spans and 49,500,000 inner-loop passes to report just 99 problems. This work runs while other agents wait.

Use a single pass over the sorted spans, or bound the work before building them. Limiting reported clashes does not limit the comparisons.

---

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

[nissa-seru]

Addressed in d92344b9e, in #463, which this PR is stacked on. A replacement whose edit is already in named can't add a clash, so the clash scan now links past it the first time it meets it (nextLater, src/modules/workspace/edit-plan.ts:519). Each later scan then crosses a run of such replacements in one step. On 160,040 generated cases, the two versions gave the same plans, and the same problems in the same order.

I timed your example on Linux with Bun 1.4.3: 100 edits replacing x in a 20 KB file of 10,000 xs. The planner took 2.96 to 3.09 s at a3eaa3334, the commit before it, and 0.19 to 0.20 s at d92344b9e, with the same 99 problems. A test at test/workspace-edit-plan.test.ts:157 plans 2,000 edits of one text at 500 places in a child process with a 5 s timeout, and checks its 1,999 problems. This PR's head carries the commit.

Written by Abigail-2676.

— Tabitha-2696

[greptile-apps]

Receipts repeatedly scan every change

otherReplacements filters all of plan.changes once per edit, even after collecting the 20 notes it will show. A successful batch with 500 edits and 100 replacements per edit scans 50,000 changes 500 times to prepare its receipt. That adds work after the files are already stored.

Group changes by edit in one pass and build the notes from those groups.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/edit-text.ts
Line: 329-334

Comment:
**Receipts repeatedly scan every change**

`otherReplacements` filters all of `plan.changes` once per edit, even after collecting the 20 notes it will show. A successful batch with 500 edits and 100 replacements per edit scans 50,000 changes 500 times to prepare its receipt. That adds work after the files are already stored.

Group changes by `edit` in one pass and build the notes from those groups.

---

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

[nissa-seru]

Addressed in 706da54a7, in #463, which this PR is stacked on. A file's plan now keeps one entry per edit, with its first replacement, its count and the lines a receipt names (EditChanges, src/modules/workspace/edit-plan.ts:339). otherReplacements builds its notes from those entries and no longer filters every change for each edit (src/modules/workspace/edit-text.ts:375).

I timed your example on Linux with Bun 1.4.3: 500 edits, each replacing all 100 occurrences of its own token, so 50,000 replacements in a 244 KB file. Building the receipt took 53 to 74 ms at 6a1d0e3d9, the commit before it, and 2 ms at a3eaa3334, that pull request's head (12 ms in one of six runs). Both gave the same receipt. This PR's head carries both commits.

Written by Abigail-2676.

— Tabitha-2696

[greptile-apps]

Unfinished disk checks stay hidden

When branches keep changing during a read, reconcilePass can return empty reports with an incomplete reason and take in nothing from disk. handleRead ignores that reason and returns stored text without a warning, or a plain not-found error. The caller cannot tell that the disk check did not finish.

Carry the reason into the read's note or error, or retry the check.

Knowledge Base Used: Workspace synchronization module

Prompt To Fix With AI

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

Comment:
**Unfinished disk checks stay hidden**

When branches keep changing during a read, `reconcilePass` can return empty `reports` with an `incomplete` reason and take in nothing from disk. `handleRead` ignores that reason and returns stored text without a warning, or a plain not-found error. The caller cannot tell that the disk check did not finish.

Carry the reason into the read's note or error, or retry the check.

**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 d4fa18ca9. When a read's disk check gives up because the selected branch kept changing, the read now says so, with the check's reason (src/modules/workspace/index.ts:2228). For a file the workspace holds, it shows the workspace's copy with the note "The path couldn't be checked against disk (the selected branch kept changing while the scan ran), so this read shows the workspace's copy." For a file only disk has, it answers "work/b.txt is not in the workspace, and disk could not be checked (the selected branch kept changing while the scan ran)."

Two tests in test/workspace-three-way.test.ts, at lines 3830 and 3842, switch the selected branch at every disk read, as the ls test above them does. Each fails with the change taken out.

ensureSynced's other callers, readBinary and a deletion, still read such a check as finding nothing, as on main. #282, at its head 40beba72b, makes ensureSynced itself report such a check as unverified, with its reason.

Written by Abigail-2676.

— Tabitha-2696

[Anarchid]

Nightly dual review · round R1 at 6285a3a · 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: CHANGES_REQUESTED (the formal review event is left to the maintainer). Finding ids R1-n are stable; cite them in fix commits.

Reviewed at 6285a3a against main e670363

Scope. As the description asks, this covers only the six commits this PR adds on top of #463's head d92344b9e (src/modules/workspace/{index,read-page,text}.ts, four test files, one changelog fragment: +809/−125). #463's ten commits are reviewed there. The "+3.9k" figure against main includes #463. GitHub reports the branch as conflicting with main at the head above, so "will it run" is judged on a trial merge into that main, not on the PR's original base. This is our first review of the PR; there are no earlier findings to account for.

Verdict: changes requested (0 blockers, 2 major, 2 minor)

The paging core holds up. Every page I generated stayed within its limit, every line was covered exactly once, and every offsetChars a marker or note names points at the rest of its line in the stored text, BOM and CRs included. The disk check is coherent and held under the mount's turn. The problems are in how the change meets everything else. Resolved the way the description proposes, the merge with main undoes #460's fix for reads. A caller that doesn't pass resultMaxChars (connectome-host's file viewer does this today) now gets about 24,000 characters where it used to get up to 5,000 lines, and it has no way to page. And at the end of a file, the structured fields say "complete" while the line says otherwise.

On the desk's question, whether read behaviour is preserved for callers: the result fields and defaults are preserved. The content is not, and the changelog says so for CRs, the BOM and long lines. It doesn't say so for in-process callers (R1-2) or scripts (R1-4). Notes are accurate at page boundaries and at cut lines mid-file. The one boundary where they fall silent is a cut line that ends the file (R1-3).

Major

R1-1. Resolved as described, the merge with main drops #460's named pass for read, and reads of files the mount passes over by design fail again. (Found by both reviewers independently.)

• Evidence: on main, every file tool's pass on its own path is named: ensureSynced calls passUnlocked(..., { named: true }) (main:src/modules/workspace/index.ts:2179), and so does settleBeforeMutation (:2164). Without it, reconcile.ts:726 (} else if (!opts.named) {) leaves a path under an ignore entry, or an editor's backup file, unobserved. This PR replaces ensureSynced in handleRead with a direct this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }) (src/modules/workspace/index.ts:2224), which has no named. The textual conflict is only at parsePath/parseFilePath and the doc comment, so the missing option doesn't show up as a conflict.
• Reproduced: I merged this head into main and resolved the handleRead conflict the way "Open pull requests this meets" proposes (this change's body with #460's parseFilePath call). #460's reads, edits and deletes a file … that the store doesn't hold, as a sync naming it takes it in (#276) then fails for all three kinds (beneath an ignored directory, ignored by its own name, an editor's backup file), each at the read call. With { named: true } added to that one pass, the read step passes. The edit step then fails in the same way; that is #463's edit pass, which needs the same option when #463 is rebased. With both added, one test still fails: an edit of a path the ignore list covers sees the disk version its settled adoption takes in too, also #463's. All of workspace-file-tools, workspace-read-text, workspace-text, workspace-edits and workspace-edit-plan pass on that merged tree.
• Failure: an agent reads work/build.log (ignored by the mount, not held). main takes it in and shows it. After this PR merges as described, it answers "is not in the workspace, and disk could not be checked (ignored by the mount)". That is exactly the regression #460 fixed. A held file under an ignore entry would instead get the "couldn't be checked against disk" note and its stored copy.
• Fix: when rebasing, call this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, { named: true }) in handleRead, keep parseFilePath(input.path) so the other-mount refusal comes first, and keep { named: true } in ensureSynced. #460's #276 tests in workspace-three-way.test.ts are the check. It is worth one line in "Open pull requests this meets" too, since #463's edit pass needs the same treatment.

R1-2. A call without resultMaxChars is now held to 24,000 characters, which cuts connectome-host's workspace file viewer down sharply, and that viewer cannot page.

• Evidence: const resultMaxChars = call.resultMaxChars ?? DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS (src/modules/workspace/index.ts:1407). The framework sets resultMaxChars on every call it dispatches (src/framework.ts:14391, :15913, :20102), so the 24,000 default only ever reaches in-process callers, whose results the framework doesn't store. connectome-host (main ac2e8bf) has two such callers. sendWorkspaceFileRead (src/modules/web-ui-module.ts:2424-2445) calls handleToolCall({ name: 'read', input: { path, limit: 5000 } }) with its own 256 KB byte cap and no resultMaxChars. The headless request-workspace-file handler (src/headless.ts:402-430, which the fleet module uses for child processes) does the same. The request message carries only path and scope (src/web/protocol.ts:1027-1032), so neither caller can ask for a second page.
• Measured: read the way the viewer reads it, this repo's src/modules/workspace/index.ts (3,780 lines, 177 KB) returned toLine: 543 at this head. Before, it returned all 3,780 lines, under the viewer's 256 KB cap. The viewer reports truncated: true and shows the first 14% of the file. Lines over 2,000 characters also show the in-line [… N more chars; …] marker, which the viewer renders as file text.
• Failure: once connectome-host takes an agent-framework release that includes this change, an operator opening a medium-sized source file in the WebUI sees a few hundred lines and has no way to see the rest.
• Fix: decide what a missing resultMaxChars means and say it in the changelog. The PR's rationale for the budget is what the framework stores whole, which doesn't apply to an in-process caller. So either (a) apply only the line limit when resultMaxChars is absent, as before, or (b) keep the 24,000 default and add a changelog sentence that in-process callers (handleToolCall, ModuleContext.callTool) now get bounded pages and should pass resultMaxChars, with connectome-host's two callers changed to pass it before the release reaches them. (b) keeps the contract #463 already documents on ToolCall.resultMaxChars. Either way, the changelog currently mentions the "carries none" case only in passing, and nothing in it tells an in-process caller its pages changed.

Minor

R1-3. A line cut at the end of the file gets no note, so toLine === totalLines reads as complete. (Sol found this; I corrected it.)

• Evidence: final() picks to === last ? (to < total ? limitNote(to, rest) : null) : budgetNote(to, rest) (src/modules/workspace/read-page.ts:96). When the page ends the file, the note is null whether or not rest is set. Reproduced: a one-line file of 1,500 " read at a limit of 1,000 returned 999 characters, totalLines: 1, toLine: 1, no note, and a cut line whose marker names offsetChars=433. A file whose last line is 3,000 characters behaves the same way at the default limit.
• The changelog says "Where a page's last line is cut, its note names the offsetChars where that line's rest starts" with no exception. The description and the tests (test/workspace-read-text.test.ts, "a page that ends the file with no note") treat the end of file as one. A model will probably see the in-line marker. A program that checks toLine < totalLines, as connectome-host's viewer does for truncated, won't.
• Sol also said that with limit: 1 a budget-cut first line leads a reader past its rest. Rejected: the note there reads Truncated at 1 lines (file has 2). Line 1 is cut: read its rest with offsetChars=742. Use offset/limit to read more. It names the rest. The only issue there is wording: the cut was made for the result limit, not the line limit.
• Fix: when rest !== null at the end of the file, emit Line N is cut: read its rest with offsetChars=K. The first-line search already measures final(), so the extra clause stays inside the budget. Alternatively, qualify the changelog sentence ("…except on the page that ends the file, where only the line's own marker names it").

R1-4. The 2,000-character line cut ignores the call's limit, so a script's 5,000,000-character call still gets cut lines.

• Evidence: shown() always cuts at MAX_LINE_CHARS (src/modules/workspace/read-page.ts:60), whatever maxChars is. The changelog's sentence about scripts ("its pages still stop at 2,000 lines or limitChars, unless a page would pass that") reads as if a script's reads were unchanged. But a script that reads a minified bundle or a one-line JSON file through read now gets content with an in-line [… N more chars; read them with offsetChars=K] it can't tell from text. Together with the CR and BOM changes, a script that rebuilt a file from line pages now gets different bytes.
• Fix: either lift the cut when the call's limit is large enough to hold the line (for example, cut at max(MAX_LINE_CHARS, …) scaled to maxChars), or add to the scripts sentence that lines are still cut at 2,000 characters and that offsetChars/limitChars is the path for raw text.

Verified fine

• Result shape and inputs: a line page still returns path, totalLines, fromLine, toLine, note?, content, and a character page path, totalChars, offsetChars, nextOffsetChars, content with an optional note added. The defaults (2,000 lines, 2,000 characters), the "not both" error, the surrogate-pair offsetChars error and the empty-file and past-the-end answers are unchanged. Validation still rejects zero, negative, fractional and NaN values before a read.

• The budget measures what the framework stores: pages are measured with JSON.stringify(data), which is exactly what history stores (src/tool-result-history.ts:57) and what the spill compares with the limit (src/framework.ts:15170).

• Boundaries, by generated walks rather than by hand. I generated 12 files: BOM or none; LF, CRLF and \r\r\n ends; lone CRs; quotes, backslashes, control characters, a tab, é and emoji; lines up to 6,000 characters; a trailing newline or none. I paged through each by following each page's note, at limits of 700, 1,000, 5,000 and 24,000, by line page (default limit and limit: 3) and by character page. Results:

  • No page passed its limit.
  • Every line was covered exactly once.
  • Each continuation offset was toLine + 1.
  • Each cut line's offsetChars and "N more chars" matched the stored text exactly, and note and marker always named the same offset.
  • Character pages put the stored text back exactly.

  At limits of 60 to 450, pages pass the limit only in the way the changelog describes, and paging always moves on.

• First-line search: the binary search terminates. Below the whole-line case, the measured page length doesn't decrease as the cut lengthens: each step adds at least one character of content, and the "more chars" count loses at most one digit.

• fileText: starts index the decoded text with the BOM and CRs included. Only a leading BOM and the CR directly before an LF are left out of a line. Invalid UTF-8 is decoded the same way for line and character pages, so offsets agree between the two.

• Disk check: the pass and the tree/blob read happen inside withMount. A draft survives a conflict and the read shows it. readBinary and deletion keep ensureSynced. A check that gave up (the branch kept changing) is now reported, which answers Greptile's comment.

• grep: it shares fileText with read, so line numbers and text agree. lineEndings is CRLF or mixed exactly when the counts say so. The pattern is built with no flags, so test() carries no lastIndex from line to line.

• Tests at this head: the four touched workspace test files plus #463's workspace-edits and workspace-edit-plan pass 334 of 334 on Node 22, as the description reports for Node 24. tool-call-result-max-chars passes 5 of 5, the full npm test passes 2,738 of 2,738 on Node 22, and CI is green on all four Linux/macOS × Node 20/24 jobs.

---

_{Method. Two independent passes, merged after every claim was re-checked. Sol (Codex gpt-5.6-sol, reasoning effort xhigh, read-only sandbox, no network) reviewed d92344b9e...6285a3a8 from a checkout of this head, with main available locally. It ran 58 commands in 9.3 minutes, read 3.35M input tokens (3.18M cached) and wrote 21.5k output tokens. Its filesystem-backed tests couldn't run in its sandbox (read-only /tmp), and it had no access to downstream repositories. Claude (Opus 5.5) did the merge and downstream work: a trial merge into current main with #460's tests run, connectome-host's main searched for in-process read callers, generated paging walks run against the built module, the full test suite run, and existing review threads and CI state read. Who caught what: R1-1 was found by both independently. R1-2 and R1-4 were Claude only. R1-3 was Sol's: its end-of-file case is confirmed and adopted, and its limit: 1 case is rejected because the note names the rest. Sol's other conclusions (shape preserved, budget measured as stored, surrogate safety, search monotone, lock held, drafts kept) agree with mine and are under "Verified fine".}

[nissa-seru]

Replying to this review.

Addressed R1-2, R1-3 and R1-4 in 77b88c4e4 and 795f422da, on #463's d92344b9e. R1-1 isn't in this push: this branch is on d92344b9e, which doesn't have #460. The description's bullet on it says how that merge resolves.

R1-2. A call that carries no resultMaxChars now pages by its line limit alone, with every line whole, as on main (src/modules/workspace/read-page.ts:77). Its character page gives limitChars whole (:174). Read with limit: 5000 and no resultMaxChars, as connectome-host's file viewer reads it, this head's src/modules/workspace/index.ts comes back whole, all 3,783 lines. The ToolCall.resultMaxChars doc says so for read, while edit and edit_many answers keep 24,000, and the changelog names in-process callers. The test at test/workspace-read-text.test.ts:190 reads 2,500 lines of a 3,000-line CRLF file with its 3,000-character line whole, and a 100,000-character character page whole.

R1-3. The page that ends the file now names a cut last line's rest (src/modules/workspace/read-page.ts:102). Your case, one line of 1,500 " read as work/quotes.txt at a limit of 1,000, now returns "note": "Line 1 is cut: read its rest with offsetChars=401." within the 1,000 characters. A file whose last line is 3,000 characters, read at 24,000, names offsetChars=2006. The tests at test/workspace-read-text.test.ts:152 and :184 pin both cases, and :187 pins a page that ends on a whole line with no note.

R1-4. The changelog's sentence on scripts now says their line pages cut a line over 2,000 characters and leave out CRs and a BOM, as a model's do, and that a character page gives the stored text exactly. We kept the cut, so every call that states a limit gets the same line pages, and each cut line's marker names the offsetChars that reads its rest.

At this head, 795f422da, on Linux with Node 24.22.0, tsc --noEmit passes at each commit. The workspace test files this change touches, with workspace-edits and workspace-edit-plan, pass 334 of 334. On Node 20.20.2, this change's four pass 279 of 279.

Written by Abigail-2676.

— Tabitha-2696

[nissa-seru]

Replying to this review.

Addressed R1-1 in eec578167. This push rebases the branch onto #463's 4da02df83, which merges main in, #460 included. The commits that answered R1-2 to R1-4 are now 83aae2881 and cd7f83b83, with the same changes.

R1-1. read's own pass over its path now names the path with { named: true }, as ensureSynced's pass has since #460 (src/modules/workspace/index.ts:2703). A read of a file the mount passes over by design now observes it as a sync naming it would, whether the store holds the file or not.

• A file the store doesn't hold. The tests for workspace: bare mount-wide sync reports totalSynced: 0 while per-path sync on the same file works — bulk and per-path disagree about reality in both directions #276 at test/workspace-three-way.test.ts:907 read one in three cases: beneath an ignored directory, ignored by its own name, and an editor's backup. All three failed on the rebased branch before this commit, where each read answered that disk "could not be checked", because the path was "ignored by the mount" or "an editor's swap or backup file".
• A file the store holds. Two new tests beside them (:934) read one beneath an ignored directory and one ignored by its own name. Each read takes disk's change in first, says so and stores it, then takes disk's deletion in first.

Taking { named: true } out again fails all five.

At this head, fd7a44b49, on Linux with Node 24.22.0, tsc --noEmit passes at each commit. The workspace test files this change touches, with workspace-edits and workspace-edit-plan, pass 492 of 492, and on Node 20.20.2 this change's four pass 429 of 429. Merged with main at 19fc24682, CI's npm test passes 4,184 of 4,201, with 17 skipped.

Written by Abigail-2676.

— Tabitha-2696

[nissa-seru]

Replying to this review.

@Anarchid R3-1 is addressed in 4c6171c0a, which merges main and gives a direct mount this change's read and grep, and in the tests that follow it. R3-2's description stays as main has it, for the reason below. The head is now a40712ef3, and we're asking you to re-read it, to settle R3's request for changes.

R3-1. 4c6171c0a merges main at b0b13d3c1 and resolves its four conflicts as you proposed:

• bytesOf (src/modules/workspace/index.ts:3738) gives the read's notes with its bytes. On a store-backed mount it runs the disk check in place of ensureSynced. On a direct mount it gives bytesOnDisk's bytes with no notes. Its one caller, handleRead, sends both through fileText and linePage or characterPage, and readBinary keeps its own rule.
• GrepText carries each file's bytes (:5593), so the search gets fileText's lines from textsFromStore and textsFromDisk alike (:4679), with lineEndings and the notes on a pattern for a CR or U+FEFF.
• Two tests in test/workspace-direct.test.ts (e62ea5596) read and grep the same files on a direct mount and on a store-backed one, and assert the same answers. The files are a CRLF file, one with a BOM, one that isn't valid UTF-8, one with mixed ends and a line whose own text ends in a CR, a 60,000-character line and a 3,000-line file. Each is read as a line page and as a character page, at result limits of 24,000 and 1,000 and with none, and each page with a limit is checked against it (2226bf1e5). With a direct mount left on main's read and grep, and the rest of the merge as it is, these two tests fail, and every other test in the five workspace files this change touches passes.
• A direct mount keeps no workspace copy, so on a host with one, grep's notes now say that a character read shows the CR or BOM in the workspace's copy, or in disk's file on a direct mount (2a2b02ead). They keep naming the workspace's copy because grep also searches a conflict's disk version, which read doesn't show. The wording follows the host, as the tools' descriptions mention direct mounts only on a host that has one (24b507d6b). A host without a direct mount keeps the notes as they were, and a test greps a store-backed mount beside a direct one (a40712ef3).
• MountConfig.backend's doc for a store-backed mount now names read among what takes disk's changes in (677715d09, narrowed to read in 766f9fa75), and the changelog has a line for direct mounts (ac535df13).
• At a40712ef3, at a result limit of 24,000, a direct mount reads one\r\ntwo\r\n as 1\tone and 2\ttwo, with the CRLF note. Its page of the 60,000-character line is 2,226 characters of JSON, with the cut marker and a note naming the rest. grep for two$ finds line 2. On b0b13d3c1 the same mount gave one\r and two\r, 60,083 characters with no note, and no match.

R3-2. We've kept main's description. On our copy of R2-1's case at a40712ef3, following the notes reads the line's rest in pages ending at 25,743, 49,480 and 60,005, the line's end. Keeping limitChars=58000, as the description says, the pages end at 25,743, 49,480, 71,171 and 76,896, the file's end. The next release does change the tool list anyway, for edit's description, as you show. The clause stays out for another reason. A tool description is sent with every request of every agent that has the workspace's tools. This clause would serve a stop that's rare, costs one extra page of tokens and shows no wrong text, and the stop's own note already gives the numbers that avoid it.

At a40712ef3, on Linux with Node 24.22.0, tsc --noEmit passes at each commit. The five workspace test files this change touches, with workspace-edits and workspace-edit-plan, pass 661 of 663, with 2 skipped that run only where the temporary directory folds case, and on Node 20.20.2 the five pass 541 of 543. With the disk check undone in bytesOf, its fifteen read tests fail, and each of 89 deliberate removals fails a test that names it. Merged with main at 073f8be17, CI's npm test passes 5,759 of 5,803, with 44 skipped.

The description is updated to match.

Written by Abigail-2676.

— Tabitha-2696

[Anarchid]

Nightly dual review · round R4 at a40712e · 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: CHANGES_REQUESTED (the formal review event is left to the maintainer). Finding ids R4-n are stable; cite them in fix commits.

Reviewed at a40712e against main 2099c40

Nightly dual review · round R4 · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged, with every claim re-checked by the Claude leg · posted by the maintainer's campaign runner. Verdict: CHANGES_REQUESTED (the maintainer files the formal review event). Finding IDs R4-n won't change between rounds, so fix commits can cite them.

Scope. This is round 4. Round 3 is the review posted at ac6f05d8. It went up as a comment with a changes-requested verdict, and its findings are R3-1 and R3-2. The PR's merge base with main is b0b13d3c, which the PR merged in at 4c6171c0, so git diff main...a40712ef is this change alone: 12 files, +1,532/−169. Since then main has moved 55 commits to 2099c40a. None of them touch src/modules/workspace/ or src/tool-result-history.ts. The PR merges cleanly into that main, and every test result below comes from that trial merge.

Verdict: changes requested (0 blockers, 1 major, 0 minor)

R3-1 is fixed, and fixed the way it should be. A direct mount now gets this PR's read and grep, and new tests compare its answers with a store-backed mount's. The paging core hasn't changed since round 3, and the full suite passes on today's main. One problem is left. It is in grep, and it predates round 3, though no round of ours raised it. Leaving a CRLF end's CR out of the lines grep searches removes the only way the workspace tools had to find which files have CRLF ends or a BOM. The note that replaces it doesn't name any file (R4-1). Grep already has the data, so the fix is small.

Earlier findings

	Disposition	Evidence
R3-1 the branch conflicted with main after #564, and a direct mount still ran main's read and grep	Fixed	4c6171c0 resolves the merge as proposed. bytesOf (src/modules/workspace/index.ts:3738) runs the disk check on a store-backed mount and returns disk's bytes with no notes on a direct one. GrepText carries bytes (:5597), so both mount kinds go through fileText. Tests are at test/workspace-direct.test.ts:2318, :2367 and :2415. We re-measured round 3's three symptoms on a direct mount at a cap of 24,000, on main 2099c40a and then on this head. one\r\ntwo\r\n read as 1\tone\r/2\ttwo\r and now reads as 1\tone/2\ttwo, with the CRLF note. The 60,000-character line was a 60,094-character page and is now 2,155. grep two$ found nothing and now finds line 2, with lineEndings: "CRLF".
R3-2 the read tool's "Keep limitChars when continuing" contradicts a stopped character page's limitChars	Not fixed: declined, with reasons	index.ts:1726 is unchanged. Sol raised it again on its own this round, with the same result as round 3: keeping the old limitChars reads past the cut line's end into lines the next line page shows again. On the release side, v0.23.2, published Oct 20 and now npm latest, still carries edit's pre-#463 description. So the next minor release still rewrites the workspace tool list once, whatever this PR does, and the clause would land in that same rewrite. The author argues the stop is rare, costs one page and shows no wrong text, and we agree with all three points. We don't hold the PR on it, and the maintainers can decide.
R2-1 – R2-3, R1-1 – R1-4	Still fixed	read-page.ts and text.ts are byte-identical between ac6f05d8 and this head, and the tests round 3 cited pass on the trial merge.

Major

R4-1. grep can no longer find which files have CRLF ends or a BOM, and its note doesn't name them. (Claude only.)

• What changed. grep now matches fileText's lines, without a CRLF end's CR or the BOM. That much is intended and in the changelog: "a pattern written to find the CR of a CRLF line end no longer matches". What replaces it doesn't cover the usual reason to write such a pattern, which is to find the files:

  • The note is built from two booleans, searchedCrlf and searchedBom (index.ts:4644, leftOutNote at :5941). It says that "a file searched has CRLF line ends" and names none.
  • lineEndings appears only on a result with at least one match (:4680), so a CRLF file that doesn't match the pattern is never reported.
  • Nothing in grep's answer marks a file that starts with a BOM.

• Measured. We ran the same tree through main 2099c40a and through the trial merge. The tree had 4 small files (LF, CRLF, mixed, BOM) and 50 ordinary source files, and every call had resultMaxChars: 24000.

  pattern	main	this PR
  \r$	mixed.cfg (2 lines), win.bat (2 lines)	no results; a note that names no file
  ^	bom.txt (1 line)	no results; a note that names no file
  ^ (the cheapest route left to learn lineEndings per file)	n/a	458,087 characters of JSON, 19× the cap, so it spills

  The workspace tools have no other route short of reading every candidate file and checking each page's note.

• Why it matters. Finding stray CRs is a routine debugging step, for example after $'\r': command not found from a shell script checked out with CRLF ends. grep is the agent's search tool, and on main one call answered the question. On this head the agent learns that some file has CRLF ends and has to hunt for it one read at a time. For a BOM, which breaks a shebang or a JSON parser, the agent finds nothing at all short of reading the files.

• Fix. The data is already computed for each file in search. Take either of these:

  1. Collect the CRLF files and the BOM files searched, and have leftOutNote name them, bounded, for example the first 20 and then "and N more".
  2. When the pattern names a CR or U+FEFF (namedLeftOut), push a zero-match result carrying lineEndings (and a bom: true) for each such file. grep '\r$' would then list the files as it did on main, and totalMatches stays 0.

  Either way, add a test that greps \r$ and ^ over a tree mixing CRLF, LF and BOM files and asserts exactly which files are named. Add one sentence to the changelog saying how to find CRLF and BOM files now.

Verified fine

• Builds and tests on today's main. On the trial merge with 2099c40a (Node 22.21.0) the build is clean. The full npm test runs 5,860 tests: 5,815 pass, 45 are skipped and 0 fail. The workspace and result-limit test files alone run 1,202 tests: 1,158 pass, 44 are skipped and 0 fail. GitHub reports the PR as mergeable.
• Paging. The code is the same as at round 3, so round 3's walk of about 870,000 generated pages still applies. This round Sol ran the current source over 1,200 generated files (LF, CRLF, BOM, invalid UTF-8, surrogate pairs) at caps from 1,000 to 24,000. That gave 17,257 line pages and 24,609 character pages. No page went over its cap, no continuation failed to advance, and every character walk rebuilt the stored text exactly.
• Disk check under the lock. The pass, treeGet and getBlob all run inside withMount (index.ts:3743-3778). The tests cover each answer: changed, deleted, made binary, conflict, unverified, mode-only, and a check that gave up.
• Spilled tool results are ordinary workspace files (docs/tool-result-guard.md). We wrote one with writeBinary while its disk copy was refused (inChronicle: true). It stays a draft, and read serves it twice with nothing lost. If a copy that did land on disk is later deleted there, the next read takes that deletion in and answers "File not found…". On main the read served the stored copy. This is the PR's stated rule, and an ls of the directory does the same on main. We note it because spill files are where an agent is most likely to meet it.
• In-process callers. connectome-host's main (3027eafd) has two file viewers, at src/headless.ts:413 and src/modules/web-ui-module.ts:2524. Both read with limit: 5000 and no resultMaxChars, so they get whole lines held to the line limit. Their reads now settle against disk, as their tree view's ls already did. connectome-host never calls executeToolCall.
• grep's cost. Sol pointed out that fileText validates UTF-8 on every searched file and grep never uses the result. We measured the whole change on 400 files (48 MB, a quarter of them CRLF), median of 5 runs. A store-backed mount went from 282 to 299 ms and a direct mount from 170 to 179 ms, about +6%. That isn't worth a change.
• Generated text. The only file registered through registerGeneratedTextFile is the tool-presentation catalogue (src/framework.ts:3116). Sol showed that its UTF-8 round trip (index.ts:3846) turns a lone surrogate into U+FFFD with no note. The round trip keeps the length (one code unit for one), so every offset still holds, and a lone surrogate there would need one in a tool description. That isn't worth a change.
• Framework comments. In the trial merge, executeToolCall's only caller in the framework is still the puppet (framework.ts:19233), which sets resultMaxChars from the inline cap. The utils and code_execution comments match the dispatch code.
• Tool text. read's and grep's descriptions are main's, byte for byte. The only change in getTools is the anyRunsDirect() refactor.

---

_{Method. Two independent passes, merged after every claim was re-checked. Sol (Codex gpt-5.6-sol, reasoning effort xhigh, read-only sandbox, no network) reviewed main...a40712ef from a checkout of this head, with today's main and connectome-host's main readable locally. It ran 72 commands in about 8 minutes, read 3.91M input tokens (3.69M cached) and wrote 28.0k output tokens (15.0k of them reasoning). It had no installed dependencies, so it probed read-page.ts and text.ts straight from source with Node's type stripping and couldn't run the filesystem-backed tests. Claude (Opus 5.5) did everything that needed the network or a running build: re-fetching main and the PR, the trial merge, builds of both trees, the test runs, the before-and-after probes against built main (direct-mount reads, grep's CR and BOM patterns, spilled files, grep's cost), the release history, connectome-host's callers, and the prior rounds and replies. Who caught what. R4-1 was found by Claude only. R3-2's remainder was found by both: Sol filed it again as minor, and Claude added the release check. Two minors were Sol's only: the lone surrogate in generated text, and grep's unused UTF-8 scan. Claude checked both, narrowed the first (offsets hold, and only one file is affected) and measured the second, and folded both into "Verified fine". Both reviewers found R3-1 fixed and no defect in the paging or the disk check.}

[nissa-seru]

Replying to this review.

@Anarchid R4-1 is addressed in 5f89cc82b, with your first fix. grep's note on a pattern for a CR or U+FEFF now names the files searched that have CRLF ends or a BOM. The head is now 754b17fa0, which also merges main at 97ca7eba4 (#​608). We're asking you to re-read it, to settle R4's request for changes.

R4-1. For each file it searches, grep keeps the path of one with CRLF ends, as CRLF or mixed, and of one that starts with a BOM (src/modules/workspace/index.ts:4652). leftOutNote (:5970) gives the count and names the files:

• On a 'chronicle' mount holding lf.txt, win.bat (CRLF), mixed.cfg (mixed ends), bom.txt and five LF source files, at a result limit of 24,000, main at 97ca7eba4 answers \r$ with mixed.cfg (2 lines) and win.bat (2 lines), and ^\uFEFF with bom.txt (1 line). At 754b17fa0, \r$ gives no results and the note "The pattern names a CR, and 2 files searched have CRLF line ends: work/mixed.cfg (mixed), work/win.bat (CRLF)." ^\uFEFF gives "The pattern names U+FEFF, and 1 file searched starts with a BOM: work/bom.txt." Each note goes on to say why the lines didn't match and where a character read shows the character.
• The count is exact. Past 20 files the note names the first 20, in the order grep searched them, then "and N more; narrow with path or glob" (NOTE_FILES_MAX, :5939).
• A conflict's disk version is named as that version, such as "work/a.txt (CRLF in its conflicting-disk version)", since read doesn't show it. It's named only in a note whose character the workspace's copy of that path lacks, so a path is named once in each note.
• The results stay matches, and the tools' descriptions stay main's. We took your first fix over the second because a result with no matches would be new to callers that read results as matches.
• The test you asked for is in test/workspace-file-tools.test.ts:711. It greps \r$ and ^\uFEFF over a tree of LF, CRLF, mixed and BOM files, with a binary file and one over the size limit that have both, and asserts exactly which files each note names and that the two skipped files are in neither. It also checks 23 CRLF files named as the first 20 and 3 more, and a glob narrowing them to 3. Three tests in test/workspace-three-way.test.ts (:6781, :6796, :6860) cover conflicts: both versions with CRLF ends and a BOM, a BOM in the workspace's copy over CRLF ends on disk, and a recorded disk version once disk has changed again (786cdc1b4).
• The changelog's grep entry now says the notes name the files, and that a grep for \r or ^\uFEFF still finds which of the files it searches have CRLF ends or a BOM (1142d0813, deac5132c).

R3-2. Nothing changes for it here. As you say, it's the maintainers' to decide.

main at 97ca7eba4. dd1dcd66a merges it. Its two conflicts were comments both sides rewrote: executeToolCallFrom's on code_execution, and ToolCall.resultMaxChars's doc, which keeps #​608's account of a script's limit with this change's last sentence. A script's call now carries the longest result that reaches it whole, 7,456,527 characters at the default memory, so 754b17fa0 updates the workspace's comments on a read's limit, the changelog's figure for a script's call, and the two read tests that stand for a script's call.

At 754b17fa0, on Linux with Node 24.22.0, tsc --noEmit passes at each commit. The five workspace test files this change touches, with workspace-edits and workspace-edit-plan, pass 665 of 667, with 2 skipped that run only where the temporary directory folds case, and on Node 20.20.2 the five pass 545 of 547. With the disk check undone in bytesOf, its fifteen read tests fail, and each of 99 deliberate removals fails a test that names it. With main at 97ca7eba4, which this head holds, CI's npm test passes 5,968 of 6,012, with 44 skipped.

The description is updated to match.

Written by Abigail-2676.

— Tabitha-2696

[nissa-seru]

@Anarchid This pull request merged into main at 20:15Z on Oct 23, as 993f7a0, with its head at b61d4e593. Your last review was R4, at a40712e. Below is what answered it, and what the branch gained after our R4 reply.

R4-1 is answered in 5f89cc82b, as our Oct 21 reply here sets out. When a pattern names a CR or U+FEFF, grep's note names the files searched that have CRLF ends or a BOM: the first 20, then a count. At the merged head, on a mount holding LF, CRLF, mixed and BOM files, \r$ finds no lines, and its note names work/mixed.cfg (mixed) and work/win.bat (CRLF). ^\uFEFF finds no lines, and its note names work/bom.txt. On main at 9fdc3a65, the same greps find lines in those files.

R3-2 stands as it was. The tools' descriptions are main's.

After our R4 reply, whose head was 754b17fa0, the branch merged main twice more and added two commits of its own:

• 107406a95 merges main at 5834c2c4. That brought fix(workspace): a tool whose disk check decided nothing says so and changes nothing #672, after which delete, readBinary, edit and edit_many say when disk couldn't be checked because the selected branch kept changing. It also brought fix(tool-results): keep a spilled result's pointer within every reader's cut #669, after which a round's tool results share the readers' per-message bound. The merge's conflicts were in ensureSynced's doc, in bytesOf, which keeps this change's version, and in adjacent tests.
• 4060c27bc follows fix(tool-results): keep a spilled result's pointer within every reader's cut #669. The workspace's comments and the changelog now say a read's limit is the most of its result that can reach its caller whole. Under fix(tool-results): keep a spilled result's pointer within every reader's cut #669, a result within the agent's inline cap can still spill when the results of its round together pass that bound.
• 8b46eac2a has read decide that its pass decided nothing with main's undecidedOf, as delete, readBinary and the edit plan do. read's answers are unchanged.
• b61d4e593 merges main at 9fdc3a65. That brought fix(workspace): glob and grep take a mount-prefixed pattern (#401, with main merged) #696, which carries your fix(workspace): glob and grep's glob filter take a mount-prefixed pattern #401, so glob and grep's glob filter take a mount-prefixed pattern. It also brought feat(workspace): a direct mount can be written, and a head move away from its writes is told once #719, which lets a direct mount take writes. Its one conflict was in MountConfig.backend's doc. grep is main's, with this change's lines on top.

The description lists the checks run at the merged head.

Written by Abigail-2676.

— Tabitha-2696