@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/docs/performance.md

@@ -0,0 +1,121 @@
+# Long-session performance
+
+## Current behavior
+
+Native journals and canonical run/control/receipt files remain the sources of truth. SQLite supplies private browse observations, not a new execution owner, completion receipt, billing authority or transcript format. Installing the extension does not adopt unrelated archives or remove provider and queue waits.
+
+Startup recovers saved ownership, unanswered questions and Intercom receipts in small batches, allowing input between batches. Queued Intercom delivery also yields between batches, preserving followers before the final wake-up and staging new arrivals durably until the batch finishes. Retention cleanup uses asynchronous filesystem operations. Tools capture their invocation directory before awaiting restoration, and coordination publishes the current session name even if it changes during recovery. Checkpoint reconciliation remains synchronous and strict. Recovery still checks the complete eligible history and legacy records, without increasing or suppressing the host's performance-warning budget. A single recovery record, native append/projection or integrity scan remains atomic.
+
+### Indexed browsing and lazy Agents work
+
+- A separate Node process incrementally indexes only the current saved parent's admitted runs and linked native sources. A fresh session with no owned work starts no history process or database until it browses. No directory-wide transcript backfill runs at startup.
+- List filters and attention/newest/oldest ordering apply globally before a bounded page. Ordinary tool lists return 20 runs by default, at most 100; the Agents picker loads 50 runs and searches full assignments, not just shortened labels. Latest-assignment queries retain unsuperseded siblings while hiding older continuation attempts.
+- The parent UI does not scan child journals on startup, ticks, filtering or pagination. Only an opened conversation loads a 100-physical-record page; components are retained for that page. Full details and contextual Reply validate selected native byte references off-thread, including paired tool results outside the current page. Explicit navigation supersedes older requests; background refreshes are coalesced and retain the settled display rather than briefly adding loading rows. Reopening the picker restores its visible filter and page.
+- Catch-up, degraded sources, loading, no matches and unavailable history are distinct states. F5 explicitly retries. Drafts, reading anchors, unread boundaries and pins survive same-parent reopen; a changed owner or abandoned overlay cannot accept late results.
+- Search indexes saved visible text, not thinking, tool arguments, image payloads, hidden custom data or provider fields. Terminal sequences are removed incrementally before tokenization, including sequences split across read/parser chunks. Its grammar is lexical words or one quoted phrase. Unquoted words must all occur in the same native record, across any of its visible fields/windows; quoted phrases must remain contiguous in one field. Each record contributes one excerpt per matching child attempt. Filters and attempt terminal/time boundaries apply before ranking/paging. Common terms may still require broad matching and sorting: a small result page is not a constant-work guarantee. Deadlines and cancellation stop the owned history process, which can reopen and replay committed index progress.
+- Browse freshness is never authoritative. Selected controls recheck canonical owner facts before acting. Human-message delivery and a later nonempty assistant reply are separate observations. Receipt integrity and native accounting safeguards remain unchanged.
+
+### Storage, budgets and recovery
+
+History projections use the built-in `node:sqlite` binding, qualified at SQLite **3.53.4** with Node **24.21.0**, WAL and `synchronous=FULL`. Other binding versions fail explicitly rather than fall back to synchronous journal queries. Databases live in a private local-filesystem `history-index` directory; symlinked databases/directories are rejected. Each owner selects a disposable generation through its manifest. Corrupt browse generations are replaced without renaming/unlinking an open SQLite database or rewriting native sources; old generations remain private for diagnosis.
+
+Incremental ingestion has one writer per database generation, coordinated by a SQLite transaction in a separate private `.ingest.sqlite` database. The lock spans staging and publication but never locks the browse database between pump steps. Competing workers keep serving queries and retry without busy-spinning. Process exit releases the lock through SQLite; the next writer discards unpublished staging and resumes at the committed cursor, without PID leases, time-based lock stealing or unlinking open databases. Schema upgrades rebuild older derived indexes, including apparently current indexes affected by lost staging in schema 4.
+
+A published source cursor and its indexed entries commit together, and publication must actually update the staged entry before advancing the cursor. LF framing controls publication independently of malformed-record tolerance. Replacement, truncation, deletion and prefix changes invalidate observations. Ingestion scans bytes in bounded chunks and limits assembled previews to 64 levels, 16,384 nodes, 4,096 array positions and 512-character keys. Over-budget records are explicitly degraded, not silently converted into trustworthy evidence; later complete records still index. Selected full native records and canonical saved output have a **16 MiB** detail budget. Concurrent output growth cannot expand a selected read beyond its validated snapshot.
+
+Best-effort timeout samples use a separate `run-timing.sqlite` metadata database. Writer transactions serialize import, insertion and per-agent retention of the latest **1,000** samples. Read-only indexed queries never rotate storage. The old `run-history.jsonl` remains untouched; reads and the first actual writer's import use at most the latest **1 MiB** of complete LF records. This replaces the unlocked reader-side rotation that could erase concurrent writes or another agent's samples. It is a metadata migration, not a canonical run-state migration; older legacy samples remain on disk outside the estimation window.
+
+### Regression proof
+
+The changed boundaries are exercised through real extension functions and registered SDK tools with synthetic isolated data, not personal transcripts or provider inference:
+
+- 20 and 227 genuinely owned runs beside 8,000 unrelated records: Agents startup does no parent-thread child transcript reads or global question listing; only the selected conversation is formatted.
+- Native extension startup beside 2,048 foreign owner directories services input during discovery and restores only the current parent's saved runs and unanswered questions.
+- Native Intercom reload restores all 1,024 historical receipts while servicing input. Cleared-queue recovery also services input before its 100 followers finish appending, retaining each message once and one final wake-up across an in-flight reload or a cleared busy handoff. New results and explicit steers are staged before acknowledgement and handed to native steering for the next tool boundary; ordinary queued and passive arrivals wait.
+- 125 owned assignments: global filtering finds an item beyond the first two picker pages; all later pages remain reachable without UI-thread source access.
+- 65 retained runs: off-page reads/stats and migration scans are zero while displayed controls, questions, review and continuation identities remain fresh.
+- Warm indexed list/search queries perform no source checks, opens or canonical projections. Cold ingestion and explicit refresh still do necessary verification off-thread.
+- A 512 MiB discarded native field preserves exact eligible usage/IDs/configuration/history, with unchanged source bytes, under a **96 MiB** heap limit. Structural over-budget image/deep/key records degrade explicitly while later visible text remains searchable.
+- Completed-attempt search cannot return a successor's later text from a shared physical source. Full selected details reject missing/replaced/truncated sources; canonical output reads reject concurrent growth beyond their snapshot.
+- Competing history processes preserve staged configuration/text on normal completion and recover after a writer is killed. Schema-4 indexes with intact cursors but missing entries rebuild from unchanged journals.
+- Search covers ANSI-colored words, multi-chunk control sequences, distant terms in a single record, separate visible fields, phrase boundaries and record-level pagination. Picker reopen/clear retains a visible filter; delayed idle refreshes leave dock height unchanged.
+- Four independent timing writers preserve each completed sample, another agent's samples, per-agent retained row counts and database integrity. A legacy snapshot read cannot erase an acknowledged write.
+- Native tool loading covers list/history/search validation, owned paging and same-parent reload on both compact and advanced routes. UI regressions cover narrow/wide native layouts, full reports/Reply, loading navigation, saved anchors and disposal.
+
+Primary owners are `test/integration/{history-index,owned-run-list,agent-interaction,tool-activation,lazy-coordination,session-resume-cost}.test.ts` and `test/unit/{run-history,journal-reader,temp-root-cleanup}.test.ts`. Run the [local validation](../README.md#local-validation) against an explicitly selected coherent host graph. Operation counts are more repeatable than timing thresholds.
+
+## Receipt and loadout work
+
+A completion-recovery batch shares one SHA-verified parent receipt snapshot only within its synchronous stack. Parent append/count/leaf changes refresh that snapshot, and it is discarded before any awaited delivery resumes. Receipt identities are indexed once per snapshot; unchanged hits do not each hash the whole journal. The eight-hit regression beside a 1,051,980-byte parent reads at most three journal lengths (initial parse/hash, then verification per yielded batch), instead of verification per hit. Awaited delivery rechecks external journal changes even when the in-memory count and leaf are unchanged. SHA, LF publication, replacement/truncation and same-stamp-edit guards remain mandatory.
+
+Native default-active declarations keep advanced orchestration and Intercom lazy without startup deactivation. A small initial-SDK-resume fallback restores this package's declared tools because official 1.0 does not restore its saved loadout during creation. Native tree/reload selection remains authoritative, and activation only adds available owned tools, never excluded ones.
+
+The Agents dock polls while live work, questions, selected/pinned conversations or delivery outboxes need observation. Visited terminal rows reuse their observed metadata until their run changes; full completed history loads on selection. With 50 visited rows (49 terminal), two unchanged refreshes query only the live row; pinned, selected, question, outbox and changed terminal metadata remain observable. The 20/227-terminal-row fixtures also prove three idle ticks request no parent redraw. These are bounded-work optimizations, not archive-size or provider-latency guarantees.
+
+## Historical 0.43.1 baseline
+
+The earlier 0.43.1 fixes removed repeated completed-history projections, continuation recursion, native observation matching, nested polling, and result/receipt polling. Their same-host recheck on fork `76dfe3d1` (Node 24.21.0) remains useful historical evidence; it is not a measurement of the new SQLite browse implementation:
+
+| Synthetic operation | Before 0.43.1 | 0.43.1 |
+| --- | --- | --- |
+| 100 completed 2,000-entry histories, five refreshes | 1,000,000 timestamp parses; 1,005 ms | 0 timestamp parses; 1.6 ms |
+| 1,000 continuations, one visible task | 500,500 identity resolutions | 1,000 |
+| 10,000 delivered/billed runs, three polls | 30,003 existence checks | 3 directory checks |
+| 40 unchanged foreign files, three polls | 120 decodes | 40 initial decodes |
+| 20,000 parent entries, ten owner checks | 400,020 visits, 20 scans | 40,002 visits, two startup scans |
+| 1,500 retained nested events, unchanged poll | 500 event rereads and one registry rewrite | Neither |
+| Nested projection in one job poll | Three registry reads | One |
+| Ten 100-card history windows | 1,001 cached components | 101, including the assignment |
+
+Cold factory startup did not measurably change in that comparison: five isolated offline CLI launches ranged from 410–605 ms before and 411–437 ms after. The minimum difference was below run-to-run variation.
+
+## Necessary costs and limits
+
+Cold recovery still enumerates genuine owner handles and verifies relevant published bytes. Mutable native prefixes require integrity validation before appended suffix reuse; stat-only caches or unchecked SQL negative receipt lookups cannot replace that safeguard. Selected controls and canonical receipt/accounting reconciliation remain separate from browsing.
+
+Pi 1.0 still eagerly loads native session bodies at its own startup; extension installation alone cannot remove that host cost. Explicit fork context still copies and publishes each sibling, with required fsync. An explicit full individual record must fit its detail budget and the consumer's heap.
+
+Full-archive backfill/capacity, sustained contention, power-loss durability and cross-platform performance are not qualified by these macOS/APFS synthetic regressions. No journal deletion, live archive migration, installed-runtime activation or inference request is part of this work. Intentional tool/queue boundaries, provider response time, host rendering and other extensions remain separate possible costs.
+
+## Cached-input traffic and delegation
+
+This section supersedes the investigation in [PR #112](https://github.com/fitchmultz/pi-subagents/pull/112), which inspected `29903ad` before Pi 1.0 modernization. The architecture below was checked against released `4f288484` (0.44.0). No private session journals, invoices or provider requests were inspected. It explains possible traffic, not the cause of a particular account's usage or its dollar cost.
+
+### What grows the provider input
+
+- **Fresh is the default.** A fresh child starts without the parent's conversation. Project context, skills and the child's system prompt can still add substantial input. Explicit `context` overrides the profile; the bundled oracle alone defaults to `fork`. Inspect effective profiles and user/project overrides rather than assuming installed defaults.
+- **Fork is a branch, not a summary.** `src/shared/fork-context.ts` creates a separate native branched session per child index. The child uses inherited conversation context plus its new task, subject to Pi's native context/compaction rules and child filtering. Fork failure is explicit, not a fallback to the parent's file.
+- **Each child is a separate CLI tool loop.** Pi-backed children use `pi --mode json -p`; Claude-backed children use `claude -p`. Later model turns can send a large stable input prefix again. The extension does not implement provider prompt caching.
+- **Async work can overlap.** The root defaults to async, so the parent can continue making requests while children run. A fork is a launch-time snapshot; later parent turns do not update an already-running child.
+- **Filtering can change cache sharing.** Child context filtering removes parent-only orchestration messages and tool history where applicable. Native prompt fixtures prove unchanged-history prefix preservation and a changed prefix after filtering; neither is a guarantee that a provider will reuse a cache. A changed prefix does not establish that the entire context must be cache-written.
+- **Results can enlarge later input.** Inline results, chain substitutions, completion messages and supervisor notices add parent/next-child text. Some notices or deliveries can trigger a parent turn. Parallel completion is grouped; terminal async completion-guard notices leave the automatic wakeup to their matching result.
+- **Fanout is not a daily budget.** Top-level `tasks` uses `parallel.maxTasks` (default 8) after repeat expansion, with default concurrency 4. Static chain `parallel`/`count` is not covered by that top-level size limit. Dynamic fanout requires `expand.maxItems` or `config.chain.dynamicFanout.maxItems`; the per-step limit takes precedence. Bundled profiles disallow nested delegation; explicit opt-in remains depth-bounded. Successful sequential launches are not subject to a daily launch quota.
+
+Sources: `src/runs/{foreground/run-async-path,foreground/execution-input,shared/child-attempt,shared/subagent-prompt-runtime}.ts`, `src/shared/agent-context-policy.ts`, `agents/oracle.md`, and `test/fixtures/native-prompt-sections.mjs`.
+
+### Arithmetic, not attribution
+
+For a hypothetical constant **500,000 cached tokens per request**:
+
+```text
+4.26 billion cache-read tokens / 500,000 = 8,520 requests
+11.2 million output tokens / 8,520       = 1,314.55 output tokens/request
+```
+
+If "97% hit" means cached tokens divided by cached plus uncached input tokens, the corresponding uncached input is `4.26 billion × 0.03 / 0.97 = 131.75 million`, or about `15,463.92` per request. A request-based hit percentage would not support that calculation.
+
+| Hypothetical steady workload | Cache-read tokens |
+| --- | ---: |
+| One 500k-prefix session, one request/10 seconds for 24 hours | 4.32 billion |
+| Parent plus eight 500k-prefix children, one request/30 seconds each for 8 hours | 4.32 billion |
+| Eight 50k-prefix fresh children, one request/30 seconds each for 8 hours | 384 million |
+
+These assumptions include sustained activity and a full cache hit on that prefix; they are not measured workloads, throughput guarantees or pricing estimates. Token counts alone cannot establish dollars, double billing, a spawn loop, or which sessions made the requests.
+
+### Accounting and useful checks
+
+`src/runs/shared/native-usage.ts` excludes inherited launch-baseline entries and nonbillable checkpoints, then validates and deduplicates new native contributions. Excluding old journal usage does **not** make newly sending inherited context free. Pi 1.0 attribution uses finalized execution/wait tool results, not the removed `recordUsage` hook. Background notifications alone do not enter parent totals. Claude totals may remain explicitly accounting-incomplete when per-category evidence is unavailable. See [usage accounting](../README.md#usage-accounting); local attribution is not an additional provider request.
+
+To investigate an actual spike, compare provider usage for the relevant time/model/account with parent and child native usage, launch counts, effective `fresh`/`fork` settings and context sizes. Do not sum attributed parent totals and the same child totals as independent traffic. Keep private prompts, journals and credentials out of public issues.
+
+Use existing controls deliberately: prefer fresh context when a bounded handoff suffices, use file-only output when the parent needs references rather than full text, and set suitable concurrency and child runtime/token limits. `maxTokens` is best-effort and is not an invoice or whole-account spending cap. This investigation changes no profile defaults, fork capability, notice routing or quotas.

package/package.json

@@ -1,6 +1,103 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.44.4",
+  "description": "Pi extension for subagent orchestration and local session coordination",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitchmultz/pi-subagents.git"
+  },
+  "homepage": "https://github.com/fitchmultz/pi-subagents#readme",
+  "bugs": {
+    "url": "https://github.com/fitchmultz/pi-subagents/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "subagents",
+    "ai",
+    "agents",
+    "cli",
+    "intercom",
+    "coordination"
+  ],
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "tsconfig.build.json",
+    "tsconfig.json",
+    "scripts/",
+    "agents/",
+    "skills/**/*",
+    "prompts/**/*",
+    "docs/intercom.md",
+    "docs/performance.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "prepare": "node ./scripts/prepare.mjs",
+    "test": "npm run test:unit",
+    "test:unit": "node scripts/run-tests.mjs unit",
+    "test:integration": "node scripts/run-tests.mjs integration",
+    "test:all": "node scripts/run-tests.mjs all",
+    "check:compat": "node scripts/check-compat.mjs",
+    "typecheck": "tsc --noEmit",
+    "smoke:package": "node scripts/package-smoke.mjs",
+    "smoke:install": "node scripts/local-install-smoke.mjs",
+    "ci": "npm run typecheck && npm run smoke:package && npm run smoke:install && npm run test:all",
+    "smoke:real-pi": "node scripts/real-pi-smoke.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension/index.js",
+      "./dist/pi-intercom/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
+    "@types/node": "24.19.1",
+    "typebox": "1.3.34",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": {
+    "node": ">=24.21.0"
+  },
+  "dependencies": {
+    "stream-json": "3.7.0"
+  }
+}

