[nissa-seru]

TL;DR: a workspace materialize with force and applyDeletions no longer removes a pipe, socket or device at a path the workspace deleted, nor a followed symlink to anything but a regular file. It still removes a regular file, or a followed symlink to one (the link itself). Its refusal, forced or not, says that no push unlinks such an entry and to ask whoever runs the host if it should go. Before, the refusal for a pipe, socket or device offered the forced materialize that removed it.

Problem

On main 9c1e7577, all in src/modules/workspace/:

• unlinkContained (effects.ts) applies a workspace deletion to disk. Of the kinds of entry it can find at the path, it refused only a directory, a symlink on a mount that doesn't follow symlinks, and a followed one it can't resolve inside the mount. It unlinked anything else.
• Without force, such a path isn't unlinked. Observation reports a pipe, socket or device, or a followed symlink to one, as "not a regular file", and a followed symlink to a directory as "a symlink to a directory, not walked". decide() makes a path disk can't vouch for unverified, and an unforced push refuses it.
• force skips the checks of what disk's copy holds, but never the mount's boundary. With it and applyDeletions, the push planned the unlink with expect: any, which removed:
  • a pipe, socket or device at a path the workspace deleted;
  • on a mount that follows symlinks, a symlink whose target is a directory, a pipe, a socket or a device.
• The refusal before any force named that forced materialize for a pipe, socket or device (forcedWay in reconcile.ts): "cannot verify disk copy (not a regular file) — fix it and materialize again with applyDeletions, or materialize it with force and applyDeletions to delete it".
• A forced materialize without applyDeletions listed such a deletion, and a deletion over a directory, among the deletions left on disk, and its note said "materialize with applyDeletions to remove them". The unlink refuses a directory, forced or not.

effects.ts's header says an effect acts on "a regular file inside the mount", and writeContained already refuses each of these, forced or not. A socket or device node that someone put at the path isn't the file the workspace deleted.

Changes

• unlinkContained refuses a pipe, socket or device at the path, and a followed symlink whose target isn't a regular file. Each refusal touches nothing, so the path's evidence goes back as it was. It still removes a regular file, and a followed symlink to a regular file inside the mount: the link itself goes, never the file it leads to. Its doc comment says what it removes and what it refuses.

• The refusals' words. The unlink refuses in observation's own words for the path, "not a regular file" and "a symlink to a directory, not walked". inTheWay (reconcile.ts), which already answers a directory in a push's way, answers both for a deletion, forced or not:

  • "disk has a pipe, socket or device at this path, or a symlink to one, and no push unlinks it, forced or not — ask whoever runs this host if it should go"
  • "disk has a symlink to a directory at this path, and no push unlinks it, forced or not — ask whoever runs this host if it should go"

  A forced materialize lists either after "not unlinked: ", as it lists a directory.

• A forced push without applyDeletions refuses a deletion that inTheWay says no push makes, in those words, as an unforced push does, rather than listing it among the deletions left on disk for applyDeletions to remove.

• forcedWay no longer offers force for a deletion of what isn't a regular file, and its doc says force stops there. PushOptions.force and pushPaths' doc say that, forced or not, nothing but a regular file, or a followed symlink to one, is written over or unlinked.

• Confirming an earlier unlink names a pipe, socket or device that appeared at the path since as one, where it said "a file".

• Changelog: a fragment says what changes, with what operators do now in a sub-bullet of its own. The unreleased fragment for the workspace file tools (fix(workspace): the file tools store exactly what they're given or refuse, and say when a stored change didn't reach disk #456) said "For a deletion, something that isn't a regular file is offered force as it is", which this change makes untrue, so that sentence goes.

What callers will notice

• Agents: a deletion over a pipe, socket or device, or over a followed symlink to a directory or to one of those, is refused in the same words before and after force, and isn't offered force. A delete on a mount that pushes as it goes quotes the refusal. A forced materialize without applyDeletions refuses it too, and a deletion over a directory, rather than listing it as left for applyDeletions.
• Operators: a forced materialize with applyDeletions no longer clears such an entry. Remove one by hand:
  • The safe way: unlink <path>. It removes exactly that one entry, whether a pipe, a socket, a device node or the symlink itself, never what a link leads to, and it refuses a directory.
  • To avoid: rm -r on a link to a directory written with a trailing slash. It acts on the directory. With GNU coreutils 9.4 on Linux, mkdir dir && touch dir/f && ln -s dir l && rm -r l/ empties dir, then fails with "cannot remove 'l/': Not a directory", leaving the link.
• Scripts: these refusal texts changed. Nothing in connectome-host 16539782, chapterx c38b2cd1, discord-mcpl e2944eb2, context-manager 0c855201 or membrane a6037789 matches on them.

Tests

On Linux, with Node 24.22.0 and 20.20.2, each run from a clean build after npm install, as CI installs:

• At this head, a26b214bb: tsc --noEmit is clean. The two test files this change touches, test/workspace-three-way.test.ts and test/workspace-file-tools.test.ts, run without --test-force-exit, pass 372 of 372 on each runtime. CI runs the whole suite.
• The tests this change adds or changes:
  • workspace-three-way.test.ts, a forced removal: on a mount that follows symlinks, six paths the workspace deleted, where disk now holds a FIFO, a socket, a symlink to a directory, a symlink to a FIFO, a symlink to a regular file and a directory. A materialize with applyDeletions refuses the FIFO, the socket and the links to the directory and to the FIFO in the new words, and the directory in its own, offering no force. A forced one without applyDeletions refuses them in the same words and leaves only the link to the regular file for applyDeletions. A forced one with it refuses them after "not unlinked: ", and they stay, with the directory and the FIFO the links lead to. It removes the symlink to the regular file, and the file stays. It protects the rule that no push unlinks anything but a regular file or a followed symlink to one, and the agent's reading one refusal whichever way it asks.
  • workspace-three-way.test.ts, confirming an unlink: an unlink that reached disk unconfirmed, and a FIFO made at the path just before the push that confirms it. The push names it "a pipe, socket or device appeared at this path since it was checked" and leaves it, and the unlink is still owed. It protects the confirmation's rule that nothing found there is removed, with its words for what it found.
  • workspace-file-tools.test.ts: a file disk replaced with a FIFO, deleted on a mount that pushes as it goes. The test pinned the old behaviour, a forced materialize unlinking the FIFO. It now checks the delete's refusal, the forced materialize's "not unlinked: " in the same words, and that the FIFO stays.
• Red-first: against main's source with this head's two test files, those three tests fail. Main's tests of a write over a FIFO and of a file appearing during a confirmation, run beside them, pass there as here.
• On main: two probes drove the same paths through main's source, to show what this change replaces.
  • The five paths other than the directory: before force, a materialize with applyDeletions refused all five: the FIFO, the socket and the links to the directory and to the FIFO as unverified, offering force for all but the link to the directory, and the link to the regular file as a stale copy, offering force too. Forced, it unlinked all five, leaving the directory, the FIFO and the file that the links led to.
  • All six: forced without applyDeletions, it listed all six among the deletions left on disk, the deleted path's directory included, with the note "Files deleted in the workspace were left on disk; materialize with applyDeletions to remove them."
• Removals: each of twelve edits to the built code, made alone, fails at least one of those tests:
  • either refusal in unlinkContained taken out;
  • the check at the path narrowed to a FIFO, or the check behind a link narrowed to a directory;
  • the two link refusals swapped, or every followed link refused;
  • inTheWay's deletion case taken out, applied to writes too (main's write-over-FIFO test fails), left without the link to a directory, or with its two descriptions swapped;
  • the check before pendingDeletions taken out;
  • the confirmation's label for a pipe, socket or device taken out.

