@yycholla/pi-dynamic-workflows 3.3.0

package/dist/builtin-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bundled workflow commands: `/deep-research`, `/adversarial-review`,
+ * `/multi-perspective`, `/code-review`, and `/codebase-audit`.
+ *
+ * Each command starts its generated workflow through the WorkflowManager's
+ * background path — the command returns immediately, progress is visible in
+ * the task panel and `/workflows` (pause/stop work like any managed run), and
+ * the report is delivered back into the conversation on completion by
+ * installResultDelivery. Running inline in the handler instead would block the
+ * whole session until the workflow finished (#104).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { WorkflowManager } from "./workflow-manager.js";
+import { type WorkflowStorage } from "./workflow-saved.js";
+export declare function registerBuiltinWorkflows(pi: ExtensionAPI, opts: {
+    cwd: string;
+    manager: WorkflowManager;
+    storage?: WorkflowStorage;
+}): void;

package/dist/builtin-commands.js

@@ -0,0 +1,251 @@
+/**
+ * Bundled workflow commands: `/deep-research`, `/adversarial-review`,
+ * `/multi-perspective`, `/code-review`, and `/codebase-audit`.
+ *
+ * Each command starts its generated workflow through the WorkflowManager's
+ * background path — the command returns immediately, progress is visible in
+ * the task panel and `/workflows` (pause/stop work like any managed run), and
+ * the report is delivered back into the conversation on completion by
+ * installResultDelivery. Running inline in the handler instead would block the
+ * whole session until the workflow finished (#104).
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { findBuiltinWorkflow } from "./builtin-workflows.js";
+import { MAX_DIFF_CHARS } from "./code-review.js";
+import { parseCommandArgs } from "./saved-commands.js";
+import { createWorkflowStorage } from "./workflow-saved.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Cap on the diff-source exec's stdout+stderr buffer. Node's default (1 MB)
+ * throws on anything but a small diff — `gh pr diff` on a sizeable PR routinely
+ * exceeds it. 64 MB comfortably covers any realistic diff while still bounding
+ * worst-case memory; the prompt-side cap (code-review.ts's MAX_DIFF_CHARS) is
+ * what actually protects the review from a huge diff, not this buffer.
+ */
+const DIFF_EXEC_MAX_BUFFER = 64 * 1024 * 1024;
+function alreadyRegistered(pi, name) {
+    try {
+        return (pi.getCommands?.() ?? []).some((c) => c.name === name);
+    }
+    catch {
+        return false;
+    }
+}
+/** Split a command argument string into tokens, respecting single/double quotes. */
+function tokenizeArgs(input) {
+    const tokens = [];
+    for (const m of input.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+        tokens.push(m[1] ?? m[2] ?? m[3] ?? "");
+    }
+    return tokens;
+}
+/**
+ * Start a built-in workflow through the manager's background path and tell the
+ * user where to watch it. startInBackground can throw synchronously (script
+ * parse, run lease) — surface that as a notify instead of an unhandled error.
+ * Async failures are handled by the manager's generic delivery ("✗ Background
+ * workflow … failed"), so no handler-side await is needed — that await is
+ * exactly what used to hang the session (#104).
+ */
+function startBackground(manager, ctx, name, script, args, exec) {
+    try {
+        const { runId } = manager.startInBackground(script, args, exec ?? {});
+        ctx.ui.notify(`/${name} running in the background (${runId}) — watch the task panel or /workflows; the report is posted here when it finishes.`, "info");
+    }
+    catch (error) {
+        ctx.ui.notify(`${name} failed to start: ${error instanceof Error ? error.message : error}`, "error");
+    }
+}
+/**
+ * Look up a built-in descriptor by its fixed, hardcoded name. Every call site
+ * below passes one of the 5 literal names in BUILTIN_WORKFLOWS, so this can
+ * only throw if that registry and this file's command names fall out of sync
+ * — a programming error, not a user-input problem (tests pin the names stay
+ * in sync, see builtin-commands.test.ts).
+ */
+function requireBuiltin(name) {
+    const found = findBuiltinWorkflow(name);
+    if (!found)
+        throw new Error(`internal error: no built-in workflow registered for "${name}"`);
+    return found;
+}
+/**
+ * Resolve a built-in's script/exec context for the given args, surfacing an
+ * invalid-args error (e.g. a whitespace-only string that passes the handler's
+ * cheap `!value` check but fails the registry's real validation) as the same
+ * kind of warning notify the handlers already use for their own validation,
+ * rather than an uncaught rejection.
+ */
+function resolveBuiltinOrNotify(name, cwd, args, ctx) {
+    try {
+        return requireBuiltin(name).resolve(cwd, args);
+    }
+    catch (error) {
+        ctx.ui.notify(`/${name}: ${error instanceof Error ? error.message : String(error)}`, "warning");
+        return undefined;
+    }
+}
+export function registerBuiltinWorkflows(pi, opts) {
+    const { cwd, manager } = opts;
+    const storage = opts.storage ?? createWorkflowStorage(cwd);
+    /**
+     * A project/user saved workflow always takes precedence over a built-in of
+     * the same name — on every path, not just the `workflow` tool's `name`
+     * input. Builtins are registered as commands before saved workflows
+     * (registerAllSavedWorkflows skips a name that's already registered), so
+     * without this dynamic check a same-named saved workflow would silently
+     * never run from its slash command. Checking here, at invocation time
+     * rather than registration time, makes "saved wins" hold regardless of
+     * registration order. Mirrors registerSavedWorkflow's own handler exactly
+     * (same parseCommandArgs call, same startBackground path, no builtin exec
+     * context) so a shadowed command behaves identically to how it would if the
+     * saved workflow itself had been registered under this name.
+     */
+    function runSavedShadowIfPresent(name, rawArgs, ctx) {
+        const saved = storage.load(name);
+        if (!saved)
+            return false;
+        startBackground(manager, ctx, name, saved.script, parseCommandArgs(rawArgs, saved.parameters));
+        return true;
+    }
+    if (!alreadyRegistered(pi, "deep-research")) {
+        pi.registerCommand("deep-research", {
+            description: "Research a question across the web with cross-checked sources",
+            async handler(args, ctx) {
+                if (runSavedShadowIfPresent("deep-research", args, ctx))
+                    return;
+                const question = args.trim();
+                if (!question)
+                    return ctx.ui.notify("Usage: /deep-research <question>", "warning");
+                // Resolve through the shared builtin registry (builtin-workflows.ts) so
+                // this command and the workflow tool's `name` input always run the exact
+                // same generated script and exec context (tools/toolset) for this pattern.
+                const resolved = resolveBuiltinOrNotify("deep-research", cwd, { question }, ctx);
+                if (!resolved)
+                    return;
+                startBackground(manager, ctx, "deep-research", resolved.script, { question }, {
+                    tools: resolved.tools,
+                    toolset: resolved.toolset,
+                });
+            },
+        });
+    }
+    if (!alreadyRegistered(pi, "adversarial-review")) {
+        pi.registerCommand("adversarial-review", {
+            description: "Investigate a task, then cross-check each finding with skeptical reviewers",
+            async handler(args, ctx) {
+                if (runSavedShadowIfPresent("adversarial-review", args, ctx))
+                    return;
+                const task = args.trim();
+                if (!task)
+                    return ctx.ui.notify("Usage: /adversarial-review <task or question>", "warning");
+                const resolved = resolveBuiltinOrNotify("adversarial-review", cwd, { task }, ctx);
+                if (!resolved)
+                    return;
+                startBackground(manager, ctx, "adversarial-review", resolved.script, { task });
+            },
+        });
+    }
+    if (!alreadyRegistered(pi, "code-review")) {
+        pi.registerCommand("code-review", {
+            description: "Multi-angle parallel code review: 7 specialized finders (correctness, reuse, simplification, efficiency, altitude) + verify pass → ranked findings",
+            async handler(args, ctx) {
+                if (runSavedShadowIfPresent("code-review", args, ctx))
+                    return;
+                const input = args.trim();
+                let diffSource = "git diff HEAD";
+                let diff = "";
+                try {
+                    let cmd;
+                    let cmdArgs;
+                    if (!input) {
+                        diffSource = "git diff HEAD";
+                        cmd = "git";
+                        cmdArgs = ["diff", "HEAD"];
+                    }
+                    else if (/^\d+$/.test(input)) {
+                        diffSource = `gh pr diff ${input}`;
+                        cmd = "gh";
+                        cmdArgs = ["pr", "diff", input];
+                    }
+                    else if (input.includes("..")) {
+                        diffSource = `git diff ${input}`;
+                        cmd = "git";
+                        cmdArgs = ["diff", input];
+                    }
+                    else {
+                        diffSource = `git diff HEAD -- ${input}`;
+                        cmd = "git";
+                        cmdArgs = ["diff", "HEAD", "--", input];
+                    }
+                    // execFile (not exec/shell) + array args: input can't break out into a
+                    // shell command. maxBuffer raised well past Node's 1MB default so a
+                    // large `gh pr diff` doesn't throw ERR_CHILD_PROCESS_STDOUT_MAXBUFFER.
+                    const { stdout } = await execFileAsync(cmd, cmdArgs, { cwd, maxBuffer: DIFF_EXEC_MAX_BUFFER });
+                    diff = stdout;
+                    if (!diff.trim()) {
+                        return ctx.ui.notify(`No diff output from: ${diffSource}`, "warning");
+                    }
+                }
+                catch (err) {
+                    const code = err?.code;
+                    if (code === "ERR_CHILD_PROCESS_STDOUT_MAXBUFFER") {
+                        return ctx.ui.notify(`Diff from ${diffSource} exceeds the ${Math.floor(DIFF_EXEC_MAX_BUFFER / (1024 * 1024))}MB capture limit — ` +
+                            `narrow the target (e.g. a specific file or path) and try again.`, "error");
+                    }
+                    return ctx.ui.notify(`Failed to get diff (${diffSource}): ${err instanceof Error ? err.message : err}`, "error");
+                }
+                // The workflow itself also caps prompt size (MAX_DIFF_CHARS), but truncating
+                // here lets us tell the user clearly rather than have it happen silently deep
+                // inside the generated script.
+                const originalLength = diff.length;
+                if (originalLength > MAX_DIFF_CHARS) {
+                    diff = diff.slice(0, MAX_DIFF_CHARS);
+                    ctx.ui.notify(`Diff is ${originalLength.toLocaleString()} characters — truncated to the first ` +
+                        `${MAX_DIFF_CHARS.toLocaleString()} for the review. Findings past the cut are not covered.`, "warning");
+                }
+                const resolved = resolveBuiltinOrNotify("code-review", cwd, { diff, diffSource }, ctx);
+                if (!resolved)
+                    return;
+                startBackground(manager, ctx, "code-review", resolved.script, { diff, diffSource });
+            },
+        });
+    }
+    if (!alreadyRegistered(pi, "multi-perspective")) {
+        pi.registerCommand("multi-perspective", {
+            description: "Analyze a topic from several independent perspectives in parallel, then synthesize",
+            async handler(args, ctx) {
+                if (runSavedShadowIfPresent("multi-perspective", args, ctx))
+                    return;
+                const [topic, ...rest] = tokenizeArgs(args);
+                if (!topic) {
+                    return ctx.ui.notify('Usage: /multi-perspective "<topic>" [perspective1] [perspective2] …', "warning");
+                }
+                // resolve() falls back to a broadly-useful default set when fewer than
+                // two perspectives are given (see builtin-workflows.ts).
+                const resolved = resolveBuiltinOrNotify("multi-perspective", cwd, { topic, perspectives: rest }, ctx);
+                if (!resolved)
+                    return;
+                startBackground(manager, ctx, "multi-perspective", resolved.script);
+            },
+        });
+    }
+    if (!alreadyRegistered(pi, "codebase-audit")) {
+        pi.registerCommand("codebase-audit", {
+            description: "Run parallel checks against a codebase scope, then cross-validate and report",
+            async handler(args, ctx) {
+                if (runSavedShadowIfPresent("codebase-audit", args, ctx))
+                    return;
+                const [scope, ...checks] = tokenizeArgs(args);
+                if (!scope || checks.length === 0) {
+                    return ctx.ui.notify('Usage: /codebase-audit <scope> "<check1>" ["<check2>" …]', "warning");
+                }
+                const resolved = resolveBuiltinOrNotify("codebase-audit", cwd, { scope, checks }, ctx);
+                if (!resolved)
+                    return;
+                startBackground(manager, ctx, "codebase-audit", resolved.script);
+            },
+        });
+    }
+}

package/dist/builtin-workflows.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared registry of the 5 curated built-in workflow patterns
+ * (`deep-research`, `adversarial-review`, `code-review`, `multi-perspective`,
+ * `codebase-audit`).
+ *
+ * This is the single place that turns a pattern's name + caller-supplied args
+ * into a runnable script (and, where a pattern needs it, an exec context such
+ * as web tools). Both entry points a model or user can reach a built-in
+ * through — the `/deep-research`-style slash commands (builtin-commands.ts)
+ * and the `workflow` tool's `name` input (workflow-tool.ts) — resolve through
+ * this one registry, so the two paths can never drift apart and the
+ * per-pattern generator scripts are written exactly once.
+ */
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { WorkflowStorage } from "./workflow-saved.js";
+/** Default perspective set used when a caller gives fewer than two. */
+export declare const DEFAULT_MULTI_PERSPECTIVES: readonly string[];
+/** A resolved, ready-to-run script plus the exec context it needs (if any). */
+export interface BuiltinWorkflowInvocation {
+    script: string;
+    tools?: ToolDefinition[];
+    toolset?: string;
+}
+export interface BuiltinWorkflowDescriptor {
+    /** Also the slash-command name (without the leading `/`). */
+    name: string;
+    description: string;
+    /** Build the script (and exec context) for one invocation; throws on invalid `args`. */
+    resolve(cwd: string, args: unknown): BuiltinWorkflowInvocation;
+}
+/** The 5 curated built-in workflow patterns, keyed by their stable name. */
+export declare const BUILTIN_WORKFLOWS: readonly BuiltinWorkflowDescriptor[];
+/** Stable list of built-in workflow pattern names, in registry order. */
+export declare const BUILTIN_WORKFLOW_NAMES: readonly string[];
+export declare function findBuiltinWorkflow(name: string): BuiltinWorkflowDescriptor | undefined;
+/**
+ * Resolve a name to a runnable invocation, checking project/user saved
+ * workflows first and falling back to the built-in patterns — the same
+ * precedence `workflow-saved.ts` already uses internally (project > user), one
+ * level up: saved workflows (of either scope) beat a built-in of the same name.
+ */
+export declare function resolveWorkflowInvocation(name: string, args: unknown, ctx: {
+    storage: WorkflowStorage;
+    cwd: string;
+}): BuiltinWorkflowInvocation | undefined;

package/dist/builtin-workflows.js

@@ -0,0 +1,121 @@
+/**
+ * Shared registry of the 5 curated built-in workflow patterns
+ * (`deep-research`, `adversarial-review`, `code-review`, `multi-perspective`,
+ * `codebase-audit`).
+ *
+ * This is the single place that turns a pattern's name + caller-supplied args
+ * into a runnable script (and, where a pattern needs it, an exec context such
+ * as web tools). Both entry points a model or user can reach a built-in
+ * through — the `/deep-research`-style slash commands (builtin-commands.ts)
+ * and the `workflow` tool's `name` input (workflow-tool.ts) — resolve through
+ * this one registry, so the two paths can never drift apart and the
+ * per-pattern generator scripts are written exactly once.
+ */
+import { createCodingTools } from "@earendil-works/pi-coding-agent";
+import { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
+import { generateCodeReviewWorkflow } from "./code-review.js";
+import { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
+import { createWebTools } from "./web-tools.js";
+/** Default perspective set used when a caller gives fewer than two. */
+export const DEFAULT_MULTI_PERSPECTIVES = [
+    "technical",
+    "product",
+    "security",
+    "user experience",
+    "maintainability",
+];
+function asRecord(args) {
+    return args && typeof args === "object" ? args : {};
+}
+function requireNonEmptyString(value, argName, patternName) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Built-in workflow "${patternName}" requires args.${argName} to be a non-empty string.`);
+    }
+    return value;
+}
+function requireStringArray(value, argName, patternName) {
+    if (!Array.isArray(value) || value.length === 0 || !value.every((v) => typeof v === "string" && v.trim())) {
+        throw new Error(`Built-in workflow "${patternName}" requires args.${argName} to be a non-empty array of non-empty strings.`);
+    }
+    return value;
+}
+/** The 5 curated built-in workflow patterns, keyed by their stable name. */
+export const BUILTIN_WORKFLOWS = [
+    {
+        name: "deep-research",
+        description: "Research a question across the web with cross-checked sources. args: { question: string }.",
+        resolve(cwd, args) {
+            requireNonEmptyString(asRecord(args).question, "question", "deep-research");
+            return {
+                script: generateDeepResearchWorkflow(),
+                // Research agents need real web access on top of the coding tools; the
+                // "web-research" tag is what a resumed run re-resolves (see
+                // WorkflowManagerOptions.toolsets).
+                tools: [...createCodingTools(cwd), ...createWebTools()],
+                toolset: "web-research",
+            };
+        },
+    },
+    {
+        name: "adversarial-review",
+        description: "Investigate a task, then cross-check each finding with skeptical reviewers. args: { task: string, reviewers?: number, threshold?: number }.",
+        resolve(_cwd, args) {
+            requireNonEmptyString(asRecord(args).task, "task", "adversarial-review");
+            return { script: generateAdversarialReviewWorkflow() };
+        },
+    },
+    {
+        name: "code-review",
+        description: "Multi-angle parallel code review: 7 specialized finders (correctness, reuse, simplification, efficiency, altitude) + verify pass → ranked findings. args: { diff: string, diffSource?: string }.",
+        resolve(_cwd, args) {
+            // Truncation past MAX_DIFF_CHARS already happens inside the generated
+            // script at runtime (see code-review.ts); a caller invoking by name is
+            // responsible for supplying `diff` (e.g. by running `git diff` itself),
+            // unlike the /code-review slash command, which fetches it automatically.
+            requireNonEmptyString(asRecord(args).diff, "diff", "code-review");
+            return { script: generateCodeReviewWorkflow() };
+        },
+    },
+    {
+        name: "multi-perspective",
+        description: "Analyze a topic from several independent perspectives in parallel, then synthesize. args: { topic: string, perspectives?: string[] }.",
+        resolve(_cwd, args) {
+            const record = asRecord(args);
+            const topic = requireNonEmptyString(record.topic, "topic", "multi-perspective");
+            const perspectives = Array.isArray(record.perspectives) && record.perspectives.length >= 2
+                ? requireStringArray(record.perspectives, "perspectives", "multi-perspective")
+                : [...DEFAULT_MULTI_PERSPECTIVES];
+            return { script: generateMultiPerspectiveWorkflow(topic, perspectives) };
+        },
+    },
+    {
+        name: "codebase-audit",
+        description: "Run parallel checks against a codebase scope, then cross-validate and report. args: { scope: string, checks: string[] }.",
+        resolve(_cwd, args) {
+            const record = asRecord(args);
+            const scope = requireNonEmptyString(record.scope, "scope", "codebase-audit");
+            const checks = requireStringArray(record.checks, "checks", "codebase-audit");
+            return { script: generateCodebaseAuditWorkflow(scope, checks) };
+        },
+    },
+];
+/** Stable list of built-in workflow pattern names, in registry order. */
+export const BUILTIN_WORKFLOW_NAMES = BUILTIN_WORKFLOWS.map((w) => w.name);
+export function findBuiltinWorkflow(name) {
+    return BUILTIN_WORKFLOWS.find((w) => w.name === name);
+}
+/**
+ * Resolve a name to a runnable invocation, checking project/user saved
+ * workflows first and falling back to the built-in patterns — the same
+ * precedence `workflow-saved.ts` already uses internally (project > user), one
+ * level up: saved workflows (of either scope) beat a built-in of the same name.
+ */
+export function resolveWorkflowInvocation(name, args, ctx) {
+    const saved = ctx.storage.load(name);
+    if (saved)
+        return { script: saved.script };
+    const builtin = findBuiltinWorkflow(name);
+    if (builtin)
+        return builtin.resolve(ctx.cwd, args);
+    return undefined;
+}

package/dist/code-review.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Multi-angle parallel code review workflow.
+ * 7 specialized finder agents → verify pass → ranked report.
+ */
+/**
+ * Hard cap on diff characters fed into the review. This bounds worst-case
+ * prompt size across 7 parallel finders + a per-candidate verify pass, even
+ * when the diff-source exec step (see builtin-commands.ts) already raised its
+ * own maxBuffer and successfully read a very large diff. Oversized diffs are
+ * truncated rather than rejected — findings in the untruncated prefix still
+ * have value — and the truncation is surfaced to the user, not silent.
+ */
+export declare const MAX_DIFF_CHARS = 200000;
+/**
+ * Generate a code-review workflow script.
+ *
+ * The workflow expects `args` to be passed with shape:
+ *   { diff: string, diffSource: string }
+ *
+ * Model tier routing follows the spec:
+ *   Finders A/B/C → medium (correctness)
+ *   Finders D/E/F → small  (cleanup)
+ *   Finder  G     → big    (altitude / abstraction)
+ *   Synthesis     → big
+ */
+export declare function generateCodeReviewWorkflow(): string;

package/dist/code-review.js

@@ -0,0 +1,181 @@
+/**
+ * Multi-angle parallel code review workflow.
+ * 7 specialized finder agents → verify pass → ranked report.
+ */
+/**
+ * Hard cap on diff characters fed into the review. This bounds worst-case
+ * prompt size across 7 parallel finders + a per-candidate verify pass, even
+ * when the diff-source exec step (see builtin-commands.ts) already raised its
+ * own maxBuffer and successfully read a very large diff. Oversized diffs are
+ * truncated rather than rejected — findings in the untruncated prefix still
+ * have value — and the truncation is surfaced to the user, not silent.
+ */
+export const MAX_DIFF_CHARS = 200_000;
+/**
+ * Generate a code-review workflow script.
+ *
+ * The workflow expects `args` to be passed with shape:
+ *   { diff: string, diffSource: string }
+ *
+ * Model tier routing follows the spec:
+ *   Finders A/B/C → medium (correctness)
+ *   Finders D/E/F → small  (cleanup)
+ *   Finder  G     → big    (altitude / abstraction)
+ *   Synthesis     → big
+ */
+export function generateCodeReviewWorkflow() {
+    return `export const meta = {
+  name: 'code_review',
+  description: 'Multi-angle parallel code review: 7 finder angles + verify pass → ranked findings',
+  phases: [
+    { title: 'Find' },
+    { title: 'Verify' },
+    { title: 'Report' },
+  ],
+}
+
+const MAX_DIFF_CHARS = ${MAX_DIFF_CHARS}
+const rawDiff = (args && args.diff) || ''
+const diffSource = (args && args.diffSource) || 'git diff HEAD'
+const diffTruncated = rawDiff.length > MAX_DIFF_CHARS
+const diff = diffTruncated ? rawDiff.slice(0, MAX_DIFF_CHARS) : rawDiff
+if (diffTruncated) {
+  log(
+    'Diff truncated for review: showing the first ' + MAX_DIFF_CHARS + ' of ' + rawDiff.length +
+    ' characters (' + (rawDiff.length - MAX_DIFF_CHARS) + ' omitted). Findings past the cut are not covered.'
+  )
+}
+const candidateSchema = {
+  type: 'object',
+  properties: {
+    candidates: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          file: { type: 'string' },
+          line: { type: 'number' },
+          summary: { type: 'string' },
+          failure_scenario: { type: 'string' },
+        },
+        required: ['file', 'line', 'summary', 'failure_scenario'],
+      },
+    },
+  },
+  required: ['candidates'],
+}
+
+const diffBlock = '\\n\\n<diff source=\\"' + diffSource + '\\"' + (diffTruncated ? ' truncated=\\"true\\"' : '') + '>\\n' +
+  diff + (diffTruncated ? '\\n\\n[... diff truncated: ' + (rawDiff.length - MAX_DIFF_CHARS) + ' more characters omitted ...]' : '') +
+  '\\n</diff>\\n'
+const base = 'Use the read/grep tools to pull in any additional file context you need.' + diffBlock
+
+phase('Find')
+const finders = await parallel([
+  () => agent(
+    'You are a line-by-line correctness scanner. Hunt ONLY for: inverted conditions, off-by-one errors, ' +
+    'null/nil dereferences, wrong variable used, swallowed errors. For each candidate name the exact file, ' +
+    'line number, a one-line summary, and the concrete failure scenario. Return ONLY issues you can justify ' +
+    'with a line in the diff.' + base,
+    { label: 'A-line-scan', tier: 'medium', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a removed-behavior auditor. For every deleted line or block in the diff: name the invariant ' +
+    'or contract it enforced, then find where (or prove) that contract is re-established elsewhere. ' +
+    'Report only gaps where the invariant is NOT re-established.' + base,
+    { label: 'B-removed-behavior', tier: 'medium', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a cross-file call-site tracer. For each function/method whose signature or behavior changed ' +
+    'in the diff: grep the codebase for callers, then check whether each call site is still correct after ' +
+    'the change. Report only call sites that are now broken or need updating.' + base,
+    { label: 'C-cross-file-tracer', tier: 'medium', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a reuse finder. Identify new code in the diff that duplicates existing helpers, utilities, ' +
+    'or patterns already present in the codebase. Propose the existing symbol that should be used instead.' + base,
+    { label: 'D-reuse', tier: 'small', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a simplification finder. Look for: redundant state that could be derived, copy-paste ' +
+    'variation that could be a shared function, and dead code introduced by the diff.' + base,
+    { label: 'E-simplification', tier: 'small', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are an efficiency finder. Identify: redundant I/O or network calls, sequential work that could ' +
+    'be parallel, and blocking operations on the startup or hot path introduced by the diff.' + base,
+    { label: 'F-efficiency', tier: 'small', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are an altitude reviewer. Assess whether the change is made at the RIGHT abstraction level. ' +
+    'Look for: bandaids on shared infrastructure that should be fixed at the root, fixes in the wrong ' +
+    'layer (e.g. compensating in the UI for a data model problem), or the change solving a symptom ' +
+    'rather than the cause.' + base,
+    { label: 'G-altitude', tier: 'big', schema: candidateSchema }
+  ),
+])
+
+// Collect and deduplicate candidates across all finders
+const allRaw = finders.flatMap((r, fi) => {
+  const label = ['A','B','C','D','E','F','G'][fi]
+  return ((r && r.candidates) || []).map((c) => ({ ...c, angle: label }))
+})
+
+// Deduplicate: same file + line + first 40 chars of summary → keep first
+const seen = new Set()
+const allCandidates = allRaw.filter((c) => {
+  const key = (c.file || '') + ':' + (c.line || 0) + ':' + (c.summary || '').slice(0, 40)
+  if (seen.has(key)) return false
+  seen.add(key)
+  return true
+})
+
+phase('Verify')
+// NOTE: deliberately NOT using the verify() stdlib helper here. verify() only
+// returns a boolean real/not-real vote; this phase needs the 3-way
+// CONFIRMED/PLAUSIBLE/REFUTED verdict so the synthesis report can hedge
+// ("worth a second look" vs "will break"). Since only REFUTED is filtered out
+// below, verify()'s boolean would collapse CONFIRMED and PLAUSIBLE into one
+// bucket and lose that signal for no behavioral gain — verify({reviewers: 1})
+// is already a single agent() call under the hood, same as this.
+const verdicts = allCandidates.length > 0
+  ? await parallel(allCandidates.map((c, i) => () =>
+      agent(
+        'You are a verifier. Determine whether this code review finding is CONFIRMED, PLAUSIBLE, or REFUTED. ' +
+        'CONFIRMED = you can trace the exact failure in the diff. PLAUSIBLE = concern is valid but not certain. ' +
+        'REFUTED = finding is wrong or already handled.\\n\\n' +
+        'FINDING:\\nFile: ' + c.file + '\\nLine: ' + c.line + '\\nSummary: ' + c.summary + '\\n' +
+        'Failure scenario: ' + c.failure_scenario + diffBlock,
+        {
+          label: 'verify-' + (i + 1),
+          schema: {
+            type: 'object',
+            properties: { verdict: { type: 'string', enum: ['CONFIRMED', 'PLAUSIBLE', 'REFUTED'] }, reason: { type: 'string' } },
+            required: ['verdict'],
+          },
+        }
+      )
+    ))
+  : []
+
+const surviving = allCandidates
+  .map((c, i) => ({ ...c, verdict: (verdicts[i] && verdicts[i].verdict) || 'PLAUSIBLE', verifyReason: (verdicts[i] && verdicts[i].reason) || '' }))
+  .filter((c) => c.verdict !== 'REFUTED')
+
+// Rank: correctness (A/B/C) before cleanup (D/E/F) before altitude (G), cap at 10
+const rankAngle = (a) => ['A','B','C'].includes(a) ? 0 : ['D','E','F'].includes(a) ? 1 : 2
+surviving.sort((a, b) => rankAngle(a.angle) - rankAngle(b.angle))
+const top = surviving.slice(0, 10)
+
+phase('Report')
+const synthesis = await agent(
+  'You are a senior code reviewer writing the final report. Below are the verified findings from a ' +
+  'multi-angle code review (already ranked by severity). Write a concise markdown report: ' +
+  '1 sentence per finding with file, line, and the failure scenario. Note the total found vs shown. ' +
+  'Correctness issues (A/B/C) come first, then cleanup (D/E/F), then altitude (G).\\n\\n' +
+  'FINDINGS JSON:\\n' + JSON.stringify(top, null, 2),
+  { label: 'synthesis', tier: 'big' }
+)
+
+return { total: allCandidates.length, surviving: surviving.length, findings: top, report: synthesis, diffTruncated }`;
+}