@cr1ms0n/pi-subagent 0.8.1

package/docs/ROADMAP.md

@@ -0,0 +1,252 @@
+# Roadmap
+
+> 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.
+
+Prioritized improvement plan, consolidated from four review passes: the
+competitor field study (@tintinweb, nicobailon), the strategic review, the
+fresh-eyes engine review, and the oh-my-pi task-system comparison. Each item
+carries a design sketch grounded in the current code, an effort/impact rating,
+and explicit risks. Ordering within a phase is the intended implementation
+order; phases are independently shippable releases.
+
+Legend: effort S (<½ day) / M (1–2 days) / L (3+ days) · impact ▲ high / △ medium
+
+---
+
+## Phase 1 — Structured results (v0.3.0) — ✅ SHIPPED
+
+The single biggest remaining quality gap. Free-text child output forces the
+parent to re-parse prose, which is fragile and burns tokens. oh-my-pi's
+`yield` protocol validates the design; we adapt it to our process boundary.
+
+> Implemented in `src/structured.ts` + runner/policy/output wiring: 1.1
+> (output_schema with settle-gated validation and one steer-based repair
+> round, agent-file `output_schema:` inline or `@file.json`), 1.2 (validated
+> JSON handoff to synthesis), 1.3 (conservative arg repair). E2E-verified
+> against real Pi.
+
+### 1.1 `output_schema` — validated structured output ▲ M
+
+**What:** optional JSON Schema per task. The child must end with a fenced
+` ```json:result ` block (or a final JSON object) satisfying the schema; we
+validate on our side of the process boundary and surface `result.parsed` in
+details plus a `structured: true` flag.
+
+**Design:**
+- Schema field `output_schema: Type.Optional(Type.Object({}, { additionalProperties: true }))`
+  on `TaskFields` (`src/schema.ts`). Validate at policy time that it parses as
+  a JSON Schema (typebox `Value.Check` against a permissive meta-check).
+- Inject a compact contract into the child via the existing
+  `--append-system-prompt` path (`src/runner.ts` `spec.systemPrompt` join):
+  "Your final message MUST end with a ```json:result fenced block matching
+  this schema: …". Persona prompt first, schema contract last (highest
+  salience).
+- Parse in `ProtocolParser.finalize()` (`src/protocol.ts`): scan the final
+  assistant text for the fenced block, fall back to a trailing bare JSON
+  object. Attach `structuredOutput?: unknown` + `structuredError?: string` to
+  `TaskResult` (`src/types.ts`), thread through `toPersistedResult` /
+  `compactDetails`.
+- **Retry integration (the payoff):** schema-invalid output is NOT a transient
+  failure (no model fallback), but gets one **steer-based repair round** —
+  reuse the wrap-up machinery in `src/runner.ts` (`handleBudgetBreach`
+  pattern): steer "your result did not validate: <errors>; re-emit the fenced
+  block" and allow 1 extra turn. Mirrors oh-my-pi's yield-reminder ladder
+  without needing an in-process tool.
+- Delivery: when `output_schema` is set and validation succeeded, `wait`/
+  foreground text is the pretty-printed JSON; `details.results[n].parsed`
+  carries the object. Validation failure after the repair round → state
+  `partial`, `structuredError` set, raw text still delivered (never lose paid
+  work).
+- Agent files (`src/agents.ts`): allow `output_schema` in frontmatter as an
+  inline JSON value or `@file.json` reference, so personas can carry contracts.
+
+**Dependency:** none new — use typebox `Value.Check` with a schema compiled
+via `Type.Unsafe` wrapping, or plain structural validation for the JSON-Schema
+subset we accept (`type/properties/required/items/enum`). Do NOT add ajv.
+
+**Risks:** models ignoring the contract (mitigated by the repair steer); the
+fenced-block convention colliding with task content (use a unique fence tag).
+
+### 1.2 `{outputs}` handoff for synthesis + sequential patterns △ S
+
+**What:** when parallel tasks used `output_schema`, feed the synthesis child
+the *validated objects* (JSON) instead of prose tails, and include per-task
+validity flags. Pure upgrade to `runSynthesis` (`src/extension.ts`).
+
+### 1.3 Arg repair for mangled task text △ S
+
+oh-my-pi's `repair-args.ts` steal. LLMs sometimes double-encode JSON into
+string fields. Detect structural escape patterns (`\"`, `\\n`, `\u00XX`) in
+`task` / `system_prompt` / `synthesis` at policy time and de-mangle once when
+the decoded form parses cleanly. **Never** touch identifier fields (`agent`,
+`model`, `id`) or `tools`. ~50 lines in `src/policy.ts` + table tests.
+
+---
+
+## Phase 2 — Agent ecosystem depth (v0.3.x)
+
+Builds on the named-agent files just shipped. All items are additive
+frontmatter/behavior; no format break.
+
+### 2.1 `spawns:` allowlist in agent frontmatter ▲ S
+
+**What:** per-agent control over which agents its children may use — finer
+than the global depth cap. oh-my-pi steal (`spawn-policy.ts`).
+
+**Design:**
+- Frontmatter `spawns: false | "*" | "a, b"` parsed in `src/agents.ts`.
+- Enforcement at spawn time: the parent's *own* spawn policy travels to the
+  child via env (`PI_SUBAGENT_SPAWNS`) next to `PI_SUBAGENT_DEPTH`
+  (`src/runner.ts` childEnv). `validateSubagentRequest` (`src/policy.ts`)
+  reads it: `false` → reject any spawn; list → the requested `agent:` (or
+  agentless composition) must be allowed. Fail closed on malformed env, same
+  as `parseDepth`.
+- `spawns: false` children also get the subagent tool filtered out (extend
+  the existing `tool !== "subagent"` filter logic to honor policy, not just
+  the depth ceiling).
+
+**Risk:** env is advisory (children can shell out to `pi` directly) — document
+as accidental-recursion guard, exactly like depth (SECURITY.md item 3).
+
+### 2.2 Resumable-session discovery △ S
+
+Fresh-eyes gap G6: resuming requires already knowing the child session id.
+Extend bare `status` output (`src/extension.ts`): completed runs list
+`session <id8> (resumable)` per result, and add a one-line hint to
+`promptGuidelines`. No new action needed — the data is already in snapshots;
+we just don't advertise it.
+
+### 2.3 Dry-run validation (`action: "plan"`) △ S
+
+Fresh-eyes gap G11: policy failures (write-guard, unknown agent, bad tools)
+currently surface only after enqueue. Add `action: "plan"` that runs
+`validateSubagentRequest` + worktree/git preflight (`isGitRepo` for
+isolation:'worktree' tasks) and returns the resolved per-task spec
+(`resolutionNotes`, effective model/tools/budgets) without spawning.
+Cheap: the validation path is already pure.
+
+### 2.4 Agent file ergonomics △ S
+
+- `system_prompt: "@path.md"` references (relative to the agent file), so
+  personas can share prompt fragments. Resolve in `src/agents.ts` with the
+  same symlink/size guards.
+- `/subagents` overlay: an `agents` line in the header showing catalog count,
+  and unknown-agent errors already list availability (done) — add the catalog
+  to `/subagent-cost`'s sibling command? No — keep one surface, skip.
+
+---
+
+## Phase 3 — Engine hardening (v0.4.0)
+
+Remaining items from the fresh-eyes review plus oh-my-pi's concurrency lesson.
+Individually small, collectively they close the last known failure modes.
+
+### 3.1 Queue-slot release granularity ▲ M
+
+oh-my-pi's deadlock lesson (their issue #3749): a semaphore slot held for a
+child's full lifetime deadlocks spawn trees wider than the limit. We're
+partially exposed: a nested parent (depth 1) holds a per-session slot in *its*
+runtime while its own children queue — different semaphores per process, so
+the per-session limiter is safe, but the **machine-wide `maxGlobalActive`
+slot** (`src/process-lock.ts` global slots) IS held across the child's whole
+run, including while that child waits on its own children's global slots.
+
+**Design:** exempt nested parents from double-counting — a child process
+should release/not-hold its global slot while it is itself blocked waiting
+for descendants. Simplest correct fix given our process boundary: count only
+*leaf* work against the global cap by having the runner acquire the global
+slot **after** semaphore acquire and release it during any period the child
+reports zero active LLM streaming (not knowable today) — OR, pragmatically:
+raise the effective cap per depth level (`maxGlobalActive` applies per depth
+tier: `slots(depth) = maxGlobalActive - depth * reserved`). Decide at
+implementation time; write the deadlock repro test first
+(`tests/process-lock.test.ts`: tree of width > cap).
+
+### 3.2 Dirty-baseline worktrees △ M
+
+oh-my-pi steal. `worktrees.create` (`src/worktree.ts`) snapshots `HEAD`,
+silently excluding the parent's uncommitted changes — a writer agent asked to
+"fix the bug I'm mid-way through" can't see the WIP.
+
+**Design:** optional `include_wip: true` on worktree tasks: after
+`git worktree add`, apply `git diff HEAD` from the base checkout (plus
+untracked files via `git ls-files -o --exclude-standard` copy) into the
+worktree, uncommitted. `diff`/`apply` must then diff against
+`baseCommit + WIP` — capture a synthetic baseline patch in the handle and
+subtract it (oh-my-pi's filtered-delta approach, simplified: store the WIP
+patch, exclude its hunks from `diff` output via `git diff` against a temp
+index). Keep default OFF; document that apply-back of WIP-seeded worktrees
+reports the combined delta if subtraction fails, with a warning.
+
+### 3.3 Lease-expiry reclaim latency △ S
+
+Fresh-eyes #10: a crashed same-host owner is reclaimed instantly via
+`isAlive`, but a *cross-host* (or identity-unverifiable) dead owner blocks
+resume for up to 2× lease. Reduce the stale window to
+`leaseExpiresAt < now()` (one lease, not two) when the process identity is
+verifiably dead-or-foreign-host, keeping the 2× grace only when identity is
+unknown. One condition in `src/process-lock.ts:300` + clock-skew comment.
+
+### 3.4 API-consumer orphan records △ S
+
+Fresh-eyes #8: `runSubagent()` without `locks`/`runId` writes no run record,
+so its children are invisible to orphan reclaim. Either (a) document loudly in
+the JSDoc that durable reclaim requires `locks` + `runId` (S), or (b) create a
+default ProcessLockManager when omitted (M, changes API behavior). Choose (a)
+now, revisit if the SDK surface grows users.
+
+---
+
+## Phase 4 — Observability polish (v0.4.x)
+
+### 4.1 Live transcript view in `/subagents` △ M
+
+The UI-overhaul "stretch" item, now more valuable with steering: the detail
+view shows the *checkpointed* transcript (capped, message-boundary updates).
+Tail the child's session `.jsonl` (we know the path: `sessionDir` +
+`sessionId`) for the selected running run, rendering the last N events live.
+Read-only file tailing; no RPC changes. Pairs with the existing `s` steer key
+to close the observe→steer loop in one surface.
+
+### 4.2 Widget/notification config △ S
+
+`widget: "background" | "off"` and `notifications: "batched" | "off"` in
+`SubagentConfig` — some users will want quiet mode. Trivial gates around
+`refreshWidget` / `CompletionBatcher` in `src/extension.ts`.
+
+### 4.3 Stall/attempt events in checkpoints for `status` △ S
+
+`stalledSince`/`attempts` already render inline and in details; also include
+them in `formatStatusPreview` so background `status` polling shows
+`[stalled 2m]` / `[attempt 2]` without opening the overlay.
+
+---
+
+## Explicitly deferred (decided, with reasons)
+
+| Item | Reason |
+|---|---|
+| Inter-agent messaging (`hub`-style) | Star topology + synthesis + steer covers ~85%; even oh-my-pi (full engine access) scopes it to "quick coordination". Revisit only on demonstrated demand. |
+| CoW filesystem isolation | Requires native code; impossible in a TS-only extension. `git worktree` stays. |
+| In-process execution mode | Would forfeit our moat (crash durability, orphan reclaim, version isolation). |
+| Chains / DAG workflows | The orchestrating LLM sequences calls fine; `resume` + structured outputs (1.1) compose. nicobailon's chain complexity is a warning, not an invitation. |
+| Scheduling (cron) | Different product. A separate extension could call our tool. |
+| Tiny-model label generation | `description` param covers it at zero cost. |
+| Eager-delegation system prompt | Fork-only capability; our `promptGuidelines` already nudge. |
+| Agent management UI (eject/create wizard) | Files are the UI; keep one config surface. |
+
+## Sequencing summary
+
+| Release | Contents | Theme |
+|---|---|---|
+| v0.3.0 | 1.1, 1.2, 1.3 | structured results |
+| v0.3.x | 2.1, 2.2, 2.3, 2.4 | agent ecosystem |
+| v0.4.0 | 3.1, 3.2, 3.3, 3.4 | engine hardening |
+| v0.4.x | 4.1, 4.2, 4.3 | observability |
+
+Every phase keeps the standing invariants (docs/ARCHITECTURE.md): capability
+profiles fail closed, explicit params beat file/config defaults, delivery-once,
+partial work is never discarded, and no feature may require the parent to be
+alive for a child's work to survive.

package/docs/SECURITY.md

@@ -0,0 +1,85 @@
+# 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` (+ explicit read-only extras) | No |
+| `review` | same as explore | No |
+| `general` | inherited active tools (may include `bash`/`edit`/`write`) | Yes |
+
+Parallel mode defaults to `explore` to avoid concurrent shared writes.
+
+## Hard rules
+
+1. **Read-only means no `bash`.** `bash` can rewrite the disc and is never part of
+   an explore/review profile.
+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.

package/docs/UI-OVERHAUL.md

@@ -0,0 +1,186 @@
+# UI Overhaul Plan — Pi-Native Rendering
+
+> **Status: fully implemented.** All five phases are done (`src/format.ts`,
+> `src/ui.ts`, `src/extension.ts`, `src/notifications.ts`). Deviations from
+> the plan: the inline spinner uses a wall-clock frame (Pi's working indicator
+> drives repaints, so no timer is owned); the ledger command landed as
+> `/subagent-cost` via `ctx.ui.notify`. Phase 4 shipped as the background-only
+> ambient widget plus batched `followUp` completion notifications with
+> flush-time wait-suppression (see docs/UX.md). The `description` param is the
+> task label across all surfaces. This document is retained as design rationale.
+
+Goal: remove the duplicated cost footer, make inline chat rendering clean and
+smooth, and align every surface with Pi's native conventions. Informed by a
+code-level review against Pi's TUI docs/built-ins and a comparison with
+`@tintinweb/pi-subagents` (Claude Code-style reference), `nicobailon/pi-subagents`
+(highest-download orchestrator), and Claude Code's Task tool.
+
+## Design principles (from the comparison research)
+
+1. **Pi's tool shell owns state signaling.** The Box wrapper already paints
+   `toolPendingBg` / `toolSuccessBg` / `toolErrorBg` and animates the working
+   indicator. We stop drawing our own ✓/✗/state-colored words and spinners that
+   never animate.
+2. **Cost is a per-run attribute, not a competing ledger.** No package that
+   feels native adds a second persistent cost line. Dollar cost appears inside
+   the run's own result block and on demand (`/subagent-cost`-style command);
+   ambient surfaces show tokens/context-%, which Pi's footer doesn't cover.
+3. **Fixed-height, mutate-in-place progress.** Streaming blocks never grow and
+   never get replaced with differently-shaped text. Repaints are event-gated,
+   with a trailing flush so the last update always lands.
+4. **Three optional layers**: inline block (foreground), ambient widget
+   (background only — never double-render), notification on completion.
+   Overlay is for depth, not liveness.
+
+---
+
+## Phase 1 — Kill the duplicate cost footer (P0)
+
+Files: `src/extension.ts` (`refreshFooter`), `src/ui.ts` (`FooterStatusModel`), `src/usage.ts`.
+
+- `setStatus("subagent", …)` shrinks to a terse indicator, themed, only when
+  actionable:
+  - running: `⚙ 2 running` (`warning`)
+  - undelivered results: `· 1 ready` (`success`)
+  - nothing running/ready → `setStatus("subagent", undefined)`. Drop the
+    `hasUsage` keep-alive entirely.
+- Delete `root $…` / `combined $…` / `subagents $…` from the footer. Pi's
+  native footer already shows session cost; child-run cost moves to:
+  - the run's own inline result block (`$0.0123` as one dim stat),
+  - a new **`/subagent-cost` command** printing parent/children/combined once,
+    in-flow (replaces the always-on ledger; reuses `buildUsageLedger`),
+  - the `/subagents` overlay header (already there),
+  - `status` tool output (unchanged — the model still needs it).
+- Fix `FooterStatusModel.update()` to react to ready-count changes, not just
+  running-count. Remove the hardcoded width-160 render; a terse segment needs
+  no truncation.
+
+## Phase 2 — Native inline rendering (P0/P1)
+
+Files: `src/format.ts`, `src/extension.ts` (renderCall/renderResult), `src/schema.ts`.
+
+Adopt the Claude Code / tintinweb two-line collapsed block:
+
+```
+renderCall (static, one line):
+▸ subagent  Find auth middleware and summarize     (toolTitle bold + muted preview)
+▸ subagent  3 parallel tasks
+
+renderResult, running (isPartial, fixed height, mutates in place):
+⠹ ↻3 · 12.4k tok · 8s
+  ⎿ reading src/auth/middleware.ts…
+
+renderResult, done:
+↻8 · 33.8k tok · $0.012 · 12.3s
+  ⎿ Done — Found 5 middleware call sites…        (first line of final output)
+
+renderResult, parallel — one block per task:
+task-1 ↻5 · 21k tok · 9s   ⎿ editing 2 files…
+task-2 ↻3 · 12k tok · 7s   ⎿ running tests…
+```
+
+Concrete changes:
+
+- **Add an optional `description` param** (short human label, 3–5 words) to the
+  tool schema; fall back to a truncated task preview. This is load-bearing for
+  every surface (inline header, widget rows, notifications, overlay list).
+- **`renderCall` = exactly one line.** Delete the title + `Task:` + tasks-preview
+  block; delete the fake `expandHint()` literal and use
+  `keyHint("app.tools.expand", "to expand")` (only when collapsed).
+- **`renderResult` rebuilt around `options.isPartial` and `context`:**
+  - reuse `context.lastComponent` (a `Text`) via `setText()` — stable row
+    identity, no per-frame Container/closure rebuild; delete `lineComponent`.
+  - partial view: stats line + one `⎿ activity` line derived from live text
+    tail. No spinner glyph of our own unless we drive it: keep a timer in
+    `context.state` bumping a frame + `context.invalidate()` at ~80–120 ms
+    while `isPartial`, disposed when the final render arrives.
+  - terminal view: stats (turns · tokens · $cost · fixed duration) + one-line
+    summary; `⎿ Stopped` / `⎿ Wrapped up (max turns)` / error text for
+    non-success. No ✓/✗ glyphs, no state-colored words — the shell shows it.
+  - expanded: final output rendered via `Markdown` + `getMarkdownTheme()`,
+    capped ~50 lines with a dim `… use wait/status for full output` trailer.
+- **Delete from `format.ts`:** emoji profile icons (`🔍📋⚡` → single-cell
+  themed glyphs if kept at all), duplicated parallel task list in results,
+  unconditional elapsed line, `Date.now()`-based elapsed for finished tasks
+  (freeze duration at `endedAt - startedAt`).
+- **Bug fix:** `String(wrapTextWithAnsi(...))` comma-join at format.ts:166-169
+  (use the returned `string[]` directly).
+
+## Phase 3 — Smooth streaming (P0)
+
+Files: `src/extension.ts` (`streamUpdate`), `src/registry.ts` (already coalesced).
+
+- Replace the drop-based 250 ms throttle with a **trailing-edge flush**:
+  non-structural updates schedule a deferred emit instead of being dropped, so
+  the final state of a burst always renders. Structural updates still flush
+  immediately.
+- Stop baking time-varying text (`formatStatusPreview` with elapsed) into the
+  streamed `content`. Stream stable data in `details` (state, usage, live-text
+  tail, activity) and let `renderResult` compute elapsed at render time with
+  its `context.state` ticker.
+- Separate LLM-facing `content` (compact status string, updated rarely) from
+  render-facing `details` (updated often) so UI smoothness never churns model
+  context.
+
+## Phase 4 — Background runs: widget + notifications (P1)
+
+Files: `src/extension.ts`, new `src/notifications.ts`.
+
+- **Ambient widget** (`ctx.ui.setWidget("subagent", …)`, above editor),
+  **background runs only** (foreground already renders inline — avoids the
+  double-render bug tintinweb hit):
+
+  ```
+  ● Subagents
+  ├─ ⠹ review  Audit dependency licenses · ↻4 · 18k tok · 41s
+  └─ 1 queued
+  ```
+
+  Cleared when no background runs. Config: `widget: "background" | "off"`.
+- **Completion notifications** via `pi.sendMessage(…, { deliverAs: "followUp",
+  triggerTurn: true })` + `registerMessageRenderer`: themed compact box for the
+  human (state, stats, first-line preview, artifact/session pointers),
+  structured payload for the model. Replaces the bare `ctx.ui.notify` toast.
+  - Smart-join: completions within a short window group into one notification;
+    failures bypass batching and flush immediately.
+  - Consumption suppression: a `wait` that already delivered the result
+    suppresses the redundant notification (short hold + delivered flag — we
+    already track `delivered`).
+
+## Phase 5 — Overlay polish (P2)
+
+Files: `src/ui.ts`.
+
+- Rebuild the list on `SelectList` + `DynamicBorder` with injected
+  `keybindings` instead of hand-rolled j/k/q handling and the custom `▶`
+  prefix.
+- Detail view: render transcript/final output through `Markdown`; themed
+  section headers; keep scroll.
+- Header keeps the full cost ledger (this is the right home for it).
+- Stretch (only if demanded): live-follow transcript viewer for a running
+  child, reading the child session `.jsonl` we already know the path to.
+
+## Sequencing & risk
+
+| Phase | Effort | Risk | User-visible win |
+|-------|--------|------|------------------|
+| 1 footer | S | low | removes the #1 complaint immediately |
+| 3 streaming | S | low | fixes stutter; independent of visual redesign |
+| 2 inline | M | medium (renderer rewrite + tests) | fixes "ugly" |
+| 4 widget/notifications | M | medium (new message type) | background UX |
+| 5 overlay | M | low | polish |
+
+Phases 1+3 first (small, independent, biggest complaints), then 2, then 4/5.
+
+Testing: extend `tests/format.test.ts` for the new block layouts (collapsed /
+partial / terminal / parallel), add renderer identity tests (same component
+instance reused across partial renders), and a streaming test asserting the
+trailing flush delivers the last update of a burst.
+
+## Anti-goals
+
+- No second persistent cost surface anywhere.
+- No growing inline blocks; no appending streamed output to history.
+- No custom expand keybinding; Ctrl+O (`app.tools.expand`) only.
+- No per-completion notification spam in fanouts.
+- Never show raw un-themed strings in any surface.

package/docs/UX.md

@@ -0,0 +1,141 @@
+# 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 `followUp` message (custom type
+`subagent-completion`) notifies the parent LLM so it reacts 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.

package/extensions/subagent.ts

@@ -0,0 +1 @@
+export { default } from "../src/extension.js";