@fyeeme/pi-review 1.0.0 → 1.0.1

package/README.md

@@ -29,6 +29,9 @@ From the package dir:
 npm install
 ```
 
+This resolves [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)
+(`^0.3.0`, from the npm registry — no sibling-repo layout requirement).
+
 Then point pi at it (e.g. via your extensions config), or symlink into your pi
 extensions directory.
 
@@ -63,6 +66,17 @@ This is the deterministic mode selection a pure-prompt skill cannot reproduce
 `ctx.getContextUsage()`). The decision is announced in the trigger message so
 it is observable.
 
+**Apply → verify → revert safety net** (harden-code-simplify): after Phase 2
+applies the cleanups, the handler also injects a verification command detected
+from `package.json` scripts (`check` → `test` → `lint` → `typecheck`). The
+skill snapshots the touched files, applies the fixes, runs that command, and
+on failure auto-reverts per-file (a clean apply runs verify exactly once; only
+a failure escalates to one verify per touched file). The result is reported as
+structured outcomes via `review_report` (`level: "simplify"`), not a free-text
+summary. If no verification command is detectable, fixes are kept but the
+report states no verification was run (verification is opportunistic, never
+blocking).
+
 ### `subagent` tool
 
 An LLM-callable tool that spawns one or more real pi subprocesses:
@@ -70,9 +84,20 @@ An LLM-callable tool that spawns one or more real pi subprocesses:
 | mode | behavior |
 |---|---|
 | `single` | run `prompts[0]` once (e.g. an independent verify agent) |
-| `parallel` | run all prompts concurrently, capped at 8 (e.g. one finder per angle) |
+| `parallel` | run all prompts concurrently, capped at the ceiling (e.g. one finder per angle) |
 | `chain` | run sequentially; each later prompt receives prior output |
 
+**Fan-out guards** (harden-code-simplify, shared with `/code-review`):
+
+- **Recursion cap (whitelist-by-default)** — a spawned sub-agent does not
+  receive the `subagent` tool in its default toolset, so it cannot recurse. A
+  caller opts in by listing `subagent` in the child's `tools` whitelist; set
+  `PI_SUBAGENT_MAX_SPAWN_DEPTH` to allow multi-level fan-out up to a hard cap.
+- **Default turn budget** — fan-out agents get a finite default `maxTurns` (25)
+  when the caller omits it; an explicit `0` is honored.
+- **Configurable concurrency** — `PI_MAX_CONCURRENT_SUBAGENTS` (default 8;
+  invalid values fall back to the default).
+
 Each sub-agent is a full `pi --mode json -p --no-session` run. Progress streams
 to the TUI via `onUpdate` as each agent completes. ESC aborts the whole batch
 (SIGTERM → 5s → SIGKILL per subprocess). Errors are thrown (not returned) so
@@ -85,8 +110,6 @@ pi-review/
 ├── index.ts                     factory: registerTool(subagent) + 2 commands
 ├── skills/                      bundled SKILL.md files (code-review, simplify)
 ├── src/
-│   ├── agent/dispatch.ts        spawnAgent + mapWithConcurrencyLimit (self-contained copy
-│   │                            from pi-dynamic-workflows; no external dep beyond node + pi-ai)
 │   ├── skills.ts                bundledSkillPath — resolve this extension's own skills/ dir
 │   ├── tools/subagent.ts        defineTool("subagent") — generic capability layer
 │   └── commands/
@@ -96,15 +119,18 @@ pi-review/
 ```
 
 The layout is deliberately layered: `src/tools/` is the **generic capability
