The Usage page lists 16 agents named after their own UUID, and cannot say what one instance cost — the DO's storage meter writes an instance id into ai_usage.agent_id

[serge-ivo]

The question that cannot be answered

"What did Chess coder 2 cost me this week?" The owner runs seven Repo Coder instances against seven different repositories. The Usage page cannot tell him about any one of them, and its by-agent breakdown lists sixteen rows labelled with a raw UUID.

Measured

usage_summary(range: "7d"), 2026-08-12. byAgent contains two different kinds of key:

agent_coder_repo                        1330 calls   label "Repo Coder"       ← agents.id
agent_coder_lead                         310 calls   label "Coder Lead"       ← agents.id
2dff5c62-59f0-4d2d-b0a6-b1db5c879c46     160 calls   label "tmux Operator"    ← agents.id (a UUID agent)
5fab318d-2850-45a4-982c-958765c7261e     155 calls   label "5fab318d-…"       ← agent_instances.id  (Coder Lead)
bd43f4de-ef35-4051-bdec-43f8571414a1      84 calls   label "bd43f4de-…"       ← agent_instances.id  (Chess coder 2)
cda75e28-cace-4958-ac3e-6a7528e6b719      60 calls   label "cda75e28-…"       ← agent_instances.id  (Heartfull (tmux))
…13 more instance-id rows, every one labelled with its own key…

Sixteen rows are keyed by an instance id and carry no name. Every one of them corresponds to an instance in my_instances. So the same agent appears twice — once as its template with a proper label, once (or several times, one per instance) as an unlabelled UUID.

Mechanism — fully traced

Why the label is the UUID. workers/api/src/routes/usage.ts:41-49 resolves the agent per row:

SELECT COALESCE(u.agent_id, i.agent_id) AS agent_id, … a.name AS agent_name
FROM ai_usage u
LEFT JOIN agent_instances i ON i.id = u.instance_id
LEFT JOIN agents a ON a.id = COALESCE(u.agent_id, i.agent_id)

and lib/usage.ts:511 falls back to the key when the join found no name:

byAgent: sortByCost(maps.agent).map((b) => ({ ...b, label: b.key === "unassigned" ? "Unassigned" : opts.agentNames?.[b.key] || b.key })),

The COALESCE handles the case it was written for — a row with only instance_id. It cannot help a row where agent_id is set to something that is not an agent.

Who writes an instance id into agent_id. The Durable Object's storage meter:

• routes/instances.ts:213-215 initialises an instance's DO with agentId: instanceId — correct, that is the DO's own identity.
• agent-do.ts:153-166 builds the meter from it: const meter = platformAi && userId ? { db: this.env.DB, userId, agentId } : null; — where agentId is state.agentId, i.e. the instance UUID for an instance DO.
• EngineMeter (agent-storage/base.ts:16-21) declares both agentId and instanceId. The only construction site above sets agentId only; instanceId is never populated.
• agent-storage/vectors.ts:315 and agent-storage/summaries.ts:143 then record:

  { userId: this.meter.userId, agentId: this.meter.agentId, instanceId: this.meter.instanceId, model: …, kind: "embedding" | "summary" }

  → ai_usage.agent_id = <instance uuid>, ai_usage.instance_id = NULL.

With instance_id null the agent_instances join has nothing to join on, and with agent_id set the COALESCE prefers it. Both joins miss. The row is orphaned by construction.

Why chat rows are fine, and why that hid this. agent-think.ts:783 records { kind: "chat", instanceId: state.agentId } — the same value, passed in the right field. Those rows have agent_id NULL, the COALESCE resolves them through agent_instances, and they land on the properly-labelled template row. Same for the Pilot (coding-session.ts → decideCodingAction(…, { kind: "coding", instanceId })). So the big-ticket spend attributes correctly and only the platform-paid embedding/summary crumbs are orphaned — which is why this reads as cosmetic until you try to answer a question with the page.

