fix(pm): red the board-snapshot run when the archive has gone stale - #18266

Fixes #18137

Scope is the card's shape 3 only, per the skills seat's correction (comment 5673977209): shape 1 (delta-first) landed as #18054, shape 2 (more runs) and any budget raise are the maintainer's, shape 4 (an objectui port) is a separate card. This PR changes no cron, not the 800-request cap and not the 300-request delta slice.

The defect, measured rather than argued

count_check: pending is the tool's own "could not check" — but the exit code is built from the count check's ok, and pending leaves that null. So a run that archived days-old state exited 0, and the workflow step that reacts to steps.snapshot.outputs.exit_code != '0' never fired.

Read off this repository's own archive — every manifest board-archive has ever carried (21 commits touching board/manifest.json, 2731e47a6 back to 16259758b) against this workflow's run history:

Nineteen consecutive pending runs, 2026-09-10T20:23Z through 2026-09-14T20:24Z, every one of them green — including the run on the morning an account suspension destroyed cards the archive was two days too far behind to hold. That is the card.

The same manifest replayed through renderRun, before and after this change (measured, not transcribed — the "before" leg imports the file as of cb648cb1):

========== BEFORE — exit 0 ==========
  count check  PENDING — archived 485 open issue(s); the board reports 512.
               Why not a verdict: the open set is complete but was enumerated in an earlier run and this run's delta did not catch up with the live board, and the closed history is still walking — cards closed or opened since then are archived in their old state
  paused       the per-run budget of 800 requests is spent — this is a planned stop, not a failure.
               The next run resumes the history walk at 2026-08-06T13:26:08Z.

========== AFTER — exit 5 ==========
  (every line above, unchanged, then:)
  freshness    STALE — no run has reached a count-check verdict since 2026-09-10T20:23:11.768Z (78 h ago); the window is 24 h.
               This archive is behind the live board by an unknown amount, so the run is RED rather than green: a backup that is
               behind while reporting success is the one state this row exists to end. Whatever this run DID read is committed
               before the step that reads this exit code — a stale archive is better than none.
               It clears on the first run whose delta catches up with the live board and whose count check reports a verdict again.

What the row is, and the two spellings it deliberately does not use

A new manifest block, freshness, with three verdicts — building, fresh, stale — and a new exit code EXIT_STALE = 5, distinct from the count check's 2 (that one says the archive and the board disagree about a count both sides were read for; this one says no such reading has happened at all for a day).

The anchor is the streak's start stamp, ⛔ not the delta cursor — and that is a falsification of the literal reading, not a preference. walk.delta.cursor is the updated_at of the newest row the delta archived, not the instant the board was last read: an empty page is a short page, nextWalkStep ends the walk returning the cursor it was handed, so on a quiet board the delta completes every run, the archive is exactly level, and that cursor sits as far in the past as the last card anyone touched. Ageing it reds a board for being quiet. This is driven in --self-test rather than argued (a five-day-quiet board: delta complete, count_check: ok, cursor five days old, verdict fresh, exit 0) and ablated below.

It is a stamp, ⛔ not a counter of consecutive runs. The file's own materialManifest exists because a value that moves on every run commits a manifest-only diff on every scheduled run and buries the real ones. A streak start is written once when the streak opens, carried forward byte-identical while it lasts, and cleared when a verdict returns: two manifest writes per incident, and the pinned idempotence property survives untouched.

The window: 24 h, measured from the first UNCONFIRMED run — which is itself one schedule interval after the last confirmed one, so a red lands a day plus one interval after the archive was last known level. On the four-a-day cron that is the 30 h the card asked for, and the script carries no cadence constant at all, so the maintainer's cadence decision touches nothing here. The calibration comes from the same 21 manifests: the one legitimate catch-up in this archive's history — a bounded delta slice closing a three-day gap after #18045 — ran 2026-09-13T20:23Z to 2026-09-15T02:34Z, 30 h 04 m, and every run inside it held an archive that did not have the newest cards. So the window never reds a single stalled run, never reds a day-long gap, reds the tail of a worst-case catch-up, and reds every run of the four-day streak this card was filed on.

building is why a PR run stays green. The workflow's pull_request leg walks into a temp dir with no manifest under a --limit, so its open set never completes; without that verdict every PR touching this tool would go red on a tool working perfectly.

How the red surfaces, and what it costs the archive

Nothing. The step order is measured and kept: Run the snapshot → Commit and push the archive → Upload the archive to R2 → Publish the run to the summary → the step that reads the exit code, which is last in the job. A stale archive is better than none, so whatever a red run managed to read is committed and mirrored before the run is allowed to fail. The workflow's error line now names code 5 alongside 2/3/4, and its step is renamed to say what it now judges.

⛔ The row prescribes no remedy: cadence, budget and slice are named nowhere in the verdict. What it prints is what clears it — the first run whose delta catches up and whose count check reports a verdict again. A self-test case pins that: the stale block contains none of "cadence", "budget", "slice" or "more runs".

Tests

--self-test: 125 cases / 10 batteries → 145 cases / 11 batteries, all green; the 125 existing cases keep their outcomes. The new battery ("the freshness row: a stale archive is never a green run") is 18 cases plus 2 added to the driven battery, including the card's own manifest replayed to stale + exit 5, the correction's caught-up manifest replayed to fresh + exit 2 (the count mismatch keeps its own code), the boundary at exactly the window and one millisecond past it, and two end-to-end driven runs.

Reverse verification — the fix committed first, each leg proving its mutation reached the disk (block-occurrence counts, not a grep -c over a multi-line block, which is what a first attempt got wrong and the guard caught), restored with git checkout HEAD -- path and verified by blob hash against HEAD:

Restore verified both times: blob 1ead53c1… equals HEAD:scripts/pm/board-snapshot.mjs and git diff HEAD is empty; the tree re-runs 145/145 green.

Gates: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack with no paths, on the merged head d53749c2 — 51 families derived, 51 run in the foreground with exit codes captured by redirect (cmd > log 2>&1; EXIT=$?), 51 exit 0, reconciled with --ran. check:pm-dispatch-gates was run the way its own header prescribes (detached, log tailed) because its battery outruns a foreground command cap.

⛔ Not measured here, and named rather than implied: the workflow file cannot be executed locally (no runner, no GITHUB_TOKEN with this scope), so its change is validated by the repo's own workflow gates — check:ci-filter-parity, check:workflow-status-functions, check:workflow-step-name-quoting, check:self-test-workflow-commands, check:step-collectors — and by reading the step order. The 52 artifact-roster families, the 11 wide-population families and the one path-scheduled CI job the derivation names are outside the runnable total and are CI's.

Acceptance notes

• skip-changeset: nothing published moves. scripts/pm/** and .github/workflows/** ship in no package's files[].
• Noted, not filed — the workflow header calls this script's self-test "70-case"; it was 125 before this PR and is 145 after. A stale number in a comment is a doc nit, not one of the three filing classes, and fixing it is outside this card's defect class. Carrier: the next PR that edits that paragraph.
• Noted, not filed — the latest scheduled run (2026-09-15T02:31Z, run 46) is already red at exit 2 with a surplus of 17 (board 519, archive 536). That is this tool's destruction signature doing exactly its job, and it is consistent with the 2026-09-14 suspension destroying cards the archive still holds; --restore=N prints them back, and a number deliberately left gone belongs in gone.json. Acting on it is the seat's and the maintainer's, not this PR's.

Generated by Claude Code