pi-workflow-engine 0.10.3 → 0.12.0

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

@@ -0,0 +1,401 @@
+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 { isMissingPathError } from "./filesystem-error.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;
+}

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

@@ -1,10 +1,14 @@
 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 { WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progress-types.ts";
 import type { WorkflowUsageSnapshot } from "./usage.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
+import type { WorkflowModelProfileName } from "./model-profiles.ts";
+
+export type { WorkflowLaneItemStatus } from "./progress-types.ts";
 
 /** A reference to a registered workflow by name. */
 export type WorkflowRef = string;
@@ -28,6 +32,13 @@ export interface WorkflowRunMetadata {
   readonly runId: string;
   readonly resumedFromRunId?: string;
   readonly journalPath: string;
+  readonly recordPath: string;
+}
+
+export interface WorkflowBackgroundOrigin {
+  /** Stable pi session id used to route and deduplicate completion delivery. */
+  readonly sessionId: string;
+  readonly requestedAt: number;
 }
 
 export interface WorkflowRunOptions {
@@ -35,29 +46,47 @@ export interface WorkflowRunOptions {
   perf?: boolean;
   concurrency?: number;
   parallelSubmissionLimit?: number;
-  /** Output-token ceiling for the whole run. Omit for no limit (budget.total === null). */
+  /** Maximum number of agent calls that may reach a live model session during this run. */
+  maxAgents?: number;
+  /** Maximum live duration of one agent call in milliseconds. */
+  agentTimeoutMs?: number;
+  /** Retry count for transient provider/session failures. Defaults to zero. */
+  agentRetries?: number;
+  /** Explicitly schedule resumable background runs after recognized provider usage windows. */
+  autoResumeOnUsageLimit?: boolean;
+  /** Maximum recognized usage-limit pauses before automatic scheduling stops. */
+  usageLimitMaxAttempts?: number;
+  /** Maximum delay accepted from a provider reset hint. */
+  usageLimitMaxDelayMs?: number;
+  /** Internal count carried into a scheduler-created successor run. */
+  usageLimitAttempt?: number;
+  /** Output-token ceiling across recorded subagent attempts. Omit for no limit (budget.total === null). */
   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. */
+  /** Internal origin metadata for an explicitly backgrounded tool invocation. */
+  background?: WorkflowBackgroundOrigin;
+  /** Replay completed agent results from this prior run id when call and execution context still match. */
   resumeFromRunId?: string;
+  /** Explicitly allow resume to ignore only a workflow-source fingerprint mismatch. */
+  resumeEditedWorkflow?: boolean;
   resultViewer?: "open" | "skip";
   /** Additional abort signal to compose with the host context signal. */
   signal?: AbortSignal;
   /** 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 {
@@ -65,9 +94,8 @@ export interface WorkflowProgressSource {
 }
 
 /** Options for a single `agent()` call. */
-export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
-
-export type AgentToolHint = "search";
+export type AgentToolHint = "search" | "external-search";
+export type AgentResumePolicy = "read-only" | "off";
 
 export interface IsolatedAgentResult<T> {
   readonly result: T;
@@ -94,27 +122,46 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   /** Phase to group this agent under in the progress tree. */
   phase?: string;
   /**
-   * Optional model id. Omit to inherit the host model. Explicit refs are strict:
-   * bare ids resolve as Anthropic shorthand; use "provider/id" for other providers.
+   * Optional model id. Overrides profile routing; when both model and profile are
+   * omitted, inherit the host model. Explicit refs are strict: bare ids resolve as
+   * Anthropic shorthand; use "provider/id" for other providers.
    */
   model?: string;
-  /** Reasoning effort for this agent. */
+  /** Reasoning effort for this agent. Overrides the profile's configured effort. */
   thinkingLevel?: ThinkingLevel;
+  /** Exact configured model route to use when model/thinkingLevel do not override it. */
+  profile?: WorkflowModelProfileName;
   /**
    * Stable identity hint for resume replay. Use this for repeated logical calls
    * 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"]). */
   tools?: string[];
   /**
-   * Dynamically include installed tools matching semantic categories. Currently
-   * "search" matches grep/find/code-search style tools such as ast-grep,
-   * mgrep, ffgrep, fffind, ripgrep wrappers, and pi's built-in grep/find/ls.
+   * Dynamically include installed tools matching semantic categories. "search"
+   * matches local grep/find/code-search tools; "external-search" matches installed
+   * web search, browsing, and URL extraction tools.
    */
   toolHints?: readonly AgentToolHint[];
+  /** Fail before prompting unless every semantic tool hint matched an installed tool. */
+  requireToolHints?: boolean;
   /**
    * Skill names to expose to this subagent. Subagents receive no skills by default.
    * When omitted, clear prompt text such as `/skill:name`, `include skill name`, or
@@ -122,7 +169,10 @@ export interface AgentOptions<S extends TSchema = TSchema> {
    * prompt inference for prompts that mention skills only as subject matter.
    */
   skills?: readonly string[];
-  /** typebox schema. When set, the agent is forced to return matching structured data. */
+  /**
+   * typebox schema. The agent must call the validated `final_answer` tool; bounded
+   * repair exhaustion throws `WorkflowStructuredOutputError` instead of returning null.
+   */
   schema?: S;
 }
 
@@ -135,11 +185,11 @@ export interface WorkflowApi {
   agent<S extends TSchema>(
     prompt: string,
     opts: AgentOptions<S> & { schema: S; isolation: "worktree" },
-  ): Promise<IsolatedAgentResult<Static<S> | null>>;
+  ): Promise<IsolatedAgentResult<Static<S>>>;
   /** Run a text subagent in a disposable worktree and return its final text plus patch. */
   agent(prompt: string, opts: AgentOptions & { isolation: "worktree" }): Promise<IsolatedAgentResult<string>>;
-  /** Run a subagent and return its validated structured output (null if it never produced one). */
-  agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S> | null>;
+  /** Run a subagent and return validated structured output; rejects with a recoverable typed error on repair exhaustion. */
+  agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S>>;
   /** Run a subagent and return its final assistant text. */
   agent(prompt: string, opts?: AgentOptions): Promise<string>;
   /**
@@ -151,9 +201,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 +231,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;
+}