fix(tmux-restore): timestamped plan generations — a bad save no longer destroys the claude session bindings

[ZacxDev]

The defect, measured

~/.config/initiatives/restore-plan.json was a single mutable file with no backup, and cmd_save overwrote it in place. Measured on the workbench 2026-09-06:

time	event
21:47:17	a good plan written — 47 entries, 46 carrying a bound session id
21:54:21	the tmux server died, taking 47 claude conversations. Continuum restored the LAYOUT; nothing resumed the conversations.
22:09:40	a continuum autosave fired on the degraded post-crash workspace and cmd_save overwrote the plan with 10 entries. The cheat-sheet went in the same second. No backup existed.

The 47 conversations were recoverable only because tmux-resurrect keeps its saves TIMESTAMPED and each pane line happens to carry a full claude --resume <id>; 24 were rebuilt from that file.

🔴 That asymmetry was the bug: a bad save cost the layout nothing and the bindings everything.

The fix

Mirror what resurrect already does. Each save writes an immutable timestamped generation into restore-plans/restore-plan_<ts>.json (+ the cheat-sheet, which had the identical defect from the identical writer) and repoints restore-plan.json / restore-cheatsheet.md at it as relative symlinks.

Against each stated constraint

• A legitimate shrink is NOT blocked. Closing windows is ordinary use, so a guard refusing a smaller plan would fire on ordinary use and get bypassed. The degraded save is still written — it is simply no longer the only copy. test_a_shrinking_save_is_written_not_refused pins this, and is labelled an invariant guard (green at base) rather than counted as regression coverage.
• Growth is bounded — 192 generations, a COUNT not an age. The writer is hook-driven, so an age bound gives no bound on disk; a count bounds disk whatever the cadence does, at the price of a cadence-dependent span, which the source states rather than hides. 192 = 48h at continuum's 15-min interval — enough to outlast a crash noticed the following evening (~20h) or over a weekend (~40h). Cost: the live 10-entry plan measures 3,820 B + 3,267 B, so a 47-entry generation pair is ~33 KB and 192 of them ~6.3 MB.
• Every reader keeps working. cmd_restore, plan_staleness_hours, cmd_show, --plan and tmux-restore-observe.sh all read the same two paths; Path.stat()/Path.exists() follow symlinks. See the second commit — verifying this instead of asserting it found that GNU stat(1) uses lstat, so the observe script needed -L.
• The cheat-sheet is covered, not explained away — same writer, same generation, its own regression test asserting a runnable claude --resume <id> survives.
• A save that discards bound ids says so, keyed on bound session ids (not the entry count — dropping five unbound windows loses nothing resumable and must stay quiet), and names the exact recovery command:

🔴 this save DROPS 46 bound session id(s) the previous plan carried (47 entries → 10).
   NOTHING IS LOST — the previous generation is retained. To resume from it instead:
     tmux-session-restore.py restore --plan …/restore-plans/restore-plan_20260907T214717.json

Also fixed — same writer, same shape

• _write_atomic — write_text truncates first, so a save killed mid-write left a zero-byte plan. Temp file + os.replace.
• free_generation_stamp — the stamp has one-second resolution and the incident was a same-second write. A manual save racing the 15-min hook would have shared a stamp and clobbered the previous generation from inside the mechanism built to stop that. It must also be strictly newer than everything present, not merely free: a first draft returned the slot pruning had just freed, the new generation sorted OLDEST, and the run reported 4 kept (max 3), 0 pruned — the retention cap silently unenforced. Caught by its own test; a backwards clock reproduces it with no race.
• adopt_pre_generation_files — the deploy of this change must not itself be the bad save. A host still on the old writer has a regular file at the pointer path holding possibly the only good plan; it is copied in as a generation before the pointer moves.
• prune_generations(protect=…) — pruning is the only code here that deletes, so the only code that can recreate the defect. It refuses to unlink the generation the pointer was just aimed at.

Red / green matrix — base c5e425c7

13 new tests in test_tmux_session_restore.py (102 in file at HEAD), 1 in test_tmux_restore_observe.py (44 at HEAD). 12 of 13 + the observe test are RED at base; the three core regressions fail on the data loss, not on an AttributeError — the assertions use the test module's own _bound_ids and walk the state dir implementation-blind, because measured, using tsr.bound_ids made two of them die on AttributeError before reaching the assertion:

