@cr1ms0n/pi-subagent 0.8.1

package/CHANGELOG.md

@@ -0,0 +1,352 @@
+# Changelog
+
+## 0.8.1 — @cr1ms0n community fork (2026-09-08)
+
+- Require an explicit model matching user-owned default/agent model policy.
+- Restrict fallback models and their order to the configured route.
+- Inject the effective model mapping into the parent prompt.
+- Show actual attempt models in inline, background, inspector and completion UI.
+- Preserve older completion payloads and encode Windows parallel/synthesis record filenames.
+- Keep thinking-level selection unchanged from upstream.
+
+The entries below are retained upstream history from @parke.dev/pi-subagent.
+
+
+## Unreleased
+
+### Machine-wide worktree GC
+
+- Startup maintenance now sweeps every repo container under `worktreeDir` via
+  `WorktreeManager.sweepAll()`, not just the current checkout's — stale
+  containers for repos you stop visiting are finally reclaimed. Each
+  container's base repo is resolved from the create-time `base-repo` marker or
+  the linked worktree's gitdir pointer, then swept with the existing `sweep()`
+  safety model (archive unique work, never delete unreachable branches, 1h
+  min-age, keepPaths shielding).
+- Containers whose base repo is gone are **kept and reported**
+  (`GlobalSweepReport.orphanedContainers`), never deleted: their object stores
+  lived inside the deleted repo, so unique work cannot be proven absent or
+  archived. Empty leftovers (no worktrees, no archived patches) are removed.
+- Run process records now carry `worktreeCwd` so live worktree-isolated runs
+  from **other concurrent Pi processes** are shielded from the global sweep,
+  same as this session's live runs.
+- Known limitation: `pi-workflows` reuses `WorktreeManager` with the default
+  root (its worktrees land in the same containers and are reclaimed by the
+  global sweep) but writes run records to a separate lock root, so its live
+  worktrees are shielded only by the 1h min-age window, not by run records.
+
+## 0.8.0
+
+### Lifecycle-driven storage GC (no more wall-clock retention)
+
+Sessions and worktrees are now reclaimed when their run is **over**, not after
+N days. "Over" means: terminal run state, not referenced by the parent branch,
+not owned by any running run record machine-wide, and past a 1-hour
+concurrency race guard.
+
+- **Child session transcripts** are distilled to a small `.digest.json`
+  preserving the meaningful impact — task, final output, model/thinking,
+  usage totals, turn/tool/error counts, duration — and the raw `.jsonl` is
+  deleted (`src/distill.ts`). Sessions referenced by the active branch or busy
+  in any live run are never touched, so resume keeps working.
+- **Worktrees** holding unique work are archived as one applyable
+  `git apply --3way` patch under `<repo-container>/_patches/` and the multi-GB
+  directory (checkout + node_modules) is reclaimed immediately. Branches whose
+  commits exist on no other ref are still never deleted. If archiving fails,
+  the worktree is kept — work is never destroyed unpreserved.
+- `diff` / `apply` / `discard` transparently fall back to the archived patch
+  when the worktree directory is already reclaimed.
+- `sessionRetentionDays` and `worktreeRetentionDays` are accepted but inert.
+
+## 0.7.0
+
+### Public library SDK
+
+- Added stable `@parke.dev/pi-subagent` and `@parke.dev/pi-subagent/sdk`
+  entrypoints for programmatic consumers.
+- Exported orchestration, runner, worktree, process-lock, semaphore, backend,
+  usage, and task/result types without requiring `src/*` imports.
+- The Pi extension manifest remains `./extensions/subagent.ts` and is unchanged.
+- Deep `src/*` package imports are intentionally no longer public once this
+  export map ships.
+
+## 0.6.0
+
+### Multi-backend children: pi, Codex, Claude Code
+
+`backend: "pi" | "codex" | "claude"` on any task, parallel item, or agent
+frontmatter. Children run on the vendor CLI as a child process, so **every
+existing safety guarantee still applies** — git worktree isolation, machine-wide
+process locks, nesting-depth limits, orphan reclaim, PID-identity group kill —
+and **no new dependencies** are added. (The reference implementation this was
+adapted from embeds `@anthropic-ai/claude-agent-sdk` in-process; the `claude`
+CLI exposes everything needed without that weight.)
+
+Internally this is a new `BackendAdapter` seam (`src/backend.ts`,
+`src/backends/`). `ChildRunner` keeps all the backend-agnostic machinery;
+adapters own only invocation building, event-stream parsing, the stdin command
+dialect, and a capability record. The `pi` backend is a verbatim extraction of
+the previous inline logic.
+
+**Capabilities are enforced, not assumed.** Requests a backend cannot honor are
+refused at validation time with an explanation, because silently dropping a
+budget or a read-only guarantee turns a safety feature into a no-op:
+
+|                                  | pi                | codex                               | claude                 |
+| -------------------------------- | ----------------- | ----------------------------------- | ---------------------- |
+| `max_cost`                       | ✅                | ❌ refused (tokens only, no cost)   | ✅ `total_cost_usd`    |
+| read-only profile                | ✅ tool allowlist | ✅ `--sandbox read-only` (OS-level) | ✅ `--allowedTools`    |
+| steering / graceful wrap-up      | ✅                | ❌ no stdin channel                 | ❌ one-shot print mode |
+| `resume`                         | ✅                | ✅                                  | ✅                     |
+| `context:'fork'` / `fork_resume` | ✅                | ❌ refused                          | ✅ `--fork-session`    |
+| `thinking`                       | ✅                | ❌                                  | ❌                     |
+| `output_schema`                  | ✅                | ✅ `--output-schema`                | ✅ `--json-schema`     |
+
+Parsers were written against event streams captured verbatim from the real
+CLIs (codex-cli 0.144.6, claude-code 2.1.219) and are fixture-tested including
+truncated-stream, API-error and rate-limit paths.
+
+### Live transcript for every backend
+
+Pressing `t` on a running run in `/subagents` previously assumed pi's session
+layout and entry schema, so codex/claude runs showed "waiting for child
+session…" forever. Vendor transcripts are now located by session id and
+rendered through per-backend renderers, with each vendor's boilerplate
+(codex's sandbox preamble, claude's queue bookkeeping) filtered out.
+
+Tests: 277 → 308.
+
+**Verified live:** codex end-to-end through the runner; the `max_cost` refusal
+message; codex's read-only sandbox blocking a shell write with "operation not
+permitted"; and both vendor transcripts tailing real on-disk session files.
+Claude's happy path is fixture-tested only — the development account was
+rate-limited during this work.
+
+## 0.5.1
+
+### `subagent_wait` — dedicated blocking-collect tool
+
+- New **`subagent_wait`** tool (`{ id, timeout_ms? }`) sits alongside `subagent`.
+  Collecting a background run is the one management step a model reaches for
+  reflexively mid-flow, and burying it behind the `action:` union cost a
+  discovery step. This matches the shape the highest-adoption package in the
+  ecosystem converged on (`pi-subagents` ships `subagent` + `subagent_wait`).
+- Implemented as a thin front-end that rewrites its arguments into the
+  equivalent `action:"wait"` request and reuses the main tool's `execute`, so
+  delivery / `markDelivered` / output-cap semantics cannot drift between the
+  two surfaces. `action:"wait"` remains fully supported.
+- **`timeout_ms`** added to the shared wait path (so `action:"wait"` gains it
+  too): on timeout the run is explicitly **not** cancelled and **not** marked
+  delivered, so it stays collectable by a later wait.
+
+### `/btw` — side questions hidden from the main agent
+
+- New **`/btw <question>`** command (or bare `/btw` for a prompt). The aside
+  runs as a normal subagent run — full policy, profile, budget, semaphore and
+  process-lock machinery — but its result is delivered with `pi.appendEntry()`
+  - an entry renderer, which by design does not participate in LLM context.
+    The user gets an answer rendered in the transcript while the main agent keeps
+    working, unaware of both question and answer.
+- Ported from [davis7dotsh/my-pi-setup](https://github.com/davis7dotsh/my-pi-setup)'s
+  by-the-way feature, adapted to our process-per-child model.
+
+Tests: 273 → 276. Both features' load-bearing invariants are mutation-checked.
+
+## 0.5.0
+
+### Native Pi cost accounting (pi#6671)
+
+- **Upward**: the tool result that delivers a run (foreground completion or
+  the first `wait`) now carries the run's total provider usage as a native
+  `usage` field. Pi builds after v0.80.10 persist it on the session entry and
+  fold it into the footer cost, `/session` statistics (`Tools/summaries`
+  bucket), and RPC `get_state` totals — resolving the undercount that
+  motivated [pi#6509](https://github.com/earendil-works/pi/issues/6509).
+  Attachment is delivered-flag gated: exactly once per run UUID; status,
+  replayed waits, steer, worktree actions, and plan responses never attach
+  usage. Older Pi hosts silently ignore the field (no minimum version bump).
+- **Downward**: tool-result messages in a child's event stream that carry
+  nested usage (e.g. grandchild subagents on a new-Pi child) now fold into
+  the run's cumulative usage, so `max_cost` budgets and the
+  root/subagent/combined ledger see true subtree spend. Pre-#6671 children
+  never emit the field; behavior there is unchanged.
+- Known native-total gaps documented in COST-ACCOUNTING.md: dismissed-without-
+  wait background runs and failed/lost runs (thrown errors carry no usage)
+  reach only the extension ledger.
+
+## 0.4.0
+
+### Agent ecosystem (PLAN phase 2)
+
+- **`spawns:` allowlist** in agent frontmatter (`false` / `"*"` / name list):
+  controls which agents a persona's children may spawn. The policy travels via
+  `PI_SUBAGENT_SPAWNS`; `spawns: false` children don't register the subagent
+  tool at all. Malformed env fails closed to disabled. Accidental-recursion
+  guard, not a security boundary (documented in SECURITY.md).
+- **`@include relative/path.md`** in agent bodies: one-level prompt
+  composition with the same 64KB/symlink guards as `@contract.json`;
+  missing/rejected includes stay verbatim.
+- **Resumable-session discovery**: bare `status` lists `session <id8>
+(resumable)` under completed runs; run-specific `status` shows full ids, and
+  the prompt guidelines mention `resume:`.
+- **`action: "plan"`** dry-run: full validation plus worktree/fork/output
+  preflights, returning the resolved per-task plan (model, tools, budgets,
+  isolation, notes) without spawning — same errors as the real call.
+
+### Engine hardening (PLAN phase 3)
+
+- **Depth-tiered global slots**: slot records carry `depth` and shallow tiers
+  reserve capacity for deeper ones, so a spawn tree wider than
+  `maxGlobalActive` can no longer deadlock while parents wait on children.
+  Old slot files without `depth` count as depth 0.
+- **`include_wip: true`** (worktree isolation only): seeds the worktree with
+  the parent checkout's uncommitted changes. `diff`/`apply` subtract the WIP
+  patch when clean, else report the combined delta with an explicit
+  `[includes parent WIP]` warning; an untouched WIP-only worktree counts as
+  unchanged and is cleaned up.
+- **Faster stale-lock reclaim**: a lease-expired cross-host (or unverifiable
+  foreign) owner is reclaimable after one lease period; the 2× window remains
+  only where clock skew is plausible (same host, identity unknown).
+- **Library-use warning**: `runSubagent()` without `locks` + `runId` writes no
+  durable run record (children invisible to orphan reclaim) — now documented
+  loudly in JSDoc and README.
+
+### Observability (PLAN phase 4)
+
+- **Live transcript view**: in `/subagents`, `t` on a running run tails the
+  child's session file (500ms poll, auto-follow, scroll-up pauses); `s` steer
+  works from the same view.
+- **`widget: "off"` / `notifications: "off"`** config keys (env
+  `PI_SUBAGENT_WIDGET` / `PI_SUBAGENT_NOTIFICATIONS`) for quiet mode.
+- Status previews append `[stalled <dur>]` and `[attempt N]` so background
+  polling surfaces watchdog/retry state without the overlay.
+
+## 0.3.1
+
+- Remove `publishConfig.provenance` (it blocked the one-time local bootstrap
+  publish of the new package name; OIDC publishes generate provenance
+  automatically). First release published end-to-end via Trusted Publishing
+  under `@parke.dev`.
+
+## 0.3.0
+
+### Structured results
+
+- **`output_schema`**: declare a JSON Schema per task (or in agent-file
+  frontmatter as inline JSON / `@contract.json`). 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 ignored). Invalid output triggers **one steer-based repair round**
+  before the child is allowed to settle; still-invalid results end `partial`
+  with `structuredError` and the raw text delivered — paid work is never
+  discarded. Valid results deliver as clean JSON and surface as
+  `details.results[].structuredOutput`.
+- **Typed synthesis handoff**: validated parallel results feed the `synthesis`
+  child as JSON blocks instead of prose tails, with per-task validity flags.
+- **Arg repair**: double-encoded task/system-prompt text (literal `\n`/`\"`
+  escapes) is conservatively de-mangled once at validation time; identifier
+  fields and path-like strings are never touched.
+- UI: terminal rows annotate `✓ schema` / `schema ✗`.
+
+## 0.2.1
+
+- **Package moved to `@parke.dev/pi-subagent`** (owned by the `parke.dev` npm
+  org). `@lukehagar/pi-subagent` is deprecated at 0.2.0 and will receive no
+  further updates; install the new scope with
+  `pi install npm:@parke.dev/pi-subagent`. No code changes besides the rename.
+- CI/release workflows on actions/checkout@v7 + actions/setup-node@v7;
+  CI matrix trimmed to supported LTS lines (22, 24); `engines.node` corrected
+  to `>=22.19.0` (the actual pi-coding-agent floor).
+
+## 0.2.0
+
+Major feature release: reliability engine, named agents, background-run UX,
+and a complete TUI overhaul.
+
+### Named agent files
+
+- Reusable subagent personas as markdown files with YAML frontmatter, discovered
+  from `.pi/agents/` (project), `.agents/agents/` (shared workspace), and
+  `$PI_CODING_AGENT_DIR/agents/` (global). Invoke with `agent: "name"`.
+- Body becomes the child's appended system prompt; frontmatter supplies defaults
+  (`model`, `thinking`, `profile`, `tools`, budgets, `fallback_models`, `isolation`).
+- Precedence per field: explicit params > agent file > per-profile `taskDefaults`
+  > parent inheritance. Capability profiles fail closed regardless of what an
+  > agent file declares.
+- Catalog advertised in the tool's system-prompt guidelines and live in bare
+  `status` output; file changes picked up within seconds.
+
+### Reliability
+
+- **Graceful budget stops**: at `max_turns`/`max_cost` the child is steered to
+  wrap up and given `grace_turns` (default 2) for a final answer before SIGTERM.
+  Results end `partial` with `wrappedUp: true` when the child concluded in time.
+- **Retry with model fallback**: transient failures (queue timeouts, stalls,
+  spawn errors, provider errors, protocol truncation) retry automatically up to
+  `max_retries` extra attempts, escalating through `fallback_models`. Usage
+  accumulates across attempts; `attempts`/`attemptedModels` recorded. Task-quality
+  failures never retry.
+- **Stall watchdog**: protocol silence for `stallAfterMs` (90s) flags the task
+  and probes liveness via `get_state`; continued silence for `stallKillAfterMs`
+  more kills the child (feeding retry) instead of burning the whole timeout.
+- **PID-reuse protection on macOS/BSD**: process start-time identity via
+  `ps -o lstart=`; group kills verify identity before signalling.
+
+### Orchestration
+
+- **Mid-run steering** (`action: "steer"`): children run in Pi RPC mode with a
+  live stdin command channel; inject guidance delivered after the current turn.
+- **Context forking** (`context: "fork"`): child starts from a real branched
+  copy of the parent conversation. Single-task only; fails fast when the parent
+  session is not persisted.
+- **Worktree loop**: `diff` / `apply` / `discard` actions on finished runs with
+  changed worktrees. `apply` lands the combined patch as uncommitted changes via
+  `git apply --3way`; never commits, never auto-deletes.
+- **Parallel synthesis** (`synthesis: "…"`): one read-only child folds parallel
+  outputs into a brief delivered first, with explicit truncation markers.
+- **Per-task `description`** labels and per-profile `taskDefaults` config
+  (model/thinking/budget routing without naming agents).
+
+### Background runs
+
+- **Completion notifications**: terminal async runs send a batched `followUp`
+  message so the parent reacts without polling. Successes group within a short
+  window; failures flush immediately; a consuming `wait` suppresses the
+  redundant notification. Themed compact box for humans.
+- **Ambient widget**: live above-editor tree (spinner, stats, activity tail)
+  for background runs only — foreground runs already render inline.
+
+### TUI overhaul
+
+- One-line `renderCall`; fixed-shape mutate-in-place streaming blocks; compact
+  terminal stats with state glyphs; per-task rows for parallel runs; frozen
+  durations at `endedAt`; reliability annotations (`[attempt 2]`,
+  `[stalled 2m]`, `◐ wrapped up`).
+- Terse footer (running/ready counts only); cost ledger moved to
+  `/subagent-cost`, `status`, and the `/subagents` overlay header.
+- Overlay rebuilt: themed header with counters + ledger, two-line list rows,
+  structured detail view, steering (`s`), worktree apply/discard (`a`/`x`).
+- Trailing-edge streaming flush (the last update of a burst always renders);
+  stable component identity across partial renders.
+
+### Performance
+
+- Transcript joins only on message boundaries (was O(N²) per stdout chunk).
+- Memoized per-result snapshot projection (only changed tasks re-project).
+- Trailing-edge coalescing for streamed tool updates.
+
+### Fixes
+
+- Resolve the Pi CLI entry through bin symlinks (npm/Homebrew shims) instead of
+  falling back to bare `pi` on PATH.
+- Headless children auto-cancel extension UI dialogs so they can never hang.
+- Prompt-rejection in RPC mode fails fast instead of idling forever.
+
+## 0.1.3
+
+- Require `type: object` tool schema for provider compatibility.
+
+## 0.1.2
+
+- Publish scoped `@lukehagar/pi-subagent` on npm; release workflow hardening.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Parke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.