@cr1ms0n/pi-subagent 0.8.9 → 0.10.0

package/README.zh-CN.md

@@ -0,0 +1,132 @@
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+# Pi Smart Subagents
+
+在 [Pi](https://pi.dev/) 中运行独立子代理，由 Jev 为每项任务选择执行模型和具体工具。
+
+npm 包名为 `@cr1ms0n/pi-subagent`。本项目是 Luke Parke 的 `@parke.dev/pi-subagent` 0.8.0 的独立社区分支，上游来自 [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent)，并非上游官方发行版。原始 MIT 许可证和版权声明均予以保留。
+
+上游扩展提供子进程引擎、命名代理、后台任务、工作树和用量统计。本分支增加了强制 Jev 模型与工具选择，并在发送任务前核验子进程实际采用的模型和工具权限。
+
+---
+
+<a id="quick-start"></a>
+### 安装与快速开始
+
+需要 Node.js 22.19.0 或更高版本，以及已安装、已配置可用模型提供方的 Pi CLI。Pi 0.86.0 是已验证的宿主基线，能够执行内置工具、扩展工具和延迟注册工具的允许列表。若宿主无法核验所选能力，扩展会拒绝启动，不会扩大工具权限。
+
+**1. 安装已发布的软件包。**
+
+安装精确的 `0.10.0` 版本。较早的 `0.9.0` 使用旧的 `apiKeyEnv` 配置契约，不接受 `apiKey`：
+
+```bash
+pi install npm:@cr1ms0n/pi-subagent@0.10.0
+```
+
+Pi 会直接加载这个软件包。不要同时启用本扩展的其他副本或 `@parke.dev/pi-subagent`，它们会注册同名工具。本包提供 `subagent`、`subagent_wait`、`/subagents`、`/subagent-cost` 和 `/btw`。
+
+**2. 将 TypeSafe 凭据保存到私有配置。**
+
+在用户级 `~/.pi/subagent.json` 中设置 `jevRouting.apiKey`，格式如下。如果从 `0.9.0` 升级，请在启动新任务前将 `jevRouting.apiKeyEnv` 中的现有值移到 `jevRouting.apiKey`，并删除旧字段。不要把密钥放进聊天或仓库文件。配置文件以明文保存密钥，需要限制文件访问权限并保护备份。迁移与安全说明见[凭据配置](docs/REFERENCE.md#credential-setup)。子模型所需的提供方认证需要另行在 Pi 中配置。
+
+**3. 配置候选模型。**
+
+将下面的配置加入 `~/.pi/subagent.json`，保留其他已有设置。把示例模型 ID 替换为当前 Pi 中可用的精确 `provider/model-id`，并自行描述模型特点。如果存在旧的 `modelPolicy` 配置，需要将其移除；扩展不会自动迁移。
+
+```json
+{
+  "jevRouting": {
+    "selectorModel": "jev-latest",
+    "apiKey": "<your-typesafe-api-key>",
+    "timeoutMs": 15000,
+    "models": [
+      {
+        "model": "<provider/model-id>",
+        "description": "Describe this model's strengths and the tasks you want it to handle."
+      }
+    ]
+  }
+}
+```
+
+将 `apiKey` 占位符替换为自己的 TypeSafe 密钥，并移除旧的 `apiKeyEnv` 字段。扩展不会回退读取环境变量，也不会自动迁移。模型描述可以使用中文。可选的 thinking 默认值、profile 默认值和限制见[配置参考](docs/REFERENCE.md#configuration)。
+
+Jev 选择可能产生 TypeSafe 费用。它会接收委派任务文本、模型 ID 与描述、候选工具名称与描述，以及必要约束；不会自动上传仓库文件或对话历史，但任务中主动包含的文本仍可能泄露敏感信息。`action: "plan"` 同样会调用 Jev，之后实际执行时还会重新选择。
+
+**4. 启动 Pi，委派一个只读任务。**
+
+启动 Pi；如果刚切换扩展代码，需要重新加载或重启。加载 `0.10.0` 后，每次新任务都会重新读取配置，修改 `apiKey` 不需要更新 shell 环境变量。
+
+```bash
+pi
+```
+
+让主代理使用 `subagent`，例如传入下面的请求：
+
+```json
+{
+  "task": "Read README.md and summarize what this package does.",
+  "description": "Summarize the README",
+  "profile": "explore",
+  "tools": ["read"],
+  "max_turns": 4,
+  "timeout_ms": 120000,
+  "max_retries": 0
+}
+```
+
+不要传入 `model` 或 `fallback_models`。Jev 从配置的模型列表和允许的工具中进行选择；路由失败会阻止本次新任务启动，不会改用兜底方案。已有任务的管理操作不依赖路由凭据。
+
+---
+
+<a id="delegation"></a>
+### 任务委派
+
+- **模型与工具路由：**本分支让 Jev 根据任务和模型描述进行匹配，逐个选择工具；本地权限检查和子进程启动核验负责落实选择结果。
+- **命名代理与并行工作：**上游引擎支持可复用的代理角色和并发子进程。本分支为每个新子代理执行 Jev 路由，代理文件不能固定其模型或工具选择。
+- **后台任务：**上游引擎支持状态查询、可中断等待、取消和中途指导。本分支会显示所选模型，并在展开结果中展示工具详情。
+- **隔离修改：**上游工作树机制支持检查、应用或丢弃改动，避免并行代理共用同一个可写工作区。
+- **结构化结果与预算：**上游引擎在父进程中校验结构化输出，并保留部分工作成果。本分支始终使用已选定的模型和工具集进行重试，单独统计选择器 token。
+
+后台任务设置 `async: true`，之后使用 `subagent_wait` 或 `action: "wait"` 收取结果。中断等待或等待超时不会取消子代理，需要停止任务时使用 `action: "cancel"`。通过 `/subagents` 检查任务，通过 `/subagent-cost` 查看用量。
+
+[使用参考](docs/REFERENCE.md#quick-usage)涵盖并行任务、结果汇总、恢复与分叉、结构化输出、预算，以及工作树的 diff/apply/discard 操作。[TUI 指南](docs/UX.md)介绍任务查看器和键盘操作。
+
+---
+
+<a id="permissions-and-costs"></a>
+### 权限与费用
+
+| Profile | 工具选择 | 修改项目文件 |
+| --- | --- | --- |
+| `explore` | Jev 选择的本地允许的只读工具，加上可用的 Pi 上下文控制工具 | 不允许 |
+| `review` | 与 explore 相同的只读策略 | 不允许 |
+| `general` | Jev 选择的本地允许的工具，加上可用的 Pi 上下文控制工具 | 选中可写工具时可以修改 |
+
+单任务默认使用 `general`，并行任务默认使用 `explore`。显式传入的 `tools` 列表限定候选工具范围。即使传入 `tools: []`，本地仍会补充可用的 Pi 上下文管理工具。工具选择为空绝不表示允许所有工具。
+
+Profile 是工具选择策略，不是操作系统沙箱。子进程继承主进程环境，也能读取同一用户有权访问的文件，包括私有配置。工作树只隔离代码工作区。委派不可信任务前，请阅读[安全模型](docs/SECURITY.md)。
+
+用量账本分别记录主代理、子代理、路由和合计用量。TypeSafe 只报告路由 token，不报告金额，因此选择器费用标记为**未报告**，不代表免费。`max_cost` 限制子代理执行时由提供方报告的费用，不限制 TypeSafe 费用。结果交付、重试和会话分支的统计规则见[费用统计](docs/COST-ACCOUNTING.md)。
+
+扩展管理的新任务只支持 Pi 后端，原生 Codex/Claude 后端请求会被拒绝。[底层 SDK](docs/REFERENCE.md#using-the-runner-as-a-library)是另一套显式任务规格 API，不会自动调用 Jev，嵌入方需要自行负责模型和工具选择。
+
+---
+
+<a id="development"></a>
+### 开发
+
+源码是使用 peer dependencies 的独立 TypeScript 包，没有构建步骤，也没有随仓库提供的测试运行器或类型检查脚本。本仓库支持的检查方式见[开发与验证](docs/DEVELOPMENT.md)。语法转换不等于语义类型检查；`npm pack --dry-run --ignore-scripts --json` 用于检查打包内容，不会发布包。
+
+[架构约定](docs/ARCHITECTURE.md)记录模块职责和不变量。[发布维护](docs/RELEASING.md)说明如何选择性更新源码，以及需要单独明确授权的 npm 发布流程。
+
+---
+
+<a id="license"></a>
+### 许可证
+
+[MIT](LICENSE)。Copyright (c) 2026 Luke Parke。社区分支由 cr1ms0n（awoaCrim）维护。重新分发时请保留原始版权声明和许可证。
+
+译自 [README.md](README.md)，英文文件 blob：`02294faabd946a50be23551e43e694451628bc39`。中英文内容如有差异，以英文为准。
+
+感谢 [Linux.do](https://linux.do/)。

package/docs/ARCHITECTURE.md

@@ -12,9 +12,10 @@
   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.
+- 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.
@@ -26,10 +27,20 @@
   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.
+- `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.
+- `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
@@ -65,7 +76,9 @@ Invariants:
 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.
+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,
@@ -96,10 +109,10 @@ Invariants:
     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.
+    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
@@ -120,6 +133,36 @@ Invariants:
     `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.
+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.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,124 @@
+# Development and verification
+
+This is a standalone ESM TypeScript package loaded by Pi, not the upstream monorepo. Start with the [README](../README.md) for installation and the [architecture contract](ARCHITECTURE.md) before changing engine behavior.
+
+---
+
+### Checkout and runtime
+
+[package.json](../package.json) declares Node.js 22.19.0 or newer and Pi/TypeBox peer dependencies. There is no compiled distribution or build step. The extension entry is [extensions/subagent.ts](../extensions/subagent.ts); the supported SDK exports are in [src/index.ts](../src/index.ts).
+
+To use a local checkout, replace the example path with your own:
+
+```bash
+pi install /absolute/path/to/pi-smart-subagents
+```
+
+Pi registers a local path without copying it. Do not enable that checkout and another copy of the same extension together. Reload or restart Pi after package changes. Keep user settings, provider credentials and real session files outside the repository.
+
+The product skill at [skills/subagent/SKILL.md](../skills/subagent/SKILL.md) is distributed with the package. Maintainer-specific agents, workflows, task records and local verification artifacts are not required to use or inspect the public source.
+
+---
+
+### Source ownership
+
+| Responsibility | Owner |
+| --- | --- |
+| Pi registration and lifecycle wiring | [extension.ts](../src/extension.ts) |
+| Request schema, permission checks and normalization | [schema.ts](../src/schema.ts), [policy.ts](../src/policy.ts), [config.ts](../src/config.ts), [agents.ts](../src/agents.ts) |
+| Jev transport, candidate policy and dispatch | [routing-types.ts](../src/routing-types.ts), [routing-policy.ts](../src/routing-policy.ts), [jev-router.ts](../src/jev-router.ts), [dispatch-routing.ts](../src/dispatch-routing.ts) |
+| Local preflight and child capability verification | [dispatch-preflight.ts](../src/dispatch-preflight.ts), [startup-check.ts](../src/startup-check.ts), [child-preflight.ts](../src/child-preflight.ts) |
+| Child processes, retries and protocol | [runner.ts](../src/runner.ts), [orchestrator.ts](../src/orchestrator.ts), [protocol.ts](../src/protocol.ts), [backend adapters](../src/backends/) |
+| Concurrency, ownership and durable worktrees | [semaphore.ts](../src/semaphore.ts), [process-lock.ts](../src/process-lock.ts), [registry.ts](../src/registry.ts), [worktree.ts](../src/worktree.ts) |
+| Persistence, accounting and output | [persistence.ts](../src/persistence.ts), [usage.ts](../src/usage.ts), [output.ts](../src/output.ts), [structured.ts](../src/structured.ts) |
+| TUI, notifications and transcript display | [format.ts](../src/format.ts), [ui.ts](../src/ui.ts), [notifications.ts](../src/notifications.ts), [transcript.ts](../src/transcript.ts) |
+
+Keep engine rules in their owning modules. The extension is a composition root, and renderers consume narrow projections rather than owning a second run store. The architecture document covers the remaining modules and invariants.
+
+---
+
+### Checks available in this checkout
+
+There are no npm scripts, devDependencies, TypeScript project configuration or bundled test suite. `npm test`, `npm run typecheck` and the upstream release-check scripts are not available here. Installing dependencies alone does not create those commands. The historical [plan](PLAN.md) and [roadmap](ROADMAP.md) refer to upstream tooling and previous release work.
+
+#### Documentation and whitespace
+
+Review the English and Chinese READMEs together: commands, config keys, feature claims, language links, anchors and license references must agree. Check links against the intended public Git tree, not only files that happen to exist in a maintainer's checkout. Keep the English-source blob reference in the Chinese README current when changing the translation.
+
+For tracked changes:
+
+```bash
+git diff --check
+```
+
+For a prepared commit:
+
+```bash
+git diff --cached --check
+```
+
+These commands do not check Markdown links, translation accuracy or untracked files. Review those separately. Documentation-only changes do not require a provider call or a claim that engine tests passed.
+
+#### Offline TypeScript syntax check
+
+When the global Pi installation includes esbuild, the following Bash/Git Bash command enumerates production TypeScript files, parses and strips their types, and writes only to a unique temporary directory. It removes that directory afterward. It does not download a tool or modify source files.
+
+```bash
+node --input-type=module - "$(npm root -g)" <<'NODE'
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const esbuild = path.join(process.argv[2], "@earendil-works/pi-coding-agent/node_modules/esbuild/bin/esbuild");
+if (!fs.existsSync(esbuild)) throw new Error("Global Pi esbuild is unavailable; no syntax check was run.");
+const files = [];
+function walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(file);
+    else if (file.endsWith(".ts")) files.push(file);
+  }
+}
+walk("src");
+walk("extensions");
+const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-syntax-"));
+try {
+  for (const file of files.sort()) {
+    const result = spawnSync(process.execPath, [esbuild, file, "--loader:.ts=ts", "--format=esm",
+      "--target=node22", `--outfile=${path.join(outputDir, "check.js")}`], { stdio: "inherit" });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(`Syntax transform failed for ${file}`);
+  }
+  process.stdout.write(`Parsed ${files.length} TypeScript files; no semantic typechecking performed.\n`);
+} finally {
+  fs.rmSync(outputDir, { recursive: true, force: true });
+}
+NODE
+```
+
+This catches malformed TypeScript only. It does not resolve imports, check types or validate peer APIs. If your Pi installation does not expose that esbuild path, report the missing check rather than claiming success or installing new tooling silently.
+
+A semantic typecheck requires a separately configured TypeScript environment and compatible peers. There is no repository-owned command for it here. Any external harness or isolated fixture run must be reported with its actual setup, scope and limitations; private maintainer fixtures are not a test suite shipped in this checkout.
+
+#### Package contents
+
+Review the npm file list without generating or publishing a tarball:
+
+```bash
+npm pack --dry-run --ignore-scripts --json
+```
+
+The output should contain production source, the distributed skill, public documentation, both READMEs, changelog, license and package metadata. It must not contain local settings, agent instructions, tasks, backups, transcripts, credentials, tarballs or generated test bundles. Git exclusions and the package `files` allowlist are separate controls; inspect both when changing packaging.
+
+A dry run verifies packaging, not application behavior. For an actual release, follow the additional artifact and installation checks in [release maintenance](RELEASING.md).
+
+---
+
+### Behavior verification
+
+For engine changes, trace the affected architecture invariants and exercise the owned boundary with an injected transport, fake process or isolated host when such a harness is available. State what was exercised and keep paid partial output/accounting semantics intact.
+
+A real `subagent` call and `action: "plan"` both invoke Jev and may incur charges. A plan avoids spawning a child; it is not an offline test. Obtain explicit permission before live routing/provider smoke tests, use synthetic task data and keep real user sessions out of fixtures.
+
+Report syntax transforms, semantic typechecks, package checks, fixture assertions and live-provider checks separately. Do not summarize them as “tests passed” when no test suite was run.

package/docs/PLAN.md

@@ -1,5 +1,7 @@
 # Execution plan — remaining roadmap phases
 
+> **Historical upstream plan.** Retained as design rationale for phases that shipped before this fork's Jev routing changes. Version targets, test paths and `npm run release:check` below describe the upstream monorepo, not tools available in this standalone checkout. See [the current reference](REFERENCE.md), [architecture contract](ARCHITECTURE.md) and [development checks](DEVELOPMENT.md) for the maintained behavior and verification instructions. Historical gate statements are not verification results for the current checkout.
+
 Formalization of [ROADMAP.md](./ROADMAP.md) phases 2–4 into implementable work
 items. Where the roadmap holds rationale and design sketches, this document
 holds the execution contract: exact scope, file-level work breakdown,