pi-workflow-engine 0.10.2 → 0.11.0

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

@@ -0,0 +1,404 @@
+import { createHash } from "node:crypto";
+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 { unknownErrorMessage } from "./unknown-error.ts";
+
+export type FingerprintCapture =
+  | { readonly kind: "verified"; readonly fingerprint: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export type TreeFileValidation =
+  | { readonly kind: "verified" }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface TreeFingerprintOptions {
+  readonly root: string;
+  /** Root-relative directory paths to exclude, never bare names at every depth. */
+  readonly excludedRelativePaths?: ReadonlySet<string>;
+  readonly maxBytes: number;
+  readonly maxFiles: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface TreeFileValidationOptions {
+  readonly root: string;
+  readonly path: string;
+  readonly excludedRelativePaths?: ReadonlySet<string>;
+  readonly signal?: AbortSignal;
+}
+
+export interface DeclaredInputFingerprintOptions {
+  readonly root: string;
+  /** Explicit paths relative to `root`. Files and directories are both supported. */
+  readonly inputs: readonly string[];
+  /** Paths with these segment sequences are never valid declared inputs. */
+  readonly excludedRelativePaths?: ReadonlySet<string>;
+  readonly maxBytes: number;
+  readonly maxEntries: number;
+  /** Record direct directory identity without recursively walking descendants. */
+  readonly shallowDirectories?: boolean;
+  readonly signal?: AbortSignal;
+}
+
+export type DeclaredInputPathResolution =
+  | { readonly kind: "verified"; readonly paths: readonly string[] }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface FingerprintFileOperations {
+  readonly open: (path: string, flags: number) => Promise<FileHandle>;
+  readonly lstat: (path: string) => Promise<BigIntStats>;
+}
+
+const NODE_FINGERPRINT_FILE_OPERATIONS: FingerprintFileOperations = {
+  open: async (path, flags) => await open(path, flags),
+  lstat: async (path) => await lstat(path, { bigint: true }),
+};
+
+/** A deterministic hash sink that enforces one shared byte budget across file reads. */
+export class BoundedFingerprint {
+  readonly #hash = createHash("sha256");
+  #bytes = 0;
+
+  constructor(private readonly maxBytes: number) {}
+
+  add(label: string, value: string | Buffer): void {
+    this.#hash.update(label);
+    this.#hash.update("\0");
+    this.#hash.update(value);
+    this.#hash.update("\0");
+  }
+
+  async addFileHandle(label: string, handle: FileHandle, signal?: AbortSignal): Promise<void> {
+    this.#hash.update(label);
+    this.#hash.update("\0");
+    const stream = handle.createReadStream({ autoClose: false, highWaterMark: 64 << 10, signal });
+    try {
+      for await (const chunk of stream) {
+        throwIfAborted(signal);
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        this.#bytes += buffer.length;
+        if (this.#bytes > this.maxBytes) {
+          stream.destroy();
+          throw new Error(`content fingerprint exceeded ${this.maxBytes} bytes`);
+        }
+        this.#hash.update(buffer);
+      }
+    } catch (error) {
+      throwIfAborted(signal);
+      throw error;
+    }
+    this.#hash.update("\0");
+  }
+
+  digest(): string {
+    return this.#hash.digest("hex");
+  }
+}
+
+/** Open, validate, and use one regular file without reopening its pathname. */
+export async function withValidatedFingerprintFile<T>(
+  path: string,
+  signal: AbortSignal | undefined,
+  use: (handle: FileHandle, info: BigIntStats) => Promise<T>,
+  operations: FingerprintFileOperations = NODE_FINGERPRINT_FILE_OPERATIONS,
+): Promise<T> {
+  throwIfAborted(signal);
+  const flags = process.platform === "win32"
+    ? constants.O_RDONLY
+    : constants.O_RDONLY | constants.O_NOFOLLOW;
+  const handle = await operations.open(path, flags);
+  try {
+    const [openedInfo, pathInfo] = await Promise.all([
+      handle.stat({ bigint: true }),
+      operations.lstat(path),
+    ]);
+    throwIfAborted(signal);
+    if (!openedInfo.isFile()) throw new Error(`content fingerprint opened an unsupported entry: ${path}`);
+    if (pathInfo.isSymbolicLink()) throw new Error(`content fingerprint encountered a symbolic link: ${path}`);
+    if (!pathInfo.isFile()) throw new Error(`content fingerprint encountered an unsupported entry: ${path}`);
+    if (openedInfo.dev !== pathInfo.dev || openedInfo.ino !== pathInfo.ino) {
+      throw new Error(`content fingerprint path changed while it was being opened: ${path}`);
+    }
+    return await use(handle, openedInfo);
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Fingerprint a bounded directory tree with stable path ordering and entry handling. */
+export async function captureTreeFingerprint(options: TreeFingerprintOptions): Promise<FingerprintCapture> {
+  try {
+    throwIfAborted(options.signal);
+    const root = resolve(options.root);
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory()) throw new Error(`fingerprint root is not a directory: ${root}`);
+
+    const fingerprint = new BoundedFingerprint(options.maxBytes);
+    const directories = [root];
+    let fileCount = 0;
+
+    for (let index = 0; index < directories.length; index++) {
+      throwIfAborted(options.signal);
+      const directory = directories[index]!;
+      const entries = await readdir(directory, { withFileTypes: true });
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+
+      for (const entry of entries) {
+        throwIfAborted(options.signal);
+        const path = join(directory, entry.name);
+        const relativePath = relative(root, path);
+        if (entry.isDirectory()) {
+          if (!isExcludedRelativePath(relativePath, options.excludedRelativePaths)) directories.push(path);
+          continue;
+        }
+
+        fileCount += 1;
+        if (fileCount > options.maxFiles) throw new Error(`content fingerprint exceeded ${options.maxFiles} files`);
+        fingerprint.add("path", relativePath);
+
+        if (entry.isSymbolicLink()) {
+          throw new Error(`content fingerprint encountered a symbolic link: ${path}`);
+        }
+        if (!entry.isFile()) throw new Error(`content fingerprint encountered an unsupported entry: ${path}`);
+
+        await withValidatedFingerprintFile(path, options.signal, async (handle, info) => {
+          fingerprint.add("mode", String(info.mode));
+          await fingerprint.addFileHandle("file", handle, options.signal);
+        });
+      }
+    }
+
+    return { kind: "verified", fingerprint: fingerprint.digest() };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+/** Fingerprint only explicitly declared files/directories under one shared bound. */
+export async function captureDeclaredInputFingerprint(
+  options: DeclaredInputFingerprintOptions,
+): Promise<FingerprintCapture> {
+  try {
+    throwIfAborted(options.signal);
+
+    const root = resolve(options.root);
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory()) throw new Error(`declared-input root is not a directory: ${root}`);
+
+    const resolvedInputs = resolveDeclaredInputPaths(root, options.inputs, options.excludedRelativePaths);
+    if (resolvedInputs.kind === "unverifiable") return resolvedInputs;
+    const inputs = resolvedInputs.paths;
+    const fingerprint = new BoundedFingerprint(options.maxBytes);
+    let entryCount = 0;
+
+    const recordEntry = (relativePath: string, kind: "directory" | "file" | "missing", mode?: number): void => {
+      entryCount += 1;
+      if (entryCount > options.maxEntries) {
+        throw new Error(`declared-input fingerprint exceeded ${options.maxEntries} entries`);
+      }
+      fingerprint.add("path", relativePath);
+      fingerprint.add("kind", kind);
+      if (mode !== undefined) fingerprint.add("mode", String(mode));
+    };
+
+    const visit = async (path: string, relativePath: string, directInput = false): Promise<boolean> => {
+      throwIfAborted(options.signal);
+
+      let info;
+      try {
+        info = await lstat(path);
+      } catch (error) {
+        if (!isMissingPathError(error)) throw error;
+        recordEntry(relativePath, "missing");
+        return true;
+      }
+
+      if (info.isSymbolicLink()) throw new Error(`declared input contains a symbolic link: ${relativePath}`);
+      if (info.isFile()) {
+        await withValidatedFingerprintFile(path, options.signal, async (handle, openedInfo) => {
+          recordEntry(relativePath, "file", Number(openedInfo.mode));
+          await fingerprint.addFileHandle("file", handle, options.signal);
+        });
+        return true;
+      }
+      if (!info.isDirectory()) throw new Error(`declared input contains an unsupported entry: ${relativePath}`);
+
+      if (options.shallowDirectories === true) {
+        recordEntry(relativePath, "directory", info.mode);
+        return true;
+      }
+
+      const entries = await readdir(path, { withFileTypes: true });
+      entries.sort((left, right) => left.name.localeCompare(right.name));
+      let hasObservableChild = false;
+      for (const entry of entries) {
+        const childPath = join(path, entry.name);
+        const childRelativePath = relativePath === "." ? entry.name : `${relativePath}/${entry.name}`;
+        if (isExcludedDeclaredInput(childRelativePath, options.excludedRelativePaths)) continue;
+        hasObservableChild = (await visit(childPath, childRelativePath)) || hasObservableChild;
+      }
+      const observableEmptyDirectory = entries.length === 0 && !isExcludedAncestor(relativePath, options.excludedRelativePaths);
+      if (!directInput && !hasObservableChild && !observableEmptyDirectory) return false;
+      recordEntry(relativePath, "directory", info.mode);
+      return true;
+    };
+
+    for (const relativePath of inputs) {
+      throwIfAborted(options.signal);
+      fingerprint.add("input", relativePath);
+      const segments = relativePath === "." ? [] : relativePath.split("/");
+      let path = root;
+      let missing = false;
+      for (let index = 0; index < Math.max(0, segments.length - 1); index++) {
+        path = join(path, segments[index]!);
+        let info;
+        try {
+          info = await lstat(path);
+        } catch (error) {
+          if (!isMissingPathError(error)) throw error;
+          recordEntry(relativePath, "missing");
+          missing = true;
+          break;
+        }
+        if (info.isSymbolicLink()) throw new Error(`declared input traverses a symbolic link: ${relativePath}`);
+        if (!info.isDirectory()) {
+          recordEntry(relativePath, "missing");
+          missing = true;
+          break;
+        }
+      }
+      if (!missing) await visit(relativePath === "." ? root : join(root, ...segments), relativePath, true);
+    }
+
+    return { kind: "verified", fingerprint: fingerprint.digest() };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+/** Validate and canonicalize caller-authored paths before passing them to Git or the filesystem. */
+export function resolveDeclaredInputPaths(
+  root: string,
+  inputs: readonly string[],
+  excludedRelativePaths?: ReadonlySet<string>,
+  base = root,
+): DeclaredInputPathResolution {
+  try {
+    if (!Array.isArray(inputs)) throw new Error("declared inputs must be an array");
+    const paths = [...new Set(inputs.map((input) => declaredInputPath(root, base, input)))].sort();
+    for (const path of paths) rejectExcludedDeclaredInput(path, excludedRelativePaths);
+    return { kind: "verified", paths };
+  } catch (error) {
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+/** Verify that a regular file is reached only through directories included in the tree hash. */
+export async function validateTreeFile(options: TreeFileValidationOptions): Promise<TreeFileValidation> {
+  try {
+    throwIfAborted(options.signal);
+    const root = resolve(options.root);
+    const path = resolve(options.path);
+    if (!isPathWithin(root, path)) return { kind: "unverifiable", reason: "file is outside its fingerprint root" };
+
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory()) throw new Error(`fingerprint root is not a directory: ${root}`);
+    const pathFromRoot = relative(root, path);
+    if (pathFromRoot === "") return { kind: "unverifiable", reason: "fingerprint source resolves to its root directory" };
+
+    const segments = pathFromRoot.split(/[\\/]/).filter(Boolean);
+    let current = root;
+    for (let index = 0; index < segments.length; index++) {
+      throwIfAborted(options.signal);
+      const segment = segments[index]!;
+      const isFile = index === segments.length - 1;
+      if (!isFile && isExcludedRelativePath(relative(root, join(current, segment)), options.excludedRelativePaths)) {
+        return { kind: "unverifiable", reason: "file is inside an excluded fingerprint directory" };
+      }
+      current = join(current, segment);
+      const info = await lstat(current);
+      if (isFile ? !info.isFile() : !info.isDirectory()) {
+        return {
+          kind: "unverifiable",
+          reason: isFile ? "fingerprint source is not a regular file" : "fingerprint source path traverses a non-directory entry",
+        };
+      }
+    }
+    return { kind: "verified" };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+export function isPathWithin(root: string, path: string): boolean {
+  const pathFromRoot = relative(resolve(root), resolve(path));
+  return pathFromRoot === "" || (!isAbsolute(pathFromRoot) && pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`));
+}
+
+function isExcludedRelativePath(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+  if (!excluded || excluded.size === 0) return false;
+  const normalized = normalizeRelativePath(path);
+  for (const candidate of excluded) {
+    const normalizedCandidate = normalizeRelativePath(candidate);
+    if (normalized === normalizedCandidate || normalized.startsWith(`${normalizedCandidate}/`)) return true;
+  }
+  return false;
+}
+
+function normalizeRelativePath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+
+function declaredInputPath(root: string, base: string, input: string): string {
+  if (typeof input !== "string" || input.length === 0) throw new Error("declared input paths must be non-empty strings");
+  if (isAbsolute(input)) throw new Error(`declared input must be relative to the workflow cwd: ${input}`);
+  const path = resolve(base, input);
+  if (!isPathWithin(root, path)) throw new Error(`declared input escapes the repository root: ${input}`);
+  if (!isPathWithin(base, path)) throw new Error(`declared input escapes the workflow cwd: ${input}`);
+  const relativePath = relative(root, path).split(sep).join("/");
+  return relativePath.length === 0 ? "." : relativePath;
+}
+
+function rejectExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): void {
+  if (!isExcludedDeclaredInput(path, excluded)) return;
+  throw new Error(`declared input enters excluded path: ${path}`);
+}
+
+function isExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+  if (!excluded) return false;
+  const normalized = normalizeRelativePath(path);
+  for (const candidate of excluded) {
+    const normalizedCandidate = normalizeRelativePath(candidate);
+    if (
+      normalized === normalizedCandidate ||
+      normalized.startsWith(`${normalizedCandidate}/`) ||
+      normalized.endsWith(`/${normalizedCandidate}`) ||
+      normalized.includes(`/${normalizedCandidate}/`)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isExcludedAncestor(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+  if (!excluded) return false;
+  const segments = normalizeRelativePath(path).split("/").filter((segment) => segment !== ".");
+  for (const candidate of excluded) {
+    const normalizedCandidate = normalizeRelativePath(candidate);
+    for (let index = 0; index < segments.length; index++) {
+      const suffix = segments.slice(index).join("/");
+      if (normalizedCandidate.startsWith(`${suffix}/`)) return true;
+    }
+  }
+  return false;
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

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

@@ -1,10 +1,11 @@
 import type { Static, TSchema } from "typebox";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { WorkflowBudget } from "./budget.ts";
-import type { Pipeline } from "./concurrency.ts";
+import type { Pipeline, WorkflowParallel } from "./concurrency.ts";
 import type { PerfSink, PerfSnapshot } from "./perf.ts";
 import type { WorkflowProgressSnapshot } from "./progress.ts";
 import type { WorkflowUsageSnapshot } from "./usage.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
 
 /** A reference to a registered workflow by name. */
 export type WorkflowRef = string;
@@ -39,7 +40,7 @@ export interface WorkflowRunOptions {
   budget?: number;
   /** Internal/test override for the generated run id. Omit to generate a new id. */
   runId?: string;
-  /** Replay completed agent results from this prior run id when prompt/options hashes still match. */
+  /** Replay completed agent results from this prior run id when call and execution context still match. */
   resumeFromRunId?: string;
   resultViewer?: "open" | "skip";
   /** Additional abort signal to compose with the host context signal. */
@@ -47,17 +48,17 @@ export interface WorkflowRunOptions {
   /** Internal recorder override for command/tool invocation timing. */
   perfRecorder?: PerfSink;
   /** Resolve a sub-workflow reference to a module, enabling `api.workflow()`. When omitted, `api.workflow()` throws. */
-  resolveWorkflow?: (ref: WorkflowRef) => Promise<WorkflowModule>;
+  resolveWorkflow?: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
   /** Called with the final performance snapshot when perf is enabled. */
-  onPerfSnapshot?: (snapshot: PerfSnapshot) => void;
+  onPerfSnapshot?: (snapshot: PerfSnapshot) => void | Promise<void>;
   /** Called with the final workflow subagent usage snapshot. */
-  onUsageSnapshot?: (snapshot: WorkflowUsageSnapshot) => void;
+  onUsageSnapshot?: (snapshot: WorkflowUsageSnapshot) => void | Promise<void>;
   /** Called once run identity and journal paths are known. */
-  onRunMetadata?: (metadata: WorkflowRunMetadata) => void;
+  onRunMetadata?: (metadata: WorkflowRunMetadata) => void | Promise<void>;
   /** Called with the live progress source while a workflow is running, then undefined when it ends. */
-  onProgressSource?: (source: WorkflowProgressSource | undefined) => void;
+  onProgressSource?: (source: WorkflowProgressSource | undefined) => void | Promise<void>;
   /** Called with the final completed progress snapshot after live workflow UI teardown. */
-  onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void;
+  onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void | Promise<void>;
 }
 
 export interface WorkflowProgressSource {
@@ -68,6 +69,7 @@ export interface WorkflowProgressSource {
 export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
 
 export type AgentToolHint = "search";
+export type AgentResumePolicy = "read-only" | "off";
 
 export interface IsolatedAgentResult<T> {
   readonly result: T;
@@ -105,6 +107,20 @@ export interface AgentOptions<S extends TSchema = TSchema> {
    * with identical prompts/options, e.g. `${stage}:${item.id}`.
    */
   cacheKey?: string;
+  /**
+   * Resume policy for this call. Shared-workspace agents run live unless they
+   * explicitly declare themselves read-only. Those calls bind replay to the full
+   * Git-visible workspace; isolated agents bind to their disposable baseline.
+   * Use "off" to disable both journal reads and writes.
+   */
+  resume?: AgentResumePolicy;
+  /**
+   * Additional ignored/generated inputs under the workflow cwd that this
+   * read-only agent may observe. Git-visible files across the repository are
+   * captured automatically; list cwd-relative ignored paths here or use
+   * `resume: "off"` when their bounded contents cannot be captured.
+   */
+  resumeInputs?: readonly string[];
   /** Run this agent in a disposable git worktree and return its patch with the result. */
   isolation?: "worktree";
   /** Allowlist of concrete tool names the agent may use (e.g. ["read", "bash"]). */
@@ -151,9 +167,9 @@ export interface WorkflowApi {
   workflow(ref: WorkflowRef, args?: string): Promise<unknown>;
   /**
    * Run every thunk concurrently and wait for all (a barrier). Recoverable thunk
-   * failures become null slots; filter nulls before consuming survivors.
+   * failures become null slots by default; settled mode retains serialisable errors.
    */
-  parallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  parallel: WorkflowParallel;
   /**
    * Run each item through all stages independently — no barrier between stages.
    * A recoverable stage failure drops that item to null and skips its later stages.
@@ -181,7 +197,19 @@ export interface WorkflowApi {
 
 export type WorkflowRun = (api: WorkflowApi) => Promise<unknown>;
 
+export type WorkflowSourceIdentity =
+  | { readonly kind: "file"; readonly path: string; readonly root: string; readonly fingerprint: string }
+  | { readonly kind: "fingerprint"; readonly fingerprint: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+/** The authored exports of a workflow module. */
 export interface WorkflowModule {
   meta: WorkflowMeta;
   default: WorkflowRun;
 }
+
+/** A validated workflow plus engine-owned provenance used for safe resume replay. */
+export interface LoadedWorkflow extends WorkflowModule {
+  readonly source: WorkflowSourceIdentity;
+  readonly isolatedWorktreeBaseline?: WorktreeBaseline;
+}

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

@@ -1,68 +1,17 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Text } from "@earendil-works/pi-tui";
-import type { AdvisoryFinding, AdvisoryLocation, AdvisoryReport } from "../advisory-schema.ts";
-import type { PerfAggregate } from "../perf.ts";
+import { isAdvisoryReport, type AdvisoryReportWithStats } from "../advisory-schema.ts";
 import { renderIssueDetails, renderIssuesTable } from "../review/review-format.ts";
-import { toReviewIssues, type ReviewContext } from "../review/review-issues.ts";
+import { toReviewIssues } from "../review/review-issues.ts";
 import { formatCount } from "./workflow-format.ts";
-import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "../usage.ts";
-
-export interface WorkflowPerfDetails {
-  readonly enabled: boolean;
-  readonly startedAt: number;
-  readonly aggregates: readonly PerfAggregate[];
-}
-
-export interface WorkflowResultEnvelope {
-  name: string;
-  result: unknown;
-  completedAt: number;
-  usage?: WorkflowUsageSnapshot;
-  perf?: WorkflowPerfDetails;
-  runId?: string;
-  resumedFromRunId?: string;
-}
-
-export interface AdvisoryWorkflowResult extends AdvisoryReport {
-  stats?: Record<string, string | number>;
-  reviewContext?: ReviewContext;
-}
+import { formatWorkflowUsageLine } from "../usage.ts";
+import type { WorkflowPerfDetails, WorkflowResultEnvelope } from "../workflow-execution.ts";
 
 export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelope {
   if (!isRecord(value)) return false;
   return typeof value.name === "string" && "result" in value && typeof value.completedAt === "number";
 }
 
-function isAdvisoryLocation(value: unknown): value is AdvisoryLocation {
-  if (!isRecord(value)) return false;
-  if (typeof value.file !== "string") return false;
-  if (value.line !== undefined && typeof value.line !== "number") return false;
-  if (value.symbol !== undefined && typeof value.symbol !== "string") return false;
-  return true;
-}
-
-function isAdvisoryFinding(value: unknown): value is AdvisoryFinding {
-  if (!isRecord(value)) return false;
-  if (typeof value.summary !== "string") return false;
-  if (typeof value.category !== "string") return false;
-  if (!isSeverity(value.severity)) return false;
-  if (!isConfidence(value.confidence)) return false;
-  if (!Array.isArray(value.locations) || !value.locations.every(isAdvisoryLocation)) return false;
-  if (!Array.isArray(value.evidence) || !value.evidence.every((entry) => typeof entry === "string")) return false;
-  if (typeof value.impact !== "string") return false;
-  if (typeof value.recommendation !== "string") return false;
-  return true;
-}
-
-export function isAdvisoryReport(value: unknown): value is AdvisoryWorkflowResult {
-  if (!isRecord(value)) return false;
-  if (typeof value.summary !== "string" || !Array.isArray(value.findings)) return false;
-  if (!value.findings.every(isAdvisoryFinding)) return false;
-  if (!Array.isArray(value.nextSteps) || !value.nextSteps.every((entry) => typeof entry === "string")) return false;
-  if (value.stats !== undefined && !isStats(value.stats)) return false;
-  return true;
-}
-
 export interface WorkflowRunDisplayMetadata {
   readonly runId?: string;
   readonly resumedFromRunId?: string;
@@ -105,7 +54,7 @@ export function renderWorkflowResultText(
 
 function renderAdvisoryResult(
   name: string,
-  result: AdvisoryWorkflowResult,
+  result: AdvisoryReportWithStats,
   expanded: boolean,
   theme: Theme,
   usage?: unknown,
@@ -213,19 +162,6 @@ function safeJson(value: unknown): string {
   }
 }
 
-function isSeverity(value: unknown): value is AdvisoryFinding["severity"] {
-  return value === "low" || value === "medium" || value === "high";
-}
-
-function isConfidence(value: unknown): value is AdvisoryFinding["confidence"] {
-  return value === "low" || value === "medium" || value === "high";
-}
-
-function isStats(value: unknown): value is Record<string, string | number> {
-  if (!isRecord(value)) return false;
-  return Object.values(value).every((entry) => typeof entry === "string" || typeof entry === "number");
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }

package/.pi/extensions/pi-workflow-engine/src/unknown-error.ts

@@ -0,0 +1,8 @@
+/** Read an unknown thrown value without allowing hostile coercion to mask the original failure. */
+export function unknownErrorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}