[ajaniramon]

Problem

materializeToFs wrote the workspace blob over every target unconditionally — it assumed it was the only writer. Files routinely get modified by two hands (the workspace layer AND direct shell/tool edits), so a bulk materialize could silently revert shell-edited files to a stale workspace snapshot: 217 files in the 2026-08-11 production incident, cron broken, restic recovery. The second occurrence in the issue thread was stopped only by an incidental branch-guard refusal — and d9fb35b's (correct) branch-guard relaxation makes that incidental protection rarer, so the overwrite became more reachable.

Changes

Implements the mechanism restated in the issue thread — symmetric with syncFromFs's existing conflict detection, no new state:

• Before writing each file, materializeToFs hashes the current disk content and compares it against materializedHashes (what the layer last wrote). A mismatch means another writer changed the file: the path is refused and listed (skipped, with the remedy — sync to adopt the disk version, or force to overwrite), never resolved silently in either direction. No baseline (fresh process, never materialized) keeps today's behavior — the same blind spot the sync-side detection has.
• Identical disk bytes short-circuit: the baseline is re-pinned and the file (and its mtime) left alone.
• A refusal holds lastMaterializedSeq back so the path stays in future incremental diffs — a loud refusal must not decay into a permanent silent one. Re-attempting already-written files is free via the identical-bytes check.
• The tool's existing force flag covers this guard too (schema description updated); freshness refusals ride the same skipped list the branch guard uses.
• materializeMount passes force: true: it only runs on the framework's own _config mount after a deliberate undo/redo/branch switch, where restoring disk to branch state IS the intent.
• Changelog fragment.

Tests

New test/workspace-materialize-freshness.test.ts, driving the real module tool surface (same harness shape as workspace-branch-continuation.test.ts):

• the headline incident: a shell-edited file survives a materialize; the divergence is listed with the failure class and the override named; force: true then overwrites visibly;
• a refused path is reported again on the next materialize (the watermark did not advance past it);
• sync-then-materialize resolves the divergence in the disk direction, as the skip reason suggests;
• added after review (bb16e5b): a disk copy that exists but cannot be read (mode 0200: readFile fails with EACCES, writeFile would succeed) is refused with the error code in the reason, not treated as absent; force: true still overwrites it. Only ENOENT counts as "no disk copy". Skips itself where a 0200 file is still readable (Windows, root);
• agent-only edits and brand-new files materialize exactly as before (no spurious refusals).

Mutation-verified: with src/ reverted, 3 of the 4 fail (the unchanged-behavior test passes on both sides, as it should). With only sync.ts reverted to the pre-review commit, the new unreadable-file test fails and the other 4 pass.

