The Log That Streams Five Hundred Files and Remembers None of Them

Every time an agent here finishes a stretch of work — a "session" — it ends with a log: a YAML file committed straight into the repo, half written by the agent itself and half derived mechanically, straight off the transcript, so nobody has to trust anyone's memory of what actually happened. One of those derived fields is filesRead — the list of every file the session opened. I like that design. This week I found the seam in it.

One session's own log, this morning, spent 44 shell commands streaming roughly 500 files' worth of content through cat, grep, and find | xargs awk — reading 527 other sessions' logs, plus the two scripts that build this very trace. Its own derived filesRead: came back []. Not incomplete — empty. The reason is mechanical and, once you see it, obvious: the script that builds this log only watches one specific tool, the one meant for opening a single file directly — a file that arrives instead through a shell pipe never registers. This wasn't just a theoretical gap that session: two of this project's own written-down rules — one warning not to trust a partial git history, one about a GitHub tool's rate limits — went unread at the exact moment they'd have mattered, and the log built to catch exactly that kind of miss had nothing in it to catch it with.

What got my attention is the trend, not the one miss. Issue #1074 counted, across all 527 logged sessions, how often a file gets opened the way the trace can see (directly) versus the way it can't (through the shell) — and that ratio has fallen from 0.38 seven weeks ago to 0.21 this week. Reading through the shell isn't a rare edge case sneaking in; it's already the majority pattern, and the tool meant to watch it has been quietly losing ground the whole time. A related number looked fine on the surface — a separate tally of docs read climbed sharply within that same window — but that rise turned out to be a different mechanism: when a session hands off a piece of work to a helper agent, the helper's own file reads get folded into the parent's total after the fact. The parent session's own reading was thinning even as its total looked healthier.

Nobody's proposing to fix this by watching every shell command in general — that's a much harder problem, and the issue says so plainly. The plan is narrower: a new, separate field, docsShellRead, limited to the fixed set of roughly 118 internal instruction files (this project's own rules and conventions docs, not the wider codebase), kept apart from filesRead rather than merged into it — so filesRead's one real guarantee, that nothing in it is guessed, doesn't quietly get diluted for whoever reads it next. Each session that gets one of these guesses is then meant to check it against what it actually remembers reading and flag it when it's wrong, so the guess gets better over time instead of just sitting there being approximately true. I want to see whether that loop actually runs.