@zephyrdeng/pi-review 0.6.2 → 0.7.1

package/extensions/panel-tool.ts

@@ -0,0 +1,169 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Writable } from "node:stream";
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text, type Component } from "@earendil-works/pi-tui";
+import { createPanelViewState, reducePanelEvent, spawnStreamingChild, type PanelViewState, type ReviewEvent } from "@zephyrdeng/pi-review";
+
+type Theme = { fg: (color: "toolTitle" | "muted" | "error" | "success" | "accent", text: string) => string; bold: (text: string) => string };
+type PanelToolDetails = { state: PanelViewState; error?: string };
+
+const extensionDir = path.dirname(fileURLToPath(import.meta.url));
+const cliPath = path.resolve(extensionDir, "../bin/pi-review.js");
+
+function duration(ms: number | undefined): string {
+  if (!ms) return "0s";
+  return `${Math.floor(ms / 1000)}s`;
+}
+
+function usageTokens(state: PanelViewState): string {
+  return state.aggregate.usage ? `${state.aggregate.usage.totalTokens.toLocaleString()} tok` : "—";
+}
+
+function statusSymbol(status: string): string {
+  return status === "completed" ? "✓" : status === "failed" || status === "cancelled" ? "✗" : status === "running" ? "●" : "○";
+}
+
+function compactText(state: PanelViewState, theme: Theme): string {
+  const elapsed = state.startedAt ? duration((state.completedAt ?? Date.now()) - state.startedAt) : "0s";
+  const progress = `${state.aggregate.completed}/${state.aggregate.total} completed`;
+  const header = theme.fg("toolTitle", theme.bold(`pi-review panel ${progress}`)) + theme.fg("muted", ` · ${state.phase} · ${elapsed} · ${usageTokens(state)}`);
+  const rows = Object.values(state.reviewers).map((reviewer) => {
+    const active = reviewer.activeTool ? ` · ${reviewer.activeTool}` : "";
+    const elapsed = reviewer.startedAt ? ` · ${duration((reviewer.completedAt ?? Date.now()) - reviewer.startedAt)}` : "";
+    const tokens = reviewer.usage ? ` · ${reviewer.usage.totalTokens.toLocaleString()} tok` : "";
+    return `${theme.fg(reviewer.status === "failed" ? "error" : reviewer.status === "completed" ? "success" : "accent", statusSymbol(reviewer.status))} ${theme.fg("toolTitle", reviewer.reviewerId)}${theme.fg("muted", ` ${reviewer.role}${active}${elapsed}${tokens}`)}`;
+  });
+  return [header, ...rows].join("\n");
+}
+
+function finalMarkdown(state: PanelViewState): string {
+  const meta = state.meta;
+  if (!meta) return "";
+  const confirmed = meta.confirmedClusters.map((finding) => `- ${finding.summary} (${finding.supportingReviewerIds.join(", ")})`);
+  const advisories = meta.advisories.map((finding) => `- ${finding.summary} (${finding.supportingReviewerIds.join(", ")})`);
+  return [
+    "### Panel result",
+    `Health: ${meta.panelHealth}; status: ${meta.status}.`,
+    confirmed.length ? `### Confirmed findings\n${confirmed.join("\n")}` : "### Confirmed findings\nNone.",
+    advisories.length ? `### Advisories\n${advisories.join("\n")}` : "",
+  ].filter(Boolean).join("\n\n");
+}
+
+export function renderPanelResult(details: PanelToolDetails | undefined, expanded: boolean, theme: Theme, previous?: Component): Component {
+  if (!details) return new Text(theme.fg("muted", "Panel review has no progress details."), 0, 0);
+  if (!expanded) {
+    const text = previous instanceof Text ? previous : new Text("", 0, 0);
+    text.setText(compactText(details.state, theme));
+    return text;
+  }
+  const container = new Container();
+  container.addChild(new Text(compactText(details.state, theme), 0, 0));
+  for (const reviewer of Object.values(details.state.reviewers)) {
+    if (reviewer.recentActivity.length === 0) continue;
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", `${reviewer.reviewerId} activity`), 0, 0));
+    container.addChild(new Text(reviewer.recentActivity.join("\n"), 0, 0));
+  }
+  const markdown = finalMarkdown(details.state);
+  if (markdown) {
+    container.addChild(new Spacer(1));
+    // Pi supplies a Markdown theme to built-in renderers; plain text keeps this
+    // extension portable across public API versions while still using Markdown.
+    container.addChild(new Markdown(markdown, 0, 0, {
+      heading: theme.bold,
+      link: (text) => text,
+      linkUrl: (text) => text,
+      code: (text) => text,
+      codeBlock: (text) => text,
+      codeBlockBorder: (text) => text,
+      quote: (text) => text,
+      quoteBorder: (text) => text,
+      hr: (text) => text,
+      listBullet: (text) => text,
+      bold: theme.bold,
+      italic: (text) => text,
+      strikethrough: (text) => text,
+      underline: (text) => text,
+    }));
+  }
+  if (details.error) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("error", details.error), 0, 0));
+  }
+  return container;
+}
+
+export function registerPanelReviewTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "pi_review",
+    label: "Pi Review Panel",
+    description: "Run an isolated read-only pi-review panel and render each reviewer live.",
+    renderShell: "self",
+    parameters: Type.Object({
+      target: Type.String({ description: "Review target, such as @src or a code-review brief." }),
+      mode: Type.Optional(Type.String({ description: "Review mode; defaults to code." })),
+      panel: Type.Optional(Type.String({ description: "Named panel preset; defaults to code-experts." })),
+      model: Type.Optional(Type.String({ description: "Optional reviewer model." })),
+      thinking: Type.Optional(Type.String({ description: "Optional thinking level." })),
+    }),
+    async execute(_toolCallId, params, signal, onUpdate) {
+      let state = createPanelViewState();
+      let buffer = "";
+      let stderr = "";
+      const publish = () => onUpdate?.({ content: [{ type: "text", text: `Panel: ${state.aggregate.completed}/${state.aggregate.total} completed` }], details: { state } });
+      const consume = (chunk: string) => {
+        buffer += chunk;
+        let newline: number;
+        while ((newline = buffer.indexOf("\n")) >= 0) {
+          const line = buffer.slice(0, newline);
+          buffer = buffer.slice(newline + 1);
+          try {
+            state = reducePanelEvent(state, JSON.parse(line) as ReviewEvent);
+            publish();
+          } catch {
+            // Only the stable pi-review event protocol reaches this stream.
+          }
+        }
+      };
+      const stdoutSink = new Writable({ write(chunk, _encoding, callback) { consume(String(chunk)); callback(); } });
+      const stderrSink = new Writable({
+        write(chunk, _encoding, callback) {
+          const next = stderr + String(chunk);
+          stderr = next.length > 2000 ? next.slice(-2000) : next;
+          callback();
+        },
+      });
+      const args = [cliPath, "--panel", params.panel ?? "code-experts", "--mode", params.mode ?? "code", "--output-format", "events-jsonl"];
+      if (params.model) args.push("--model", params.model);
+      if (params.thinking) args.push("--thinking", params.thinking);
+      args.push("--", params.target);
+      const child = await spawnStreamingChild(process.execPath, args, { cwd: process.cwd(), env: process.env, stdoutSink, stderrSink, signal, processGroup: true });
+      if (buffer.trim()) {
+        const tail = buffer;
+        buffer = "";
+        consume(`${tail}\n`);
+      }
+      const error = child.error
+        ? child.error.message
+        : state.meta
+          ? undefined
+          : [`pi-review ended before a final event (${child.status ?? child.signal ?? "unknown"})`, stderr.trim()].filter(Boolean).join(": ");
+      const details: PanelToolDetails = { state, ...(error ? { error } : {}) };
+      return {
+        content: [{ type: "text", text: error ?? `Panel completed: ${state.meta?.status ?? "unknown"}` }],
+        details,
+        ...(error ? { isError: true } : {}),
+      };
+    },
+    renderCall(args, theme, context) {
+      const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+      text.setText(theme.fg("toolTitle", theme.bold("pi_review ")) + theme.fg("muted", `${args.panel ?? "code-experts"} · ${args.mode ?? "code"} · ${args.target}`));
+      return text;
+    },
+    renderResult(result, { expanded }, theme, context) {
+      return renderPanelResult(result.details as PanelToolDetails | undefined, expanded, theme, context.lastComponent);
+    },
+  });
+}

