@cr1ms0n/pi-subagent 0.9.0 → 0.10.0

package/docs/REFERENCE.md

@@ -0,0 +1,436 @@
+# Usage and configuration reference
+
+Return to the [English README](../README.md) or [Chinese README](../README.zh-CN.md) for installation. This reference documents the extension-managed Jev path and the separate explicit-spec SDK. The underlying subagent engine comes from Luke Parke's upstream extension; Jev routing and startup capability verification are additions in this fork.
+
+---
+
+### Credential setup
+
+Version `0.10.0` reads the TypeSafe key from `jevRouting.apiKey` in your private, user-level `~/.pi/subagent.json`. Set the key locally using an editor, preserve unrelated configuration and replace the placeholder in the [routing example](#jev-routing). Do not paste the key into chat, shell commands, source control or task descriptions.
+
+This file stores the credential in plaintext. Restrict access to your user account and protect editor backups and synchronized copies. Same-user processes, including children with filesystem access, may read it; neither profiles nor worktrees provide an OS sandbox. See [SECURITY](SECURITY.md#routing-disclosure-and-credentials).
+
+When upgrading from published npm `0.9.0`, remove `apiKeyEnv` and add `apiKey` with the actual key locally. The old field is rejected even if both fields are present. There is no environment fallback, automatic migration or default key. Published `0.9.0` still requires its older `apiKeyEnv` setup, while `0.10.0` uses the config-file credential contract.
+
+Reload or restart Pi after changing extension code. Subsequent dispatches re-read the config file, so a later key edit does not require setting an environment variable. Provider credentials for execution models are configured independently using Pi's own authentication mechanisms. Rotate credentials exposed in source, logs or conversation.
+
+---
+
+### Quick usage
+
+These are request objects for the `subagent` tool, not shell commands. New work calls Jev; omit `model` and `fallback_models`.
+
+#### Foreground and named agents
+
+Use an explicit read-only profile for exploration. Single tasks otherwise default to `general`.
+
+```json
+{
+  "task": "Find all call sites of parseConfig and summarize patterns.",
+  "description": "Map parseConfig usage",
+  "profile": "explore"
+}
+```
+
+A named agent supplies a persona and non-model defaults; Jev still chooses the model and tools.
+
+```json
+{
+  "task": "Review this diff for security issues.",
+  "agent": "reviewer",
+  "profile": "review"
+}
+```
+
+#### Parallel tasks and synthesis
+
+Parallel tasks default to `explore`. Optional synthesis starts an additional read-only child and has its own routing selection. Raw worker results remain available if synthesis fails.
+
+```json
+{
+  "tasks": [
+    { "task": "Audit backend error handling.", "description": "Backend audit" },
+    { "task": "Audit frontend error handling.", "description": "Frontend audit" }
+  ],
+  "synthesis": "Merge both audits into one prioritized findings list."
+}
+```
+
+Omit `synthesis` when you only need the separate worker reports.
+
+#### Background work and collection
+
+Start a background run and keep its returned run ID:
+
+```json
+{ "task": "Audit dependency licenses.", "profile": "review", "async": true }
+```
+
+Inspect without consuming the deliverable:
+
+```json
+{ "action": "status", "id": "<run-id>" }
+```
+
+Collect the result with the same tool:
+
+```json
+{ "action": "wait", "id": "<run-id>" }
+```
+
+Or pass this request to `subagent_wait`, which delegates to the same collection handler:
+
+```json
+{ "id": "<run-id>", "timeout_ms": 30000 }
+```
+
+An interrupted or timed-out wait does not cancel or consume a still-running task. Cancel it explicitly when needed:
+
+```json
+{ "action": "cancel", "id": "<run-id>" }
+```
+
+#### Inspect a paid plan
+
+A plan runs local preflights and Jev selection without spawning a child or creating a run entry. It can incur selector fees; a later dispatch selects again. It checks the same model/tool/budget/isolation resolution as a launch.
+
+```json
+{
+  "action": "plan",
+  "tasks": [
+    { "task": "Implement feature A.", "profile": "general", "isolation": "worktree" }
+  ]
+}
+```
+
+#### Structured output
+
+The child must produce a fenced `json:result` block matching the requested schema. The parent validates it and allows one repair round. An unresolved schema failure preserves raw output as a partial result rather than discarding paid work.
+
+```json
+{
+  "task": "Audit the auth module.",
+  "profile": "review",
+  "output_schema": {
+    "type": "object",
+    "required": ["findings", "risk"],
+    "properties": {
+      "findings": { "type": "array", "items": { "type": "string" } },
+      "risk": { "type": "string", "enum": ["low", "medium", "high"] }
+    }
+  }
+}
+```
+
+#### Resume, fork and steering
+
+A fork starts from a branch of the persisted parent conversation. It is single-task only:
+
+```json
+{ "task": "Implement the plan we agreed on.", "context": "fork", "profile": "general" }
+```
+
+Find a resumable child session ID in status, then start a new invocation:
+
+```json
+{ "task": "Continue from your findings and propose a fix plan.", "resume": "<session-id>" }
+```
+
+Both operations select again. To guide an existing child instead, steer it; parallel runs use `index` to select the worker:
+
+```json
+{ "action": "steer", "id": "<run-id>", "index": 0, "message": "Skip tests; focus on src and wrap up." }
+```
+
+#### Budgets and retries
+
+A budget breach requests a final answer and allows the configured grace turns. Transient failures retry the already selected model and tool set; they never trigger reselection or fallback models.
+
+```json
+{ "task": "Audit dependencies.", "profile": "review", "max_turns": 15, "grace_turns": 2, "max_retries": 1 }
+```
+
+#### Isolated writers
+
+Use separate worktrees for parallel changes:
+
+```json
+{
+  "tasks": [
+    { "task": "Implement feature A.", "profile": "general", "isolation": "worktree" },
+    { "task": "Implement feature B.", "profile": "general", "isolation": "worktree" }
+  ]
+}
+```
+
+Inspect each finished patch:
+
+```json
+{ "action": "diff", "id": "<run-id>", "index": 0 }
+```
+
+Apply it as uncommitted changes in the parent checkout:
+
+```json
+{ "action": "apply", "id": "<run-id>", "index": 0 }
+```
+
+Discard an unwanted worktree and branch:
+
+```json
+{ "action": "discard", "id": "<run-id>", "index": 1 }
+```
+
+The `/subagents` overlay provides the same loop: `s` to steer, `a` to apply and `x` to discard.
+
+---
+
+### Side questions (`/btw`)
+
+Ask a side question in Pi:
+
+```text
+/btw does this repo have a rate limiter?
+```
+
+Or open the question prompt:
+
+```text
+/btw
+```
+
+`/btw` runs a one-off read-only subagent for _you_, not for the model. It uses the same policy, budget, semaphore and process-lock machinery as any run, but delivers its answer as a custom session entry, which does not participate in LLM context. The main agent keeps working and never sees the question or the answer; useful for checking something mid-task without derailing the conversation or polluting the context window.
+
+---
+
+### Backends
+
+Jev routing manages Pi-backed new dispatch only. A `backend: "codex"` or `backend: "claude"` new task is refused before any selector or provider work, including a backend inherited from agent frontmatter; the extension never silently switches it to Pi. Existing Codex/Claude runs stay manageable: `status`, `wait`, `cancel`, `steer`, `diff`, `apply` and `discard` all still work. Provider diversity is not lost, because another provider's execution model stays eligible through Pi once it is in your configured candidate list.
+
+The following new-work request is refused; use the Pi-backed path instead:
+
+```json
+{ "task": "Summarize this module", "backend": "codex", "profile": "explore" }
+```
+
+The low-level SDK is a different contract: `runTasks`/`runSubagent` execute the explicit `TaskSpec` you hand them, so embedding code can still select a backend directly. Everything else (worktrees, process locks, depth limits, budgets, orphan reclaim) is backend-agnostic and applies unchanged.
+
+Capabilities differ, and **unsupported combinations are refused with an explanation rather than silently ignored**: a dropped `max_cost` or unenforced read-only profile would be a safety regression, not a minor degradation.
+
+|                                 | `pi` (default) | `codex`                               | `claude`               |
+| ------------------------------- | -------------- | ------------------------------------- | ---------------------- |
+| `max_cost`                      | yes            | **refused** (reports tokens, no cost) | yes (`total_cost_usd`) |
+| read-only profile               | tool allowlist | `--sandbox read-only` (OS-level)      | `--allowedTools`       |
+| steering / graceful wrap-up     | yes            | **no** (no stdin channel)             | **no** (one-shot)      |
+| `resume`                        | yes            | yes                                   | yes                    |
+| `context:'fork'`, `fork_resume` | yes            | **refused**                           | yes                    |
+| `thinking`                      | yes            | no                                    | no                     |
+| `output_schema`                 | yes            | yes                                   | yes                    |
+
+A budget breach on a backend without steering hard-stops instead of asking the child to wrap up. Codex's read-only sandbox is enforced by the OS, which is stronger than a tool allowlist.
+
+Agent frontmatter `backend:` remains a default. New extension-managed work rejects any effective backend other than Pi, including a native backend inherited from an agent. Direct SDK specs retain the backend capabilities listed above.
+
+---
+
+### Profiles
+
+| Profile                      | Tools                                                   | Writes                                      |
+| ---------------------------- | ------------------------------------------------------- | ------------------------------------------- |
+| `explore` (parallel default) | Jev-selected subset of locally permitted read-only candidates + available Pi context tools | no project-file writes |
+| `review`                     | same as explore                                         | no project-file writes                      |
+| `general`                    | Jev chooses from the full available locally permitted catalog + Pi context tools | yes for selected write-capable tools; unknown custom tools count as writable |
+
+Jev chooses individual tool names, not a capability bundle. Candidates come from the full available locally permitted catalog, not from the agent file's `tools` defaults and not from the parent's currently active tools. An explicit task `tools` list is a ceiling, and explore/review keep their read-only rule regardless of what the selector returns. An empty selection never means "all tools".
+
+For the Pi backend, the context-management tools `new_context`, `get_context_remaining`, `history`, and `notes` are added locally when the parent exposes them, so they are never a selector question. They are control-plane tools: they may update continuity notes or the remote context window, but cannot modify the child checkout or run a shell command. This exception also applies when a task supplies a narrower tool list, so Pi's `contextManagement` remains usable for configured gateway models. Locally added controls are reported in the route metadata.
+
+The finalized tool set is passed to the child as Pi's `--tools` allowlist (`--no-tools` for a true empty set). Pi 0.86.0 is the verified baseline for built-in, extension and late-registered tool enforcement; a host that cannot honor that allowlist is refused rather than silently weakened, and the extension does not claim identical behavior on untested older releases. Before the real task prompt is sent, the child is also asked to confirm the selected model and the finalized tool names through a verified private startup command; if the host cannot verify that command or the child cannot confirm both, the launch aborts with a startup diagnostic instead of running with a broader tool set.
+
+Parallel write-capable tasks sharing one checkout are rejected unless each uses `isolation: "worktree"`, distinct `cwd`, or explicit `allow_shared_writes: true`.
+
+---
+
+### Configuration
+
+Defaults can be overridden in `~/.pi/subagent.json` and per-field via env vars (env wins over file):
+
+| Setting                 | Env var                               | Default                               |
+| ----------------------- | ------------------------------------- | ------------------------------------- |
+| `maxTasksPerRun`        | `PI_SUBAGENT_MAX_TASKS`               | 8                                     |
+| `maxActiveProcesses`    | `PI_SUBAGENT_MAX_ACTIVE`              | 4                                     |
+| `maxQueuedTasks`        | `PI_SUBAGENT_MAX_QUEUED`              | 32                                    |
+| `maxGlobalActive`       | `PI_SUBAGENT_MAX_GLOBAL_ACTIVE`       | 16                                    |
+| `defaultTimeoutMs`      | `PI_SUBAGENT_TIMEOUT_MS`              | 900000                                |
+| `maxDepth`              | `PI_SUBAGENT_MAX_DEPTH`               | 2                                     |
+| `killGraceMs`           | `PI_SUBAGENT_KILL_GRACE_MS`           | 3000                                  |
+| `sessionDir`            | `PI_SUBAGENT_SESSION_DIR`             | `~/.pi/subagent-sessions`             |
+| `worktreeDir`           | `PI_SUBAGENT_WORKTREE_DIR`            | `~/.pi/subagent-worktrees`            |
+| `lockDir`               | `PI_SUBAGENT_LOCK_DIR`                | `~/.pi/subagent-locks`                |
+| `worktreeRetentionDays` | `PI_SUBAGENT_WORKTREE_RETENTION_DAYS` | unused (lifecycle GC)                 |
+| `sessionRetentionDays`  | `PI_SUBAGENT_SESSION_RETENTION_DAYS`  | unused (lifecycle GC)                 |
+| `lockRetentionDays`     | `PI_SUBAGENT_LOCK_RETENTION_DAYS`     | 7                                     |
+| `taskDefaults`          | -                                     | none                                  |
+| `jevRouting`            | -                                     | required for new dispatch (see below) |
+| `graceTurns`            | `PI_SUBAGENT_GRACE_TURNS`             | 2                                     |
+| `stallAfterMs`          | `PI_SUBAGENT_STALL_AFTER_MS`          | 90000                                 |
+| `stallKillAfterMs`      | `PI_SUBAGENT_STALL_KILL_AFTER_MS`     | 90000                                 |
+| `maxRetries`            | `PI_SUBAGENT_MAX_RETRIES`             | 1                                     |
+| `widget`                | `PI_SUBAGENT_WIDGET`                  | `background` (`off` disables)         |
+| `notifications`         | `PI_SUBAGENT_NOTIFICATIONS`           | `batched` (`off` disables)            |
+| (bin)                   | `PI_SUBAGENT_BIN`                     | auto (`process.execPath` + CLI entry) |
+
+#### Jev routing
+
+New subagent dispatches are selected by Jev, TypeSafe's structured-decision API, against a dedicated candidate list you maintain in `~/.pi/subagent.json`. Fixed routing is gone: a `modelPolicy` block produces a migration error, and an explicit `model` or `fallback_models` on new work is rejected rather than bypassing selection. Management actions (`status`, `wait`, `cancel`, `steer`, `diff`, `apply`, `discard`) never call the selector and need no credential.
+
+```json
+{
+  "jevRouting": {
+    "selectorModel": "jev-latest",
+    "apiKey": "<your-typesafe-api-key>",
+    "timeoutMs": 15000,
+    "models": [
+      {
+        "model": "<provider/model-id>",
+        "description": "<your characteristics notes, Chinese allowed>"
+      }
+    ]
+  }
+}
+```
+
+- `selectorModel` defaults to the stable alias `jev-latest`. Pin an exact version to control which selector version is requested. This does not guarantee deterministic choices; the extension records the version that actually answered.
+- `apiKey` is required and has no default. It must be a non-blank string; surrounding whitespace is trimmed and embedded whitespace/control characters are rejected. Store it only in the private config file. The transport uses it for the Authorization header and does not copy it into prompts, selector JSON bodies, argv, logs, receipts or results. `apiKeyEnv` is rejected with migration guidance; environment variables cannot supply or override the key.
+- `timeoutMs` defaults to 15000 and must be an integer between 100 and 600000. It bounds one logical task selection, including all its HTTP requests and queue waits. Parallel workers each have a selection allowance, still capped by their absolute task `timeout_ms` deadline. Deferred synthesis has a separate allowance.
+- `models` holds 1 to 255 entries, each with an exact `provider/model-id` and a non-blank description. Those descriptions are what Jev matches against your task, so write them the way you would explain the model to a colleague. `thinking` is optional.
+
+Plan and background-start native usage attachments are limited to 1024 selector HTTP receipts per invocation. Larger requests fail with a request-splitting error; background work has not started at that point. Previously incurred selector tokens remain in the ledger. This bounds an atomic delivery record, not the number of tools Jev may consider within each task.
+
+The candidate list is intersected with the models the local Pi registry reports as available. A configured model Pi cannot resolve is not eligible, and an empty eligible pool fails before any request. Adding a model anywhere else in Pi does not authorize it, and legacy `modelPolicy` entries are never imported automatically. An unknown `jevRouting` field is an error, not a silent default.
+
+Jev receives only the current delegated task text, your model IDs and descriptions, candidate tool names and descriptions, and the permission/output requirements it needs to choose. It does not receive repository files, conversation history, full system prompts, persona text or tool parameter schemas. Task text and descriptions are user content and may contain sensitive material, so treat what you delegate as disclosure to TypeSafe.
+
+Every new extension-managed dispatch routes through Jev: `task`/`tasks[]`, `action:"plan"`, `/btw`, resume, fork, locally permitted nested dispatch and the optional `synthesis` child. `action:"plan"` calls Jev and runs the same local preflights, returns the resolved model/tool plan and the selector usage, and creates no child or run entry. A later dispatch selects again; there is no cached decision to reuse. If optional synthesis selection fails, the worker plan and its usage stay valid and synthesis is reported as blocked with its diagnostic.
+
+`thinking` is optional and is an opaque Pi thinking-level string. Common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`, but the package does not remap or restrict model-specific values. Pi receives the value unchanged and decides whether the active model supports it. Resolution order is: explicit task `thinking` > agent frontmatter `thinking` > profile `taskDefaults.<profile>.thinking` > the selected candidate's optional `thinking` > the parent session's thinking level. Jev never chooses a thinking level.
+
+The extension re-reads `jevRouting` on each dispatch and injects non-secret routing guidance into the parent prompt, never the key. Configuration edits reach the next decision without a code change. Missing or invalid `jevRouting.apiKey`, or other invalid routing configuration, rejects new dispatch and plan with a remedy; management stays available.
+
+The mandatory routing above is the Extension dispatch contract. The stable SDK exports (`runTasks` and `runSubagent`) are trusted low-level library APIs: they execute the explicit `TaskSpec` you pass and perform no implicit routing, config discovery or network call. Library callers own model and tool choice, and must not read these SDK calls as Jev enforcement.
+
+#### Named agent files
+
+Define reusable subagent personas as markdown files, discovered from the same conventional roots skills use (higher root wins name conflicts):
+
+| Priority | Location                                                                | Scope                       |
+| -------- | ----------------------------------------------------------------------- | --------------------------- |
+| 1        | `.pi/agents/<name>.md`                                                  | project (authoritative)     |
+| 2        | `.agents/agents/<name>.md`                                              | shared cross-tool workspace |
+| 3        | `$PI_CODING_AGENT_DIR/agents/<name>.md` (default `~/.pi/agent/agents/`) | global                      |
+
+The markdown body becomes the child's appended system prompt; frontmatter supplies defaults using the same snake_case names as the tool parameters:
+
+```md
+---
+description: Security-focused code reviewer
+# Legacy model/fallback fields are ignored; Jev routing owns model/tool choice.
+thinking: high
+profile: review
+max_turns: 20
+spawns: false # or "*", "scout", "[reviewer, scout]"
+---
+
+You are a security auditor. Review code for injection flaws, auth issues,
+and sensitive data exposure. Report findings with file:line evidence and
+severity ratings.
+
+@include shared/review-checklist.md
+```
+
+Agent files may also pin a structured contract with `output_schema: {"type": "object", …}` (single-line inline JSON) or `output_schema: @contract.json` (path relative to the agent file).
+
+`spawns:` controls which agents a child of this persona may spawn: `false` disables further nesting (no tool registered in that child), `"*"` (or omit) is unrestricted, and a comma/bracket list is an allowlist (agentless tasks are rejected under an allowlist). The policy is passed to the child via `PI_SUBAGENT_SPAWNS` and enforced on each subsequent spawn.
+
+Body lines that consist solely of `@include relative/path.md` expand that file one level deep (relative to the agent file, same 64KB/symlink guards as `@contract.json`). Missing or rejected includes leave the line verbatim; includes do not recurse.
+
+Invoke with `{ task: "…", agent: "reviewer" }`. The agent file supplies persona, capability, thinking and budget defaults only: model and tool selection stay with Jev routing, and a legacy `model`/`fallback_models` in frontmatter is ignored. An explicit `system_prompt` appends after the persona body. Profiles still enforce capability: `profile: review` filters candidates to read-only tools. Legacy agent `tools` defaults are ignored; an explicit task `tools` list requesting write tools under review fails closed. The agent catalog is advertised in the tool's system-prompt guidelines (session start) and in bare `status` output (live), and file changes are picked up within seconds; no restart needed.
+
+#### Per-profile task defaults
+
+`taskDefaults` in `~/.pi/subagent.json` remains available for non-model fields such as thinking, budgets, and retry counts. Its legacy `model` and `fallbackModels` fields are ignored; model and tool routing belong only to `jevRouting`. A profile `thinking` value overrides the selected candidate's optional `thinking` default. Invalid fields are dropped field-by-field.
+
+Notes on behavior:
+
+- `timeout_ms` is the absolute task deadline: local preflight, Jev selection, setup, queue time and runtime all count against it, and selection cannot reset it. Timed-out tasks report `state: "timeout"` with `timeoutPhase: "queued"|"starting"|"running"` so agents can retry capacity issues without confusing them for task failures.
+- Budget stops (`max_turns`, `max_cost`) trigger a **graceful wrap-up**: the child is steered to produce its final answer NOW and allowed `graceTurns` more turns before SIGTERM. Results end as `partial` with `wrappedUp: true` when the child concluded in time. `graceTurns: 0` restores immediate stops.
+- A **stall watchdog** flags children with no protocol activity for `stallAfterMs` (a liveness probe distinguishes quiet-but-thinking from dead), then kills after `stallKillAfterMs` more silence; feeding automatic retry instead of burning the whole timeout.
+- **Transient failures retry automatically** (queue timeouts, stalls, spawn errors, provider errors) up to `maxRetries` extra attempts on the already selected model and tool set. There are no emergency or fallback models, and a quality or budget failure never reselects. Usage accumulates across attempts; results record `attempts`. Task-quality failures (nonzero exit with complete protocol, cancellations, budget stops, running timeouts) never retry.
+- `context: "fork"` starts a single child from a real branched copy of the parent conversation (`--fork` on the parent's session file). It requires a persisted parent session, cannot combine with `resume`, and is rejected for parallel fanout (context duplication × N is a cost bug, not a feature).
+- **Structured output** (`output_schema`): the contract is appended to the child's system prompt; the final message must end with a fenced `json:result` block. Validation runs parent-side against a dependency-free JSON-Schema subset (type/properties/required/items/enum/const; unknown keywords are ignored, never rejected). Invalid output triggers **one steer-based repair round**; still-invalid results end `partial` with `structuredError` set and the raw text delivered; paid work is never discarded. Validated parallel results feed the `synthesis` child as clean JSON instead of prose.
+- **Arg repair**: double-encoded task text (literal `\n` / `\"` escapes from LLM re-encoding) is conservatively de-mangled once at validation time. Identifier fields and paths are never touched. Protocol streams truncated after useful assistant output also end as `partial`.
+- Aborting a `wait` returns immediately without cancelling the background run.
+- Child processes are launched via the same Node runtime + CLI entry as the parent when possible (`PI_SUBAGENT_BIN` overrides). Bare `pi` on PATH is only a logged last resort.
+- Direct resume is exclusive **across processes** via durable locks under `lockDir`. Lost runs block resume until startup orphan reconciliation kills (or confirms dead) the recorded child process group.
+- `maxGlobalActive` bounds concurrent children across every Pi parent process on the machine (in addition to the per-session semaphore).
+- Nested children at the depth ceiling do not re-register the subagent tool; only top-level parents run maintenance/orphan reclaim/worktree GC.
+- Preserved worktrees live under `worktreeDir` (durable, not `/tmp`) and are garbage-collected on startup by **lifecycle**, not wall-clock retention: once a run is over (not live, past a 1h concurrency race guard), the worktree's unique work is archived as one applyable patch under `<repo-container>/_patches/` and the directory is reclaimed immediately. Branches holding commits that exist on no other ref are never deleted. `diff`/`apply`/`discard` transparently fall back to the archived patch when the directory is already gone. Live runs are never swept: the current session's live worktrees plus any worktree recorded on a running run record (concurrent Pi processes) are shielded machine-wide.
+- Startup GC sweeps **every** repo container under `worktreeDir`, not just the current checkout's, so repos you stop visiting are still reclaimed. A container whose base repo no longer exists is kept and reported, never deleted; its worktrees' object stores lived inside the deleted repo, so unique work cannot be distinguished from a pristine checkout, let alone archived. Empty containers (no worktrees, no archived patches) are removed.
+- Child session transcripts are likewise distilled on lifecycle: when a run is over and nothing on the parent branch references its session, the transcript is reduced to a small `.digest.json` (task, final output, model, usage, turn/tool/error counts) and the raw `.jsonl` is deleted. Resume needs the transcript, so anything referenced or busy machine-wide is kept.
+- `keep_background: true` on a task keeps processes the child intentionally backgrounded (e.g. dev servers) alive after a clean exit.
+- `include_wip: true` (with `isolation: "worktree"`) seeds the worktree with the parent checkout's uncommitted changes so the child sees your dirty baseline. `diff`/`apply` subtract that baseline when clean, else report the combined delta with an explicit `[includes parent WIP]` warning.
+
+---
+
+### Using the runner as a library
+
+Import the stable public SDK from the package root or the explicit `/sdk` subpath; do not reach into `src/*` internals (those paths are not part of the supported contract):
+
+```ts
+import {
+  runTasks,
+  runSubagent,
+  ChildRunner,
+  WorktreeManager,
+  Semaphore,
+  ProcessLockManager,
+  addUsage,
+  normalizeUsage,
+  emptyUsage,
+  type TaskSpec,
+  type TaskResult,
+  type RunState,
+  type UsageStats,
+} from "@cr1ms0n/pi-subagent/sdk";
+```
+
+The package root is an alias for the same SDK: `import { runTasks } from "@cr1ms0n/pi-subagent"`.
+
+The Extension dispatch path routes every new task through Jev, so callers never pass a model to it. The low-level SDK is the opposite contract: it is explicit-spec and performs no implicit routing, config discovery or network call, so embedding code supplies the model (and tool list) it resolved itself. This placeholder is illustrative only and configures nothing:
+
+```ts
+const task: TaskSpec = {
+  task: "Audit src/ for unsafe parsing",
+  profile: "explore",
+  model: "<provider/model-id resolved by your embedding code>",
+  timeoutMs: 10 * 60_000,
+};
+```
+
+Prefer `runTasks()` for multi-task / worktree orchestration (same path the extension and pi-workflows use). `runSubagent()` runs a single child process directly without the extension host, but durable coordination is **opt-in**. Pass both `locks` (a `ProcessLockManager`) and a stable `runId` if you want global concurrency slots and orphan reclaim to see the child. Without those options no durable run record is written, so a parent restart cannot reclassify the process and nested children vanish from reconcile. There is intentionally no implicit default lock manager; embedding code that needs durability must construct and share one.
+
+The Pi extension entry is unchanged: package `pi.extensions` still points at `./extensions/subagent.ts`.
+
+---
+
+### Cost accounting
+
+`status`, `/subagent-cost`, and the `/subagents` overlay header show separate **root**, **subagent**, **routing**, and **combined** totals based on provider-reported usage. On Pi builds after v0.80.10, delivered runs also report their total usage natively on the tool result ([pi#6671](https://github.com/earendil-works/pi/pull/6671)), so Pi's own footer, `/session`, and RPC totals include subagent spend exactly once per run. Older Pi hosts ignore the field. Nested usage reported by a child's tool results (e.g. grandchild subagents) folds into the run's totals and budgets. The extension footer stays terse (running/ready counts only). Delivery and replay do not double count runs. See [docs/COST-ACCOUNTING.md](COST-ACCOUNTING.md).
+
+Jev selection is billed separately from execution. TypeSafe reports tokens, not currency, so the ledger shows routing tokens as their own category, counts each selector request once by its request ID (including plan and pre-spawn failures), and marks routing cost as **unreported** rather than free. Numeric dollar totals exclude unreported routing spend, and `max_cost` caps provider-reported execution cost only; it does not cap TypeSafe charges. Route metadata (selected model, selected tools, locally added controls, selector version, confidence, outcome, latency) travels with the run alongside usage.
+
+---
+
+### Engine contract
+
+The [architecture contract](ARCHITECTURE.md) owns the complete lifecycle, persistence, permission and delivery invariants. The [security model](SECURITY.md) explains the limits of tool profiles and worktree isolation. For source layout and checks available in a fresh checkout, see [development](DEVELOPMENT.md).

package/docs/RELEASING.md

@@ -1,32 +1,151 @@
-# Releasing @cr1ms0n/pi-subagent
-
-This is an independent community fork of `@parke.dev/pi-subagent` by Luke Parke. Preserve the MIT license and copyright, and do not publish this fork under the upstream scope. The upstream monorepo's tag automation does not publish this package.
-
-## Prepare
-
-1. Update `package.json` and `CHANGELOG.md`; use an unpublished version.
-2. Run strict type checking against the installed Pi version and offline fake-runner/extension tests. Do not run real provider calls without permission.
-3. Run `npm pack --dry-run --json` and review the file list. Do not include authentication, user settings, machine-specific paths, local backups, session transcripts or generated test bundles.
-4. Run `npm pack --ignore-scripts`, install the resulting tarball into an isolated prefix with `--ignore-scripts --legacy-peer-deps`, then repeat the offline checks against the packed source.
-
-## Publish
-
-Use an existing npm login or a securely supplied environment-based credential. Never put tokens in command text, source files, or a committed `.npmrc`. Enable TLS verification.
-
-```bash
-npm whoami --strict-ssl=true --registry=https://registry.npmjs.org/
-npm publish ./cr1ms0n-pi-subagent-<version>.tgz --access public --ignore-scripts --strict-ssl=true --registry=https://registry.npmjs.org/
-npm view @cr1ms0n/pi-subagent@<version> name version dist.integrity --strict-ssl=true --registry=https://registry.npmjs.org/
-```
-
-A successful public release makes every file in the tarball public. Verify the package metadata and registry integrity before replacing an existing installation.
-
-## Install and replace
-
-```bash
-pi install npm:@cr1ms0n/pi-subagent@<version>
-```
-
-Do not enable this package and `@parke.dev/pi-subagent` at the same time: both register the same tool names. Back up the old package selection, activate only the new package after verification, and keep the old source for rollback. Reload or restart Pi after changing packages. Configure `~/.pi/subagent.json` `jevRouting` (candidate models plus the credential environment variable) before spawning tasks.
-
-This fork uses the same config and persisted state paths as upstream. Switching packages is not a data migration. Upgrading must not overwrite user model choices or credentials.
+# Release and repository maintenance
+
+This is an independent community fork of Luke Parke's `@parke.dev/pi-subagent`. Preserve the original [MIT license](../LICENSE), copyright and upstream attribution. Do not publish under the upstream scope. This standalone repository does not inherit the upstream monorepo's tag automation.
+
+---
+
+### Choose the scope first
+
+A README or repository-presentation update does not require a new npm version, tag, GitHub Release, package installation or binary upload. An edit to a Release body should change only that body. A new package release is a separate operation with artifact verification and explicit publication approval.
+
+Read [package.json](../package.json), [CHANGELOG.md](../CHANGELOG.md), the working tree and index before making changes. Record the original local HEAD, remote main and any remote metadata you intend to update. Preserve unrelated modifications and existing commit history by default. A separately approved single-root conversion must follow the history-replacement safeguards below; do not infer that permission from a documentation update or another project’s release rules.
+
+---
+
+### Public source-tree boundary
+
+Commit production source, the distributed [subagent skill](../skills/subagent/SKILL.md), public documentation and package metadata. Keep local maintainer tooling and private artifacts out of the public tree: `.trellis/`, `.agents/`, `.codex/`, project-local `.pi/` configuration, `AGENTS.md`, `LOCAL-PATCH.md`, Trellis-named support files, credentials, sessions, logs, dependencies, generated bundles and tarballs.
+
+The product directory [skills/](../skills/) is not the local `.agents/skills/` directory. Never remove the product skill merely because local workflow skills are excluded. No Actions workflow or contributor guide is required for this manual release process.
+
+Do not stage or discard local `.gitignore` edits. Where exclusion rules are maintained in `.git/info/exclude`, preserve its existing content and keep that file local. Ignore rules do not untrack files already in Git. When a reviewed cleanup needs to stop tracking local files, use `git rm --cached -- <explicit paths>` after backing them up and verifying their contents; never delete the working copies to clean the public tree. An ordinary commit does not erase those files from older history.
+
+---
+
+### Documentation-only source updates
+
+Keep [README.md](../README.md) and [README.zh-CN.md](../README.zh-CN.md) synchronized in the same change. Preserve the language switch, package identity, original copyright and license links. Each README ends with one Linux.do acknowledgement; do not expand it into a community/contact section. Do not add a documentation-index table, contribution guide or stale release-promotion block to the landing page.
+
+Run the relevant [development checks](DEVELOPMENT.md), including relative-link and translation review, whitespace checks and the package dry run. A fresh checkout has no bundled test runner or typecheck script; do not claim upstream/private harness commands are available.
+
+Stage only explicitly reviewed paths. For example, when both README files are the complete change:
+
+```bash
+git add -- README.md README.zh-CN.md
+```
+
+Inspect the staged names:
+
+```bash
+git diff --cached --name-status
+```
+
+Inspect the actual staged patch:
+
+```bash
+git diff --cached
+```
+
+Create an ordinary commit after reviewing and approving its scope. Do not use broad `git add -A`, `--amend -a`, history squashing or a force push for documentation maintenance.
+
+Before an authorized push, re-read remote main and compare it with the value saved at the start. Stop on an unexplained change rather than accepting a new baseline. The local branch can be named differently from remote main; target the reviewed commit deliberately:
+
+```bash
+git push origin HEAD:refs/heads/main
+```
+
+Use a normal fast-forward push for ordinary maintenance. Afterward, confirm local HEAD and remote main match, read back affected files, and verify the intended current tree no longer exposes local-only paths. Update GitHub About fields only when that specific edit was approved, and re-read them afterward. Source push and About edits can succeed separately; report their actual status separately.
+
+---
+
+### Explicitly approved history replacement
+
+Only replace the main history when the repository owner has explicitly requested that scope. Preserve the original graph in a local-only backup ref and an external Git bundle, verify the bundle in a separate repository, and retain working-file and index backups. Construct a parentless candidate from the reviewed public tree; verify its tree and that its reachable history contains exactly one commit before changing the local branch. Local maintenance files must remain on disk.
+
+Before replacing remote main, obtain approval for the exact candidate and original remote SHA. Recheck remote state and use an explicit `--force-with-lease=refs/heads/main:<original-sha>` with only `<candidate-sha>:refs/heads/main`. Stop if the lease fails; never refresh the expected SHA to bypass it. Do not push backup refs, use an unqualified force or alter tags and other branches.
+
+Read back the remote commit, parent list and tree after the update. A single-root main history does not erase old objects from GitHub caches, other clones or local backups. It also does not authorize npm publication, installation or About changes.
+
+---
+
+### Prepare an npm release
+
+Only perform this section for an approved version release:
+
+1. Choose an unpublished version and update package metadata and changelog together. Keep README install examples consistent with the intended release.
+2. Run the checks available in the actual environment, as described in [development](DEVELOPMENT.md). A syntax transform is not a semantic typecheck. Record missing tooling and any separately configured typecheck/fixture results. Do not run real provider calls without permission.
+3. Inspect the package dry-run list for unexpected files.
+4. Pack the source, record the tarball's integrity, and test the packed source in an isolated installation where suitable offline verification is available. Do not imply a missing harness was run.
+5. Review the final name, version, tarball, contents and verification results before requesting publication approval.
+
+Dry-run contents:
+
+```bash
+npm pack --dry-run --ignore-scripts --json
+```
+
+Create the release artifact only when preparing a release:
+
+```bash
+npm pack --ignore-scripts
+```
+
+Install the reviewed artifact into a separate temporary prefix using `--ignore-scripts --legacy-peer-deps` if installation checks are part of the approved release scope. Never replace the working Pi installation merely to inspect a package.
+
+---
+
+### Publish with verified TLS
+
+Use an existing npm login or a securely supplied environment-based credential. Never put tokens in command text, source files, a committed `.npmrc` or diagnostics.
+
+If the environment contains `NODE_TLS_REJECT_UNAUTHORIZED=0`, remove that override before any credential-bearing registry operation. `--strict-ssl=true` does not undo a Node-level TLS override.
+
+In Bash:
+
+```bash
+unset NODE_TLS_REJECT_UNAUTHORIZED
+```
+
+In PowerShell:
+
+```powershell
+Remove-Item Env:NODE_TLS_REJECT_UNAUTHORIZED -ErrorAction SilentlyContinue
+```
+
+Check the authenticated account without displaying credentials:
+
+```bash
+npm whoami --strict-ssl=true --registry=https://registry.npmjs.org/
+```
+
+After explicit approval, publish the reviewed tarball. Replace `<version>` with the approved version:
+
+```bash
+npm publish "./cr1ms0n-pi-subagent-<version>.tgz" --access public --ignore-scripts --strict-ssl=true --registry=https://registry.npmjs.org/
+```
+
+Read the exact version's registry metadata:
+
+```bash
+npm view "@cr1ms0n/pi-subagent@<version>" name version dist.integrity --strict-ssl=true --registry=https://registry.npmjs.org/
+```
+
+Registry propagation can lag. A successful publish is not proof that the exact version is already readable. Verify name/version/integrity against the reviewed local artifact before replacing an installation; do not repeat a publication blindly after an uncertain response. All files in a published tarball become public.
+
+GitHub tags, Releases and attachments are separate from npm publication. Do not create or modify them implicitly. If explicitly requested, inspect the existing remote objects, use a tool that actually supports the operation, update only the approved fields/assets, then read back and verify the result.
+
+---
+
+### Install and replace
+
+Installation is a separate local change. After artifact verification and approval, replace `<version>` with the verified release:
+
+```bash
+pi install "npm:@cr1ms0n/pi-subagent@<version>"
+```
+
+Back up the old package selection/source and keep it for rollback. Do not enable this fork and `@parke.dev/pi-subagent` simultaneously: both register the same tools. Verify the physical installed package version and files rather than relying only on a command's exit status or the settings entry. Reload or restart Pi after changing packages.
+
+This fork uses the same configuration and persisted-state paths as upstream. Switching packages is not a data migration. Do not overwrite model choices or credentials during upgrades. Configure `jevRouting` in `~/.pi/subagent.json` before starting new tasks, as described in the [reference](REFERENCE.md#jev-routing).
+
+Report preparation, publication, remote synchronization and local installation as distinct states, including checks that could not be performed.

package/docs/ROADMAP.md

@@ -1,5 +1,7 @@
 # Roadmap
 
+> **Historical upstream roadmap.** Retained for rationale and deferred ideas, not as this fork's current release schedule. Phases 2-4 are recorded as shipped in [the historical execution plan](PLAN.md); their future-tense sketches below do not mean these features are missing. Jev routing supersedes the old model-selection assumptions. Use [the current reference](REFERENCE.md), [architecture contract](ARCHITECTURE.md) and [development checks](DEVELOPMENT.md) for current behavior and available tooling. Historical test claims are not verification results for this checkout.
+
 > Execution details for the remaining phases (work breakdown, acceptance
 > criteria, test plans, release gates) live in [PLAN.md](./PLAN.md). This
 > document holds the rationale, design sketches, and deferral decisions.