ORB-158: close the spend ledger loop

tools/README.md

@@ -12,7 +12,7 @@
 > - `check-calibration.mjs` verifies the model-stamped calibration artifact covers every skill and agent and is under 90 days old.
 > - `wave-plan.mjs` reports same-wave path collisions and unknown affected-file declarations without changing wave order.
 > - `preflight.mjs` verifies an autonomous run's environment before any worktree is created and never repairs a failed precondition.
-> - `teardown-worktree.mjs` removes a completed ticket's Orca worktree immediately after verified Done, only when its evidence checks pass.
+> - `teardown-worktree.mjs` removes a completed ticket's Orca worktree immediately after verified Done, then closes its remaining reservations in the shared spend ledger.
 
 Reusable scripts an agent (or a human) invokes from the CLI. The bar for landing a file here: it has a single clear purpose and you will run it again. One-off commands stay in your shell history or the scratchpad.
 
@@ -32,7 +32,7 @@ Read `CONVENTIONS.md` before adding one. Use the `/make-tool` skill to scaffold
 | `redesign-coverage.mjs` | Asserts the redesign denominator twice: every surface in `surfaces.json` is claimed by exactly one #539 redesign ticket (D35), and every `.tsx` under `apps/*/app` + `apps/*/components` maps to exactly one ticket by directory rule (D38); exits 1 on any unclaimed surface or orphaned file. Survives until #539 completes (D39). | `npm run redesign:coverage` (`--json`) |
 | `arch-map.mjs` | Generates `architecture.json` + `architecture.html` (routes, parity pairs, endpoints, i18n ownership); the drift CI job (`arch-map.yml`) regenerates and fails on drift. | `node tools/arch-map.mjs` |
 | `ai-quota.mjs` | Reads the current account-level Claude and Codex quota windows from Orca's labeled Usage control and the Codex app-server JSON-RPC API, returning both engines in one object while preserving a healthy side when the other is unavailable. Its usage percentages are context only: they belong to no invocation, never feed the fuse, and are never subtracted to infer invocation cost. When `launch-worker.mjs` copies one into a ledger record, the launcher adds the observation timestamp there. Backs `/quota`. | `node tools/ai-quota.mjs --json` (`--help`) |
-| `automation-budget.mjs` | Maintains the append-only per-invocation automation ledger using authoritative input and output token counts. Provider-estimated cost is recorded only when the provider supplies it. Missing token measurements stay absent and make the fuse fail closed rather than becoming zero. The engine-local fuse atomically checks and appends a pending reservation under one ledger lock before worktree creation, so concurrent launchers cannot both pass the same remaining budget. Verified pre-delivery rollback appends a cancellation tombstone; delivered work keeps the pending entry until the worker appends its provider-authoritative measurement with the exact command and ledger path it received. Routine work projected to cross 1,000,000 tokens blocks, while explicitly reserved deep work proceeds with a warning. | `node tools/automation-budget.mjs check|reserve|record|cancel|report --help` |
+| `automation-budget.mjs` | Maintains the append-only per-invocation automation ledger using authoritative input and output token counts. Provider-estimated cost is recorded only when the provider supplies it. A pending reservation is active and makes routine work fail closed; a terminal record without token measurements, whether explicitly completed or legacy unmarked, is completed-but-unknown, stays outside token totals, and does not block routine work. When completed-unknown records are present, a routine PROCEED or WARN emits a warning that their spend is unmeasured and the fuse cannot see it. The engine-local fuse atomically checks and appends a pending reservation under one ledger lock before worktree creation, so concurrent launchers cannot both pass the same remaining budget. Verified pre-delivery rollback appends a cancellation tombstone; a worker torn down after an accepted send is closed as completed-but-unknown; delivered work remains pending until the worker appends its provider-authoritative measurement, or its completed-but-unknown observation, with the exact command and ledger path it received. Verified-Done teardown closes any remaining reservation for its issue as completed-but-unknown. The fuse itself is scoped to the engine's whole quota pool and never to one ticket: `check` and `reserve` read the ledger without `--identity-prefix` on purpose, because the weekly account quota is shared by every ticket; `--identity-prefix` guards only a targeted repair write and a targeted report read. Routine work projected to cross 1,000,000 tokens blocks, while explicitly reserved deep work proceeds with a warning. | `node tools/automation-budget.mjs check|reserve|record|cancel|report --help` |
 | `check-dashes.mjs` | The cross-repo dash ban: em dashes banned everywhere, en dashes only in numeric ranges. Backs the Dash Ban CI job, lefthook, and the shrink-only `dash-baseline.json`. | `--files <f>...` \| `--check-baseline` \| `--write-baseline` \| `--text "<s>"` |
 | `check-copy.mjs` | The copy register: whole-file, values-only scan of locale copy for AI cliches, placeholder content, typed uppercase, and hardcoded brand colors. Backs the Copy Register CI job. | `node tools/check-copy.mjs --check` \| `--write-baseline` |
 | `check-context-budget.mjs` | Enforces the shrink-only byte budget for repo-visible always-loaded context and the structural allowlists for sibling `@` imports and unconditional rule files. Reports resolvable sibling context without enforcing it. Backs the Context Budget CI job. | `node tools/check-context-budget.mjs --check` \| `--write-baseline` \| `--json` |