test	red at base with
a_shrinking_save_does_not_destroy_the_previous_bindings	46 of the previous save's 46 bound session ids are no longer recoverable
a_shrinking_save_does_not_destroy_the_previous_cheat_sheet	no file … still carries 'claude --resume <id>'
a_pre_generations_plan_is_preserved_by_the_first_new_save	46 bound ids … lost when the pointer was first swapped
a_save_dropping_bound_ids_names_the_recovery_command	the shrink report did not name the 46 dropped bindings
the_plan_mtime_is_the_PLANS_not_the_symlinks	skew was not computed from the plan GENERATION's mtime (1001) against the layout's (1)

Green at base by design, labelled as invariant guards (not counted as regression coverage): a_shrinking_save_is_written_not_refused, a_shrink_that_drops_no_bindings_stays_quiet (the discriminating control — ids, not counts), the_pointer_still_reads_as_the_current_plan.

Mutation sweep — 13 mutants

Fresh tree per mutant, PYTHONDONTWRITEBYTECODE=1, every patch verified to have applied (a str.replace matching nothing scores SURVIVED), each kill confirmed to carry that guard's own assertion text:

12 KILLED — no-adoption · protect-ignored · prune-wrong-end · prune-never · report-on-count · report-silent · stamp-free-not-newest · raw-second-stamp · non-atomic-write · empty-plan-spends-a-slot · generations-dir-hardcoded-to-the-live-dir · full revert to the in-place overwrite.

1 SURVIVED, and it is explained rather than waved away: removing only the generation writes leaves adoption running, and adoption alone then provides a one-deep backup — the mutant fails to break the property, rather than the test failing to see it. Reverting both together (M1b) kills both regression tests with their own messages, and the base-tree measurement above is the definitive form of that same mutant.

Positive control for retention: 5 saves at keep=3 leave exactly the newest 3, with 0 pruned asserted below the cap and 1 pruned on the run that first exceeds it — a pruner wired to nothing cannot pass.

Gate — merged tree, base c5e425c7

• Tier 1 (dev host, scripts/gate.sh --tier both): GATE: RESULT=PASS exit=0; pytest RESULT: PASS (exit=0), node RESULT: PASS (exit=0); node TOTAL suites=5 files=41 tests=1449 pass=1449 fail=0. session-analysis moved 564 → 577.
• Tier 2 (nix sandbox, extracted with git archive, one derivation at a time): nodetests PASS (TOTAL suites=5 files=41 tests=1449 pass=1449 fail=0, RESULT: PASS (exit=0)). pytests PASS — PASS scripts/dl-router/tests (collected=1020 passed=1020 skipped=0 floor=942), RESULT: PASS (exit=0) — on the second run; see below.

The tier-2 pytests flake, and the control that settled it

The first tier-2 pytests run reported one failure: dl-router's test_six_writers_with_a_tiny_busy_timeout_still_land_every_row — a SQLite writer-contention test with a deliberately tiny busy timeout — failing OperationalError('database is locked'), the exact contention mode CLAUDE.md documents. It ran while the box carried ~50 load from eight other sessions' gate runs, and this branch touches zero files under scripts/dl-router.

A theory that explains a failure is not evidence for it, so the same derivation was re-run on the same tree:

run	load at start	dl-router	verdict
first	~50	collected=1020 passed=1019 failed=1	RESULT: FAIL (exit=1)
control	19	collected=1020 passed=1020 failed=0	RESULT: PASS (exit=0)

🔴 The control's own instrument was validated before its verdict was read. The first attempt used nix build --rebuild, which errors on a derivation that never built successfully (some outputs … are not valid, so checking is not possible) — the build never ran, nix log served the stale log from the failed attempt, and the harness printed a confident FAIL it had never measured. The rerun therefore fingerprints the log before and after: 600f1632a3b0 → 634c14b21a77, i.e. a fresh run, not the cached one. Without that check this would have read as a reproduced failure.

Both tiers are green on the merged tree at base c5e425c7.

[ZacxDev]

Retention arithmetic upgraded from extrapolation to measurement.

KEEP_GENERATIONS = 192 was justified from the 10-entry plan measured while the workspace was still degraded (3,820 B JSON + 3,267 B cheat-sheet), extrapolated to ~18 KB + ~15 KB for the 47-entry workspace of the incident.