byKind for the same window: embedding 393 calls, summary 73 — consistent with the 16 orphaned rows' call counts.

The second half: there is no per-instance figure at all

Fixing the labels makes the page tidy. It still cannot answer the owner's question, because byAgent groups by template: agent_coder_repo's 1,330 calls are seven instances working on seven repositories, summed. The ledger has the data — ai_usage.instance_id is populated on every chat and coding row — and nothing surfaces it.

What to do, cheapest first

1. Populate instanceId on the meter. agent-do.ts:160-161 → { db: this.env.DB, userId, agentId, instanceId: agentId } for an instance DO (the DO knows which it is; the same state.agentId is the instance id). Every future embedding/summary row then resolves through the existing COALESCE, with no query change. One line.
2. Backfill or tolerate. Existing rows keep an instance id in agent_id forever. Either a migration (UPDATE ai_usage SET instance_id = agent_id, agent_id = NULL WHERE agent_id IN (SELECT id FROM agent_instances)) or a second LEFT JOIN agent_instances i2 ON i2.id = u.agent_id in the route, resolving through it when the agents join misses. I would do the query fix, not the migration: it is reversible, it fixes the history the owner is looking at right now, and ai_usage is observability rather than a ledger of record.
3. Add byInstance. aggregateUsage already builds five maps by the same into() helper (lib/usage.ts:470-482); a sixth on r.instance_id, labelled from agent_instances.config.name, is a few lines and is the thing that actually answers "what did Chess coder 2 cost?". The MCP usage_summary tool passes the payload straight through, so it arrives there for free.
4. Make it hard to regress. A row whose agent_id matches no agents.id is a bug, not a display state. Assert it in usage.test.ts against a fixture containing an instance id in agent_id, and — better — narrow the type so a call site cannot pass an instance id as agentId by accident. The EngineMeter interface having both fields, with only one ever set, is what made this invisible.

Alternatives rejected

• Just improve the label fallback (show "unknown agent" instead of the UUID). Hides the defect and loses the attribution — the row belongs to a named instance and the platform knows which.
• Drop agent_id from ai_usage and always resolve through instance_id. Not every row has an instance (kind:"run" records agentId: agent.id from routes/run.ts:82, a creator-side call against a template). The column is load-bearing; the bug is one writer using it for the wrong id.

Regression risk

The route's COALESCE currently prefers u.agent_id. Adding a second resolution path must keep template-scoped rows (creator run/chat against an agent, no instance) attributing to the template — a naive "if it looks like a UUID, treat it as an instance" would break 2dff5c62-…, which is a genuine UUID agent id and today labels correctly as "tmux Operator". Resolve by lookup, never by shape. usage.test.ts should carry one row of each: agent-id-that-is-a-UUID, instance-id-in-agent_id, instance-id-in-instance_id.

Reported as observed via MCP usage_summary; the mechanism above is read from the code, not instrumented at runtime.

[serge-ivo]

Blast radius measured, and one cheaper path to step 3 you may not know exists

Re-measured on production 2026-08-13 via MCP usage_summary, all three ranges. The mechanism in the body reproduces exactly; here is the size of it, and one correction to the priority.

1. The mislabelled rows are 0.0007% of the value — but they are not the reason the question is unanswerable

range: "all" (the whole ledger sits inside 30 days, so 30d and all are byte-identical):

bucket	calls	value
22 rows keyed by a raw UUID with the UUID as its own label	645	$71,545 = $0.07
agent_coder_repo (label "Repo Coder")	1,760	$9,566.69
total	5,721	$9,621.22

So the orphaned rows are 11.3% of the calls and 0.0007% of the value — consistent with the body's read that they are the platform-paid embedding/summary crumbs (byKind: embedding 659 calls / $0.002, summary 134 calls / $0.03).