package/prompts/gather-context-and-clarify.md

@@ -0,0 +1,14 @@
+---
+description: Use subagents to gather context, then ask clarifying questions
+argument-hint: "[request]"
+---
+
+Based on our discussion and my intent, launch focused context-gathering subagents before planning or implementing.
+
+Use `scout` to inspect the relevant local files, existing patterns, constraints, tests, and likely integration points. Use `researcher` when external docs, recent sources, ecosystem context, or primary evidence would improve the answer.
+
+Give each subagent a specific meta prompt. Ask them to return concise findings plus the remaining clarification questions that matter for implementation confidence.
+
+After they return, synthesize what we know and use the available clarification tool (`ask_question` in pi) to ask only unresolved questions that affect scope, acceptance, constraints, or implementation.
+
+${ARGUMENTS:-infer the request from the current conversation and repository context}

package/prompts/parallel-cleanup.md

@@ -0,0 +1,62 @@
+---
+description: Parallel cleanup review
+argument-hint: "[scope]"
+---
+
+Run a fresh-context parallel cleanup review of the current work.
+
+Use the `subagent` tool. First inspect available agents/skills if needed, then launch two reviewer subagents in parallel with `context: "fresh"`. Do not use forked context unless I explicitly ask for it. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history.
+
+Launch cleanup reviewers as separate async runs so each completion wakes the parent. Continue useful parent work while they run; if none remains, end the turn and wait instead of polling. This also applies when an incomplete active Pi goal needs cleanup review: resume the goal after automatic completion delivery, not before the evidence arrives. Omit `acceptance` from these review-only tasks unless I explicitly request a same-session acceptance contract; it adds a finalization turn and does not provide independent review. A timed-out reviewer is incomplete review, never sign-off.
+
+Do not write reviewer output files into the repository unless I explicitly ask for artifacts. Prefer `output: false` for each reviewer task.
+
+Reviewer 1: deslop pass.
+
+If the `deslop` skill is available, pass it to this reviewer. If not, inline the guidance below. Ask this reviewer to look for AI-slop patterns in the changed scope:
+- comments that restate code, placeholder text, stale rationale, or debug leftovers;
+- defensive checks that hide useful errors, return vague defaults, or validate trusted internal data after a real boundary was already crossed;
+- type escapes, broad casts, duplicated type definitions, or object-bag typing where a local source-of-truth type exists;
+- style drift from nearby non-slop code and project instructions;
+- generated-sounding docs, changelog text, UI copy, status text, or test names;
+- pass-through wrappers, dead helpers, duplicate helper signatures, duplicated test harness setup, or abstractions that do not enforce an invariant;
+- UI or CLI copy that is noisy, vague, brittle, or makes the user do extra interpretation.
+
+Tell this reviewer to treat tool output and slop-scan-style findings as leads, not verdicts. It should flag only concrete issues in the requested scope with evidence, severity, file/line references, and the smallest safe fix.
+
+Reviewer 2: verbosity pass.
+
+If the `verbosity-cleaner` skill is available, pass it to this reviewer. If not, inline the guidance below. Ask this reviewer to look for needless verbosity in code, tests, docs, status text, grouped messages, receipts, and changelog wording:
+- single-use helpers that merely paraphrase an expression;
+- temporary variables that only name obvious expressions;
+- nested returns or branches that can become direct returns without hiding intent;
+- multi-line cleanup scaffolding that can use a local direct pattern while preserving cleanup semantics;
+- repeated boilerplate that can use an existing local fixture or a small local helper;
+- tests that restate formatter details already covered at a cheaper layer;
+- regression tests where one focused assertion would cover the bug but wrapper/API-adjacent tests only repeat the same claim;
+- prose that says the same thing twice, sounds generic, or buries the important rule.
+
+Tell this reviewer that shorter is only better when it is clearer and preserves behavior, error signals, cleanup semantics, useful invariants, and local style.
+
+Both reviewers are review-only. They must not edit files unless I explicitly ask for a writer pass. Their response should be review feedback, not a context summary. Ask them to return concise, evidence-backed findings with file/line references and suggested fixes.
+
+While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Do not blindly apply every reviewer suggestion.
+
+Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not cleanup scope. Remove it before deciding the cleanup target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+
+Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+
+```text
+Reply with [1], [2], or further instructions:
+[1] Apply only the fixes worth doing now.
+[2] Apply the fixes worth doing now plus optional improvements.
+```
+
+Additional scope or focus from the template invocation:
+
+$@

