@cr1ms0n/pi-subagent 0.8.8 → 0.9.0

package/docs/RELEASING.md

@@ -1,32 +1,32 @@
-# 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` modelPolicy 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.
+# 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.

package/docs/SECURITY.md

@@ -1,97 +1,125 @@
-# Security model
-
-Pi packages run with full system access. This extension spawns child `pi`
-processes that inherit the parent environment (including provider credentials)
-and can use tools according to their capability profile.
-
-## What subagents can do
-
-| Profile | Default tools | Writes? |
-|---------|---------------|---------|
-| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and allowlisted Pi context tools) | No project-file writes |
-| `review` | same as explore | No project-file writes |
-| `general` | inherited active tools (+ allowlisted Pi context tools) | Yes if `bash`/`edit`/`write` are active |
-
-Pi context tools are allowlisted by **target model**, not by parent session: a
-child receives `new_context`, `get_context_remaining`, `history`, or `notes`
-only when the toolkit config has `compaction.contextManagement: "remote"`, the
-child's target model exactly equals a `compaction.gatewayContextModels` entry,
-and the parent exposes the tool. Missing/unreadable/invalid/disabled toolkit
-configuration yields no context tools. Retry fallback attempts are re-filtered
-per attempt, so a disallowed fallback cannot inherit them.
-
-Parallel mode defaults to `explore` to avoid concurrent shared writes.
-
-## Hard rules
-
-1. **Read-only means no project-file mutation.** `bash` can rewrite the disk and is never part of
-   an explore/review profile. Pi context-management tools (`new_context`,
-   `get_context_remaining`, `history`, `notes`) are an explicit control-plane
-   exception, but only for the exact target models allowlisted above: they may
-   update continuity notes/window state but cannot access the project write
-   tools, and they are rejected as unavailable for every other target.
-2. **Parallel writers** require `isolation: "worktree"`, distinct `cwd` values,
-   or an explicit `allow_shared_writes: true` opt-in.
-3. **Depth is capped** (`maxDepth`, default 2). Nested children at the ceiling do
-   not re-register the subagent tool. Depth is scheduling metadata — `bash` or an
-   env-scrubbing wrapper can still invoke `pi` directly, so treat it as an
-   accidental-recursion guard, not a security boundary.
-   **Spawn allowlists** (`spawns:` in agent frontmatter, env `PI_SUBAGENT_SPAWNS`)
-   refine that same guard: a child may be limited to named personas, or to none
-   (tool not registered). Like depth, this is not a sandbox — children can still
-   shell out to `pi`.
-4. **Process caps** limit concurrency both per parent session (`maxActiveProcesses`)
-   and machine-wide (`maxGlobalActive`, default 16).
-5. **Transcripts** under `~/.pi/subagent-sessions` may contain task content, tool
-   output, and secrets that appeared in context. Protect that directory. Task text
-   is delivered via stdin (not argv) so it stays out of `ps` listings, but it is
-   still written into the child session log.
-6. **Background permission prompts** are limited because children run headless
-   (RPC mode). Extension UI dialogs raised inside a child are auto-cancelled so
-   they can never hang a run — which also means a child can never obtain
-   interactive consent. Prefer restricted tools for async/background runs.
-11. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
-    into a running child's conversation with user-level authority. Anything that
-    can call the subagent tool can steer any live run in the same session.
-7. **Process cleanup.** On POSIX, children run in their own process group so tree
-   kills work for ordinary descendants. Parent (re)start reaps orphans recorded
-   under `~/.pi/subagent-locks/runs/` so resume cannot race a still-alive writer.
-   Grandchildren that call `setsid()` can still escape a simple process-group kill.
-8. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
-   concurrent parents cannot append to the same child session.
-9. **Profiles are tool-selection policy, not a sandbox.** Children inherit
-   `$HOME`, SSH/cloud credentials, network access, and the parent filesystem.
-   Git worktrees only isolate the checkout. For untrusted tasks, use an outer
-   container/cgroup/network policy.
-10. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
-    turn; orphans may spend money the ledger never sees. Combine with provider
-    account budgets for hard spend limits.
-
-## Trust and project cwd
-
-If `cwd` points outside the parent project, the child inherits whatever local
-project config/trust applies to that path. Treat external `cwd` as elevated risk
-and prefer read-only profiles when exploring third-party trees.
-
-## Output artifacts
-
-`output` files are written by the child. Resolve paths carefully and reject
-duplicate output paths across parallel workers.
-
-## Named agent files
-
-Agent files (`.pi/agents/`, `.agents/agents/`, global agent dir) inject their
-body into the child's system prompt and set its model/tools/budgets. A
-project-level agent file shapes subagent behavior the same way project
-extensions and skills do — review them like code when working in untrusted
-repositories. Mitigations: capability profiles still fail closed (an agent
-cannot grant write tools under `explore`/`review`), symlinked agent files are
-skipped, names are validated against traversal characters, and files over
-64KB are ignored.
-
-## Machine-wide state
-
-`~/.pi/subagent-locks/` holds session locks, global concurrency slots, and run
-process identity records. It is per-user (under `$HOME`) and must not be shared
-across untrusted users/containers without care — a compromised client could
-interfere with lock reclaim on the same account.
+# Security model
+
+Pi packages run with full system access. This extension spawns child `pi`
+processes that inherit the parent environment (including provider credentials)
+and can use tools according to their capability profile.
+
+## What subagents can do
+
+| Profile | Default tools | Writes? |
+|---------|---------------|---------|
+| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
+| `review` | same as explore | No project-file writes |
+| `general` | Jev-chosen subset of the full available locally permitted catalog (+ Pi context tools) | Yes if the selected tools include `bash`/`edit`/`write` |
+
+Parallel mode defaults to `explore` to avoid concurrent shared writes.
+
+## Hard rules
+
+1. **Read-only means no project-file mutation.** `bash` can rewrite the disk and is never part of
+   an explore/review profile. Pi context-management tools (`new_context`,
+   `get_context_remaining`, `history`, `notes`) are an explicit control-plane
+   exception: they may update continuity notes/window state but cannot access
+   the project write tools. The finalized tools reach the child as Pi's `--tools`
+   allowlist (`--no-tools` when empty), and the selector's answer is re-validated
+   locally: unknown, unavailable or unsafe choices cannot launch broader
+   capability, and an empty selection never becomes "all tools". 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.
+   Before the real task prompt, a package-local startup check verifies the routing
+   bootstrap command source and has the child acknowledge the exact selected model
+   and tool names; a mismatch aborts as a capability diagnostic and is never fixed
+   by widening tools, switching models or approving project trust.
+2. **Parallel writers** require `isolation: "worktree"`, distinct `cwd` values,
+   or an explicit `allow_shared_writes: true` opt-in.
+3. **Depth is capped** (`maxDepth`, default 2). Nested children at the ceiling do
+   not re-register the subagent tool. Depth is scheduling metadata — `bash` or an
+   env-scrubbing wrapper can still invoke `pi` directly, so treat it as an
+   accidental-recursion guard, not a security boundary.
+   **Spawn allowlists** (`spawns:` in agent frontmatter, env `PI_SUBAGENT_SPAWNS`)
+   refine that same guard: a child may be limited to named personas, or to none
+   (tool not registered). Like depth, this is not a sandbox — children can still
+   shell out to `pi`.
+4. **Process caps** limit concurrency both per parent session (`maxActiveProcesses`)
+   and machine-wide (`maxGlobalActive`, default 16).
+5. **Transcripts** under `~/.pi/subagent-sessions` may contain task content, tool
+   output, and secrets that appeared in context. Protect that directory. Task text
+   is delivered via stdin (not argv) so it stays out of `ps` listings, but it is
+   still written into the child session log.
+6. **Background permission prompts** are limited because children run headless
+   (RPC mode). Extension UI dialogs raised inside a child are auto-cancelled so
+   they can never hang a run — which also means a child can never obtain
+   interactive consent. Prefer restricted tools for async/background runs.
+11. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
+    into a running child's conversation with user-level authority. Anything that
+    can call the subagent tool can steer any live run in the same session.
+7. **Process cleanup.** On POSIX, children run in their own process group so tree
+   kills work for ordinary descendants. Parent (re)start reaps orphans recorded
+   under `~/.pi/subagent-locks/runs/` so resume cannot race a still-alive writer.
+   Grandchildren that call `setsid()` can still escape a simple process-group kill.
+8. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
+   concurrent parents cannot append to the same child session.
+9. **Profiles are tool-selection policy, not a sandbox.** Children inherit
+   `$HOME`, SSH/cloud credentials, network access, and the parent filesystem.
+   Git worktrees only isolate the checkout. For untrusted tasks, use an outer
+   container/cgroup/network policy.
+10. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
+    turn; orphans may spend money the ledger never sees. It caps provider-reported
+    execution cost only: TypeSafe reports routing tokens, not currency, so selector
+    cost is unreported and outside `max_cost`. Combine with provider account
+    budgets for hard spend limits.
+
+## Routing disclosure and credentials
+
+Jev routing sends a minimal projection to TypeSafe: the current delegated task
+text, the configured candidate model IDs and your per-model descriptions,
+eligible candidate tool names and descriptions, and necessary constraints
+(profile, requested thinking, whether structured output is needed). It does not
+upload repository files, conversation history, full system prompts, persona text
+or tool parameter schemas, and does not read them in the background. Resume, fork
+and synthesis select from the new task instruction rather than the assembled
+transcript. Task text and model descriptions are user content and can themselves
+contain secrets; there is no guaranteed redaction.
+
+The TypeSafe credential is read from the environment variable named by
+`jevRouting.apiKeyEnv` (default `TYPESAFE_API_KEY`) and sent only as an
+`Authorization` header to the fixed official HTTPS endpoint, with redirects
+disabled. It is never stored in the config file, prompts, argv, logs or results.
+Rotate any credential that has been pasted into a transcript or shared in
+conversation.
+
+New extension-managed dispatch is Pi-only. A `backend: "codex"` or
+`backend: "claude"` new task is rejected before any selector or provider work,
+including a backend inherited from agent frontmatter, rather than silently
+switched to Pi. Existing native-backend runs stay manageable.
+
+## Trust and project cwd
+
+If `cwd` points outside the parent project, the child inherits whatever local
+project config/trust applies to that path. Treat external `cwd` as elevated risk
+and prefer read-only profiles when exploring third-party trees.
+
+## Output artifacts
+
+`output` files are written by the child. Resolve paths carefully and reject
+duplicate output paths across parallel workers.
+
+## Named agent files
+
+Agent files (`.pi/agents/`, `.agents/agents/`, global agent dir) inject their
+body into the child's system prompt and set persona, thinking and budget
+defaults. Model and tool selection come from Jev routing; a legacy
+`model`/`fallback_models` in frontmatter is ignored. A
+project-level agent file shapes subagent behavior the same way project
+extensions and skills do — review them like code when working in untrusted
+repositories. Mitigations: capability profiles still fail closed (an agent
+cannot grant write tools under `explore`/`review`), symlinked agent files are
+skipped, names are validated against traversal characters, and files over
+64KB are ignored.
+
+## Machine-wide state
+
+`~/.pi/subagent-locks/` holds session locks, global concurrency slots, and run
+process identity records. It is per-user (under `$HOME`) and must not be shared
+across untrusted users/containers without care — a compromised client could
+interfere with lock reclaim on the same account.