Instance-keyed rows in byAgent, all-time, all self-labelled: 12ebf1f0 (133 calls), 5fab318d (185), f8ddc272 (68), bd43f4de (88), 5219a03a (80), cda75e28 (60), 933ebec5 (36), 26f71cd8 (18), e4d2d031 (15), a1d3522f (20), 267286d5 (6), 964594b6 (10), 1a8486b5 (9), 880ce9d4 (3), 6d3b28f1 (6), 6d2d9401 (6), dfc1cf92 (4), feba6e06 (2), plus five 1–2 call rows. Every one matches an instance in my_instances. 22 rows, not 16 — the count grows with the window.

The priority correction: fixing the labels makes the page tidy and moves seven cents. The body already says this ("which is why this reads as cosmetic"), and the measurement confirms it hard. Step 3 — a per-instance figure — is the whole ticket. Steps 1 and 2 are hygiene that should not gate it.

2. Step 3 is smaller than the body thinks, because the per-instance query already exists — twice

The body proposes a sixth map in aggregateUsage. That is right and cheap. But note the platform already computes exactly this number in two places, so there is a prior art to match rather than invent:

• lib/stats-sources.ts:310-337 — usageTokens and usageValue, both WHERE instance_id = ?1 AND user_id = ?2 AND created_at >= ?3 AND created_at < ?4, exposed as the stat-card sources usage.tokens ("AI tokens") and usage.cost ("AI value (list price)"), declared at lib/stats-schema.ts:144-162.
• routes/admin-instance-detail.ts:113-121 — the same rollup, admin-only, and it already returns both figures (value_micros and charged_micros via CHARGED_SQL).

The per-instance capability is therefore built, tested and shipped — and inert. Measured on production, GET /v1/instances/:id/stats/schema for three instances (Chess coder 2 bd43f4de…, Coder Home 12ebf1f0…, Coder Lead 5fab318d…):

{"cards":[],"templateDefault":[],"override":{"cards":[],"hidden":[]},"historyStart":null}

and GET /v1/instances/bd43f4de…/stats?window=7d → {"window":7,"historyStart":null,"throughDay":"2026-08-11","cards":[]}.

No agent template declares a default stats card, so no instance has one. "What did Chess coder 2 cost?" is answerable today by adding one card — and nobody would ever discover that.

That gives a step 0 that is a data change, not code: seed usage.cost + usage.tokens into the coding agents' config.stats template default (the same shape migration 0057 uses for pipelines). It ships the answer immediately and does not compete with byInstance — byInstance is still the right thing for the cross-agent view, which is the one that ranks seven Repo Coders against each other.

3. Two things byInstance must carry, or it will answer the wrong question

• A charged figure per bucket, not just notional. Filed as The Usage page prints $9,566.69 next to "Repo Coder" and $36.35 as "Est. billed" — every breakdown carries only the notional figure, so no agent has a charged cost #543: UsageBucket has no chargedCostMicros, so byInstance built on today's bump() would print $9,566.69-style notional dollars per instance. For this account that number is 99.7% engine spend at payer: unknown — real consumption, not money. byInstance without the charged column reproduces the exact confusion at finer granularity.
• Engine rows already carry instance_id. All four recordEngineUsage sites pass instanceId and none passes agentId (routes/coding.ts:237,714; workflows/coding-session.ts:402,724), so the row is agent_id NULL, instance_id set and resolves through the existing COALESCE. The expensive rows are already correctly keyed — byInstance will attribute the $9,541 of engine spend per instance on day one, with no writer change. That is worth saying explicitly, because it means step 3 does not depend on steps 1 or 2 landing first.

4. Confirmed unchanged

agent-do.ts:160-161 still constructs the meter without instanceId, and EngineMeter (agent-storage/base.ts) still declares both fields with only one ever set. The one-line fix in step 1 is still correct as written.

Verified: the measurements above (MCP usage_summary, GET …/stats, GET …/stats/schema, production, 2026-08-13) and the code paths cited. Not verified: whether a stats card seeded on a template retro-applies to already-subscribed instances — readInstanceStats resolves creator default < subscriber override, so it should, but I have not exercised it.

