pi-workflow-engine 0.13.0 → 1.1.0

package/USAGE.md

@@ -2,7 +2,7 @@
 
 `pi-workflow-engine` adds zero-dependency Dynamax workflows to pi: opt into live, parallel subagents for the tasks that need a custom investigation instead of one long prompt. Most users only need these surfaces:
 
-This release requires **pi 0.80.10 or newer**. pi remains host-provided rather
+This release requires **pi 1.0.0 or newer**. pi remains host-provided rather
 than bundled by this package, and the extension rejects older runtimes at load
 time with an update message.
 
@@ -36,7 +36,7 @@ Useful flags:
 /workflow code-review --concurrency=4    # cap concurrent subagents
 /workflow code-review --max-agents=20    # cap total live agent calls in the run
 /workflow code-review --agent-timeout-ms=600000 # abort one live agent after 10 minutes
-/workflow code-review --agent-retries=2  # retry classified transient provider failures
+/workflow code-review --agent-retries=2  # restart agents whose in-session retries are exhausted
 /workflow code-review --budget=50000     # output-token ceiling for subagents
 /workflow code-review --resume <run-id>  # replay matching completed agent calls
 /workflow code-review --resume <run-id> --resume-edited # reuse unchanged calls after a workflow edit
@@ -109,7 +109,9 @@ command instead of selecting another model.
 as external web search, browsing, or HTTP(S) page extraction. Local grep/find
 tools do not satisfy this check. The workflow does not bundle a scraper or a
 paid API; install or enable the web capability you prefer, then restart or
-reload pi so subagent sessions can see it.
+reload pi so subagent sessions can see it. An MCP web search server also
+qualifies when the host agent runs `research` through the `workflow` tool,
+because only those runs can reach the host's MCP tools.
 
 The workflow bounds decomposition to four lanes and verification to twelve
 claims, while the engine's concurrency, total-agent, timeout, cancellation, and
@@ -124,7 +126,7 @@ the journal's deterministic replay surface.
 
 Use `dynamax` when the built-in workflows are not specific enough and you want the main pi agent to author a temporary workflow for the current question. It is the fastest path from "this needs multiple angles" to a live fan-out, verifier pass, and synthesized result.
 
-Interactive shortcut: run `/workflow` with no arguments, choose `✍ Author temporary one-shot workflow…`, and type a brief. pi will send that brief back to the host agent as a `dynamax` request so it can author and run an inline workflow with the `workflow` tool's `script` argument.
+Interactive shortcut: run `/workflow` with no arguments, choose `+ author a one-off workflow` (the last row, below the registered workflows), and type a brief. Escape closes the picker without running anything. pi will send that brief back to the host agent as a `dynamax` request so it can author and run an inline workflow with the `workflow` tool's `script` argument.
 
 That inline workflow should investigate, fan out, verify, and summarize. It is **not** where code edits happen. If you want changes made, use the workflow result as evidence and then ask pi to edit separately.
 
@@ -146,7 +148,7 @@ Sticky mode and inspector shortcut:
 
 The workflow inspector and code-review results viewer are also registered as first-class shortcuts shown by `/hotkeys`. The defaults are `ctrl+shift+m` for the inspector and `ctrl+shift+r` for the latest review results. `ctrl+o` is intentionally not used because pi already uses it for tool-output expansion and tree filtering.
 
-When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives the workflow permission reminder, stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. Sticky mode, one-shot pending mode, and active Dynamax workflow runs show compact TUI status with `/workflow:dynamax on|off` and the inspector shortcut; off mode clears that status line.
+When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives a `<dynamax>` system prompt section that permits the workflow tool (pi appends it as a section patch, so the cached prompt head is kept), stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. The footer status states the mode compactly: `◆ dynamax` while sticky, `◆ dynamax · next prompt` while a one-shot waits for its prompt, and `◆ dynamax · this turn` while that run is active; off mode clears it. A running workflow names itself in its own status next to it.
 
 ### Prompt editor cue
 
@@ -160,7 +162,7 @@ The default effect is `shine`. Set `PI_DYNAMAX_EFFECT=static` for a motionless
 cue or `PI_DYNAMAX_EFFECT=off` to disable it. A non-empty `NO_COLOR` also
 disables the default cue; an explicit `PI_DYNAMAX_EFFECT` value takes precedence.
 
