[ZacxDev]

What

Per-officer-instance Claude usage, measured from each instance's own Claude Code transcripts and pushed to the officer's HQ, per session and UTC hour: API calls, the four token fields, and turns.

Two halves:

1. ccd: GET /v1/usage?since=<unix seconds> (cmd/ccd/usage_route.go). Bearer-authenticated like /v1/transcript. Reads every *.jsonl under <CLAUDE_CONFIG_DIR>/projects/ (any depth, mtime >= since). A subagent's nested transcript counts on its parent session. Complete lines only, decoded with a lean struct that never decodes content. No transcript text appears in the answer or in logs.
2. muster: the officer usage collector (internal/officers/usage, wired in internal/api/officer_usage.go). It runs for every declared officer with no new configuration. Every 10 minutes it reads each up instance's ccd through the agent gateway (Gateway.Usage) with since = now - 25h and PUTs the result to HQ with the officer's own token. officerFleet.Stop pushes once more just before scaling an instance to zero.

Counting rules (ccd)

• since is truncated DOWN to the UTC hour and clamped to at most 48 h before now, on an hour boundary. The oldest bucket is therefore always a whole hour. This matters because HQ replaces a bucket on every push.
• api_calls / tokens come from assistant records, subagent (sidechain) records included. Each API call is counted once with the existing per-call rule: key = message.id + input + cache_read + cache_creation, each field takes its max, and isApiErrorMessage and <synthetic> records are skipped. The call is bucketed at the hour of its first record. The rule moved out of turnResult.addUsage into callLedger (cmd/ccd/callusage.go), which the turn usage and the hourly count both use.
• turns are distinct non-empty promptIds of non-sidechain user records, bucketed at the hour first seen.
• The answer is sorted by hour, then session. A bucket with zero calls and zero turns is omitted, and buckets is [], never null.

ccd answer:

{"since":"2000-01-03T10:00:00Z","buckets":[{"session":"sess-a","hour":"2000-01-03T10:00:00Z","turns":1,"api_calls":1,"input_tokens":11,"output_tokens":29,"cache_read_tokens":1301,"cache_creation_tokens":701}]}

The HQ contract (implemented exactly as specified)

PUT {hq_url}/officers/{officer_id}/usage (the path is built like every other officer route, url.PathEscaped), Authorization: Bearer <officer token>:

{"instance":"<agent name>","pool":"routine|judgement|","account":"<cc account now, or \"\">","generated_at":"<RFC3339 UTC>",
 "buckets":[{"session":"..","hour":"<on the hour>","turns":0,"api_calls":0,"input_tokens":0,"output_tokens":0,"cache_read_tokens":0,"cache_creation_tokens":0}]}

• account is the instance row's cc_account at push time, or "" for a pool on the LLM proxy (officers.ProxyAgent).
• If there are more than 1000 buckets, only the newest 1000 are sent, and the cut is logged.
• The fake HQ (hqtest) implements the route with a strict decoder: pool values, hours on the hour, 413 past 256 KiB or 1000 buckets, and the upsert. UsageAbsent makes it play an HQ without the route.

Failure handling

• Nothing is retried within a tick; the next tick's push covers it.
• A ccd without the route (404/405, which maps to ErrUsageUnsupported) is skipped and logged once per instance.
• HQ 404 is logged once per officer, and pushes continue.
• Every attempt is counted on muster_officer_usage_push_total{result}, with results pushed, ccd_unsupported, ccd_failed, hq_not_found, hq_refused, hq_unavailable and skipped. The metric is added to the metrics ledger. HQ refusals are logged by status, never by body.
• One collect runs at a time, so a tick's push and a pre-stop push can never reach HQ out of order.
• The pre-stop push is bounded at 10 s and never fails the stop.

Tests

Change-scoped runs only, done locally; CI runs the full suite.

