pi-workflow-engine 0.9.0 → 0.10.1

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-result-renderer.ts

@@ -19,6 +19,8 @@ export interface WorkflowResultEnvelope {
   completedAt: number;
   usage?: WorkflowUsageSnapshot;
   perf?: WorkflowPerfDetails;
+  runId?: string;
+  resumedFromRunId?: string;
 }
 
 export interface AdvisoryWorkflowResult extends AdvisoryReport {
@@ -61,27 +63,61 @@ export function isAdvisoryReport(value: unknown): value is AdvisoryWorkflowResul
   return true;
 }
 
-export function renderWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme, usage?: unknown): Component {
+export interface WorkflowRunDisplayMetadata {
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+}
+
+export interface WorkflowDetailLineInput {
+  readonly usage?: unknown;
+  readonly perf?: WorkflowPerfDetails;
+  readonly metadata?: WorkflowRunDisplayMetadata;
+}
+
+export function renderWorkflowResult(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): Component {
   const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme, usage), 0, 0));
+  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme, usage, metadata, perf), 0, 0));
   return box;
 }
 
-export function renderWorkflowResultText(name: string, result: unknown, expanded: boolean, theme: Theme, usage?: unknown): string {
+export function renderWorkflowResultText(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
   if (isAdvisoryReport(result)) {
-    return renderAdvisoryResult(name, result, expanded, theme, usage);
+    return renderAdvisoryResult(name, result, expanded, theme, usage, metadata, perf);
   }
-  return renderGenericWorkflowResult(name, result, expanded, theme, usage);
-}
-
-function renderAdvisoryResult(name: string, result: AdvisoryWorkflowResult, expanded: boolean, theme: Theme, usage?: unknown): string {
+  return renderGenericWorkflowResult(name, result, expanded, theme, usage, metadata, perf);
+}
+
+function renderAdvisoryResult(
+  name: string,
+  result: AdvisoryWorkflowResult,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
   const icon = theme.fg("success", "✓");
   const title = theme.fg("accent", theme.bold(`Workflow: ${name}`));
   const lines = [`${icon} ${title}`, theme.fg("muted", result.summary)];
   const stats = statsLine(result.stats, theme);
   if (stats) lines.push(stats);
-  const usageLine = formatWorkflowUsageLine(usage);
-  if (usageLine) lines.push(theme.fg("dim", usageLine));
+  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
 
   if (result.findings.length === 0) {
     lines.push(theme.fg("success", "No findings."));
@@ -108,17 +144,49 @@ function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): vo
   }
 }
 
