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}

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

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):

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).

Tests: test/repo-wallet.test.ts, test/repo-wallet-routes.test.ts.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs