agent-farm: migration backups (~/.agent-farm.bak-*) are never reaped

[waleedkadous]

Found during a disk audit (2026-07-25): a ~/.agent-farm.bak-20260702-113930 directory — created by a state migration on 2026-07-02 — was still on disk three weeks later at 18 GB (a full copy of the agent-farm dir, dominated by the logs it duplicated). Nothing ever deletes these backups.

Proposal:

• Migrations that create a .bak should record it and reap it after a verification window (e.g. 7 days of successful operation on the migrated state), or
• codev doctor should at minimum surface existing .bak dirs with age + size so the human can decide.

Related: the no-rotation issue filed alongside this one — the .bak was so large mostly because the logs inside it had never rotated.

[waleedkadous]

Completion statistics

Shipped in #1242 (merge commit 25b2ef9c, merged 2026-07-25T12:41Z).

Protocol	AIR (Implement → Review)
Iterations	1 — no rework rounds
Started → complete	09:40Z → 12:42Z (3h 1m wall clock)
Active build time	~12 min (09:40Z → 09:52Z, when the pr gate was requested)
Human gate wait	2h 45m (09:52Z → 12:37Z)
CMAP	codex APPROVE/HIGH, claude APPROVE/HIGH — no key issues from either
Required CI	6/6 green

Diff

File	Lines
packages/codev/src/lib/migration-backup-audit.ts	+188 (new)
packages/codev/src/__tests__/migration-backup-audit.test.ts	+182 (new, 14 tests)
packages/codev/src/commands/doctor.ts	+45 −1
codev/resources/commands/codev.md + skeleton mirror	+10
codev/state/air-1239_thread.md	+66
Total	490 insertions, 1 deletion

Implementation LOC excluding tests and the builder thread: 243 — inside AIR's 300-LOC threshold, so no escalation was needed.

Testing

• 14 new unit tests; full suite 183 files / 3655 tests passed, 3 files / 48 tests skipped (pre-existing)
• No flaky tests encountered; nothing skipped by this change
• End-to-end: ran the built codev doctor against a real home directory carrying the actual leftovers. It found all five, with sizes cross-checked against du -sh

Notes for the record

The issue's first proposal was not implementable as written, and finding that out was most of the value of the investigation. No code in this repo creates the ~/.agent-farm.bak-* directory reported here — git grep -i backup over packages/** returns nothing. Those directories came from ad-hoc procedure during the #1118 state consolidation, not a shipped code path, so "migrations that create a .bak should record it and reap it" has no migration to instrument. The second proposal (surface in codev doctor) was implemented instead.

The scan was extended to a second leftover family the issue didn't mention but which the codebase genuinely creates and also never reaps: the state.db.pre-merge-<timestamp> renames (plus -wal / -shm sidecars) from db/consolidate.ts:335 renameWithSidecars, which deliberately renames rather than deletes the source state.db after merging into global.db. The real-machine doctor run found three of these alongside the two hand-made copies.

Deliberately not auto-reaping. Doctor reports path + age + size and prints the exact rm -rf; it never deletes. These are multi-gigabyte copies of the user's own state, and removing them on a timer with no consent step is not something a diagnostic command should do. The 7-day window gates the warning, not a deletion.

A test caught a real bug worth recording. The first match pattern was /bak/i, which reads as obviously correct and is not — backup contains back, not bak — so every agent-farm-db-backup-* directory, including both of the ones actually on the reporter's disk, was silently skipped. The test asserting the literal directory names from #1118 is what pinned it; a generic pattern test would have passed. Pattern is now /bac?k/i.

Follow-up

The 18 GB figure in the report is mostly duplicated unrotated logs, so the sibling log-rotation issue is the larger lever on disk. This change makes the leftover visible; rotation makes it small.