-function renderGenericWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme, usage?: unknown): string {
+function renderGenericWorkflowResult(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
   const lines = [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(`Workflow: ${name}`))}`];
   const summary = extractSummary(result);
   if (summary) lines.push(theme.fg("muted", summary));
-  const usageLine = formatWorkflowUsageLine(usage);
-  if (usageLine) lines.push(theme.fg("dim", usageLine));
+  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
   if (expanded) lines.push(theme.fg("dim", safeJson(result)));
   else if (!summary) lines.push(theme.fg("dim", "Result available in expanded view."));
   return lines.join("\n");
 }
 
+function pushWorkflowDetailLines(lines: string[], theme: Theme, input: WorkflowDetailLineInput): void {
+  for (const line of formatWorkflowDetailLines(input)) {
+    lines.push(theme.fg("dim", line));
+  }
+}
+
+export function formatWorkflowDetailLines(input: WorkflowDetailLineInput): string[] {
+  return [
+    formatWorkflowRunLine(input.metadata),
+    formatWorkflowUsageLine(input.usage),
+    formatWorkflowPerfLine(input.perf),
+  ].filter((line): line is string => line !== undefined);
+}
+
+export function formatWorkflowRunLine(metadata: WorkflowRunDisplayMetadata | undefined): string | undefined {
+  if (!metadata?.runId) return undefined;
+  return metadata.resumedFromRunId ? `Run: ${metadata.runId} (resumed from ${metadata.resumedFromRunId})` : `Run: ${metadata.runId}`;
+}
+
+export function formatWorkflowPerfLine(perf: WorkflowPerfDetails | undefined): string | undefined {
+  if (!perf) return undefined;
+  const parts = perf.aggregates.slice(0, 4).map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
+  return parts.length > 0 ? `Perf: ${parts.join(" · ")}` : "Perf: no samples";
+}
+
 function statsLine(stats: Record<string, string | number> | undefined, theme: Theme): string | undefined {
   if (!stats) return undefined;
   const ordered = ["files", "candidates", "dropped", "verified", "kept"];

package/.pi/extensions/pi-workflow-engine/src/workflow-advisory-utils.ts

@@ -1,4 +1,5 @@
 import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type AdvisoryFinding, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import { compactResults } from "./concurrency.ts";
 import type { AgentOptions, WorkflowApi, WorkflowProgressEvent } from "./types.ts";
 
 export interface AdvisoryLens {
@@ -20,7 +21,11 @@ export interface LensVerificationPipelineResult<Verified> {
   refuted: number;
 }
 
-const DEFAULT_ADVISORY_TOOLS = ["read", "bash"];
+/** Default concrete read/inspect tools for advisory workflows. */
+export const DEFAULT_ADVISORY_TOOLS: NonNullable<AgentOptions["tools"]> = ["read", "bash", "grep", "find", "ls"];
+
+/** Dynamically include installed grep/find/search-like extension tools. */
+export const DEFAULT_ADVISORY_TOOL_HINTS: NonNullable<AgentOptions["toolHints"]> = ["search"];
 
 export type AdvisorySchedulingMode = "pipeline" | "finder-barrier";
 
@@ -29,6 +34,7 @@ export interface LensVerificationPipelineOptions<Lens extends AdvisoryLens, Veri
   lenses: readonly Lens[];
   perLens: number;
   tools?: AgentOptions["tools"];
+  toolHints?: AgentOptions["toolHints"];
   finderPhase?: string;
   verifierPhase?: string;
   schedulingMode?: AdvisorySchedulingMode;
@@ -60,6 +66,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
     lenses,
     perLens,
     tools = DEFAULT_ADVISORY_TOOLS,
+    toolHints = DEFAULT_ADVISORY_TOOL_HINTS,
     finderPhase = "Find",
     verifierPhase = "Verify",
     schedulingMode = "pipeline",
@@ -77,6 +84,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
       phase: finderPhase,
       label: `find:${lens.label}`,
       tools,
+      toolHints,
       thinkingLevel: "low",
       schema: AdvisoryCandidatesSchema,
     });
@@ -113,6 +121,7 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
       phase: verifierPhase,
       label: `verify:${location.file.split("/").pop() ?? location.file}`,
       tools,
+      toolHints,
       thinkingLevel: "low",
       schema: AdvisoryVerdictSchema,
     });
@@ -125,9 +134,9 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
 
   if (schedulingMode === "finder-barrier") {
     const found = await api.parallel(lenses.map((lens) => async () => findForLens(lens)));
-    const novel = found.flatMap(dedupeFound);
+    const novel = compactResults(found).flatMap(dedupeFound);
     const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
-    return { verified: verdicts.filter((value): value is Verified => value !== null), rawCandidates, dropped, refuted };
+    return { verified: compactResults(verdicts), rawCandidates, dropped, refuted };
   }
 
   const perLensVerified = await api.pipeline(
@@ -136,11 +145,11 @@ export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Ver
     async (found) => {
       const novel = dedupeFound(found);
       const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
-      return verdicts.filter((value): value is Verified => value !== null);
+      return compactResults(verdicts);
     },
   );
 
-  return { verified: perLensVerified.flat(), rawCandidates, dropped, refuted };
+  return { verified: compactResults(perLensVerified).flat(), rawCandidates, dropped, refuted };
 }
 
 function candidatesNovelToRun(candidates: readonly AdvisoryCandidate[], seen: Set<string>): AdvisoryCandidate[] {

package/.pi/extensions/pi-workflow-engine/src/worktree.ts

@@ -0,0 +1,238 @@
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runBoundedProcess } from "./process-runner.ts";
+
+export interface WorktreeGitCommandOptions {
+  readonly cwd: string;
+  readonly args: readonly string[];
+  readonly signal?: AbortSignal;
+  readonly timeoutMs: number;
+  readonly maxBufferBytes?: number;
+}
+
+export interface WorktreeGitCommandResult {
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly error?: string;
+}
+
+export interface WorktreeGitRunner {
+  runGit(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult>;
+}
+
+export interface WorktreeRef {
+  readonly path: string;
+}
+
+export interface WorktreeAddFailure {
+  readonly path: string;
+  readonly error: string;
+  readonly cleanup?: WorktreeGitCommandResult;
+}
+
+export interface GitWorktreeProbe {
+  readonly ok: boolean;
+  readonly inside: boolean;
+  readonly error?: string;
+}
+
+export interface WorktreeRemovalOutcome extends WorktreeGitCommandResult {
+  readonly path: string;
+}
+
+export interface WorktreePatch {
+  readonly patch: string;
+  readonly changed: boolean;
+}
+
+export interface WorktreeRegistryOptions {
+  readonly repoCwd: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly patchCapture?: WorktreePatchCapture;
+  readonly timeoutMs?: number;
+}
+
+export type WorktreePatchCapture = (options: {
+  readonly worktreePath: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}) => Promise<WorktreePatch | { readonly error: string }>;
+
+const DEFAULT_WORKTREE_TIMEOUT_MS = 30_000;
+const WORKTREE_DIFF_MAX_BYTES = 16 << 20;
+let pathCounter = 0;
+
+export class WorktreeRegistry {
+  private readonly paths = new Set<string>();
+  private readonly runner: WorktreeGitRunner;
+  private readonly patchCapture: WorktreePatchCapture;
+  private readonly timeoutMs: number;
+
+  constructor(private readonly repoCwd: string, options: Omit<WorktreeRegistryOptions, "repoCwd"> = {}) {
+    this.runner = options.runner ?? spawnGitRunner;
+    this.patchCapture = options.patchCapture ?? captureWorktreePatch;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  }
+
+  get size(): number {
+    return this.paths.size;
+  }
+
+  register(path: string): void {
+    this.paths.add(path);
+  }
+
+  async probe(signal?: AbortSignal): Promise<GitWorktreeProbe> {
+    return await isGitWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs });
+  }
+
+  async add(signal?: AbortSignal): Promise<WorktreeRef | WorktreeAddFailure> {
+    const added = await addWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs });
+    this.register(added.path);
+    if ("error" in added) {
+      const cleanup = await this.remove(added.path);
+      return { ...added, cleanup };
+    }
+    return added;
+  }
+
+  async capturePatch(path: string, signal?: AbortSignal): Promise<WorktreePatch | { readonly error: string }> {
+    return await this.patchCapture({ worktreePath: path, runner: this.runner, signal, timeoutMs: this.timeoutMs });
+  }
+
+  async remove(path: string): Promise<WorktreeGitCommandResult> {
+    const result = await removeWorktree({ repoCwd: this.repoCwd, path, runner: this.runner, timeoutMs: this.timeoutMs }).catch((error: unknown) => ({
+      ok: false,
+      stdout: "",
+      stderr: "",
+      error: formatError(error),
+    }));
+    if (result.ok) this.paths.delete(path);
+    return result;
+  }
+
+  async removeAll(): Promise<readonly WorktreeRemovalOutcome[]> {
+    return await Promise.all(
+      [...this.paths].map(async (path) => ({
+        path,
+        ...(await this.remove(path)),
+      })),
+    );
+  }
+}
+
+export function createWorktreePath(baseDir = tmpdir()): string {
+  pathCounter += 1;
+  return join(baseDir, `pi-workflow-${process.pid}-${pathCounter}-${randomUUID()}`);
+}
+
+export async function isGitWorktree(options: {
+  readonly repoCwd: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<GitWorktreeProbe> {
+  const result = await (options.runner ?? spawnGitRunner)
+    .runGit({
+      cwd: options.repoCwd,
+      args: ["rev-parse", "--is-inside-work-tree"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!result.ok) return { ok: false, inside: false, error: result.error ?? (result.stderr.trim() || "git worktree probe failed") };
+  return { ok: true, inside: result.stdout.trim() === "true" };
+}
+
+export async function addWorktree(options: {
+  readonly repoCwd: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+  readonly baseDir?: string;
+}): Promise<WorktreeRef | WorktreeAddFailure> {
+  const path = createWorktreePath(options.baseDir);
+  const result = await (options.runner ?? spawnGitRunner)
+    .runGit({
+      cwd: options.repoCwd,
+      args: ["worktree", "add", "--detach", path, "HEAD"],
+      signal: options.signal,
+      timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!result.ok) return { path, error: result.error ?? (result.stderr.trim() || "git worktree add failed") };
+  return { path };
+}
+
+export async function removeWorktree(options: {
+  readonly repoCwd: string;
+  readonly path: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly timeoutMs?: number;
+}): Promise<WorktreeGitCommandResult> {
+  return await (options.runner ?? spawnGitRunner).runGit({
+    cwd: options.repoCwd,
+    args: ["worktree", "remove", "--force", options.path],
+    timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
+  });
+}
+
+export async function captureWorktreePatch(options: {
+  readonly worktreePath: string;
+  readonly runner?: WorktreeGitRunner;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<WorktreePatch | { readonly error: string }> {
+  const runner = options.runner ?? spawnGitRunner;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  const intentToAdd = await runner
+    .runGit({
+      cwd: options.worktreePath,
+      args: ["add", "-N", "."],
+      signal: options.signal,
+      timeoutMs,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!intentToAdd.ok) return { error: intentToAdd.error ?? (intentToAdd.stderr.trim() || "git add -N failed before patch capture") };
+
+  const diff = await runner
+    .runGit({
+      cwd: options.worktreePath,
+      args: ["diff", "--no-color", "HEAD"],
+      signal: options.signal,
+      timeoutMs,
+      maxBufferBytes: WORKTREE_DIFF_MAX_BYTES,
+    })
+    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: formatError(error) }));
+  if (!diff.ok) return { error: diff.error ?? (diff.stderr.trim() || "worktree diff capture failed") };
+  return { patch: diff.stdout, changed: diff.stdout.trim().length > 0 };
+}
+
+export const spawnGitRunner: WorktreeGitRunner = {
+  async runGit(options) {
+    return await runGitCommand(options);
+  },
+};
+
+async function runGitCommand(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult> {
+  return await runBoundedProcess({
+    file: "git",
+    args: options.args,
+    cwd: options.cwd,
+    env: { ...process.env, GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" },
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+    maxBufferBytes: options.maxBufferBytes,
+    abortError: "git worktree command aborted",
+    timeoutError: `git worktree command timed out after ${options.timeoutMs}ms`,
+    maxBufferError: options.maxBufferBytes === undefined ? undefined : `git worktree command exceeded ${options.maxBufferBytes} bytes`,
+    exitError: (stderr, code, signal) => stderr.trim() || `git exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
+  });
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -14,7 +14,10 @@ import {
   primaryLocation,
   recordVerdictProgress,
   verdictConfidence,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
+import { compactResults } from "../src/concurrency.ts";
 import { captureDiff } from "../src/diff-capture.ts";
 import type { ReviewContext } from "../src/review/review-issues.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
@@ -55,7 +58,8 @@ const ANGLES: Angle[] = [
   { label: "conventions", kind: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
 ];
 
-const TOOLS = ["read", "bash"];
+const TOOLS = DEFAULT_ADVISORY_TOOLS;
+const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_ANGLE = 6;
 const DIFF_EMBED_CAP = 60_000;
 
@@ -123,7 +127,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
       "and read any relevant AGENTS.md or project docs noting conventions a reviewer should know.\n" +
       "Return diffCommand exactly as a reviewer should run it. Structured output only.",
-    { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
@@ -195,7 +199,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           `Surface up to ${PER_ANGLE} candidates. Use category exactly "${angle.kind}". Each candidate must include a one-line summary, ` +
           "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
           "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
-        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
+        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
       );
       const raw = (found?.candidates ?? []).slice(0, PER_ANGLE);
       rawCandidateCount += raw.length;
@@ -224,7 +228,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     }),
   );
 
