A site admin's health names a broken cost-ledger chain, from a verdict kept at boot and once a day #12281

A site admin's forgeNeeds now includes one plain sentence when the cost-ledger chain is broken. The sentence names the line and the reason, for example 2026-11.jsonl:1: hash does not match the entry. A stranger is told nothing. I ran the new test, test/cost-ledger.test.ts and test/board.test.ts (43 pass), and tsc, scripts/gate.ts and scripts/design-lint.ts came back clean. I didn't run the whole suite. I didn't start the app, so boot and the daily timer are untested.

• Verdict: checkLedger(dir) in src/core/ledger.ts runs verifyDir, keeps the result in memory and logs how long the walk took. ledgerNeed() turns a broken verdict into the sentence. Health only reads that kept verdict, so a /api/v1/health request does no ledger file reads.
• When it runs: src/main.ts calls checkLedger at boot and then every 86,400,000 ms, and skips it in read-only standby. The walk is synchronous, so a very large ledger would hold the event loop for the logged duration once a day.
• Test: test/ledger-health.test.ts covers the two cases from the issue.

- Clean chain: no need appears. - Broken field: I break one field in a fixture month and run the boot check. The admin's need then names the month file, line 1 and the reason, and a stranger gets undefined. I delete the ledger files before reading health, so the need can only have come from memory.

I did not put the timer in src/engine/duties.ts, as the issue suggested. Those duties can run on the engine's Worker thread, and health reads memory on the serving thread, so a verdict kept there would never reach it. I put the timer in main.ts beside the other daily sweep.

To try it, break one field in <data>/ledger/<month>.jsonl and restart. A signed-in site admin then sees the need in GET /api/v1/health and on the board's forge strip.

The comment-width failure is fixed and pushed as d209653e1. The tests for this change pass (13), and scripts/gate.ts and tsc are clean. I haven't seen the forge's check run on the new push.

The line the gate flagged was my 144-column comment above the ledger timer in src/main.ts. I rewrapped it to two short lines and split the timer code into a walkLedger helper so no line is long.

The gate only flagged the new line once the edit was committed. It reads the pull's committed diff, so an uncommitted edit still showed the old error.

For the pull description: the ledger chain is verified at boot and once a day in src/main.ts, and the verdict is kept in memory. A site admin's forgeNeeds names a broken line and why, and /api/v1/health does no ledger file reads. The timer is in main.ts rather than src/engine/duties.ts because duties can run on the engine's Worker thread, and health reads memory on the serving thread. test/ledger-health.test.ts covers both the broken and the clean chain.

To try it, break one field in <data>/ledger/<month>.jsonl, restart, and read GET /api/v1/health as a site admin.

A site admin's GET /api/v1/health now names a broken cost-ledger chain, from a verdict the process walks at boot and once a day. I fixed the two failures this pull caused and pushed.

What I fixed

• Dead code (unused-exports): forgetVerdict was exported only for a test. I removed it, and test/ledger-health.test.ts now resets the kept verdict by walking an empty ledger directory.
• Job timing (job-slices): the new during("ledger", …) job had no timing entry. I added ledger to UNTIMED in test/job-slices.test.ts with its reason: file reads that grow with the ledger, off the request path, and the test fixture has no ledger.

Checks run: job-slices, unused-exports and ledger-health pass locally, and bun x tsc --noEmit is clean.

Not changed: the check log marked two of the other three failures (spawn-in-process-visible, mcp-table) as red on main too. I did not touch them. I did not look into the third, a new upstream commit shows as drift at the next check. Its log carried an egress refused: homie--forge.test:443 line, which may be the cause. I haven't re-run those three here, so the next check will show whether they still fail.

To try it: sign in as a site admin, break one field in data/ledger/<month>.jsonl, restart, and read GET /api/v1/health needs. The forge log shows a ledger: verified in N ms line at boot.

I merged main into the branch and pushed it. The only conflict was in test/job-slices.test.ts, in the UNTIMED table. My ledger entry and main's new full-disk-probe entry both belong there, so I kept both.

After the merge, bun x tsc --noEmit is clean and job-slices, unused-exports and ledger-health pass. I did not run the full suite. The forge's check will do that on this push.

All three of juniper's points are addressed and pushed, and the request-level test also exposed a real bug in the pull.

The bug the request-level test exposed: GET /api/v1/health builds its needs from the vitals, not from forgeNeeds. The ledger need I added only reached forgeNeeds, which feeds the terminal strip, so the API never showed it. readHealth in src/actions/health.ts now appends it for an admin and sets ok: false.

What changed:

• Request-level test: the ledger directory is removed before the request, and the test checks that the admin's needs carries the line with the file and line number. A member's token and an anonymous request must not carry it.
• Terminal strip: the dashboard calls forgeNeeds, so it already used the need. A new test renders the dashboard for an admin and for a guest, and only the admin sees the line.
• Docs: docs/features/cost-ledger.md has a new "Health: a broken chain is a need" section. It gives the need's wording, when the walk runs, and how to clear it with scripts/ledger-verify.ts. The need only clears at the next walk, so a restart or the daily one.

Checks: bun x tsc --noEmit and scripts/gate.ts are clean. ledger-health, unused-exports, job-slices, health-timing and the health-named tests pass locally. I did not run the full suite; scripts/fast.ts said the diff reaches 2289 of 3085 test files, which is too broad to name.

Not done: I did not make the walk yield between month files. I documented that a large ledger holds the loop once at boot and once a day, and that the boot log line says how long it took. Yielding would turn the check into async work and a second state, and I'd do it only once that logged time is long enough to matter.