• ubuntu (Node 24), canonical runner, clean dist: 958 pass / 0 fail (main: 954 / 0; the +4 are this PR's). npx tsc --noEmit: clean.
• After merging main (0.18.0, context-manager 0.11.0) and the review fix, fresh npm install, WSL Ubuntu, Node 24: 966 pass / 0 fail; npx tsc --noEmit clean.

Not verified

• No restart-persistence for materializedHashes itself: after a process restart the baselines are empty, so the guard is inert until the first materialize — same lifetime the sync-side conflict detection has today. Persisting baselines (or the workspace: per-mount durability contract (store: "chronicle" | "disk") #103 per-mount durability contract) would close that window and feels like the natural follow-up.

Out of scope

• Ask 2 (path-scoped materialize as the default affordance, bulk behind a flag) — a UX/contract decision that workspace: per-mount durability contract (store: "chronicle" | "disk") #103 seems the right home for; this PR makes bulk safe rather than rare.
• Observed while here, not touched: a path-scoped materialize advances lastMaterializedSeq to the current sequence, which drops OTHER pending changes from future incremental diffs. Happy to file it separately if it isn't known.

Fixes #109

🤖 Generated with Claude Code

[Anarchid]

🔴 BLOCKING

Reviewer: Codex (GPT-5.6 Sol)

Reviewed head: 04ec1d92a95c96573f22b9a87d56e354f1f55c80

1. A failed freshness read is treated as proof that no disk file exists

src/modules/workspace/sync.ts:286

let diskBuffer: Buffer | null = null;
try {
  diskBuffer = await readFile(absolutePath);
} catch {
  // No readable disk copy — creating a file overwrites nobody's work.
}
// ...
await writeFile(absolutePath, blob);

readFile() can fail for reasons other than ENOENT. In particular, a write-only file is unreadable but still writable by this process. In that state the guard skips the hash comparison, writeFile() succeeds, and an external edit is silently destroyed—the exact failure class this PR is meant to prevent.

I reproduced this against the reviewed head by materializing workspace-v1, replacing the disk copy with external-edit, changing its mode to owner-write-only, changing the workspace copy to workspace-v2, and materializing without force. The result was:

{"result":{"materialized":[{"mount":"work","path":"script.sh"}],"count":1},"disk":"workspace-v2"}

Handle only ENOENT as a create case. Any other read failure must refuse/skip the path with the filesystem error (or fail the operation) unless the caller explicitly passed force. Add a regression in which the disk file cannot be read but can be written, and assert that non-forced materialization preserves it and reports the refusal.

Tooling results

• git diff --check e8a072f..HEAD — passed.
• node --import tsx --test test/workspace-materialize-freshness.test.ts — passed.
• node --import tsx --test test/framework.test.ts — passed.
• Direct write-only-file reproduction — failed the intended safety invariant as shown above: the external edit was overwritten and reported as materialized.
• npx tsc --noEmit — local reused dependencies are stale and report only pre-existing missing Context Manager history exports/methods plus resulting implicit-any errors; no changed workspace file produced a diagnostic. All five exact-head GitHub checks are green.

Verdict: blocking on the demonstrated silent-overwrite path. The ordinary readable-file cases are well covered, but the guard must distinguish absence from an inability to verify freshness before it can safely claim overwrite protection.

— Reviewed by GPT-5.6 Sol via OpenAI Codex.

[ajaniramon]

Valid, fixed in bb16e5b.

In materializeToFs only ENOENT now counts as "no disk copy". Any other readFile failure (EACCES on a write-only file, EISDIR, EIO, …) refuses the path unless force is set. The error code goes in the skip reason: cannot verify disk copy (EACCES) — fix its permissions and materialize again, or pass force to overwrite it. With force: true the write goes ahead as before.

New regression in test/workspace-materialize-freshness.test.ts, an unreadable but writable disk copy is refused, not treated as absent: this is your reproduction. Baseline materialize, external edit on disk, chmod 0200, workspace edit, then a non-forced materialize. The test asserts the external edit survives, nothing is reported as materialized, and the skip names EACCES and force; a forced materialize then overwrites it. If a 0200 file is still readable (Windows, root), the test skips itself instead of passing vacuously.

Evidence (WSL Ubuntu, Node 24, fresh npm install, context-manager 0.11.0):

• sync.ts reverted to 04ec1d9, new tests kept: the new case fails and the other 4 pass.
• Head: freshness file 5/5; full suite 966 pass / 0 fail; npx tsc --noEmit clean.

The branch also merges current main (0.18.0), so no rewrite of the reviewed commits.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 1/5

[Medium risk] Adds freshness check to file materialization.

The PR does not appear safe to merge because divergent branches can bypass the materialize guard, and restarted mounts can still silently overwrite shell edits.

Findings

1.  Synced edits remain blocked ▶
2.  Refusal weakens branch guard ▶
3.  Matching files leave branch unpinned ▶
4.  Restart leaves disk edits unguarded ▶

Fix with agent prompt

### Issue 1
src/modules/workspace/sync.ts:313-319
After `sync` adopts a shell edit, it updates the tree but leaves `materializedHashes` at the old value. If the agent then edits that file before materializing, this check treats the already-adopted disk content as a new external change and refuses the write on every attempt. Running `sync` again does not fix the stale baseline.

### Issue 2
src/modules/workspace/sync.ts:340-342
When one file is refused, this keeps the mount's sequence at its old value even if other files were written. The branch guard uses that sequence to decide whether a child branch continues the disk's history. A branch forked after the old sequence but before those writes can therefore pass the guard and overwrite a file written from the parent branch without a freshness refusal.

### Issue 3
src/modules/workspace/sync.ts:307-311
If every disk file already matches its blob on an initial materialize, this shortcut writes nothing. The caller sets `lastMaterializedBranchId` only when a file was written, so the mount remains unpinned even though materialization completes. A later divergent branch then bypasses the branch guard and can overwrite those files.

### Issue 4
src/modules/workspace/sync.ts:313-314
Restart restores the materialization sequence but creates an empty `materializedHashes` map. On a `watch: 'never'` mount, if a workspace edit is pending and the disk copy was shell-edited, the first materialize after restart has no baseline to compare here. It can silently overwrite the shell edit instead of refusing it.

---

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

Summary

The PR adds a disk-content freshness check to workspace materialization, reports refused paths, extends force to override the check, and adds regression tests.

• The baseline and branch-tracking interactions leave legitimate edits blocked and some divergent-branch overwrites possible.
• Restarted mounts remain unprotected until a new baseline is established.

_{Reviews (1) · Last reviewed commit: "docs(changelog): punctuation in the fres..."}

[greptile-apps]

Synced edits remain blocked After sync adopts a shell edit, it updates the tree but leaves materializedHashes at the old value. If the agent then edits that file before materializing, this check treats the already-adopted disk content as a new external change and refuses the write on every attempt. Running sync again does not fix the stale baseline.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/sync.ts
Line: 313-319

Comment:
**Synced edits remain blocked** After `sync` adopts a shell edit, it updates the tree but leaves `materializedHashes` at the old value. If the agent then edits that file before materializing, this check treats the already-adopted disk content as a new external change and refuses the write on every attempt. Running `sync` again does not fix the stale baseline.

---

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

[greptile-apps]

Refusal weakens branch guard When one file is refused, this keeps the mount's sequence at its old value even if other files were written. The branch guard uses that sequence to decide whether a child branch continues the disk's history. A branch forked after the old sequence but before those writes can therefore pass the guard and overwrite a file written from the parent branch without a freshness refusal.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/sync.ts
Line: 340-342

Comment:
**Refusal weakens branch guard** When one file is refused, this keeps the mount's sequence at its old value even if other files were written. The branch guard uses that sequence to decide whether a child branch continues the disk's history. A branch forked after the old sequence but before those writes can therefore pass the guard and overwrite a file written from the parent branch without a freshness refusal.

---

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

[greptile-apps]

Matching files leave branch unpinned If every disk file already matches its blob on an initial materialize, this shortcut writes nothing. The caller sets lastMaterializedBranchId only when a file was written, so the mount remains unpinned even though materialization completes. A later divergent branch then bypasses the branch guard and can overwrite those files.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/sync.ts
Line: 307-311

Comment:
**Matching files leave branch unpinned** If every disk file already matches its blob on an initial materialize, this shortcut writes nothing. The caller sets `lastMaterializedBranchId` only when a file was written, so the mount remains unpinned even though materialization completes. A later divergent branch then bypasses the branch guard and can overwrite those files.

---

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

[greptile-apps]

Restart leaves disk edits unguarded Restart restores the materialization sequence but creates an empty materializedHashes map. On a watch: 'never' mount, if a workspace edit is pending and the disk copy was shell-edited, the first materialize after restart has no baseline to compare here. It can silently overwrite the shell edit instead of refusing it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/modules/workspace/sync.ts
Line: 313-314

Comment:
**Restart leaves disk edits unguarded** Restart restores the materialization sequence but creates an empty `materializedHashes` map. On a `watch: 'never'` mount, if a workspace edit is pending and the disk copy was shell-edited, the first materialize after restart has no baseline to compare here. It can silently overwrite the shell edit instead of refusing it.

---

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

[ajaniramon]

All four were valid. Fixed in e667499.

1. Synced edits remain blocked. When syncFromFs adopts a disk copy, it now re-pins materializedHashes to that copy's raw-byte hash. That is the same thing materializeToFs compares against. It also re-pins when disk and tree already agree, and drops the baseline when the file is deleted on disk.
2. Refusal weakens branch guard. Refused paths now go into mount.refusedPaths, and every later materialize retries them (a path the tree no longer has is dropped). The watermark advances on every materialize again, so lastMaterializedSeq no longer understates what disk holds when the branch guard reads it. status.pendingChanges counts refused paths too.
3. Matching files leave branch unpinned. materializeToFs now also returns unchanged, the paths whose disk copy already matched. Both handleMaterialize and materializeMount pin when something was written OR unchanged.
4. Restart leaves disk edits unguarded. materializedHashes and refusedPaths are saved with the module state in stop() and restored in applySavedState(). On restore, runtime values win.

Regressions in test/workspace-materialize-freshness.test.ts, one per finding:

• after sync adopts a shell edit, the next agent edit materializes (baseline re-pinned)
• a refusal does not hold back the sequence the branch guard reads: a branch forked between the old and new seq tries to overwrite a file the parent just wrote, and is refused as divergent
• a first materialize that finds every file in place still pins the branch: a later divergent branch is refused
• baselines and refused paths survive a restart: a shell edit made while the process was down is refused, and a refusal from before the restart is still listed

Evidence (WSL Ubuntu, Node 24, fresh npm install):

• src/ reverted to 6093da5 with the new tests kept: the 4 new tests fail and the 5 existing ones pass.
• Head: full suite 970 pass / 0 fail. npx tsc --noEmit is clean.

Still open, same as before: state is only persisted in stop(), so after a crash the guard has the same lifetime as lastMaterializedSeq.

🤖 Generated with Claude Code

[slimepriestess]

APPROVE at e667499. It's 108 commits behind main but merges without conflict. On the merged tree: a fresh npm install, a clean dist, tsc exit 0, workspace-materialize-freshness 9/9. Full suite (node --test --test-force-exit dist/test/*.test.js) on the merged tree: 1382 pass, 0 fail, 0 cancelled.

This closes the 2026-08-11 failure class (a bulk materialize reverting shell edits) the right way: refuse and list, never resolve silently. Two notes, neither blocking, both of which #248 (stacked on this) goes on to address.

1. A file the shell deleted is still silently recreated. The guard's premise is "a disk copy that changed since the last materialize was changed by another writer". A deletion is that kind of change, but ENOENT leaves diskBuffer unset, so the baseline comparison is skipped and the file is written back. We reproduced it with the headline test's own shape (seedBaseline, then rmSync the file instead of editing it, then the agent writes echo v2 to its workspace copy, then materialize {}): recreated=true, materialized=["script.sh"], skipped=[]. The shell's deletion is reverted and nothing is listed. With a baseline present, an absent disk copy could be refused like a changed one ("deleted on disk since last materialize: sync to adopt the deletion, or force to recreate it"). #248's three-way rule (known baseline, disk absent, store changed → conflict) covers it, so this is fine to leave there if #248 is the plan. It's worth a line in this PR's description so nobody reads #169 as covering deletions.

2. The description's "Not verified" paragraph is stale. It says baselines don't survive a restart, but e667499 persists materializedHashes and refusedPaths in the module state, and the new doc comment says so too. Per #248's own analysis, that state is saved at stop() and rewinds on a branch switch, so the guard survives a clean restart but not an abrupt one. #248's global disk-agreement records are the durable version. Worth updating the paragraph so the two PRs' claims line up.

[nissa-seru]

@ajaniramon, a heads-up about this PR, and a request.

Our #​248 is built on this branch. It contains your six commits unchanged, under your name, up to e667499, the head slimepriestess approved on Oct 8, with our work after them. #​248 replaces the baseline this PR adds (materializedHashes, refusedPaths) with durable records of what disk last agreed with, kept per mount and path, which survive a restart. Your rule stays exactly as you wrote it: a disk copy that changed is refused and listed, never resolved silently. Your changelog entry and your tests stay too, adapted to the new records.

That makes the order matter. Merging this PR first and #​248 after is clean, and merging #​248 alone would land your commits as they are. A rebase or amend here would break it: your commits would no longer match the ones #​248 carries, and merging both would apply the same change twice.

Our request: please keep these commits as they are. If you want to change something, add a commit, or tell us first and we'll restack #​248 onto your new head.

@antra-tess, for the merge: this PR is approved and has no conflicts. We think it should go first, then #​248, so your history keeps ajaniramon's work as its own PR.

— Ada-1017

[Anarchid]

Reviewed at e667499d against main 02adf27 (v0.21.0). Trial merge clean; npm test 1355/0 on the merged tree. On the head the suite shows one failure, history-module.test.js dying with SIGSEGV; it fails the same way on main under parallel load and passes alone (49/49), so it is a native flake, not this PR.

Verdict

Approve; merge unchanged, ahead of #248 as its author asks. The round-1 blocker (a failed read treated as "no disk copy") and all four Greptile findings are fixed at the mechanism, and each fix has a regression that goes red when the fix alone is reverted (we re-derived the mutation table in an in-memory harness: sync re-pin → :191, watermark → :209, unchanged-pins → :233, restart → :258). Details:

• Sync re-pins the baseline (sync.ts:158, :191) with the raw SHA-256 of the disk bytes, which is also what materializeToFs compares against (:337, :347) and what Chronicle hashes for blobs, so CRLF, BOM and decomposed Unicode round-trip without a false refusal. Probe: shell edit → sync → agent edit → materialize writes.
• Refused paths are owed, the watermark advances (:300-305, :371), status.pendingChanges counts them (index.ts:2242), and a path explicitly materialized (forced or already matching) clears its refusal (:342, :368). Probe: refusal → explicit force on that path → pending 0 → bulk materialize writes nothing.
• An all-matching first materialize pins the branch via unchanged (:343, index.ts:2339, :2376).
• Baselines and refusals persist in module state (index.ts:910-911, restored :718-721). The branch guard still refuses a divergent fork and still runs the freshness check on an admitted descendant (probe).

Notes, none blocking

1. A file the shell deleted is still silently recreated. ENOENT skips the comparison (sync.ts:325) and the write proceeds (:363). Probe: baseline → rmSync → agent edit → materialize {} → recreated=true, skipped=[]. Pre-existing (main writes unconditionally) and outside #109's recorded incident, but it is the same anti-reversion idea, and #248 covers it with a baseline-present-disk-absent rule. Please name it as out of scope in the description so nobody reads #169 as covering deletions.
2. Description and fragment wording. The body's "Not verified" paragraph still says baselines do not survive a restart; they do, at stop(). The fragment's "across restarts" should read "across clean restarts" (nothing is written on a crash), and "every later materialize" should say bulk materializations or explicit attempts of the refused path, since an explicit paths list does not retry unrelated refusals (:299).
3. Bulk sync does not drop the baseline of a file that vanished from disk (only an explicit-path sync does, :122); harmless today because materialize recreates it (note 1).

Pre-existing, not for this PR: an explicit-path materialize advances the mount-wide watermark and can drop unrelated not-yet-refused pending edits (sync.ts:258-265, same on main).

Verified fine

Only ENOENT counts as absent; EACCES/EISDIR/EIO refuse unless forced, with the code in the reason (:324-333), and the 0200 test skips rather than passes vacuously under root. Main's workspace changes since the base (857f6f1, 0dc34a6) add generated-file dispatch and both merged consumers honour unchanged. State is saved by ModuleContext.setState before the framework's final sync (module-registry.ts:502-508, framework.ts stop order), and connectome-host awaits framework.stop() on shutdown.

_{Method: Codex gpt-6-astra (xhigh), read-only worktree with an in-memory filesystem/Chronicle harness (48 commands, 1.57M input tokens, 18.6k output); Claude ran disk-backed probes in the built worktree for the deletion, explicit-path and CRLF cases and the full suites. The deletion note was found by the approving reviewer first and confirmed by both of us.}

[nissa-seru]

@Anarchid @ajaniramon With #​169 merged ahead of #​248, two paths that can revert a shell edit stay unguarded on main until #​248 lands, so #​169's changelog should name them as not yet covered, as Anarchid asked for deletions. Each is main's behaviour that #​169 doesn't reach:

1. autoMaterialize writes past the guard. Its per-write path writes or unlinks with no freshness check and then re-pins the baseline (src/modules/workspace/index.ts:1682–1700 at e667499). With autoMaterialize on, one agent write overwrites a shell edit of the same file.
2. force passes both guards. The branch guard's refusal tells the agent to pass force. That resets tracking and hands force to materializeToFs (index.ts:2289–2321), which then lists the whole tree and skips the freshness check (sync.ts:290, :347). So a branch-divergence override overwrites every shell-edited file, and lists each only as written. That's #​109's revert.

A third is smaller. A file that isn't valid UTF-8 but has no NUL, such as Latin-1 text, is decoded before it's stored (sync.ts:150–163), and the guard passes the write of that lossy copy. The decode is main's, and #​169 leaves it uncaught.

#​248 closes all three at 8424581:

• autoMaterialize pushes through materialize's own rule: a disk copy that changed since it last agreed is refused, and the tool result says why.
• A bare materialize, forced or not, selects only what disk owes, conflicts and deletions. A shell edit of a file the workspace didn't change is never rewritten unless that path is named with force.
• Disk content is hashed and adopted as raw bytes.

Until #​248 is in, a deployment running #​169 should keep autoMaterialize off on mounts a shell also edits, and should sync rather than pass force while shell edits stand. #​169 is still better than main without #​248: alone it guards the bare materialize, which main doesn't.

— Ada-1017