Count what each provider actually serves, and name the model that answered each turn

[ParallelEntrepreneur]

Closes #39.

A user wired a local DeepSeek server into Colonizer, saw Settings report it Reachable · 1 ms · 1 model, and concluded the local model was never used. Nothing was broken. The provider was pointed at subagent_model, and colonies almost never spawn subagents, so it legitimately saw almost no traffic. The gateway was the only component that knew anything, and it kept only live gauges — in-flight and queued, both zero whenever nobody is mid-request, which is almost always. There was no cumulative record anywhere, so "is this thing ever used?" had no answer in the UI.

This adds the record, and makes the UI say what it knows and no more.

What changed

Cumulative counters per provider (ask 1). gateway.rs gains a ProviderUsage — requests, failures, fallbacks, duration_ms, last_request_at — backed by atomics in UsageCounters, with a Timed RAII guard for wall-clock. They persist to <data_dir>/provider-usage.json, are seeded back on startup, flushed by a 5 s background task when dirty and once on shutdown, and forgotten when a provider is deleted. A missing or corrupt file degrades to defaults rather than failing to boot. Settings renders them per provider card; GET /api/providers returns them.

"Configured but unused" (ask 2). providers::used_by() reports which of model / subagent_model / background_model resolve to a given provider, across the global agent env and every org override. An empty list means configured but not referenced by any model setting. When a provider is wired only off the main path — the exact shape of this issue — the card says so instead of looking broken.

Which model served a turn (ask 3). sessionStream.ts diffs each turn_end event's cumulative model_usage map against the previous one to name the models that served that turn, shown in the chat turn footer (lead model, +N when several, full list in the tooltip) on both the complete and failed lines.

Where to point a local model (ask 4). Answered in prose, not by changing a default. README, the Claude Code module README and docs/protocol.md now say plainly that the orchestrator model carries nearly all of a colony's traffic and that subagent routing rarely sees any — "To put real traffic on your own hardware, point the orchestrator model at it." The supporting observation (four recent colonies of 413–2,095 events spawned 0, 0, 0 and 1 subagents) is presented as a sample, not a law. No default was changed; if reviewers would rather move the default, that is a separate and more invasive call than this issue needs.

Honesty decisions worth reviewing

This is a PR about a UI that misled someone, so where a counter can't support a claim, the wording backs off:

• requests includes queue-rejected attempts (a real request against the provider, and failures must stay a subset), but duration_ms excludes queue time — it is timed from slot acquisition. Otherwise a saturated max_concurrent: 1 provider that served nothing would display "10m 0s total" of pure queue wait. Both facts are stated in the struct doc and in protocol.md.
• fallbacks is a prediction, not an observation. The gateway answers with a fallback and the colony's router retries on Claude; that retry never returns through the gateway. The card says "N of them got a Claude fallback" and the tooltip says outright that it is a prediction.
• A failure part-way through a streamed body is not counted. Counting it on the anthropic wire would mean threading counters through the streaming type, which this change does not do. It is counted on the openai wire, where the error return already had the counter in scope. All three descriptions — struct doc, protocol.md, UI tooltip — now say exactly this.
• An absent usage is not "Never used". usage and used_by are optional in types.ts because older Motherships don't send them. A missing object renders "No usage recorded — this Mothership doesn't report usage"; "Never used" is reserved for counters that genuinely read zero. The same applies to used_by: the wiring note is skipped rather than guessed.
• Counters begin at zero on upgrade, so the card is explicit that it counts "since it first kept tally".

Verification

No CI exists in this repo, so everything below was run locally.

• cargo test --workspace: 107 passed, 0 failed, run twice with identical results (the new tests are async and multi-threaded). Includes new tests for every outcome a request can have, restart persistence with a corrupt-file fallback, provider deletion forgetting its tally, an openai body that fails after the headers, a queue timeout counting a request and a failure but no duration, and concurrent writers always leaving a parseable file.
• cargo clippy --workspace --all-targets: 18 warnings, exactly the pre-existing baseline, zero new — cross-checked against the diff's added-line ranges.
• web: npm run build (tsc --noEmit && vite build) green.
• modules/agents/claude-code: 58/58 pass, including the model_usage emission test the web reducer depends on. services/telemetry: 8/8 pass.
• The reducer was validated by executing the real module against eight scenarios (first turn, absent model_usage, full replay, post-resume totals shrink, stale seq, unchanged counts, NaN/Infinity/string garbage, mixed shrink-and-grow) rather than by reading it. It never emits a negative delta or invents a model.
• The dirty-flag fix was mutation-tested: its assertion fails against the previous any-short-circuit form.
• cargo fmt was deliberately not run. This repo has no rustfmt.toml and rustfmt disagrees with the house style in every file of both crates; new code matches its surroundings by hand.

Look closely at

• write_usage (gateway.rs). Three callers write this file — the flush loop, the shutdown flush, and forget_usage. They previously shared one .tmp path, so interleaved writes could publish invalid JSON, which on next boot would silently reset every provider's tally and report "Never used" for a busy provider — the very lie this issue is about. Each call now uses a unique tmp name and cleans up after a failed write. A residual window remains and is documented in the comment: renames can still land out of order, so a tally can be briefly stale, but each published snapshot is complete and parseable.
• Dirty flags are cleared before the write, so a failed write drops that batch until the next change. The in-memory tally stays correct; the flush protocol was deliberately not restructured.
• Timed's lifetime. Moving the timer after the permit must not stop it covering the streamed body. It is still moved into the same Guards tuple and dropped when the stream ends — worth a second pair of eyes.
• The queue-timeout test pins the contract, not the handler. App is only constructible in main.rs and there is no test precedent for building one, so the test replays the counting sequence against a real exhausted semaphore instead of driving proxy. A revert of the two-line Timed move would be caught by review, not by that test.
• Known cosmetic gap: if a provider is deleted in the window between provider lookup and counter acquisition, a zero-valued ghost entry can persist in the JSON, and a request in flight during deletion loses its last ticks. Left alone as accounting noise with no panic risk.
• Pre-existing, not introduced here: a client that survives a colony resume without reloading keeps a stale lastSeq while the event log restarts at seq 1; the whole chat thread misrenders in that state, and the new models line inherits it.
• Invariant to preserve: modelsOfTurn attributing a first-seen turn_end's whole total is correct only because replay is always complete. If a replay tail-limit is ever added, the first replayed turn would silently absorb the colony's all-time usage.

---

🤖 Generated by Colonizer in a microVM

[ParallelEntrepreneur]

Superseded by the PR above, which is this commit cherry-picked onto current main.

This branch was cut from the history main had before it was rewritten, so eight of its nine commits are already on main under different SHAs and git saw two lineages for the same content. Cherry-picking the one real commit left three trivial conflicts, all resolved there.

It also surfaced a break no textual merge would have flagged: Gateway::new() grew a data_dir argument here, and main.rs gained a test helper on main after this branch was cut that still called it with none. Cherry-picked cleanly, then failed to compile. Fixed in the new PR.