pi-workflow-engine 1.1.0 → 1.2.0

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

@@ -1,8 +1,10 @@
-import { CustomEditor, type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import { CustomEditor, type BeforeAgentStartEvent, type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
 import type { EditorComponent } from "@earendil-works/pi-tui";
 import { completeCurrentArgument } from "./command-completions.ts";
 import type { DynamaxShortcuts } from "./dynamax-shortcuts.ts";
+import { appendSectionToForcedPrompt } from "./prompt-sections.ts";
 import { sessionKey } from "./session-identity.ts";
+import { WORKFLOW_TOOL_NAME } from "./types.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import { dot, GLYPH } from "./ui/kit.ts";
 import { setWorkflowInspectorShortcut } from "./ui/workflow-widget.ts";
@@ -20,8 +22,19 @@ export interface DynamaxState {
   turnActive: boolean;
 }
 
+/** The output-token pool a `+500k`-style directive in the user's prompt sets for that turn's workflow runs. */
+export interface DynamaxTurnBudget {
+  readonly total: number;
+  /** Tokens not yet spent by this turn's synchronous runs; never negative. */
+  remaining(): number;
+  /** Count a finished synchronous run's output tokens against the pool. */
+  spend(outputTokens: number): void;
+}
+
 export interface DynamaxRuntime {
   state: DynamaxState;
+  /** Set by a budget directive in a user prompt, cleared when that run settles. */
+  turnBudget?: DynamaxTurnBudget;
 }
 
 export type DynamaxRuntimeStore = Map<string, DynamaxRuntime>;
@@ -35,9 +48,18 @@ export interface DynamaxRegistrationOptions {
 export interface DynamaxHandle {
   /** Opt the next agent run in. The `input` hook ignores prompts this extension sends (pi tags them `source: "extension"`). */
   markOneShot(ctx: ExtensionContext): void;
+  /** The current turn's output-token pool, when the user's prompt set one. */
+  turnBudget(ctx: ExtensionContext): DynamaxTurnBudget | undefined;
+  /** Whether Dynamax covers this session now: sticky, a pending one-shot, or a one-shot turn in progress. */
+  isActive(ctx: ExtensionContext): boolean;
 }
 
 export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/i;
+/** `+500k`, `+1.5m`, `+2M`, `+250000`: after the start or whitespace, before the end, whitespace, or punctuation. */
+export const BUDGET_DIRECTIVE_PATTERN = /(?:^|\s)\+(\d+(?:\.\d+)?)([km]?)(?=$|\s|[.,;:!?)\]}"'])/i;
+/** Smaller values are ignored, so a `+1` or `+2` in ordinary prose never caps a run at a few tokens. */
+export const BUDGET_DIRECTIVE_MIN_TOKENS = 1_000;
+const BUDGET_DIRECTIVE_MULTIPLIERS: Readonly<Record<string, number>> = { "": 1, k: 1_000, m: 1_000_000 };
 export const DYNAMAX_STATUS_KEY = "dynamax";
 
 type EditorFactory = NonNullable<ReturnType<ExtensionContext["ui"]["getEditorComponent"]>>;
@@ -53,29 +75,31 @@ function disposeDynamaxDecorations(decorations: Set<DynamaxEditorDecoration>): v
   decorations.clear();
 }
 
+/** With no argument the command toggles sticky mode, so these name only the explicit forms. */
 const DYNAMAX_ACTION_COMPLETIONS = [
-  { value: "on", description: "Keep Dynamax enabled for this session" },
+  { value: "on", description: "Make workflow orchestration the default for this session" },
   { value: "off", description: "Disable sticky and pending Dynamax modes" },
   { value: "status", description: "Show the current Dynamax state" },
 ] as const;
 
-export const ADAPTIVE_WORKFLOW_GUIDANCE = `
-Adaptive multi-pass workflows are optional. Use a simple single-pass fan-out when it is sufficient. When the first pass may expose gaps, conflicts, weak claims, or missing evidence:
-- run the bounded first-pass agents;
-- give their surviving results to a structured gap-analysis agent so the LLM decides what needs follow-up;
-- put a hard maxItems bound on LLM-authored task arrays and defensively slice them before fan-out;
-- use ordinary TypeScript conditionals or bounded loops to launch follow-up agents only when gaps exist;
-- synthesize the first-pass and follow-up results together.
-Do not generate a second pass when the first pass is sufficient, and do not invent iteration, quorum, graph, reduction, or retry primitives for this pattern.`;
-
 /** System prompt section pi wraps as `<dynamax>`; adding or dropping it appends a section patch instead of rewriting the prompt. */
 export const DYNAMAX_SECTION = "dynamax";
 
-/** Only the opt-in itself: the authoring rules already reach the model as the workflow tool's guidelines. */
+/**
+ * Only the opt-in itself: the workflow tool's guidelines send the model to the workflow-authoring
+ * skill, which carries the authoring rules and patterns.
+ */
 export const DYNAMAX_REMINDER =
   "The user opted into dynamax multi-agent orchestration for this request, so the workflow tool is permitted. " +
   "Run a registered workflow by name, or author an inline workflow script when none fits, following the workflow tool's guidelines.";
 
+/** Sticky mode is a standing default for the session, not a one-request permission. */
+export const DYNAMAX_STICKY_REMINDER =
+  "Dynamax is on for this session. Orchestrate every substantive task with the workflow tool by default: " +
+  "scout inline first to find the work list, then run one single-phase workflow per phase (understand, design, implement, review) " +
+  "and read each result before choosing the next. Lean toward adversarial verification of findings. " +
+  "Work without a workflow only for conversational turns and trivial or already-verified edits.";
+
 export function createDynamaxState(): DynamaxState {
   return { sticky: false, oneShotPending: false, turnActive: false };
 }
@@ -97,6 +121,48 @@ export function hasDynamaxToken(text: string): boolean {
   return DYNAMAX_TOKEN_PATTERN.test(text);
 }
 
+/** The output tokens the first budget directive in `text` asks for, if any. */
+export function parseBudgetDirective(text: string): number | undefined {
+  const match = BUDGET_DIRECTIVE_PATTERN.exec(text);
+  if (!match) return undefined;
+  const multiplier = BUDGET_DIRECTIVE_MULTIPLIERS[(match[2] ?? "").toLowerCase()] ?? 1;
+  // Round, not floor: 2.3 * 1000 is 2299.999... in floating point.
+  const tokens = Math.round(Number(match[1]) * multiplier);
+  return Number.isSafeInteger(tokens) && tokens >= BUDGET_DIRECTIVE_MIN_TOKENS ? tokens : undefined;
+}
+
+export function createDynamaxTurnBudget(total: number): DynamaxTurnBudget {
+  let spent = 0;
+  return {
+    total,
+    remaining: () => Math.max(0, total - spent),
+    spend(outputTokens) {
+      if (Number.isFinite(outputTokens) && outputTokens > 0) spent += outputTokens;
+    },
+  };
+}
+
+export type DynamaxTurnBudgetResolution =
+  | { readonly kind: "budget"; readonly budget: number | undefined }
+  | { readonly kind: "spent"; readonly total: number };
+
+/**
+ * A run's budget. Without a turn pool it is the explicit one, if any. The user's pool caps every run in
+ * its turn: the remainder, clamped to the run budget range, is the budget, and an explicit one can only
+ * lower it. A pool with less than `min` left is spent.
+ */
+export function resolveTurnBudget(
+  explicit: number | undefined,
+  pool: DynamaxTurnBudget | undefined,
+  range: { readonly min: number; readonly max: number },
+): DynamaxTurnBudgetResolution {
+  if (pool === undefined) return { kind: "budget", budget: explicit };
+  const remaining = pool.remaining();
+  if (remaining < range.min) return { kind: "spent", total: pool.total };
+  const cap = Math.min(range.max, Math.floor(remaining));
+  return { kind: "budget", budget: explicit === undefined ? cap : Math.min(explicit, cap) };
+}
+
 export function markDynamaxOneShot(state: DynamaxState): void {
   state.oneShotPending = true;
 }
@@ -136,12 +202,21 @@ export function dynamaxStatusText(state: DynamaxState, theme: Theme): string {
 /**
  * Add the opt-in section for this run and consume a pending one-shot. pi rebuilds `sections` for every
  * run, so an inactive run simply leaves it out and pi records the removal as a patch.
+ *
+ * Sticky mode covers every run, including one a custom message started (`sendMessage` with
+ * `triggerTurn`, such as a background completion). Only a user prompt consumes the one-shot: the
+ * opt-in belongs to the request the user typed it in.
  */
-export function applyDynamaxPromptSection(sections: Record<string, string>, state: DynamaxState): boolean {
-  if (!state.sticky && !state.oneShotPending) return false;
-  state.oneShotPending = false;
+export function applyDynamaxPromptSection(
+  sections: Record<string, string>,
+  state: DynamaxState,
+  messageType: BeforeAgentStartEvent["messageType"] = "user",
+): boolean {
+  const oneShot = messageType === "user" && state.oneShotPending;
+  if (!state.sticky && !oneShot) return false;
+  if (oneShot) state.oneShotPending = false;
   state.turnActive = true;
-  sections[DYNAMAX_SECTION] = DYNAMAX_REMINDER;
+  sections[DYNAMAX_SECTION] = state.sticky ? DYNAMAX_STICKY_REMINDER : DYNAMAX_REMINDER;
   return true;
 }
 
@@ -230,23 +305,30 @@ export function registerDynamax(pi: ExtensionAPI, shortcuts: DynamaxShortcuts, o
   });
 
   pi.on("input", (event, ctx) => {
-    if (event.source !== "extension" && hasDynamaxToken(event.text)) markOneShot(ctx);
+    if (event.source === "extension") return { action: "continue" };
+    if (hasDynamaxToken(event.text)) markOneShot(ctx);
+    const budget = parseBudgetDirective(event.text);
+    if (budget !== undefined) getDynamaxRuntime(runtimes, ctx).turnBudget = createDynamaxTurnBudget(budget);
     return { action: "continue" };
   });
 
   pi.on("before_agent_start", (event, ctx) => {
-    const runtime = getDynamaxRuntime(runtimes, ctx);
     const options = event.systemPromptOptions;
-    if (!applyDynamaxPromptSection(options.sections, runtime.state)) return undefined;
+    // Subagent sessions load this extension but withhold the workflow tool, so a `dynamax` in a
+    // subagent prompt must neither permit that tool nor consume the one-shot.
+    if (!options.selectedTools.includes(WORKFLOW_TOOL_NAME)) return undefined;
+    const runtime = getDynamaxRuntime(runtimes, ctx);
+    if (!applyDynamaxPromptSection(options.sections, runtime.state, event.messageType)) return undefined;
     updateDynamaxSurfaces(ctx, runtime);
-    // An earlier extension forced the whole prompt, and pi renders no sections then; append to its text instead.
-    if (options.forceSystemPrompt === undefined) return undefined;
-    return { systemPrompt: `${options.forceSystemPrompt}\n\n<${DYNAMAX_SECTION}>\n${DYNAMAX_REMINDER}\n</${DYNAMAX_SECTION}>` };
+    return appendSectionToForcedPrompt(options, DYNAMAX_SECTION);
   });
 
-  pi.on("agent_end", (_event, ctx) => {
+  // Not agent_end: pi emits that per agent loop, and one run continues in fresh loops after a
+  // provider retry, overflow compaction, or queued follow-up. agent_settled fires once per run.
+  pi.on("agent_settled", (_event, ctx) => {
     const runtime = getDynamaxRuntime(runtimes, ctx);
     if (!runtime.state.sticky) runtime.state.turnActive = false;
+    runtime.turnBudget = undefined;
     updateDynamaxSurfaces(ctx, runtime);
   });
 
@@ -260,15 +342,12 @@ export function registerDynamax(pi: ExtensionAPI, shortcuts: DynamaxShortcuts, o
   }
 
   pi.registerCommand("workflow:dynamax", {
-    description: "Toggle Dynamax workflow orchestration: /workflow:dynamax [on|off|status]",
+    description: "Toggle sticky Dynamax orchestration for this session: /workflow:dynamax [on|off|status]",
     getArgumentCompletions: (argumentPrefix) => completeCurrentArgument(argumentPrefix, DYNAMAX_ACTION_COMPLETIONS),
     handler: async (args, ctx) => {
       const runtime = getDynamaxRuntime(runtimes, ctx);
-      const action = args.trim().toLowerCase();
-      if (action === "") {
-        ctx.ui.notify(`Dynamax ${describeDynamaxState(runtime.state)}. Usage: /workflow:dynamax [on|off|status]`, "info");
-        return;
-      }
+      const typed = args.trim().toLowerCase();
+      const action = typed === "" ? (runtime.state.sticky ? "off" : "on") : typed;
       if (action === "on") {
         enableDynamaxSticky(runtime.state);
         updateDynamaxSurfaces(ctx, runtime);
@@ -285,11 +364,15 @@ export function registerDynamax(pi: ExtensionAPI, shortcuts: DynamaxShortcuts, o
         ctx.ui.notify(`Dynamax ${describeDynamaxState(runtime.state)}`, "info");
         return;
       }
-      ctx.ui.notify("Usage: /workflow:dynamax [on|off|status]", "warning");
+      ctx.ui.notify("Usage: /workflow:dynamax [on|off|status] (no argument toggles sticky mode)", "warning");
     },
   });
 
-  return { markOneShot };
+  return {
+    markOneShot,
+    turnBudget: (ctx) => getDynamaxRuntime(runtimes, ctx).turnBudget,
+    isActive: (ctx) => isDynamaxActive(getDynamaxRuntime(runtimes, ctx).state),
+  };
 }
 
 export function updateDynamaxSurfaces(ctx: Pick<ExtensionContext, "hasUI" | "ui">, runtime: DynamaxRuntime): void {

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

@@ -15,11 +15,12 @@ import {
   resolveWorkflowRunOptions,
   type ResolvedWorkflowRunOptions,
 } from "./options.ts";
-import type { AgentOptions, IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
+import type { AgentOptions, IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowMeta, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { showWorkflowInspector } from "./ui/workflow-inspector.ts";
 import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
 import { WorktreeRegistry } from "./worktree.ts";
 import { runFinalizers } from "./finalizers.ts";
+import { workflowArgsText, workflowInputPresent } from "./workflow-input.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   captureWorkflowResumeContext,
@@ -27,11 +28,14 @@ import {
 } from "./resume-context.ts";
 import {
   DurableWorkflowRun,
+  persistWorkflowRunScript,
   ProjectWorkflowRunStore,
   workflowRunRecordPath,
   type WorkflowRunStore,
 } from "./workflow-run-store.ts";
 import { createWorkflowRunRecord } from "./workflow-run-record.ts";
+import { canRelaunchWorkflowRun } from "./workflow-run-history.ts";
+import { sealWorkflowRunScript } from "./workflow-run-seal.ts";
 import {
   createProviderUsageLimitPauseRecord,
   WorkflowProviderUsageLimitError,
@@ -76,22 +80,23 @@ export interface WorkflowEngineDependencies {
 /**
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
  * to a shared semaphore + progress tracker), invoke the workflow, return its result.
+ * `input` is a slash command's argument string or a tool call's JSON value.
  */
 export async function runWorkflow(
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   options: WorkflowRunOptions = {},
   dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
-  return await runResolvedWorkflow(ctx, mod, args, resolveWorkflowRunOptions(options), dependencies);
+  return await runResolvedWorkflow(ctx, mod, input, resolveWorkflowRunOptions(options), dependencies);
 }
 
 /** Execute an options-normalized workflow without re-reading environment defaults. */
 export async function runResolvedWorkflow(
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   resolvedOptions: ResolvedWorkflowRunOptions,
   dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
@@ -107,16 +112,20 @@ export async function runResolvedWorkflow(
   const journalPath = workflowJournalPath(ctx.cwd, runId);
   const resumePath = resolvedOptions.resumeFromRunId ? workflowJournalPath(ctx.cwd, resolvedOptions.resumeFromRunId) : undefined;
   const runStore = new ProjectWorkflowRunStore(ctx.cwd);
+  const script = await sealRunScript(ctx.cwd, runId, mod);
   let persistenceFailureReported = false;
+  const initialRecord = createWorkflowRunRecord({
+    runId,
+    workflow: mod,
+    options: resolvedOptions,
+    progress: progress.snapshot(),
+    argumentsPresent: workflowInputPresent(input),
+    scriptPersisted: script.path !== undefined,
+    scriptSeal: script.seal,
+  });
   const durableRun = new DurableWorkflowRun(
     runStore,
-    createWorkflowRunRecord({
-      runId,
-      workflow: mod,
-      options: resolvedOptions,
-      progress: progress.snapshot(),
-      argumentsPresent: args.length > 0,
-    }),
+    initialRecord,
     (error) => {
       if (persistenceFailureReported) return;
       persistenceFailureReported = true;
@@ -124,7 +133,11 @@ export async function runResolvedWorkflow(
     },
   );
   durableProgress = durableRun;
-  const progressSource = { snapshot: () => progress.snapshot(), state: () => durableRun.state };
+  const progressSource = {
+    snapshot: () => progress.snapshot(),
+    state: () => durableRun.state,
+    skipAgent: (agentId: number) => progress.skipAgent(agentId),
+  };
   const worktrees = dependencies.worktrees ?? new WorktreeRegistry(ctx.cwd);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
@@ -132,7 +145,7 @@ export async function runResolvedWorkflow(
   const workflowOutcome = await captureOutcome(async () => {
     await notifyLifecycleObserver(progress, "progress source callback", () => resolvedOptions.onProgressSource?.(progressSource));
     if (resolvedOptions.inspect && ctx.hasUI && ctx.mode === "tui") {
-      void showWorkflowInspector(ctx.ui, progressSource.snapshot, () => ({ state: progressSource.state() }))
+      void showWorkflowInspector(ctx.ui, progressSource.snapshot, () => ({ state: progressSource.state() }), progressSource)
         .catch((error: unknown) => {
           try {
             progress.log(`inspector failed: ${unknownErrorMessage(error)}`);
@@ -151,6 +164,7 @@ export async function runResolvedWorkflow(
         resumedFromRunId: resolvedOptions.resumeFromRunId,
         journalPath,
         recordPath: workflowRunRecordPath(ctx.cwd, runId),
+        ...(script.path === undefined ? {} : { scriptPath: script.path }),
       }),
     );
     progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
@@ -184,7 +198,7 @@ export async function runResolvedWorkflow(
 
     // perf.total_ms wraps the whole tree: sub-workflows run inside this span via api.workflow().
     return perf.time("workflow.total_ms", () =>
-      runWorkflowWithContext(rc, progress, mod, args, {
+      runWorkflowWithContext(rc, progress, mod, input, {
         abortController: runAbortController,
         submissionLimit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
         resolveWorkflow: resolvedOptions.resolveWorkflow,
@@ -225,7 +239,7 @@ export async function runResolvedWorkflow(
     durableRun.transition({
       state: "paused",
       progress: progress.snapshot(),
-      ...createProviderUsageLimitPauseRecord(pauseError, resolvedOptions, mod.source.kind === "file" && args.length === 0),
+      ...createProviderUsageLimitPauseRecord(pauseError, resolvedOptions, canRelaunchWorkflowRun(initialRecord)),
     });
   } else if (pauseError) {
     durableRun.transition({
@@ -247,6 +261,33 @@ export async function runResolvedWorkflow(
   throw outcome.error;
 }
 
+/**
+ * Seal a run whose code came from a script for this install, so a repository cannot ship a run record
+ * whose relaunch runs its own code. An inline run's script is also written beside its record; a saved
+ * script resolves again by name, and the seal pins the content that ran. A failed write or seal only
+ * costs the run its relaunch from `/workflow:runs`.
+ */
+async function sealRunScript(cwd: string, runId: string, mod: LoadedWorkflow): Promise<{ readonly path?: string; readonly seal?: string }> {
+  const { source } = mod;
+  const savedScript = source.kind === "file" && source.selfContained === true;
+  if (!savedScript && (source.kind !== "fingerprint" || mod.inlineScript === undefined)) return {};
+  let path: string | undefined;
+  if (mod.inlineScript !== undefined && source.kind === "fingerprint") {
+    try {
+      path = await persistWorkflowRunScript(cwd, runId, mod.inlineScript);
+    } catch (error) {
+      process.stderr.write(`[${mod.meta.name}] script persistence failed: ${unknownErrorMessage(error)}\n`);
+      return {};
+    }
+  }
+  try {
+    return { path, seal: await sealWorkflowRunScript(runId, source.fingerprint) };
+  } catch (error) {
+    process.stderr.write(`[${mod.meta.name}] script seal failed, so /workflow:runs cannot relaunch this run: ${unknownErrorMessage(error)}\n`);
+    return { path };
+  }
+}
+
 function backgroundPauseError(error: unknown, ...signals: Array<AbortSignal | undefined>): unknown {
   if (isWorkflowPauseError(error)) return error;
   for (const signal of signals) {
@@ -345,7 +386,7 @@ function createWorkflowAgent(
   function agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S>>;
   function agent(prompt: string, opts?: AgentOptions): Promise<string>;
   function agent(prompt: string, agentOpts?: AgentOptions): Promise<unknown> {
-    const scopedOptions = scope.agentOptions(agentOpts);
+    const scopedOptions = scope.agentOptions(withPhaseProfile(mod.meta, agentOpts));
     const executionOptions: AgentExecutionOptions =
       scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
         ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
@@ -355,6 +396,17 @@ function createWorkflowAgent(
   return agent;
 }
 
+/**
+ * Routing order is the agent's `model`, then its `profile`, then its declared phase's `profile`, then
+ * the host. Only an explicit `opts.phase` selects a phase profile: the global `phase()` is shared
+ * state that concurrent `parallel`/`pipeline` branches race on.
+ */
+function withPhaseProfile(meta: WorkflowMeta, opts: AgentOptions | undefined): AgentOptions | undefined {
+  if (opts?.phase === undefined || opts.model !== undefined || opts.profile !== undefined) return opts;
+  const profile = meta.phases?.find((phase) => phase.title === opts.phase)?.profile;
+  return profile === undefined ? opts : { ...opts, profile };
+}
+
 /**
  * Build the `WorkflowApi` from an existing run context and invoke the module. Reused for both
  * the top-level run and every `api.workflow()` sub-step, so children share the parent's semaphore,
@@ -364,10 +416,12 @@ export async function runWorkflowWithContext(
   rc: WorkflowRunContext,
   progress: WorkflowProgress,
   mod: LoadedWorkflow,
-  args: string,
+  input: unknown,
   opts: WorkflowContextOptions,
 ): Promise<unknown> {
   const depth = opts.depth ?? 0;
+  // Converted before any agent runs, so an argument with no JSON form rejects the call up front.
+  const args = workflowArgsText(input);
   const scope = createWorkflowScope(progress, opts.progressPrefix ?? "", opts.progressNamespace);
   const resumeContext: AgentResumeBaseContext = {
     workflow: await captureWorkflowResumeContext(mod, rc.signal),
@@ -388,7 +442,8 @@ export async function runWorkflowWithContext(
           const childController = new AbortController();
           const unlink = linkAbortSignal(rc.signal, childController);
           try {
-            return await runWorkflowWithContext({ ...rc, signal: childController.signal }, progress, childMod, childArgs ?? "", {
+            const childInput = childArgs === undefined ? "" : childArgs;
+            return await runWorkflowWithContext({ ...rc, signal: childController.signal }, progress, childMod, childInput, {
               abortController: childController,
               submissionLimit: opts.submissionLimit,
               resolveWorkflow: opts.resolveWorkflow,
@@ -416,6 +471,7 @@ export async function runWorkflowWithContext(
     log: scope.log,
     progress: scope.event,
     args,
+    input,
     cwd: rc.cwd,
     budget: rc.budget,
     signal: rc.signal,

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

@@ -2,3 +2,8 @@
 export function isMissingPathError(error: unknown): boolean {
   return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
+
+/** Identify a path that already exists, as reported for an exclusive (`wx`) create. */
+export function isExistingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}

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

@@ -36,10 +36,16 @@ export function compileInlineWorkflow(source: string): LoadedWorkflow {
   return {
     meta: parsedMeta.meta,
     default: (api) => executor(api, Type),
-    source: { kind: "fingerprint", fingerprint: createHash("sha256").update(source).digest("hex") },
+    source: { kind: "fingerprint", fingerprint: inlineScriptFingerprint(source) },
+    inlineScript: source,
   };
 }
 
+/** A compiled script can import nothing, so the hash of its source is its whole identity. */
+export function inlineScriptFingerprint(source: string): string {
+  return createHash("sha256").update(source).digest("hex");
+}
+
 /** The script's pure-literal meta, read without compiling or running anything; undefined when it does not parse. */
 export function readInlineWorkflowMeta(source: string): WorkflowMeta | undefined {
   try {

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

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rm, stat, appendFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, appendFile, writeFile } 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 { isExistingPathError } from "./filesystem-error.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   isAgentResumeContext,
@@ -15,6 +16,9 @@ import {
 export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
 export const WORKFLOW_JOURNAL_KEEP = 50;
 
+/** Ignores everything in the runs directory, including this file, so user projects never commit run data. */
+const WORKFLOW_RUNS_GITIGNORE = "*\n";
+
 export interface JournalEntryV2 {
   readonly version: 2;
   readonly key: string;
@@ -56,6 +60,20 @@ export class WorkflowJournalLoadError extends Error {
   override readonly name = "WorkflowJournalLoadError";
 }
 
+/**
+ * Create the directory that holds run files, with a `.gitignore` that ignores all of them: records,
+ * journals, and scripts can carry prompts and results, and user projects do not list this directory in
+ * their own ignore files. An existing `.gitignore` is never overwritten.
+ */
+export async function ensureWorkflowRunsDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  try {
+    await writeFile(join(dir, ".gitignore"), WORKFLOW_RUNS_GITIGNORE, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (!isExistingPathError(error)) throw error;
+  }
+}
+
 export function createWorkflowRunId(): string {
   return randomUUID();
 }
@@ -161,7 +179,7 @@ export async function createWorkflowJournal(options: {
   readonly writePath: string;
 }): Promise<WorkflowJournal> {
   const priorEntries = options.resumePath ? await loadJournalEntries(options.resumePath, { required: true }) : [];
-  await mkdir(dirname(options.writePath), { recursive: true });
+  await ensureWorkflowRunsDir(dirname(options.writePath));
   await appendFile(options.writePath, "", "utf8");
   return createMemoryBackedJournal(priorEntries, options.writePath);
 }
@@ -201,10 +219,10 @@ export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[]
       const entry: JournalEntryV2 = { version: 2, key, result, identity };
       if (writePath) {
         try {
-          await mkdir(dirname(writePath), { recursive: true });
+          await ensureWorkflowRunsDir(dirname(writePath));
           await appendFile(writePath, `${JSON.stringify(entry)}\n`, "utf8");
         } catch (error) {
-      return { ok: false, error: unknownErrorMessage(error) };
+          return { ok: false, error: unknownErrorMessage(error) };
         }
       }
       return { ok: true };

package/.pi/extensions/pi-workflow-engine/src/model-profiles.ts

@@ -1,12 +1,8 @@
-import { randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { getAgentDir, type ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { isMissingPathError } from "./filesystem-error.ts";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { configFilePaths, readJsonConfigFile, writeJsonConfigFile, type ConfigFilePaths } from "./config-file.ts";
 import { isRecord } from "./guards.ts";
-import { unknownErrorMessage } from "./unknown-error.ts";
 
 export const WORKFLOW_MODEL_PROFILE_NAMES = ["small", "medium", "big"] as const;
 export type WorkflowModelProfileName = (typeof WORKFLOW_MODEL_PROFILE_NAMES)[number];
@@ -20,10 +16,7 @@ export interface WorkflowModelProfileFile {
   readonly profiles: Partial<Record<WorkflowModelProfileName, WorkflowModelProfileConfig>>;
 }
 
-export interface WorkflowModelProfilePaths {
-  readonly user: string;
-  readonly project: string;
-}
+export type WorkflowModelProfilePaths = ConfigFilePaths;
 
 interface ResolvedWorkflowModelProfileBase {
   readonly name: WorkflowModelProfileName;
@@ -52,15 +45,10 @@ const HOST_FALLBACK_THINKING: Record<WorkflowModelProfileName, ThinkingLevel> =
   big: "high",
 };
 const CONFIG_FILE_NAME = "workflow-models.json";
+const CONFIG_LABEL = "workflow model profiles";
 
-export function workflowModelProfilePaths(
-  cwd: string,
-  agentDir: string = getAgentDir(),
-): WorkflowModelProfilePaths {
-  return {
-    user: join(agentDir, CONFIG_FILE_NAME),
-    project: join(cwd, ".pi", CONFIG_FILE_NAME),
-  };
+export function workflowModelProfilePaths(cwd: string, agentDir?: string): WorkflowModelProfilePaths {
+  return configFilePaths(CONFIG_FILE_NAME, cwd, agentDir);
 }
 
 export function resolveWorkflowModelProfiles(input: {
@@ -123,22 +111,8 @@ export function resolveAgentModelProfile(
 }
 
 export function readWorkflowModelProfileFile(configPath: string): WorkflowModelProfileFile {
-  let contents: string;
-  try {
-    contents = readFileSync(configPath, "utf8");
-  } catch (error) {
-    if (isMissingPathError(error)) return { profiles: {} };
-    throw new Error(
-      `Could not read workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix the file permissions or remove the file.`,
-    );
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(contents);
-  } catch (error) {
-    throw new Error(`Invalid JSON in workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix or remove the file.`);
-  }
-  return parseWorkflowModelProfileFile(parsed, configPath);
+  const parsed = readJsonConfigFile(configPath, CONFIG_LABEL);
+  return parsed === undefined ? { profiles: {} } : parseWorkflowModelProfileFile(parsed, configPath);
 }
 
 export function setWorkflowModelProfile(input: {
@@ -239,19 +213,7 @@ function assertOnlyKeys(value: Record<string, unknown>, allowed: readonly string
 }
 
 function writeWorkflowModelProfileFile(configPath: string, config: WorkflowModelProfileFile): void {
-  const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
-  try {
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-    renameSync(temporaryPath, configPath);
-  } catch (error) {
-    try {
-      unlinkSync(temporaryPath);
-    } catch {
-      // Best effort: preserve the original write error.
-    }
-    throw new Error(`Could not write workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}.`);
-  }
+  writeJsonConfigFile(configPath, config, CONFIG_LABEL);
 }
 
 function invalidConfig(configPath: string, reason: string): Error {

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

@@ -1,6 +1,6 @@
 import type { WorkflowUsageSnapshot } from "./usage.ts";
 
-export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+export type AgentRowStatus = "queued" | "running" | "done" | "failed" | "skipped";
 export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
 
 export interface AgentRowSnapshot {