docs(adr): ADR-022 — persona colleagues, separating who an agent is from where it runs

[lilyshen0722]

Draft. Design-lead input pending, Sam to ratify.

The argument in one user

2026-08-14, from production message history:

• 03:26 asks Scout two questions in Chinese → substantive answers in 4 and 5 seconds, including a refusal to invent something it couldn't know
• 03:30 goes to add an agent → v1 catalog → installs the claude-code template
• 03:30–03:36 asks it the same question three times across two pods → total silence
• gone

Across 21 real signups since 08-01: 21 verified, 21 got a workspace, 5 ever typed anything, and 0 have ever received a reply to something they said.

The structural cause

The catalog sells a runtime as if it were a colleague. Picking claude-code picks a CLI you must go launch, so "Hire an agent" returns a seat that can't do anything yet.

That contradicts a thesis we already hold — CLAUDE.md's "identity is portable, separate from runtime", and ADR-001's model of exactly that split. The UI only ever offered the axis users care about least and can act on least.

Decisions

1. Persona is a first-class object — role, prompt, skills, voice. Not a runtime.
2. Persona and runtime are chosen separately, in that order. Changing where must never change who (ADR-001 identity continuity).
3. The hosted half ships on the runtime we already have. The native runtime already executes four personas off one engine with different prompts — it is already persona-parameterized. This needs no part of ADR-021's milestone track. That's the highest-leverage fact in the document.
4. Liveness shown at pick time, not discovered through silence.
5. The first-party set is retired, not ported — per Sam: pod-welcomer gone (Scout does it), task-clerk gone (agents read tasks via MCP), pod-summarizer reworked into a reader-specific TLDR rather than a resident agent, scout kept as persona Add basic unit tests for backend functions #1.

The constraint that shapes everything

V2YourTeamPage.tsx:124:

const primaryHirePath = isEntitled ? '/v2/agents/browse' : '/v2/agents/byo';

Unentitled users are routed to BYO on purpose, because hosted agents burn our tokens. The broken path is the free-tier default by design. Any redesign assuming free hosted agents is a pricing proposal in a product costume — so the free allowance is called out as Sam's decision, and the consequences section states plainly that a zero allowance makes this a better-shaped catalog and not a better activation rate.

Deliberately unanswered

The four design questions (what a persona is as an object, the pick-then-place flow and where it lives, how personas differ in-room, how rationing appears without reading as a paywall) are left open for fable-lead rather than pre-answered by me.

Also documented: /api/registry/agents returns 50 entries of which 21 are internal or smoke-test rows, and it's linked from the logged-out landing footer.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XeUH4HVDsDHYPsHJthXjB8

[lilyshen0722]

Adversarial pass on the three claims, all attacked at source. Claim 3 is right and worse than stated. Claim 2's weak input is not the one you flagged. Claim 1 holds on machinery and fails on the number.

---

Claim 2 — the price is not your weakest input. Two of your three configured bounds do not bind.

Your manifest values are accurate (scout.ts:89,104,105,110: deepseek-v4-flash, maxTurns: 6, maxTokens: 12000, dailyRunCap: 60). The native runtime does not read two of them.

nativeRuntimeService.ts:50   const MAX_TURNS = 10;          // hardcoded
nativeRuntimeService.ts:51   const MAX_TOKENS = 50_000;     // hardcoded
nativeRuntimeService.ts:52   const MAX_WALL_CLOCK_MS = 60_000;
:788  if (turnIndex >= MAX_TURNS)
:794  if (run.totalTokens >= MAX_TOKENS)
:800  if (Date.now() - startTime >= MAX_WALL_CLOCK_MS)

maxTurns and maxTokens from the manifest appear nowhere in backend/services except llmService's own unrelated options.maxTokens. So a run is bounded by 10 turns, not 6, and by a hardcoded 50k, not 6 × 12000.

Note your "worst-case run around 50k tokens" happens to equal MAX_TOKENS — the conclusion may survive, but not by the derivation stated, and that matters for the next person who tries to tune cost down via the manifest. dailyRunCap is the only one of the four that is actually read (:616).

And the token ceiling cannot fire

:926  run.totalTokens += Number(usage.total_tokens || 0);
:794  if (run.totalTokens >= MAX_TOKENS) { ... }

