@cr1ms0n/pi-subagent 0.8.8 → 0.9.0

package/docs/ARCHITECTURE.md

@@ -1,132 +1,168 @@
-# Architecture contract
-
-`pi-subagent` is split by ownership boundary:
-
-- `runner.ts`: one child process, Pi RPC protocol (JSONL commands on stdin, events on
-  stdout — a superset of `--mode json`), cancellation, process trees, budgets, and a live
-  stdin command channel used for mid-run steering. Extension UI dialogs from headless
-  children are auto-cancelled so they can never hang a run; stdin is closed after
-  `agent_settled` so RPC children shut down cleanly. Budget breaches steer a wrap-up
-  message and allow grace turns before SIGTERM (`wrappedUp` marks a clean conclusion).
-  A stall watchdog flags protocol silence, probes liveness via `get_state`, and kills
-  after a second window so retry can take over. Group kills verify process start-time
-  identity (Linux `/proc`, macOS/BSD `ps lstart`) before signalling a possibly-recycled
-  PID; transcript joins happen only on message boundaries, not per-chunk ticks.
-- Retry with model fallback lives in `orchestrator.ts` (`isTransientFailure`): queue
-  timeouts, stalls, spawn errors, and provider errors re-run the same spec on the next
-  fallback model with accumulated usage; task-quality failures never retry. Each attempt
-  re-derives its Pi context-tool membership from the attempt's target model via
-  `context-policy.ts`, so an ineligible fallback cannot inherit the primary's tools.
-- `context-policy.ts`: sole reader/parser of the operator-owned `pi-openai-toolkit`
-  Remote Context allowlist (`<Pi agent dir>/extensions/pi-openai-toolkit/config.json`).
-  Exposes the exact `gatewayContextModels` match plus the four context-tool names, and
-  fails closed to an empty allowlist on any missing/unreadable/invalid/non-remote
-  configuration. The toolkit's native `openai-codex` rule is intentionally not mirrored.
-- `context: "fork"` spawns the child with `--fork <parent session file>` so it starts
-  from a real branched copy of the parent conversation. Fail-fast when the parent
-  session is not persisted; single-task only.
-- `registry.ts`: one parent-session runtime, run state, snapshots, resume locks, and the
-  single LiveRun→snapshot/persisted-result projections used by every consumer.
-- `semaphore.ts`: per-parent-runtime child-process limit.
-- `process-lock.ts`: machine-wide durable coordination under `~/.pi/subagent-locks/` —
-  exclusive per-child-session resume locks, global concurrency slots, and run process
-  identity records for orphan reconcile.
-- `launch.ts`: resolve the child `pi` invocation via `PI_SUBAGENT_BIN` or
-  `process.execPath` + CLI entry (bare PATH name only as last-resort fallback).
-- `persistence.ts`: versioned active-branch event folding and bounded child transcript metadata.
-- `maintenance.ts`: filesystem GC (session files) and abort-race helpers; kept out of persistence.
-- `usage.ts`: provider-reported root/subagent/combined accounting.
-- `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles. `schema.ts` retains the canonical TypeBox validators and derives provider-safe tool-schema projections; `extension.ts` registers those projections while validating calls with the originals. Pi context-management control-plane tools are granted per target model: `context-policy.ts` reads the operator-owned `pi-openai-toolkit` Remote Context allowlist (`compaction.gatewayContextModels` with `contextManagement: "remote"`), `policy.ts` removes the four context names from every non-eligible Pi child, `orchestrator.ts` re-filters them per fallback attempt, and both fail closed to no context tools when the config is missing or invalid.
-- `config.ts`: defaults ← `~/.pi/subagent.json` ← `PI_SUBAGENT_*` env overrides.
-- `structured.ts`: structured-output contract (dependency-free JSON-Schema subset
-  validation, fenced json:result extraction, contract/repair prompts) and
-  conservative double-encoded-arg repair. The runner gates the child's settle on
-  validation and runs one steer-based repair round before accepting failure.
-- `agents.ts`: named agent files (`.pi/agents/`, `.agents/agents/`, global agent dir).
-  Flat-YAML frontmatter + markdown persona body; resolved in policy with explicit
-  params > agent file > profile taskDefaults > parent inheritance. Catalog refreshes
-  lazily (5s TTL) so new files work mid-session; symlinks and oversized files skipped.
-- `notifications.ts`: background-run completion batching. Successes group within a
-  debounce window (hard cap on hold time); failures bypass batching and flush
-  immediately; delivered-state is re-checked at flush time so a consuming `wait`
-  suppresses the redundant notification.
-- `ui.ts`: renderers, footer status and `/subagents` inspector. The ambient widget
-  (extension-side) shows BACKGROUND runs only — foreground runs render inline as the
-  tool result, so widget display would double-render them.
-- `extension.ts`: wiring only; no business logic. Nested children at the depth ceiling do
-  not re-register the tool; only top-level parents run maintenance.
-
-Invariants:
-
-1. A run belongs to exactly one parent session key and cannot update another session.
-2. No more than `maxActiveProcesses` children run per extension runtime, and no more than
-   `maxGlobalActive` across every Pi parent process on the machine.
-3. Cancellation prevents queued tasks from spawning.
-4. A child session may have only one direct resume writer at a time, enforced by an
-   in-memory lock *and* a durable file lock under `lockDir` that survives crashes and
-   coordinates across independent parent processes.
-5. Parallel write-capable tasks need isolated worktrees/distinct cwd or explicit unsafe opt-in.
-6. Every tool response is globally capped to 50 KB / 2,000 lines; full data lives in artifacts/transcripts.
-7. Status is compact; wait is the one-shot deliverable.
-8. On shutdown or tree navigation, child runs are cancelled and awaited for a bounded grace period.
-9. On startup, orphan process groups recorded under `lockDir` are reaped (SIGTERM then SIGKILL)
-   before any matching child session is eligible for resume. `$state: "lost"` is a labeling
-   that keeps `resumeBlocked` until reconciliation proves death.
-10. Billed usage is folded once per root message and once per full child run UUID.
-11. Checkpoint persistence events are lightweight (state, usage, process identity, pointers).
-    Full transcripts and final output are persisted exactly once, in the terminal event.
-12. High-frequency registry "changed" events coalesce (trailing window); state transitions,
-    new child sessions, billed-usage advances, and terminal events flush immediately.
-13. `wait` is interruptible: aborting a wait returns promptly and does NOT cancel the
-    background run. Only `cancel` (or parent shutdown) aborts a run.
-14. Budget stops (`max_turns`/`max_cost`) with at least one completed turn end as `partial`
-    and deliver their output normally. Streams truncated after useful assistant output also
-    end as `partial`. Timeouts report `state: "timeout"` with `timeoutPhase`.
-15. `timeout_ms` covers the whole task, including semaphore queue time, but the phase
-    (queued / starting / running) is recorded so agents can apply the right retry policy.
-16. Worktrees live under a durable root (`~/.pi/subagent-worktrees`), never a purgeable OS
-    tmpdir. Startup maintenance (top-level parents only) prunes stale git registrations,
-    removes unchanged leftovers, and sweeps changed-but-expired worktrees. Live-run
-    worktrees are always shielded. `include_wip` worktrees carry the parent's WIP patch in
-    the handle: `diff`/`apply` subtract it when subtraction is clean and otherwise report
-    the combined delta with an explicit `[includes parent WIP]` warning — never silently
-    wrong; a worktree containing only the untouched WIP patch counts as unchanged.
-17. Process-tree reaping after a clean exit can be disabled per task with `keep_background`
-    (for legitimately backgrounded work such as dev servers); forced stops always reap.
-18. Protocol completion prefers Pi's `agent_settled` event. Legacy `agent_end` without
-    `willRetry` is accepted for older Pi builds; `agent_end` with `willRetry: true` is
-    treated as non-terminal.
-19. Depth and spawn-policy parsing fail closed on malformed values: env scrubbing cannot
-    silently reset the depth counter to top-level, and a malformed `PI_SUBAGENT_SPAWNS`
-    disables spawning rather than unrestricting it.
-20. Budget breaches (`max_turns`/`max_cost`) steer a wrap-up message and allow grace
-    turns before SIGTERM; a child that concludes within grace ends `partial` with
-    `wrappedUp: true`. `graceTurns: 0` restores immediate stops.
-21. Transient failures (queued timeout, stall, spawn error, provider error, protocol
-    truncation) retry up to `maxRetries` extra attempts, escalating through
-    `fallback_models`; usage accumulates across attempts and `attemptedModels` is
-    recorded. Task-quality failures (nonzero exit with complete protocol, cancellation,
-    budget stop, running timeout) never retry.
-22. The stall watchdog treats protocol silence as suspect, not fatal: after
-    `stallAfterMs` the task is flagged and probed via `get_state` (a live child's
-    answer clears the flag); only continued silence for `stallKillAfterMs` more kills
-    the child — which is then a transient failure eligible for retry.
-23. Only `async: true` runs notify on completion and appear in the ambient widget.
-    Notification delivery respects delivered-once: a `wait` that consumed the run
-    suppresses the notification.
-24. Named agent files supply per-field defaults only; explicit request params always
-    win, and capability profiles fail closed regardless of what an agent file declares.
-25. Structured-output validation never discards paid work: schema failure after the
-    repair round downgrades completed → partial with `structuredError`, and the raw
-    text still delivers. Validation is enforced on the parent side of the process
-    boundary — the child cannot self-attest.
-26. Arg repair only decodes free-text fields with high-signal escape patterns
-    (literal \n or \") and no real newlines; identifier fields, tool lists, and
-    Windows-path-like strings are never modified.
-27. Global slots are depth-tiered: `tryAcquireGlobalSlot(runId, depth)` admits only while
-    `activeAtOrBelowDepth(depth) < maxGlobalActive - reservedFor(depth)`, holding slots
-    back for deeper tiers so a full-width spawn tree cannot deadlock on its own children.
-    Slot records without a `depth` field count as depth 0.
-28. `action: "plan"` is a truth oracle: it runs the exact validation and preflights of a
-    real spawn and returns the resolved plan without spawning — never a softer check, and
-    never a registry entry.
+# Architecture contract
+
+`pi-subagent` is split by ownership boundary:
+
+- `runner.ts`: one child process, Pi RPC protocol (JSONL commands on stdin, events on
+  stdout — a superset of `--mode json`), cancellation, process trees, budgets, and a live
+  stdin command channel used for mid-run steering. Extension UI dialogs from headless
+  children are auto-cancelled so they can never hang a run; stdin is closed after
+  `agent_settled` so RPC children shut down cleanly. Budget breaches steer a wrap-up
+  message and allow grace turns before SIGTERM (`wrappedUp` marks a clean conclusion).
+  A stall watchdog flags protocol silence, probes liveness via `get_state`, and kills
+  after a second window so retry can take over. Group kills verify process start-time
+  identity (Linux `/proc`, macOS/BSD `ps lstart`) before signalling a possibly-recycled
+  PID; transcript joins happen only on message boundaries, not per-chunk ticks.
+- Retry lives in `orchestrator.ts` (`isTransientFailure`): queue timeouts, stalls, spawn
+  errors, and provider errors re-run the same already-selected spec (model and tool set)
+  with accumulated usage; there is no fallback-model escalation, and task-quality failures
+  never retry.
+- `context: "fork"` spawns the child with `--fork <parent session file>` so it starts
+  from a real branched copy of the parent conversation. Fail-fast when the parent
+  session is not persisted; single-task only.
+- `registry.ts`: one parent-session runtime, run state, snapshots, resume locks, and the
+  single LiveRun→snapshot/persisted-result projections used by every consumer.
+- `semaphore.ts`: per-parent-runtime child-process limit.
+- `process-lock.ts`: machine-wide durable coordination under `~/.pi/subagent-locks/` —
+  exclusive per-child-session resume locks, global concurrency slots, and run process
+  identity records for orphan reconcile.
+- `launch.ts`: resolve the child `pi` invocation via `PI_SUBAGENT_BIN` or
+  `process.execPath` + CLI entry (bare PATH name only as last-resort fallback).
+- `persistence.ts`: versioned active-branch event folding, the bounded routing-event decoder
+  (`subagent-routing-v1`), and bounded child transcript metadata.
+- `maintenance.ts`: filesystem GC (session files) and abort-race helpers; kept out of persistence.
+- `usage.ts`: provider-reported root/subagent/combined accounting, plus a separate
+  once-per-request routing-token category whose currency is reported as unreported.
+- `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles. `schema.ts` retains the canonical TypeBox validators and derives provider-safe tool-schema projections; `extension.ts` registers those projections while validating calls with the originals. Pi context-management control-plane tools remain available to child allowlists without granting project-file write access.
+- `routing-types.ts` / `routing-policy.ts` / `jev-router.ts` / `dispatch-routing.ts`:
+  the mandatory Jev route. `routing-types.ts` owns the selector DTOs, decision/receipt
+  shapes and local resource limits; `routing-policy.ts` owns the strict `jevRouting`
+  parser, the candidate intersection with locally available models, and the injected
+  model-facing guidance; `jev-router.ts` owns the injectable TypeSafe transport,
+  response validation, deadlines and per-request receipts; `dispatch-routing.ts`
+  resolves every worker before any launch and refuses a partially selected fanout. The
+  router has no engine imports and makes no parent UI calls.
+- `config.ts`: defaults ← `~/.pi/subagent.json` ← `PI_SUBAGENT_*` env overrides.
+- `structured.ts`: structured-output contract (dependency-free JSON-Schema subset
+  validation, fenced json:result extraction, contract/repair prompts) and
+  conservative double-encoded-arg repair. The runner gates the child's settle on
+  validation and runs one steer-based repair round before accepting failure.
+- `agents.ts`: named agent files (`.pi/agents/`, `.agents/agents/`, global agent dir).
+  Flat-YAML frontmatter + markdown persona body; resolved in policy with explicit
+  params > agent file > profile taskDefaults > parent inheritance. Catalog refreshes
+  lazily (5s TTL) so new files work mid-session; symlinks and oversized files skipped.
+- `notifications.ts`: background-run completion batching. Successes group within a
+  debounce window (hard cap on hold time); failures bypass batching and flush
+  immediately; delivered-state is re-checked at flush time so a consuming `wait`
+  suppresses the redundant notification.
+- `ui.ts`: renderers, footer status and `/subagents` inspector. The ambient widget
+  (extension-side) shows BACKGROUND runs only — foreground runs render inline as the
+  tool result, so widget display would double-render them.
+- `extension.ts`: wiring only; no business logic. Nested children at the depth ceiling do
+  not re-register the tool; only top-level parents run maintenance.
+
+Invariants:
+
+1. A run belongs to exactly one parent session key and cannot update another session.
+2. No more than `maxActiveProcesses` children run per extension runtime, and no more than
+   `maxGlobalActive` across every Pi parent process on the machine.
+3. Cancellation prevents queued tasks from spawning.
+4. A child session may have only one direct resume writer at a time, enforced by an
+   in-memory lock *and* a durable file lock under `lockDir` that survives crashes and
+   coordinates across independent parent processes.
+5. Parallel write-capable tasks need isolated worktrees/distinct cwd or explicit unsafe opt-in.
+6. Every tool response is globally capped to 50 KB / 2,000 lines; full data lives in artifacts/transcripts.
+7. Status is compact; wait is the one-shot deliverable.
+8. On shutdown or tree navigation, child runs are cancelled and awaited for a bounded grace period.
+9. On startup, orphan process groups recorded under `lockDir` are reaped (SIGTERM then SIGKILL)
+   before any matching child session is eligible for resume. `$state: "lost"` is a labeling
+   that keeps `resumeBlocked` until reconciliation proves death.
+10. Billed execution usage is folded once per root message and once per full child run UUID.
+    Selector usage is a separate category folded once per selector request ID, with currency
+    reported as unreported rather than inferred.
+11. Checkpoint persistence events are lightweight (state, usage, process identity, pointers).
+    Full transcripts and final output are persisted exactly once, in the terminal event.
+12. High-frequency registry "changed" events coalesce (trailing window); state transitions,
+    new child sessions, billed-usage advances, and terminal events flush immediately.
+13. `wait` is interruptible: aborting a wait returns promptly and does NOT cancel the
+    background run. Only `cancel` (or parent shutdown) aborts a run.
+14. Budget stops (`max_turns`/`max_cost`) with at least one completed turn end as `partial`
+    and deliver their output normally. Streams truncated after useful assistant output also
+    end as `partial`. Timeouts report `state: "timeout"` with `timeoutPhase`.
+15. `timeout_ms` covers the whole task, including semaphore queue time, but the phase
+    (queued / starting / running) is recorded so agents can apply the right retry policy.
+16. Worktrees live under a durable root (`~/.pi/subagent-worktrees`), never a purgeable OS
+    tmpdir. Startup maintenance (top-level parents only) prunes stale git registrations,
+    removes unchanged leftovers, and sweeps changed-but-expired worktrees. Live-run
+    worktrees are always shielded. `include_wip` worktrees carry the parent's WIP patch in
+    the handle: `diff`/`apply` subtract it when subtraction is clean and otherwise report
+    the combined delta with an explicit `[includes parent WIP]` warning — never silently
+    wrong; a worktree containing only the untouched WIP patch counts as unchanged.
+17. Process-tree reaping after a clean exit can be disabled per task with `keep_background`
+    (for legitimately backgrounded work such as dev servers); forced stops always reap.
+18. Protocol completion prefers Pi's `agent_settled` event. Legacy `agent_end` without
+    `willRetry` is accepted for older Pi builds; `agent_end` with `willRetry: true` is
+    treated as non-terminal.
+19. Depth and spawn-policy parsing fail closed on malformed values: env scrubbing cannot
+    silently reset the depth counter to top-level, and a malformed `PI_SUBAGENT_SPAWNS`
+    disables spawning rather than unrestricting it.
+20. Budget breaches (`max_turns`/`max_cost`) steer a wrap-up message and allow grace
+    turns before SIGTERM; a child that concludes within grace ends `partial` with
+    `wrappedUp: true`. `graceTurns: 0` restores immediate stops.
+21. Transient failures (queued timeout, stall, spawn error, provider error, protocol
+    truncation) retry up to `maxRetries` extra attempts on the already selected model and
+    tool set; there is no fallback-model escalation and no reselection. Usage accumulates
+    across attempts. Task-quality failures (nonzero exit with complete protocol,
+    cancellation, budget stop, running timeout) never retry.
+22. The stall watchdog treats protocol silence as suspect, not fatal: after
+    `stallAfterMs` the task is flagged and probed via `get_state` (a live child's
+    answer clears the flag); only continued silence for `stallKillAfterMs` more kills
+    the child — which is then a transient failure eligible for retry.
+23. Only `async: true` runs notify on completion and appear in the ambient widget.
+    Notification delivery respects delivered-once: a `wait` that consumed the run
+    suppresses the notification.
+24. Named agent files supply per-field defaults only; explicit request params always
+    win, and capability profiles fail closed regardless of what an agent file declares.
+25. Structured-output validation never discards paid work: schema failure after the
+    repair round downgrades completed → partial with `structuredError`, and the raw
+    text still delivers. Validation is enforced on the parent side of the process
+    boundary — the child cannot self-attest.
+26. Arg repair only decodes free-text fields with high-signal escape patterns
+    (literal \n or \") and no real newlines; identifier fields, tool lists, and
+    Windows-path-like strings are never modified.
+27. Global slots are depth-tiered: `tryAcquireGlobalSlot(runId, depth)` admits only while
+    `activeAtOrBelowDepth(depth) < maxGlobalActive - reservedFor(depth)`, holding slots
+    back for deeper tiers so a full-width spawn tree cannot deadlock on its own children.
+    Slot records without a `depth` field count as depth 0.
+28. `action: "plan"` is a truth oracle: it runs the exact validation, Jev selection and
+    local preflights of a real spawn and returns the resolved plan and its selector usage
+    without spawning. It creates no registry entry, and its fee-bearing selection is not
+    cached for a later dispatch.
+29. Every new extension-managed launch (`task`/`tasks[]`, `action:"plan"`, `/btw`,
+    resume, fork, nested dispatch and the optional synthesis child) crosses one selector
+    interface before any child starts. The dedicated candidate list intersected with
+    locally available models is the only source of execution models; the full locally
+    permitted tool catalog is the only candidate source. Legacy `model`/`fallback_models`
+    fields are rejected on new work, and an empty selected tool set never becomes
+    inheritance or "all tools".
+30. The finalized tool subset is passed to the child as Pi's `--tools` allowlist
+    (`--no-tools` when empty). Pi 0.86.0 is the verified baseline for built-in, extension
+    and late-registered tool enforcement; a host that cannot honor the allowlist is
+    refused rather than silently weakened, and no older release is advertised as
+    equivalent.
+    Startup verification is the enforcement companion: the Pi adapter supplies a
+    package-local preflight extension plus a bounded non-secret expectation, verifies that
+    the nonce-specific bootstrap command exists from the expected package source, then
+    requires the child to acknowledge the exact selected model and finalized tool names
+    (including nested-tool source) before the real task prompt is sent. Missing or
+    mismatched acknowledgement is a capability/startup diagnostic, never compensated by
+    broadening tools or choosing another model.
+31. An absolute task deadline is created before preflight/selection, and routing, setup,
+    queue and retries all count against it. Pending selector work is tracked per session
+    runtime, aborted on cancellation, shutdown or session switch, and every post-await
+    transition re-checks captured runtime/session ownership so a late response cannot
+    launch into a replaced session.
+32. Before any paid selection, plan and dispatch share a side-effect-free direct-resume
+    availability check (in-memory owner, `resumeBlocked`, durable lock ownership and
+    staleness) that acquires, renews or reaps nothing. Dispatch still takes the
+    authoritative lock atomically at the existing launch point, and forked resumes skip
+    the exclusive direct-resume check.

package/docs/COST-ACCOUNTING.md

@@ -1,66 +1,116 @@
-# Cost accounting
-
-`pi-subagent` reports three independent ledgers:
-
-- **root** — provider-reported usage from assistant messages on the active parent-session branch.
-- **subagents** — provider-reported cumulative usage from child-run checkpoints and terminal events on that same branch.
-- **combined** — root + subagents.
-
-These totals appear in `subagent { action: "status" }`, per-run status, the `/subagent-cost` command, and the `/subagents` overlay header. The footer stays terse (running/ready counts only) because Pi's native footer already shows session cost — including subagent spend, on Pi builds with native tool-result usage accounting (see below).
-
-## Source of truth
-
-The extension does not estimate prices. It uses Pi's normalized provider response:
-
-```ts
-message.usage.cost.total
-```
-
-It also retains provider-reported input/output/cache category costs, token counts, reasoning tokens, context size, and completed turn count when supplied.
-
-## Native Pi usage accounting
-
-Pi builds after v0.80.10 persist an optional `usage` field on tool-result messages ([pi#6671](https://github.com/earendil-works/pi/pull/6671)) and fold it into the native footer total, `/session` statistics (as `Tools/summaries`), and RPC `get_state` totals.
-
-The extension participates in both directions:
-
-- **Upward** — the tool result that *delivers* a run (foreground completion, or the first `wait`) carries the run's total provider usage as native `usage`. Attachment is gated on the same delivered-flag transition as output delivery, so it happens exactly once per run UUID. Status, replayed waits, steer, diff/apply/discard, and plan responses never attach usage. Older Pi hosts copy only `content`/`details` from tool results and silently ignore the field — safe on every version this package supports.
-- **Downward** — a child's event stream may contain tool-result messages that themselves carry nested usage (for example, a grandchild subagent on a new-Pi child). The parent folds that into the run's cumulative usage, so `max_cost` budgets and both ledgers see true subtree spend. Pre-#6671 children simply never emit the field.
-
-Known undercounts in the **native** total (the extension ledger still counts these from persisted entries):
-
-- A background run dismissed in the overlay (or via status) without a delivering `wait` never produces a tool result, so its spend reaches only the extension ledger.
-- A failed or lost run raises an error instead of returning a tool result; any pre-failure usage likewise reaches only the extension ledger.
-
-Because the native footer counts parent assistant messages plus delivered tool-result usage, and the extension's **combined** counts the same runs by UUID, the two agree whenever every terminal run was delivered.
-
-## Deduplication rules
-
-1. Root assistant messages are counted once by session-entry ID.
-2. Each subagent run is counted once by full run UUID; the newest live/checkpoint/terminal cumulative value replaces older values.
-3. Delivery, dismissal, status, and checkpoint events never add cost.
-4. If an old run is evicted from in-memory UI history, its latest persisted usage still contributes to the session ledger.
-5. Active and immediately completed runs supplement or replace stale persisted checkpoints until newer session entries become visible; the full run UUID prevents double counting afterward.
-6. Resumed and forked invocations are distinct billed runs. Their new provider usage is counted once, even though they reuse prior context.
-7. Retry attempts (transient-failure retries and model fallbacks) accumulate into their
-   run's single usage record — every attempt's billed usage counts once, under one run
-   UUID, with `attemptedModels` recording the escalation path.
-8. The optional parallel `synthesis` child bills into the same run as an extra result.
-9. Native `usage` on the delivering tool result mirrors rule 2's run totals and is attached at most once per run (delivered-flag gated), so Pi-side totals cannot double count a run either.
-
-## Branch semantics
-
-Only `sessionManager.getBranch()` is used. Costs from abandoned sibling branches are excluded. When a parent session is forked, its inherited active-branch terminal entries remain part of that fork's historical total; new runs are added to the fork independently.
-
-## Failure and cancellation
-
-Any usage reported before a failure, timeout, budget stop, cancellation, or parent crash is retained in a cumulative checkpoint/terminal record. A run with no provider response contributes zero rather than an estimate.
-
-## Provider limitations
-
-Accounting is only as precise as the provider data normalized by Pi:
-
-- Some providers may report zero or incomplete costs.
-- `reasoning` is a subset of output tokens and is not added to output again.
-- `contextTokens` is the latest turn's context size, not an additive billed-token field.
-- The extension deliberately does not infer missing prices from a local model table.
+# Cost accounting
+
+`pi-subagent` reports four independent ledgers:
+
+- **root** — provider-reported usage from assistant messages on the active parent-session branch.
+- **subagents** — provider-reported cumulative usage from child-run checkpoints and terminal events on that same branch.
+- **routing**: usage reported by the Jev/TypeSafe selector, one record per selector HTTP request.
+- **combined**: root + subagents + routing.
+
+These totals appear in `subagent { action: "status" }`, per-run status, the
+`/subagent-cost` command, and the `/subagents` overlay header. The footer stays
+terse (running/ready counts only) because Pi's native footer already shows
+session cost, including subagent spend, on Pi builds with native tool-result
+usage accounting (see below).
+
+## Source of truth
+
+The extension does not estimate prices. It uses Pi's normalized provider response:
+
+```ts
+message.usage.cost.total
+```
+
+It also retains provider-reported input/output/cache category costs, token counts, reasoning tokens, context size, and completed turn count when supplied.
+
+## Routing (selector) accounting
+
+Jev selection is billed separately from child execution:
+
+- TypeSafe reports input and output **tokens**, not billed currency. The routing
+  ledger therefore reports tokens and marks its currency as **unreported**. Do not
+  read the numeric `0` currency placeholder in the native usage schema as the
+  selector being free: it is the API-required number for an unreported value.
+- Numeric dollar totals for root/subagent/combined exclude unreported routing
+  spend. The status line says so explicitly rather than silently omitting it.
+- `max_cost` remains the provider-reported execution ceiling for the child and
+  its subtree. It cannot cap TypeSafe charges, so a run can stay under `max_cost`
+  while still incurring selector fees.
+- No selector price is inferred from a public price page or a local model table.
+
+A routing record exists per selector HTTP request, not per logical selection: a
+model question plus one or more packed tool-question requests each produce their
+own record, and all of them count once by full request ID. Plan selections and
+pre-spawn failures are included, because no child run exists to carry them.
+
+Successful route metadata (decision ID, selector model and reported version(s),
+selected execution model/tools, locally added control-plane tools, confidence,
+success outcome, latency and receipt IDs) travels with the run and both registry
+projections. Per-request failure outcomes and safe error codes stay in selector receipts. It carries no descriptions, raw request bodies, headers,
+credentials or invented rationale.
+
+Receipts pending append visibility remain in a bounded session-local overlay until the
+active branch exposes the matching record. Persistence retries reuse the receipt ID,
+not the paid selector request. If persistence cannot be confirmed, new child launch is
+blocked and a branch change is cancelled; a forced shutdown reports that durable usage
+may be incomplete. This cannot repair an unavailable storage adapter after process exit.
+
+## Native Pi usage accounting
+
+Pi builds after v0.80.10 persist an optional `usage` field on tool-result messages ([pi#6671](https://github.com/earendil-works/pi/pull/6671)) and fold it into the native footer total, `/session` statistics (as `Tools/summaries`), and RPC `get_state` totals.
+
+The extension participates in both directions:
+
+- **Upward**: the tool result that *delivers* a run (foreground completion, or the first `wait`) carries the run's total provider usage as native `usage`. Attachment is gated on the same delivered-flag transition as output delivery, so it happens exactly once per run UUID. Status, replayed waits, steer, diff/apply/discard, and plan responses never attach run execution usage; plan may report its own selector usage through its result instead (rule 10). Older Pi hosts copy only `content`/`details` from tool results and silently ignore the field; that is safe on every version this package supports.
+- **Downward**: a child's event stream may contain tool-result messages that themselves carry nested usage (for example, a grandchild subagent on a new-Pi child). The parent folds that into the run's cumulative usage, so `max_cost` budgets and the execution/routing ledgers see true subtree spend. Pre-#6671 children simply never emit the field.
+
+Known undercounts in the **native** total (the extension ledger still counts these from persisted entries):
+
+- A background run dismissed in the overlay (or via status) without a delivering `wait` never produces a tool result, so its spend reaches only the extension ledger.
+- A failed or lost run raises an error instead of returning a tool result; any pre-failure usage likewise reaches only the extension ledger. The same native limitation applies to selector usage on a thrown error: the extension ledger retains it, but a thrown tool call cannot attach a native usage object. This is documented rather than converted into a success.
+
+Because the native footer counts parent assistant messages plus delivered tool-result usage, and the extension's **combined** counts the same runs by UUID, the reported token totals agree when every run and selector receipt was successfully delivered as native usage. Thrown errors and undelivered plan/dispatch failures can leave selector usage only in the extension ledger; currency totals never include unreported selector fees.
+
+## Deduplication rules
+
+1. Root assistant messages are counted once by session-entry ID.
+2. Each subagent run is counted once by full run UUID; the newest live/checkpoint/terminal cumulative value replaces older values.
+3. Delivery, dismissal, status, and checkpoint events never add cost.
+4. If an old run is evicted from in-memory UI history, its latest persisted usage still contributes to the session ledger.
+5. Active and immediately completed runs supplement or replace stale persisted checkpoints until newer session entries become visible; the full run UUID prevents double counting afterward.
+6. Resumed and forked invocations are distinct billed runs. Their new provider usage is counted once, even though they reuse prior context.
+7. Retry attempts (transient-failure retries on the already selected model and tool set)
+   accumulate into their run's single usage record: every attempt's billed usage counts once
+   under one run UUID. There is no fallback-model escalation, so `attemptedModels` repeats the
+   selected model rather than recording a route change.
+8. The optional parallel `synthesis` child bills into the same run as an extra result.
+9. Selector requests are counted once by full selector request ID, including plan
+   requests and pre-spawn rejected decisions. Route references inside task results
+   never add selector usage again, and each receipt is folded once across
+   replay/status/repeated wait.
+10. Native `usage` on the delivering tool result mirrors rule 2's run totals and is attached at most once per run (delivered-flag gated), so Pi-side totals cannot double count a run either. Worker pre-spawn routing tokens attach once at async start; the first delivery/wait attaches child execution usage plus any deferred-synthesis routing tokens not yet delivered; foreground completion attaches all invocation routing tokens plus execution tokens. Plan attaches only its own routing usage. Missing usage on an interrupted or invalid response stays **unknown**, never an invented zero. A partial or malformed token report retains individually validated counts while marking completeness unknown; for example, valid input with invalid output is not a complete report.
+
+Native routing attachment commits atomically: foreground/wait use the run's single
+`delivered` event for linked receipts; plan and async-start use one `native-delivery`
+request-ID batch on the routing event stream. A throwing append does not consume a
+prefix or set the in-memory run delivered flag. Transient persistence failures retry
+without another selector call. A batch holds at most 1024 receipt IDs; larger plan or
+background requests must be split. Background requests check this bound before any
+child/run registration. Already incurred selector usage stays in the ledger.
+
+## Branch semantics
+
+Only `sessionManager.getBranch()` is used. Costs from abandoned sibling branches are excluded. When a parent session is forked, its inherited active-branch terminal entries remain part of that fork's historical total; new runs are added to the fork independently.
+
+## Failure and cancellation
+
+Any usage reported before a failure, timeout, budget stop, cancellation, or parent crash is retained in a cumulative checkpoint/terminal record. A run with no provider response contributes zero rather than an estimate.
+
+## Provider limitations
+
+Accounting is only as precise as the provider data normalized by Pi:
+
+- Some providers may report zero or incomplete costs.
+- `reasoning` is a subset of output tokens and is not added to output again.
+- `contextTokens` is the latest turn's context size, not an additive billed-token field.
+- The extension deliberately does not infer missing prices from a local model table, and TypeSafe's token-only reports are never converted into a dollar estimate.