-layer** (subagent tool + dispatch), `src/commands/` is the **entry layer** (one
+layer** (subagent tool), `src/commands/` is the **entry layer** (one
 file per skill). If a third or fourth skill needs the subagent tool, `src/tools/`
 can be split into its own `pi-subagent` extension with zero refactor — the code
 is already separated.
 
-`src/agent/dispatch.ts` is a self-contained copy of the spawn pattern from
-`examples/extensions/subagent` and `pi-dynamic-workflows/src/agent/dispatch.ts`
-(~150 lines). When pi promotes `spawnAgent` to a public `pi-coding-agent`
-export, this file should be deleted in favor of that import.
+The dispatch primitive (`spawnAgent`, `mapWithConcurrencyLimit`,
+`createSpawnRegistry`, `abortAgent`, `getPiInvocation` + types) lives in
+[`pi-subagent-core`](../pi-subagent-core) (npm `@fyeeme/pi-subagent-core`), a
+shared library extracted from the duplicated copies that used to live here and
+in `pi-dynamic-workflows`. When pi promotes `spawnAgent` to a public
+`pi-coding-agent` export, `pi-subagent-core` should be deleted in favor of that
+import.
 
 ## Relation to the skills
 

package/index.ts

@@ -4,6 +4,9 @@
  * Registers:
  *   - the `subagent` tool — general-purpose parallel/sequential sub-agent fan-out
  *     via real pi subprocesses. Shared capability used by both skills below;
+ *   - the `review_report` tool — structured findings sink for the code-review
+ *     skill (Pi's counterpart to CC's ReportFindings): renders the Markdown
+ *     report + writes JSON to <cwd>/.pi/review/ for CI;
  *   - the `/code-review` command — effort-level review via the code-review skill;
  *   - the `/code-simplify` command — cleanup via the simplify skill; the handler
  *     decides parallel vs single-pass from ctx.getContextUsage(), mirroring CC's
@@ -13,16 +16,25 @@
  * provides the entry commands + the fan-out capability they need.
  *
  * Layout (layered so the tool layer can be split into its own extension later):
- *   src/tools/subagent.ts    — generic capability (subagent tool + dispatch)
- *   src/commands/*.ts        — per-skill entry commands
+ *   src/tools/subagent.ts      — generic capability (subagent tool; dispatch from pi-subagent-core)
+ *   src/tools/review_report.ts — structured findings sink (review_report tool; CC ReportFindings counterpart)
+ *   src/commands/*.ts          — per-skill entry commands
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isFanoutToolAllowed } from "@fyeeme/pi-subagent-core";
 import { registerCodeReview } from "./src/commands/code-review.ts";
 import { registerSimplify } from "./src/commands/code-simplify.ts";
 import { subagentTool } from "./src/tools/subagent.ts";
+import { reviewReportTool } from "./src/tools/review_report.ts";
 
 export default function (pi: ExtensionAPI): void {
-	pi.registerTool(subagentTool);
+	// The fan-out tool registers only when recursion is allowed for THIS
+	// process (top-level, or a child the spawner explicitly opted in AND that is
+	// below the max-depth cap). A default child — spawned without the fan-out
+	// tool in its whitelist — loads without it, so it physically cannot recurse.
+	// This is the whitelist-by-default recursion guard (harden-code-simplify).
+	if (isFanoutToolAllowed()) pi.registerTool(subagentTool);
+	pi.registerTool(reviewReportTool);
 	registerCodeReview(pi);
 	registerSimplify(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-review",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Review & cleanup extension for pi. Registers /code-review and /code-simplify commands plus a general-purpose `subagent` tool that spawns parallel pi subprocesses — providing the real fan-out capability the code-review and simplify skills (bundled under `skills/`) need for their multi-agent flows. The /code-simplify handler uses ctx.getContextUsage() to decide parallel vs single-pass mode deterministically.",
   "type": "module",
   "license": "MIT",
@@ -34,16 +34,21 @@
     "test": "vitest --run",
     "typecheck": "tsc"
   },
+  "dependencies": {
+    "@fyeeme/pi-subagent-core": "^0.3.2"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.77.0",
-    "@earendil-works/pi-coding-agent": ">=0.77.0",
+    "@earendil-works/pi-ai": ">=0.84.1",
+    "@earendil-works/pi-coding-agent": ">=0.84.1",
+    "@earendil-works/pi-tui": ">=0.84.1",
     "jiti": ">=2.0.0",
     "typebox": ">=1.0.0",
     "typescript": ">=5.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.77.0",
-    "@earendil-works/pi-coding-agent": "0.77.0",
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "22.19.19",
     "jiti": "2.7.0",
     "typebox": "1.1.38",

package/skills/code-review/SKILL.md

@@ -41,9 +41,13 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
   Pi ADAPTATIONS (differ from the CC runtime)
   ════════════════════════════════════════════════════════════════════════
     1. Output   — CC calls a ReportFindings tool with {level, findings}; Pi
-                  PRINTS a Markdown findings table + details block as text
-                  (no such tool on Pi). [was JSON array; switched for
-                  readability]
+                  uses this extension's `review_report` tool (the Pi counterpart
+                  to ReportFindings, verdict/outcome enums aligned to CC
+                  v2.1.226): it renders the Chinese Markdown report (table +
+                  details) back to the conversation AND writes a
+                  machine-readable JSON to <cwd>/.pi/review/ for CI / --fix /
+                  --comment. If the tool is absent, fall back to printing the
+                  Markdown as text.
     2. Fan-out  — CC uses the Agent tool; Pi uses the `subagent` tool
                   (mode: parallel), or runs angles sequentially if unavailable.
     3. Verify   — CC uses the Agent tool; Pi uses `subagent` for the
@@ -75,6 +79,8 @@ altitude, and conventions findings when the output cap forces a cut.
 | high | **recall** — catch every real bug a careful reviewer would; **err on the side of surfacing** | independent agent | more angles | ≤ 10 |
 | xhigh → max | recall + **gap-hunt** | independent agent | above + 1 fresh gap finder | larger, may include uncertain |
 
+**max 与 xhigh 结构相同**：fan-out / verify / sweep 完全一致，差别仅在模型 reasoning effort（CC v2.1.226 注释实证：`max → same structure as xhigh (the API reasoning effort differs, not the fan-out)`）。若运行时不支持调节 reasoning effort，max 在结构上退化为 xhigh——不要因档名而期待更多 fan-out。
+
 Each finder surfaces **up to 6 candidate findings** with `file`, `line`, a
 one-line `summary`, and a concrete `failure_scenario`.
 
@@ -277,48 +283,38 @@ At **high and below**, skip Phase 3.
 
 ## Output
 
-Print the findings as a **Markdown table + a details block** — readable in a
-terminal and in rendered Markdown (no JSON, no ReportFindings tool on Pi). Cap =
-low's min(files_changed, 4); 8 at medium; 10 at high; larger at xhigh → max.
-
-**全部用中文输出**：表头、概述、场景一律用中文；`Verdict`、`Category` 作为标识符保留
-英文 token（CONFIRMED / PLAUSIBLE；correctness / reuse …）。
-
-**1. 表头行** — 单行写明：力度、diff 命令/范围、改动文件数、命中条数、是否真的多智能体
-并发（见下文 Single-pass honesty）。示例：
-
-> `max` · `git diff HEAD` · 29 个文件 · 3 条发现 · 多智能体（验证 + 查漏）
-
-**2. 发现汇总表** — 按严重程度从高到低，每条一行：
-
-| # | 判定 | 类别 | 位置 | 概述 |
-|---|------|------|------|------|
-| 1 | CONFIRMED | correctness | path/file.ext:123 | 一句话说明这个 bug |
-| 2 | PLAUSIBLE | reuse | path/file.ext:45 | … |
-
-- `判定` — `CONFIRMED` / `PLAUSIBLE` / 留空（未做验证）。
-- `类别` — 产生该发现的角度，短横线小写 slug（`correctness`、`simplification`、
-  `efficiency`、`reuse`、`altitude`、`conventions`，或更具体的如 `test-coverage`）。
-- `位置` — `文件:行号`。
-- `概述` — 一句话说明（≤ 约 80 字，同时作为紧凑标签）。
-
-**3. 详情块** — 与表格同序；场景放不进单元格，在这里展开：
-
-**1. path/file.ext:123 — 类别** *(判定)*
-概述：<一句话>
-场景：<具体的输入/状态 → 错误输出/崩溃；若是清理类发现，写明具体代价——重复了什么、
-浪费了什么、哪里更难维护，或违反了哪条规则>
-
-If more than `{cap}` survive, keep the `{cap}` most severe (correctness outranks
-cleanup/altitude/conventions when cutting). If nothing survives, print the header
-line with count 0 and skip the table and details — don't emit an empty table.
-
-### Single-pass honesty
-
-If this review did not actually fan out — low effort, or medium+ where the
-`subagent` tool was unavailable so the angles ran sequentially in one context —
-state clearly in the header line that this was a single-pass review done without the
-multi-agent fan-out, so whoever reads it isn't misled about what actually ran.
+Report the findings via the `review_report` tool (this extension's counterpart
+to CC's `ReportFindings`) — call it **once** with
+`{ level, target, files_changed, fanned_out, findings }`, findings ranked
+most-severe first (empty array if nothing survived verification). The tool
+renders the Chinese Markdown report (table + details) back to the conversation
+AND writes a machine-readable JSON to `<cwd>/.pi/review/` for CI / `--fix` /
+`--comment`. Do **not** also hand-write the Markdown table.
+
+Each finding in the array carries: `file`, `line` (optional), `category`
+(`correctness` / `reuse` / `simplification` / `efficiency` / `altitude` /
+`conventions`, or a more specific slug like `test-coverage`), `verdict`
+(`CONFIRMED` / `PLAUSIBLE` / `REFUTED`), `summary` (one line, Chinese), and
+`failure_scenario` (concrete input/state → wrong output/crash; for cleanup
+findings, the concrete cost — Chinese). When re-reporting after applying
+`--fix`, set `outcome` on each finding (`fully_achieved` / `mostly_achieved` /
+`partially_achieved` / `not_achieved` / `unclear_from_transcript` — mirrored
+verbatim from CC's `ReportFindings`, v2.1.226).
+
+Cap = low's min(files_changed, 4); 8 at medium; 10 at high; larger at
+xhigh → max. If more than `{cap}` survive, send the `{cap}` most severe
+(correctness outranks cleanup/altitude/conventions when cutting). If nothing
+survives, send an empty `findings` array — the tool prints a zero-count header.
+
+**全部用中文**：`summary` 与 `failure_scenario` 一律中文；`verdict`、`category`、
+`outcome` 作为标识符保留英文 token。
+
+**`fanned_out` 诚实** — 准确设置：仅当多智能体 fan-out 真的跑起来（subagent
+finder + verify agent）才为 `true`；low effort 或任何单遍/自审降级为 `false`。该
+字段会出现在报告表头，让读者不被误导（替代旧的 Single-pass honesty 小节）。
+
+**降级** — 若 `review_report` 工具未注册（这份 SKILL.md 跑在 pi-review 扩展之外），
+退回到直接打印 Markdown 表格 + 详情块文本；不要报错。
 
 ---
 
@@ -329,8 +325,13 @@ findings to the working tree instead of stopping at the report: fix each one
 directly — correctness bugs and reuse/simplification/efficiency cleanups alike.
 Skip any finding whose fix would change intended behavior, require changes well
 outside the reviewed diff, or that you judge to be a false positive — note the
-skip rather than arguing with it. Finish with a brief summary of what was fixed
-and what was skipped.
+skip rather than arguing with it. Then call `review_report` once more to
+re-report, setting `outcome` on each finding (`fully_achieved` / `mostly_achieved`
+/ `partially_achieved` / `not_achieved` / `unclear_from_transcript` — skipped
+ones are `not_achieved` or `unclear_from_transcript`). This structured re-report
+replaces the hand-written summary and makes the fix result machine-consumable.
+If `review_report` is unavailable, fall back to a brief text summary of what was
+fixed and what was skipped.
 
 ## Posting comments (--comment)
 

package/skills/simplify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: simplify
-description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v2 (from Claude Code CLI v2.1.223) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied to the working tree."
+description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v2 (from Claude Code CLI v2.1.223) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
 ---
 
 <!--
@@ -38,7 +38,9 @@ description: "Review the changed code for reuse, simplification, efficiency, and
     3. Command     — CC: /simplify; Pi: /code-simplify.
 
   Prerequisite: the `subagent` tool (provided by the pi-review extension) for
-                PARALLEL MODE. SINGLE-PASS MODE runs standalone.
+                PARALLEL MODE, and the `review_report` tool (same extension) for
+                the Phase 2 structured outcome report. SINGLE-PASS MODE runs
+                standalone apart from `review_report`.
 -->
 
 You are improving the quality of the changed code, not hunting for bugs. Review
@@ -96,14 +98,9 @@ bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
 deep enough — prefer generalizing the underlying mechanism over adding special
 cases.
 
-## Phase 2 — Apply the fixes
+## Phase 2 — Apply, verify, and report
 
-Wait for all four agents to complete, dedup findings that point at the same line
-or mechanism, and fix each remaining one directly. Skip any finding whose fix
-would change intended behavior, require changes well outside the reviewed diff,
-or that you judge to be a false positive — note the skip rather than arguing
-with it. Finish with a brief summary of what was fixed and what was skipped (or
-confirm the code was already clean).
+Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). The parallel fan-out only changes how findings are gathered (Phase 1); applying, verifying, and reporting are identical across modes. Set `fanned_out: true` in the report since the 4-agent fan-out actually ran.
 
 ---
 
@@ -145,13 +142,106 @@ bandaid. Special cases layered on shared infrastructure are a sign the fix isn't
 deep enough — prefer generalizing the underlying mechanism over adding special
 cases.
 
-## Phase 2 — Apply the fixes
+## Phase 2 — Apply, verify, and report
 
-Dedup findings that point at the same line or mechanism, and fix each remaining
-one directly. Skip any finding whose fix would change intended behavior, require
-changes well outside the reviewed diff, or that you judge to be a false positive
-— note the skip rather than arguing with it. Finish with a brief summary of what
-was fixed and what was skipped (or confirm the code was already clean). State
-clearly in your summary that this was a single-pass review done without the
-`subagent` tool, not the full 4-agent fan-out, so whoever reads it isn't misled
-about what actually ran.
+Follow the shared **Phase 2** procedure at the end of this skill (snapshot → apply → verify → auto-revert on failure → report via `review_report`). Single-pass vs parallel only changes how findings are gathered (Phase 1); applying, verifying, and reporting are identical across modes. Set `fanned_out: false` in the report so a reader is not misled into thinking the 4-agent fan-out ran.
+
+---
+
+# Phase 2 — Apply, verify, and report (shared by both modes)
+
+Dedup findings that point at the same line or mechanism first. Then apply,
+verify, and report. This safety net is what distinguishes `/code-simplify` from
+a blind cleanup: a finding is only "done" once it is applied AND the project
+still verifies — otherwise it is reverted.
+
+## Step 1 — Snapshot the baseline
+
+Before applying any fix, snapshot every file you are about to edit so a failed
+verification can be reverted cleanly. For each touched file, copy its current
+content into a temp dir:
+
+```
+mkdir -p /tmp/pi-simplify-baseline/$(dirname <file>)
+cp <file> /tmp/pi-simplify-baseline/<file>
+```
+
+`$(dirname <file>)` keeps the target's parent dir (e.g. `src/`) inside the
+baseline — a bare `cp <file> /tmp/pi-simplify-baseline/<file>` fails with ENOENT
+for any file in a subdirectory. If a fix CREATES a new file, record its path so
+Step 3a can remove it on rollback (it has no baseline entry).
+
+This baseline captures the working-tree state **including** the user's
+uncommitted changes — reverting to it undoes only `/code-simplify`'s fixes,
+never the user's diff. Do **not** use `git checkout` / `git restore` to revert:
+that would discard the user's intended changes too.
+
+## Step 2 — Apply the fixes
+
+Apply each surviving finding directly. Skip any finding whose fix would change
+intended behavior, require changes well outside the reviewed diff, or that you
+judge to be a false positive — note the skip (it will be reported as
+`not_achieved`).
+
+## Step 3 — Verify, branching on the result
+
+Run the verification command the handler injected in the trigger message (e.g.
+`npm run check`), then branch:
+
+- **No verification command was detected** → keep the applied changes, mark each
+  applied finding `fully_achieved`, and say in the report that NO verification
+  was run. Verification is opportunistic — never block on its absence.
+- **Verification passes** → keep the changes; applied findings are
+  `fully_achieved` (or `mostly_achieved` / `partially_achieved` if a fix only
+  partly addressed the issue).
+- **Verification fails** → the working tree is verified-broken; go to Step 3a.
+
+### Step 3a — Auto-revert (hybrid granularity, only on failure)
+
+1. Revert ALL touched files from the Step 1 baseline (working-tree parent dirs
+already exist, so copying back is safe):
+   ```
+   cp /tmp/pi-simplify-baseline/<file> <file>
+   ```
+2. Remove any files the fixes CREATED (they have no baseline entry and would
+otherwise survive the rollback).
+3. Re-apply ONE file's findings at a time, running the verification command
+   after each file. Keep only files whose verification passes; revert any file
+   whose verification fails back to its baseline.
+4. If NO file passes on its own, leave everything reverted and mark every
+   finding `not_achieved` — a clean tree is the safe outcome, not a broken one.
+
+This caps the cost: the common case (clean apply) runs verification exactly
+once; only a failure escalates to one verification per touched file.
+
+## Step 4 — Report via `review_report`
+
+Call the `review_report` tool **once** with `level: "simplify"` and one finding
+entry per cleanup, ranked most-severe first. Each entry carries `file`, `line`
+(optional), `category` (`reuse` / `simplification` / `efficiency` /
+`altitude`), `summary` (one line, Chinese), `failure_scenario` (the concrete
+cost — Chinese), and `outcome`:
+
+- `fully_achieved` — applied and verification passed (or no verification command
+  existed and the change was kept).
+- `mostly_achieved` / `partially_achieved` — applied but only partly addresses
+  the issue.
+- `not_achieved` — skipped, or reverted by the auto-revert in Step 3a.
+- `unclear_from_transcript` — could not determine.
+
+Do **not** write a free-text summary as the primary record — the structured
+`review_report` call IS the summary (it renders the report AND writes JSON to
+`<cwd>/.pi/review/` for CI). If `review_report` is unavailable, fall back to a
+brief text summary listing each finding's outcome.
+
+Set `fanned_out` honestly in the call: `true` only if the 4-agent fan-out
+(subagent) actually ran; `false` for single-pass. The report header shows this
+so a reader is not misled about what ran.
+
+## Step 5 — Clean up
+
+```
+rm -rf /tmp/pi-simplify-baseline
+```
+
+Remove the baseline snapshots once the report is delivered.

package/src/commands/code-simplify.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { bundledSkillPath } from "../skills.ts";
 
 /** Context fraction at which we fall back to single-pass — a Pi-specific heuristic (see decideSimplifyMode). */
@@ -6,6 +8,35 @@ const CONTEXT_NEAR_FULL_THRESHOLD = 0.8;
 
 export type SimplifyMode = "parallel" | "single-pass";
 
+/** Priority order for picking a verification command from package.json scripts. */
+const VERIFY_SCRIPT_PRIORITY = ["check", "test", "lint", "typecheck"] as const;
+
+/**
+ * Pick the project verification command from a package.json `scripts` map, in
+ * priority order (check → test → lint → typecheck). Pure — unit-testable.
+ * Returns the runnable command (e.g. `npm run check`) or null when none exists.
+ */
+export function detectVerifyCommand(scripts: Record<string, string> | null): string | null {
+	if (!scripts) return null;
+	for (const key of VERIFY_SCRIPT_PRIORITY) {
+		const v = scripts[key];
+		if (typeof v === "string" && v.trim() !== "") return `npm run ${key}`;
+	}
+	return null;
+}
+
+/** Read package.json scripts from `cwd`; returns null when absent/unparseable. */
+function readScriptsAt(cwd: string): Record<string, string> | null {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")) as {
+			scripts?: Record<string, string>;
+		};
+		return pkg.scripts ?? null;
+	} catch {
+		return null;
+	}
+}
+
 /**
  * Decide simplify mode deterministically from real context usage + tool availability.
  * Pure function — unit-testable.
@@ -48,18 +79,20 @@ export function registerSimplify(pi: ExtensionAPI): void {
 				contextWindow: usage?.contextWindow ?? 0,
 				hasSubagent,
 			});
-			const pct =
-				usage && usage.tokens != null && usage.contextWindow > 0
-					? Math.round((usage.tokens / usage.contextWindow) * 100) + "%"
-					: "?";
+			const pct = usage && usage.percent != null ? `${Math.round(usage.percent)}%` : "?";
 			const bodyLabel = mode === "parallel" ? "PARALLEL MODE" : "SINGLE-PASS MODE";
+			const verifyCmd = detectVerifyCommand(readScriptsAt(ctx.cwd));
+			const verifyLine = verifyCmd
+				? `Verification command: \`${verifyCmd}\` (detected from package.json scripts). After applying Phase 2 fixes, run it; on failure, follow the skill's auto-revert procedure — never leave the working tree verified-broken.`
+				: `No verification command detected in package.json (looked for check/test/lint/typecheck). Apply fixes and report outcomes, but state in the report that no verification was run (verification is opportunistic, never blocking).`;
 			pi.sendUserMessage(
 				`Clean up the changed code now. Target: ${args || "(whole diff)"}.\n\n` +
 					`Handler decided ${mode} mode (context ${pct} full, subagent ${hasSubagent ? "available" : "absent"}). ` +
 					`Load ${bundledSkillPath("simplify/SKILL.md")} via the read tool and follow the ${bodyLabel} body. ` +
 					(mode === "parallel"
 						? `Use the \`subagent\` tool (mode: parallel) for the 4-agent fan-out.`
-						: `Work the four angles inline — do not fake fan-out.`),
+						: `Work the four angles inline — do not fake fan-out.`) +
+					`\n${verifyLine}`,
 			);
 		},
 	});

package/src/tools/review_report.ts

@@ -0,0 +1,225 @@
+/**
+ * src/tools/review_report.ts — the `review_report` LLM tool.
+ *
+ * Structured findings sink for the code-review skill — Pi's counterpart to
+ * CC's native `ReportFindings` tool (verified in CC v2.1.226 binary: "Report
+ * code-review findings as a typed list so the host UI can render them"). Pi has
+ * no host finding-renderer, so this tool does double duty: it renders a tidy
+ * Chinese Markdown report (table + details) back to the conversation AND writes
+ * a machine-readable JSON (findings + level + outcome) to
+ * `<cwd>/.pi/review/<id>.json` so CI / --fix / --comment can consume it.
+ *
+ * `verdict` (CONFIRMED/PLAUSIBLE/REFUTED) and `outcome` (5-state) enums follow
+ * the CC ReportFindings shape (outcome values copied from the CC binary). The
+ * code-review skill drops REFUTED findings before reporting, so that value is
+ * accepted by the schema but rarely seen in practice.
+ */
+import { defineTool, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// --- enums following the CC ReportFindings shape ----------------------------
+
+const Verdict = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")]);
+
+/** CC ReportFindings `outcome` 5 档（v2.1.226 二进制实证）。re-report after --fix 时填。 */
+const Outcome = Type.Union([
+	Type.Literal("fully_achieved"),
+	Type.Literal("mostly_achieved"),
+	Type.Literal("partially_achieved"),
+	Type.Literal("not_achieved"),
+	Type.Literal("unclear_from_transcript"),
+]);
+
+const Level = Type.Union([
+	Type.Literal("low"),
+	Type.Literal("medium"),
+	Type.Literal("high"),
+	Type.Literal("xhigh"),
+	Type.Literal("max"),
+	// simplify reuses this tool for structured apply-outcome reporting
+	// (harden-code-simplify). Not a review effort level — carries no verdict.
+	Type.Literal("simplify"),
+]);
+
+// --- schema -----------------------------------------------------------------
+
+const FindingParams = Type.Object({
+	file: Type.String({ description: "相对仓库根的文件路径。" }),
+	line: Type.Optional(Type.Number({ description: "行号（1-based）。省略表示文件级。" })),
+	category: Type.String({
+		description:
+			"产生该发现的角度 slug：correctness / reuse / simplification / efficiency / altitude / conventions（或更具体如 test-coverage）。",
+	}),
+	verdict: Type.Optional(Verdict),
+	summary: Type.String({ description: "一句话说明（≤80字），同时作紧凑标签。中文。" }),
+	failure_scenario: Type.String({
+		description:
+			"具体场景：输入/状态 → 错误输出/崩溃；清理类发现写明具体代价（重复/浪费/更难维护/违反哪条规则）。中文。",
+	}),
+	outcome: Type.Optional(Outcome),
+});
+
+const ReviewReportParams = Type.Object({
+	level: Level,
+	target: Type.Optional(Type.String({ description: "审查目标（diff 命令/范围，或 PR/分支/路径），用于报告表头。" })),
+	files_changed: Type.Optional(Type.Number({ description: "改动文件数，用于报告表头。" })),
+	fanned_out: Type.Optional(
+		Type.Boolean({ description: "是否真的多智能体并发（Single-pass honesty）。false/省略表示单遍自审。" }),
+	),
+	findings: Type.Array(FindingParams, {
+		description: "已验证、去重、按严重度从高到低排序的发现列表（most-severe first）。空数组表示无发现存活。",
+	}),
+});
+
+interface ReviewReportDetails {
+	level: string;
+	findingsCount: number;
+	/** 结构化 JSON 落盘路径；落盘失败时为 null（仍返回渲染报告）。 */
+	outFile: string | null;
+}
+
+// --- render -----------------------------------------------------------------
+
+interface FindingInput {
+	file: string;
+	line?: number;
+	category: string;
+	verdict?: string;
+	summary: string;
+	failure_scenario: string;
+	outcome?: string;
+}
+interface ReportInput {
+	level: string;
+	target?: string;
+	files_changed?: number;
+	fanned_out?: boolean;
+	findings: FindingInput[];
+}
+
+function fmtLoc(f: { file: string; line?: number }): string {
+	return f.line != null ? `${f.file}:${f.line}` : f.file;
+}
+
+/** Escape a value for a GFM table cell: backslash-escape pipes and collapse
+ *  newlines. Free-text fields (summary/category/verdict/loc) are LLM-provided
+ *  and routinely contain `||`, `|`, regex, or shell pipes that would otherwise
+ *  split the row into extra columns and break the whole summary table. */
+function escapeCell(v: string): string {
+	return v.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+/** 渲染中文 Markdown 报告（表头行 + 汇总表 + 详情块），格式与原 SKILL.md 教的一致。 */
+function renderReport(p: ReportInput): string {
+	const lines: string[] = [];
+	const fanLabel = p.fanned_out === true ? "多智能体" : p.fanned_out === false ? "单遍自审" : "未标注";
+	const targetStr = (p.target ?? "(whole diff)").replace(/`/g, "\\`"); // backtick inside the inline-code cell would close it early
+	const filesStr = p.files_changed != null ? `${p.files_changed} 个文件` : "文件数未标注";
+	lines.push(`\`${p.level}\` · \`${targetStr}\` · ${filesStr} · ${p.findings.length} 条发现 · ${fanLabel}`);
+	lines.push("");
+
+	if (p.findings.length === 0) {
+		lines.push("（无发现存活验证。）");
+		return lines.join("\n");
+	}
+
+	lines.push("| # | 判定 | 类别 | 位置 | 概述 |");
+	lines.push("|---|------|------|------|------|");
+	for (let i = 0; i < p.findings.length; i++) {
+		const f = p.findings[i]!;
+		lines.push(`| ${i + 1} | ${escapeCell(f.verdict ?? "")} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.summary)} |`);
+	}
+	lines.push("");
+	lines.push("**详情**");
+	lines.push("");
+	p.findings.forEach((f, i) => {
+		const v = f.verdict ? ` *(${f.verdict})*` : "";
+		const out = f.outcome ? `\n修复结果：\`${f.outcome}\`` : "";
+		lines.push(`**${i + 1}. ${fmtLoc(f)} — ${f.category}**${v}`);
+		lines.push(`概述：${f.summary}`);
+		lines.push(`场景：${f.failure_scenario}${out}`);
+		lines.push("");
+	});
+	return lines.join("\n").trimEnd();
+}
+
+// --- tool -------------------------------------------------------------------
+
+export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewReportDetails>({
+	name: "review_report",
+	label: "Report review findings",
+	description:
+		"Report code-review findings as a typed list — Pi's counterpart to CC's ReportFindings. Use this only when the active code-review instructions tell you to report findings with this tool. Call it once with the verified findings ranked most-severe first (empty array if nothing survived verification) and do not also print the findings as text — the tool renders a tidy Chinese Markdown report back to the conversation AND writes a machine-readable JSON to <cwd>/.pi/review/ for CI / --fix / --comment. When re-reporting after applying fixes, set `outcome` on each finding. 上报结构化 code-review 发现（CC ReportFindings 的 Pi 对等物）。",
+	promptSnippet: "review_report — report structured code-review findings (renders Markdown + writes JSON for CI)",
+	promptGuidelines: [
+		"After verify + dedup, call `review_report` once with { level, findings } (most-severe first; empty array if none survived). Do not also hand-write the Markdown table — this tool renders it.",
+		"On re-report after --fix, set each finding's `outcome` (fully_achieved / mostly_achieved / partially_achieved / not_achieved / unclear_from_transcript).",
+		"Use this tool only when the code-review skill instructs reporting findings; otherwise follow the active output format.",
+	],
+	parameters: ReviewReportParams,
+
+	async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+		const report = renderReport(params);
+
+		let outFile: string | null = null;
+		let writeError: string | null = null;
+		const now = new Date();
+		try {
+			const dir = path.join(ctx.cwd, ".pi", "review");
+			await fs.promises.mkdir(dir, { recursive: true });
+			const safeId = toolCallId.replace(/[^\w.-]+/g, "_");
+			const ts = now.toISOString().replace(/[:.]/g, "-");
+			const fp = path.join(dir, `${ts}-${safeId}.json`);
+			await fs.promises.writeFile(
+				fp,
+				JSON.stringify(
+					{
+						level: params.level,
+						target: params.target ?? null,
+						filesChanged: params.files_changed ?? null,
+						fannedOut: params.fanned_out ?? null,
+						generatedAt: now.toISOString(),
+						findings: params.findings,
+					},
+					null,
+					2,
+				),
+				{ encoding: "utf-8", mode: 0o600 },
+			);
+			outFile = fp;
+		} catch (err) {
+			/* 落盘失败不阻塞：仍返回渲染报告，但带上错误信息便于 CI/--fix 排障。 */
+			writeError = err instanceof Error ? err.message : String(err);
+		}
+
+		const tail = outFile
+			? `\n\n[结构化发现已写入 \`${outFile}\`]`
+			: `\n\n[结构化落盘失败（${writeError ?? "未知原因"}），仅渲染报告]`;
+		const details: ReviewReportDetails = {
+			level: params.level,
+			findingsCount: params.findings.length,
+			outFile,
+		};
+		return {
+			content: [{ type: "text" as const, text: report + tail }],
+			details,
+		};
+	},
+
+	// Render the returned Markdown report through pi's width-aware Markdown component
+	// (the same path assistant text takes), not the plain-Text tool-result fallback that
+	// renderer-less extension tools get. Without this, the GFM table is shown as raw
+	// `|`/`|---|` wrapped to terminal width — no borders, no alignment.
+	// tool-execution.ts wraps renderResult in try/catch and falls back to plain Text on
+	// throw, so a failure here degrades to the pre-change behavior rather than erroring.
+	renderResult(result, _options, _theme, _context) {
+		const text = result.content
+			.filter((c) => c.type === "text")
+			.map((c) => (c.type === "text" ? c.text : ""))
+			.join("\n");
+		return new Markdown(text, 0, 0, getMarkdownTheme());
+	},
+});

package/src/tools/subagent.ts

@@ -21,14 +21,33 @@ import {
 	abortAgent,
 	createSpawnRegistry,
 	mapWithConcurrencyLimit,
+	parsePositiveInt,
 	spawnAgent,
 	type AgentSpawnRegistry,
 	type AgentSpawnOptions,
 	type AgentSpawnResult,
-} from "../agent/dispatch.ts";
+} from "@fyeeme/pi-subagent-core";
 
-/** Cap on concurrent subprocesses (matches pi-dynamic-workflows + examples/subagent). */
-const MAX_CONCURRENCY = 8;
+/** Default concurrency ceiling when PI_MAX_CONCURRENT_SUBAGENTS is unset/invalid. */
+const DEFAULT_MAX_CONCURRENCY = 8;
+
+/**
+ * Effective concurrency ceiling, configurable via PI_MAX_CONCURRENT_SUBAGENTS
+ * (parity with CC's CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS). Unset, missing, or
+ * non-positive/non-integer values fall back to the default. Read at call time
+ * so a changed env takes effect without a reload.
+ */
+function getMaxConcurrency(): number {
+	return parsePositiveInt(process.env.PI_MAX_CONCURRENT_SUBAGENTS) ?? DEFAULT_MAX_CONCURRENCY;
+}
+
+/**
+ * Default turn budget for a fan-out agent when the caller omits maxTurns. A
+ * runaway agent cannot otherwise be bounded. Generous (well above the ~10–15
+ * turns the 4-angle finder/verify agents need) so legitimate work is not
+ * truncated; callers may override with a smaller or larger explicit value.
+ */
+const DEFAULT_FANOUT_MAX_TURNS = 25;
 
 // Module-level registry so abortAgent can reach in-flight calls. callIds are
 // unique per tool call (toolCallId#index), so a single registry is safe.
@@ -45,10 +64,12 @@ const SubagentParams = Type.Object({
 	systemPrompt: Type.Optional(Type.String({ description: "Appended to the sub-agent's system prompt." })),
 	tools: Type.Optional(Type.Array(Type.String(), { description: "Tool whitelist for the sub-agent. Omit for default tools." })),
 	parallelism: Type.Optional(
-		Type.Number({ description: `Max concurrent agents in parallel mode (default min(prompts.length, ${MAX_CONCURRENCY})).` }),
+		Type.Number({
+			description: `Max concurrent agents in parallel mode (integer ≥ 1; default min(prompts.length, ceiling)). The ceiling is PI_MAX_CONCURRENT_SUBAGENTS (default ${DEFAULT_MAX_CONCURRENCY}).`, 
+		}),
 	),
 	maxTurns: Type.Optional(
-		Type.Number({ description: "Max assistant turns per sub-agent. When reached, the subprocess is aborted. Omit for unlimited." }),
+		Type.Number({ description: "Max assistant turns per sub-agent. When reached, the subprocess is aborted. Omit for the default budget; 0 means abort after the first message." }),
 	),
 	cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the session cwd." })),
 });
@@ -221,13 +242,21 @@ export const subagentTool = defineTool<typeof SubagentParams, SubagentDetails>({
 
 		const cwd = params.cwd ?? ctx.cwd;
 		const baseSystem = params.systemPrompt;
+		// Recursion opt-in: a child may itself spawn sub-agents ONLY when the
+		// caller explicitly listed the fan-out tool in the child's whitelist.
+		// Default (omitted, or whitelist without it) → the child loads without
+		// the subagent tool (see isFanoutToolAllowed in the extension entry).
+		const allowChildRecursion = params.tools?.includes("subagent") ?? false;
 		// Per-call-agnostic subset of AgentSpawnOptions; callId/task are added per spawn.
 		const baseOpts: Omit<AgentSpawnOptions, "callId" | "task"> = {
 			cwd,
 			model: params.model,
 			tools: params.tools,
 			signal,
-			maxTurns: params.maxTurns,
+			// Default turn budget applies when omitted; an explicit 0 is honored by
+			// spawnAgent (it uses `!= null`, not truthiness) rather than treated as unset.
+			maxTurns: params.maxTurns ?? DEFAULT_FANOUT_MAX_TURNS,
+			allowChildRecursion,
 		};
 
 		const partial: SubagentDetails = {
@@ -287,7 +316,12 @@ export const subagentTool = defineTool<typeof SubagentParams, SubagentDetails>({
 		};
 
 		if (params.mode === "parallel") {
-			const conc = Math.min(params.parallelism ?? MAX_CONCURRENCY, MAX_CONCURRENCY, prompts.length);
+			const ceiling = getMaxConcurrency();
+			// Fractional / non-positive parallelism from the model would reach
+			// mapWithConcurrencyLimit as `new Array(3.5)` → RangeError. Clamp to a
+			// sane integer instead of failing the whole tool call.
+			const requested = Math.floor(Math.max(1, params.parallelism ?? ceiling));
+			const conc = Math.min(requested, ceiling, prompts.length);
 			await mapWithConcurrencyLimit(prompts, conc, (p, i) => runOne(p, i));
 		} else {
 			// single or chain

package/src/agent/dispatch.ts

@@ -1,353 +0,0 @@
-/**
- * src/agent/dispatch.ts — agent dispatch via pi subprocess.
- *
- * Reuses the spawn pattern from examples/extensions/subagent and
- * pi-dynamic-workflows/src/agent/dispatch.ts: one `pi --mode json -p
- * --no-session` subprocess per agent call, stdout parsed for
- * {message_end, tool_result_end} events, AbortSignal → SIGTERM with a
- * 5s SIGKILL escalation.
- *
- * This is a SELF-CONTAINED copy (no pi-dynamic-workflows dependency): the
- * workflow-engine retry/skip/lifecycle machinery is stripped, leaving only
- * spawnAgent + mapWithConcurrencyLimit + a per-call abort registry. The
- * subagent tool builds its single/parallel/chain modes on top of this.
- *
- * When pi promotes spawnAgent to a public @earendil-works/pi-coding-agent
- * export, this file should be deleted in favor of that import.
- */
-import { spawn, type ChildProcess } from "node:child_process";
-import { StringDecoder } from "node:string_decoder";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { Message } from "@earendil-works/pi-ai";
-
-/** Stable id for one agent call; the registry key for per-call abort. */
-export type AgentCallId = string;
-
-/** callId → per-call AbortController. */
-export type AgentAbortMap = Map<AgentCallId, AbortController>;
-
-// ---------------------------------------------------------------------------
-// Concurrency limiter (ported from examples/extensions/subagent)
-// ---------------------------------------------------------------------------
-
-/**
- * Run `fn` over `items` with at most `concurrency` in flight, preserving
- * input order in the output array. parallel mode builds on this.
- */
-export async function mapWithConcurrencyLimit<TIn, TOut>(
-	items: TIn[],
-	concurrency: number,
-	fn: (item: TIn, index: number) => Promise<TOut>,
-): Promise<TOut[]> {
-	if (items.length === 0) return [];
-	const limit = Math.max(1, Math.min(concurrency, items.length));
-	const results: TOut[] = new Array(items.length);
-	let nextIndex = 0;
-	// Stop dispatching NEW items once any worker has errored, so a rejection
-	// doesn't leave sibling workers pulling more items and spawning unawaited
-	// subprocesses. In-flight calls finish; the failing worker rethrows.
-	let failed = false;
-	const workers = new Array(limit).fill(null).map(async () => {
-		while (!failed) {
-			const current = nextIndex++;
-			if (current >= items.length) return;
-			try {
-				results[current] = await fn(items[current], current);
-			} catch (err) {
-				failed = true;
-				throw err;
-			}
-		}
-	});
-	await Promise.all(workers);
-	return results;
-}
-
-// ---------------------------------------------------------------------------
-// pi binary resolution (ported from examples/extensions/subagent)
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the `pi` invocation for the subprocess. Prefers re-entering the
- * current script (node <script> / bun <script>); falls back to the `pi`
- * binary on PATH when run under a generic runtime.
- */
-export function getPiInvocation(args: string[]): { command: string; args: string[] } {
-	const currentScript = process.argv[1];
-	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
-	if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
-		return { command: process.execPath, args: [currentScript, ...args] };
-	}
-
-	const execName = path.basename(process.execPath).toLowerCase();
-	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-	if (!isGenericRuntime) {
-		return { command: process.execPath, args };
-	}
-
-	return { command: "pi", args };
-}
-
-// ---------------------------------------------------------------------------
-// Usage + result
-// ---------------------------------------------------------------------------
-
-export interface AgentUsage {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	cost: number;
-	contextTokens: number;
-	turns: number;
-}
-
-export interface AgentSpawnOptions {
-	/** Stable id for this call; the registry key for per-call abort. */
-	readonly callId: AgentCallId;
-	/** Prompt passed as the final positional arg to `pi -p`. */
-	readonly task: string;
-	/** Working directory for the spawned pi process. Defaults to process.cwd(). */
-	readonly cwd?: string;
-	/** `--model` override. */
-	readonly model?: string;
-	/** `--tools` whitelist (comma-joined). */
-	readonly tools?: string[];
-	/** System prompt appended via a temp file (`--append-system-prompt`). */
-	readonly systemPrompt?: string;
-	/** Caller-level abort signal; linked to this call's per-call controller. */
-	readonly signal?: AbortSignal;
-	/** Max assistant turns. When reached, the subprocess is aborted (SIGTERM). Omit for unlimited. */
-	readonly maxTurns?: number;
-}
-
-export interface AgentSpawnResult {
-	callId: AgentCallId;
-	exitCode: number;
-	messages: Message[];
-	stderr: string;
-	usage: AgentUsage;
-	model?: string;
-	stopReason?: string;
-	errorMessage?: string;
-	/** True if aborted. exitCode may be null/non-zero. */
-	aborted: boolean;
-	/** True if killed because the caller's maxTurns budget was reached. Distinct
-	 *  from `aborted` (external cancel): the agent did useful bounded work. */
-	maxTurnsReached: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Registry — Map<callId, ChildProcess> + per-call AbortController
-// ---------------------------------------------------------------------------
-
-export interface AgentSpawnRegistry {
-	/** callId → child process. The table that translates abort → SIGTERM on one process. */
-	readonly processes: Map<AgentCallId, ChildProcess>;
-	/** callId → per-call controller. */
-	readonly controllers: AgentAbortMap;
-}
-
-export function createSpawnRegistry(): AgentSpawnRegistry {
-	return {
-		processes: new Map(),
-		controllers: new Map(),
-	};
-}
-
-/**
- * Abort exactly one in-flight call by id. Aborts the call's per-call
- * controller; spawnAgent's race-safe listener translates that into
- * SIGTERM→SIGKILL on exactly the one subprocess. Returns false if the
- * callId is not in flight.
- */
-export function abortAgent(registry: AgentSpawnRegistry, callId: AgentCallId): boolean {
-	const controller = registry.controllers.get(callId);
-	if (!controller) return false;
-	controller.abort();
-	return true;
-}
-
-// ---------------------------------------------------------------------------
-// Spawn — the dispatch primitive
-// ---------------------------------------------------------------------------
-
-export async function spawnAgent(
-	registry: AgentSpawnRegistry,
-	options: AgentSpawnOptions,
-): Promise<AgentSpawnResult> {
-	const { callId, task, cwd, model, tools, systemPrompt, signal } = options;
-
-	// Per-call controller — the abort entry point.
-	const controller = new AbortController();
-	registry.controllers.set(callId, controller);
-
-	// Link the caller-level signal to this call's controller so a run-wide
-	// abort reaches every in-flight call. Named + removed in finally — otherwise
-	// a normally-completing call leaks a listener on the parent signal.
-	const onParentAbort = (): void => controller.abort();
-	if (signal) {
-		if (signal.aborted) controller.abort();
-		else signal.addEventListener("abort", onParentAbort);
-	}
-
-	const args: string[] = ["--mode", "json", "-p", "--no-session"];
-	if (model) args.push("--model", model);
-	if (tools && tools.length > 0) args.push("--tools", tools.join(","));
-
-	let tmpPromptDir: string | null = null;
-	let tmpPromptPath: string | null = null;
-
-	const result: AgentSpawnResult = {
-		callId,
-		exitCode: 0,
-		messages: [],
-		stderr: "",
-		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-		aborted: false,
-		maxTurnsReached: false,
-	};
-
-	try {
-		if (systemPrompt && systemPrompt.trim()) {
-			const tmp = await writePromptToTempFile(callId, systemPrompt);
-			tmpPromptDir = tmp.dir;
-			tmpPromptPath = tmp.filePath;
-			args.push("--append-system-prompt", tmpPromptPath);
-		}
-
-		// The prompt is the final positional arg consumed by `-p`.
-		args.push(task);
-
-		const exitCode = await new Promise<number>((resolve) => {
-			const invocation = getPiInvocation(args);
-			const proc = spawn(invocation.command, invocation.args, {
-				cwd: cwd ?? process.cwd(),
-				shell: false,
-				stdio: ["ignore", "pipe", "pipe"],
-			});
-			registry.processes.set(callId, proc);
-
-			let buffer = "";
-			const decoder = new StringDecoder("utf8");
-
-			const processLine = (line: string) => {
-				if (!line.trim()) return;
-				let event: { type: string; message?: Message };
-				try {
-					event = JSON.parse(line) as { type: string; message?: Message };
-				} catch {
-					return;
-				}
-
-				if (event.type === "message_end" && event.message) {
-					const msg = event.message;
-					result.messages.push(msg);
-					if (msg.role === "assistant") {
-						result.usage.turns++;
-						// Enforce maxTurns: abort the subprocess when the limit is reached.
-						// killProc handles the SIGTERM→SIGKILL escalation. Use `!= null` so an
-						// explicit maxTurns: 0 is honored (and marked) rather than treated as "unset".
-						if (options.maxTurns != null && result.usage.turns >= options.maxTurns) {
-							result.maxTurnsReached = true;
-							controller.abort();
-						}
-						const usage = msg.usage;
-						if (usage) {
-							result.usage.input += usage.input || 0;
-							result.usage.output += usage.output || 0;
-							result.usage.cacheRead += usage.cacheRead || 0;
-							result.usage.cacheWrite += usage.cacheWrite || 0;
-							result.usage.cost += Number(usage.cost?.total) || 0;
-							result.usage.contextTokens = usage.totalTokens || 0;
-						}
-						if (!result.model && msg.model) result.model = msg.model;
-						if (msg.stopReason) result.stopReason = msg.stopReason;
-						if (msg.errorMessage) result.errorMessage = msg.errorMessage;
-					}
-				}
-
-				if (event.type === "tool_result_end" && event.message) {
-					result.messages.push(event.message);
-				}
-			};
-
-			proc.stdout.on("data", (data) => {
-				// StringDecoder buffers incomplete multi-byte UTF-8 sequences across chunk
-				// boundaries so a CJK char split between two `data` events isn't replaced
-				// with U+FFFD (which would corrupt the line and silently drop the event).
-				buffer += decoder.write(data);
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) processLine(line);
-			});
-
-			proc.stderr.on("data", (data) => {
-				result.stderr += data.toString();
-			});
-
-			proc.on("close", (code) => {
-				const tail = decoder.end();
-				if (tail) buffer += tail;
-				if (buffer.trim()) processLine(buffer);
-				resolve(code ?? 1); // code===null → signal-killed (OOM/SIGKILL): treat as failure, not silent empty success
-			});
-
-			proc.on("error", (err) => {
-				// Surface the spawn error (e.g. ENOENT when `pi` is not on PATH) instead
-				// of swallowing it.
-				result.errorMessage = err.message;
-				result.stderr += err.message;
-				resolve(1);
-			});
-
-			// Per-call abort → SIGTERM (SIGKILL after 5s). Race-safe: if the controller
-			// was already aborted before this listener registered, kill now.
-			const killProc = () => {
-				// Late-abort guard: if the proc already exited, don't flip a successful
-				// result's `aborted` flag.
-				if (proc.exitCode !== null || proc.signalCode !== null) return;
-				result.aborted = true;
-				proc.kill("SIGTERM");
-				const timer = setTimeout(() => {
-					// SIGTERM may be ignored — force SIGKILL after the grace period.
-					proc.kill("SIGKILL");
-				}, 5000);
-				// Clear the timer once the proc exits so we don't leak a libuv handle.
-				proc.once("close", () => clearTimeout(timer));
-			};
-			if (controller.signal.aborted) killProc();
-			else controller.signal.addEventListener("abort", killProc, { once: true });
-		});
-
-		result.exitCode = exitCode;
-		return result;
-	} finally {
-		// Always release registry slots, the parent-signal listener, and temp files.
-		registry.processes.delete(callId);
-		registry.controllers.delete(callId);
-		if (signal) signal.removeEventListener("abort", onParentAbort);
-		if (tmpPromptPath)
-			try {
-				fs.unlinkSync(tmpPromptPath);
-			} catch {
-				/* ignore */
-			}
-		if (tmpPromptDir)
-			try {
-				fs.rmdirSync(tmpPromptDir);
-			} catch {
-				/* ignore */
-			}
-	}
-}
-
-async function writePromptToTempFile(callId: string, prompt: string): Promise<{ dir: string; filePath: string }> {
-	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-cr-agent-"));
-	const safeName = callId.replace(/[^\w.-]+/g, "_");
-	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-	return { dir: tmpDir, filePath };
-}