pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/background-workflows.ts

@@ -1,18 +1,20 @@
 import { SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { WorkflowAbortError, WorkflowPauseError } from "./cancellation.ts";
+import { isRecord } from "./guards.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import {
+  stopWorkflowRunRecord,
   transitionWorkflowRun,
   type WorkflowRunRecord,
   type WorkflowRunState,
 } from "./workflow-run-record.ts";
-import { updateWorkflowRunDelivery } from "./workflow-run-background.ts";
+import { updateWorkflowRunDelivery, type WorkflowRunDelivery } from "./workflow-run-background.ts";
 import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { truncateText } from "./text.ts";
+import { workflowResultSummary } from "./workflow-execution.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
-import { emptyWorkflowUsageTotals } from "./usage.ts";
 
 const BACKGROUND_DELIVERY_CUSTOM_TYPE = "workflow-result";
-const BACKGROUND_WIDGET_KEY = "workflow-background";
 const SHUTDOWN_WAIT_MS = 5_000;
 const SUMMARY_LIMIT = 500;
 
@@ -25,7 +27,10 @@ export interface BackgroundWorkflowStartInput {
 
 export interface BackgroundWorkflowResultDetails {
   readonly name: string;
-  readonly result: { readonly summary: string };
+  /** The retained result of a completed run, so the delivery renders like a foreground result; else `{ summary }`. */
+  readonly result: unknown;
+  readonly summary: string;
+  readonly startedAt?: number;
   readonly completedAt: number;
   readonly usage: WorkflowRunRecord["usage"];
   readonly runId: string;
@@ -56,7 +61,7 @@ type BackgroundWorkflowSettledListener = (ctx: ExtensionContext, runId: string)
 /** Owns background runs for one extension instance and routes their durable completion delivery. */
 export class BackgroundWorkflowCoordinator {
   private readonly active = new Map<string, ActiveBackgroundRun>();
-  private readonly settledListeners = new Set<BackgroundWorkflowSettledListener>();
+  private settledListener: BackgroundWorkflowSettledListener | undefined;
   private readonly pendingDelivery = new Map<string, Set<string>>();
   private readonly shuttingDown = new Set<string>();
   private readonly storeForCwd: (cwd: string) => WorkflowRunStore;
@@ -82,13 +87,8 @@ export class BackgroundWorkflowCoordinator {
     let accepted = false;
     let deliveryScheduled = false;
     let settled = false;
-    let startedSignalled = false;
-    let resolveStarted: (() => void) | undefined;
-    let rejectStarted: ((error: unknown) => void) | undefined;
-    const started = new Promise<void>((resolve, reject) => {
-      resolveStarted = resolve;
-      rejectStarted = reject;
-    });
+    // Settles once: a rejection after the run published its metadata is ignored.
+    const started = Promise.withResolvers<void>();
 
     const scheduleDelivery = (): void => {
       if (deliveryScheduled || !accepted || !settled || this.shuttingDown.has(sessionId)) return;
@@ -100,18 +100,13 @@ export class BackgroundWorkflowCoordinator {
 
     const settledPromise = (async () => {
       try {
-        await input.run(controller.signal, () => {
-          if (startedSignalled) return;
-          startedSignalled = true;
-          resolveStarted?.();
-        });
-        if (!startedSignalled) rejectStarted?.(new Error("Background workflow ended before publishing run metadata."));
+        await input.run(controller.signal, () => started.resolve());
+        started.reject(new Error("Background workflow ended before publishing run metadata."));
       } catch (error) {
-        if (!startedSignalled) rejectStarted?.(error);
+        started.reject(error);
       } finally {
         settled = true;
         this.active.delete(input.runId);
-        this.updateBackgroundSurface(input.ctx);
         await this.notifyRunSettled(input.ctx, input.runId);
         scheduleDelivery();
       }
@@ -124,7 +119,7 @@ export class BackgroundWorkflowCoordinator {
       isSettled: () => settled,
     });
 
-    await started;
+    await started.promise;
     const record = await this.storeForCwd(input.ctx.cwd).load(input.runId);
     if (record?.state !== "running" || !record.background || record.background.origin.sessionId !== sessionId) {
       controller.abort(new WorkflowAbortError("Background workflow could not persist its origin metadata."));
@@ -132,7 +127,6 @@ export class BackgroundWorkflowCoordinator {
     }
 
     accepted = true;
-    this.updateBackgroundSurface(input.ctx);
     scheduleDelivery();
   }
 
@@ -145,9 +139,8 @@ export class BackgroundWorkflowCoordinator {
     );
   }
 
-  onRunSettled(listener: BackgroundWorkflowSettledListener): () => void {
-    this.settledListeners.add(listener);
-    return () => this.settledListeners.delete(listener);
+  onRunSettled(listener: BackgroundWorkflowSettledListener): void {
+    this.settledListener = listener;
   }
 
   async stop(ctx: ExtensionContext, runId: string): Promise<WorkflowRunRecord> {
@@ -243,7 +236,6 @@ export class BackgroundWorkflowCoordinator {
         this.log(`[workflow:${runId}] failed to force paused state during shutdown: ${unknownErrorMessage(error)}`);
       }
     }
-    if (ctx.hasUI) ctx.ui.setWidget(BACKGROUND_WIDGET_KEY, undefined);
   }
 
   private async queueOrDeliver(ctx: ExtensionContext, runId: string): Promise<void> {
@@ -262,12 +254,10 @@ export class BackgroundWorkflowCoordinator {
   }
 
   private async notifyRunSettled(ctx: ExtensionContext, runId: string): Promise<void> {
-    for (const listener of this.settledListeners) {
-      try {
-        await listener(ctx, runId);
-      } catch (error) {
-        this.log(`[workflow:${runId}] background settlement listener failed: ${unknownErrorMessage(error)}`);
-      }
+    try {
+      await this.settledListener?.(ctx, runId);
+    } catch (error) {
+      this.log(`[workflow:${runId}] background settlement listener failed: ${unknownErrorMessage(error)}`);
     }
   }
 
@@ -292,23 +282,6 @@ export class BackgroundWorkflowCoordinator {
     this.pendingDelivery.set(sessionId, pending);
   }
 
-  private updateBackgroundSurface(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    const sessionId = ctx.sessionManager.getSessionId();
-    const runs = [...this.active.entries()]
-      .filter(([, run]) => run.sessionId === sessionId)
-      .map(([runId, run]) => ({ runId, name: run.name }));
-    if (runs.length === 0) {
-      ctx.ui.setWidget(BACKGROUND_WIDGET_KEY, undefined);
-      return;
-    }
-    ctx.ui.setWidget(
-      BACKGROUND_WIDGET_KEY,
-      [formatBackgroundActivity(runs, ctx.ui.theme)],
-      { placement: "aboveEditor" },
-    );
-  }
-
   private async deliver(ctx: ExtensionContext, runId: string): Promise<boolean> {
     const store = this.storeForCwd(ctx.cwd);
     const record = await store.load(runId);
@@ -333,25 +306,18 @@ export class BackgroundWorkflowCoordinator {
   }
 }
 
-function formatBackgroundActivity(
-  runs: readonly { readonly runId: string; readonly name: string }[],
-  theme: ExtensionContext["ui"]["theme"],
-): string {
-  const visible = runs.slice(0, 2).map((run) => `${run.name} ${run.runId.slice(0, 8)}`);
-  const hidden = runs.length - visible.length;
-  const suffix = hidden > 0 ? ` · +${hidden} more` : "";
-  return `${theme.fg("accent", "●")} ${theme.bold("Background workflows")} ${theme.fg("dim", `· ${visible.join(" · ")}${suffix}`)}`;
-}
-
 export function backgroundOrigin(ctx: Pick<ExtensionContext, "sessionManager">, requestedAt = Date.now()): WorkflowBackgroundOrigin {
   return { sessionId: ctx.sessionManager.getSessionId(), requestedAt };
 }
 
 export function backgroundResultDetails(record: WorkflowRunRecord): BackgroundWorkflowResultDetails {
   if (!isDeliverableState(record.state)) throw new Error(`Workflow run ${record.runId} has not finished or paused.`);
+  const summary = backgroundSummary(record);
   return {
     name: record.workflow.name,
-    result: { summary: backgroundSummary(record) },
+    result: record.state === "completed" && record.result.kind === "value" ? record.result.value : { summary },
+    summary,
+    startedAt: record.startedAt,
     completedAt: record.endedAt ?? record.updatedAt,
     usage: record.usage,
     runId: record.runId,
@@ -362,14 +328,12 @@ export function backgroundResultDetails(record: WorkflowRunRecord): BackgroundWo
 }
 
 function backgroundSummary(record: WorkflowRunRecord): string {
-  if (record.state !== "completed") return boundedSummary(`Workflow ${record.state}: ${record.message}`);
+  if (record.state !== "completed") return truncateText(`Workflow ${record.state}: ${record.message}`, SUMMARY_LIMIT);
   if (record.result.kind === "unavailable") {
-    return boundedSummary(`Workflow completed; retained result is unavailable: ${record.result.reason}`);
+    return truncateText(`Workflow completed; retained result is unavailable: ${record.result.reason}`, SUMMARY_LIMIT);
   }
-  const value = record.result.value;
-  if (typeof value === "string") return boundedSummary(value);
-  if (isRecord(value) && typeof value.summary === "string") return boundedSummary(value.summary);
-  return "Workflow completed. Open run history for the retained result.";
+  const summary = workflowResultSummary(record.result.value);
+  return summary === undefined ? "Workflow completed. Open run history for the retained result." : truncateText(summary, SUMMARY_LIMIT);
 }
 
 function formatBackgroundDelivery(details: BackgroundWorkflowResultDetails): string {
@@ -379,7 +343,7 @@ function formatBackgroundDelivery(details: BackgroundWorkflowResultDetails): str
     `Run ID: ${details.runId}`,
     `State: ${details.status}`,
     "",
-    details.result.summary,
+    details.summary,
   ].join("\n");
 }
 
@@ -404,7 +368,7 @@ function isDeliverableState(state: WorkflowRunState): state is "completed" | "fa
 async function markDelivery(
   store: WorkflowRunStore,
   runId: string,
-  delivery: Parameters<typeof updateWorkflowRunDelivery>[1],
+  delivery: WorkflowRunDelivery,
 ): Promise<void> {
   const latest = await store.load(runId);
   if (!latest?.background || latest.background.delivery.state !== "pending") return;
@@ -424,16 +388,7 @@ async function forcePausedRecord(store: WorkflowRunStore, runId: string): Promis
 async function forceStoppedRecord(store: WorkflowRunStore, runId: string): Promise<void> {
   const record = await store.load(runId);
   if (!record || (record.state !== "queued" && record.state !== "running")) return;
-  await store.save(transitionWorkflowRun(record, {
-    state: "stopped",
-    progress: record.progress,
-    usage: record.usage ?? record.progress.usage ?? {
-      agents: [],
-      totals: emptyWorkflowUsageTotals(),
-      assistantMessages: 0,
-    },
-    error: new WorkflowAbortError("Workflow stopped by user."),
-  }));
+  await store.save(stopWorkflowRunRecord(record));
 }
 
 async function reconcileInterruptedRun(
@@ -482,11 +437,3 @@ async function waitForRuns(runs: readonly Promise<void>[], timeoutMs: number): P
     if (timer) clearTimeout(timer);
   }
 }
-
-function boundedSummary(value: string): string {
-  return value.length <= SUMMARY_LIMIT ? value : `${value.slice(0, SUMMARY_LIMIT - 1)}…`;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

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

@@ -27,7 +27,7 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
 export function isFatalWorkflowError(error: unknown, signal: AbortSignal | undefined): boolean {
   if (signal?.aborted) return true;
   if (safeInstanceOf(error, WorkflowAbortError)) return true;
-  if (typeof DOMException !== "undefined" && safeInstanceOf(error, DOMException)) {
+  if (safeInstanceOf(error, DOMException)) {
     try {
       return error.name === "AbortError";
     } catch {
@@ -67,10 +67,6 @@ export async function raceWithAbort<T>(operation: () => Promise<T>, signal: Abor
     };
     const onAbort = () => finish(() => reject(abortReason(signal)));
     signal.addEventListener("abort", onAbort, { once: true });
-    if (signal.aborted) {
-      onAbort();
-      return;
-    }
     void operation().then(
       (value) => finish(() => resolve(value)),
       (error: unknown) => finish(() => reject(error)),

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

@@ -1,5 +1,6 @@
 import { performance } from "node:perf_hooks";
 import { abortReason, isFatalWorkflowError, throwIfAborted } from "./cancellation.ts";
+import { isFiniteNumber } from "./guards.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
 /**
@@ -14,22 +15,28 @@ export class Semaphore {
   private active = 0;
   private readonly waiters: Array<() => void> = [];
 
-  constructor(private readonly max: number) {}
+  constructor(private readonly max: number) {
+    if (!Number.isInteger(max) || max < 1) throw new RangeError("Semaphore capacity must be a positive integer");
+  }
 
   async run<T>(fn: () => Promise<T>, options: { onQueueWaitMs?: (durationMs: number) => void; signal?: AbortSignal } = {}): Promise<T> {
     throwIfAborted(options.signal);
     const queuedAt = performance.now();
     if (this.active >= this.max) {
       await this.waitForSlot(options.signal);
+    } else {
+      this.active++;
     }
-    options.onQueueWaitMs?.(performance.now() - queuedAt);
-    throwIfAborted(options.signal);
-    this.active++;
     try {
+      options.onQueueWaitMs?.(performance.now() - queuedAt);
+      throwIfAborted(options.signal);
       return await fn();
     } finally {
-      this.active--;
-      this.waiters.shift()?.();
+      // Transfer ownership directly. A selected waiter owns this reservation
+      // even before its continuation runs, including if it is then cancelled.
+      const next = this.waiters.shift();
+      if (next) next();
+      else this.active--;
     }
   }
 
@@ -53,10 +60,6 @@ export class Semaphore {
         cleanup();
         reject(abortReason(signal));
       };
-      if (signal?.aborted) {
-        reject(abortReason(signal));
-        return;
-      }
       this.waiters.push(waiter);
       signal?.addEventListener("abort", onAbort, { once: true });
     });
@@ -132,13 +135,6 @@ export async function parallel<T>(
 }
 
 export function bindParallel(options: ParallelOptions): WorkflowParallel {
-  const executionOptions: ParallelOptions = {
-    signal: options.signal,
-    abortController: options.abortController,
-    limit: options.limit,
-    drainTimeoutMs: options.drainTimeoutMs,
-  };
-
   function boundParallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
   function boundParallel<T>(
     thunks: Array<() => Promise<T>>,
@@ -149,9 +145,9 @@ export function bindParallel(options: ParallelOptions): WorkflowParallel {
     workflowOptions?: ParallelSettledOptions,
   ): Promise<Array<T | null> | Array<ParallelSettledResult<T>>> {
     if (workflowOptions?.settled) {
-      return await parallel(thunks, { ...executionOptions, settled: true });
+      return await parallel(thunks, { ...options, settled: true });
     }
-    return await parallel(thunks, executionOptions);
+    return await parallel(thunks, options);
   }
 
   return boundParallel;
@@ -218,7 +214,6 @@ async function runParallel<T, Result>(
     };
 
     options.signal?.addEventListener("abort", onAbort, { once: true });
-    if (options.signal?.aborted) onAbort();
     for (let worker = 0; worker < limit; worker++) {
       void runWorker().then(completeWorker, (error) => {
         recordFatalFailure(error);
@@ -258,7 +253,7 @@ function readSerializableDetails(
         typeof detail === "string" ||
         typeof detail === "boolean" ||
         detail === null ||
-        (typeof detail === "number" && Number.isFinite(detail))
+        isFiniteNumber(detail)
       ) {
         details[key] = detail;
       }
@@ -279,12 +274,12 @@ function readProperty(value: unknown, property: string): unknown {
 }
 
 function normalizeLimit(limit: number | undefined, itemCount: number): number {
-  if (limit === undefined || !Number.isFinite(limit)) return Math.max(1, itemCount);
+  if (!isFiniteNumber(limit)) return Math.max(1, itemCount);
   return Math.max(1, Math.min(itemCount, Math.trunc(limit)));
 }
 
 function normalizeDrainTimeout(timeoutMs: number | undefined): number {
-  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) return DEFAULT_FATAL_DRAIN_TIMEOUT_MS;
+  if (!isFiniteNumber(timeoutMs)) return DEFAULT_FATAL_DRAIN_TIMEOUT_MS;
   return Math.max(0, Math.trunc(timeoutMs));
 }
 
@@ -296,48 +291,7 @@ function normalizeDrainTimeout(timeoutMs: number | undefined): number {
  *
  * Each stage receives (previousResult, originalItem, index).
  */
-export async function pipeline<Item, A>(
-  items: readonly Item[],
-  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
-): Promise<Array<A | null>>;
-export async function pipeline<Item, A, B>(
-  items: readonly Item[],
-  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
-  stage2: (prev: A, item: Item, index: number) => Promise<B>,
-): Promise<Array<B | null>>;
-export async function pipeline<Item, A, B, C>(
-  items: readonly Item[],
-  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
-  stage2: (prev: A, item: Item, index: number) => Promise<B>,
-  stage3: (prev: B, item: Item, index: number) => Promise<C>,
-): Promise<Array<C | null>>;
-export async function pipeline<Item, A, B, C, D>(
-  items: readonly Item[],
-  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
-  stage2: (prev: A, item: Item, index: number) => Promise<B>,
-  stage3: (prev: B, item: Item, index: number) => Promise<C>,
-  stage4: (prev: C, item: Item, index: number) => Promise<D>,
-): Promise<Array<D | null>>;
-export async function pipeline<Item, A, B, C, D, E>(
-  items: readonly Item[],
-  stage1: (prev: Item, item: Item, index: number) => Promise<A>,
-  stage2: (prev: A, item: Item, index: number) => Promise<B>,
-  stage3: (prev: B, item: Item, index: number) => Promise<C>,
-  stage4: (prev: C, item: Item, index: number) => Promise<D>,
-  stage5: (prev: D, item: Item, index: number) => Promise<E>,
-): Promise<Array<E | null>>;
-export async function pipeline(
-  items: readonly unknown[],
-  ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
-): Promise<Array<unknown | null>>;
-export async function pipeline(
-  items: readonly unknown[],
-  ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
-): Promise<Array<unknown | null>> {
-  return pipelineWithOptions(items, stages);
-}
-
-export function bindPipeline(options: PipelineOptions): Pipeline {
+export function bindPipeline(options: PipelineOptions) {
   async function boundPipeline<Item, A>(
     items: readonly Item[],
     stage1: (prev: Item, item: Item, index: number) => Promise<A>,
@@ -368,33 +322,30 @@ export function bindPipeline(options: PipelineOptions): Pipeline {
     stage4: (prev: C, item: Item, index: number) => Promise<D>,
     stage5: (prev: D, item: Item, index: number) => Promise<E>,
   ): Promise<Array<E | null>>;
+  async function boundPipeline(
+    items: readonly unknown[],
+    ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
+  ): Promise<Array<unknown | null>>;
   async function boundPipeline(
     items: readonly unknown[],
     ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
   ): Promise<Array<unknown | null>> {
-    return pipelineWithOptions(items, stages, options);
+    return await parallel(
+      items.map((item, index) => async () => {
+        let acc: unknown = item;
+        for (const stage of stages) {
+          throwIfAborted(options.signal);
+          acc = await stage(acc, item, index);
+        }
+        return acc;
+      }),
+      options,
+    );
   }
   return boundPipeline;
 }
 
-export async function pipelineWithOptions(
-  items: readonly unknown[],
-  stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>,
-  options: PipelineOptions = {},
-): Promise<Array<unknown | null>> {
-  throwIfAborted(options.signal);
-  return await parallel(
-    items.map((item, index) => async () => {
-      throwIfAborted(options.signal);
-      let acc: unknown = item;
-      for (const stage of stages) {
-        throwIfAborted(options.signal);
-        acc = await stage(acc, item, index);
-      }
-      return acc;
-    }),
-    options,
-  );
-}
+export type Pipeline = ReturnType<typeof bindPipeline>;
 
-export type Pipeline = typeof pipeline;
+/** `pipeline` without a run's abort signal (tests, benchmarks). */
+export const pipeline: Pipeline = bindPipeline({});

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

@@ -1,13 +1,12 @@
 import { readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { LoadedWorkflow, WorkflowSourceIdentity } from "./types.ts";
 import type { PerfSink } from "./perf.ts";
 import { loadWorkflow, parseWorkflowModule } from "./workflow-module.ts";
 import { BUILTIN_SOURCE_ROOT, BUILTIN_WORKFLOW_DEFINITIONS, BUILTIN_WORKFLOW_FILES } from "./workflows.ts";
-import { captureTreeFingerprint } from "./tree-fingerprint.ts";
-import { FINGERPRINT_EXCLUDED_RELATIVE_PATHS } from "./resume-context.ts";
+import { captureSourceTreeFingerprint, type FingerprintCapture } from "./tree-fingerprint.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
 export interface DiscoverWorkflowsOptions {
@@ -16,16 +15,13 @@ export interface DiscoverWorkflowsOptions {
   readonly userWorkflowDir?: string;
 }
 
-const DISCOVERY_FINGERPRINT_MAX_BYTES = 32 << 20;
-const DISCOVERY_FINGERPRINT_MAX_FILES = 4096;
-
 const discoveryCache = new Map<string, Map<string, LoadedWorkflow>>();
 /** Best-effort dynamic load of every `*.ts` workflow in a directory. */
 async function loadDir(
   dir: string,
   sourceIdentity: (path: string) => WorkflowSourceIdentity,
   excludeFiles: ReadonlySet<string> = new Set(),
-  provenanceRoot?: string,
+  captureProvenance?: () => Promise<FingerprintCapture>,
 ): Promise<LoadedWorkflow[]> {
   let entries: string[];
   try {
@@ -33,12 +29,15 @@ async function loadDir(
   } catch {
     return [];
   }
+  const candidates = entries.filter(
+    (name) => !excludeFiles.has(name) && name.endsWith(".ts") && !name.startsWith("_") && !name.startsWith("."),
+  );
+  // The shipped workflows/ dir holds only excluded built-ins; skip the tree hash when nothing will be imported.
+  if (candidates.length === 0) return [];
 
-  const before = provenanceRoot ? await captureDiscoveryFingerprint(provenanceRoot) : undefined;
+  const before = await captureProvenance?.();
   const modules: Array<{ readonly path: string; readonly module: Parameters<typeof loadWorkflow>[0] }> = [];
-  for (const name of entries) {
-    if (excludeFiles.has(name)) continue;
-    if (!name.endsWith(".ts") || name.startsWith("_") || name.startsWith(".")) continue;
+  for (const name of candidates) {
     try {
       const path = join(dir, name);
       const importUrl = pathToFileURL(path);
@@ -56,15 +55,6 @@ async function loadDir(
   return modules.map(({ path, module }) => loadWorkflow(module, sourceIdentity(path)));
 }
 
-async function captureDiscoveryFingerprint(root: string) {
-  return await captureTreeFingerprint({
-    root,
-    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
-    maxBytes: DISCOVERY_FINGERPRINT_MAX_BYTES,
-    maxFiles: DISCOVERY_FINGERPRINT_MAX_FILES,
-  });
-}
-
 /**
  * All available workflows by name. Static registry wins on name collisions, so the
  * bundled example is always the verified one even if a same-named file is dropped in.
@@ -80,14 +70,14 @@ export async function discoverWorkflows(repoDir: string, options: DiscoverWorkfl
 
   const byName = await timed(options.perf, "discovery.total_ms", async () => {
     const next = new Map<string, LoadedWorkflow>();
-    const builtinSource = await captureDiscoveryFingerprint(BUILTIN_SOURCE_ROOT);
+    const builtinSource = await captureSourceTreeFingerprint(BUILTIN_SOURCE_ROOT);
     for (const definition of BUILTIN_WORKFLOW_DEFINITIONS) {
       const source: WorkflowSourceIdentity =
         builtinSource.kind === "verified"
           ? {
               kind: "file",
               path: definition.path,
-              root: definition.root,
+              root: BUILTIN_SOURCE_ROOT,
               fingerprint: builtinSource.fingerprint,
             }
           : {
@@ -98,6 +88,9 @@ export async function discoverWorkflows(repoDir: string, options: DiscoverWorkfl
     }
 
     const repoWorkflowDir = join(repoDir, "workflows");
+    // The shipped extension dir is both the built-in root and the drop-in root; hash that tree once.
+    const repoProvenance =
+      resolve(repoDir) === resolve(BUILTIN_SOURCE_ROOT) ? async () => builtinSource : () => captureSourceTreeFingerprint(repoDir);
     const [repoDynamic, userDynamic] = await Promise.all([
       timed(options.perf, "discovery.repo_dir_ms", () =>
         loadDir(
@@ -107,7 +100,7 @@ export async function discoverWorkflows(repoDir: string, options: DiscoverWorkfl
             reason: "dynamic workflow module graphs are not loaded from an immutable source snapshot",
           }),
           BUILTIN_WORKFLOW_FILES,
-          repoDir,
+          repoProvenance,
         ),
       ),
       timed(options.perf, "discovery.user_dir_ms", () =>

package/.pi/extensions/pi-workflow-engine/src/dynamax-shortcuts.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Key, type KeyId } from "@earendil-works/pi-tui";
+import { isRecord } from "./guards.ts";
 
 export const DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT = "ctrl+shift+m" satisfies KeyId;
 export const DEFAULT_REVIEW_RESULTS_SHORTCUT = "ctrl+shift+r" satisfies KeyId;
@@ -112,10 +113,6 @@ function defaultDynamaxShortcuts(): DynamaxShortcuts {
   return { inspector: DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT, results: DEFAULT_REVIEW_RESULTS_SHORTCUT };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function warnUsingDefaults(reason: "Could not read" | "Invalid", configPath: string): void {
   console.warn(`${reason} pi-workflow-engine config at ${configPath}; using default workflow shortcuts.`);
 }