pi-workflow-engine 0.10.3 → 0.11.0

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

@@ -2,21 +2,53 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { AgentOptions } from "./types.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
+import { canonicalizeIdentity } from "./identity-canonicalization.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  isAgentResumeContext,
+  resumeContextMismatchReason,
+  type AgentResumeContext,
+} from "./resume-context.ts";
 
 export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
 export const WORKFLOW_JOURNAL_KEEP = 50;
 
-export interface JournalEntry {
+export interface JournalEntryV2 {
+  readonly version: 2;
+  readonly key: string;
+  readonly result: unknown;
+  readonly identity: AgentResumeContext;
+}
+
+/** Parsed so journals written before effective-session identity can fail closed without aborting resume. */
+export interface LegacyJournalEntryV2 {
+  readonly version: 2;
+  readonly key: string;
+  readonly result: unknown;
+  readonly identity: unknown;
+}
+
+/** Parsed only so resume can explain why an older entry is not replayed. */
+export interface LegacyJournalEntryV1 {
+  readonly version?: 1;
   readonly key: string;
   readonly value: unknown;
+  readonly context?: unknown;
 }
 
-export type JournalLookup = { readonly hit: true; readonly value: unknown } | { readonly hit: false };
+export type JournalEntry = LegacyJournalEntryV2 | LegacyJournalEntryV1;
+
+export type JournalLookup = { readonly hit: true; readonly value: unknown } | { readonly hit: false; readonly reason?: string };
 export type JournalRecordResult = { readonly ok: true } | { readonly ok: false; readonly error: string };
 
+export type AgentJournalKeyCapture =
+  | { readonly kind: "verified"; readonly key: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
 export interface WorkflowJournal {
-  lookup(key: string): JournalLookup;
-  record(key: string, value: unknown): Promise<JournalRecordResult>;
+  lookup(key: string, identity: AgentResumeContext): JournalLookup;
+  record(key: string, result: unknown, identity: AgentResumeContext): Promise<JournalRecordResult>;
 }
 
 export class WorkflowJournalLoadError extends Error {
@@ -31,28 +63,71 @@ export function workflowJournalPath(cwd: string, runId: string): string {
   return join(cwd, WORKFLOW_RUNS_DIR, `${validateRunId(runId)}.jsonl`);
 }
 
-export function agentJournalKey(prompt: string, opts: AgentOptions = {}): string {
-  const behaviorHash = hashAgentCall(prompt, opts);
-  const cacheKey = opts.cacheKey?.trim();
-  if (!cacheKey) return `agent:${behaviorHash}`;
+export function agentJournalKey(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
+  const capture = captureAgentJournalKey(prompt, opts, worktreeBaseline);
+  return capture.kind === "verified" ? capture.key : `agent:unverifiable:${randomUUID()}`;
+}
+
+export function hashAgentCall(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
+  const capture = captureAgentCallHash(prompt, opts, worktreeBaseline);
+  return capture.kind === "verified"
+    ? capture.hash
+    : createHash("sha256").update(`unverifiable:${randomUUID()}`).digest("hex");
+}
+
+/** Capture a replay key without allowing hostile or oversized schemas to escape as exceptions. */
+export function captureAgentJournalKey(
+  prompt: string,
+  opts: AgentOptions = {},
+  worktreeBaseline?: WorktreeBaseline,
+): AgentJournalKeyCapture {
+  const behavior = captureAgentCallHash(prompt, opts, worktreeBaseline);
+  if (behavior.kind === "unverifiable") return behavior;
+  let cacheKey: string | undefined;
+  try {
+    cacheKey = opts.cacheKey?.trim();
+  } catch {
+    return { kind: "unverifiable", reason: "agent cache key could not be inspected" };
+  }
+  if (!cacheKey) return { kind: "verified", key: `agent:${behavior.hash}` };
   const cacheKeyHash = createHash("sha256").update(cacheKey).digest("hex");
-  return `agent:${cacheKeyHash}:${behaviorHash}`;
-}
-
-export function hashAgentCall(prompt: string, opts: AgentOptions = {}): string {
-  const behavior = {
-    prompt,
-    opts: {
-      model: opts.model,
-      thinkingLevel: opts.thinkingLevel,
-      tools: sortedArray(opts.tools),
-      toolHints: sortedArray(opts.toolHints),
-      skills: sortedArray(opts.skills),
-      schema: opts.schema,
-      isolation: opts.isolation,
-    },
-  };
-  return createHash("sha256").update(stableStringify(behavior)).digest("hex");
+  return { kind: "verified", key: `agent:${cacheKeyHash}:${behavior.hash}` };
+}
+
+type AgentCallHashCapture =
+  | { readonly kind: "verified"; readonly hash: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+function captureAgentCallHash(
+  prompt: string,
+  opts: AgentOptions,
+  worktreeBaseline: WorktreeBaseline | undefined,
+): AgentCallHashCapture {
+  try {
+    const behavior = {
+      prompt,
+      opts: {
+        thinkingLevel: opts.thinkingLevel,
+        tools: opts.tools,
+        toolHints: opts.toolHints,
+        skills: opts.skills,
+        schema: opts.schema,
+        isolation: opts.isolation,
+        worktreeBaseline: worktreeBaseline
+          ? {
+              ref: worktreeBaseline.ref,
+              patchFingerprint: createHash("sha256").update(worktreeBaseline.patch ?? "").digest("hex"),
+            }
+          : undefined,
+      },
+    };
+    const canonical = canonicalizeIdentity(behavior);
+    return canonical.kind === "verified"
+      ? { kind: "verified", hash: createHash("sha256").update(canonical.value).digest("hex") }
+      : canonical;
+  } catch {
+    return { kind: "unverifiable", reason: "agent replay inputs could not be inspected" };
+  }
 }
 
 export async function loadJournalEntries(path: string, options: { readonly required?: boolean } = {}): Promise<JournalEntry[]> {
@@ -61,7 +136,7 @@ export async function loadJournalEntries(path: string, options: { readonly requi
     content = await readFile(path, "utf8");
   } catch (error) {
     if (options.required) {
-      throw new WorkflowJournalLoadError(`Could not load workflow resume journal at ${path}: ${formatError(error)}`);
+      throw new WorkflowJournalLoadError(`Could not load workflow resume journal at ${path}: ${unknownErrorMessage(error)}`);
     }
     return [];
   }
@@ -99,25 +174,42 @@ export async function createWorkflowJournal(options: {
 }
 
 export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[] = [], writePath?: string): WorkflowJournal {
-  const priorByKey = new Map<string, JournalEntry | "ambiguous">();
+  const priorByKey = new Map<string, JournalEntry[]>();
   for (const entry of priorEntries) {
-    priorByKey.set(entry.key, priorByKey.has(entry.key) ? "ambiguous" : entry);
+    const entries = priorByKey.get(entry.key) ?? [];
+    entries.push(entry);
+    priorByKey.set(entry.key, entries);
   }
 
   return {
-    lookup(key) {
-      const entry = priorByKey.get(key);
-      if (!entry || entry === "ambiguous") return { hit: false };
-      return { hit: true, value: entry.value };
+    lookup(key, identity) {
+      const entries = priorByKey.get(key);
+      if (!entries || entries.length === 0) return { hit: false };
+
+      const current = entries.filter(
+        (entry): entry is JournalEntryV2 => entry.version === 2 && isAgentResumeContext(entry.identity),
+      );
+      if (current.length === 0) {
+        return {
+          hit: false,
+          reason: entries.some((entry) => entry.version === 2)
+            ? "journal entry predates effective replay identity"
+            : "journal entry predates replay contract v2",
+        };
+      }
+      const matches = current.filter((entry) => resumeContextMismatchReason(entry.identity, identity) === undefined);
+      if (matches.length === 1) return { hit: true, value: matches[0]!.result };
+      if (matches.length > 1) return { hit: false, reason: "multiple cached entries match this agent call" };
+      return { hit: false, reason: resumeContextMismatchReason(current[0]!.identity, identity) };
     },
-    async record(key, value) {
-      const entry = { key, value };
+    async record(key, result, identity) {
+      const entry: JournalEntryV2 = { version: 2, key, result, identity };
       if (writePath) {
         try {
           await mkdir(dirname(writePath), { recursive: true });
           await appendFile(writePath, `${JSON.stringify(entry)}\n`, "utf8");
         } catch (error) {
-          return { ok: false, error: formatError(error) };
+      return { ok: false, error: unknownErrorMessage(error) };
         }
       }
       return { ok: true };
@@ -164,37 +256,29 @@ function validateRunId(runId: string): string {
   return trimmed;
 }
 
-function sortedArray(values: readonly string[] | undefined): readonly string[] | undefined {
-  return values ? [...values].sort() : undefined;
-}
-
-function stableStringify(value: unknown): string {
-  return JSON.stringify(normalizeStable(value));
-}
-
-function normalizeStable(value: unknown): unknown {
-  if (value === undefined) return undefined;
-  if (value === null) return null;
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
-  if (Array.isArray(value)) return value.map(normalizeStable);
-  if (typeof value === "object") {
-    const record = value as Record<string, unknown>;
-    const out: Record<string, unknown> = {};
-    for (const key of Object.keys(record).sort()) {
-      const normalized = normalizeStable(record[key]);
-      if (normalized !== undefined) out[key] = normalized;
-    }
-    return out;
-  }
-  return String(value);
-}
-
 function isJournalEntry(value: unknown): value is JournalEntry {
   if (typeof value !== "object" || value === null) return false;
-  const entry = value as { readonly key?: unknown; readonly value?: unknown };
-  return typeof entry.key === "string" && "value" in entry;
+  const entry = value as {
+    readonly version?: unknown;
+    readonly key?: unknown;
+    readonly result?: unknown;
+    readonly identity?: unknown;
+    readonly value?: unknown;
+    readonly context?: unknown;
+  };
+  if (entry.version === 2) {
+    return typeof entry.key === "string" && "result" in entry && "identity" in entry;
+  }
+  return (
+    (entry.version === undefined || entry.version === 1) &&
+    typeof entry.key === "string" &&
+    "value" in entry &&
+    (entry.context === undefined || isLegacyAgentResumeContext(entry.context))
+  );
 }
 
-function formatError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function isLegacyAgentResumeContext(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const context = value as { readonly repository?: unknown; readonly workflow?: unknown; readonly model?: unknown };
+  return "repository" in context && "workflow" in context && "model" in context;
 }

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

@@ -4,12 +4,15 @@ import type { WorkflowRunOptions } from "./types.ts";
 export const WORKFLOW_BUDGET_MIN = 1;
 export const WORKFLOW_BUDGET_MAX = 1_000_000_000;
 
-export interface ResolvedWorkflowRunOptions extends WorkflowRunOptions {
+export type ResolvedWorkflowRunOptions = Omit<
+  WorkflowRunOptions,
+  "perf" | "concurrency" | "parallelSubmissionLimit" | "budget"
+> & {
   readonly perf: boolean;
   readonly concurrency: number;
-  readonly parallelSubmissionLimit?: number;
-  readonly budget?: number;
-}
+  readonly parallelSubmissionLimit: number | null;
+  readonly budget: number | null;
+};
 
 export function defaultConcurrency(cpuCount = cpus().length): number {
   return Math.min(8, Math.max(2, cpuCount));
@@ -30,8 +33,8 @@ export function resolveWorkflowRunOptions(
     ...input,
     perf: input.perf ?? env.PI_WORKFLOW_PERF === "1",
     concurrency,
-    parallelSubmissionLimit,
-    budget,
+    parallelSubmissionLimit: parallelSubmissionLimit ?? null,
+    budget: budget ?? null,
   };
 }
 

package/.pi/extensions/pi-workflow-engine/src/process-runner.ts

@@ -1,11 +1,13 @@
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { performance } from "node:perf_hooks";
+import { unknownErrorMessage } from "./unknown-error.ts";
 
 export interface BoundedProcessOptions {
   readonly file: string;
   readonly args: readonly string[];
   readonly cwd: string;
   readonly env?: NodeJS.ProcessEnv;
+  readonly stdin?: string | Uint8Array;
   readonly signal?: AbortSignal;
   readonly timeoutMs: number;
   readonly maxBufferBytes?: number;
@@ -16,81 +18,243 @@ export interface BoundedProcessOptions {
   readonly exitError: (stderr: string, code: number | null, signal: NodeJS.Signals | null) => string;
 }
 
-export interface BoundedProcessResult {
-  readonly ok: boolean;
+interface BoundedProcessResultBase {
   readonly stdout: string;
   readonly stderr: string;
   readonly durationMs: number;
   readonly bytes: number;
-  readonly error?: string;
 }
 
-export async function runBoundedProcess(options: BoundedProcessOptions): Promise<BoundedProcessResult> {
+export interface UnconfirmedProcessTermination {
+  readonly status: "unconfirmed";
+  readonly reason: string;
+}
+
+export type BoundedProcessFailure =
+  | { readonly kind: "spawn" | "abort" | "timeout" | "max-buffer"; readonly message: string }
+  | {
+      readonly kind: "exit";
+      readonly message: string;
+      readonly code: number | null;
+      readonly signal: NodeJS.Signals | null;
+    };
+
+export type BoundedProcessResult =
+  | (BoundedProcessResultBase & { readonly ok: true; readonly error?: undefined; readonly failure?: undefined })
+  | (BoundedProcessResultBase & {
+      readonly ok: false;
+      /** Backward-compatible display message. Branch on `failure.kind` for control flow. */
+      readonly error: string;
+      readonly failure: BoundedProcessFailure;
+      /** Present only when the runner's final bound elapsed without observing child closure. */
+      readonly termination?: UnconfirmedProcessTermination;
+    });
+
+export type WindowsTaskkillResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: string };
+
+export interface ProcessRunnerDependencies {
+  readonly platform: NodeJS.Platform;
+  readonly runWindowsTaskkill: (pid: number, complete: (result: WindowsTaskkillResult) => void) => void;
+  readonly killChild: (child: ChildProcess, signal: NodeJS.Signals) => boolean;
+}
+
+const NODE_PROCESS_RUNNER_DEPENDENCIES: ProcessRunnerDependencies = {
+  platform: process.platform,
+  runWindowsTaskkill(pid, complete) {
+    let completed = false;
+    const finish = (result: WindowsTaskkillResult) => {
+      if (completed) return;
+      completed = true;
+      complete(result);
+    };
+    try {
+      const killer = spawn("taskkill.exe", ["/pid", String(pid), "/t", "/f"], {
+        detached: false,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      killer.once("error", (error) => finish({ ok: false, reason: `taskkill failed to start: ${unknownErrorMessage(error)}` }));
+      killer.once("close", (code, signal) => {
+        if (code === 0) {
+          finish({ ok: true });
+          return;
+        }
+        finish({
+          ok: false,
+          reason: `taskkill exited with ${code === null ? `signal ${signal ?? "unknown"}` : `code ${code}`}`,
+        });
+      });
+      killer.unref();
+    } catch (error) {
+      finish({ ok: false, reason: `taskkill could not be started: ${unknownErrorMessage(error)}` });
+    }
+  },
+  killChild: (child, signal) => child.kill(signal),
+};
+
+export async function runBoundedProcess(
+  options: BoundedProcessOptions,
+  dependencies: ProcessRunnerDependencies = NODE_PROCESS_RUNNER_DEPENDENCIES,
+): Promise<BoundedProcessResult> {
   const start = performance.now();
   let stdout = "";
   let stderr = "";
   let bytes = 0;
-  let error: string | undefined;
+  let pendingFailure: BoundedProcessFailure | undefined;
   const child = spawn(options.file, [...options.args], {
     cwd: options.cwd,
     env: options.env ?? process.env,
-    stdio: ["ignore", "pipe", "pipe"],
+    detached: dependencies.platform !== "win32",
+    stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
   });
 
   return await new Promise<BoundedProcessResult>((resolve) => {
     let settled = false;
     let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    let hardSettleTimer: ReturnType<typeof setTimeout> | undefined;
+    let directChildKillAttempted = false;
+    let windowsTerminationReason = "process close was not observed after taskkill and direct-child fallback";
     const killGraceMs = Math.max(1, options.killGraceMs ?? 100);
-    const finish = (ok: boolean, finishError?: string) => {
+    const cleanup = () => {
+      clearTimeout(timeout);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      if (hardSettleTimer) clearTimeout(hardSettleTimer);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (failure?: BoundedProcessFailure, termination?: UnconfirmedProcessTermination) => {
       if (settled) return;
       settled = true;
       cleanup();
-      resolve({ ok, stdout, stderr, durationMs: performance.now() - start, bytes, error: finishError });
+      const base = { stdout, stderr, durationMs: performance.now() - start, bytes };
+      if (!failure) {
+        resolve({ ...base, ok: true });
+        return;
+      }
+      resolve({ ...base, ok: false, error: failure.message, failure, ...(termination ? { termination } : {}) });
     };
-    const kill = (message: string) => {
-      error = error ?? message;
-      child.kill("SIGTERM");
-      forceKillTimer ??= setTimeout(() => {
-        child.kill("SIGKILL");
-        finish(false, error);
-      }, killGraceMs);
+    const killDirectChild = (signal: NodeJS.Signals, reason: string) => {
+      if (directChildKillAttempted) return;
+      directChildKillAttempted = true;
+      windowsTerminationReason = reason;
+      try {
+        if (!dependencies.killChild(child, signal)) {
+          windowsTerminationReason = `${reason}; direct-child termination was not accepted`;
+        }
+      } catch (error) {
+        windowsTerminationReason = `${reason}; direct-child termination failed: ${unknownErrorMessage(error)}`;
+      }
     };
-    const onAbort = () => kill(options.abortError);
-    const timeout = setTimeout(() => kill(options.timeoutError), options.timeoutMs);
-    const cleanup = () => {
-      clearTimeout(timeout);
-      if (forceKillTimer) clearTimeout(forceKillTimer);
-      options.signal?.removeEventListener("abort", onAbort);
+    const signalPosixProcess = (signal: NodeJS.Signals) => {
+      let groupSignalled = false;
+      if (child.pid !== undefined) {
+        try {
+          process.kill(-child.pid, signal);
+          groupSignalled = true;
+        } catch {
+          // The process may have exited before its descendants released stdio.
+          // Fall back to the direct child below.
+        }
+      }
+      if (!groupSignalled) {
+        try {
+          dependencies.killChild(child, signal);
+        } catch {
+          // The hard-settlement timer remains authoritative when signalling fails.
+        }
+      }
     };
+    const destroyStdio = () => {
+      child.stdin?.destroy();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+    };
+    const terminate = (failure: BoundedProcessFailure) => {
+      pendingFailure ??= failure;
+      if (forceKillTimer) return;
+      if (dependencies.platform === "win32") {
+        if (child.pid === undefined) {
+          killDirectChild("SIGKILL", "taskkill was unavailable because the child process had no pid");
+        } else {
+          try {
+            dependencies.runWindowsTaskkill(child.pid, (result) => {
+              if (settled || result.ok) return;
+              killDirectChild("SIGKILL", result.reason);
+            });
+          } catch (error) {
+            killDirectChild("SIGKILL", `taskkill invocation failed: ${unknownErrorMessage(error)}`);
+          }
+        }
+      } else {
+        signalPosixProcess("SIGTERM");
+      }
+      forceKillTimer = setTimeout(() => {
+        if (dependencies.platform === "win32") {
+          if (directChildKillAttempted) {
+            windowsTerminationReason = `${windowsTerminationReason}; child did not close within the termination grace period`;
+          } else {
+            killDirectChild("SIGKILL", "taskkill did not close the child within the termination grace period");
+          }
+        } else {
+          signalPosixProcess("SIGKILL");
+        }
+        destroyStdio();
+        if (!settled) {
+          hardSettleTimer = setTimeout(() => {
+            if (!pendingFailure) return;
+            finish(
+              pendingFailure,
+              { status: "unconfirmed", reason: dependencies.platform === "win32"
+                ? windowsTerminationReason
+                : "process close was not observed after forced process-group termination" },
+            );
+          }, killGraceMs);
+        }
+      }, killGraceMs);
+    };
+    const onAbort = () => terminate({ kind: "abort", message: options.abortError });
+    const timeout = setTimeout(() => terminate({ kind: "timeout", message: options.timeoutError }), options.timeoutMs);
 
-    if (options.signal?.aborted) {
-      kill(options.abortError);
-    } else {
-      options.signal?.addEventListener("abort", onAbort, { once: true });
-    }
-
-    child.stdout?.on("data", (chunk: Buffer) => {
+    const captureChunk = (chunk: Buffer, append: (text: string) => void) => {
+      if (pendingFailure) return;
       bytes += chunk.length;
       if (options.maxBufferBytes !== undefined && bytes > options.maxBufferBytes) {
-        kill(options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`);
+        terminate({
+          kind: "max-buffer",
+          message: options.maxBufferError ?? `process output exceeded ${options.maxBufferBytes} bytes`,
+        });
         return;
       }
-      stdout += chunk.toString("utf8");
-    });
-    child.stderr?.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString("utf8");
+      append(chunk.toString("utf8"));
+    };
+    child.stdout?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stdout += text)));
+    child.stderr?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stderr += text)));
+    child.on("error", (spawnError) => {
+      if (!pendingFailure) finish({ kind: "spawn", message: spawnError.message });
     });
-    child.on("error", (spawnError) => finish(false, spawnError.message));
     child.on("close", (code, signal) => {
-      if (error) {
-        finish(false, error);
+      if (pendingFailure) {
+        finish(pendingFailure);
         return;
       }
       if (code === 0) {
-        finish(true);
+        finish();
         return;
       }
-      finish(false, options.exitError(stderr, code, signal));
+      const message = options.exitError(stderr, code, signal);
+      finish({ kind: "exit", message, code, signal });
     });
+    if (options.signal?.aborted) {
+      onAbort();
+    } else {
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+    }
+    if (options.stdin !== undefined) {
+      // The child may reject input and exit before consuming it. Its process exit
+      // remains the authoritative result; avoid surfacing a secondary EPIPE.
+      child.stdin?.on("error", () => undefined);
+      child.stdin?.end(options.stdin);
+    }
   });
 }

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

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
 import type { WorkflowLaneItemStatus, WorkflowProgressEvent } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 import { statusTextFromCounts, type WorkflowStatusCounts } from "./ui/workflow-format.ts";
 import { createWorkflowWidget, type WorkflowWidget } from "./ui/workflow-widget.ts";
 
@@ -228,7 +229,7 @@ export class ProgressTracker {
     if (row) {
       this.transitionAgentStatus(row, "failed");
       row.doneAt = Date.now();
-      row.error = errorMessage(error);
+      row.error = unknownErrorMessage(error);
     }
     this.render();
   }
@@ -384,7 +385,3 @@ function laneItemLimitFromEnv(): number {
   if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_LANE_ITEM_LIMIT;
   return Math.trunc(parsed);
 }
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/.pi/extensions/pi-workflow-engine/src/replay-path-identity.ts

@@ -0,0 +1,48 @@
+import { relative, resolve, sep } from "node:path";
+import { isPathWithin } from "./tree-fingerprint.ts";
+
+export interface ReplayWorkspaceRoots {
+  readonly sessionCwd: string;
+  readonly workspaceRoot: string;
+}
+
+/** Map a path in either the disposable session or main workspace to one stable namespace. */
+export function logicalWorkspacePath(path: string, roots: ReplayWorkspaceRoots): string | undefined {
+  for (const root of resolvedWorkspaceRoots(roots)) {
+    if (isPathWithin(root, path)) return `workspace:${portableRelativePath(root, path)}`;
+  }
+  return undefined;
+}
+
+/** Normalize absolute workspace paths embedded in generated system prompts. */
+export function normalizeWorkspaceReferences(value: string, roots: ReplayWorkspaceRoots): string {
+  const paths = [...resolvedWorkspaceRoots(roots)].sort((left, right) => right.length - left.length);
+  return paths.reduce((normalized, path) => replacePathPrefix(normalized, path, "<workspace>"), value);
+}
+
+export function portableRelativePath(root: string, path: string): string {
+  const value = relative(root, path).split(sep).join("/");
+  return value.length === 0 ? "." : value;
+}
+
+function resolvedWorkspaceRoots(roots: ReplayWorkspaceRoots): readonly string[] {
+  return [...new Set([resolve(roots.sessionCwd), resolve(roots.workspaceRoot)])];
+}
+
+function replacePathPrefix(value: string, prefix: string, replacement: string): string {
+  let result = "";
+  let cursor = 0;
+  while (cursor < value.length) {
+    const index = value.indexOf(prefix, cursor);
+    if (index === -1) return result + value.slice(cursor);
+    const next = value[index + prefix.length];
+    if (next !== undefined && next !== "/" && next !== "\\" && /[\p{L}\p{N}._-]/u.test(next)) {
+      result += value.slice(cursor, index + prefix.length);
+      cursor = index + prefix.length;
+      continue;
+    }
+    result += value.slice(cursor, index) + replacement;
+    cursor = index + prefix.length;
+  }
+  return result;
+}