[serge-ivo]

Correction to my figures above: I mis-tallied the self-labelled rows. Recounted line by line from the same range:"all" payload, it is 26 rows, 759 calls, 35,073 micros = $0.035 — not 22 / 645 / $0.07. That is 13.3% of calls and 0.00036% of value, which strengthens rather than changes the point: the labels are cosmetic, the per-instance figure is the ticket.

Full list, calls · micros: 12ebf1f0 133·9916 · 5fab318d 185·6236 · f8ddc272 68·4136 · bd43f4de 88·3761 · 5219a03a 80·3419 · cda75e28 60·2896 · 933ebec5 36·1256 · 26f71cd8 18·997 · e4d2d031 15·846 · a1d3522f 20·475 · 267286d5 6·297 · 964594b6 10·247 · 1a8486b5 9·189 · 880ce9d4 3·185 · 6d3b28f1 6·119 · 6d2d9401 6·51 · dfc1cf92 4·13 · feba6e06 2·7 · a9ee6079 1·5 · 59cc5144 1·4 · 8d21ea1a 1·4 · da39100b 1·4 · 4d4a455c 2·4 · bfc76603 2·3 · 5d14a2e1 1·2 · e26f69d0 1·1.

One substantive thing that recount surfaced. The body says "Every one of them corresponds to an instance in my_instances." Over the all-time window that is almost true: 25 of the 26 match a live instance, but 26f71cd8-a376-4600-8522-ababd77d2b1f (18 calls) does not — it is absent from GET /v1/instances/my/instances, so it is an unsubscribed or deleted instance.

That matters for step 2 of the fix. A second LEFT JOIN agent_instances i2 ON i2.id = u.agent_id resolves 25 of 26 and leaves this one still labelled with its own UUID, because the instance row is gone while the ledger row survives — which is deliberate (routes/analytics.ts:51: "ai_usage rows survive, because they are the spend record"). So the label fallback has to handle "an id that resolves to nothing" as a permanent state, not a transient one. "Deleted agent" beats a raw UUID and beats "Unassigned", which already means something else (agent_id IS NULL).

[serge-ivo]

Shipped in 7be9dfc and verified against production, which turned out to be the interesting part.

The answer to the question you asked: per-instance grouping on the Usage page

You asked whether the answer was the stats cards, a byInstance grouping, or both. It is the grouping, and the stats cards are the wrong shape for this question — details at the bottom.

GET /v1/usage?range=30d, live, a few minutes ago. The one row your comment named:

	value	charged	calls
byAgent "Repo Coder"	$9,569.14	$18.57	2,103

is now 30 byInstance rows, top six:

instance	value	charged	calls
Chess coder 2	$2,495.30	$7.27	525
PAS Coder	$1,884.38	$1.52	199
FWS platform	$1,794.10	$0.66	526
Heartfull	$1,663.16	$6.46	507
FGS platform	$1,587.33	$0.63	104
FAS platform	$142.67	$0.28	105

"What did Chess coder 2 cost me?" is now a row. Note that it carries both figures — $2,495.30 of value against $7.27 of money. Your comment's point 3 was the load-bearing one: a per-instance card printing only the notional figure would have rebuilt the exact misreading #543 fixed, one level finer. Every bucket goes through the same bump(), so the charged column came along for free.

The console renders it as a full-width "By agent instance" card directly under "Who pays", above "By agent", with a line at the point of comparison saying which axis is which. It is hidden for an account with fewer than two instances, where it would repeat "By agent" verbatim.

The labels: zero raw UUIDs left, and a case neither of us predicted

Live, both axes:

byAgent     rows=16  raw-UUID labels=0
byInstance  rows=30  raw-UUID labels=0