package/docs/UX.md

@@ -1,141 +1,158 @@
-# pi-subagent UX
-
-## Overview
-The standalone pi-subagent provides rich TUI support for monitoring, inspecting, and interacting with isolated subagent runs (single and parallel modes): inline streaming blocks, a terse footer, an ambient widget for background runs, batched completion notifications, mid-run steering, a worktree apply loop, and the `/subagents` inspector. UI logic is kept independent from `runner`/`registry` via small structural adapters (`SubagentAdapter`).
-
-## Design principles
-
-1. **Pi's tool shell owns state signaling.** The Box wrapper paints
-   `toolPendingBg` / `toolSuccessBg` / `toolErrorBg`, so inline blocks do not
-   repeat state words or draw their own success/error framing.
-2. **Cost is a per-run attribute, not a competing ledger.** Dollar cost appears
-   inside the run's own result block; the parent/children/combined ledger is
-   available on demand via `/subagent-cost`, in `status` tool output, and in the
-   `/subagents` overlay header. The footer never shows cost.
-3. **Fixed-height, mutate-in-place progress.** Streaming blocks keep a stable
-   shape (stats line + one `⎿ activity` line; parallel adds one line per task)
-   and the same component identity is reused across partial renders.
-4. **Trailing-edge streaming flush.** Structural updates (state transition, new
-   session id, billed turn) emit immediately; live-text bursts coalesce with a
-   deferred flush so the last update of a burst always lands.
-
-## Surfaces
-
-### Inline tool block (foreground runs)
-- `renderCall` is exactly one line: `subagent <task preview>` (or
-  `N parallel tasks — first task…`, `wait a1b2c3d4`, `… · background`).
-- `renderResult` while streaming (fixed shape, spinner animates via wall-clock
-  frame; Pi's working indicator drives repaints):
-  ```
-  ⠹ ↻3 · 12.4k tok · 8s
-    ⎿ reading src/auth/middleware.ts…
-  ```
-- Terminal single run:
-  ```
-  ↻8 · 33.8k tok · $0.012 · 12s
-    ⎿ Found 5 middleware call sites…
-    → /tmp/report.md
-  ```
-- Parallel: one line per task with a themed state glyph
-  (`◌ queued · ⠹ running · ✓ done · ✗ failed · ◐ partial · − cancelled · ◷ timeout`),
-  per-task stats, and a one-line tail (live activity or first output line).
-- Expanded (Ctrl+O / `app.tools.expand`): full task output capped with a dim
-  `… +N lines` trailer pointing at the artifact/child session.
-- Durations freeze at `endedAt`; running durations tick at render time.
-- Reliability annotations render inline: `[attempt 2]` during a retry,
-  `[stalled 2m]` while the stall watchdog is flagging silence, and
-  `◐ wrapped up` on budget-stopped runs that concluded gracefully.
-
-### Footer status
-Terse and actionable only: `⚙ 2 running · 1 ready · /subagents`. Cleared when
-nothing is running or ready. No cost — Pi's footer already shows session cost.
-
-### Ambient widget (background runs only)
-An above-editor widget renders while `async: true` runs are live — foreground
-runs already render inline as the tool result, so they never appear here
-(avoids double-render):
-
-```
-● Subagents
-├─ ⠼ Audit deps · ↻4 · 18k tok · 41s
-│   ⎿ checking license headers…
-└─ ◌ License scan · 12s
-```
-
-Cleared when the last background run settles. Spinner and elapsed animate on
-a 250ms interval that exists only while background runs are live.
-
-### Completion notifications (background runs only)
-When an async run reaches a terminal state, a `steer` message (custom type
-`subagent-completion`) is queued for the parent LLM before its next LLM call,
-so it can react without polling. The human sees a themed compact box (state
-glyph, label, stats, one-line preview, artifact pointers); the LLM sees plain
-text with run ids and a `wait { id }` pointer.
-
-- Successes within a short window batch into one message (no fanout spam);
-  failures bypass batching and flush immediately, carrying held successes.
-- A `wait` that already delivered the run suppresses the redundant
-  notification (delivered-state is re-checked at flush time).
-
-### `/subagents` overlay
-- Header: title + running/ready counters + full usage ledger + rule.
-- List: two lines per run — glyph/id/state/stats, then the task preview.
-  Selection cursor `▶`, animated spinner for live runs.
-- Detail: run stats, summary, then per-task sections (glyph, label,
-  model/profile/thinking, usage, pointers, transcript/final output/errors),
-  scrollable with ↑↓/j/k and PageUp/PageDown.
-- Actions: `c` cancel, `s` steer (prompts for a message, injects it into the
-  running child), `d` dismiss, `r` resume, `o` output pointers, `a` apply a
-  finished run's changed worktree into the main checkout (confirm dialog),
-  `x` discard worktree + branch (confirm dialog), Enter drill-down,
-  Esc/b back, Esc/q close.
-- Live transcript (`t` on a **running** run's detail): tails the child's
-  session file (`sessionDir/<…sessionId…>.jsonl`) on a 500ms poll while the
-  pane is visible — compact role/tool lines, auto-follow unless you scroll
-  up (which pauses follow). No RPC reads; hidden/finished runs never poll.
-  Missing file shows “waiting for child session…”. `s` steering still works
-  from the same pane so observe → steer stays on one surface.
-
-### `/subagent-cost`
-Prints the root/subagents/combined ledger once, on demand.
-
-### Mid-run steering
-Children run in Pi RPC mode, so their stdin stays open as a command channel.
-`action: "steer"` (or `s` in the overlay) queues a message that is delivered
-after the child's current assistant turn, before its next LLM call — course
-correction without cancel + retry. Parallel runs steer one task via `index`.
-
-### Worktree loop
-Finished runs with changed worktrees support `diff` / `apply` / `discard`
-actions (tool) and `a` / `x` keys (overlay). `apply` lands the worktree's
-combined patch (committed + uncommitted + untracked vs base) onto the main
-checkout as **uncommitted working-tree changes** via `git apply --3way`; it
-never commits and never deletes the worktree. `discard` is the explicit
-cleanup step and always confirms first.
-
-### Parallel fan-in
-`synthesis: "<instruction>"` on a parallel run spawns one read-only child
-after all tasks settle that folds their outputs into a single brief, delivered
-first in the result. Synthesis failures degrade silently to raw results.
-
-## States
-- **Queued/Running**: spinner + live stats + activity tail from live text.
-- **Completed/Partial/Failed/Cancelled/Timeout/Lost**: state glyph, frozen
-  duration, usage summary, output pointers; failures show the error message.
-- **Delivered vs Undelivered**: footer/overlay track pending delivery.
-- **Notification**: one per terminal transition to avoid spam.
-
-## Integration Notes
-- Extension wires via `ctx.ui.custom((tui, theme, kb, done) => createSubagentsOverlay(tui, theme, adapter, done), {overlay: true})`.
-- Adapter provides getActiveRuns/getCompletedRuns/cancelRun etc. without tight coupling.
-- Inline renderers reuse `context.lastComponent` (a `LineBlock`) so the row keeps
-  a stable component identity across partial renders.
-- Streamed tool updates separate LLM-facing `content` (compact status string)
-  from render-facing `details` (state, usage, live-text tail, run timing).
-- Tests combine pure UI models with a headless Pi extension harness: format
-  helpers, block layouts (collapsed/streaming/terminal/parallel), navigation,
-  truncation (ANSI-safe via `visibleWidth`), ready state, lifecycle/disposal.
-- Follows Pi TUI guidelines (render(width), handleInput, invalidate,
-  requestRender, dispose). The overlay owns a single animation interval.
-
-See ARCHITECTURE.md for ownership boundaries. All rendering respects terminal width and ANSI safety.
+# pi-subagent UX
+
+## Overview
+The standalone pi-subagent provides rich TUI support for monitoring, inspecting, and interacting with isolated subagent runs (single and parallel modes): inline streaming blocks, a terse footer, an ambient widget for background runs, batched completion notifications, mid-run steering, a worktree apply loop, and the `/subagents` inspector. UI logic is kept independent from `runner`/`registry` via small structural adapters (`SubagentAdapter`).
+
+## Design principles
+
+1. **Pi's tool shell owns state signaling.** The Box wrapper paints
+   `toolPendingBg` / `toolSuccessBg` / `toolErrorBg`, so inline blocks do not
+   repeat state words or draw their own success/error framing.
+2. **Cost is a per-run attribute, not a competing ledger.** Dollar cost appears
+   inside the run's own result block; the parent/children/combined ledger is
+   available on demand via `/subagent-cost`, in `status` tool output, and in the
+   `/subagents` overlay header. The footer never shows cost.
+3. **Fixed-height, mutate-in-place progress.** Streaming blocks keep a stable
+   shape (stats line + one `⎿ activity` line; parallel adds one line per task)
+   and the same component identity is reused across partial renders.
+4. **Trailing-edge streaming flush.** Structural updates (state transition, new
+   session id, billed turn) emit immediately; live-text bursts coalesce with a
+   deferred flush so the last update of a burst always lands.
+
+## Surfaces
+
+### Inline tool block (foreground runs)
+- `renderCall` is exactly one line: `subagent <task preview>` (or
+  `N parallel tasks — first task…`, `wait a1b2c3d4`, `… · background`).
+- `renderResult` while streaming (fixed shape, spinner animates via wall-clock
+  frame; Pi's working indicator drives repaints):
+  ```
+  ⠹ ↻3 · 12.4k tok · 8s
+    ⎿ reading src/auth/middleware.ts…
+  ```
+- Terminal single run:
+  ```
+  ↻8 · 33.8k tok · $0.012 · 12s
+    ⎿ Found 5 middleware call sites…
+    → /tmp/report.md
+  ```
+- Parallel: one line per task with a themed state glyph
+  (`◌ queued · ⠹ running · ✓ done · ✗ failed · ◐ partial · − cancelled · ◷ timeout`),
+  per-task stats, and a one-line tail (live activity or first output line).
+- Expanded (Ctrl+O / `app.tools.expand`): full task output capped with a dim
+  `… +N lines` trailer pointing at the artifact/child session.
+- Expanded detail adds one bounded route line for Jev-routed runs: selected
+  execution model, selected tools (plus locally added control-plane tools),
+  selector version, confidence, outcome and selection latency. Legacy runs
+  simply have no route line.
+- Durations freeze at `endedAt`; running durations tick at render time.
+- Reliability annotations render inline: `[attempt 2]` during a same-model
+  retry, `[stalled 2m]` while the stall watchdog is flagging silence, and
+  `◐ wrapped up` on budget-stopped runs that concluded gracefully.
+
+### Footer status
+Terse and actionable only: `⚙ 2 running · 1 ready · /subagents`. Cleared when
+nothing is running or ready. No cost — Pi's footer already shows session cost.
+
+### Ambient widget (background runs only)
+An above-editor widget renders while `async: true` runs are live — foreground
+runs already render inline as the tool result, so they never appear here
+(avoids double-render):
+
+```
+● Subagents
+├─ ⠼ Audit deps · ↻4 · 18k tok · 41s
+│   ⎿ checking license headers…
+└─ ◌ License scan · 12s
+```
+
+Cleared when the last background run settles. Spinner and elapsed animate on
+a 250ms interval that exists only while background runs are live.
+
+### Completion notifications (background runs only)
+When an async run reaches a terminal state, a `steer` message (custom type
+`subagent-completion`) is queued for the parent LLM before its next LLM call,
+so it can react without polling. The human sees a themed compact box (state
+glyph, label, stats, one-line preview, artifact pointers); the LLM sees plain
+text with run ids and a `wait { id }` pointer.
+
+- Successes within a short window batch into one message (no fanout spam);
+  failures bypass batching and flush immediately, carrying held successes.
+- A `wait` that already delivered the run suppresses the redundant
+  notification (delivered-state is re-checked at flush time).
+
+### `/subagents` overlay
+- Header: title + running/ready counters + full usage ledger + rule.
+- List: two lines per run — glyph/id/state/stats, then the task preview.
+  Selection cursor `▶`, animated spinner for live runs.
+- Detail: run stats, summary, then per-task sections (glyph, label,
+  model/selector route/profile/thinking, usage, pointers, transcript/final
+  output/errors), scrollable with ↑↓/j/k and PageUp/PageDown.
+- Actions: `c` cancel, `s` steer (prompts for a message, injects it into the
+  running child), `d` dismiss, `r` resume, `o` output pointers, `a` apply a
+  finished run's changed worktree into the main checkout (confirm dialog),
+  `x` discard worktree + branch (confirm dialog), Enter drill-down,
+  Esc/b back, Esc/q close.
+- Live transcript (`t` on a **running** run's detail): tails the child's
+  session file (`sessionDir/<…sessionId…>.jsonl`) on a 500ms poll while the
+  pane is visible — compact role/tool lines, auto-follow unless you scroll
+  up (which pauses follow). No RPC reads; hidden/finished runs never poll.
+  Missing file shows “waiting for child session…”. `s` steering still works
+  from the same pane so observe → steer stays on one surface.
+
+### `/subagent-cost`
+Prints the root/subagents/routing/combined ledger once, on demand. Routing
+tokens appear as their own category and their currency as unreported; the known
+dollar totals exclude that unreported selector spend.
+
+### Mid-run steering
+Children run in Pi RPC mode, so their stdin stays open as a command channel.
+`action: "steer"` (or `s` in the overlay) queues a message that is delivered
+after the child's current assistant turn, before its next LLM call — course
+correction without cancel + retry. Parallel runs steer one task via `index`.
+
+### Worktree loop
+Finished runs with changed worktrees support `diff` / `apply` / `discard`
+actions (tool) and `a` / `x` keys (overlay). `apply` lands the worktree's
+combined patch (committed + uncommitted + untracked vs base) onto the main
+checkout as **uncommitted working-tree changes** via `git apply --3way`; it
+never commits and never deletes the worktree. `discard` is the explicit
+cleanup step and always confirms first.
+
+### Parallel fan-in
+`synthesis: "<instruction>"` on a parallel run asks for one read-only child
+after all tasks settle that folds their outputs into a single brief, delivered
+first in the result. It is best effort and deferred: its route is selected only
+when aggregation is actually needed after the workers finish, so it never blocks
+worker launch. A selector or child failure keeps the raw worker outputs, their
+usage and a bounded `Optional synthesis blocked: …` diagnostic instead of
+discarding or re-routing them.
+
+### Plan results (tool output, not TUI)
+`action:"plan"` returns the resolved model/tools and the selector usage it
+incurred, and states that a later dispatch selects again. It starts no child and
+creates no run entry, so plan never adds an overlay row or ambient widget. A
+plan whose optional synthesis selection fails still returns the valid worker plan
+and labels only that synthetic stage blocked with its diagnostic.
+
+## States
+- **Queued/Running**: spinner + live stats + activity tail from live text.
+- **Completed/Partial/Failed/Cancelled/Timeout/Lost**: state glyph, frozen
+  duration, usage summary, output pointers; failures show the error message.
+- **Delivered vs Undelivered**: footer/overlay track pending delivery.
+- **Notification**: one per terminal transition to avoid spam.
+
+## Integration Notes
+- Extension wires via `ctx.ui.custom((tui, theme, kb, done) => createSubagentsOverlay(tui, theme, adapter, done), {overlay: true})`.
+- Adapter provides getActiveRuns/getCompletedRuns/cancelRun etc. without tight coupling.
+- Inline renderers reuse `context.lastComponent` (a `LineBlock`) so the row keeps
+  a stable component identity across partial renders.
+- Streamed tool updates separate LLM-facing `content` (compact status string)
+  from render-facing `details` (state, usage, live-text tail, run timing).
+- Tests combine pure UI models with a headless Pi extension harness: format
+  helpers, block layouts (collapsed/streaming/terminal/parallel), navigation,
+  truncation (ANSI-safe via `visibleWidth`), ready state, lifecycle/disposal.
+- Follows Pi TUI guidelines (render(width), handleInput, invalidate,
+  requestRender, dispose). The overlay owns a single animation interval.
+
+See ARCHITECTURE.md for ownership boundaries. All rendering respects terminal width and ANSI safety.