Spend ledger

Time keeps a record of what it spends on models. This folder holds it.

One file per month: time/ledger/<YYYY-MM>.jsonl, for example 2026-10.jsonl.
One JSON line per model call. Fields:
- at: when the call was made, ISO 8601 in UTC (2026-10-14T09:30:00Z).
- model: the model that was called.
- in: input (prompt) tokens.
- out: output (completion) tokens.
- pool: the provider the call booked to (anthropic, venice); time/pools.json maps it to a capacity pool.
- usd: the cost in US dollars, or null if the seat has no price (unpriced seats).

Example line:

{"at":"2026-10-14T09:30:00Z","model":"some-model","in":1200,"out":350,"usd":0.0123}

Who writes and reads it

Written by Time itself. At the end of each run, Time appends that run's calls to the current month's file in one ledger: commit.
Read before every model call. Whichever workflow is about to call a model (heartbeat, mentions, venture loop, Astra) adds up usd for today and for the month and refuses the call if either total has reached its cap (TIME_DAILY_USD, TIME_MONTHLY_USD). A null counts as zero.

When a cap trips

Time stops calling models. The next time the heartbeat has a card to run, it opens one issue labelled andon (never a second while that one is open). A monthly cap also switches TIME_MODE to dry-run, or says in the issue that it couldn't, until a human raises the cap. A daily cap clears itself at midnight UTC. Close the issue once it is handled.

Don't edit it by hand

Humans should never edit these files. The caps rely on them being exact, and Time only ever appends. A hand edit can hide spend or break the next append.

The router's outcomes (`router-outcomes.jsonl`)

Not spend, but it lives here for the same reason: Time appends to it daily and CI ignores this folder. One JSON line per router pick that has settled, written by housekeeping (.github/time/housekeeping.py, step 4), so a learning policy has rewards to read. Fields:

n, kind: the card and the kind it was picked as.
picked, settled: the day Astra picked it, and the day the card closed.
merged, pr: whether its PR landed, and which PR.
days: whole days from picked to settled.
usd: the dollars this ledger booked while the card's worker ran (each dispatched beat until the next beat on the card). The ledger has no card field, so this is a proxy: review and planning calls on the card are not in it, and two cards whose runs overlap are each charged what was booked in their own window.
signups: for a venture pick, the venture's signups at day 7 (TIME_VENTURE_MEASURE_DAYS); null for any other kind.

{"n":168,"kind":"feature","picked":"2026-10-17","settled":"2026-10-19","merged":true,"pr":190,"days":2,"usd":1.25,"signups":null}

A pick is written once, when its card closes, and never rewritten. Astra's daily log shows one summary line per kind over the ranked table (picks, merged share, median days, median $). No pick reads the file yet: router.score is still the whole policy.

Pools (`time/pools.json`)

The operator keeps one entry per capacity pool; a route with no entry is paced by TIME_DAILY_USD. Time reads the file through the API once per run. Fields: name, kind, routes, and by kind:

expiring: balance_usd (as of as_of, a date), resets_at (the date the credit lapses). Allows (balance - spent since as_of) / days to resets_at x TIME_PACE a day.
window: window_usd, resets_at as weekly:mon or hours:5. Allows window_usd per window.
balance: balance_usd. Allows TIME_DAILY_USD a day.

[{"name": "anthropic-credits", "kind": "expiring", "balance_usd": 30, "as_of": "2026-10-19", "resets_at": "2026-10-29", "routes": ["anthropic"]}]

README.md