-  const novel = perAngle.flatMap(({ angle, candidates }) =>
+  const novel = compactResults(perAngle).flatMap(({ angle, candidates }) =>
     candidates
       .filter((candidate) => {
         const key = dedupKey(candidate);
@@ -249,6 +253,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           phase: "Verify",
           label: `verify:${location.file.split("/").pop() ?? location.file}`,
           tools: TOOLS,
+          toolHints: TOOL_HINTS,
           thinkingLevel: "low",
           schema: AdvisoryVerdictSchema,
         },
@@ -259,7 +264,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     }),
   );
 
-  const verified = verdicts.filter((value): value is Verified => value !== null);
+  const verified = compactResults(verdicts);
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
   progress({ type: "counter", key: "verified", label: "verified", value: verified.length });

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -14,7 +14,10 @@ import {
   formatLocation,
   primaryLocation,
   recordVerdictProgress,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
+import { compactResults } from "../src/concurrency.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -57,7 +60,8 @@ const HYPOTHESIS_LENSES: HypothesisLens[] = [
   { label: "test-fixture", category: "test-fixture", text: "The failure is caused by test setup, fixtures, mocks, generated files, or stale local state rather than product code." },
 ];
 
-const TOOLS = ["read", "bash"];
+const TOOLS = DEFAULT_ADVISORY_TOOLS;
+const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_LENS = 4;
 
 export default async function run(api: WorkflowApi): Promise<unknown> {
@@ -85,7 +89,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect relevant files, package/test configuration, and safe diagnostic commands. " +
       "Safe commands are read-only commands such as status, grep, listing files, typecheck/test commands, or commands explicitly requested by the user. " +
       "Do not run mutation, install, commit, network, or destructive commands. Return scoped files, observations, and constraints. Structured output only.",
-    { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
@@ -117,7 +121,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           `Consider ONLY this hypothesis lens:\n${lens.text}\n\n` +
           `Surface up to ${PER_LENS} root-cause hypotheses. Use category exactly "${lens.category}". ` +
           "Each hypothesis must include a one-line summary, locations, impact explaining how it produces the symptom, and an optional recommendation for the next validation step. Structured output only.",
-        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
+        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
       );
       const candidates = (found?.candidates ?? []).slice(0, PER_LENS).map((candidate) => ({ ...candidate, lens }));
       rawCandidateCount += candidates.length;
@@ -136,13 +140,13 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     }),
   );
 