• cmd/ccd/usage_route_test.go pins the whole answer as literal JSON over a synthetic fixture whose token values are pairwise distinct within each bucket. It covers:
  • a multi-block call counted once, at its max output;
  • the same id with a different input side counted as two calls;
  • api-error and <synthetic> records skipped;
  • sidechain calls counted, and sidechain prompts not counted as turns;
  • a nested subagent file attributed to its parent session;
  • records before since excluded;
  • since 10:30 still counting a 10:05 record;
  • a partial trailing line and an undecodable line skipped;
  • an old-mtime file not read;
  • 401 without a bearer, and 400 on a missing or bad since;
  • the 48 h clamp, measured with the clock off the hour and on it.
• internal/officers/usage/collect_test.go runs against the fake HQ through the real client and covers:
  • exact PUT bytes for a tiered officer's judgement and routine instances and for an untiered officer;
  • down and absent instances never read;
  • unsupported ccd skipped and logged once;
  • HQ 404 tolerated, logged once per officer, and recovered once the route appears;
  • the cap keeping the newest buckets;
  • a failing flush pushing nothing.
• internal/api/officer_usage_test.go covers the server wiring:
  • the instance is read by its own row, and the row's account is in the exact body;
  • Stop reads the instance while it is still running, then stops it;
  • a failing read or a down HQ does not fail Stop;
  • the gateway sentinel maps to the quiet skip;
  • a proxy pool reports no account.
• internal/agentgateway/usage_test.go covers the turn bearer, the since query and 404/405 → unsupported.

Mutation results

Each mutant was run with -count=1, restored by copy, and its checksum re-verified:

mutant	result
since hour-truncation removed	red: both ccd answer tests (since 10:30, the 10:00 bucket gone)
dedup key = message id only	red: both ccd answer tests and the existing TestExtractTurnSumsTheTurnsUsageOncePerAPICall (the shared helper)
output added to the dedup key	red: both ccd answer tests (api_calls 3)
sidechain check dropped from turns	red: TestUsageRouteCountsOnlyTheWindowsHours (turns 2)
pre-Stop flush removed	red: TestStopPushesTheInstancesUsageBeforeScalingItToZero (no read)
flush moved after the scale-down	red: same test (read @stopped)
collector's Up check dropped	red: TestATickPushesEachUpInstanceExactlyTheContractBody (the down instance was read)
bucket cap keeps the oldest	red: TestOverTheBucketCapTheNewestAreSent

Verifying HQ's numbers

docs/officers.md ("Claude usage to HQ") includes a jq recipe that recomputes one session-hour from the transcripts by the same rules. I checked it against ccd's answers on both test fixtures, and every bucket matches.

Audit round 1 (93aeda7)

• Yellow, fixed: the call ledger was per file. A call copied into several transcripts (a forked subagent, a branched or resumed session) was counted once per file, and a prompt copied into another session's file was counted again there.
  • ccd now keeps ONE ledger and one prompt set for the whole scan.
  • Each call and prompt is owned (session and hour) by its first record in sorted relative-path order, so the owner is stable between pushes.
  • New test TestUsageRouteCountsACallInSeveralFilesOnce: red at 7669838, green now.
  • Mutants all red on that test: per-file ledger restored; reverse file order; no sort (the walk's order); prompt set keyed per session; meta and compaction-summary records counted as turns. The no-sort mutant survived until a cross-project case was added.
• Green, done: isMeta and isCompactSummary user records are no longer turns.
• Docs: the jq recipe now reads every transcript in sorted order and dedups across all of them.
  • It reproduces every bucket of ccd's answers on both test fixtures.
  • An hour ccd omits reads as all zeros.
  • The old per-session input reports a DIFF.
  • The earlier "message ids are unique, so the two agree" was false and has been removed.

Deploy notes

• Officer instance pods need the new claude-code-agent image, i.e. a restart onto it, before /v1/usage answers. Until then each instance is skipped with one log line.
• HQ's route can land before or after this change. Until it does, HQ answers 404 and pushes are dropped, with one log line per officer.
• No new environment variable and no schema change.
• Caveat: account is the account at push time, so hours from before a failover inside the 25 h window are reported on the new account.
• Caveat: hours older than 25 h when an instance comes back up are never backfilled.

Not run locally

The DB-backed and whole-suite tests were not run here, by policy; CI runs them.

🤖 Generated with Claude Code