Not verified

• Windows: the tests that make a FIFO are skipped there, so neither refusal ran there. macOS until CI runs.
• A device node: making one needs root, so the tests use a FIFO and a socket. A device meets the same check as they do, isFile(), at the path and behind a followed link.

Out of scope

• A write over a pipe, socket or device, or a followed link to one, is refused forced or not, as before. Its refusal offers no force and keeps its wording: "cannot verify disk copy (not a regular file) — fix it and materialize again".
• A followed symlink that dangles or loops is refused, forced or not, as "a symlink that leaves the mount", which it doesn't, and in other words than observation's. That wording is unchanged here.
• A deletion over a symlink the mount doesn't follow, or over a followed one that dangles, loops or leaves the mount, is refused by the unlink forced or not, as before. A forced materialize without applyDeletions still lists such a deletion among those left on disk.
• A path whose branch intent can't be read is refused before force for that, with "once it can be, sync this path", and left by a forced push, as before. Where disk holds a pipe, socket or device there, that refusal doesn't say that only someone who runs the host can clear it.
• The wording of the push's other refusals is unchanged.

What each part is for

• The two refusals in unlinkContained are what the change is for. An unlink, like a write, acts only on what the header promises, a regular file inside the mount. Force skips the checks of what disk's copy holds, not the kind of entry the effect acts on.
• Observation's words for the refusals, not a sentence of the unlink's own. The refusal before force comes from observation's note, and the forced one from the unlink. The same words let one case in inTheWay answer both, so the agent reads one refusal before and after force. A sentence of the unlink's own would leave the refusal before force in other words, and inTheWay would have to know both.
• inTheWay's case for a deletion. inTheWay is where a push answers what's in its way forced or not, and it already did so for a directory. Without the case, a forced refusal would read "not unlinked: not a regular file", and the one before force would still end "fix it and materialize again with applyDeletions", with nothing saying that force won't help. It's limited to deletions, since a write over the same entries keeps its own refusal.
• "Ask whoever runs this host if it should go", where the directory case says "move or remove it on disk". A socket or device node at the path is likely the host's, and removing one can do real harm, so whether it goes is for whoever runs the host to decide. The changelog says how they remove one safely.
• The check before pendingDeletions. Its note tells the agent that applyDeletions removes what it lists, so a deletion no push makes doesn't belong there. One call to inTheWay decides it, the same answer the unforced push gives, and it covers a directory, which was listed the same way.
• forcedWay's offer goes. Once inTheWay answers that note first, the line can't be reached, and it describes a way out the unlink now refuses.
• The confirmation's label costs one more case in an expression, and makes the function name a pipe, socket or device the same way wherever it meets one.
• The doc lines say where force stops, since the docs said it overwrites or unlinks a copy that can't be verified.
• The changed test in workspace-file-tools.test.ts pinned the old behaviour, a forced materialize unlinking a FIFO. It's turned round rather than deleted: the same steps now check the refusal's words and that the FIFO stays.

Review

Reviewed internally: a review of the first commit's change, whose findings the second commit answers. Naomi-2422 (Claude Opus 5.5) read and approved the change.

— Pippa-2571 (Claude Opus 5.5), contributing through nissa-seru. Description checked and posted by Fiona-2757 (Claude Opus 5.5).

[greptile-apps]

Required label not found on this PR.