-The implementation follows pi 0.80.10's [official `CustomEditor`
+The implementation follows pi's [official `CustomEditor`
 pattern](https://pi.dev/docs/latest/extensions#custom-editor): it decorates only
 the editor's rendered lines, retaining the wrapped editor's input, cursor,
 deletion, paste, multiline, undo, completion, IME, and app-keybinding behavior.
@@ -172,7 +174,7 @@ is used so highlighting is never silently disabled. Pi editor registration is
 still last-writer-wins; the previous editor is restored on shutdown only while
 the Dynamax decorator still owns the registration.
 
-When the host agent calls the `workflow` tool from a TUI session, pi opens the live workflow inspector for that run. The compact workflow widget still shows the latest moving status above the editor, but the inspector is the richer view for phases, agents, findings, and logs.
+When the host agent calls the `workflow` tool, the inspector stays closed so the agent's reply remains in view; the compact workflow widget shows the moving status above the editor. Press the inspector shortcut or run `/workflow:inspector` for the richer view of phases, agents, findings, and logs, live or after the run.
 
 Configure either shortcut by creating `~/.pi/agent/extensions/pi-workflow-engine.json`:
 
@@ -241,9 +243,11 @@ Workflow results are rendered in pi with:
 
 These workflow usage totals are separate from `--perf`, which is internal timing only. They are also separate from pi's built-in footer and `/session` totals, which may still show host-session usage only unless pi core adds a first-class extension usage API. If a model has no pricing configured, token totals can be non-zero while displayed cost remains `$0.000`.
 
-The result, inspector overview, compact widget, and status line all use the same usage summary. Providers with a complete breakdown show `fresh`, `cache read`, `cache write`, and `output` separately. Zero cache components are omitted. If a provider reports only some components, the summary labels mixed-run component totals with `≥` and preserves the provider's aggregate `total`; if it reports no components, the summary falls back to aggregate `tokens`. Costs are summed from provider session totals and are never inferred from local pricing.
+Results, the inspector overview, the runs browser and the live widget header show usage in the compact form `↑34k ↓1.2k · $0.02` (input including cache, output, and cost when known); the footer status line carries no usage. The result text handed to the host agent keeps the full breakdown: providers with a complete breakdown show `fresh`, `cache read`, `cache write`, and `output` separately. Zero cache components are omitted. If a provider reports only some components, the summary labels mixed-run component totals with `≥` and preserves the provider's aggregate `total`; if it reports no components, the summary falls back to aggregate `tokens`. Costs are summed from provider session totals and are never inferred from local pricing.
 
-During a run, pi shows live phases and subagent status. Use `--inspect` if you want a larger live view while the workflow is active, then `/workflow:inspector` if you want to bring the last completed inspector back up afterward.
+During a run, a widget above the editor shows the workflow's progress bar, finished/total agents, elapsed time and usage; phases in chronological order, with finished phases collapsed to one line and the active phase listing its running, failed and done agents; the declared phases not reached yet; the workflow's counters; and the inspector shortcut. The footer status line reads `◆ review · Find 6/10 · 12s`. Use `--inspect` if you want a larger live view while the workflow is active, then `/workflow:inspector` if you want to bring the last completed inspector back up afterward.
+
+The inspector has Overview, Agents, Findings, and Logs sections, plus Result for a retained run opened from `/workflow:runs`. Switch sections with `tab`/`shift+tab`, `←`/`→`, or `1`–`5`; move with `↑`/`↓` or `j`/`k`, jump with `g`/`G`, expand an agent or finding with `enter`, and close with `q` or `esc`. Expanded agents show the full error, last tool, model, and token usage.
 
 ### Durable run records
 
@@ -257,7 +261,7 @@ Persistence is intentionally bounded and private by default. Raw workflow args,
 
 The host-facing `workflow` tool accepts `background: true`. It returns as soon as the run ID and origin metadata are durably recorded, while the normal workflow engine continues in-process with the same concurrency, budget, worktree, progress, usage, and resume rules. Synchronous execution remains the default, and the `/workflow` slash command remains synchronous.
 
-Background runs are detached from the initiating tool-call signal, so the host agent can finish that turn and continue the conversation. When the run completes or fails, the extension waits for the originating session to become idle and inserts one concise `workflow-result` message containing the run ID, terminal state, and summary. Delivery state is stored with the run record; on reload, the extension checks both that state and the session message history before retrying, which suppresses duplicates even if persistence failed immediately after message insertion.
+Background runs are detached from the initiating tool-call signal, so the host agent can finish that turn and continue the conversation. While one runs, it shows a single line above the editor (`◆ background · code-review 56b57550 · Find 6/10 · 12s`) instead of the full live widget. When the run completes or fails, the extension waits for the originating session to become idle and inserts one concise `workflow-result` message containing the run ID, terminal state, and summary. Delivery state is stored with the run record; on reload, the extension checks both that state and the session message history before retrying, which suppresses duplicates even if persistence failed immediately after message insertion.
 
 Provider usage-window continuation is a separate, explicit background option:
 
@@ -281,7 +285,7 @@ A graceful pi session shutdown aborts active background work and records it as `
 
 ### Recent runs and lifecycle actions
 
-`/workflow:runs` opens pi's native selection UI with a bounded list of recent project runs. Each option includes an accessible state label, workflow name, age, duration, usage summary, and full run ID. Choose a run, then choose one of the lifecycle actions currently valid for it: inspect, stop, resume, or restart. The background activity line is present only while this session owns active background work.
+`/workflow:runs` opens a runs browser in the TUI: one aligned row per recent project run (state glyph and word, workflow, duration, age, cost when known, short run ID) above a details pane for the selected run with its wall-clock times, phases, agent and token counts, resume lineage, pause details, outcome, and why a relaunch is unavailable when it is. Keys act on the selected run: `enter` or `i` inspect, `r` resume, `s` stop (press twice), `R` restart; only the actions currently valid for that run are listed in the footer, and the others explain why they are unavailable. The browser refreshes while a run is active and reopens on the same run after an action. RPC sessions keep pi's native two-step selection (run, then action). The background activity line is present only while this session owns active background work.
 
 The same operations are available without the selection UI:
 
@@ -293,9 +297,9 @@ The same operations are available without the selection UI:
 /workflow:inspector <run-id>
 ```
 
-Inspect is always safe. Stop is available for a background run active in the current session and for a retained paused run with a pending resume timer. Resume is limited to paused registered workflows whose source fingerprint is unchanged and whose invocation had no redacted arguments; it starts a new background run ID with `resumeFromRunId` journal replay. Restart is limited to completed, failed, or stopped registered workflows that had no arguments and also creates a new background run ID. Inline workflows and argument-bearing invocations are intentionally not relaunched because their executable input was not persisted. In `print` and `json` modes, list and inspect return formatted text without opening TUI components, while resume/restart report that background execution requires TUI or RPC mode.
+Inspect is always safe. Stop is available for a background run active in the current session and for a retained paused run with a pending resume timer. Resume is limited to paused registered workflows whose source fingerprint is unchanged and whose invocation had no redacted arguments; it starts a new background run ID with `resumeFromRunId` journal replay. A paused run already resumed by a queued, running, paused, or completed run is listed as `resumed as <run-id>` and offers no second resume; once every resume of it has failed or been stopped, manual resume is offered again, while automatic provider-limit resume never fires twice for the same paused run. Restart is limited to completed, failed, or stopped registered workflows that had no arguments and also creates a new background run ID. Inline workflows and argument-bearing invocations are intentionally not relaunched because their executable input was not persisted. In `print` and `json` modes, list and inspect return formatted text without opening TUI components, while resume/restart report that background execution requires TUI or RPC mode.
 
-Code-review findings are rendered as a formatted result message by default. pi no longer asks whether to open the findings viewer. Use `--result-viewer` or `--review-viewer` when you want to inspect findings interactively, press `enter` to expand/collapse the nicely formatted finding text, and use `1`-`9` to jump directly to a visible finding. The viewer is centred, scales to the terminal, and shows the visible finding/detail ranges while scrolling. `/workflow:results` or `ctrl+shift+r` reopens the most recent validated code-review report in the current pi session without rerunning the workflow; selections reset when it reopens.
+Code-review findings are rendered as a formatted result message by default. pi no longer asks whether to open the findings viewer. Use `--result-viewer` or `--review-viewer` when you want to inspect findings interactively. The viewer lists findings most severe first with the selected finding's full detail beside the list (below it in narrow terminals); `space` or `enter` selects a finding, `a` toggles all, `f` generates patch previews and `c` posts PR comments for the selection, and `pgup`/`pgdn` scroll a long detail. The viewer is sized to its content and shows scroll hints only when something is clipped. `/workflow:results` or `ctrl+shift+r` reopens the most recent validated code-review report in the current pi session without rerunning the workflow; selections reset when it reopens.
 
 The Fix action revalidates the exact reviewed PR/ref/index/working-tree snapshot, then runs each selected finding through its own worktree-isolated agent and returns the finding ID, validation summary, patch, and changed status. Failed attempts do not discard successful previews, no patch is applied to your active tree automatically, and a moved or unverifiable review target is rejected rather than patched against the wrong code. The original review and all Fix previews retained in that pi session share one output-token budget. Reopening the viewer does not reset it, finalized preview usage is always deducted, and only one preview can run at a time.
 
@@ -421,6 +425,11 @@ overrides its profile.
 
 `tools` is a strict allowlist. If you set `tools: ["read", "bash"]`, extension tools such as `ast-grep`, `mgrep`, `fffind`, or `ffgrep` are hidden from that subagent. Add `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools while keeping the concrete base allowlist portable. Use `toolHints: ["external-search"]` for installed web search, browsing, and URL-extraction tools; `requireToolHints: true` fails before prompting unless each requested capability matched. The built-in advisory workflows use `tools: ["read", "bash", "grep", "find", "ls"]` plus `toolHints: ["search"]`.
 
+Subagents are SDK sessions, so pi's built-in codemode and MCP extensions do not load in them. Two opt-ins cover that:
+
+- **Codemode.** Add `"codemode"` to an agent's `tools` to let it batch or filter many tool calls in one script, for example `tools: ["read", "grep", "codemode"]`. Scripts can call only that agent's other allowed tools, and never `final_answer`. Classifier calls a script makes count toward the run's usage and budget.
+- **Host MCP tools.** In runs started by the `workflow` tool, subagents reach the host's MCP tools over its existing connections and through its permission handlers. Name a tool in `tools` (for example `"mcp__linear__create_issue"`), or use `toolHints: ["external-search"]` to pick up MCP web research tools; servers that declare a tool not read-only or closed-world are excluded from that hint. Bridged tools act in the host session, so the local `search` hint never bridges them, and an isolated worktree agent that names a local MCP tool sees the main checkout through it, not its worktree. `/workflow` commands and background runs outlive the host tool call that makes this possible: an agent there that names an MCP tool fails before prompting rather than running without it.
+
 Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; if `tools` is also restricted, the engine automatically keeps `read` available so the subagent can load the selected `SKILL.md`. When `skills` is omitted, clear prompt text such as `/skill:name`, `include skill name`, or `use the name skill` is also treated as an opt-in. Pass `skills: []` to suppress that inference.
 
 Set `model` only when a subagent should use a specific model. Bare ids keep the Anthropic shorthand; `provider/id` targets built-in, custom, or local providers. Explicit models override a requested profile; calls with neither inherit the host/session default. Malformed or unknown explicit refs fail fast.
@@ -459,18 +468,37 @@ export default async function run({ workflow }: WorkflowApi) {
 
 Nesting is one level only: calling `workflow()` from inside a sub-workflow rejects. Resolution throws on an unknown name. Inside `parallel()` or `pipeline()`, recoverable branch errors become `null` results, so filter nulls before synthesis; a genuine run abort still rejects.
 
+### Classify between stages
+
+`classify(context, opts?)` answers typed `choice`, `score`, or `bool` questions about JSON `state` with one of pi's classifier models (for example TypeSafe Jev or Cloudflare Clef), using the host's credentials and no chat session. It suits cheap gates between stages, such as deduplicating findings or deciding which items need a follow-up agent.
+
+```ts
+const answers = await api.classify(
+  {
+    state: { finding },
+    questions: {
+      followUp: { type: "bool", instructions: "Does this finding need verification?", criteria: { true: "Plausible but unproven", false: "Clearly settled" } },
+    },
+  },
+  { label: `triage:${finding.id}` },
+);
+if (answers.followUp?.type === "bool" && answers.followUp.probability > 0.5) { /* verify it */ }
+```
+
+Without `opts.model` ("provider/id"), the first classifier with working credentials is used. Calls share the run's concurrency cap, count toward usage and the budget, and are not journaled, so a resumed run classifies again. When no classifier is configured the call rejects with a recoverable error, so guard it or let `parallel()` turn it into `null`.
+
 ### Where workflows live
 
 Guaranteed built-ins are statically registered:
 
 1. Add `.pi/extensions/pi-workflow-engine/workflows/<name>.ts`.
 2. Import it in `.pi/extensions/pi-workflow-engine/src/workflows.ts`.
-3. Add it to `BUILTIN_WORKFLOWS`.
+3. Add a `defineBuiltinWorkflow(mod, "<name>.ts")` entry to `BUILTIN_WORKFLOW_DEFINITIONS`.
 
 Drop-in workflows are also discovered best-effort from:
 
-- `.pi/extensions/pi-workflow-engine/workflows/*.ts`
-- `~/.pi/agent/workflows/*.ts`
+- `~/.pi/agent/workflows/*.ts`: the user-level drop-in directory, which survives `pi update`.
+- The extension's own `workflows/*.ts` directory: `.pi/extensions/pi-workflow-engine/workflows/` in a working copy or a project-vendored copy. Files added to an installed package are replaced by `pi update`.
 
 Use `/workflow <name> --refresh` after adding a drop-in file.
 
@@ -517,7 +545,7 @@ Only tune these when a workflow is too slow, too expensive, or too noisy:
 | `--parallel-limit=N` / `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` | Limit eager `parallel()` submission. |
 | `--max-agents=N` / `PI_WORKFLOW_MAX_AGENTS=N` | Cap live model calls across the complete run, including sub-workflows. Default `64`; values are clamped to `1`–`10000`. Replay hits do not consume the cap. The `workflow` tool field is `maxAgents`. |
 | `--agent-timeout-ms=N` / `PI_WORKFLOW_AGENT_TIMEOUT_MS=N` | Abort one live agent after this duration. Default `1800000` (30 minutes); values are clamped to `1000`–`86400000`. The session is aborted and its isolated worktree is cleaned up. The `workflow` tool field is `agentTimeoutMs`. |
-| `--agent-retries=N` / `PI_WORKFLOW_AGENT_RETRIES=N` | Retry terminal assistant failures that pi classifies as transient provider or transport errors. Default `0`; values are clamped to `0`–`10`. Backoff starts at one second, doubles, and caps at 30 seconds. The `workflow` tool field is `agentRetries`. |
+| `--agent-retries=N` / `PI_WORKFLOW_AGENT_RETRIES=N` | Restart the whole agent after a transient provider or transport failure that pi's in-session turn retry could not recover. Default `0`; values are clamped to `0`–`10`. Backoff starts at one second, doubles, and caps at 30 seconds. The `workflow` tool field is `agentRetries`. |
 | `--budget=N` / `PI_WORKFLOW_BUDGET=N` | Set an output-token ceiling across recorded subagent attempts, including failed provider attempts. `agent()` throws `WorkflowBudgetExceededError` before starting another model request once the ceiling is reached; agents already running may overshoot because the engine does not reserve per-agent estimates. |
 | `--perf` / `PI_WORKFLOW_PERF=1` | Include internal timing aggregates. Usage/cost totals are reported separately from perf. |
 | `PI_WORKFLOW_LANE_ITEM_LIMIT=N` | Cap retained progress lane items. |
@@ -525,17 +553,29 @@ Only tune these when a workflow is too slow, too expensive, or too noisy:
 These controls bound different dimensions: concurrency limits how many agents
 are active together, `max-agents` limits how many live model calls the run may
 start in total, `agent-timeout-ms` bounds one active call (including retry
-backoff), and `budget` limits recorded output tokens. Every retry consumes
+backoff), and `budget` limits recorded output tokens. Every agent restart consumes
 another live-agent admission and remains inside the original timeout, budget,
 and abort scope. Usage from failed attempts is retained, so it can exhaust the
 budget before the next retry begins. Host cancellation takes precedence over
 limit and timeout failures.
 
-Workflow subagents disable pi's session-level automatic retry so this run-level
-policy is authoritative and visible in the existing agent progress row. Invalid
+Transient provider failures are retried in two layers. First, each subagent
+inherits pi's session-level automatic retry from your pi `retry` settings
+(enabled by default: 3 retries with 2s, 4s, 8s backoff). It retries the failed
+turn in place, keeping the agent's earlier tool work; each attempt is logged in
+the workflow progress log, and usage from failed attempts is still recorded.
+Like the agent's other turns, these in-place retries are not budget-checked, and
+a retryable rate-limit or usage-limit error is retried in-session before a
+background run's usage-limit pause takes effect. Only when those retries are
+exhausted does `--agent-retries` restart the agent from scratch. Invalid
 models, schema-contract failures, exhausted budgets, agent limits, worktree
 failures, timeouts, and host aborts are never provider-retried.
 
+pi-workflow-engine 0.12.0 and 0.13.0 wrote `"retry": {"enabled": false}` into
+`~/.pi/agent/settings.json` whenever a workflow ran, which disables automatic
+retry for the host session and every subagent. Workflow runs log a warning while
+that setting is in effect; remove it unless you disabled retry on purpose.
+
 ## Common fixes
 
 - **Unknown workflow**: confirm the extension is loaded with `pi list`; use `--refresh` for new drop-ins.
@@ -561,6 +601,25 @@ fails, the result retains verified records and reports incomplete coverage.
 Synthesis selects or merges IDs; the workflow reconstructs evidence-bearing
 fields from those records.
 
+### Duplicate candidates
+
+Lenses often report the same defect in different words. When a TypeSafe Jev
+classifier is reachable (TypeSafe directly, OpenRouter, Cloudflare Workers AI,
+Vercel AI Gateway, or OpenCode Zen), the four advisory workflows ask it whether
+each pair of candidates in the same file describes one defect. Before
+verification, a candidate joins a group only when the classifier is at least 80%
+sure it matches every member, so each defect gets one verifier. Merged
+candidates keep all of their source IDs, locations, impacts, and evidence, and
+the verifier sees the other wordings as "Also reported as" evidence. If the
+first comparison fails (no Jev credentials, a bad key, a rate limit), the merge
+is skipped.
+
+Measured on GPT-6.1 Sol code reviews with planted bugs, the merge cut verifier
+agents and cost by about 40% (e.g. 29 → 18 agents, $0.60 → $0.37 list price on
+a small diff; 22 → 14 agents, $1.74 → $0.89 on a 160 KB diff). In every
+instrumented run, each planted bug that a finder proposed reached the final
+report, with or without merging.
+
 ### Selective adversarial challenges
 
 Add `--challenge` to an advisory workflow to challenge up to three uncertain or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.13.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [
@@ -22,7 +22,6 @@
   },
   "files": [
     ".pi/extensions/pi-workflow-engine",
-    ".pi/settings.json",
     "assets/preview.png",
     "skills",
     "README.md",

package/skills/workflow-code-review-actions/SKILL.md

@@ -1,38 +1,27 @@
 ---
 name: workflow-code-review-actions
-description: "Act on selected code-review findings from pi-workflow-engine: make minimal fixes or post GitHub PR inline comments using gh, GitHub MCP/tools, or project-specific tools."
+description: "Act on selected code-review findings from pi-workflow-engine: post GitHub PR inline comments using gh, GitHub MCP/tools, or project-specific tools."
 ---
 
-Use this skill when the parent agent receives selected code-review finding JSON from `pi-workflow-engine`.
+Use this skill when the parent agent receives selected code-review finding JSON from `pi-workflow-engine`. The engine hands comments to the parent agent only when its own `gh` posting could not resolve the PR or failed for some findings.
+
+Fixes are never handed off: the results viewer generates isolated, independently validated patch previews for selected findings. Do not edit files in response to a code-review handoff.
 
 ## Inputs
 
-The prompt will include compact JSON with:
+The prompt will include the verified reviewed PR head SHA, the reason the engine could not post the comments itself, and compact JSON with:
 
-- `context`: workflow name, target, diff command, changed files, and optional summary.
+- `context`: workflow name, target, `diffTarget` (with the PR `number`), display `diffCommand`, changed files, optional summary, and optional snapshot identity.
 - `issues`: selected findings with `id`, `summary`, `category`, `severity`, `confidence`, `location`, `impact`, `evidence`, and `recommendation`.
 
-## Fix mode
-
-When mode is `fix selected code-review findings`:
-
-1. Inspect the selected issue JSON before editing.
-2. Make minimal edits that address only the selected findings.
-3. Preserve unrelated user changes and avoid broad refactors.
-4. Run focused validation if available for the touched files or behavior.
-5. Summarize changed files and validation results.
-6. Do not post GitHub PR comments in fix mode.
-
-## Comment mode
-
-When mode is `post inline GitHub PR comments`:
+## Posting comments
 
-1. Do not edit files or make code changes.
-2. Prefer installed GitHub MCP/tools if visible in the active tool list.
+1. Prefer installed GitHub MCP/tools if visible in the active tool list.
+2. Before posting, resolve the current PR head and require it to equal the verified reviewed head from the prompt; stop if it differs.
 3. If no GitHub MCP/tools are available, use `gh`:
-   - Resolve the PR with `gh pr view --json number,headRefOid,url,headRepositoryOwner,headRepository`.
-   - Resolve the repository with `gh repo view --json nameWithOwner` when owner/name is missing.
-   - Post each inline comment with `gh api repos/{owner}/{repo}/pulls/{number}/comments` and include `commit_id`, `path`, `line`, and `side=RIGHT`.
+   - Resolve the PR with `gh pr view <context.diffTarget.number> --json headRefOid,url`.
+   - Take owner/repo from the PR `url`, which names the base repository, so fork PRs are commented upstream. Do not use `headRepositoryOwner`/`headRepository`; on a fork PR they name the fork. Fall back to `gh repo view --json nameWithOwner` only if the URL is missing.
+   - Post each inline comment with `gh api repos/{owner}/{repo}/pulls/{number}/comments` and include `commit_id` (the verified head), `path`, `line`, and `side=RIGHT`.
 4. Keep each comment concise: summary, severity/confidence/category, impact, evidence, and recommendation.
 5. Report posted, skipped, and failed counts.
 

package/.pi/extensions/pi-workflow-engine/src/diff-capture.ts

@@ -1,81 +0,0 @@
-import type { PerfSink } from "./perf.ts";
-import { runBoundedProcess, type BoundedProcessFailure } from "./process-runner.ts";
-import { parseAllowedDiffCommand, reviewDiffCommand, type ReviewDiffTarget } from "./review-diff-target.ts";
-
-export {
-  formatReviewDiffTarget,
-  GitReviewDiffTargetSchema,
-  isReviewDiffTarget,
-  parseAllowedDiffCommand,
-  PullRequestReviewDiffTargetSchema,
-  reviewDiffCommand,
-  ReviewDiffTargetSchema,
-  reviewGitDiffBaseline,
-  type GitDiffBaselineTarget,
-  type GitReviewDiffTarget,
-  type PullRequestReviewDiffTarget,
-  type ReviewDiffTarget,
-} from "./review-diff-target.ts";
-
-interface DiffCaptureResultBase {
-  readonly stdout: string;
-  readonly durationMs: number;
-  readonly bytes: number;
-}
-
-export type DiffCaptureResult =
-  | (DiffCaptureResultBase & { readonly ok: true; readonly error?: undefined; readonly failure?: undefined })
-  | (DiffCaptureResultBase & { readonly ok: false; readonly error: string; readonly failure: DiffCaptureFailure });
-
-export type DiffCaptureFailure = BoundedProcessFailure | { readonly kind: "invalid-target"; readonly message: string };
-
-export interface DiffCaptureOptions {
-  readonly cwd: string;
-  readonly signal?: AbortSignal;
-  readonly timeoutMs: number;
-  readonly maxBufferBytes: number;
-  readonly perf?: PerfSink;
-  readonly env?: NodeJS.ProcessEnv;
-  readonly killGraceMs?: number;
-}
-
-export async function captureDiff(command: string, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
-  const parsed = parseAllowedDiffCommand(command);
-  if ("error" in parsed) {
-    return {
-      ok: false,
-      stdout: "",
-      durationMs: 0,
-      bytes: 0,
-      error: parsed.error,
-      failure: { kind: "invalid-target", message: parsed.error },
-    };
-  }
-
-  return await captureDiffTarget(parsed, options);
-}
-
-export async function captureDiffTarget(target: ReviewDiffTarget, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
-  const command = reviewDiffCommand(target);
-  const result = await runBoundedProcess({
-    file: command.file,
-    args: command.args,
-    cwd: options.cwd,
-    env: diffCaptureEnv(options.env),
-    signal: options.signal,
-    timeoutMs: options.timeoutMs,
-    maxBufferBytes: options.maxBufferBytes,
-    killGraceMs: options.killGraceMs,
-    abortError: "diff capture aborted",
-    timeoutError: `diff capture timed out after ${options.timeoutMs}ms`,
-    maxBufferError: `diff capture exceeded ${options.maxBufferBytes} bytes`,
-    exitError: (stderr, code, signal) => stderr.trim() || `diff command exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
-  });
-  options.perf?.observe("diff.capture_ms", result.durationMs);
-  options.perf?.observe("diff.bytes", result.bytes);
-  return result;
-}
-
-function diffCaptureEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {
-  return { ...(env ?? process.env), GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" };
-}

package/.pi/extensions/pi-workflow-engine/src/review/code-review-orchestration.ts

@@ -1,24 +0,0 @@
-const DIFF_EMBED_CAP = 60_000;
-
-export function buildCodeReviewScopeBlock(input: {
-  readonly diffCommand: string;
-  readonly files: readonly string[];
-  readonly summary: string;
-  readonly conventions?: string;
-  readonly diffText: string;
-  readonly target: string;
-}): string {
-  const diffBlock = input.diffText
-    ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
-        input.diffText.length > DIFF_EMBED_CAP
-          ? `${input.diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${input.diffCommand}\` for the full diff)`
-          : input.diffText
-      }\n\`\`\`\n`
-    : "";
-  return (
-    `## Diff command\n${input.diffCommand}\n\n## Changed files\n${input.files.map((file) => `- ${file}`).join("\n")}\n\n` +
-    `## Summary\n${input.summary}\n\n## Conventions\n${input.conventions ?? "(none noted)"}\n` +
-    diffBlock +
-    (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
-  );
-}

package/.pi/extensions/pi-workflow-engine/src/review/review-results-flow.ts

@@ -1,52 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { WorkflowRunOptions } from "../types.ts";
-import { toReviewIssues, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
-import { isReviewReport, type ReviewReport } from "./review-report.ts";
-import { ReviewResultsViewer } from "./review-results-viewer.ts";
-import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "../ui/workflow-viewer-layout.ts";
-
-export type ReviewResultsPresentationDecision =
-  | {
-      readonly kind: "send";
-      readonly reason: "not-code-review" | "not-advisory" | "no-findings" | "disabled" | "not-tui" | "not-requested";
-    }
-  | { readonly kind: "open"; readonly issues: readonly ReviewIssue[] };
-
-export interface ReviewResultsDecisionInput {
-  readonly workflowName: string;
-  readonly result: unknown;
-  readonly mode?: string;
-  readonly hasUI: boolean;
-  readonly resultViewer?: WorkflowRunOptions["resultViewer"];
-}
-
-export function codeReviewReport(workflowName: string, result: unknown): ReviewReport | undefined {
-  return workflowName === "code-review" && isReviewReport(result) ? result : undefined;
-}
-
-export interface ReviewResultsViewerContext {
-  readonly ui: Pick<ExtensionContext["ui"], "custom">;
-}
-
-export function decideReviewResultsPresentation(input: ReviewResultsDecisionInput): ReviewResultsPresentationDecision {
-  if (input.workflowName !== "code-review") return { kind: "send", reason: "not-code-review" };
-  const report = codeReviewReport(input.workflowName, input.result);
-  if (!report) return { kind: "send", reason: "not-advisory" };
-  if (report.findings.length === 0) return { kind: "send", reason: "no-findings" };
-  if (input.resultViewer === "skip") return { kind: "send", reason: "disabled" };
-  if (input.mode !== "tui" || !input.hasUI) return { kind: "send", reason: "not-tui" };
-
-  if (input.resultViewer !== "open") return { kind: "send", reason: "not-requested" };
-
-  return { kind: "open", issues: toReviewIssues(input.workflowName, report) };
-}
-
-export async function showReviewResultsViewer(
-  ctx: ReviewResultsViewerContext,
-  issues: readonly ReviewIssue[],
-): Promise<ReviewIssueSelection> {
-  return await ctx.ui.custom<ReviewIssueSelection>(
-    (tui, theme, _keybindings, done) => new ReviewResultsViewer(issues, "code-review", tui, theme, done),
-    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
-  );
-}

package/.pi/settings.json

@@ -1,3 +0,0 @@
-{
-  "extensions": ["extensions/pi-workflow-engine/index.ts"]
-}