@cr1ms0n/pi-subagent 0.9.0 → 0.11.0

package/README.zh-CN.md

@@ -0,0 +1,42 @@
+# Pi Smart Subagents
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+在 [Pi](https://pi.dev/) 中运行独立子代理，由 Jev 为每项任务选择模型和工具。
+
+本项目是 Luke Parke 的 `@parke.dev/pi-subagent` 的独立社区分支，上游来自 [LukasParke/pi-extensions](https://github.com/LukasParke/pi-extensions/tree/main/packages/pi-subagent)。保留上游的命名代理、并行与后台任务、工作树和用量统计，增加 Jev 路由与子代理能力核验。
+
+---
+
+<a id="quick-start"></a>
+### 安装
+
+```bash
+pi install npm:@cr1ms0n/pi-subagent
+```
+
+---
+
+<a id="delegation"></a>
+### 使用
+
+首次使用前，在 `~/.pi/subagent.json` 中配置 TypeSafe API key 和候选模型，见[配置示例](docs/REFERENCE.md#jev-routing)。
+
+然后直接对 Pi 说，例如：
+
+> 用只读子代理查看这个项目的目录结构，并总结主要模块。
+
+Jev 会选择模型和工具。使用 `/subagents` 查看任务，使用 `/subagent-cost` 查看用量。
+
+并行任务、后台执行、工作树和结构化结果见[使用参考](docs/REFERENCE.md#quick-usage)，键盘操作见 [TUI 指南](docs/UX.md)。
+
+---
+
+<a id="license"></a>
+### 许可证
+
+[MIT](LICENSE)。Copyright (c) 2026 Luke Parke。社区分支由 cr1ms0n（awoaCrim）维护。重新分发时请保留原始版权声明和许可证。
+
+译自 [README.md](README.md)，英文文件 blob：`f55b496dc010bd4242e6f6ffc8c987425ee9d7f4`。中英文内容如有差异，以英文为准。
+
+感谢 [Linux.do](https://linux.do/)。

package/docs/ARCHITECTURE.md

@@ -12,10 +12,7 @@
   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.
+- Retry lives in [orchestrator.ts](../src/orchestrator.ts). Ranked extension tasks advance through a locally finalized Jev candidate plan only for recognized settled availability failures before any current-invocation tool starts. [model-failover.ts](../src/model-failover.ts) owns conservative evidence classification and bounded attempt helpers. Tools stay fixed, thinking resolves per candidate, and usage accumulates once. Unknown execution evidence blocks restart. The trusted unranked SDK retains its separate `isTransientFailure` and explicit fallback contract.
 - `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.
@@ -24,7 +21,7 @@
 - `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.
+  identity records for orphan reconcile. Ranked tasks keep one record running across attempts and final artifact/worktree work; the orchestrator terminalizes it once. A bounded list of attempt sessions protects earlier transcripts from other parents' maintenance while the task is live.
 - `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
@@ -38,14 +35,12 @@
   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.
+  response validation, deadlines and per-request receipts, including a validated full probability ranking and model-independent task tool decisions; `dispatch-routing.ts` resolves every worker before any launch and refuses a partially selected fanout. Local policy finalizes a frozen candidate attempt plan with per-model thinking and one shared tool set. 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.
+  validation and runs one steer-based repair round after an otherwise successful invalid answer. Ranked provider-error/aborted attempts skip repair and cannot publish structuredOutput from failed text. The latest completed assistant text replaces earlier text even when empty, so a host retry cannot reuse the failed turn's JSON.
 - `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
@@ -80,7 +75,7 @@ Invariants:
     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.
+    Full transcripts and final output are persisted exactly once, in the terminal event. Ranked attempt histories carry bounded metadata/session pointers at checkpoints, with output previews only in terminal projections (1 KiB per preview, 16 KiB total). Active-branch retention includes earlier attempt session references.
 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
@@ -108,18 +103,14 @@ Invariants:
 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.
+21. Extension-managed ranked tasks permit at most `maxRetries` extra child attempts, locally capped at 255 total launches. A recognized settled availability failure advances to the next candidate only with conclusive no-tool activity; started or unknown activity blocks all new-child restart. Candidate exhaustion never wraps to the primary. Conclusively pre-work infrastructure retry may repeat the same candidate within the same budget. No retry calls Jev or broadens tools. Usage and budget comparisons include prior attempts. Authentication, quota/billing, invalid requests, context limits, task-quality, cancellation, task-deadline and budget stops do not cause model failover. The trusted unranked SDK keeps its legacy transient/explicit-fallback behavior.
 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.
+    the child. A stall does not authorize restart on the ranked path: silence cannot establish that no work began.
 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.
+    suppresses the notification. The actual final model and a bounded attempt-chain tail with its total count use the same display projection as compact results.
 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
@@ -137,11 +128,9 @@ Invariants:
     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`,
+29. Every new extension-managed invocation (`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`
+    interface before any child starts. The dedicated candidate list intersected with locally available models is the only source of execution models. One validated full probability ranking belongs to the invocation, and fallback reuses it without another selection. The original selectedModel/confidence remain immutable; result.model reports the actual attempt. The full locally permitted tool catalog is the only tool candidate source, and one model-independent selection is shared by every attempt. 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
@@ -154,13 +143,12 @@ Invariants:
     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.
+    mismatched acknowledgement is a capability/startup diagnostic, never compensated by broadening tools or choosing another model. Every ranked replacement gets its own exact-model/shared-tools acknowledgement before the task prompt.
 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.
+    launch into a replaced session. Replacement attempts await prior child cleanup, retain run/worktree/resume ownership and recheck cancellation, deadline and cumulative task budgets before launch. Durable task records remain running during replacement and finalization, protecting all known attempt sessions and the worktree across parent processes; only child slots are released per attempt. Pi/provider internal retries and global retry settings remain unchanged.
 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

package/docs/COST-ACCOUNTING.md

@@ -44,9 +44,7 @@ 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,
+original selected model, ranked candidate probabilities, shared selected tools, locally added control-plane tools, confidence, success outcome, latency and receipt IDs) travels with the run and both registry projections. Actual attempt models are recorded separately; fallback never rewrites the initial selection as a new decision. 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
@@ -79,10 +77,7 @@ Because the native footer counts parent assistant messages plus delivered tool-r
 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.
+7. Ranked failover and permitted same-model pre-work retries accumulate into one run usage record. Every attempt's provider-reported usage counts once under the same run UUID; attempted-model metadata is descriptive, not another ledger input. Advancing to a ranked candidate makes no additional selector request and creates no new receipt. The initial selector decision remains distinct from the actual execution model.
 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
@@ -106,6 +101,10 @@ Only `sessionManager.getBranch()` is used. Costs from abandoned sibling branches
 
 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.
 
+All ranked attempts share the absolute task deadline and cumulative `max_cost`/`max_turns` budget. Prior usage is an offset for the next child's budget comparisons, not part of that child's returned usage, so aggregation adds each attempt only once. A replacement cannot start after reported cost or turns meets its ceiling. In-attempt completed-turn checks and wrap-up grace remain unchanged. Pi's internal provider retries are not counted as separately launched extension attempts.
+
+When every attempt fails, earlier output previews retain their originating model/session and the final task remains failed. Preserving billed work does not convert failure into `partial` or success. The existing native undercount for thrown failures still applies; the extension ledger retains all reported attempt usage.
+
 ## Provider limitations
 
 Accounting is only as precise as the provider data normalized by Pi:

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,