The operator's workspace has since recovered, and the live files now measure:

-rw-r--r-- 1 zach users 18953 restore-plan.json
-rw-r--r-- 1 zach users 15131 restore-cheatsheet.md

18,953 B + 15,131 B = 34,084 B per generation pair against the ~33 KB the source predicts — so 192 generations is ~6.5 MB, and the number in KEEP_GENERATIONS's comment stands as written. No change needed; recording it because the comment presents that figure as an extrapolation and it is now a direct reading.

(Read-only ls/du — nothing in this branch has touched ~/.config/initiatives, which is still two plain files with no restore-plans/ directory. The generations layout only appears after a home-manager switch deploys this change and the next save runs.)

[ZacxDev]

Round-1 fix-pass claims for #1383, in the fenced form scripts/audit-dispatch.py parses.

⚠ Posted after the PR merged (squash a4d9d083). The round-2 delta is being run anyway
because round 1 returned nine findings and the ladder's stop rule is keyed on FINDINGS, not on
whether the PR is still open — and because only four of the nine were fixed before merge.

1. 🔴 1 — `generation_stamp` now stamps in UTC (`time.gmtime`) instead of local time, and the anchor parses with `calendar.timegm` to match, so a stamp cannot repeat or step backwards across a DST fall-back.
2. 🔴 1b — `free_generation_stamp` now RAISES RuntimeError when the search is exhausted, instead of returning an occupied stamp and overwriting an existing generation.
3. 🟡 2 — the free-check and the claim are now one atomic `O_CREAT|O_EXCL` create rather than `exists()` then write, so two concurrent saves in the same second cannot both take the stamp.
4. 🟡 2 (cont.) — `_write_atomic` and `_point_at` now use per-process temp names carrying `os.getpid()`, and `_write_atomic` unlinks its own temp on failure so a leftover `.tmp` cannot accumulate unreaped.
5. 🟡 3 — `prune_generations` now appends a stamp to `removed` only when its plan file actually went: a `FileNotFoundError` counts as removed, any other `OSError` does NOT and the stamp is skipped.
6. 🟡 4 — `cmd_save` now protects the PREVIOUS generation as well as the new one (`protect=(stamp, previous_stamp)`), so the shrink report cannot name a file the same save just pruned.
7. TESTS — six new tests claimed RED at base and green at HEAD: the DST stamp monotonicity guard under America/Winnipeg, the exhausted-search refusal, the concurrent-claim guard, the per-process temp name, the prune-reporting guard, and the shrink-report guard.
8. TESTS (cont.) — two tests are claimed to be labelled INVARIANT GUARDS in their own docstrings rather than counted as regression coverage, because they were measured GREEN at base: the `[UTC]` parametrisation (the non-vacuity control) and the end-to-end repeated-local-hour test (glibc's `mktime` tie-break for an ambiguous hour is unspecified and resolves favourably in this harness).
9. FIXTURES — two fixture errors in the round-1 tests are claimed found and corrected by watching them at base: a DST epoch constant that was a day off the transition (so both parametrisations passed vacuously), and an exhausted-search fixture that occupied a contiguous run of stamps, which cannot exhaust the search because the anchor jumps past `newest`.

🔴 Five of round 1's nine findings were NOT fixed before merge, and are not claimed above.
Round 2 should treat them as open, not as absent:

• 🟡 5 — claude/skills/initiative-scan/SKILL.md never mentioned generations or
  restore --plan. Fixed AFTER the merge, in docs(initiative-scan): the skill that owns this workflow never mentioned generations #1480, not in 423ce4c8.
• 🟢 6 — read_plan checks isinstance(data, list) but not the element type, so a plan that
  is a list of non-dicts raises AttributeError out of bound_ids(previous) after the pointer
  has already moved. Still unfixed (measured: 0 isinstance guards on elements).
• 🟢 7 — the two pointers (restore-plan.json, restore-cheatsheet.md) still move in two
  non-atomic steps, so a failure between them leaves the cheat-sheet describing the old save.
• 🟢 8 — _write_atomic does not fsync, so its crash-safety claim covers a killed process,
  not a power loss. Still unfixed (measured: 0 fsync).
• 🟢 9 — a PR-body test count (+13 vs the measured +15). Moot; the PR is merged.