Your own measurement — 6,624 AgentRuns, zero with token data — means usage.total_tokens is absent. The || 0 then keeps run.totalTokens at 0, so 0 >= 50_000 is never true. The 50k guardrail is dead. Live bounds are 10 turns or 60s wall-clock, plus the daily cap.

So the same empty field both hides the cost and disables the ceiling meant to contain it. Direction of error on your estimate is upward, magnitude unknown — because the counter that would measure it is the dead one.

The good news, and it should change what you do before ratifying

The capture is already written. :860-867 reads llmResponse.usage and writes promptTokens / completionTokens / totalTokens onto the turn; :927 saves it. This is not missing telemetry — it is built telemetry returning empty, which is a bug with a findable cause, not a feature to schedule. Three candidates, very different costs: LiteLLM/OpenRouter not returning usage for deepseek-v4-flash; the field name not matching; or the response shape differing on the tool-call path.

liteLLMCallId is also captured (:871), so LiteLLM's own spend log is a second source needing no code change at all.

You said the price is your guess. I'd put it differently: you have two unmeasured inputs multiplied, and one of them is measurable today. Ratifying "~$1/day" before spending an hour on that is the avoidable part.

One structural note on tokens: maxTokens is an output cap (llmService:139 max_tokens: options.maxTokens || DEFAULT_MAX_OUTPUT_TOKENS). Input is uncapped, and :879-883 pushes each assistant message and tool result onto messages, re-sent every turn. For a tool-using agent the accumulating prompt is usually the dominant term, and nothing in the arithmetic models it.

---

Claim 3 — confirmed, and the ceiling cannot live where you want to put it

Cap query is exactly as you describe (:622-627): countDocuments({ podId, agentName, instanceId, startedAt >= dayStart }).

AgentRun has no user dimension at all. Fields: podId, agentName, instanceId, trigger, triggerEventId, status, turns, totalTokens, startedAt, completedAt, errorKind, errorMessage. The index is {podId, agentName, instanceId, startedAt}.

So a per-user ceiling cannot be computed where the cap currently lives — the collection cannot express "this user." It needs either a denormalized userId on AgentRun (schema + write-path change, and forward-only: existing rows can't be attributed, so the ceiling starts from zero history on day one) or a per-turn join through AgentInstallation.installedBy on the hot path.

One more, which the ADR should decide rather than inherit: the cap fails open by design (:614-616, "Count failure fails OPEN … an infrastructure fault must not silence an agent"). That is correct for a runaway-loop guard. It is wrong for a spend ceiling — a promise you can price must not evaporate exactly when Mongo is unhealthy. Same code, two purposes, opposite failure preferences. D5 currently inherits the loop-guard's choice for the pricing control.

---

Claim 1 — you avoid M4's ledger and inherit M4's unanswered question

The machinery half holds. Seat granting exists today: User.entitlements.cloudAgents (models/User.ts:79, :207, default false) gated at install.ts:361. Rationing by seat needs no credit ledger, no metering, no M4 machinery. That part of the claim is sound and measurable.

The number half does not. D5 says the per-user ceiling "is what makes '1 hosted colleague included' a promise we can price." Pricing a seat requires unit cost per seat. Unit cost requires the telemetry that Claim 2 shows is dead. So the ADR avoids M4's ledger and inherits M4's measurement requirement — and ships neither.

It does not smuggle in M4 under another name. It smuggles in M4's open question, and the finding above means that question is currently unanswerable from our own data. That is fine as a sequencing choice; it is not fine as a stated bound. I'd weaken D5's language from "it is what the shipped configuration already enforces" to what is actually true: two of the four configured limits are not read by the runtime, the token ceiling cannot fire, and the allowance is an estimate pending one telemetry fix.

---

Not verified

• The per-token price of deepseek-v4-flash — no pricing source here; I attacked the token count instead, which I think is the softer input.
• Your production counts (6,624 runs, zero token data, 0.3% utilization, 21 signups) — no DB access; taken as given, and Claim 2's conclusion depends on the zero-token one being right.
• Which of the three causes makes usage empty. That is one run's logs away and it changes the fix cost by an order of magnitude.
• D6, and everything in @pod-architect's and @ux-lead's lanes.