-  const hypotheses = dedupe(perLens.flat(), (dropped) => {
+  const hypotheses = dedupe(compactResults(perLens).flat(), (dropped) => {
     droppedCandidateCount += dropped;
     progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
   });
 
   phase("Verify");
-  const verified = (
+  const verified = compactResults(
     await parallel(
       hypotheses.map((hypothesis) => async (): Promise<Verified | null> => {
         const location = primaryLocation(hypothesis);
@@ -157,6 +161,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
             phase: "Verify",
             label: `verify:${location.file.split("/").pop() ?? location.file}`,
             tools: TOOLS,
+            toolHints: TOOL_HINTS,
             thinkingLevel: "low",
             schema: AdvisoryVerdictSchema,
           },
@@ -167,8 +172,8 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
         });
         return { ...hypothesis, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence };
       }),
-    )
-  ).filter((value): value is Verified => value !== null);
+    ),
+  );
 
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
@@ -241,4 +246,3 @@ function rank(finding: Verified): number {
   if (finding.verdict === "CONFIRMED") return 0;
   return 1;
 }
-

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -10,6 +10,8 @@ import {
   formatEvidence,
   formatLocation,
   runLensVerificationPipeline,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
@@ -51,7 +53,8 @@ const PERF_LENSES: PerfLens[] = [
   { label: "measurement", category: "measurement", text: "Missing, misleading, noisy, or insufficient benchmark/measurement design." },
 ];
 
-const TOOLS = ["read", "bash"];
+const TOOLS = DEFAULT_ADVISORY_TOOLS;
+const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_LENS = 4;
 
 export default async function run(api: WorkflowApi): Promise<unknown> {
@@ -77,7 +80,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect repository structure, scripts, likely hot-path files, and any existing benchmark or measurement commands. " +
       "Prefer identifying what to measure before claiming bottlenecks. Return files, commands, summary, and known measurements or the lack of them. " +
       `This workflow will fan out across ${PERF_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
-    { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
   );
 
   if (!scope || scope.files.length === 0) {
@@ -107,6 +110,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     schedulingMode: "finder-barrier",
     perLens: PER_LENS,
     tools: TOOLS,
+    toolHints: TOOL_HINTS,
     finderPrompt: (lens) =>
       `## Perf-review finder — ${lens.label}\n\n${scopeBlock}\n` +
       "This workflow is advisory-only: identify bottleneck hypotheses, measurement gaps, and safe optimization directions, but do not edit files.\n" +

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -10,6 +10,8 @@ import {
   formatEvidence,
   formatLocation,
   runLensVerificationPipeline,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
@@ -50,7 +52,8 @@ const REFACTOR_LENSES: RefactorLens[] = [
   { label: "conventions", category: "conventions", text: "Departures from project conventions, naming, dependency rules, or local idioms." },
 ];
 
-const TOOLS = ["read", "bash"];
+const TOOLS = DEFAULT_ADVISORY_TOOLS;
+const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_LENS = 5;
 
 export default async function run(api: WorkflowApi): Promise<unknown> {
@@ -76,7 +79,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect repository structure, the target path or module, and relevant AGENTS.md / project docs conventions. " +
       "Return the concrete files that should be considered, a short summary, and any conventions that affect refactor advice. " +
       `This workflow will fan out across ${REFACTOR_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
-    { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
   );
 
   if (!scope || scope.files.length === 0) {
@@ -104,6 +107,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     schedulingMode: "finder-barrier",
     perLens: PER_LENS,
     tools: TOOLS,
+    toolHints: TOOL_HINTS,
     finderPrompt: (lens) =>
       `## Refactor-scout finder — ${lens.label}\n\n${scopeBlock}\n` +
       "This workflow is advisory-only: do not edit files and do not propose broad rewrites.\n" +