Cost ledger
Every run that ends (finishRun, and cancelRun: agent, check, deploy) appends one line to $FORGE_DATA/ledger/<yyyy-mm>.jsonl (by the month it ended). Nothing is written on a day with no runs. A snapshot has no run row, so the snapshot service appends its own entry when one ends, taken or failed: kind: "snapshot", run: "snapshot:<startedAt>", startedAt, endedAt, wall_s, and failed: true only when it failed. It has no repo: a snapshot is the whole forge's, so repo is optional and absent, never a made-up id. A forge with nowhere to put a snapshot writes nothing.
An entry
{run, kind, repo, issue, pull, startedAt, endedAt, wall_s, tokens_in, tokens_out, usd_tokens, prev, hash}
issue,pull,startedAt,wall_s,tokens_in,tokens_out,usd_tokensappear only when the run knows them: absent, never zero. Todaytokens_*are always absent (runs record dollars, not tokens);usd_tokensis the run'scostUsdwhen above zero.hashis sha256 (hex) of the entry's canonical JSON (keys sorted) withouthash.previs the previous entry's hash, across months; the first entry's is 64 zeros.
Appends are synchronous and read the tip from the end of the files on every append, so two runs ending together never share a prev, in this process or another on the same directory (an interleaving of two processes is still two writes, not one lock: run one forge per directory). A corrupt or torn last line is skipped with one logged error and the ledger chains from the last readable entry; ledger-verify still names the corrupt line. A failed append is logged and never reaches the finish path. The ledger is off until boot sets its directory (setLedgerDir in src/main.ts; not in read-only mode).
Verify
bun scripts/ledger-verify.ts [dir] # default $FORGE_DATA/ledger
Prints ok N entries, or broken at <file>:<line>: <why> and exits 1.
The tests are test/cost-ledger.test.ts, not test/ledger.test.ts: that name is the decision ledger's.
Reading it on a pull and an issue (#12114)
A pull's header, and an issue's, carry one line for people who may see owner facts (writers; nobody else sees it, on the page or in the terminal):
cost: $0.42 tokens · 30 lane-min · 3.0 h waiting · ask→live 5.3 h
- tokens: dollars the finished runs recorded. lane-min: minutes the runs held a lane, start to finish. waiting: hours the runs sat queued before starting. ask→live: hours from the ask (the issue the pull closes; for an issue, its own creation) to its change being live in production.
- A pull's line sums its own finished runs; an issue's sums its own and those of every pull that closes it. A part no run knows is left out, never shown as zero; with nothing to say there is no line.
- It is read from the finished
runrows with indexed queries (src/core/ledger_rollup.ts), never from the ledger's files, and only when the thing has agent runs, so a page with none pays no extra read. - The terminal's pull screen puts it in the head's second row; the issue screen puts it on the cost row. Both call
costLineFor, the same gate as the page.
Tests: test/ledger-rollup.test.ts, test/tui-issue-cost.test.ts, test/tui-pull-cost.test.ts.
Health: a broken chain is a need
The chain is walked once at boot and then once a day, on the serving thread (checkLedger in src/core/ledger.ts, run under during("ledger", …) from src/main.ts; not in read-only mode). The walk logs ledger: verified in N ms: ok, N entries or broken at <file>:<line>: <why>, and keeps the verdict in memory.
When the verdict is broken, a site admin (and no one else) reads one more line in needs of GET /api/v1/health (and the MCP health tool), with ok: false, and on the terminal's and the board's forge strip:
The cost ledger's chain is broken at <file>:<line>: <why>. Run bun scripts/ledger-verify.ts to see it; the ledger's records after that line cannot be trusted.
Health only reads the kept verdict; it never touches the files, so a request stays fast however big the ledger is.
Clearing it. Run bun scripts/ledger-verify.ts (see Verify) to see the line, then repair or move aside the damaged file (keep a copy: the chain is evidence). The need clears at the next walk: restart the forge, or wait for the daily one. Nothing clears it sooner, so a repaired ledger reads broken until then.
Cost. The walk is synchronous: a big ledger holds the event loop for the length of the walk, once at boot and once a day. The boot log line says how long it took; if that grows to something a person would feel, the walk should yield between month files.
Where the chain lives: git
The jsonl is the spool; git is truth. src/core/ledger_git.ts commits the chain to the ledger branch of a repository the forge owns: FORGE_LEDGER_REPO (owner/name), else FORGE_REPO; with neither, nothing is committed. A timer (ledger-git) fires hourly and, only when a month file has lines the branch lacks, appends them (one file per month, <yyyy-mm>.jsonl at the branch root) in one commit, signed with the forge's SSH host key (<data>/ssh/host_ed25519, an SSHSIG in the commit's gpgsig header, namespace git). No new lines, no commit. If the branch holds lines the spool does not, nothing is committed over it and the failure is logged. Entry text reaches git only as blob content, never as an argument.
Clone and verify (another forge, no database)
git clone <forge>/<owner>/<repo> ledger-clone bun scripts/ledger-verify.ts --git ledger-clone --key "ssh-ed25519 AAAA…"
Walks the ledger branch, checks every commit's signature and the whole hash chain, and prints ok N entries, M signed commits, key …, or broken at <file>:<line>: <why> / broken at <commit>: bad signature … and exits 1. --key pins the signer (the forge's host_ed25519.pub); without it the commits must agree on one key, which is printed — compare it yourself. --branch names another branch.
A client's bill
The person who claimed a hosted forge (the first person admin in its own database, matched to a signed-in account here by email address) downloads one month of what it cost as one signed file. The link is on their settings page (/settings, any account, admin or not), on the forge's row in /forges for an admin who claimed it, and in the terminal under "Your forges' bills", which shows the month's totals. The API is GET /api/v1/forges/:name/bill?month=YYYY-MM, and /forges/:name/bill serves the same file; the month defaults to this one. Anyone else, signed in or not, gets 404, including the person who made the forge if they did not claim it. A month over 4 MiB of entries gets 413 and is never cut.
The file (src/core/ledger_bill.ts, access in src/actions/forge_bill.ts):
- Line 1 is a JSON header
{bill, forge, month, own, key, signature}. - The next
ownlines are the entries of the forge's own ledger directory, a hash chain. - The lines after them are the entries in this forge's spool whose
repois one of the apps the forge follows. They come out of a chain shared with other forges, so each is checked on its own. - This forge signs the forge name, the month,
ownand all entry lines with its SSH host key (namespaceforge-bill).
To check a bill:
bun scripts/ledger-verify.ts --key "ssh-ed25519 AAAA…" <bill>
It prints ok N entries $X (the sum of usd_tokens), or broken at line N: <why> and exits 1 when an entry changed, the own chain is cut, or the signature is not by that key. The first own entry's prev is not checked, because the bill holds one month. The address match trusts the email on both accounts.
A repository's monthly cap (#13309)
An admin of a repository can hold a cap on what its crew spends in a month. Spend is this ledger's list-price dollars for the repository's runs since 00:00 UTC on the 1st (read from the usage table, monthSpent in src/core/wallet.ts).
- Set it, on the page.
/<owner>/<name>/wallet(admins only). Whole US dollars, 1 to 100000; empty removes the cap. - Set it, in the terminal. With the repository open, the palette's "Wallet" shows the month's spend and the cap;
csets it, empty removes it. Same gate (saveCap,src/actions/wallet.ts), samewallet.capevent. - At the cap. New runs are refused with one sentence: "This repository's monthly cap of $N is reached; its crew starts no new runs until YYYY-MM-01 (UTC) or the cap is raised." A run already under way is not cut off. The repository page shows the same sentence as one plain line (admins only), linking the wallet.
- Resume. Raise or remove the cap, or wait for the new month. The check is in
executeAgentRun(src/crew/runner.ts).
Tests: test/repo-wallet.test.ts, test/repo-wallet-routes.test.ts.