@@ -50,7 +50,7 @@ Read `CONVENTIONS.md` before adding one. Use the `/make-tool` skill to scaffold
 | `wave-plan.mjs` | Builds a merge-gated wave table for a Linear project, label, all non-done team issues, or an explicit `--issues` list. Reports same-wave file collisions and unknown affected-file declarations without changing table order. Backs `/orchestrate` (which then launches workers) and `/next` (which stops at the answer). Relation reads run in a bounded pool. | `node tools/wave-plan.mjs --help` |
 | `compose-prompt.mjs` | Composes the worker prompt from a Linear issue's verbatim body plus every chronological comment, preserving comment Markdown. Write outside an Orbit repository so the prompt cannot be committed. | `node tools/compose-prompt.mjs --issue ORB-N --output <absolute path>` |
 | `launch-worker.mjs` | Launches one ticket's Orca worktree + TUI worker end to end (`/orchestrate` step 2), and is the single place the four measured launch gotchas are handled: `worktree create` needs `--name`, a fresh checkout blocks on the workspace-trust prompt, Orca's `<gituser>/<name>` branch is not the contract branch, and a multi-line prompt through `terminal send` arrives mangled. Reads the engine, model routing, repo paths and concurrency cap through `tools/lib/orchestrator-config.mjs`; before creating anything, it serialises the target repo's live Orca inventory and worktree creation, excludes main and archived worktrees, and refuses at the cap with the current count and occupying paths. It also refuses any engine that does not declare `interactive: true` (a headless worker cannot be supervised) or whose command or args carry a headless token; prints handle + worktree path + branch as JSON. Exit 0 means the worker ACCEPTED the prompt as a user turn, read back off the TUI after the send, because orca accepting a `terminal send` is not delivery: measured on ORB-88, the composer swallowed the pointer and the launch reported success on a worker sitting idle with no work. Any non-zero exit rolls the worktree and its new branches back out, so a relaunch starts clean. | `node tools/launch-worker.mjs --issue ORB-N --prompt-file <path>` (`--dry-run`, `--help`) |
-| `teardown-worktree.mjs` | Removes one completed ticket's Orca worktree, terminals, and local branch immediately after the Linear issue is verified Done. Refuses unless the worktree is clean, the forge-reported pull request merge commit is in the target branch, the local branch tip is contained in the pull request head, the live issue is Done, and no terminal is repainting. Verifies removal from the filesystem and `git worktree list`, rather than trusting Orca's removal response. | `node tools/teardown-worktree.mjs --issue ORB-N` (or a worktree selector; `--help`) |
+| `teardown-worktree.mjs` | Removes one completed ticket's Orca worktree, terminals, and local branch immediately after the Linear issue is verified Done, then closes any remaining pending reservation for that issue in the shared spend ledger as completed-but-unknown. Refuses unless the worktree is clean, the forge-reported pull request merge commit is in the target branch, the local branch tip is contained in the pull request head, the live issue is Done, and no terminal is repainting. Verifies removal from the filesystem and `git worktree list`, rather than trusting Orca's removal response. Ledger inspection and closure never stop at the first failure: every engine is inspected and every reservation is attempted, and the exit-3 message lists each failure with its own prefix-guarded `automation-budget.mjs` recovery or inspection command plus the ledger path, so a partial failure strands no reservation without a named repair. | `node tools/teardown-worktree.mjs --issue ORB-N` (or a worktree selector; `--help`) |
 | `nudge-worker.mjs` | Delivers a message to a running TUI worker only when it is tui-idle, and exits 1 sending NOTHING while it is mid-turn (a send while busy is queued and cuts the running turn short). Appends the update to the worker's prompt file from stdin and sends a one-line re-read pointer; rejects multi-line `--text`. | `node tools/nudge-worker.mjs --terminal <handle> --prompt-file <path> < update.md` (`--text`, `--help`) |
 | `worker-status.mjs` | The artifact-backed worker completion gate and one-time pre-merge verifier. Requires commits above fresh `origin/<base>`, a clean worktree, local HEAD equal to the remote PR head, an open PR with an approving review on that exact head, complete review activity inventories, zero unresolved threads, auditable acknowledgements for standalone automated activity, Linear In Review with the PR attached, and both screenshot and critique evidence for `visible-effect`. `--verify-review` also proves every resolved automated thread, including an informational one, has reconciliation evidence after its latest finding-bearing nested activity, names a later PR commit that changed the reviewed path, and rejects human threads resolved by the worker. | `node tools/worker-status.mjs --worktree <path> --issue ORB-N` (`--base`, `--verify-review`, `--json`, `--help`) |
 | `worker-watch.mjs` | The LIVENESS half of babysitting, alongside `worker-status.mjs`'s delivery verdict: for every Orca worktree in the Orbit repos, the ticket, branch, Linear state, BUSY or IDLE classified by repaint delta across two `terminal list` samples, the last meaningful output lines with TUI repaint noise stripped, and the contract verdict. Reports only; deciding what to send a stalled worker stays the orchestrator's judgement. Backs `/watch`. | `node tools/worker-watch.mjs` (`--repo`, `--lines`, `--no-contract`, `--json`, `--help`) |