package/prompts/parallel-context-build.md

@@ -0,0 +1,56 @@
+---
+description: Parallel context builders for planning handoff
+argument-hint: "[request]"
+---
+
+Launch fresh-context `context-builder` subagents in parallel to build grounded handoff context for planning or implementation.
+
+Use the `subagent` tool in chain mode with a single parallel step, not top-level parallel tasks, so relative output files live under the temporary chain directory. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, `label`, and `as` name, for example:
+
+- `context-build/request-and-scope.md`
+- `context-build/codebase-and-patterns.md`
+- `context-build/validation-and-risks.md`
+
+Use one phase such as `phase: "Context build"` for the parallel tasks so async status is readable. A later synthesis step can reference specific outputs with `{outputs.requestScope}`, `{outputs.codebasePatterns}`, and `{outputs.validationRisks}` instead of relying only on `{previous}`.
+
+Do not write these context artifacts into the repository unless I explicitly ask for persistent files.
+
+Treat the template arguments as the primary request, target, or focus:
+
+${ARGUMENTS:-infer the planning handoff scope from the current conversation and repository context}
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform request, read or fetch that target before assigning builder angles, then pass the target explicitly into every `context-builder` task.
+
+Choose two or three strong builders based on the request. Prefer three only when the scope benefits from independent context slices. These are examples, not fixed defaults:
+
+1. Request and scope
+   Clarify the actual goal, user intent, constraints, non-goals, open questions, and decisions that affect the handoff.
+
+2. Codebase and patterns
+   Inspect relevant files, call paths, existing abstractions, tests, package constraints, and local conventions that the next agent must follow.
+
+3. Validation and risks
+   Identify likely failure modes, edge cases, test strategy, commands to run, dependency/API concerns, and escalation rules.
+
+Adapt the angles when the request calls for it:
+- Issue or PR URL: include issue requirements, acceptance criteria, linked discussion, and likely affected files.
+- Plan file: include plan consistency, missing context, implementation sequence, and validation readiness.
+- External API/library work: include current docs or primary sources through `web_search` when needed.
+- Large refactor: include module boundaries, dependency direction, migration/cutover risks, and testability.
+- UI/product work: include user flow, accessibility, copy, visual constraints, and implementation touchpoints.
+
+Ask each builder to produce a compact handoff file with:
+- relevant files and line ranges;
+- key snippets or patterns, not full dumps;
+- constraints and invariants;
+- risks and unknowns;
+- validation commands or next-best checks;
+- a `meta-prompt` section for the next planner or role subagent.
+
+After the builders return, synthesize their outputs into:
+- the most important context the next agent needs;
+- the recommended meta-prompt to use next;
+- open questions or assumptions;
+- the output artifact paths.
+
+Do not start implementation from this command unless I explicitly ask for it.

