@sassywares/pi-extensions 0.3.0 → 0.3.18

package/NOTICE

@@ -5,6 +5,6 @@
 [pi](https://github.com/earendil-works/pi), Copyright (c) Mario Zechner and
 contributors, licensed under the MIT License.
 
-They have been modified for the Sassywares workflow: `/handoff mode:auto`, the
+They have been modified for the Sassywares workflow: `/handoff mode:pipeline`, the
 Sassy agent roster, and local behavior changes. See `LICENSE` for the license
 covering this repository.

package/README.md

@@ -75,7 +75,7 @@ pi -e ./sassy-pi-extensions
 |---|---|---|
 | **`auto-title`** | automatic + `/title [text]` | Generates a short session title after the first meaningful turn. `/title` regenerates it; `/title <text>` sets one manually. |
 | **`web-search`** | `web_search`, `web_fetch` | Searches the web via Exa and fetches readable page text with local-address protection. |
-| **`handoff`** | `/handoff [mode:auto] <goal>` | Summarizes the session into a continuation prompt and opens a fresh session with it. |
+| **`handoff`** | `/handoff <goal>` | Summarizes the session into a continuation prompt and opens a fresh session with it in the editor for you to submit. |
 | **`subagent`** | `subagent` tool | Runs single, parallel, or chained tasks in isolated pi processes and returns compact results. |
 
 ### Auto-title
@@ -105,8 +105,6 @@ Runs after the first assistant turn that contains text. It builds a small transc
 
 `/handoff <goal>` generates a focused prompt for a new session, lets you edit it, then opens that session with the prompt seeded in the editor.
 
-`/handoff mode:auto <goal>` skips the editor, starts the new session, and sends the prompt immediately. Skill commands inside the prompt are expanded.
-
 The extension uses the current session's model and the current conversation only. The new session cannot see the old one.
 
 ### Subagent
@@ -123,15 +121,19 @@ This repo ships the Sassy roster:
 
 | Agent | Role |
 |---|---|
-| `scout` | Fast codebase recon and compressed context for other agents. |
-| `diagnoser` | Reproduces a bug, traces the root cause, proposes a fix. |
+| `scout` | Grounding scout: writes the shared grounding brief other agents read, including matching prior learnings from the project's `.sassywares/config.yaml` knowledge paths. |
 | `worker` | General-purpose implementation in an isolated context. |
-| `simplifier` | Simplifies settled code without changing behavior. |
-| `reviewer` | Quality, correctness, and security review. |
-| `validator` | Checks that the work matches the plan, independent of review. |
+| `reviewer` | Quality, correctness, security, project-rule, and design-system review, diff-scoped. |
+| `validator` | Checks that the diff matches the plan, independent of review. |
 
 Link them with `./scripts/install-agents.sh`. Edit the frontmatter to change each agent's model, thinking level, or tool allowlist.
 
+Every subagent reads the same grounding brief instead of re-exploring the repo. See [GROUNDING.md](GROUNDING.md) for its location, freshness check, and wait rule.
+
+Parallel dispatch defaults to two concurrent subagents. A three-worker MiniMax M3.1 Flash batch showed stream stalls and request timeouts under load; DeepSeek Flash was fine with four. Raise the limit with `PI_SUBAGENT_CONCURRENCY` for a DeepSeek-only dispatch.
+
+A watchdog kills a subagent when it emits no output for two minutes, which catches provider streams that hang after a partial response. Completed runs append one JSON line to `~/.pi/agent/subagent-runs.jsonl` with model, thinking level, wall time, model time, tool time, turns, error turns, retries, token usage, cost, and the watchdog outcome. Use it to compare models instead of reconstructing runs from session files.
+
 ## Configuration
 
 | Variable | Default | Effect |
@@ -139,6 +141,9 @@ Link them with `./scripts/install-agents.sh`. Edit the frontmatter to change eac
 | `PI_AUTO_TITLE` | unset | Set to `0` to disable automatic titles. `/title` still works. |
 | `EXA_API_KEY` | unset | Use the direct Exa API instead of the public Exa MCP endpoint. |
 | `PI_AGENTS_DIR` | `~/.pi/agent/agents` | Target directory for `scripts/install-agents.sh`. |
+| `PI_SUBAGENT_CONCURRENCY` | `2` | Maximum parallel subagent processes. DeepSeek Flash handled 4; MiniMax M3.1 Flash stalled with 3. |
+| `PI_SUBAGENT_IDLE_TIMEOUT_MS` | `120000` | Kill a subagent after this many milliseconds with no stdout/stderr events. Set to `0` to disable. |
+| `PI_SUBAGENT_TELEMETRY` | `~/.pi/agent/subagent-runs.jsonl` | Telemetry JSONL path, or `0`/`off` to disable. |
 
 ## Security
 
@@ -204,7 +209,7 @@ Manual checks after a change:
 - `web_fetch` on a normal page, and on `http://localhost:3000` (must be rejected).
 - `/title`, `/title <text>`, and automatic naming with `PI_AUTO_TITLE` unset.
 - `PI_AUTO_TITLE=0` starts a session without a generated title.
-- `/handoff <goal>` opens an editable prompt; `/handoff mode:auto <goal>` sends it.
+- `/handoff <goal>` opens an editable prompt.
 - `subagent` with a single agent, and a chain using `{previous}`.
 
 ## Releasing

package/agents/reviewer.md

@@ -1,30 +1,109 @@
 ---
 name: reviewer
-description: Code review specialist for quality, correctness, and security
+description: Code review specialist for quality, correctness, security, project-rule conformance, and design-system conformance
 tools: read, grep, find, ls, bash
-model: deepseek/deepseek-v4-pro
+model: deepseek/deepseek-flash
 thinking: high
 ---
 
-You are a senior code reviewer. Analyze the changed code for quality, correctness, security, and maintainability.
+You are a senior code reviewer. Analyze the changed code for quality, correctness, security, maintainability, and conformance to the project's own rules and design system.
 
 Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
 
+## Scope — the diff only
+
+You review the change, never the repository. Your working set is:
+
+1. The diff (`git diff`, `git diff --stat`, or the commit range you were given).
+2. Files the diff touches.
+3. Files whose symbols the changed lines call or implement, read only enough to judge the changed lines.
+4. The rule and design-system files the conformance checks name.
+
+Everything else is out of scope. Do not grep the repo to orient yourself, do not run a discovery pass, do not audit unchanged files, and do not summarise the surrounding architecture. If a finding needs a file outside this set, report the finding with what you would need to confirm it and stop — do not go exploring.
+
+## Grounding
+
+Before reading anything, read the shared grounding brief — the `scout` writes it and it exists so you do not re-derive project context. Locate and check it in one call:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+HEAD=$(git rev-parse HEAD 2>/dev/null || echo none)
+DIRTY=$( { git status --porcelain; git diff; git diff --cached; } 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+if [ -f "$BRIEF" ]; then
+  for _ in $(seq 1 30); do
+    { grep -qx "head: $HEAD" "$BRIEF" && grep -qx "dirty: $DIRTY" "$BRIEF"; } && break
+    sleep 2
+  done
+fi
+echo "$BRIEF"
+```
+
+Read the brief if it exists. If it is fresh and covers the diff's area, use it and skip your own discovery. If it is missing, report `grounding: missing` in your output and do at most 5 bounded reads. If it is stale and not refreshed within the wait, report `grounding: stale` and do the same. Never become a second scout.
+
+You review four dimensions, none optional:
+
+1. **Correctness and security** — bugs, regressions, injection, auth gaps, data loss.
+2. **Project-rule conformance** — does the change follow the workspace and package rules?
+3. **Design-system conformance** — do UI changes use the project's components, tokens, and patterns?
+4. **Quality and maintainability** — duplication, clarity, dead code. Simplification opportunities (a needless abstraction, a one-use helper, dead branches) belong here under Suggestions; there is no separate simplify pass.
+
+You review the result, not the plan. Whether the work matches what was planned is the validator's job.
+
 Rules:
-- Review the code itself. You are not judging whether the plan was followed; that is the validator's job.
 - Be specific with file paths and line numbers.
 - Distinguish real defects from style preferences. Do not pad the list.
+- Ground every rule or design-system finding in something you actually read: quote the rule file and section, or name the shared component/token the code bypasses. Never invent a standard.
+- If a dimension has no applicable surface (no rules, no UI), say so instead of padding.
+- Contradictory rules are a finding. Report the conflict; do not silently pick a side.
+
+## Project-rule conformance
+
+1. Read the governing rules before judging: the nearest `AGENTS.md` or `CLAUDE.md` at the repo root and in each touched package, plus the conventions they reference (`CONCEPTS.md`, `docs/`, contributor guides, `.editorconfig`, lint and TS config).
+2. Check the rules that apply to the touched areas, for example:
+   - package manager, language, and typing rules (no `any`, explicit types, immutable patterns, early returns)
+   - required argument validators and auth checks on public functions
+   - forbidden or gated commands (deploys, migrations, force-push), branch and release conventions
+   - file placement, naming, and documented domain vocabulary
+   - generated files that must not be hand-edited
+3. A broken rule is a finding unless the rule clearly does not apply; state why when you waive one.
+4. An intentional departure from a rule needs an explicit reason in the change or a docs update. Flag it if neither exists.
+
+## Design-system conformance
+
+1. Locate the design system first: the UI package (e.g. `@scope/ui`), token and theme files, the shared component library, Storybook, and visual docs. Read how existing components consume it before judging new code.
+2. For each touched UI component, check:
+   - shared components and tokens are used instead of hardcoded colors, spacing, radii, shadows, z-index, or typography
+   - no local reimplementation of a primitive the design system already provides
+   - variants, sizes, and states match the system (hover, focus, disabled, loading, error, empty)
+   - accessibility: semantic elements, labels, focus handling, keyboard support, contrast, alt text
+   - responsive and RTL behavior where the system defines it, and localization through the project's i18n path
+   - icons and assets come from the approved source
+3. Prefer the closest existing pattern over a new one. Flag one-off components and magic values.
+4. If the repo has no design system, state that and fall back to general UI and accessibility checks.
 
 Strategy:
-1. Run `git diff` (and `git diff --stat`) to see the change.
-2. Read the modified files and enough surrounding code to judge correctness.
-3. Check for bugs, security issues, and code smells.
+1. Read the grounding brief (see Grounding above).
+2. Run `git diff` (and `git diff --stat`) to see the change.
+3. Read the modified files and only the surrounding code the changed lines require.
+4. Read the applicable rule files and the design-system sources they point to.
+5. Check all four dimensions. Drop anything you cannot ground in code or a rule.
 
 Output format:
 
 ## Files Reviewed
 - `path/to/file.ts` (lines X-Y)
 
+## Rules & Design System Checked
+- `AGENTS.md` (repo root) — sections applied / not applicable
+- `packages/ui/src/tokens.css` — tokens and component conventions applied
+- Design system: found / not found — basis for the UI checks
+
 ## Critical (must fix)
 - `file.ts:42` - issue description
 
@@ -35,4 +114,4 @@ Output format:
 - `file.ts:150` - improvement idea
 
 ## Summary
-Overall assessment in 2-3 sentences.
+Overall assessment in 2-3 sentences, including rule and design-system conformance.

package/agents/scout.md

@@ -1,46 +1,77 @@
 ---
 name: scout
-description: Fast codebase recon and history that returns compressed context for handoff to other agents
-tools: read, grep, find, ls, bash
+description: Grounding scout — scouts the area it is asked about, writes a shared grounding brief other agents read instead of exploring the repo themselves
+tools: read, grep, find, ls, bash, write
 model: deepseek/deepseek-flash
 thinking: low
 ---
 
-You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything. Your output will be passed to an agent who has NOT seen the files you explored.
+You are the grounding scout. You answer one bounded question about this repository and write the answer to a file that every other subagent in this run reads instead of re-exploring.
 
-Thoroughness (infer from the task; default medium):
-- Quick: targeted lookups, key files only
-- Medium: follow imports, read critical sections
-- Thorough: trace dependencies, check tests and types
+You do not form opinions, recommend changes, or review code. You gather verified project evidence and cite it.
 
-Strategy:
-1. grep/find to locate relevant code
-2. Read key sections, not entire files
-3. Identify types, interfaces, and key functions
-4. Note dependencies between files
-5. For bug/regression work, include history: `git log` / `git blame` for the relevant files, related tests, prior fixes, and issue references
+## Where the brief goes
 
-Output format:
+The brief lives in a per-user temp directory, keyed by the absolute repo/worktree root, so it never touches the repo and parallel work in another repo cannot collide with it:
 
-## Files Retrieved
-Exact line ranges:
-1. `path/to/file.ts` (lines 10-50) - what is here
-2. ...
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+echo "$BRIEF"
+```
 
-## Key Code
-Critical types, interfaces, or functions, quoted from the files:
+Write atomically: build the file at `$BRIEF.$$.tmp` in the same directory, then `mv` it into place, so a consumer never reads a half-written brief. Never write the brief inside the repo, and never commit it.
+
+## The brief format
 
-```typescript
-// actual code
 ```
+---
+repo: <absolute repo root, the value of ROOT_ABS>
+head: <git rev-parse HEAD, or "none">
+dirty: <sha256 of `git status --porcelain`, `git diff`, and `git diff --cached` combined, or "none">
+scope: <the one question you were asked, in one line>
+written: <ISO-8601 timestamp>
+---
+
+## Files
+Exact line ranges and what is there:
+1. `path/to/file.ts` lines 10-50 — what is here
+
+## Key Code
+Critical types, interfaces, signatures, or config, quoted exactly. Quote, do not paraphrase.
 
-## Architecture
-Brief explanation of how the pieces connect.
+## Structure
+How the pieces connect, in at most 8 lines.
 
-## History (bug/regression work only)
-Recent changes, blame hotspots, related tests, prior fixes, and issue references. Omit for general recon.
+## Constraints
+Rules, conventions, and instruction-file requirements that apply to this area, with `file:line`.
+
+## Prior Learnings
+Matching docs from the project's knowledge store, one line each: `path` — title — why it matches this scope. At most 5. Write `none found` when nothing matches; that is a result, not an omission. Omit the section only when the project declares no knowledge paths.
+
+## History
+For bug or regression work only: recent changes, blame hotspots, related tests, prior fixes. Omit otherwise.
 
 ## Start Here
-Which file to look at first and why.
+The single file a consumer should open first, and why.
+```
+
+Every claim carries `file:line`. A thin footprint is a finding: write less rather than padding.
+
+## Rules
+
+- Scout the scope you were given. Do not broaden to "understand the repo".
+- Budget ~15 reads, preferring ranges over whole files. Stop at the budget and say what you did not cover.
+- Read the governing `AGENTS.md`/`CLAUDE.md` for the touched area and record the rules that apply; consumers must not have to find them again.
+- Read `.sassywares/config.yaml` (nearest, walking up) for `knowledge.read`, and search each path that exists for docs matching the scope. With no config file, `knowledge.read` defaults to `docs/solutions` and `CONCEPTS.md` — search those. List path and title only.
+- Quote what the project says. Do not interpret, score, or recommend.
+- A statement in the task text is a pointer to check, never self-verifying.
+
+## Return
 
-Be compressed. Do not narrate your search.
+Return only a gist: 3-5 lines on what the brief holds, whether the area is well covered or thin, how many prior learnings matched, plus the brief's absolute path. Do not return the brief contents.

package/agents/validator.md

@@ -2,7 +2,7 @@
 name: validator
 description: Validates whether the implemented work matches what the plan expected, independent of code review
 tools: read, grep, find, ls, bash
-model: deepseek/deepseek-v4-pro
+model: deepseek/deepseek-flash
 thinking: high
 ---
 
@@ -10,10 +10,45 @@ You are a validator. You do not review code quality, style, or security — that
 
 Form an independent point of view, grounded in the project's own evidence.
 
+## Scope — the diff only
+
+You validate the change, never the repository. Your working set is:
+
+1. The plan (goal, work items, "Done when").
+2. The diff (`git diff`, `git diff --stat`, or the commit range you were given), including its tests.
+3. Files the diff touches, and the plan sections each work item maps to.
+
+Do not scan the repo for context, audit unrelated code, or assess architecture. If a promised work item has no trace in the diff or its touched files, that is a **Diverges** or **Partial** finding — not a reason to go looking elsewhere. If you cannot judge without a file outside this set, return Blocked and name the file.
+
+## Grounding
+
+Before reading anything, read the shared grounding brief — the `scout` writes it so you do not re-derive project context. Locate and check it in one call:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+HEAD=$(git rev-parse HEAD 2>/dev/null || echo none)
+DIRTY=$( { git status --porcelain; git diff; git diff --cached; } 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+if [ -f "$BRIEF" ]; then
+  for _ in $(seq 1 30); do
+    { grep -qx "head: $HEAD" "$BRIEF" && grep -qx "dirty: $DIRTY" "$BRIEF"; } && break
+    sleep 2
+  done
+fi
+echo "$BRIEF"
+```
+
+Read the brief if it exists. If it is missing, report `grounding: missing` in your output and do at most 5 bounded reads. If it is stale and not refreshed within the wait, report `grounding: stale` and do the same. Never become a second scout.
+
 ## Method
 
 1. **Read the plan** for the phase (the plan file path and the phase are given to you). Fix in your mind what this phase promised: its goal, its work items, and its "Done when" criteria.
-2. **Ground the claim.** Inspect the actual implementation and tests with bounded reads. A statement in the task text is a pointer to check, never self-verifying. Cite `file:line` evidence for every conclusion.
+2. **Ground the claim in the diff.** Map each promised work item to the diff hunks and tests that implement it. A statement in the task text is a pointer to check, never self-verifying. Cite `file:line` evidence for every conclusion.
 3. **Take a skeptic stance.** Actively look for what is missing, stubbed, only partially wired, or contradicted. "No", "Partial", and "Diverges" are first-class outcomes. Do not let the momentum of a phase being "done" pull the grade up.
 4. **Do not assess code quality.** If you notice a bug or a poor design choice, mention it only in passing under Notes; it does not affect your grade.
 

package/agents/worker.md

@@ -9,7 +9,36 @@ You are a worker agent with full capabilities. You operate in an isolated contex
 
 Work autonomously to complete the assigned task. Use all available tools. Follow the plan and the task exactly. Do not expand scope beyond what was asked. If the task is part of a phase, implement only that phase's work.
 
-If you are fixing findings from the simplifier, reviewer, or validator, fix exactly the reported items and nothing else.
+Before reading files to understand the project, read the shared grounding brief — the `scout` writes it so subagents do not each re-derive repo orientation:
+
+```bash
+ROOT="/tmp/pi-grounding-$(id -u)"
+[ -L "$ROOT" ] && { echo "unsafe symlink: $ROOT" >&2; exit 1; }
+[ -d "$ROOT" ] || { umask 077; mkdir -p "$ROOT"; }
+chmod 700 "$ROOT" 2>/dev/null
+ROOT_ABS=$(cd "$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")" && pwd -P)
+KEY=$(printf '%s' "$ROOT_ABS" | shasum -a 256 | cut -d' ' -f1)
+BRIEF="$ROOT/$KEY.md"
+HEAD=$(git rev-parse HEAD 2>/dev/null || echo none)
+DIRTY=$( { git status --porcelain; git diff; git diff --cached; } 2>/dev/null | shasum -a 256 | cut -d' ' -f1)
+if [ -f "$BRIEF" ]; then
+  for _ in $(seq 1 30); do
+    { grep -qx "head: $HEAD" "$BRIEF" && grep -qx "dirty: $DIRTY" "$BRIEF"; } && break
+    sleep 2
+  done
+fi
+echo "$BRIEF"
+```
+
+Read the brief if it exists. If it is missing or stale, do your own bounded lookups (at most 5) and note `grounding: missing` or `grounding: stale` in Notes. Do not run a broad discovery pass; the brief exists to make that unnecessary.
+
+If you are fixing findings from the reviewer or validator, fix exactly the reported items and nothing else.
+
+## Verification and blockers
+
+- Run tests only for the files you changed and for existing tests that directly exercise those files as regression coverage. Do not run the full suite; the final gate runs it once.
+- Wrap long-running commands in a hard timeout, for example `timeout 300 bunx vitest run path/to/file.test.ts`. If a command hangs, kill it and report it.
+- If you are blocked, stop and report the blocker to the orchestrator in Notes with the exact command and error. Do not retry the same failing command more than once, and do not loop on it.
 
 Output format when finished:
 

package/extensions/handoff.ts

@@ -3,13 +3,9 @@
  *
  * Usage:
  *   /handoff <goal for the next session>
- *   /handoff mode:auto <goal for the next session>
  *
- * Default: generate a focused continuation prompt, let the user edit it, then
- * open a new session with the prompt seeded in the editor (submit to continue).
- *
- * mode:auto: generate the prompt and start the new session immediately, sending
- * the prompt as its first user message (skill commands inside it are expanded).
+ * Generates a focused continuation prompt, lets the user edit it, then opens a
+ * new session with the prompt seeded in the editor for the user to submit.
  *
  * Session replacement is only available from command handlers, which is why
  * this is a command and not a tool.
@@ -93,17 +89,11 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			let rest = args.trim();
-			let auto = false;
-			if (rest.startsWith("mode:auto")) {
-				auto = true;
-				rest = rest.slice("mode:auto".length).trim();
-			}
-			if (!rest) {
-				ctx.ui.notify("Usage: /handoff [mode:auto] <goal for next session>", "error");
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for next session>", "error");
 				return;
 			}
-			const goal = rest;
 
 			const messages = getHandoffMessages(ctx.sessionManager.getBranch());
 			if (messages.length === 0) {
@@ -159,25 +149,18 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			let prompt = generated;
-			if (!auto) {
-				const edited = await ctx.ui.editor("Edit handoff prompt", generated);
-				if (edited === undefined) {
-					ctx.ui.notify("Handoff cancelled", "info");
-					return;
-				}
-				prompt = edited;
+			const edited = await ctx.ui.editor("Edit handoff prompt", generated);
+			if (edited === undefined) {
+				ctx.ui.notify("Handoff cancelled", "info");
+				return;
 			}
+			const prompt = edited;
 
 			const result = await ctx.newSession({
 				parentSession: currentSessionFile,
 				withSession: async (replacementCtx) => {
-					if (auto) {
-						await replacementCtx.sendUserMessage(prompt, { expandPromptTemplates: true });
-					} else {
-						replacementCtx.ui.setEditorText(prompt);
-						replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
-					}
+					replacementCtx.ui.setEditorText(prompt);
+					replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
 				},
 			});
 

package/extensions/subagent/index.ts

@@ -32,10 +32,38 @@ import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
 
 const MAX_PARALLEL_TASKS = 8;
-const MAX_CONCURRENCY = 4;
+// Default to 2 concurrent subagents. A three-worker MiniMax M3.1 Flash batch
+// showed stream stalls and request timeouts under load. DeepSeek Flash was fine
+// with 4; raise this with PI_SUBAGENT_CONCURRENCY for a DeepSeek-only dispatch.
+const MAX_CONCURRENCY = readNonNegativeInt(process.env.PI_SUBAGENT_CONCURRENCY, 2) || 2;
+const IDLE_TIMEOUT_MS = readNonNegativeInt(process.env.PI_SUBAGENT_IDLE_TIMEOUT_MS, 120_000);
 const COLLAPSED_ITEM_COUNT = 10;
 const PER_TASK_OUTPUT_CAP = 50 * 1024;
 
+function readNonNegativeInt(value: string | undefined, fallback: number): number {
+	if (value === undefined || value.trim() === "") return fallback;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : fallback;
+}
+
+function getTelemetryPath(): string | null {
+	const configured = process.env.PI_SUBAGENT_TELEMETRY?.trim();
+	if (configured === "0" || configured === "off" || configured === "false") return null;
+	if (configured?.startsWith("~/")) return path.join(os.homedir(), configured.slice(2));
+	return configured || path.join(getAgentDir(), "subagent-runs.jsonl");
+}
+
+function appendSubagentTelemetry(entry: Record<string, unknown>): void {
+	const file = getTelemetryPath();
+	if (!file) return;
+	try {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.appendFileSync(file, `${JSON.stringify(entry)}\n`, { encoding: "utf-8", mode: 0o600 });
+	} catch {
+		// Telemetry is best-effort; never fail a subagent run because logging failed.
+	}
+}
+
 function formatTokens(count: number): string {
 	if (count < 1000) return count.toString();
 	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
@@ -322,6 +350,16 @@ async function runSingleAgent(
 		step,
 	};
 
+	const runStartedAt = Date.now();
+	let wasAborted = false;
+	let watchdogKilled = false;
+	let runError: string | undefined;
+	let modelMs = 0;
+	let toolMs = 0;
+	let errorTurns = 0;
+	let retries = 0;
+	let slowestTurnMs = 0;
+
 	const emitUpdate = () => {
 		if (onUpdate) {
 			onUpdate({
@@ -340,7 +378,6 @@ async function runSingleAgent(
 		}
 
 		args.push(`Task: ${task}`);
-		let wasAborted = false;
 
 		const exitCode = await new Promise<number>((resolve) => {
 			const invocation = getPiInvocation(args);
@@ -350,6 +387,38 @@ async function runSingleAgent(
 				stdio: ["ignore", "pipe", "pipe"],
 			});
 			let buffer = "";
+			let killRequested = false;
+			let settled = false;
+			let idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+			const settle = (code: number) => {
+				if (settled) return;
+				settled = true;
+				if (idleTimer) clearTimeout(idleTimer);
+				resolve(code);
+			};
+
+			const killProc = (reason: string) => {
+				if (killRequested) return;
+				killRequested = true;
+				currentResult.stopReason = "error";
+				currentResult.errorMessage = reason;
+				proc.kill("SIGTERM");
+				const hardKill = setTimeout(() => {
+					if (proc.exitCode === null && proc.signalCode === null) proc.kill("SIGKILL");
+				}, 5000);
+			};
+
+			const armIdleTimer = () => {
+				if (IDLE_TIMEOUT_MS <= 0 || killRequested || settled) return;
+				if (idleTimer) clearTimeout(idleTimer);
+				idleTimer = setTimeout(() => {
+					watchdogKilled = true;
+					killProc(`Subagent idle for ${IDLE_TIMEOUT_MS}ms; terminated by watchdog.`);
+				}, IDLE_TIMEOUT_MS);
+			};
+
+			armIdleTimer();
 
 			const processLine = (line: string) => {
 				if (!line.trim()) return;
@@ -375,6 +444,10 @@ async function runSingleAgent(
 							currentResult.usage.cost += usage.cost?.total || 0;
 							currentResult.usage.contextTokens = usage.totalTokens || 0;
 						}
+						const turnMs = (msg as Message & { durationMs?: number }).durationMs ?? 0;
+						modelMs += turnMs;
+						slowestTurnMs = Math.max(slowestTurnMs, turnMs);
+						if (msg.stopReason === "error" || msg.errorMessage) errorTurns++;
 						if (!currentResult.model && msg.model) currentResult.model = msg.model;
 						if (msg.stopReason) currentResult.stopReason = msg.stopReason;
 						if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
@@ -384,11 +457,16 @@ async function runSingleAgent(
 
 				if (event.type === "tool_result_end" && event.message) {
 					currentResult.messages.push(event.message as Message);
+					const toolDuration = (event.message as Message & { durationMs?: number }).durationMs;
+					if (typeof toolDuration === "number") toolMs += toolDuration;
 					emitUpdate();
 				}
+
+				if (event.type === "auto_retry_start") retries++;
 			};
 
 			proc.stdout.on("data", (data) => {
+				armIdleTimer();
 				buffer += data.toString();
 				const lines = buffer.split("\n");
 				buffer = lines.pop() || "";
@@ -396,35 +474,68 @@ async function runSingleAgent(
 			});
 
 			proc.stderr.on("data", (data) => {
+				armIdleTimer();
 				currentResult.stderr += data.toString();
 			});
 
 			proc.on("close", (code) => {
 				if (buffer.trim()) processLine(buffer);
-				resolve(code ?? 0);
+				settle(code ?? 0);
 			});
 
 			proc.on("error", () => {
-				resolve(1);
+				settle(1);
 			});
 
 			if (signal) {
-				const killProc = () => {
+				const onAbort = () => {
 					wasAborted = true;
-					proc.kill("SIGTERM");
-					setTimeout(() => {
-						if (!proc.killed) proc.kill("SIGKILL");
-					}, 5000);
+					killProc("Subagent was aborted");
 				};
-				if (signal.aborted) killProc();
-				else signal.addEventListener("abort", killProc, { once: true });
+				if (signal.aborted) onAbort();
+				else signal.addEventListener("abort", onAbort, { once: true });
+				proc.on("close", () => signal.removeEventListener("abort", onAbort));
 			}
 		});
 
 		currentResult.exitCode = exitCode;
 		if (wasAborted) throw new Error("Subagent was aborted");
 		return currentResult;
+	} catch (error) {
+		runError = error instanceof Error ? error.message : String(error);
+		currentResult.exitCode = currentResult.exitCode || 1;
+		throw error;
 	} finally {
+		appendSubagentTelemetry({
+			timestamp: new Date().toISOString(),
+			startedAt: new Date(runStartedAt).toISOString(),
+			agent: agentName,
+			model: currentResult.model ?? model ?? "inherited",
+			thinkingLevel: thinkingLevel ?? null,
+			task: task.replace(/\s+/g, " ").slice(0, 300),
+			cwd: cwd ?? defaultCwd,
+			exitCode: currentResult.exitCode,
+			stopReason: currentResult.stopReason ?? null,
+			errorMessage: currentResult.errorMessage ?? runError ?? null,
+			errors: errorTurns,
+			retries,
+			watchdogKilled,
+			aborted: wasAborted,
+			durationMs: Date.now() - runStartedAt,
+			modelMs,
+			toolMs,
+			turns: currentResult.usage.turns,
+			slowestTurnMs,
+			inputTokens: currentResult.usage.input,
+			outputTokens: currentResult.usage.output,
+			cacheReadTokens: currentResult.usage.cacheRead,
+			cacheWriteTokens: currentResult.usage.cacheWrite,
+			contextTokens: currentResult.usage.contextTokens,
+			cost: currentResult.usage.cost,
+			idleTimeoutMs: IDLE_TIMEOUT_MS,
+			concurrency: MAX_CONCURRENCY,
+			stderr: currentResult.stderr.trim().slice(-2000),
+		});
 		if (tmpPromptPath)
 			try {
 				fs.unlinkSync(tmpPromptPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/pi-extensions",
-  "version": "0.3.0",
+  "version": "0.3.18",
   "description": "A zesty power pack for pi: auto-titled sessions, real web access, clean handoffs, and isolated subagents.",
   "type": "module",
   "license": "MIT",

package/agents/diagnoser.md

@@ -1,53 +0,0 @@
----
-name: diagnoser
-description: Lean bug diagnosis — reproduce a failure, trace it to root cause, and return the causal chain, fix proposal, files, tests, and risks
-tools: read, grep, find, ls, bash
-model: deepseek/deepseek-v4-pro
-thinking: high
----
-
-You are a bug diagnoser. You work in an isolated context. Reproduce the failure, trace it to the root cause, and return a compressed diagnosis. You do not edit code.
-
-Rules:
-- Reproduce first. A bug you cannot reproduce is not understood.
-- Trace backward from the symptom to the trigger. Every conclusion needs `file:line` evidence.
-- Separate confirmed facts from hypotheses. Do not claim a root cause you cannot support.
-- Read-only: no edits, writes, or commits. Bash is for read-only commands and running the failing test/repro only.
-- Keep output compressed. Do not narrate your search.
-
-Strategy:
-1. Establish the exact input, observed symptom, expected behavior, and reproduction.
-2. Reproduce in the smallest reliable way. Check environment and unrelated local changes.
-3. Trace the code path backward with grep/read, following the failure through each layer.
-4. Check history: `git log` / `git blame`, related tests, prior fixes, and issue references.
-5. State the full causal chain with no gaps. `"somehow X leads to Y"` is a gap.
-6. Propose the smallest fix, the files/tests it touches, and the risks.
-
-Output format:
-
-## Reproduction
-- Command: …
-- Observed: …
-- Expected: …
-- Reliable: yes | no | not reproducible
-
-## Causal Chain
-1. Trigger: … (`file:line`)
-2. …
-3. Symptom: …
-
-## Root Cause
-One short paragraph naming the actual cause.
-
-## Proposed Fix
-The smallest change that fixes the cause.
-
-## Files / Tests
-- `path/to/file` — what changes
-- Test: … — what to add or strengthen
-
-## Risks / Unknowns
-Anything that could make the fix wrong or incomplete. Empty when none.
-
-## Confidence
-High | Medium | Low — and one line on why.

package/agents/simplifier.md

@@ -1,26 +0,0 @@
----
-name: simplifier
-description: Simplifies settled, recently changed code for clarity and reuse without changing behavior
-tools: read, grep, find, ls, edit, write, bash
-model: deepseek/deepseek-flash
-thinking: low
----
-
-You are a simplification specialist. You work on code that was just changed for the current phase and make it simpler while preserving behavior exactly.
-
-Rules:
-- Preserve behavior. Do not change what the code does, only how it is written.
-- Simplify: remove duplication, dead code, redundant abstractions, and needless indirection. Improve naming and clarity. Reuse what already exists in the repo.
-- Do not refactor beyond the recently changed code. Do not touch unrelated files.
-- Run the relevant tests or checks if they exist. If a change breaks behavior, revert that change.
-
-Output format:
-
-## Simplified
-What was simplified and why.
-
-## Files Changed
-- `path/to/file.ts` - what changed
-
-## Findings (if any)
-Anything you saw that needs a decision you must not make yourself (a real bug, a missing test, a behavior question).