Two of the live instance labels are Chess coder · 26f71cd8 and Chess coder · bfc76603 — you have two instances you named the same thing. Splitting by instance and then labelling every split "Chess coder" would have reproduced the collapse with the rows merely separated, so a label that would appear more than once carries a short id and one that is already unique does not. That case showed up on its own in production; it was not hypothetical.

Also worth recording: 26f71cd8-… is not deleted. Your second comment had it as the one id matching no live instance, inferred from its absence in my_instances. It resolves fine — it is a live instance called "Chess coder". my_instances filters by status; the Usage name lookup does not. So the Deleted · <id> fallback exists and is unit-tested, but it did not fire on this account and has no live evidence behind it. Flagging that rather than claiming the whole label surface is proven.

Resolution is by lookup, and it fixed a mirror bug you hadn't found

Both id columns are written with the wrong kind of id by a live path, in opposite directions:

• agent-do.ts builds the storage meter from state.agentId, which for an instance DO IS the instance id → an instance id in agent_id (your finding).
• agent-think.ts:783 passes instanceId: state.agentId, which is the AGENT id when a creator chats with their own template → an agent id in instance_id. Those rows were falling into "Unassigned". Same defect class, unreported, fixed by the same query.

Resolution is a LEFT JOIN against each candidate table, never the shape of the string — your regression note was right that 2dff5c62-… is a genuine UUID agent id and a shape rule would break it. It still labels as "tmux Operator". The instance joins are scoped to the row's own user, so a misattributed id can never surface another tenant's name.

The SQL lives in workers/api/src/lib/usage-ids.ts as an exported string rather than inline in the route, so usage-resolution.test.ts can execute it against real SQLite with one row of each shape you listed. Two of its nine cases were confirmed red against the previous query before the fix landed.

What I did NOT do, and why step 1 as written would have made things worse

The writers still put the id in the wrong column. I did not apply your step 1, because { db, userId, agentId, instanceId: agentId } is not a one-line fix — it is a regression:

AgentDO serves both kinds of DO. routes/agents.ts:379 initialises a template with agentId: <agent id>, routes/instances.ts:213 initialises an instance with agentId: <instance id>, and the DO has no field that says which it is. Setting instanceId: agentId unconditionally would write an agent id into instance_id for every template DO — the mirror bug above, deliberately introduced, in the one place it isn't already happening.

Doing it properly means teaching the DO its own kind (a D1 lookup cached for the DO's lifetime, or a kind on the init payload with a lazy fallback for already-initialised DOs) plus the type narrowing in your step 4. That is a real change to agent-do.ts and it deserves its own ticket. Nothing is waiting on it: the reader now resolves both directions, for history and for new rows alike.

On the stats cards (usage.cost / usage.tokens)

Your comment's point 2 was a good lead and I followed it, but I don't think seeding them answers this ticket:

1. The question is comparative. "Which of my seven coders spent the money" can only be answered where the seven appear together. A stat card on one instance's own page cannot rank.
2. usage.cost alone is forbidden by the acceptance criterion. Yesterday's lane was right to refuse it. Seeding it would print a notional figure with no payer beside it — on this account, "Chess coder 2: $2,495.30" with $7.27 of actual money.
3. Making it safe needs a new usage.charged source and a migration seeding a statsSchema onto the coding templates. Both are reasonable; neither is this ticket, and I did not want to open a migration number while three agents were landing concurrently.

So: worth a follow-up ticket ("seed usage.charged + usage.cost as default stat cards on the coding agents"), phrased so the charged source lands first.

Verified

10/10 CI gates, 8,543 unit tests, 405 Playwright specs (chromium + webkit) including the 320/375/390 sweep of /console/usage with four breakdown cards. Deploy 1fcac9e green on API, Host and MCP; the live payload above is the proof it works on real data. MCP usage_summary forwards byInstance unchanged.

Closing — the per-instance figure and the labels are both live. The writer fix is the one thing left and it is described above; say the word and I'll file it.