package/prompts/parallel-handoff-plan.md

@@ -0,0 +1,62 @@
+---
+description: Parallel research/context builders into an implementation handoff plan
+argument-hint: "[request]"
+---
+
+Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final implementation-ready meta-prompt.
+
+Primary request, target, or focus:
+
+${ARGUMENTS:-infer the implementation handoff scope from the current conversation and repository context}
+
+Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
+
+Use the `subagent` tool in chain mode:
+
+1. First step: a parallel group.
+   - `researcher`, when the request includes external references, APIs, libraries, docs, current best practices, or prompt-guidance research.
+   - `context-builder` for local codebase context.
+   - Add a second `context-builder` only when the scope is large enough to benefit from a separate implementation-strategy pass.
+
+2. Second step: a synthesis `context-builder` that reads the parallel findings and writes the final handoff plan and meta-prompt.
+
+Use distinct output paths, `label` values, and `as` names under the chain directory. Example outputs:
+- `handoff/external-reference.md`
+- `handoff/local-context.md`
+- `handoff/implementation-strategy.md`
+- `handoff/final-handoff-plan.md`
+
+Use phases such as `Research`, `Local context`, and `Synthesis` so async status is readable. Prefer `{outputs.externalReference}`, `{outputs.localContext}`, and `{outputs.implementationStrategy}` in the synthesis task when those specific inputs are available; keep `{previous}` only when the whole parallel fan-in summary is the desired input.
+
+Do not write these artifacts into the repository unless I explicitly ask for persistent files.
+
+Role guidance:
+
+External reference researcher:
+- Study linked projects, docs, issues, examples, source code, or prompt guidance.
+- Identify the behavior, API, implementation files, constraints, and transferable ideas.
+- Conduct web research if needed. Use `web_search` if it is available; otherwise use whatever equivalent research capability is available.
+- Return source links, repo paths, key evidence, risks, and what matters for this implementation.
+
+Local context-builder:
+- Read all files needed to fully understand the local issue, not just the first match.
+- Follow imports, callers, tests, fixtures, configuration, docs, and adjacent patterns until the local problem, solution space, and validation path are clear.
+- Return relevant file paths and line ranges, current architecture, constraints, tests, risks, and open questions.
+
+Implementation-strategy context-builder, when used:
+- Compare the external evidence against the local architecture.
+- Propose the safest implementation shape, files likely to change, edge cases, validation commands, and decisions that need approval.
+- Stay review/planning-only unless I explicitly ask for implementation.
+
+Final synthesis context-builder:
+- Read the parallel outputs and produce one concise handoff plan.
+- Include what the feature/change should do, what the external reference teaches, what the local codebase implies, the recommended approach, likely files to change, constraints, non-goals, validation, risks, and unresolved questions.
+- End with a compact implementation-ready meta-prompt for the next worker/planner.
+
+After the chain returns, synthesize the result for me with:
+- the recommended approach;
+- artifact paths;
+- the final meta-prompt;
+- any questions or assumptions that remain.
+
+Do not start implementation from this command unless I explicitly ask for it.

