pi-workflow-engine 0.13.0 → 1.0.0

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

@@ -1,13 +1,15 @@
 import { createHash } from "node:crypto";
 import { throwIfAborted } from "../cancellation.ts";
-import { captureDiffTarget, type DiffCaptureFailure } from "../diff-capture.ts";
+import { isGitObjectId, runGit } from "../git.ts";
 import {
+  GIT_DIFF_MACHINE_FORMAT,
+  reviewDiffCommand,
   reviewGitDiffBaseline,
   type GitReviewDiffTarget,
   type PullRequestReviewDiffTarget,
   type ReviewDiffTarget,
 } from "../review-diff-target.ts";
-import { runBoundedProcess } from "../process-runner.ts";
+import type { BoundedProcessResult } from "../process-runner.ts";
 import { unknownErrorMessage } from "../unknown-error.ts";
 import type { WorktreeBaseline } from "../worktree.ts";
 import type { ReviewContext, ReviewSnapshotIdentity } from "./review-report.ts";
@@ -39,7 +41,6 @@ export interface CapturedReviewMaterial {
 export interface ReviewMaterialCaptureFailure {
   readonly ok: false;
   readonly error: string;
-  readonly failure: DiffCaptureFailure;
 }
 
 export type ReviewMaterialCaptureResult = CapturedReviewMaterial | ReviewMaterialCaptureFailure;
@@ -64,36 +65,34 @@ export async function captureReviewMaterial(
     if (!before.ok) {
       throwIfAborted(signal);
       return latestDiff === undefined
-        ? { ok: false, error: before.error, failure: before.failure }
+        ? { ok: false, error: before.error }
         : capturedWithoutSnapshot(latestDiff, `review diff could not be recaptured: ${before.error}`);
     }
-    latestDiff = before.diff;
+    latestDiff = before.stdout;
 
     let baseline: WorktreeBaseline;
     try {
       baseline = await captureReviewWorktreeBaseline(target, cwd, signal);
     } catch (error) {
       throwIfAborted(signal);
-      return capturedWithoutSnapshot(before.diff, `review baseline could not be captured: ${unknownErrorMessage(error)}`);
+      return capturedWithoutSnapshot(before.stdout, `review baseline could not be captured: ${unknownErrorMessage(error)}`);
     }
 
     const after = await captureReviewDiff(target, cwd, signal);
     if (!after.ok) {
       throwIfAborted(signal);
-      return capturedWithoutSnapshot(before.diff, `review diff could not be recaptured: ${after.error}`);
+      return capturedWithoutSnapshot(before.stdout, `review diff could not be recaptured: ${after.error}`);
     }
-    latestDiff = after.diff;
+    latestDiff = after.stdout;
 
-    const beforeFingerprint = fingerprintReviewDiff(before.diff);
-    const afterFingerprint = fingerprintReviewDiff(after.diff);
-    if (beforeFingerprint === afterFingerprint) {
+    if (before.stdout === after.stdout) {
       return {
         ok: true,
-        diff: after.diff,
+        diff: after.stdout,
         snapshot: {
           status: "verified",
           identity: {
-            diffFingerprint: afterFingerprint,
+            diffFingerprint: createHash("sha256").update(after.stdout).digest("hex"),
             baselineFingerprint: fingerprintReviewWorktreeBaseline(baseline),
           },
           baseline,
@@ -138,20 +137,15 @@ export function fingerprintReviewWorktreeBaseline(baseline: WorktreeBaseline): s
     .digest("hex");
 }
 
-async function captureReviewDiff(
-  target: ReviewDiffTarget,
-  cwd: string,
-  signal: AbortSignal | undefined,
-): Promise<{ readonly ok: true; readonly diff: string } | { readonly ok: false; readonly error: string; readonly failure: DiffCaptureFailure }> {
-  const captured = await captureDiffTarget(target, {
+function captureReviewDiff(target: ReviewDiffTarget, cwd: string, signal: AbortSignal | undefined): Promise<BoundedProcessResult> {
+  return runGit({
+    ...reviewDiffCommand(target),
     cwd,
+    label: "diff capture",
     signal,
     timeoutMs: REVIEW_SNAPSHOT_TIMEOUT_MS,
     maxBufferBytes: REVIEW_SNAPSHOT_MAX_BYTES,
   });
-  return captured.ok
-    ? { ok: true, diff: captured.stdout }
-    : { ok: false, error: captured.error, failure: captured.failure };
 }
 
 async function captureReviewWorktreeBaseline(
@@ -170,29 +164,31 @@ async function resolvePullRequestBaseline(
   signal: AbortSignal | undefined,
 ): Promise<WorktreeBaseline> {
   const number = String(target.number);
-  const viewed = await runReviewCommand("gh", ["pr", "view", number, "--json", "headRefOid,headRefName,headRepository"], cwd, signal);
+  const viewed = await runReviewCommand("gh", ["pr", "view", number, "--json", "headRefOid,headRefName,headRepository,url"], cwd, signal);
   const details = viewed.ok ? parsePullRequestHead(viewed.stdout) : undefined;
   if (!details) {
-    throw new Error(`pull request head could not be resolved: ${viewed.error ?? (viewed.stderr.trim() || "invalid head commit")}`);
+    throw new Error(`pull request head could not be resolved: ${viewed.ok ? "invalid head commit" : viewed.error}`);
   }
 
   if (!(await commitExists(details.head, cwd, signal))) {
     const fetched = await runReviewCommand(
       "git",
-      ["fetch", "--no-tags", "--quiet", `https://github.com/${details.repository}.git`, details.branch],
+      ["fetch", "--no-tags", "--quiet", `${details.origin}/${details.repository}.git`, details.branch],
       cwd,
       signal,
     );
     if (!fetched.ok || !(await commitExists(details.head, cwd, signal))) {
       throw new Error(
-        `pull request ${number} head ${details.head} is not available locally: ${fetched.error ?? (fetched.stderr.trim() || "fetch did not provide the commit")}`,
+        `pull request ${number} head ${details.head} is not available locally: ${fetched.ok ? "fetch did not provide the commit" : fetched.error}`,
       );
     }
   }
   return { ref: details.head };
 }
 
-function parsePullRequestHead(value: string): { readonly head: string; readonly branch: string; readonly repository: string } | undefined {
+function parsePullRequestHead(
+  value: string,
+): { readonly head: string; readonly branch: string; readonly repository: string; readonly origin: string } | undefined {
   let parsed: unknown;
   try {
     parsed = JSON.parse(value);
@@ -204,12 +200,17 @@ function parsePullRequestHead(value: string): { readonly head: string; readonly
     readonly headRefOid?: unknown;
     readonly headRefName?: unknown;
     readonly headRepository?: { readonly nameWithOwner?: unknown } | null;
+    readonly url?: unknown;
   };
-  if (typeof candidate.headRefOid !== "string" || !/^[0-9a-f]{40,64}$/i.test(candidate.headRefOid)) return undefined;
+  if (typeof candidate.headRefOid !== "string" || !isGitObjectId(candidate.headRefOid)) return undefined;
   if (typeof candidate.headRefName !== "string" || candidate.headRefName.length === 0 || candidate.headRefName.includes("\0")) return undefined;
   const repository = candidate.headRepository?.nameWithOwner;
   if (typeof repository !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) return undefined;
-  return { head: candidate.headRefOid, branch: candidate.headRefName, repository };
+  // The PR URL carries the host gh resolved the PR on, which is not github.com for GitHub Enterprise.
+  if (typeof candidate.url !== "string" || !URL.canParse(candidate.url)) return undefined;
+  const url = new URL(candidate.url);
+  if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
+  return { head: candidate.headRefOid, branch: candidate.headRefName, repository, origin: url.origin };
 }
 
 async function resolveGitDiffBaseline(
@@ -236,9 +237,7 @@ async function captureMutableGitBaseline(
   const head = await tryResolveCommit("HEAD", cwd, signal);
   if (!head) throw new Error("the reviewed repository has no committed HEAD baseline");
 
-  const args = staged
-    ? ["diff", "--no-ext-diff", "--binary", "--cached", "HEAD"]
-    : ["diff", "--no-ext-diff", "--binary", "HEAD"];
+  const args = ["diff", "--no-ext-diff", ...GIT_DIFF_MACHINE_FORMAT, "--binary", ...(staged ? ["--cached"] : []), "HEAD"];
   const snapshot = await runReviewCommand("git", args, cwd, signal, REVIEW_SNAPSHOT_MAX_BYTES);
   if (!snapshot.ok) {
     throw new Error(`the reviewed working state could not be captured: ${snapshot.error}`);
@@ -255,7 +254,7 @@ async function resolveCommit(ref: string, cwd: string, signal: AbortSignal | und
 async function tryResolveCommit(ref: string, cwd: string, signal: AbortSignal | undefined): Promise<string | undefined> {
   const result = await runReviewCommand("git", ["rev-parse", "--verify", `${ref}^{commit}`], cwd, signal);
   const commit = result.stdout.trim();
-  return result.ok && /^[0-9a-f]{40,64}$/i.test(commit) ? commit : undefined;
+  return result.ok && isGitObjectId(commit) ? commit : undefined;
 }
 
 async function commitExists(ref: string, cwd: string, signal: AbortSignal | undefined): Promise<boolean> {
@@ -270,25 +269,17 @@ async function runReviewCommand(
   signal: AbortSignal | undefined,
   maxBufferBytes = REVIEW_COMMAND_MAX_BYTES,
 ) {
-  return await runBoundedProcess({
+  return await runGit({
     file,
-    args,
     cwd,
-    env: { ...process.env, GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" },
+    args,
+    label: `${file} review snapshot command`,
     signal,
     timeoutMs: REVIEW_SNAPSHOT_TIMEOUT_MS,
     maxBufferBytes,
-    abortError: `${file} review snapshot command aborted`,
-    timeoutError: `${file} review snapshot command timed out after ${REVIEW_SNAPSHOT_TIMEOUT_MS}ms`,
-    maxBufferError: `${file} review snapshot command exceeded output limit`,
-    exitError: (stderr, code, processSignal) => stderr.trim() || `${file} exited with code ${code ?? `signal ${processSignal ?? "unknown"}`}`,
   });
 }
 
 function capturedWithoutSnapshot(diff: string, reason: string): CapturedReviewMaterial {
   return { ok: true, diff, snapshot: { status: "unavailable", reason } };
 }
-
-function fingerprintReviewDiff(diff: string): string {
-  return createHash("sha256").update(diff).digest("hex");
-}

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

@@ -1,6 +1,12 @@
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 
+/**
+ * Pins the git diff output that the engine parses or applies, so user config such as
+ * diff.noprefix, diff.mnemonicPrefix, diff.srcPrefix or color.ui cannot change it.
+ */
+export const GIT_DIFF_MACHINE_FORMAT = ["--no-color", "--src-prefix=a/", "--dst-prefix=b/"] as const;
+
 export type GitDiffBaselineTarget =
   | { readonly kind: "working-tree" }
   | { readonly kind: "index" }
@@ -96,15 +102,16 @@ function isAllowedGitDiffFlag(token: string): boolean {
   return SAFE_GIT_DIFF_FLAGS.has(token) || /^-U\d+$/.test(token) || /^--unified=\d+$/.test(token) || /^--inter-hunk-context=\d+$/.test(token);
 }
 
+/** Executable argv. Git targets gain the machine-format pins, which stay out of the persisted and displayed target. */
 export function reviewDiffCommand(target: ReviewDiffTarget): { readonly file: "git" | "gh"; readonly args: readonly string[] } {
   return target.kind === "pull-request"
     ? { file: "gh", args: ["pr", "diff", String(target.number), "--color=never"] }
-    : { file: "git", args: target.args };
+    : { file: "git", args: ["diff", ...GIT_DIFF_MACHINE_FORMAT, ...target.args.slice(1)] };
 }
 
 /** Canonical display form. Never execute this string directly; use reviewDiffCommand(). */
 export function formatReviewDiffTarget(target: ReviewDiffTarget): string {
-  const command = reviewDiffCommand(target);
+  const command = target.kind === "git" ? { file: "git", args: target.args } : reviewDiffCommand(target);
   return [command.file, ...command.args].join(" ");
 }
 
@@ -115,16 +122,8 @@ export function reviewGitDiffBaseline(target: GitReviewDiffTarget): GitDiffBasel
   return parsed.baseline;
 }
 
-/** Validate persisted targets by round-tripping through the single command allowlist parser. */
-export function isReviewDiffTarget(value: unknown): value is ReviewDiffTarget {
-  if (!Value.Check(ReviewDiffTargetSchema, value)) return false;
-  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(value));
-  return !("error" in parsed) && sameReviewDiffTarget(parsed, value);
-}
-
-function sameReviewDiffTarget(left: ReviewDiffTarget, right: ReviewDiffTarget): boolean {
-  if (left.kind !== right.kind) return false;
-  if (left.kind === "pull-request") return right.kind === "pull-request" && left.number === right.number;
-  if (right.kind !== "git" || left.args.length !== right.args.length) return false;
-  return left.args.every((arg, index) => arg === right.args[index]);
+/** Validate a schema-checked persisted target by round-tripping it through the single command allowlist parser. */
+export function isAllowedReviewDiffTarget(target: ReviewDiffTarget): boolean {
+  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(target));
+  return !("error" in parsed) && Value.Equal(parsed, target);
 }

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

@@ -0,0 +1,29 @@
+/** Cap text at `limit` characters, ending a cut value with an ellipsis. */
+export function truncateText(value: string, limit: number): string {
+  return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`;
+}
+
+/** Pretty-printed JSON, or undefined when the value has no JSON form or cannot be serialized (cycles, BigInt). */
+export function prettyJson(value: unknown): string | undefined {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Compact count for display: 999, 1.2k, 12.3k, 123k, 1.2M. */
+export function formatCount(n: number): string {
+  if (!Number.isFinite(n)) return "0";
+  const sign = n < 0 ? "-" : "";
+  const value = Math.abs(n);
+  if (value < 1_000) return `${Math.trunc(n)}`;
+  if (value < 1_000_000) return `${sign}${formatCompact(value / 1_000)}k`;
+  return `${sign}${formatCompact(value / 1_000_000)}M`;
+}
+
+function formatCompact(value: number): string {
+  if (value >= 100) return `${Math.round(value)}`;
+  const rounded = Math.round(value * 10) / 10;
+  return Number.isInteger(rounded) ? `${rounded}` : rounded.toFixed(1);
+}

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

@@ -33,7 +33,8 @@ function isExternalSearchLikeTool(tool: ToolInfo): boolean {
 }
 
 function isSearchLikeTool(tool: ToolInfo): boolean {
-  if (isMutationLikeToolName(tool.name)) return false;
+  // Local code search must not hand repository context to web search tools.
+  if (isMutationLikeToolName(tool.name) || isExternalSearchLikeTool(tool)) return false;
   const name = tool.name.toLowerCase();
   if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
   return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description.toLowerCase());

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

@@ -2,8 +2,15 @@ import { lstat } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { isMissingPathError } from "./filesystem-error.ts";
 import { hashIdentity } from "./identity-fingerprint.ts";
-import { logicalWorkspacePath, portableRelativePath } from "./replay-path-identity.ts";
-import { captureTreeFingerprint, isPathWithin, validateTreeFile, type FingerprintCapture } from "./tree-fingerprint.ts";
+import { logicalWorkspacePath } from "./replay-path-identity.ts";
+import {
+  captureSourceTreeFingerprint,
+  FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+  isPathWithin,
+  portableRelativePath,
+  validateTreeFile,
+  type FingerprintCapture,
+} from "./tree-fingerprint.ts";
 
 export interface EffectiveToolSourceInfoLike {
   readonly path: string;
@@ -32,10 +39,6 @@ export interface ToolSourceIdentityOptions {
   readonly signal?: AbortSignal;
 }
 
-const SOURCE_FINGERPRINT_MAX_BYTES = 32 << 20;
-const SOURCE_FINGERPRINT_MAX_FILES = 4096;
-const SOURCE_FINGERPRINT_EXCLUSIONS = new Set([".git", ".pi/.workflow-runs"]);
-
 export async function captureEffectiveToolSourceIdentity(
   sourceInfo: EffectiveToolSourceInfoLike,
   options: ToolSourceIdentityOptions,
@@ -58,26 +61,20 @@ export async function captureEffectiveToolSourceIdentity(
     };
   }
 
-  const baseDir = declaredBaseDir === undefined ? undefined : resolveDeclaredPath(declaredBaseDir, options.sessionCwd);
+  const baseDir = declaredBaseDir === undefined ? undefined : resolve(options.sessionCwd, declaredBaseDir);
   const sourcePath = await resolveExistingSourcePath(path, baseDir, options.sessionCwd, options.workspaceRoot);
   const sourceRoot = baseDir && isPathWithin(baseDir, sourcePath) ? baseDir : dirname(sourcePath);
   const validation = await validateTreeFile({
     root: sourceRoot,
     path: sourcePath,
-    excludedRelativePaths: SOURCE_FINGERPRINT_EXCLUSIONS,
+    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
     signal: options.signal,
   });
   if (validation.kind === "unverifiable") throw new Error(`tool source "${path}" is not fingerprintable: ${validation.reason}`);
 
   let capture = options.cache.get(sourceRoot);
   if (!capture) {
-    capture = captureTreeFingerprint({
-      root: sourceRoot,
-      excludedRelativePaths: SOURCE_FINGERPRINT_EXCLUSIONS,
-      maxBytes: SOURCE_FINGERPRINT_MAX_BYTES,
-      maxFiles: SOURCE_FINGERPRINT_MAX_FILES,
-      signal: options.signal,
-    });
+    capture = captureSourceTreeFingerprint(sourceRoot, options.signal);
     options.cache.set(sourceRoot, capture);
   }
   const fingerprint = await capture;
@@ -103,11 +100,11 @@ async function resolveExistingSourcePath(
 ): Promise<string> {
   const candidates = isAbsolute(path)
     ? [resolve(path)]
-    : uniquePaths([
+    : [...new Set([
         ...(baseDir ? [resolve(baseDir, path), resolve(baseDir, path.split(/[\\/]/).at(-1) ?? path)] : []),
         resolve(sessionCwd, path),
         resolve(workspaceRoot, path),
-      ]);
+      ])];
 
   for (const candidate of candidates) {
     try {
@@ -119,13 +116,8 @@ async function resolveExistingSourcePath(
   throw new Error(`tool source path does not identify a regular file: ${path}`);
 }
 
-function resolveDeclaredPath(path: string, sessionCwd: string): string {
-  return isAbsolute(path) ? resolve(path) : resolve(sessionCwd, path);
-}
-
 function normalizeUnresolvedBaseDir(path: string, sessionCwd: string, workspaceRoot: string): string {
-  const resolvedPath = resolveDeclaredPath(path, sessionCwd);
-  return logicalWorkspacePath(resolvedPath, { sessionCwd, workspaceRoot }) ?? "source-root:.";
+  return logicalWorkspacePath(resolve(sessionCwd, path), { sessionCwd, workspaceRoot }) ?? "source-root:.";
 }
 
 function logicalSourcePath(path: string, sourceRoot: string, sessionCwd: string, workspaceRoot: string): string {
@@ -139,11 +131,7 @@ function isSyntheticSource(path: string, source: string): boolean {
   return (path.startsWith("<") && path.endsWith(">")) || source === "builtin" || source === "sdk" || /^(?:builtin|sdk):/.test(path);
 }
 
-function uniquePaths(paths: readonly string[]): readonly string[] {
-  return [...new Set(paths)];
-}
-
-function nonEmptyString(value: string, label: string): string {
+export function nonEmptyString(value: string, label: string): string {
   if (typeof value !== "string") throw new Error(`${label} is not a string`);
   if (value.length === 0) throw new Error(`${label} is empty`);
   return value;

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

@@ -6,6 +6,15 @@ import { throwIfAborted } from "./cancellation.ts";
 import { isMissingPathError } from "./filesystem-error.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
+/** Engine-owned paths that are never part of a fingerprinted or snapshotted workspace. */
+export const FINGERPRINT_EXCLUDED_RELATIVE_PATHS: ReadonlySet<string> = new Set([
+  ".git",
+  ".pi/.workflow-runs",
+]);
+
+const SOURCE_TREE_MAX_BYTES = 32 << 20;
+const SOURCE_TREE_MAX_FILES = 4096;
+
 export type FingerprintCapture =
   | { readonly kind: "verified"; readonly fingerprint: string }
   | { readonly kind: "unverifiable"; readonly reason: string };
@@ -38,8 +47,6 @@ export interface DeclaredInputFingerprintOptions {
   readonly excludedRelativePaths?: ReadonlySet<string>;
   readonly maxBytes: number;
   readonly maxEntries: number;
-  /** Record direct directory identity without recursively walking descendants. */
-  readonly shallowDirectories?: boolean;
   readonly signal?: AbortSignal;
 }
 
@@ -71,9 +78,9 @@ export class BoundedFingerprint {
     this.#hash.update("\0");
   }
 
+  /** File bytes may contain NUL, so they enter the outer hash as a fixed-length digest. */
   async addFileHandle(label: string, handle: FileHandle, signal?: AbortSignal): Promise<void> {
-    this.#hash.update(label);
-    this.#hash.update("\0");
+    const content = createHash("sha256");
     const stream = handle.createReadStream({ autoClose: false, highWaterMark: 64 << 10, signal });
     try {
       for await (const chunk of stream) {
@@ -84,13 +91,13 @@ export class BoundedFingerprint {
           stream.destroy();
           throw new Error(`content fingerprint exceeded ${this.maxBytes} bytes`);
         }
-        this.#hash.update(buffer);
+        content.update(buffer);
       }
     } catch (error) {
       throwIfAborted(signal);
       throw error;
     }
-    this.#hash.update("\0");
+    this.add(label, content.digest("hex"));
   }
 
   digest(): string {
@@ -178,6 +185,20 @@ export async function captureTreeFingerprint(options: TreeFingerprintOptions): P
   }
 }
 
+/**
+ * Fingerprint a workflow or tool source tree. Workflow provenance captured at
+ * load time is revalidated on resume, so both captures must share these bounds.
+ */
+export async function captureSourceTreeFingerprint(root: string, signal?: AbortSignal): Promise<FingerprintCapture> {
+  return await captureTreeFingerprint({
+    root,
+    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+    maxBytes: SOURCE_TREE_MAX_BYTES,
+    maxFiles: SOURCE_TREE_MAX_FILES,
+    signal,
+  });
+}
+
 /** Fingerprint only explicitly declared files/directories under one shared bound. */
 export async function captureDeclaredInputFingerprint(
   options: DeclaredInputFingerprintOptions,
@@ -227,11 +248,6 @@ export async function captureDeclaredInputFingerprint(
       }
       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;
@@ -341,6 +357,11 @@ export function isPathWithin(root: string, path: string): boolean {
   return pathFromRoot === "" || (!isAbsolute(pathFromRoot) && pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`));
 }
 
+export function portableRelativePath(root: string, path: string): string {
+  const value = relative(root, path).split(sep).join("/");
+  return value.length === 0 ? "." : value;
+}
+
 function isExcludedRelativePath(path: string, excluded: ReadonlySet<string> | undefined): boolean {
   if (!excluded || excluded.size === 0) return false;
   const normalized = normalizeRelativePath(path);
@@ -361,8 +382,7 @@ function declaredInputPath(root: string, base: string, input: string): string {
   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;
+  return portableRelativePath(root, path);
 }
 
 function rejectExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): void {
@@ -370,7 +390,7 @@ function rejectExcludedDeclaredInput(path: string, excluded: ReadonlySet<string>
   throw new Error(`declared input enters excluded path: ${path}`);
 }
 
-function isExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): boolean {
+export function isExcludedDeclaredInput(path: string, excluded: ReadonlySet<string> | undefined): boolean {
   if (!excluded) return false;
   const normalized = normalizeRelativePath(path);
   for (const candidate of excluded) {

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

@@ -3,10 +3,14 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { WorkflowBudget } from "./budget.ts";
 import type { Pipeline, WorkflowParallel } from "./concurrency.ts";
 import type { PerfSink, PerfSnapshot } from "./perf.ts";
+
+/** The host-facing tool this extension registers; subagents also load extensions, so it is withheld from them. */
+export const WORKFLOW_TOOL_NAME = "workflow";
 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";
+import type { WorkflowRunState } from "./workflow-run-record.ts";
 
 export type { WorkflowLaneItemStatus } from "./progress-types.ts";
 
@@ -91,6 +95,8 @@ export interface WorkflowRunOptions {
 
 export interface WorkflowProgressSource {
   snapshot(): WorkflowProgressSnapshot;
+  /** Durable lifecycle state of the run, so a finished snapshot can tell completed from failed. */
+  readonly state?: () => WorkflowRunState;
 }
 
 /** Options for a single `agent()` call. */