pi-workflow-engine 1.1.0 → 1.2.0

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

@@ -3,7 +3,7 @@ import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/p
 import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
 import { formatCount } from "../text.ts";
 import { compactUsage, dot, fit, GLYPH, joinParts, keyHints, progressBar, spread, type ThemeColor } from "./kit.ts";
-import { countAgents, formatDuration, formatElapsed, type WorkflowStatusCounts } from "./workflow-format.ts";
+import { countAgents, finishedAgents, formatDuration, formatElapsed, type WorkflowStatusCounts } from "./workflow-format.ts";
 
 /** pi caps string widgets at this many rows; the component keeps to the same budget. */
 const MAX_WIDGET_LINES = 10;
@@ -64,7 +64,7 @@ export class WidthAwareWidget implements Component {
 /** `◆ background · code-review 56b57550 · Find 6/10 · 12s`: one line for a run the user sent to the background. */
 export function renderBackgroundWorkflowLine(snapshot: WorkflowProgressSnapshot, width: number, theme: Theme): string[] {
   const counts = countAgents(snapshot.phases);
-  const progress = counts.total > 0 ? `${snapshot.currentPhase} ${counts.done + counts.failed}/${counts.total}` : snapshot.currentPhase;
+  const progress = counts.total > 0 ? `${snapshot.currentPhase} ${finishedAgents(counts)}/${counts.total}` : snapshot.currentPhase;
   const line = joinParts([
     `${theme.fg("accent", GLYPH.workflow)} ${theme.fg("muted", "background")}`,
     `${theme.bold(snapshot.title)} ${theme.fg("dim", snapshot.runId.slice(0, 8))}`,
@@ -92,7 +92,7 @@ function classifyPhases(snapshot: WorkflowProgressSnapshot): ClassifiedPhases {
 
 function headerLine(snapshot: WorkflowProgressSnapshot, counts: WorkflowStatusCounts, width: number, now: number, theme: Theme): string {
   const name = `${theme.fg("accent", GLYPH.workflow)} ${theme.bold(snapshot.title)}`;
-  const finished = counts.done + counts.failed;
+  const finished = finishedAgents(counts);
   const stats = joinParts([
     counts.total > 0 ? theme.fg("text", `${finished}/${counts.total}`) : undefined,
     theme.fg("muted", formatElapsed(now - snapshot.startedAt)),
@@ -156,8 +156,8 @@ function phaseBody(
 
 /**
  * Spread the row budget over active phases by importance — a reserved share for failures so they always
- * show, then running, remaining failures, done, queued — while each phase lists its chosen rows as
- * running, failed, done, queued.
+ * show, then running, remaining failures, skipped, done, queued — while each phase lists its chosen rows
+ * in that same status order.
  */
 function planAgentRows(active: readonly PhaseSnapshot[], budget: number): Map<PhaseSnapshot, AgentRowPlan> {
   const byStatus = (status: AgentRowSnapshot["status"]) =>
@@ -177,10 +177,11 @@ function planAgentRows(active: readonly PhaseSnapshot[], budget: number): Map<Ph
   take(failed, failed.length > 0 ? Math.max(1, Math.floor(budget / 3)) : 0);
   take(byStatus("running"));
   take(failed);
+  take(byStatus("skipped"));
   take(byStatus("done"));
   take(byStatus("queued"));
 
-  const rank = { running: 0, failed: 1, done: 2, queued: 3 } as const;
+  const rank = { running: 0, failed: 1, skipped: 2, done: 3, queued: 4 } as const;
   const plans = new Map<PhaseSnapshot, AgentRowPlan>();
   for (const phase of active) {
     const shown = phase.agents.filter((agent) => chosen.has(agent)).sort((a, b) => rank[a.status] - rank[b.status]);
@@ -196,7 +197,7 @@ function agentLabelWidth(plans: ReadonlyMap<PhaseSnapshot, AgentRowPlan>, width:
 
 function finishedPhaseLine(phase: PhaseSnapshot, titleWidth: number, theme: Theme): string {
   const counts = countAgents([phase]);
-  const glyph = counts.failed === 0
+  const glyph = counts.failed === 0 && counts.skipped === 0
     ? theme.fg("success", GLYPH.done)
     : counts.failed === counts.total ? theme.fg("error", GLYPH.failed) : theme.fg("warning", GLYPH.warning);
   const span = phaseSpan(phase.agents);
@@ -204,17 +205,19 @@ function finishedPhaseLine(phase: PhaseSnapshot, titleWidth: number, theme: Them
     counts.total > 0 ? theme.fg("muted", plural(counts.total, "agent")) : undefined,
     span === undefined ? undefined : theme.fg("muted", shortDuration(span)),
     counts.failed > 0 ? theme.fg("error", `${counts.failed} failed`) : undefined,
+    counts.skipped > 0 ? theme.fg("warning", `${counts.skipped} skipped`) : undefined,
   ], theme);
   return `  ${glyph} ${theme.fg("muted", fit(phase.title, titleWidth))}  ${detail}`.trimEnd();
 }
 
 function foldedPhasesLine(phases: readonly PhaseSnapshot[], theme: Theme): string {
   const counts = countAgents(phases);
-  const glyph = counts.failed > 0 ? theme.fg("warning", GLYPH.warning) : theme.fg("success", GLYPH.done);
+  const glyph = counts.failed > 0 || counts.skipped > 0 ? theme.fg("warning", GLYPH.warning) : theme.fg("success", GLYPH.done);
   const titles = phases.map((phase) => phase.title).join(" · ");
   const detail = joinParts([
     theme.fg("muted", plural(counts.total, "agent")),
     counts.failed > 0 ? theme.fg("error", `${counts.failed} failed`) : undefined,
+    counts.skipped > 0 ? theme.fg("warning", `${counts.skipped} skipped`) : undefined,
   ], theme);
   return `  ${glyph} ${theme.fg("muted", titles)}  ${detail}`;
 }
@@ -226,6 +229,7 @@ function activePhaseLine(plan: AgentRowPlan, titleWidth: number, theme: Theme):
     counts.queued > 0 ? theme.fg("muted", `${counts.queued} queued`) : undefined,
     counts.done > 0 ? theme.fg("muted", `${counts.done} done`) : undefined,
     counts.failed > 0 ? theme.fg("error", `${counts.failed} failed`) : undefined,
+    counts.skipped > 0 ? theme.fg("warning", `${counts.skipped} skipped`) : undefined,
     plan.hidden > 0 ? theme.fg("dim", `+${plan.hidden} more`) : undefined,
   ], theme);
   return `  ${theme.fg("accent", GLYPH.running)} ${theme.bold(fit(plan.phase.title, titleWidth))}  ${detail}`.trimEnd();
@@ -246,6 +250,8 @@ function agentGlyph(agent: AgentRowSnapshot, theme: Theme): string {
       return theme.fg("error", GLYPH.failed);
     case "done":
       return theme.fg("success", GLYPH.done);
+    case "skipped":
+      return theme.fg("warning", GLYPH.skipped);
     case "queued":
       return theme.fg("dim", GLYPH.queued);
   }
@@ -264,6 +270,8 @@ function agentDetail(agent: AgentRowSnapshot, now: number, theme: Theme): string
       ], theme);
     case "failed":
       return theme.fg("error", oneLine(agent.error ?? "failed"));
+    case "skipped":
+      return theme.fg("warning", "skipped");
     case "queued":
       return theme.fg("dim", "queued");
   }

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

@@ -20,7 +20,9 @@ export type AdvisoryVerified = IdentifiedAdvisoryCandidate & {
 
 export interface LensVerificationPipelineResult {
   verified: AdvisoryVerified[];
+  /** Every candidate the finders returned, including those over the per-lens cap. */
   rawCandidates: number;
+  /** Candidates never verified: over the per-lens cap, duplicates, or out of scope. */
   dropped: number;
   coverage: AdvisoryStageCoverage[];
 }
@@ -73,6 +75,7 @@ export async function runLensVerificationPipeline(
   const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
   const coverage: AdvisoryStageCoverage[] = [];
   let rawCandidates = 0;
+  let overCap = 0;
   api.phase(finderPhase);
   const found = await collectAdvisoryStage(api, "Find", lenses.map((lens) => ({ id: lens.label, run: async () => {
     const result = await api.agent(finderPrompt(lens), {
@@ -80,9 +83,16 @@ export async function runLensVerificationPipeline(
       tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
       profile: "small", schema: AdvisoryCandidatesSchema,
     });
+    rawCandidates += result.candidates.length;
+    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: result.candidates.length });
+    // A finder can return more than the cap its prompt states; keep the first perLens and report the rest.
+    const cut = Math.max(0, result.candidates.length - perLens);
+    if (cut > 0) {
+      overCap += cut;
+      api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: cut });
+      api.log(`Dropped ${cut} ${lens.label} candidate(s) over the per-lens cap of ${perLens}`);
+    }
     const raw = identifyCandidates(result.candidates.slice(0, perLens), lens.label);
-    rawCandidates += raw.length;
-    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
     const candidates = boundCandidate ? raw.flatMap((candidate) => {
       const bounded = boundCandidate(candidate, lens);
       return bounded ? [bounded] : [];
@@ -94,11 +104,12 @@ export async function runLensVerificationPipeline(
     return candidates;
   } })), coverage);
   const candidates = await mergeEquivalentCandidates(api, dedupeCandidates(found.flat()));
-  const dropped = rawCandidates - candidates.length;
-  if (dropped > 0) {
-    api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-    api.log(`Dropped ${dropped} duplicate or out-of-scope candidate(s)`);
+  const duplicateOrOutOfScope = rawCandidates - overCap - candidates.length;
+  if (duplicateOrOutOfScope > 0) {
+    api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: duplicateOrOutOfScope });
+    api.log(`Dropped ${duplicateOrOutOfScope} duplicate or out-of-scope candidate(s)`);
   }
+  const dropped = overCap + duplicateOrOutOfScope;
   api.phase("Verify");
   const verified = await collectAdvisoryStage(api, "Verify", candidates.map((candidate) => ({
     id: candidate.candidateId, candidate, run: async (): Promise<AdvisoryVerified> => {

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

@@ -0,0 +1,79 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sessionKey } from "./session-identity.ts";
+import type { WorkflowMeta } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import { DEFAULT_WORKFLOW_SIZE_GUIDELINE, workflowSizeGuidelineLine, type WorkflowSizeGuideline } from "./workflow-settings.ts";
+
+/** System prompt section pi wraps as `<workflows>`: the registered workflows the host may run by name. */
+export const WORKFLOWS_SECTION = "workflows";
+
+/**
+ * One line per workflow, sorted by name, then the size guideline, so the section text depends only on
+ * what is registered and configured.
+ */
+export function formatWorkflowCatalog(workflows: Iterable<WorkflowMeta>, sizeLine?: string): string | undefined {
+  const lines = [...workflows]
+    // Code-unit order rather than localeCompare, whose result depends on the host locale.
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+    .map((meta) => {
+      const description = meta.description.trim();
+      const whenToUse = meta.whenToUse?.trim();
+      return `- ${meta.name}${description ? `: ${description}` : ""}${whenToUse ? ` ${whenToUse}` : ""}`;
+    });
+  const blocks: string[] = [];
+  if (lines.length > 0) {
+    blocks.push(["Registered workflows the workflow tool runs by `name`, passing the target or instructions as `args` (only once the user opted into workflow orchestration):", ...lines].join("\n"));
+  }
+  if (sizeLine) blocks.push(sizeLine);
+  return blocks.length > 0 ? blocks.join("\n\n") : undefined;
+}
+
+export interface WorkflowCatalogSources {
+  readonly discover: (ctx: ExtensionContext) => Promise<Iterable<WorkflowMeta>>;
+  readonly size: (ctx: ExtensionContext) => WorkflowSizeGuideline;
+  readonly log?: (message: string) => void;
+}
+
+/**
+ * The catalog section for each session, built once from discovery and settings and then reused, so every
+ * run in the session sends identical text and keeps the provider's prompt cache. A new session start or a
+ * size change rebuilds it.
+ */
+export class WorkflowCatalogPrompt {
+  private readonly sessions = new Map<string, Promise<string | undefined>>();
+  private readonly log: (message: string) => void;
+
+  constructor(private readonly sources: WorkflowCatalogSources) {
+    this.log = sources.log ?? ((message) => process.stderr.write(`${message}\n`));
+  }
+
+  section(ctx: ExtensionContext): Promise<string | undefined> {
+    const key = sessionKey(ctx);
+    const cached = this.sessions.get(key);
+    if (cached) return cached;
+    const built = this.build(ctx);
+    this.sessions.set(key, built);
+    return built;
+  }
+
+  forget(ctx: Pick<ExtensionContext, "sessionManager">): void {
+    this.sessions.delete(sessionKey(ctx));
+  }
+
+  // The catalog only advertises workflows and a guideline; neither failure may block the prompt.
+  private async build(ctx: ExtensionContext): Promise<string | undefined> {
+    let size = DEFAULT_WORKFLOW_SIZE_GUIDELINE;
+    try {
+      size = this.sources.size(ctx);
+    } catch (error) {
+      this.log(`[workflow] workflow size guideline unavailable, using ${size}: ${unknownErrorMessage(error)}`);
+    }
+    let workflows: Iterable<WorkflowMeta> = [];
+    try {
+      workflows = await this.sources.discover(ctx);
+    } catch (error) {
+      this.log(`[workflow] workflow catalog unavailable: ${unknownErrorMessage(error)}`);
+    }
+    return formatWorkflowCatalog(workflows, workflowSizeGuidelineLine(size));
+  }
+}

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

@@ -25,6 +25,8 @@ export interface WorkflowResultEnvelope {
   readonly perf?: WorkflowPerfDetails;
   readonly runId?: string;
   readonly resumedFromRunId?: string;
+  /** Whether an inline run's script was persisted beside its journal. */
+  readonly scriptPersisted?: boolean;
 }
 
 /** A workflow result's own summary: the result itself when it is a string, else its string `summary` field. */
@@ -36,7 +38,7 @@ export function workflowResultSummary(result: unknown): string | undefined {
 export type ResolvedWorkflowRunner = (
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
-  args: string,
+  args: unknown,
   options: ResolvedWorkflowRunOptions,
 ) => Promise<unknown>;
 
@@ -44,7 +46,8 @@ export interface WorkflowExecutionInput {
   readonly ctx: ExtensionContext;
   readonly name: string;
   readonly mod: LoadedWorkflow;
-  readonly args: string;
+  /** A slash command's argument string, or a tool call's string or JSON value. */
+  readonly args: unknown;
   readonly options: ResolvedWorkflowRunOptions;
   readonly perfRecorder?: PerfSink;
   readonly runResolvedWorkflow: ResolvedWorkflowRunner;
@@ -99,6 +102,7 @@ export async function executeWorkflowInvocation(input: WorkflowExecutionInput):
     perf: perfSnapshot?.enabled ? { aggregates: perfSnapshot.aggregates } : undefined,
     runId: runMetadata?.runId,
     resumedFromRunId: runMetadata?.resumedFromRunId,
+    scriptPersisted: runMetadata?.scriptPath !== undefined,
   };
 }
 

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

@@ -0,0 +1,13 @@
+// A workflow's input is the string a slash command passes, or any JSON value from a tool call or
+// `api.workflow()`. Workflows read it verbatim as `api.input` and as text as `api.args`.
+
+/** `api.args`: a string verbatim, any other JSON value as JSON text, and "" when nothing was passed. */
+export function workflowArgsText(input: unknown): string {
+  if (typeof input === "string") return input;
+  return JSON.stringify(input) ?? "";
+}
+
+/** Whether a run had arguments. Run records never keep them, so such a run cannot be relaunched. */
+export function workflowInputPresent(input: unknown): boolean {
+  return input !== undefined && input !== "";
+}

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

@@ -2,10 +2,14 @@ import type {
   LoadedWorkflow,
   WorkflowMeta,
   WorkflowModule,
+  WorkflowPhaseMeta,
   WorkflowSourceIdentity,
 } from "./types.ts";
 import type { WorktreeBaseline } from "./worktree.ts";
 import { isRecord } from "./guards.ts";
+import { isWorkflowModelProfileName } from "./model-profiles.ts";
+
+const PHASES_SHAPE = 'meta.phases must be an array of { title: string, profile?: "small" | "medium" | "big" }';
 
 /** Validate and normalize workflow metadata without executing workflow code. */
 export function parseWorkflowMeta(meta: unknown): { meta: WorkflowMeta } | { reason: string } {
@@ -15,10 +19,14 @@ export function parseWorkflowMeta(meta: unknown): { meta: WorkflowMeta } | { rea
   const description = meta.description;
   if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
 
-  const phases = meta.phases;
-  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+  const whenToUse = meta.whenToUse;
+  if (whenToUse !== undefined && typeof whenToUse !== "string") return { reason: "meta.whenToUse must be a string when provided" };
+
+  const phases = meta.phases === undefined ? undefined : parseWorkflowPhases(meta.phases);
+  if (phases === null) return { reason: PHASES_SHAPE };
 
   const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (whenToUse !== undefined) workflowMeta.whenToUse = whenToUse;
   if (phases !== undefined) workflowMeta.phases = phases;
   return { meta: workflowMeta };
 }
@@ -50,6 +58,15 @@ function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
   return typeof value === "function";
 }
 
-function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
-  return Array.isArray(value) && value.every((phase) => isRecord(phase) && typeof phase.title === "string");
+/** The declared phases keeping only known fields, or null when any entry is malformed. */
+function parseWorkflowPhases(value: unknown): WorkflowPhaseMeta[] | null {
+  if (!Array.isArray(value)) return null;
+  const phases: WorkflowPhaseMeta[] = [];
+  for (const phase of value) {
+    if (!isRecord(phase) || typeof phase.title !== "string") return null;
+    const { profile } = phase;
+    if (profile !== undefined && (typeof profile !== "string" || !isWorkflowModelProfileName(profile))) return null;
+    phases.push({ title: phase.title, ...(profile === undefined ? {} : { profile }) });
+  }
+  return phases;
 }

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

@@ -1,5 +1,8 @@
+import { join } from "node:path";
 import { formatAdvisoryLocation, isAdvisoryReport, type AdvisoryFinding, type AdvisoryReport } from "./advisory-schema.ts";
 import { isRecord } from "./guards.ts";
+import { WORKFLOW_RUNS_DIR } from "./journal.ts";
+import { workflowRunScriptFile } from "./workflow-run-record.ts";
 import { toReviewIssues } from "./review/review-issues.ts";
 import { formatPerfSummary } from "./perf.ts";
 import { prettyJson } from "./text.ts";
@@ -15,19 +18,36 @@ export function formatWorkflowResultForContext(envelope: WorkflowResultEnvelope)
   return `## Workflow: ${envelope.name}\n\n${formatResultForContext(envelope.result)}${details.length > 0 ? `\n\n${details.join("\n")}` : ""}`;
 }
 
-/** Run id, usage and perf lines appended for the host model. */
+/** Run id, run files, usage and perf lines appended for the host model. */
 function formatWorkflowDetailLines(envelope: WorkflowResultEnvelope): string[] {
-  const run = envelope.runId
-    ? envelope.resumedFromRunId ? `Run: ${envelope.runId} (resumed from ${envelope.resumedFromRunId})` : `Run: ${envelope.runId}`
-    : undefined;
   return [
-    run,
+    ...(envelope.runId
+      ? [formatWorkflowRunLine({ runId: envelope.runId, resumedFromRunId: envelope.resumedFromRunId }), ...formatWorkflowRunFileLines(envelope.runId, envelope.scriptPersisted === true)]
+      : []),
     formatWorkflowUsageLine(envelope.usage),
     envelope.perf ? formatPerfSummary(envelope.perf.aggregates) : undefined,
   ].filter((line): line is string => line !== undefined);
 }
 
-function formatResultForContext(result: unknown): string {
+/** The run id, naming the run a resume continues. */
+export function formatWorkflowRunLine(run: { readonly runId: string; readonly resumedFromRunId?: string }): string {
+  return run.resumedFromRunId ? `Run: ${run.runId} (resumed from ${run.resumedFromRunId})` : `Run: ${run.runId}`;
+}
+
+/**
+ * Where the host model can read what the run did, relative to the workflow cwd: the persisted script it
+ * can edit and rerun with `scriptPath`, and the replay journal of completed agent results.
+ */
+export function formatWorkflowRunFileLines(runId: string, scriptPersisted: boolean): string[] {
+  return [
+    ...(scriptPersisted ? [`Script: ${join(WORKFLOW_RUNS_DIR, workflowRunScriptFile(runId))}`] : []),
+    `Journal: ${join(WORKFLOW_RUNS_DIR, `${runId}.jsonl`)}`,
+    "If the result is empty or unexpected, read the journal before diagnosing.",
+  ];
+}
+
+/** A workflow result as the host model reads it: advisory reports as findings, other values as bounded JSON. */
+export function formatResultForContext(result: unknown): string {
   if (typeof result === "string") return result;
   if (isAdvisoryReport(result)) return formatAdvisoryReportForContext(result);
   const summary = workflowResultSummary(result);

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

@@ -23,6 +23,7 @@ export function createPersistedWorkflowBackground(
     origin: {
       sessionId: truncateText(origin.sessionId, MAX_BACKGROUND_TEXT),
       requestedAt: origin.requestedAt,
+      ...(origin.wakeOnComplete ? { wakeOnComplete: true } : {}),
     },
     delivery: { state: "pending" },
   };
@@ -49,6 +50,7 @@ export function updateWorkflowRunDelivery(
 export function isPersistedWorkflowBackground(value: unknown): value is PersistedWorkflowBackground {
   if (!isRecord(value) || !isRecord(value.origin) || !isRecord(value.delivery)) return false;
   if (typeof value.origin.sessionId !== "string" || !isFiniteNumber(value.origin.requestedAt)) return false;
+  if (value.origin.wakeOnComplete !== undefined && typeof value.origin.wakeOnComplete !== "boolean") return false;
   switch (value.delivery.state) {
     case "pending":
       return true;

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

@@ -6,7 +6,7 @@ import type {
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { BackgroundWorkflowCoordinator } from "./background-workflows.ts";
 import { backgroundUnavailableResult, startBackgroundWorkflowTool } from "./background-workflow-tool.ts";
-import { validateWorkflowRunId } from "./journal.ts";
+import { validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
 import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "./options.ts";
 import type { LoadedWorkflow } from "./types.ts";
 import {
@@ -17,15 +17,19 @@ import {
   formatWorkflowRunSummary,
   isWorkflowRunLifecycleAction,
   parseWorkflowRunsCommand,
+  isInlineWorkflowRun,
   retainedWorkflowRunOutcome,
   supersedingRuns,
   WORKFLOW_RUN_ACTIONS,
   WORKFLOW_RUN_HISTORY_LIMIT,
+  workflowRunDisplayName,
   type WorkflowRunActionContext,
   type WorkflowRunLifecycleAction,
 } from "./workflow-run-history.ts";
-import { stopWorkflowRunRecord, type WorkflowRunRecord } from "./workflow-run-record.ts";
-import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { stopWorkflowRunRecord, workflowRunScriptFile, type WorkflowRunRecord } from "./workflow-run-record.ts";
+import { verifyWorkflowRunScriptSeal } from "./workflow-run-seal.ts";
+import { ProjectWorkflowRunStore, readWorkflowRunScript, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { compileInlineWorkflow, inlineScriptFingerprint } from "./inline-workflow.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   WorkflowUsageLimitScheduler,
@@ -39,7 +43,8 @@ import { completeCurrentArgument, splitArgumentPrefix } from "./command-completi
 type WorkflowRunCompletionContext = Pick<ExtensionContext, "cwd" | "sessionManager">;
 
 interface WorkflowRunControllerDependencies {
-  readonly resolveWorkflow: (name: string) => Promise<LoadedWorkflow | undefined>;
+  /** The registered workflow a relaunch runs; `ctx` decides which project's saved workflows are visible. */
+  readonly resolveWorkflow: (name: string, ctx: ExtensionContext) => Promise<LoadedWorkflow | undefined>;
   readonly execute: (
     ctx: ExtensionContext,
     name: string,
@@ -160,7 +165,7 @@ export class WorkflowRunController {
       }
       const actions = availableWorkflowRunActions(record, runs);
       const selectedAction = await ctx.ui.select(
-        `${record.workflow.name} · ${record.runId}`,
+        `${workflowRunDisplayName(record)} · ${record.runId}`,
         [...actions],
       );
       const action = actions.find((candidate) => candidate === selectedAction);
@@ -232,14 +237,10 @@ export class WorkflowRunController {
   ): Promise<string> {
     const unavailable = backgroundUnavailableResult(ctx.mode);
     if (unavailable) throw new Error(unavailable.content[0].text);
-    const workflow = await this.dependencies.resolveWorkflow(record.workflow.name);
-    if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
-    if (workflow.source.kind !== "file") {
-      throw new Error(`registered workflow ${record.workflow.name} no longer has verifiable file provenance`);
-    }
+    const { workflow, fingerprint } = await this.relaunchWorkflow(ctx, record);
     if (
       action === "resume"
-      && workflow.source.fingerprint !== record.workflow.sourceFingerprint
+      && fingerprint !== record.workflow.sourceFingerprint
     ) {
       throw new Error("workflow source changed, so journal replay cannot resume safely");
     }
@@ -264,6 +265,8 @@ export class WorkflowRunController {
       ctx,
       name: workflow.meta.name,
       options,
+      // A relaunch continues the original run, so it delivers the way that run would have.
+      wakeOnComplete: record.background?.origin.wakeOnComplete === true,
       execute: (backgroundCtx, backgroundOptions) =>
         this.dependencies.execute(backgroundCtx, workflow.meta.name, workflow, backgroundOptions),
     });
@@ -272,6 +275,35 @@ export class WorkflowRunController {
     return message;
   }
 
+  /** The module a relaunch runs: an inline run's persisted script, else the registered workflow of the same name. */
+  private async relaunchWorkflow(
+    ctx: ExtensionContext,
+    record: WorkflowRunRecord,
+  ): Promise<{ readonly workflow: LoadedWorkflow; readonly fingerprint: string }> {
+    if (record.workflow.sourceKind === "fingerprint") {
+      if (record.scriptFile === undefined) throw new Error(`inline workflow ${record.workflow.name} did not retain its script`);
+      const fingerprint = await sealedFingerprint(record);
+      let source: string;
+      try {
+        source = await readWorkflowRunScript(ctx.cwd, record.runId);
+      } catch (error) {
+        throw new Error(`inline workflow script ${record.scriptFile} is unavailable: ${unknownErrorMessage(error)}`);
+      }
+      if (inlineScriptFingerprint(source) !== fingerprint) throw new Error(unsealedRunMessage(record));
+      return { workflow: compileInlineWorkflow(source), fingerprint };
+    }
+    const workflow = await this.dependencies.resolveWorkflow(record.workflow.name, ctx);
+    if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
+    if (workflow.source.kind !== "file") {
+      throw new Error(`registered workflow ${record.workflow.name} no longer has verifiable file provenance`);
+    }
+    // A repository can also ship a saved script under the name a forged record claims.
+    if (workflow.source.selfContained === true && (await sealedFingerprint(record)) !== workflow.source.fingerprint) {
+      throw new Error(unsealedRunMessage(record));
+    }
+    return { workflow, fingerprint: workflow.source.fingerprint };
+  }
+
   private async autoResume(ctx: ExtensionContext, runId: string, attempt: number): Promise<void> {
     const record = await this.loadRecord(ctx.cwd, runId);
     if (
@@ -326,7 +358,7 @@ export class WorkflowRunController {
         .filter((record) => availableWorkflowRunActions(record, runs).includes(action))
         .map((record) => ({
           value: record.runId,
-          description: `${record.state} · ${record.workflow.name}`,
+          description: `${record.state} · ${workflowRunDisplayName(record)}`,
         })),
     );
   }
@@ -340,12 +372,36 @@ export class WorkflowRunController {
       { value: "last", description: "Inspect the current or most recent in-session workflow" },
       ...records.map((record) => ({
         value: record.runId,
-        description: `${record.state} · ${record.workflow.name}`,
+        description: `${record.state} · ${workflowRunDisplayName(record)}`,
       })),
     ]);
   }
 }
 
+/**
+ * The fingerprint a script-sourced record's seal covers. A repository can ship a record of its own, so
+ * the seal is checked before any script is read; it is this install's, over the script as recorded.
+ */
+async function sealedFingerprint(record: WorkflowRunRecord): Promise<string> {
+  const fingerprint = record.workflow.sourceFingerprint;
+  if (
+    fingerprint === undefined
+    || record.scriptSeal === undefined
+    || !(await verifyWorkflowRunScriptSeal(record.runId, fingerprint, record.scriptSeal))
+  ) {
+    throw new Error(unsealedRunMessage(record));
+  }
+  return fingerprint;
+}
+
+/** Why a script-sourced record will not run, and how to run the script anyway. */
+function unsealedRunMessage(record: WorkflowRunRecord): string {
+  const rerun = isInlineWorkflowRun(record)
+    ? `rerun it with the workflow tool's scriptPath (${WORKFLOW_RUNS_DIR}/${workflowRunScriptFile(record.runId)})`
+    : `run ${record.workflow.name} again by name`;
+  return `${isInlineWorkflowRun(record) ? "inline run" : "run"} ${record.runId} was not recorded by this pi install, or its script changed since; ${rerun}`;
+}
+
 /**
  * Runs that any stored run resumed, whatever that resume's outcome. A resumed run keeps its paused
  * record and pause attempt, so automatic resume treats the pause as spent: re-arming it after a

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

@@ -86,9 +86,28 @@ export function availableWorkflowRunActions(
 }
 
 export function canRelaunchWorkflowRun(record: WorkflowRunRecord): boolean {
+  return hasRelaunchableWorkflowSource(record) && record.options.argumentsPresent === false;
+}
+
+/**
+ * A registered workflow resolves again by name; an inline one relaunches from the script persisted beside
+ * its record, and only when the record carries a seal. This check is only the seal's presence: relaunch
+ * verifies it, and the script's fingerprint, before running anything.
+ */
+export function hasRelaunchableWorkflowSource(record: WorkflowRunRecord): boolean {
+  if (typeof record.workflow.sourceFingerprint !== "string") return false;
   return record.workflow.sourceKind === "file"
-    && typeof record.workflow.sourceFingerprint === "string"
-    && record.options.argumentsPresent === false;
+    || (isInlineWorkflowRun(record) && record.scriptFile !== undefined && record.scriptSeal !== undefined);
+}
+
+/** A run of an inline script (a tool `script` or `scriptPath`), not of a registered workflow. */
+export function isInlineWorkflowRun(record: WorkflowRunRecord): boolean {
+  return record.workflow.sourceKind === "fingerprint";
+}
+
+/** The run's workflow name, marked when it ran an inline script, so such a record cannot pose as a registered workflow's run. */
+export function workflowRunDisplayName(record: WorkflowRunRecord): string {
+  return isInlineWorkflowRun(record) ? `${record.workflow.name} (inline)` : record.workflow.name;
 }
 
 export function formatWorkflowRunHistory(
@@ -112,7 +131,7 @@ export function formatWorkflowRunSummary(
   const usage = formatWorkflowUsageLine(record.usage);
   const resumedAs = runs.resumedAs.get(record.runId);
   const actions = availableWorkflowRunActions(record, runs).filter((action) => action !== "inspect");
-  return `${record.state.toUpperCase()} ${record.workflow.name} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${resumedAs ? ` · resumed as ${resumedAs}` : ""}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
+  return `${record.state.toUpperCase()} ${workflowRunDisplayName(record)} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${resumedAs ? ` · resumed as ${resumedAs}` : ""}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
 }
 
 export function formatWorkflowRunDetails(
@@ -127,7 +146,7 @@ export function formatWorkflowRunDetails(
   const usage = formatWorkflowUsageLine(record.usage);
   const lines = [
     `Workflow run ${record.runId}`,
-    `Workflow: ${record.workflow.name}`,
+    `Workflow: ${workflowRunDisplayName(record)}`,
     `State: ${record.state.toUpperCase()}`,
     `Age: ${formatDuration(Math.max(0, now - record.createdAt))}`,
     `Duration: ${formatWorkflowRunDuration(record, now)}`,