Token Spend

Token spend

Usage is telemetry, not a session or issue spending limit. The pipeline records what it observes; it does not stop a session because of its spend or context size (no-session-budgets). This page is based on the source's usage serializers, tally and report, not a live provider billing measurement.

Records and locations

A finished session and job produce schema-checked JSON lines in hidden blocks of the issue's signed usage comments. A full comment rolls over to another comment; record lines are validated before serialization and may not terminate the hidden block. Public records contain numeric measurements, booleans, times and constrained identifiers, not task text, free-text replies, prompts or raw tool output. A reply is reduced to its fixed outcome/verdict name or null.

Local run evidence includes context.jsonl, jobs.jsonl, pushes.jsonl and job.json. Local logs are recovery/diagnostic records, not durable permission to mutate GitHub. Keep them private as appropriate: the public serializer's restrictions do not promise that every local log is safe to publish.

Usage logging is best effort and must not stop an issue. Serializer refusals are dropped with their reason on stderr in job.log; a failed append is retried once, then dropped.

Context log fields for tracing

Session transcripts live under sessions/<key>.jsonl; another launch using that key moves the earlier transcript aside to <key>.<stamp>.jsonl. Appended context.jsonl entries record key, job and session (the transcript basename, or null without a launch record). headSha is the code checkout's HEAD at session end; reviewedSha is the HEAD a non-writing session read, or null for a writer. Either is null when no head is readable. Without a launch record, the session is unrecorded, with numeric measures zero and firstContext null, unless job shutdown marks it killed.

Session records

A session record identifies repository, issue, job, job start, launch key, stage, state/phase, role, agent, model and attempt. It records ended as reply, error or aborted, a constrained reply name, seconds and turns.

The model identifier may have one provider prefix, such as anthropic/claude-opus-5-5. Reviewer phases distinguish hardening, integration and final security. Prompt provenance records the page name, SHA-256 of its pinned bytes and the brain checkout HEAD (null if unavailable).

Tokens include input, output, cacheRead, cacheWrite, optional cacheWrite1h and optional cost in US dollars. Missing cost is not zero provider spend. The tally reads usage from assistant records; absent usage is not an independently measured provider bill.

cacheWrite1h is the subset of cacheWrite written at the one-hour rate; five-minute writes are cacheWrite - cacheWrite1h. Cost sums pi's reported per-message cost.total in US dollars, not provider credits.

context.first, peak and atFinish are the first, largest and final observed per-turn context. Context counts input plus cache-read plus cache-write tokens; it is not cumulative session spend. Output contributes to total tokens, not that context measure. The current writer records window: null; there is no claimed model window or budget threshold. The record also holds task character count, a task file map, per-tool call/output-character totals and the largest tool output's tool and size. The current writer emits an empty task file map. Unrecognized tool names are grouped as other.

Job records

A job record identifies repository, issue, job, job start and role, and holds the stages visited, outcome, duration and aggregate session tokens. Its totals summarize its sessions: adding job totals to the same session totals double-counts. A job end is not proof that its code or wiki was published.

Commit and push attribution

A scoped commit carries Pipeline-Session: <launch key>@<job start>. Match the launch key and job start to the session usage record; match the launch key and job to push records. The job records each successful push in job.json under its launch and as {key, job, repo, sha, at} in pushes.jsonl. repo is code or wiki; sha is the pushed head, which may include several commits. Push records outlive the job status file.

The trailer attributes a commit to a session, not an exact share of that session's cost. A session can create several commits or no commit, and its unsuccessful work still consumes usage. Refused commits remain local; a trailer or local commit is not proof of a push, security clearance or publication. If a trailer or record is missing, exact attribution is unavailable: inspect retained local evidence without inventing a match.

Reports

Run the installed report program against the configured target:

node "$ISSUE_PIPELINE_ROOT/report.mjs" usage --config /path/to/repo.json   --since 2026-01-01 --role reviewer --issue 123

--since, --role and --issue are optional filters. The report reads account-authored issue usage records and groups sessions by role, state and model. It reports median/p90/max context and token measurements, flagged sessions and each role's tools with the most output. Flags annotate the report; nothing acts on them. Job records are not included in those session groups. These are observed records, not budget enforcement or a claim about complete provider billing.

usageFlags in repository configuration sets firstContext (a positive integer, default 40000) and toolOutputShare (default 0.25, greater than 0 and at most 1):

• first-context flags first-turn context above firstContext.
• tool-output flags the largest tool output's character count above toolOutputShare of peak context.
• first-grew flags a higher-numbered attempt whose first-turn context exceeds the latest earlier session's at the same issue and state.

Sources

• usage-log.ts: public record schemas and serialization.
• usage-comment.ts: hidden blocks and rollover.
• run-usage.ts, usage-tally.ts and token-usage.ts: emitted fields and measurement.
• report.ts and report/: reporting.
• commit-push.ts: push attribution and authority checks.