pi-workflow-engine 0.11.0 → 0.13.0

package/.pi/extensions/pi-workflow-engine/src/review/review-fix-workflow.ts

@@ -1,5 +1,8 @@
+import { initialPatchValidation, PatchEvaluationSchema, validateCandidatePatch, type PatchValidation } from "./patch-validation.ts";
+import { isFatalWorkflowError } from "../cancellation.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
 import type { ParallelSettledError } from "../concurrency.ts";
-import type { LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
+import type { IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
 import type { WorktreeBaseline } from "../worktree.ts";
 import { loadWorkflow } from "../workflow-module.ts";
 import { serializeReviewIssue, type ReviewIssue } from "./review-issues.ts";
@@ -14,6 +17,7 @@ export interface ReviewFixPreview {
   readonly result: string;
   readonly patch: string;
   readonly changed: boolean;
+  readonly validation: PatchValidation;
 }
 
 export interface ReviewFixFailure {
@@ -28,7 +32,7 @@ export interface ReviewFixWorkflowResult {
   readonly fixes: readonly ReviewFixOutcome[];
 }
 
-export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase">;
+export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase" | "cwd" | "signal">;
 
 /** Build an ephemeral workflow that generates one isolated patch preview per finding. */
 export function createReviewFixWorkflow(
@@ -40,9 +44,9 @@ export function createReviewFixWorkflow(
     meta: {
       name: "code-review-fix-previews",
       description: "Generate isolated patch previews for selected code-review findings.",
-      phases: [{ title: REVIEW_FIX_PHASE }],
+      phases: [{ title: REVIEW_FIX_PHASE }, { title: "Validate patch previews" }],
     },
-    default: (api) => runReviewFixWorkflow(api, issues, context),
+    default: (api) => runReviewFixWorkflow(api, issues, context, baseline),
   };
   return loadWorkflow(
     module,
@@ -76,6 +80,7 @@ export async function runReviewFixWorkflow(
   api: ReviewFixWorkflowApi,
   issues: readonly ReviewIssue[],
   context: ReviewContext | undefined,
+  baseline: WorktreeBaseline,
 ): Promise<ReviewFixWorkflowResult> {
   api.phase(REVIEW_FIX_PHASE);
   const settled = await api.parallel(
@@ -84,16 +89,18 @@ export async function runReviewFixWorkflow(
         isolation: "worktree",
         label: `fix:${issue.id}`,
         phase: REVIEW_FIX_PHASE,
-        thinkingLevel: "medium",
+        profile: "medium",
         cacheKey: `review-fix:${issue.id}`,
         tools: [...REVIEW_FIX_TOOLS],
         toolHints: ["search"],
       });
+      const validation = await evaluateReviewFix(api, { issue, context, baseline, isolated });
       return {
         findingId: issue.id,
         result: isolated.result,
         patch: isolated.patch,
         changed: isolated.changed,
+        validation,
       };
     }),
     { settled: true },
@@ -103,11 +110,11 @@ export async function runReviewFixWorkflow(
     entry.ok ? entry.value : { findingId: issues[index]!.id, error: entry.error },
   );
   const successful = fixes.filter(isReviewFixPreview);
-  const changed = successful.filter((fix) => fix.changed).length;
+  const count = (status: PatchValidation["status"]) => successful.filter((fix) => fix.validation.status === status).length;
   const failed = fixes.length - successful.length;
 
   return {
-    summary: `Generated ${changed} patch preview(s); ${successful.length - changed} finding(s) needed no changes; ${failed} attempt(s) failed.`,
+    summary: `${count("verified")} verified candidate(s); ${count("rejected")} rejected; ${count("blocked")} blocked; ${count("no-patch")} no-patch; ${failed} attempt(s) failed.`,
     fixes,
   };
 }
@@ -115,3 +122,32 @@ export async function runReviewFixWorkflow(
 function isReviewFixPreview(outcome: ReviewFixOutcome): outcome is ReviewFixPreview {
   return "patch" in outcome;
 }
+
+async function evaluateReviewFix(api: ReviewFixWorkflowApi, input: {
+  issue: ReviewIssue; context: ReviewContext | undefined; baseline: WorktreeBaseline; isolated: IsolatedAgentResult<string>;
+}): Promise<PatchValidation> {
+  const { issue, context, baseline, isolated } = input;
+  const validation = initialPatchValidation(baseline, isolated.baselineOid, isolated.patch);
+  if (!isolated.patch.trim()) return validation;
+  if (!isolated.baselineOid) return { ...validation, reason: "Candidate has no recorded baseline identity." };
+  if (!context?.snapshot) return { ...validation, reason: "Reviewed snapshot identity is unavailable." };
+  if (validation.baselineFingerprint !== context.snapshot.baselineFingerprint) {
+    return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
+  }
+  try {
+    const evaluated = await api.agent(
+      `Independently evaluate a candidate repair. Your fresh worktree contains the exact reviewed baseline plus the captured patch. The implementer's report is not validation evidence. Inspect the finding, callers and tests. Reject incorrect repairs; return blocked if required validation is unavailable. Select at most six focused deterministic checks with executable and argument arrays. Require at least one meaningful behavior check. If a regression test is applicable, supply a test-only baselinePatch and specific expectedFailure so the engine can prove it fails before the repair and passes after. Do not edit, install dependencies, commit or change branches. The engine will execute checks independently.\nFinding: ${JSON.stringify(serializeReviewIssue(issue))}\nBaseline: ${isolated.baselineOid}\nPatch SHA-256: ${validation.patchHash}\nPatch:\n${isolated.patch}`,
+      { isolation: "worktree", candidatePatch: { baselineOid: isolated.baselineOid, patch: isolated.patch },
+        label: `evaluate:${issue.id}`, phase: "Validate patch previews", profile: "medium", resume: "off",
+        tools: ["read", "bash", "grep", "find", "ls"], toolHints: ["search"], schema: PatchEvaluationSchema },
+    );
+    if (evaluated.baselineOid !== isolated.baselineOid || evaluated.patch !== isolated.patch) {
+      return { ...validation, status: "rejected", reason: "Evaluator changed the candidate or used a different baseline.", evaluation: evaluated.result };
+    }
+    return await validateCandidatePatch({ cwd: api.cwd, baseline, expectedFingerprint: context.snapshot.baselineFingerprint,
+        baselineOid: isolated.baselineOid, patch: isolated.patch, evaluation: evaluated.result, signal: api.signal });
+  } catch (error) {
+    if (isFatalWorkflowError(error, api.signal)) throw error;
+    return { ...validation, status: "blocked", reason: unknownErrorMessage(error) };
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/review/review-format.ts

@@ -55,9 +55,10 @@ export function renderIssueDetails(issue: ReviewIssue, theme: Theme): string {
 
 export function renderIssueDetailLines(issue: ReviewIssue, theme: Theme, width: number): string[] {
   const finding = issue.finding;
-  const metadata = `${finding.category} · severity ${finding.severity} · confidence ${finding.confidence}`;
+  const metadata = `${finding.category} · severity ${finding.severity} · confidence ${finding.confidence}${finding.verdict ? ` · ${finding.verdict}` : ""}`;
   const lines = [`${theme.fg("accent", issue.id)} ${theme.fg("text", finding.summary)}`];
   lines.push(...fieldLines("Metadata", metadata, width, theme));
+  if (finding.sourceCandidateIds?.length) lines.push(...fieldLines("Sources", finding.sourceCandidateIds.join(", "), width, theme));
   lines.push(...fieldLines("Location", formatIssueLocation(issue), width, theme, "accent"));
   lines.push(...fieldLines("Impact", finding.impact, width, theme));
   lines.push(...fieldLines("Evidence", finding.evidence.join("; ") || "(none cited)", width, theme));

package/.pi/extensions/pi-workflow-engine/src/review/review-issues.ts

@@ -37,7 +37,7 @@ export interface SerializedReviewIssue {
 
 export function toReviewIssues(name: string, report: Pick<AdvisoryReport, "findings">): ReviewIssue[] {
   return report.findings.map((finding, index) => {
-    const location = finding.locations[0];
+    const location = finding.reviewAnchor ?? finding.locations[0];
     return {
       id: formatIssueId(index),
       index,

package/.pi/extensions/pi-workflow-engine/src/review/review-report.ts

@@ -1,7 +1,7 @@
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import { AdvisoryReportWithStatsSchema } from "../advisory-schema.ts";
-import { formatReviewDiffTarget, isReviewDiffTarget, ReviewDiffTargetSchema } from "../diff-capture.ts";
+import { formatReviewDiffTarget, isReviewDiffTarget, ReviewDiffTargetSchema } from "../review-diff-target.ts";
 
 /** Atomic identity of the exact diff and post-change snapshot that were reviewed. */
 export const ReviewSnapshotIdentitySchema = Type.Object({

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

@@ -3,6 +3,7 @@ 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 =
   | {
@@ -46,6 +47,6 @@ export async function showReviewResultsViewer(
 ): Promise<ReviewIssueSelection> {
   return await ctx.ui.custom<ReviewIssueSelection>(
     (tui, theme, _keybindings, done) => new ReviewResultsViewer(issues, "code-review", tui, theme, done),
-    { overlay: true, overlayOptions: { anchor: "center", width: "80%", minWidth: 40, maxHeight: "80%", margin: 1 } },
+    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
   );
 }

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

@@ -1,11 +1,10 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, visibleWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { matchesKey, type Component, type TUI } from "@earendil-works/pi-tui";
 import { renderIssueDetailLines } from "./review-format.ts";
 import { formatIssueLocation, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
 import { truncateDisplay } from "../ui/workflow-format.ts";
+import { fitWorkflowViewerRow, fitWorkflowViewerRows, workflowViewerHeight } from "../ui/workflow-viewer-layout.ts";
 
-const VIEWPORT_HEIGHT_RATIO = 0.8;
-const VIEWPORT_MARGIN_ROWS = 2;
 const SPLIT_WIDTH = 96;
 const LIST_MIN_WIDTH = 34;
 const LIST_MAX_WIDTH = 48;
@@ -34,8 +33,8 @@ export class ReviewResultsViewer implements Component {
   render(width: number): string[] {
     const outerWidth = Math.max(4, width);
     const contentWidth = Math.max(1, outerWidth - 4);
-    const innerHeight = Math.max(1, this.modalHeight() - 2);
-    const body = fitRows(this.renderBody(contentWidth, innerHeight), innerHeight);
+    const innerHeight = Math.max(1, workflowViewerHeight(this.tui.terminal.rows) - 2);
+    const body = fitWorkflowViewerRows(this.renderBody(contentWidth, innerHeight), innerHeight);
     return [
       this.theme.fg("borderAccent", `╭${"─".repeat(Math.max(0, outerWidth - 2))}╮`),
       ...body.map((line) => this.borderedRow(line, contentWidth)),
@@ -94,20 +93,13 @@ export class ReviewResultsViewer implements Component {
     }
   }
 
-  private modalHeight(): number {
-    const terminalRows = Math.max(1, this.tui.terminal.rows);
-    const availableRows = Math.max(1, terminalRows - VIEWPORT_MARGIN_ROWS);
-    const proportionalRows = Math.floor(terminalRows * VIEWPORT_HEIGHT_RATIO);
-    return Math.min(availableRows, Math.max(3, proportionalRows));
-  }
-
   private renderBody(width: number, height: number): string[] {
     const warning = this.warning ? this.theme.fg("warning", this.warning) : "";
     const chromeRows = 5;
     const contentHeight = Math.max(1, height - chromeRows);
     let content: string[];
     if (this.issues.length === 0) {
-      content = fitRows([this.theme.fg("success", "No findings.")], contentHeight);
+      content = fitWorkflowViewerRows([this.theme.fg("success", "No findings.")], contentHeight);
     } else if (width >= SPLIT_WIDTH) {
       content = this.renderSplit(width, contentHeight);
     } else {
@@ -118,7 +110,7 @@ export class ReviewResultsViewer implements Component {
       this.headerLine(width),
       warning,
       this.theme.fg("borderMuted", "─".repeat(width)),
-      ...fitRows(content, contentHeight),
+      ...fitWorkflowViewerRows(content, contentHeight),
       this.theme.fg("borderMuted", "─".repeat(width)),
       this.helpLine(width),
     ];
@@ -131,7 +123,7 @@ export class ReviewResultsViewer implements Component {
     const details = this.renderDetailPane(detailWidth, height);
     const divider = this.theme.fg("borderMuted", "│");
     return Array.from({ length: height }, (_value, index) =>
-      `${padAnsi(list[index] ?? "", listWidth)} ${divider} ${padAnsi(details[index] ?? "", detailWidth)}`,
+      `${fitWorkflowViewerRow(list[index] ?? "", listWidth)} ${divider} ${fitWorkflowViewerRow(details[index] ?? "", detailWidth)}`,
     );
   }
 
@@ -171,7 +163,7 @@ export class ReviewResultsViewer implements Component {
       width,
     );
     const indicator = truncateDisplay(this.theme.fg("dim", `${range}${arrows ? ` ${arrows}` : ""}`), width);
-    return [heading, ...fitRows(visible, itemRows), indicator].slice(0, height);
+    return [heading, ...fitWorkflowViewerRows(visible, itemRows), indicator].slice(0, height);
   }
 
   private renderIssueRow(issue: ReviewIssue, index: number, width: number): string {
@@ -185,7 +177,7 @@ export class ReviewResultsViewer implements Component {
   private renderDetailPane(width: number, height: number): string[] {
     if (height <= 0) return [];
     const issue = this.issues[this.cursor];
-    if (!issue) return fitRows([this.theme.fg("dim", "No finding selected.")], height);
+    if (!issue) return fitWorkflowViewerRows([this.theme.fg("dim", "No finding selected.")], height);
 
     const bodyHeight = Math.max(0, height - 2);
     const heading = truncateDisplay(
@@ -206,7 +198,7 @@ export class ReviewResultsViewer implements Component {
       this.theme.fg("dim", `${this.detailsExpanded ? "Lines" : "Collapsed"} ${range}${arrows ? ` ${arrows}` : ""}`),
       width,
     );
-    return [heading, ...fitRows(visible, bodyHeight), indicator].slice(0, height);
+    return [heading, ...fitWorkflowViewerRows(visible, bodyHeight), indicator].slice(0, height);
   }
 
   private headerLine(width: number): string {
@@ -229,7 +221,7 @@ export class ReviewResultsViewer implements Component {
   }
 
   private borderedRow(content: string, width: number): string {
-    return `${this.theme.fg("border", "│")} ${padAnsi(content, width)} ${this.theme.fg("border", "│")}`;
+    return `${this.theme.fg("border", "│")} ${fitWorkflowViewerRow(content, width)} ${this.theme.fg("border", "│")}`;
   }
 
   private requestRender(): void {
@@ -300,17 +292,6 @@ export class ReviewResultsViewer implements Component {
   }
 }
 
-function fitRows(lines: readonly string[], height: number): string[] {
-  const visible = lines.slice(0, Math.max(0, height));
-  return [...visible, ...Array.from({ length: Math.max(0, height - visible.length) }, () => "")];
-}
-
-function padAnsi(text: string, width: number): string {
-  const truncated = truncateDisplay(text, width);
-  const padding = Math.max(0, width - visibleWidth(truncated));
-  return `${truncated}${" ".repeat(padding)}`;
-}
-
 function scrollArrows(hasAbove: boolean, hasBelow: boolean): string {
   return `${hasAbove ? "↑" : ""}${hasBelow ? "↓" : ""}`;
 }

package/.pi/extensions/pi-workflow-engine/src/review/review-session-coordinator.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { dynamaxSessionKey } from "../dynamax.ts";
+import { sessionKey } from "../session-identity.ts";
 import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "../options.ts";
 import type { LoadedWorkflow } from "../types.ts";
 import type { WorkflowExecution } from "../workflow-execution.ts";
@@ -42,7 +42,7 @@ export class ReviewSessionCoordinator {
   ): void {
     const name = execution.envelope.name;
     if (name !== "code-review") return;
-    const key = dynamaxSessionKey(ctx);
+    const key = sessionKey(ctx);
     const report = codeReviewReport(name, execution.envelope.result);
     if (!report) {
       this.sessions.delete(key);
@@ -72,7 +72,7 @@ export class ReviewSessionCoordinator {
     });
     if (decision.kind !== "open") return;
 
-    const retained = this.sessions.get(dynamaxSessionKey(ctx));
+    const retained = this.sessions.get(sessionKey(ctx));
     if (!retained) return;
     await this.openAndHandle(ctx, retained, decision.issues);
   }
@@ -82,7 +82,7 @@ export class ReviewSessionCoordinator {
       ctx.ui.notify("Code-review results viewer requires the TUI", "warning");
       return;
     }
-    const retained = this.sessions.get(dynamaxSessionKey(ctx));
+    const retained = this.sessions.get(sessionKey(ctx));
     if (!retained) {
       ctx.ui.notify("No code-review result is available yet. Run /workflow code-review first.", "warning");
       return;
@@ -96,7 +96,7 @@ export class ReviewSessionCoordinator {
   }
 
   dispose(ctx: ExtensionContext): void {
-    this.sessions.delete(dynamaxSessionKey(ctx));
+    this.sessions.delete(sessionKey(ctx));
   }
 
   private async openAndHandle(

package/.pi/extensions/pi-workflow-engine/src/review/review-snapshot.ts

@@ -1,13 +1,12 @@
 import { createHash } from "node:crypto";
 import { throwIfAborted } from "../cancellation.ts";
+import { captureDiffTarget, type DiffCaptureFailure } from "../diff-capture.ts";
 import {
-  captureDiffTarget,
-  type DiffCaptureFailure,
+  reviewGitDiffBaseline,
   type GitReviewDiffTarget,
   type PullRequestReviewDiffTarget,
   type ReviewDiffTarget,
-  reviewGitDiffBaseline,
-} from "../diff-capture.ts";
+} from "../review-diff-target.ts";
 import { runBoundedProcess } from "../process-runner.ts";
 import { unknownErrorMessage } from "../unknown-error.ts";
 import type { WorktreeBaseline } from "../worktree.ts";

package/.pi/extensions/pi-workflow-engine/src/review-diff-target.ts

@@ -0,0 +1,130 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+export type GitDiffBaselineTarget =
+  | { readonly kind: "working-tree" }
+  | { readonly kind: "index" }
+  | { readonly kind: "range"; readonly ref: string };
+
+export const GitReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("git"),
+  args: Type.Array(Type.String()),
+});
+
+export const PullRequestReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("pull-request"),
+  number: Type.Integer({ minimum: 1 }),
+});
+
+export const ReviewDiffTargetSchema = Type.Union([GitReviewDiffTargetSchema, PullRequestReviewDiffTargetSchema]);
+
+export type GitReviewDiffTarget = Static<typeof GitReviewDiffTargetSchema>;
+export type PullRequestReviewDiffTarget = Static<typeof PullRequestReviewDiffTargetSchema>;
+
+/** Serializable semantic identity of the diff being reviewed. */
+export type ReviewDiffTarget = Static<typeof ReviewDiffTargetSchema>;
+
+const SAFE_REF_OR_PATH = /^[A-Za-z0-9_./:@~+=,\-]+$/;
+const SAFE_GH_DIFF_FLAGS = new Set(["--color=never"]);
+const SAFE_GIT_DIFF_FLAGS = new Set(["--binary", "--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
+
+export function parseAllowedDiffCommand(command: string): ReviewDiffTarget | { error: string } {
+  const tokens = command.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length < 2) return { error: "empty or incomplete diff command" };
+  if (tokens[0] === "git" && tokens[1] === "diff") {
+    const parsed = parseGitDiff(tokens);
+    return "error" in parsed ? parsed : parsed.target;
+  }
+  if (tokens[0] === "gh" && tokens[1] === "pr" && tokens[2] === "diff" && /^\d+$/.test(tokens[3] ?? "")) {
+    const number = Number(tokens[3]);
+    if (!Number.isSafeInteger(number) || number <= 0) return { error: "pull-request number must be a positive safe integer" };
+    const flags = tokens.slice(4);
+    if (flags.includes("--patch")) return { error: "gh pr diff --patch is not supported because reviews require the cumulative pull-request diff" };
+    const unsupported = flags.find((token) => !SAFE_GH_DIFF_FLAGS.has(token));
+    if (unsupported) return { error: `unsupported gh pr diff option: ${unsupported}` };
+    return { kind: "pull-request", number };
+  }
+  return { error: "diff command is not in the git/gh allowlist" };
+}
+
+function parseGitDiff(
+  tokens: readonly string[],
+): { readonly target: GitReviewDiffTarget; readonly baseline: GitDiffBaselineTarget } | { readonly error: string } {
+  const args = tokens.slice(2);
+  const safeArgs = ["diff", "--no-ext-diff"];
+  const operands: string[] = [];
+  let staged = false;
+  let pathMode = false;
+
+  for (const token of args) {
+    if (!SAFE_REF_OR_PATH.test(token)) return { error: `unsupported git diff token: ${token}` };
+    if (token === "--") {
+      pathMode = true;
+      safeArgs.push(token);
+      continue;
+    }
+    if (!pathMode && token.startsWith("-")) {
+      if (!isAllowedGitDiffFlag(token)) return { error: `unsupported git diff option: ${token}` };
+      staged ||= token === "--cached" || token === "--staged";
+      if (token !== "--no-ext-diff") safeArgs.push(token);
+      continue;
+    }
+    if (!pathMode) operands.push(token);
+    safeArgs.push(token);
+  }
+
+  const baseline = classifyGitDiffBaseline(staged, operands);
+  return "error" in baseline ? baseline : { target: { kind: "git", args: safeArgs }, baseline };
+}
+
+function classifyGitDiffBaseline(staged: boolean, operands: readonly string[]): GitDiffBaselineTarget | { readonly error: string } {
+  if (operands.length > 1) {
+    return { error: "ambiguous git diff operands; use A..B or A...B for revisions, or -- before multiple paths" };
+  }
+  if (staged) return { kind: "index" };
+
+  const range = operands.find((operand) => operand.includes(".."));
+  if (range) {
+    const separator = range.includes("...") ? "..." : "..";
+    return { kind: "range", ref: range.slice(range.indexOf(separator) + separator.length) || "HEAD" };
+  }
+
+  return { kind: "working-tree" };
+}
+
+function isAllowedGitDiffFlag(token: string): boolean {
+  return SAFE_GIT_DIFF_FLAGS.has(token) || /^-U\d+$/.test(token) || /^--unified=\d+$/.test(token) || /^--inter-hunk-context=\d+$/.test(token);
+}
+
+export function reviewDiffCommand(target: ReviewDiffTarget): { readonly file: "git" | "gh"; readonly args: readonly string[] } {
+  return target.kind === "pull-request"
+    ? { file: "gh", args: ["pr", "diff", String(target.number), "--color=never"] }
+    : { file: "git", args: target.args };
+}
+
+/** Canonical display form. Never execute this string directly; use reviewDiffCommand(). */
+export function formatReviewDiffTarget(target: ReviewDiffTarget): string {
+  const command = reviewDiffCommand(target);
+  return [command.file, ...command.args].join(" ");
+}
+
+/** Derive reconstruction semantics from the canonical git command instead of persisting duplicate state. */
+export function reviewGitDiffBaseline(target: GitReviewDiffTarget): GitDiffBaselineTarget {
+  const parsed = parseGitDiff(["git", ...target.args]);
+  if ("error" in parsed) throw new Error(`Invalid persisted git review target: ${parsed.error}`);
+  return parsed.baseline;
+}
+
+/** Validate persisted targets by round-tripping through the single command allowlist parser. */
+export function isReviewDiffTarget(value: unknown): value is ReviewDiffTarget {
+  if (!Value.Check(ReviewDiffTargetSchema, value)) return false;
+  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(value));
+  return !("error" in parsed) && sameReviewDiffTarget(parsed, value);
+}
+
+function sameReviewDiffTarget(left: ReviewDiffTarget, right: ReviewDiffTarget): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "pull-request") return right.kind === "pull-request" && left.number === right.number;
+  if (right.kind !== "git" || left.args.length !== right.args.length) return false;
+  return left.args.every((arg, index) => arg === right.args[index]);
+}

package/.pi/extensions/pi-workflow-engine/src/session-identity.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** Stable identity for state retained for the lifetime of a pi session. */
+export function sessionKey(ctx: Pick<ExtensionContext, "sessionManager">): string {
+  return ctx.sessionManager.getSessionFile() ?? ctx.sessionManager.getSessionId();
+}

package/.pi/extensions/pi-workflow-engine/src/structured-output.ts

@@ -0,0 +1,32 @@
+export const MAX_SCHEMA_REPAIR_ATTEMPTS = 2;
+export const STRUCTURED_OUTPUT_ERROR_CODE = "WORKFLOW_STRUCTURED_OUTPUT_NONCOMPLIANCE";
+
+export interface StructuredOutputErrorDetails {
+  readonly agentLabel: string;
+  readonly promptAttempts: number;
+  readonly repairAttempts: number;
+}
+
+/** Recoverable failure raised when a schema agent never calls `final_answer`. */
+export class WorkflowStructuredOutputError extends Error {
+  readonly name = "WorkflowStructuredOutputError";
+  readonly code = STRUCTURED_OUTPUT_ERROR_CODE;
+  readonly details: StructuredOutputErrorDetails;
+
+  constructor(agentLabel: string, repairAttempts: number) {
+    const promptAttempts = repairAttempts + 1;
+    super(
+      `Schema agent "${agentLabel}" did not call final_answer after ${promptAttempts} prompt attempts (${repairAttempts} repairs).`,
+    );
+    this.details = { agentLabel, promptAttempts, repairAttempts };
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: StructuredOutputErrorDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/tool-capabilities.ts

@@ -0,0 +1,44 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { AgentToolHint } from "./types.ts";
+
+/** Raised before prompting when required semantic tool capabilities are unavailable. */
+export class WorkflowToolHintUnavailableError extends Error {
+  readonly code = "WORKFLOW_TOOL_HINT_UNAVAILABLE";
+  readonly hints: readonly AgentToolHint[];
+
+  constructor(hints: readonly AgentToolHint[]) {
+    super(`Required workflow tool capability unavailable: ${hints.join(", ")}`);
+    this.name = "WorkflowToolHintUnavailableError";
+    this.hints = [...hints];
+  }
+}
+
+export function matchesAgentToolHint(tool: ToolInfo, hint: AgentToolHint): boolean {
+  return hint === "search" ? isSearchLikeTool(tool) : isExternalSearchLikeTool(tool);
+}
+
+function isExternalSearchLikeTool(tool: ToolInfo): boolean {
+  if (isMutationLikeToolName(tool.name) || tool.sourceInfo.source === "builtin") return false;
+  const name = tool.name.toLowerCase();
+  const description = [tool.description, ...(tool.promptGuidelines ?? [])].join(" ").toLowerCase();
+  const text = `${name} ${description}`;
+  const hasResearchAction = /\b(?:browse|browser|search|fetch|extract|open|read|get)\b/.test(text)
+    || /(?:^|[-_])(?:browse|browser|search|fetch|extract)(?:$|[-_])/.test(name)
+    || /(?:^|[^a-z0-9])web(?:$|[^a-z0-9])/.test(name);
+  const hasExternalMedium = /(?:^|[-_])(?:web|browser|url|http|https|tavily|exa|firecrawl|brave|serper|parallel|perplexity)(?:$|[-_])/.test(name)
+    || /\b(?:search|browse)\s+(?:the\s+)?(?:web|internet)\b/.test(description)
+    || /\b(?:internet|web) search(?: engine)?\b/.test(description)
+    || /\b(?:fetch|extract|open|read|get)\s+(?:(?:the|a|an)\s+)?(?:url|web\s?page|website|https? page)\b/.test(description);
+  return hasResearchAction && hasExternalMedium;
+}
+
+function isSearchLikeTool(tool: ToolInfo): boolean {
+  if (isMutationLikeToolName(tool.name)) return false;
+  const name = tool.name.toLowerCase();
+  if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
+  return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description.toLowerCase());
+}
+
+function isMutationLikeToolName(name: string): boolean {
+  return /(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)/.test(name.toLowerCase());
+}

package/.pi/extensions/pi-workflow-engine/src/tool-source-identity.ts

@@ -1,5 +1,6 @@
 import { lstat } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
+import { isMissingPathError } from "./filesystem-error.ts";
 import { hashIdentity } from "./identity-fingerprint.ts";
 import { logicalWorkspacePath, portableRelativePath } from "./replay-path-identity.ts";
 import { captureTreeFingerprint, isPathWithin, validateTreeFile, type FingerprintCapture } from "./tree-fingerprint.ts";
@@ -147,7 +148,3 @@ function nonEmptyString(value: string, label: string): string {
   if (value.length === 0) throw new Error(`${label} is empty`);
   return value;
 }
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}

package/.pi/extensions/pi-workflow-engine/src/tree-fingerprint.ts

@@ -3,6 +3,7 @@ import { constants, type BigIntStats } from "node:fs";
 import { lstat, open, readdir, type FileHandle } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { throwIfAborted } from "./cancellation.ts";
+import { isMissingPathError } from "./filesystem-error.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
 export type FingerprintCapture =
@@ -398,7 +399,3 @@ function isExcludedAncestor(path: string, excluded: ReadonlySet<string> | undefi
   }
   return false;
 }
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}