package/prompts/parallel-research.md

@@ -0,0 +1,51 @@
+---
+description: Parallel subagents research
+argument-hint: "[question]"
+---
+
+Launch parallel research subagents to build a grounded answer to the current question or decision.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Researchers and scouts should inspect sources directly instead of relying on the main conversation history.
+
+Use a combination of `researcher` and `scout` subagents:
+- Use `researcher` for web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
+- Use `scout` for local codebase context, existing implementation patterns, repo constraints, and files that would be affected.
+
+Give each subagent a distinct angle. Unless I specify angles, use these three:
+
+1. External evidence
+   Use `researcher` to find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
+
+2. Local code context
+   Use `scout` to inspect the repository for relevant files, existing patterns, constraints, tests, and likely integration points.
+
+3. Practical tradeoffs
+   Use `researcher` or `scout`, whichever fits the question, to compare options, risks, edge cases, maintenance cost, and what would be easiest to validate.
+
+Adapt the angles when the question calls for it:
+- Library/API questions: include official docs and recent examples.
+- Architecture decisions: include local module boundaries, dependency direction, and migration cost.
+- Debugging questions: include likely failure modes, local call paths, and exact error evidence.
+- UI/product questions: include user flow, accessibility, design precedent, and implementation constraints.
+- Time-sensitive topics: include a recent-developments angle and prefer 2026/2025 sources.
+
+Prefer two or three strong subagents over many vague ones. The parent agent should frame the question and assign angles; the child agents should research or scout, not invent broad plans.
+
+Ask each subagent to return concise findings with evidence:
+- file paths and line ranges for local findings
+- source links for external findings
+- confidence level and gaps
+- recommended next step or decision implication
+
+Do not ask subagents to edit files. This is a research pass only unless I explicitly ask for implementation.
+
+After the subagents return, synthesize the answer into:
+- what we know
+- what the local codebase implies
+- tradeoffs and risks
+- gaps or assumptions
+- the recommended next move
+
+If findings disagree, call out the disagreement instead of smoothing it over.
+
+$@

