FS_NOT_OBSERVED fires on every first edit of a bash-inspected file — the observation contract never says bash does not count

[tommy0103]

What happened

A real DSH session (standard mode, working on another repo) hit FS_NOT_OBSERVED 6 times in 3 clusters within one turn — every time the agent edited a file it had previously inspected via bash:

step	target	prior inspection	outcome
s13	builtins.ts, packages/core/package.json	cat via bash, several turns earlier	both edits rejected → read both → edits succeed
s69	README.md (3 parallel edits)	only bash grep/sed — and it had even mutated the file with perl -pi	all 3 rejected → one read call → edits succeed
s111	tests/invoking-session.test.mjs	bash sed -n + grep	rejected → read → edit succeeds

The recovery worked every time (the — read the file, then retry remedy does its job), so each rejection costs ~2 wasted steps. But the model's behavior is not careless — cat/grep/sed are the idiomatic inspection tools, and nothing in the tool contract tells it those don't count.

Mechanism: observation is fs-tool-only, by design

fs-observation-policy records observations only from fs/observed events, which only the fs tool family (read/write/edit in dsh-tool-fs, plus str-replace-editor) emits. Bash goes through the shell capability and never touches the fs layer — the harness literally cannot see a cat. The fs-observation-policy README even documents this ("Direct ctx.fs reads emit no fs/observed"), but the edit tool description — the only place the model actually reads — says just "Read the file first (the default fs-observation-policy requires it)", without saying bash reads don't qualify.

The guard exists for a good reason: it records the file version at read time so a later edit can CAS against external/concurrent modification (FS_STALE_VERSION). A bash cat produces no version, so it can't serve as the CAS basis. The mechanism is sound; the contract is under-specified.

Interesting twist: the affected agent's self-diagnosis was half wrong

When its user asked why this kept happening, the in-session agent produced a four-point analysis blaming harness guidance. Two points hold up:

• ✅ "The contract never says what counts as read — the bash/edit toolchain split is a trap."
• ✅ "The observation rules are an implicit state machine documented nowhere end-to-end."

Two are factually wrong, which is itself diagnostic:

• ❌ "The error message doesn't say how to recover." It does — edit requires reading "<path>" first — read the file, then retry (the remedy suffix landed 2026-08-03, .agents/notes/implemented/feature/2026-08-03-fs-tool-error-remedy.md). The agent followed that remedy successfully six times without registering it as guidance.
• ❌ "Bash writes invalidate the observed state." They don't clear it — they make the recorded version stale, so the next guarded edit fails with FS_STALE_VERSION. That's the CAS safety net working as intended, not state destruction.

If the agent that lives inside this system misreads both the remedy and the mechanism, the contract text is carrying less signal than we think.

A second observation: partial reads satisfy the guard fully

In the s69 recovery, the agent read README.md with limit: 6, offset: 26 — six lines — then successfully edited three unrelated regions. Per-file versioning means the guard guarantees "the file hasn't changed since some read", not "the model has seen the region it's editing". That's coherent if the guard's only job is CAS; it's a real weakness if read-before-edit is also meant to prevent blind edits.

Directions worth discussing

1. Say the quiet part in the tool description. One sentence in edit/write: reads and writes through bash (or any non-fs tool) do not count as observation and do not refresh the version. Cheapest fix, covers the most common collision.
2. Let bash file access emit observations. The sandbox layer already sees confined file access; registering bash reads/writes into the observation map would eliminate the toolchain split entirely. Cost: the shell capability would need to attribute file accesses to paths, which it currently doesn't parse — likely not worth it.
3. Decide what the guard is for. If it's purely CAS/freshness, document that partial reads satisfy it. If it's also meant to prevent blind edits, a six-line read shouldn't green-light editing three other regions.

Related to #3144 — same meta-pattern: the harness possesses a fact (sandbox denied this / this file was never observed) that the model needs for correct diagnosis, delivered through a channel the model doesn't reliably receive.

[tommy0103]

Follow-up thought on the partial-read bypass, because I think it points at something deeper than a documentation gap: the pre-edit observation gate should probably not exist for edit at all — the check belongs inside the edit operation itself.

edit is already self-checking

The edit contract is "old_string must match literally and uniquely." That is a content assertion: if the model's belief about the target region is wrong — whitespace drift, misremembered content, file changed — the edit fails on its own, with an actionable error. Whether the model has seen the region it's editing is a question the edit executor can answer by itself; it doesn't need a prior state machine answering on its behalf.

What does the pre-edit gate add beyond old_string matching? Three things, none of which hold up well for edit:

1. Whole-file freshness (FS_STALE_VERSION). Catches "the file changed outside the edited region since you read it." But edit is surgical: changes elsewhere don't affect this replacement's correctness, and nothing is lost — untouched regions are preserved. This protects against a stale mental model, not against data loss — and that defense is leaky anyway, since the model's context for the whole repo is perpetually partial. One file's version CAS can't change that.
2. Forcing file content into the model's context. A quality goal, not a safety one — and it's unenforceable at file granularity, as the trajectory in the OP shows: a 6-line partial read unlocked edits to three unrelated regions. A hard gate whose spirit is unenforceable teaches models to satisfy the gate, not to read.
3. Clobber protection for write. This one is real: full-file overwrite has no old_string self-check, so blind writes can destroy others' changes wholesale. But that's write's requirement — the current design bundles both operations under one guard and locks edit with write's justification.

The inverted incentive

The part I find hardest to defend: CAS only applies when an observation exists. So from the model's strategy perspective, an edit to a never-read file can never fail with FS_STALE_VERSION — there's no baseline to compare against. Observing a file makes your subsequent edits more likely to be rejected; never observing keeps them uncheckable. A mechanism where compliance increases your failure rate has its incentives backwards, and the 6-line partial-read unlock is exactly what a model finding the local optimum looks like.

What "push the error down into edit" would look like

The semantics become the standard optimistic-concurrency shape: CAS is an option the caller exercises by presenting a version, not a mandatory precondition the server imposes.

• edit with no prior observation → just run it; old_string match/uniqueness is the whole check. With a prior observation whose version is stale → FS_STALE_VERSION (protects the caller who did the reading).
• write keeps the observation/CAS requirement — or at minimum refuses to overwrite an existing, never-observed file — because that's the only path with real data-loss risk.
• "Read before you edit" demotes from hard gate back to guidance in the tool description: a model that blind-edits gets educated by edit's own errors, not by a doorman checking whether it read.

This doesn't require touching the provider's CAS primitives — fs-observation-policy is already a pluggable policy (its README states the bare tools mutate unconditionally without it), so the change is to the default composition and the fs/edit-intent decision, in line with the repo's pre-release "correct foundation over compatibility" stance.

Worth steelmanning the status quo once: read-before-edit became industry convention because early models really did blind-edit from grep output with subtly wrong old_strings. But notice — that failure mode surfaces at edit time as a unique-match failure, which is precisely the argument for letting edit report it. The gate's actual function today is closer to "nudge the model to read more context," a prompt-level objective encoded as a hard state machine — hence the bypasses, the inverted incentive, and the six rejections in the OP's trajectory.