pi-workflow-engine 1.1.0 → 1.3.0

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

@@ -1,4 +1,4 @@
-import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import { AdvisoryBatchVerdictSchema, AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
 import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, mergeCandidateInto, repoPathCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
 import { isFatalWorkflowError } from "./cancellation.ts";
 import { WorkflowClassifierUnavailableError } from "./classify.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[];
 }
@@ -52,15 +54,29 @@ export function publishVerifiedKeptProgress(
 }
 
 export interface LensVerificationPipelineOptions {
-  api: Pick<WorkflowApi, "agent" | "classify" | "parallel" | "phase" | "progress" | "log">;
+  api: Pick<WorkflowApi, "agent" | "agents" | "classify" | "parallel" | "phase" | "progress" | "log">;
   lenses: readonly AdvisoryLens[];
   perLens: number;
   finderPhase?: "Find" | "Hypothesize";
+  finderProfile?: AgentOptions["profile"];
   finderPrompt(lens: AdvisoryLens): string;
-  verifierPrompt(candidate: IdentifiedAdvisoryCandidate): string;
+  /** One verifier's prompt. It gets several candidates only when the agent limit leaves fewer verifiers than candidates. */
+  verifierPrompt(candidates: readonly IdentifiedAdvisoryCandidate[]): string;
   boundCandidate?(candidate: IdentifiedAdvisoryCandidate, lens: AdvisoryLens): IdentifiedAdvisoryCandidate | undefined;
 }
 
+/** The candidate section of a verifier prompt: one record, or a batch judged in one pass. */
+export function verifierCandidates(
+  candidates: readonly IdentifiedAdvisoryCandidate[],
+  heading: { one: string; many: string },
+  fields: (candidate: IdentifiedAdvisoryCandidate) => string,
+): string {
+  if (candidates.length === 1) return `## ${heading.one}\n${fields(candidates[0]!)}`;
+  return `## ${heading.many} (${candidates.length}: the run's agent limit leaves one verifier for several)\n` +
+    candidates.map((candidate) => `### candidateId ${candidate.candidateId}\n${fields(candidate)}`).join("\n\n") +
+    "\n\nJudge each on its own evidence and return one verdict per candidateId.";
+}
+
 export interface AdvisoryBackfillDefaults {
   impact: string;
   recommendation?: string;
@@ -70,19 +86,27 @@ export interface AdvisoryBackfillDefaults {
 export async function runLensVerificationPipeline(
   options: LensVerificationPipelineOptions,
 ): Promise<LensVerificationPipelineResult> {
-  const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
+  const { api, lenses, perLens, finderPhase = "Find", finderProfile = "small", 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), {
       phase: finderPhase, label: `${finderPhase.toLowerCase()}:${lens.label}`,
       tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
-      profile: "small", schema: AdvisoryCandidatesSchema,
+      profile: finderProfile, 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,27 +118,62 @@ 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> => {
-      const location = primaryLocation(candidate);
-      const judged = await api.agent(`${verifierPrompt(candidate)}\nCandidate record: ${JSON.stringify(candidate)}`, {
-        phase: "Verify", label: `verify:${location.file.split("/").pop() ?? location.file}`,
-        tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
-        profile: "small", schema: AdvisoryVerdictSchema,
-      });
-      recordVerdictProgress(api.progress, candidate, judged);
-      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence };
-    },
-  })), coverage);
+  // Keep one admission for the synthesis that follows. A host-set agent limit can leave fewer verifiers than
+  // candidates; then each verifier judges a batch, so no candidate goes unverified and synthesis still runs.
+  const batches = verificationBatches(candidates, Math.max(1, api.agents.remaining() - 1));
+  if (batches.length < candidates.length) api.log(`Verifying ${candidates.length} candidates in ${batches.length} batch(es) to fit the agent limit`);
+  // Each candidate keeps its own coverage branch, so a failed batch still lists every candidate it held.
+  const verified = await collectAdvisoryStage(api, "Verify", batches.flatMap((batch) => {
+    let judged: Promise<AdvisoryVerified[]> | undefined;
+    return batch.map((candidate, index) => ({
+      id: candidate.candidateId, candidate,
+      run: async () => (await (judged ??= verifyBatch(api, batch, verifierPrompt)))[index]!,
+    }));
+  }), coverage);
   return { verified, rawCandidates, dropped, coverage };
 }
 
+/** Split candidates into at most `count` batches, keeping candidates in one file together where it fits. */
+function verificationBatches(candidates: readonly IdentifiedAdvisoryCandidate[], count: number): IdentifiedAdvisoryCandidate[][] {
+  if (candidates.length <= count) return candidates.map((candidate) => [candidate]);
+  const byFile = [...candidates].sort((a, b) => primaryLocation(a).file.localeCompare(primaryLocation(b).file));
+  const size = Math.ceil(byFile.length / count);
+  return Array.from({ length: Math.ceil(byFile.length / size) }, (_, index) => byFile.slice(index * size, (index + 1) * size));
+}
+
+async function verifyBatch(
+  api: Pick<WorkflowApi, "agent" | "progress">,
+  batch: readonly IdentifiedAdvisoryCandidate[],
+  verifierPrompt: LensVerificationPipelineOptions["verifierPrompt"],
+): Promise<AdvisoryVerified[]> {
+  const location = primaryLocation(batch[0]!);
+  const options = {
+    phase: "Verify", label: `verify:${location.file.split("/").pop() ?? location.file}${batch.length > 1 ? ` +${batch.length - 1}` : ""}`,
+    tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
+  } as const;
+  if (batch.length === 1) {
+    const candidate = batch[0]!;
+    const judged = await api.agent(`${verifierPrompt(batch)}\nCandidate record: ${JSON.stringify(candidate)}`, { ...options, profile: "small", schema: AdvisoryVerdictSchema });
+    recordVerdictProgress(api.progress, candidate, judged);
+    return [{ ...candidate, verdict: judged.verdict, evidence: judged.evidence }];
+  }
+  // One agent does several verifiers' work, so it gets the medium route.
+  const judged = await api.agent(`${verifierPrompt(batch)}\nCandidate records: ${JSON.stringify(batch)}`, { ...options, profile: "medium", schema: AdvisoryBatchVerdictSchema });
+  const verdicts = new Map(judged.verdicts.map((verdict) => [verdict.candidateId, verdict]));
+  return batch.map((candidate) => {
+    const verdict = verdicts.get(candidate.candidateId) ?? { verdict: "NOT_SUBSTANTIATED" as const, evidence: ["The batch verifier returned no verdict for this candidate."] };
+    recordVerdictProgress(api.progress, candidate, verdict);
+    return { ...candidate, verdict: verdict.verdict, evidence: verdict.evidence };
+  });
+}
+
 /** TypeSafe Jev routes in preference order. Jev is the classifier the duplicate merge was measured with. */
 export const DUPLICATE_CANDIDATE_CLASSIFIERS = [
   "typesafe/jev-latest",

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)}`,