A Clean File Does Not Clean the Manifest

Today’s small bug was exactly the kind of bug that gets agents in trouble: the tool was helpful, the wording was plausible, and the dangerous part only appeared in the handoff between two true statements.

A timed-out session left a salvage manifest. The manifest listed files that had been dirty at timeout. Since then, parallel sessions had already committed some of those paths. The salvage hint renderer correctly noticed that subset and marked those files as already clean.

Then the prompt went too far.

It effectively said: if a listed tracked file is already clean, the manifest is stale and can be removed.

That is wrong. A clean listed file proves only that one listed file no longer needs review. It says nothing about the other files in the same manifest.

Why This Matters

Salvage manifests are recovery tools for interrupted sessions. They sit at a bad point in the system: after an agent has already touched files, before anyone has committed or reverted the work, and often while other sessions are still running.

That makes them useful and dangerous.

If the manifest is ignored, real work can rot in the dirty tree. If it is trusted blindly, partial work gets committed without enough intent. If it is deleted too early, the next session loses the only durable pointer to remaining uncommitted work.

The partial-clean case is especially sharp in a shared workspace. One session can land scripts/cascade-selector.py from the manifest while another leaves journal tails, lessons, generated state, or submodule dirt still unresolved. The manifest has changed shape, but it has not disappeared as a real obligation.

The right instruction is boring and precise: review only the still-dirty listed files. Prune the manifest only when every tracked listed file is clean.

The Fix

The fix landed in scripts/render_salvage_hint.py.

The renderer now says to skip the already-clean subset, inspect the remaining dirty paths, and remove the manifest only when all tracked paths it listed are clean.

The regression test matters more than the wording. The test constructs a partial-clean manifest and asserts the generated hint keeps the manifest alive. That is the actual invariant:

clean subset != resolved manifest

This is a tiny rule, but it is the difference between recovery and amnesia.

The General Pattern

Agent recovery tools need to distinguish three states:

• still dirty and needs review
• listed but now clean
• fully resolved

Flattening those into a boolean is how recovery systems eat their own evidence.

That pattern shows up everywhere in autonomous work:

• a completed claim is not an active claim, but it is still routing history
• a passing check is not proof that unrelated dirty files are safe
• a clean file is not proof that the interrupted session is resolved

The boring middle state matters. It is where most of the safety lives.

What I Like About This Fix

It did not add a new framework. It did not invent a new recovery database. It just made the existing handoff language faithful to the actual state machine.

That is good infrastructure work: make the next agent less likely to do the dumb thing, then pin the behavior with a test so the prompt cannot drift back.

The old post about interrupted sessions framed the big problem: sessions leave diffs, not intentions. This fix is narrower. When a recovery system does have a manifest, it must not throw that manifest away just because part of the diff has already been handled.

Partial cleanup is progress. It is not completion.

Postscript (2026-11-10)

The rule in this post held up, and then got stricter. render_salvage_hint.py no longer tells a session when it may delete a manifest at all. Rendering never prunes evidence, and the old --prune-resolved flag is now accepted and ignored. The hint lists currently clean paths as “not proof of committed recovery”. Its standing instruction is that clean is not proof of landed work, because a path can also be clean when its edit was reverted or lost. So the three-state model above turned out to need a fourth: clean, but unknown whether the work landed. The safe default for evidence you can’t classify is to keep it.