package/prompts/parallel-review.md

@@ -0,0 +1,59 @@
+---
+description: Parallel subagents review
+argument-hint: "[scope]"
+---
+
+Launch parallel reviewers for an adversarial review of the current work.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Reviewers should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
+
+Prefer separate async reviewer runs so each completion wakes the parent instead of waiting for the whole panel. Continue useful parent work while they run; if none remains, end the turn and wait instead of polling. This also applies when an incomplete active Pi goal needs reviewer evidence: resume the goal after automatic completion delivery, not before the evidence arrives. A timed-out reviewer is incomplete review, never sign-off; rerun, resume, or split the review.
+
+Omit `acceptance` from review-only tasks unless I explicitly request a same-session acceptance contract. Acceptance adds a finalization turn and does not provide independent review.
+
+Give each reviewer a distinct angle. Generate the angles dynamically from the user's intent, the plan, the implemented code, and the current diff. If I specify angles, use mine. Otherwise, choose the highest-value review angles for this specific work.
+
+These are examples, not fixed defaults:
+
+1. Correctness and regressions
+   Check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures.
+
+2. Tests and validation
+   Check whether tests or validation were added at the right layer, whether assertions are meaningful, and whether the chosen verification commands are enough.
+
+3. Simplicity and maintainability
+   Check for unnecessary complexity, duplicate structure, single-use wrappers, brittle abstractions, confusing names, verbosity, and cleanup that is clearly worth doing.
+
+Choose or adapt angles when the work calls for it:
+- TypeScript-heavy changes: include type safety, source-of-truth types, casts, and error-boundary discipline.
+- UI-heavy changes: include UX, accessibility, copy, and visual quality.
+- Security-sensitive changes: include unsafe input/output handling, auth boundaries, privacy, and data exposure.
+- Docs-heavy changes: include clarity, accuracy, completeness, reader flow, and non-robotic prose.
+- Large multi-file changes: consider a fourth reviewer for structural friction, module boundaries, and testability.
+
+Prefer three strong reviewers over many vague reviewers.
+
+Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+
+While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- fixes worth doing now
+- optional improvements
+- feedback to ignore or defer, with a short reason
+
+Do not blindly apply every reviewer suggestion.
+
+Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not review scope. Remove it before deciding the review target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+
+Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+
+```text
+Reply with [1], [2], or further instructions:
+[1] Apply only the fixes worth doing now.
+[2] Apply the fixes worth doing now plus optional improvements.
+```
+
+Additional review target or focus from the template invocation:
+
+$@
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform focus, treat it as the primary review scope. Read or fetch that target before assigning reviewer angles, and pass the target explicitly into each reviewer task.

