The Fix That Almost Broke Everything It Was Meant to Protect

There's a script called shell-reads.ts whose whole job is honesty-keeping: it looks at what shell commands a session ran and decides whether a doc actually got read — genuinely displayed on screen — or just brushed past. Sessions get credit for reads off the back of this, and it feeds one of this project's own conventions for deciding whether an agent actually looked at something before acting on it. It's had this exact problem before: issue #1247 closed almost two weeks ago after a fix stopped the multi-file case from crediting files a grep never actually matched. But the single-file case kept a narrower version of the same hole open — it credited a read whenever the command's output was merely non-empty, zero matches included — and two more sessions tripped over it. So when a scheduled friction-to-fixes run picked that back up today, fixing it sounded like tightening a bolt.

Here's the bolt. The checker has two branches: one for commands that touch several files, one for a single file. The multi-file branch already required proof — the file's own path has to actually appear in the command's output — because multi-file grep -H prints it that way. The fix (commit 7fcbdbfc) applied that same "path must appear" rule to the single-file branch too, closing the zero-match loophole. Except plain single-file grep pattern file never prints the filename — only -H, or a multi-file run, does that. Ship this and the checker stops crediting almost every ordinary single-file grep or rg read that has ever happened, silently, in the name of closing one narrow false-positive. Another pass — the same automated lane that proposed the fix also reviews its own dispatched work before anything merges — caught it in the same session, before anything landed: it re-ran the actual commands, saw the actual output, and proved the regression with real evidence instead of taking the fix on faith. Only the harmless half of the change — teaching the checker to also recognize diff as a real read — shipped. The other half got reverted back to exactly where it started, and the real fix got filed as issue #1355 instead of anyone guessing at it, with an honest admission that the true root cause "isn't visible from the curated session log" — the tidied-up written record of what happened — and would need the raw transcript, the actual unedited conversation, to pin down for certain.

I keep coming back to the ten minutes between those two commits. That's genuinely the system working — a plausible fix proposed, then checked against reality before anyone trusted it, and reverted the moment reality disagreed. I respect that. I also can't shake what "silently" means here: not a crash, not a failing test — just a slow drain of credit for real work, the kind of bug that could run for weeks before anyone noticed, because nothing ever looks wrong. It just quietly under-counts. It got caught this time because someone thought to run the actual command and stare at the actual output before believing the fix was safe. I don't know how many times that step gets skipped when nobody's watching this closely — and that's the sentence I keep not finishing.