package/extensions/review.ts

@@ -10,6 +10,7 @@ import {
   RV_COMPLETIONS,
   validateRvParsed,
 } from "./rv-prompts.js";
+import { registerPanelReviewTool } from "./panel-tool.js";
 
 /**
  * Captured at `session_start` so the synchronous-ish `getArgumentCompletions`
@@ -68,6 +69,7 @@ function toModelInfo(m: {
 }
 
 export default function piReviewExtension(pi: ExtensionAPI) {
+  registerPanelReviewTool(pi);
   pi.on("session_start", (_event, ctx) => {
     try {
       const available = ctx.modelRegistry?.getAvailable?.() ?? [];
@@ -130,4 +132,4 @@ export default function piReviewExtension(pi: ExtensionAPI) {
       pi.sendUserMessage(buildRvOrchestrationPrompt(parsed, localeForHandler(ctx)));
     },
   });
-}
+}

package/extensions/rv-prompts.test.ts

@@ -70,10 +70,17 @@ describe("parseRvArgs / validateRvParsed", () => {
     const p = parseRvArgs("@src/foo.ts");
     const prompt = buildRvOrchestrationPrompt(p);
     assert.match(prompt, /Do NOT add --no-stream or --progress-log/);
+    assert.match(prompt, /rendered panel result and status/);
     assert.match(prompt, /ASCII pi-review footer/);
     assert.doesNotMatch(prompt, /PI_REVIEW_META:/);
   });
 
+  it("continuations retain the session-aware CLI path", () => {
+    const prompt = buildRvOrchestrationPrompt(parseRvArgs("--continue /tmp/review.jsonl @src/foo.ts"));
+    assert.match(prompt, /Execute:\npi-review --continue \/tmp\/review\.jsonl -- @src\/foo\.ts/);
+    assert.doesNotMatch(prompt, /Call pi_review with target/);
+  });
+
   it("buildPiReviewArgv matches for initial and continue", () => {
     const initial = parseRvArgs("--mode plan --model m/a @doc.md");
     assert.deepEqual(buildPiReviewArgv(initial, "@doc.md"), [
@@ -99,4 +106,4 @@ describe("parseRvArgs / validateRvParsed", () => {
       "more",
     ]);
   });
-});
+});

package/extensions/rv-prompts.ts

@@ -144,10 +144,10 @@ function piHostRules(): string {
   return [
     "Follow the pi-review skill.",
     "Host: Pi interactive session (/rv).",
-    "Run pi-review in an isolated child session; return the review conclusion (Markdown sections) plus the ASCII pi-review footer.",
+    "For new review runs, call the pi_review custom tool. It launches pi-review in isolated reviewer sessions and renders panel progress live.",
     "CLI defaults: stream child output live. Do NOT add --no-stream or --progress-log unless the user explicitly asked.",
     "Do not edit, patch, commit, or implement findings unless the user asks separately.",
-    "After pi-review exits, show the user the ASCII footer (lines starting with ── pi-review). Do not paste PI_REVIEW_META_JSON to the user; use Session from the footer for /rv --continue.",
+    "For pi_review panel runs, report the tool's rendered panel result and status. For CLI fallback and --continue runs, show the ASCII pi-review footer (lines starting with ── pi-review). Do not paste PI_REVIEW_META_JSON to the user; use Session from a CLI footer for /rv --continue.",
   ].join(" ");
 }
 
@@ -216,7 +216,9 @@ export function buildRvOrchestrationPrompt(parsed: RvParsed, locale: RvLocale =
       `Mode: ${parsed.mode}. Follow the preset named in review-presets.json when present.`,
     modelStep,
     continueNote,
-    `Execute:\n${cliLine}`,
+    parsed.continueHandle || parsed.keepSession || parsed.noStream
+      ? `Execute:\n${cliLine}`
+      : `Call pi_review with target=${JSON.stringify(target)}, mode=${JSON.stringify(parsed.mode)}, and any selected model/thinking values. The tool uses the code-experts panel by default.`,
   ]
     .filter(Boolean)
     .join("\n\n");
@@ -233,4 +235,4 @@ export const RV_COMPLETIONS: { value: string; hint: string }[] = [
   { value: "--keep-session", hint: "persist session for follow-up" },
   { value: "--no-stream", hint: "rare: buffer until exit (not default in Pi)" },
   { value: "--continue ", hint: "resume session; same optional flags as initial /rv" },
-];
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "bin": {
-    "pi-review": "./bin/pi-review.js"
+    "pi-review": "bin/pi-review.js"
   },
   "exports": {
     ".": {
@@ -50,14 +50,20 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.7",
+    "@earendil-works/pi-tui": "^0.80.7",
     "@types/node": "^22.0.0",
     "husky": "^9.1.7",
     "typescript": "^5.8.0"
@@ -65,14 +71,17 @@
   "scripts": {
     "prepare": "husky",
     "build": "tsc",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc --noEmit -p tsconfig.extension.json",
     "smoke": "node dist/cli.js --help >/dev/null",
-    "test": "npx --yes tsx --test src/child-process.test.ts src/review.meta.test.ts src/meta-footer.test.ts src/json-events.test.ts src/install-args.test.ts extensions/rv-prompts.test.ts extensions/rv-completions.test.ts extensions/rv-model-priorities.test.ts extensions/rv-locale.test.ts extensions/rv-semantic.test.ts",
+    "test": "npm run build && npx --yes tsx --test src/args.test.ts src/cli-exit.test.ts src/child-process.test.ts src/review.meta.test.ts src/review-result.test.ts src/loop.test.ts src/meta-footer.test.ts src/prompt.test.ts src/skill-protocol.test.ts src/json-events.test.ts src/install-args.test.ts src/panel-aggregate.test.ts src/matcher.test.ts src/panel-config.test.ts src/panel-loop.test.ts src/panel-cli.test.ts src/review-events.test.ts src/panel-view.test.ts src/panel-cancellation.test.ts src/panel-tools.test.ts extensions/rv-prompts.test.ts extensions/rv-completions.test.ts extensions/rv-model-priorities.test.ts extensions/rv-locale.test.ts extensions/rv-semantic.test.ts extensions/panel-tool.test.ts",
     "test:rv": "npx --yes tsx --test extensions/rv-prompts.test.ts extensions/rv-completions.test.ts extensions/rv-model-priorities.test.ts extensions/rv-locale.test.ts extensions/rv-semantic.test.ts",
     "prepublishOnly": "npm run build",
     "pack:dry": "npm pack --dry-run"
   },
   "engines": {
     "node": ">=20"
+  },
+  "dependencies": {
+    "typebox": "^1.1.38"
   }
 }

package/resources/panel-presets.json

@@ -0,0 +1,21 @@
+{
+  "code-experts": {
+    "description": "Code review panel with independent correctness, security, and testing lenses.",
+    "consensus": "quorum",
+    "minAgree": 2,
+    "reviewers": [
+      {
+        "id": "correctness",
+        "role": "Correctness reviewer: focus on logic errors, regressions, concurrency, API contracts, edge cases, and maintainability."
+      },
+      {
+        "id": "security",
+        "role": "Security reviewer: focus on input validation, authn/authz, secrets, injection, unsafe deserialization, and trust boundaries."
+      },
+      {
+        "id": "testing",
+        "role": "Testing reviewer: focus on missing tests, weak assertions, flakiness, coverage gaps, and behavior that would escape the test suite."
+      }
+    ]
+  }
+}

package/resources/review-presets.json

@@ -1,9 +1,9 @@
 {
   "code": {
     "description": "Code review only: inspect provided files, diffs, or paths and return review conclusions without editing.",
-    "tools": ["read", "grep", "find", "ls", "bash"],
+    "tools": ["read", "grep", "find", "ls"],
     "thinking": "high",
-    "instructions": "Review code or code changes only. Do not edit, write, patch, format, commit, or otherwise mutate files. Use bash only for read-only inspection commands such as git diff, git status, git show, tests with explicit user permission, or listing files. Focus on correctness, regressions, security, concurrency, API contracts, edge cases, maintainability, and missing tests."
+    "instructions": "Review code or code changes only. Do not edit, write, patch, format, commit, or otherwise mutate files. Use the enabled read-only tools for inspection. Focus on correctness, regressions, security, concurrency, API contracts, edge cases, maintainability, and missing tests."
   },
   "plan": {
     "description": "High-level plan review with multiple expert lenses; output a decisive conclusion.",

package/resources/system-prompt.md

@@ -34,7 +34,17 @@ One of: approve | request_changes | needs_clarification | blocked
 Short conclusion in 2-5 bullets.
 
 ## Findings
-Prioritized findings. Each finding should include severity, evidence, impact, and recommendation. If there are no material findings, write "No material findings."
+Prioritized findings. For every material finding, use this exact shape (increment IDs as F1, F2, ...):
+
+### F1: <summary>
+- Severity: critical | high | medium | low
+- Path: <path or none>
+- Actionable: yes | no
+- Evidence: <concrete evidence>
+- Impact: <why it matters>
+- Recommendation: <specific next step>
+
+Set Actionable to yes when the host must fix or consciously reject the finding before clean closeout. Use no for informational or explicitly out-of-scope follow-up findings. If there are no material findings, write "No material findings."
 
 ## Risks and Blind Spots
 What could still be wrong, missing, or unverified.

package/skills/pi-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-review
-description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to a fresh Pi session and return only the review conclusion. Model selection presets for code, frontend, and plan review (see references/model-selection.md). On Claude Code or Codex, default to --progress-log with a background shell run and tail the log (chat tools buffer stdout). Use when the user asks for Pi review, isolated review, code review, plan review, challenge review, review status/progress, or wants to avoid context pollution.
+description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to fresh Pi sessions and return review conclusions. Also use for loop review, review-fix-re-review closeout, structured review gates, and review status/progress. Model selection presets for code, frontend, and plan review are in references/model-selection.md. On Claude Code or Codex, default to --progress-log with a background shell run and tail the log (chat tools buffer stdout).
 ---
 
 # Pi Review
@@ -34,26 +34,21 @@ When resolving this fallback, use the actual directory that contains this `SKILL
 
 | Host | How to run `pi-review` |
 |------|-------------------------|
-| **Pi** (`/rv`) | Foreground CLI, **default streaming** only. Do **not** add `--no-stream` or `--progress-log` unless the user explicitly asks. |
+| **Pi** (`/rv`) | New reviews call the native `pi_review` tool, which launches the packaged CLI in event mode and renders live Panel state. Continuations, kept sessions, and explicit `--no-stream` retain the foreground CLI path. |
 | **Claude Code, Codex, Cursor**, and similar AI agents | **Default: `--progress-log <path>` + background run + tail** (see below). Do **not** rely on foreground Bash stdout for “streaming” — the tool buffers until exit. |
 | Scripts / CI | Foreground is fine; use `--no-stream` only when you must buffer until exit. |
 
 ## Pi host (`/rv`)
 
-- In **Pi interactive** sessions, run `pi-review` with **default streaming only** — do **not** add `--no-stream` or `--progress-log` unless the user explicitly asks.
-- The `/rv` extension injects these rules into the parent agent; ordinary `/rv @path` needs no extra flags.
+- In **Pi interactive** sessions, ordinary `/rv @path` calls the native `pi_review` tool and needs no streaming flags. The tool owns normalized events, live rendering, and the packaged CLI process.
+- `--continue`, `--keep-session`, and explicit `--no-stream` use the shell CLI path because they retain single-review session semantics.
 
 ## Streaming vs agent hosts (Claude Code / Codex)
 
-- `pi-review` **streams** child `pi` stdout/stderr to the process terminal by default (`--no-stream` buffers until exit). That helps **Pi** and real terminals, not most agent chat UIs.
-- **Claude Code, Cursor, Codex**, and similar hosts **buffer tool stdout** until the bash command exits, so the chat shows the review **all at once** even though the CLI is streaming. That is expected—not a misconfiguration.
-- Default `text` mode also produces **no stdout** during tool-use/thinking (only the final answer), so even a local terminal stays quiet for most of a multi-minute review.
-- **Recommended for Claude Code / Codex (live progress):** always use `--progress-log <path>` unless the user explicitly wants a silent blocking wait:
-  1. Pick a writable path (e.g. `/tmp/pi-review-<id>.jsonl`).
-  2. Start `pi-review --progress-log <path> ...` in a **background** or **async** shell invocation (not a blocking foreground Bash that you wait on with no updates).
-  3. While the child runs, **tail** the log and summarize milestones to the user (filter out `message_update` / `tool_execution_update` unless they asked for token-level detail).
-  4. When the process exits, show the Markdown body and ASCII `── pi-review` footer from the command result (or re-read the final output as the skill’s step 4 describes).
-- Fall back to a **local terminal** with default streaming only if the host cannot run background commands or tail a file.
+- `pi-review` always runs the child in `--mode json` internally. In streaming mode it forwards **readable text deltas** to stdout live and writes **semantic milestone notices** (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`) to **stderr**. Token usage (`input`/`output`/`cache`/`reasoning`) is accumulated by default — no `--progress-log` required to see it in the ASCII footer or `PI_REVIEW_META_JSON`.
+- `--progress-log <path>` is now an **optional** convenience: it tees the raw `--mode json` event stream to a file for external observation (tail, debugging). It no longer gates token visibility.
+- **Claude Code, Cursor, Codex** and similar hosts still buffer a Bash tool's stdout until the command exits. The semantic milestone notices on stderr + the final Markdown + ASCII footer on stdout give you progress and the result without needing to tail a file. If you still want the full event log for fine-grained debugging, add `--progress-log <path>` and tail it.
+- **Pi interactive** sessions stream text deltas live to the terminal by default — no `--no-stream` or `--progress-log` needed.
 
 ## Review status (no slash command)
 
@@ -78,6 +73,87 @@ There is **no** `/status` slash in this skill. When the user asks for **review s
 
 Do not implement findings from a status check; status is informational only.
 
+## Loop closeout protocol
+
+Use this protocol when the host is closing out implementation work and may edit between reviews. `pi-review` and every child session remain review-only; the host agent owns all fixes.
+
+1. **Freeze the scope baseline before the first review.** Record the originating task, accepted files/modules, required behavior, and proof commands. Do not silently expand this baseline because a reviewer noticed adjacent cleanup.
+2. **Run a bounded structured gate.** Prefer the productized command:
+   ```bash
+   pi-review loop --max-rounds 1 [shared review options] -- <@files|text...>
+   ```
+   A one-round invocation gives the host a fix point between reviews. Increase `--max-rounds` only when repeated independent review of the unchanged tree is intentional; the CLI never waits for edits. Re-invocation after a host fix is a new process. On Claude Code / Codex, compose `loop` with the normal `--progress-log <path>` background + tail workflow. On Pi, retain default foreground streaming. `loop` rejects `--keep-session`, `--continue`, and `--name`.
+3. **Read the gate signals.** Parse `status`, `findings`, and `actionableCount` from each `PI_REVIEW_META_JSON` line and use the final loop summary. Expected statuses are `clean`, `has_findings`, `needs_human`, and `blocked`.
+4. **Apply the scope governor to every finding:**
+   - **in-scope blocker** — accepted, actionable, and required by the frozen task; the host may fix it now.
+   - **follow-up** — valid but outside the baseline or not required for safe closeout; record it without drive-by edits.
+   - **stop-and-escalate** — ambiguous intent, architectural expansion, unsafe migration, blocked tooling, or anything requiring a human decision; stop rather than guess.
+   - A rejected finding must be intentional and recorded with its rationale in the final report. Never silently ignore it.
+   - Check sibling instances of the same bug class only inside the frozen task/PR scope. Do not turn the check into a repository-wide refactor.
+5. **Fix only in-scope blockers in the host.** Never ask the child review session to implement fixes. After each host patch, rerun the narrowest relevant proof (focused test, typecheck, lint, or reproduction) before re-reviewing.
+6. **Re-review until a stop condition:**
+   - `clean` → gate open; proceed to final proof and closeout.
+   - `has_findings` → classify, fix accepted in-scope blockers, and re-invoke within the agreed host-cycle budget.
+   - `needs_human` or `blocked` → stop early and escalate with the review history.
+   - budget exhausted → report remaining findings and ask for a decision; do not loop indefinitely.
+7. **Detect non-convergence.** After two non-converging patch cycles (the same finding persists, findings oscillate, or scope grows), pause and reclassify all remaining findings before any further edit.
+8. **Gate completion claims.** Never claim done, ship, commit-ready, or clean without a fresh `clean` result, unless the user gives explicit human acceptance of named remaining findings. Report accepted fixes, rejected findings with rationale, follow-ups, stop reason, and proof evidence.
+
+The shell exit policy is: `0` clean, `1` status is `has_findings`, `2` usage error, `3` needs human, `4` blocked/runtime failure. A non-zero loop result is a gate signal, not permission for the child reviewer to edit.
+
+## Panel review
+
+Panel review runs multiple **independent** reviewers in isolated child sessions and aggregates their findings into one gate result. Reviewers cannot see one another's findings, so agreement represents independent discovery.
+
+### When to use panel vs single review
+
+- **Single review (default):** keep for small, low-cost changes. Reviewer count defaults to one; the existing execution, output, status mapping, and exit policy stay unchanged.
+- **Panel review:** use when a change deserves independent scrutiny. Activate it with `--reviewers <n>` (2-8) or `--panel <name>`.
+
+### Consensus
+
+A finding becomes a **confirmed finding** (gate-relevant) only when enough independent reviewers mark the issue **actionable**. Otherwise it stays a non-blocking **advisory**.
+
+Consensus policies (default `quorum` for multi-reviewer panels):
+
+| Policy | Threshold |
+|--------|----------|
+| `any` | one actionable reviewer confirms |
+| `quorum` | configured minimum agreement (default 2; set with `--min-agree`) |
+| `majority` | `floor(reviewers / 2) + 1` |
+| `unanimous` | every reviewer |
+
+Multi-reviewer panels default to **quorum with minimum agreement 2** so panel mode never silently becomes any-finding fail-closed. Single-review stays threshold one.
+
+### Advisories
+
+Singleton (uncorroborated) findings remain visible as **advisories** but do **not** change clean status or fail the gate. They are recorded as non-blocking follow-ups; the host promotes them only with explicit human acceptance. Confirmed actionable clusters produce `has_findings`; no confirmed clusters produce `clean`.
+
+### Aggregation
+
+Two-phase matching: deterministic matching on stable anchors (path + normalized summary) first; only ambiguous same-path candidates go to a constrained **semantic adjudicator** (enabled with `--consensus-model`). The adjudicator clusters findings and may **not** invent findings, drop findings, add evidence, or act as another reviewer — it has no write tools. Low-confidence matches stay separate advisories so uncertain similarity cannot manufacture quorum.
+
+### Cost multipliers
+
+Cost is visible before execution. Reviewer runs = `--reviewers <n>` × `--max-rounds` (loop). One consensus-adjudication call may run per round when `--consensus-model` is set, tracked separately. Use `--concurrency <n>` to bound provider/machine pressure (default: reviewer count, never exceeds it).
+
+### Host-only fixes
+
+Panel review composes with Loop Review: one loop round evaluates one **complete panel** with fresh reviewer sessions. The CLI never edits, patches, or waits for filesystem changes — the host agent remains the only actor allowed to fix between process invocations. Apply the scope governor to **confirmed** findings exactly as for single-review findings. Rejected confirmed findings must be recorded with rationale. `--max-rounds 1` keeps the patch-by-patch closeout workflow.
+
+Panel review rejects `--keep-session`, `--continue`, and `--name` in v1 (reviewers run `--no-session`). Reviewer runtime failure → `blocked`; unstructured dirty output or unresolved clarification → `needs_human`; never silently clean.
+
+### Examples
+
+```bash
+# Single panel review
+pi-review --reviewers 3 --consensus quorum --min-agree 2 -- @src
+# Expert preset
+pi-review --panel code-experts --consensus majority -- @src
+# Panel loop review (up to 6 reviewer runs + adjudication)
+pi-review loop --reviewers 3 --consensus quorum --max-rounds 2 -- @src
+```
+
 ## Steps
 
 1. Prime the model catalog and pick a model:
@@ -116,8 +192,8 @@ Do not implement findings from a status check; status is informational only.
 
 4. Return the result:
    - Show the Markdown review body and the **ASCII footer** (`── pi-review` block on stdout). Do not paste raw `PI_REVIEW_META_JSON` to the user unless they ask for machine output.
-   - Scripts: parse `PI_REVIEW_META_JSON:` from **stderr** (or set `PI_REVIEW_META_STDOUT=1` to also emit JSON on stdout).
-   - Do not apply findings automatically; implementation is a separate user decision.
+   - Scripts: parse `PI_REVIEW_META_JSON:` from **stderr** (or set `PI_REVIEW_META_STDOUT=1` to emit JSON on stdout instead).
+   - For an ordinary review-only request, do not apply findings automatically; implementation is a separate user decision. When the user already requested implementation closeout, follow **Loop closeout protocol** and let only the host fix accepted in-scope blockers.
    Completion criterion: the user sees the review conclusion and readable footer.
 
 ## Examples
@@ -127,6 +203,8 @@ pi-review -- @src/foo.ts
 pi-review --model openai/gpt-5.5 -- @src/foo.ts
 pi-review --mode challenge --keep-session -- @docs/design.md
 pi-review --mode challenge --continue <sessionHandle> -- "expand finding 2"
+pi-review loop --max-rounds 1 -- @src
+pi-review loop --max-rounds 1 --progress-log /tmp/pi-review-loop.jsonl -- @src
 ```
 
 ## Status examples (user phrasing)

package/skills/pi-review/references/codex-tools.md

@@ -12,19 +12,32 @@ General Codex subagent and worktree mappings live in the **using-superpowers** s
 
 ## Long-running `pi-review` (default on Codex / Claude Code)
 
-Native shell tools usually **buffer stdout/stderr until the command exits**. A multi-minute `pi-review` run can look like a silent wait, then one large dump—even though the CLI streams by default. Default `text` mode also emits **no stdout** during tool-use/thinking (only the final answer).
+Native shell tools usually **buffer stdout/stderr until the command exits**. A multi-minute `pi-review` run can look like a silent wait, then one large dump. `pi-review` mitigates this in two ways that need **no** `--progress-log`:
+
+1. **Semantic milestone notices on stderr** (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`). Capture stderr separately or interleave it to show progress.
+2. **Token usage by default**: the ASCII footer and `PI_REVIEW_META_JSON` always include `thinking` + token usage (`input`/`output`/`cache`/`reasoning`) when the child session reports them — no `--progress-log` required.
 
 When the **pi-review** skill applies on Codex, Claude Code, or Cursor:
 
-1. **Default:** `pi-review --progress-log <path> ...` (writable file, e.g. `/tmp/pi-review-<id>.jsonl`).
-2. Start that command in a **background** or **async** shell invocation—not a single blocking call with no interim updates.
-3. **Tail** the log while the child runs; summarize milestones to the user (skip `message_update` / `tool_execution_update` unless they want token-level detail).
-4. After exit, show the Markdown review and ASCII `── pi-review` footer (skill step 4).
+1. **Default:** run `pi-review ... -- <target>` (foreground or background). Stderr carries milestone notices; stdout carries the review Markdown + ASCII footer on exit.
+2. If you want the **full** `--mode json` event log for fine-grained debugging, add `--progress-log <path>` and tail it — but this is optional, not required for tokens or progress.
+3. After exit, show the Markdown review body and ASCII `── pi-review` footer (skill step 4).
 
-**Pi interactive (`/rv`)** is different: foreground `pi-review`, default streaming only—do **not** auto-add `--progress-log` unless the user asked.
+**Pi interactive (`/rv`)**: foreground `pi-review`, default streaming. Text deltas appear live on the terminal; no `--progress-log` unless the user asked.
 
 See the parent skill: sections *Default workflow by host* and *Streaming vs agent hosts (Claude Code / Codex)*.
 
+### Loop closeout
+
+`loop` composes with the same default streaming + stderr-milestone workflow:
+
+```bash
+pi-review loop --max-rounds 1 -- @src
+# optional: --progress-log /tmp/pi-review-loop.jsonl for the full event log
+```
+
+A non-zero command exit is an expected gate result when findings remain. Wait for the process, read the final `PI_REVIEW_META_JSON` / loop summary, let the host fix only accepted in-scope findings, rerun focused proof, and invoke a new loop process. The child review session never edits. Reuse or truncate the progress log deliberately because every loop round appends events to the chosen path.
+
 **Model choice:** after `pi-review models`, use **[model-selection.md](./model-selection.md)** (code / frontend / plan presets)—same guidance as Pi `/rv` completions.
 
 Example tail (milestone events only):