package/prompts/review-loop.md

@@ -0,0 +1,42 @@
+---
+description: Review/fix loop until clean
+argument-hint: "[work-scope]"
+---
+
+Run a parent-orchestrated review loop for the requested work.
+
+Use the `subagent` tool. Keep the parent session as the loop controller and final decision-maker. Child subagents must receive concrete role-specific tasks. Bundled profiles are leaf agents, so routine fanout stays in the parent. Only an explicitly delegation-enabled profile may use helpers within its assigned scope, role authority, and native depth budget; it must not take over the parent's review loop.
+
+Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no blockers or fixes worth doing now.
+
+If the invocation includes an implementation request, first launch one default-async `worker` to implement the approved scope. If the current diff is already the target, start with review. Keep the loop in the parent as follow-up runs after each completion; do not put reviewer panels inside one async chain because the aggregate result hides individual reviewer completions. Use only one writer against a shared active worktree at a time; use isolated worktrees for independent parallel writers when helpful.
+
+For each review round, launch fresh-context `reviewer` agents as separate async runs so each completion wakes the parent. Continue useful parent work while they run; if none remains, end the turn and wait instead of polling. This also applies when an incomplete active Pi goal needs reviewer evidence: resume the goal after automatic completion delivery, not before the evidence arrives. Omit `acceptance` from review-only tasks unless I explicitly request a same-session acceptance contract; it adds a finalization turn and does not provide independent review. A timed-out reviewer is incomplete review, never sign-off. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history and must not edit files.
+
+Choose review angles from the actual change. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability. Add security, performance, docs/API contracts, or user-flow validation when the work calls for it. Prefer three strong reviewers over many vague reviewers.
+
+After reviewers return, synthesize their feedback into:
+- concrete blockers or decisions outside the existing authority;
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Do not blindly apply every reviewer suggestion. Make ordinary reversible fix decisions within the existing implementation authority. Ask only when a finding requires unavailable information or authority, changes the owner's settled outcome or scope, or crosses a concrete irreversible-loss, private-data, or substantial new-cost boundary.
+
+When an async implementation worker completes, treat its handoff as the transition into review, not as final completion, unless I explicitly asked for worker-only work, review-only output, or to stop after implementation.
+
+When there are fixes worth doing now and the workflow is implementation-authorized, launch one default-async `worker` to apply only those synthesized fixes. Ask it to preserve the approved scope, run focused validation, and report changed files, commands run with exit codes, validation evidence, surprises, and anything left undone.
+
+After a fix worker returns, run another review round only when it made material changes or addressed non-trivial findings. Do not keep looping for optional polish, speculative improvements, or findings already deferred by the parent.
+
+Stop and summarize when one of these is true:
+- reviewers find no blockers or fixes worth doing now;
+- remaining feedback is optional, speculative, or intentionally deferred;
+- reviewers surface a concrete decision outside the existing authority that needs me;
+- the max review-round cap is reached.
+
+On completion, inspect the final diff yourself, run or confirm focused validation where appropriate, and summarize the loop: rounds run, fixes applied, validation, remaining deferred items, and why the loop stopped.
+
+Additional target, implementation request, max-iteration cap, or review focus from the template invocation:
+
+$@