pi-workflow-engine 1.1.0 → 1.3.0

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,8 +471,10 @@ export async function runWorkflowWithContext(
     log: scope.log,
     progress: scope.event,
     args,
+    input,
     cwd: rc.cwd,
     budget: rc.budget,
+    agents: { max: rc.agentLimiter.maxAgents, remaining: () => rc.agentLimiter.remaining() },
     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 {

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

@@ -69,7 +69,9 @@ export class ProgressTracker {
   private readonly lanes = new Map<string, WorkflowLaneItem[]>();
   private readonly laneOverflow = new Map<string, number>();
   private readonly rowsById = new Map<number, AgentRow>();
-  private readonly agentCounts: Record<AgentRowStatus, number> = { queued: 0, running: 0, done: 0, failed: 0 };
+  /** How to abort each running row's agent; never part of a snapshot, so it is never persisted. */
+  private readonly skipHandlers = new Map<number, () => void>();
+  private readonly agentCounts: Record<AgentRowStatus, number> = { queued: 0, running: 0, done: 0, failed: 0, skipped: 0 };
   private readonly startedAt = Date.now();
   private readonly laneItemLimit = laneItemLimitFromEnv();
   private doneAt: number | undefined;
@@ -168,12 +170,13 @@ export class ProgressTracker {
     return id;
   }
 
-  agentStart(id: number): void {
+  agentStart(id: number, skip?: () => void): void {
     const row = this.rowsById.get(id);
     if (row) {
       this.transitionAgentStatus(row, "running");
       row.startedAt = Date.now();
       row.error = undefined;
+      if (skip) this.skipHandlers.set(id, skip);
     }
     this.publish();
   }
@@ -188,8 +191,9 @@ export class ProgressTracker {
   }
 
   agentDone(id: number): void {
+    this.skipHandlers.delete(id);
     const row = this.rowsById.get(id);
-    if (row && row.status !== "failed") {
+    if (row && row.status !== "failed" && row.status !== "skipped") {
       this.transitionAgentStatus(row, "done");
       row.doneAt = Date.now();
     }
@@ -197,6 +201,7 @@ export class ProgressTracker {
   }
 
   agentFailed(id: number, error: unknown): void {
+    this.skipHandlers.delete(id);
     const row = this.rowsById.get(id);
     if (row) {
       this.transitionAgentStatus(row, "failed");
@@ -206,6 +211,28 @@ export class ProgressTracker {
     this.publish();
   }
 
+  agentSkipped(id: number): void {
+    this.skipHandlers.delete(id);
+    const row = this.rowsById.get(id);
+    if (row) {
+      this.transitionAgentStatus(row, "skipped");
+      row.doneAt = Date.now();
+    }
+    this.publish();
+  }
+
+  /**
+   * Abort one running agent at the user's request (the inspector's skip key); false when the row is
+   * no longer running. The row turns `skipped` once the agent's session has wound down.
+   */
+  skipAgent(id: number): boolean {
+    const skip = this.skipHandlers.get(id);
+    if (!skip || this.rowsById.get(id)?.status !== "running") return false;
+    this.skipHandlers.delete(id);
+    skip();
+    return true;
+  }
+
   updateUsage(snapshot: WorkflowUsageSnapshot): void {
     this.usageSnapshot = snapshot;
     this.publish();
@@ -238,7 +265,8 @@ export class ProgressTracker {
       running: this.agentCounts.running,
       done: this.agentCounts.done,
       failed: this.agentCounts.failed,
-      total: this.agentCounts.queued + this.agentCounts.running + this.agentCounts.done + this.agentCounts.failed,
+      skipped: this.agentCounts.skipped,
+      total: this.agentCounts.queued + this.agentCounts.running + this.agentCounts.done + this.agentCounts.failed + this.agentCounts.skipped,
     };
   }
 

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

@@ -0,0 +1,15 @@
+import type { BeforeAgentStartEventResult, NormalizedBuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+
+type PromptSectionOptions = Pick<NormalizedBuildSystemPromptOptions, "sections" | "forceSystemPrompt">;
+
+/**
+ * Finish adding the `name` section from a `before_agent_start` handler. Normally the section in
+ * `options.sections` is enough and pi appends it as a patch. An earlier handler that forced the whole
+ * prompt makes pi render no sections, so the section is appended to that text instead; pi hands the
+ * returned prompt to later handlers as their `forceSystemPrompt`, so several sections chain.
+ */
+export function appendSectionToForcedPrompt(options: PromptSectionOptions, name: string): BeforeAgentStartEventResult | undefined {
+  const text = options.sections[name];
+  if (options.forceSystemPrompt === undefined || text === undefined) return undefined;
+  return { systemPrompt: `${options.forceSystemPrompt}\n\n<${name}>\n${text}\n</${name}>` };
+}

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

@@ -29,7 +29,8 @@ export function normalizeResearchLanes(plan: ResearchPlan): ResearchLane[] {
   return lanes;
 }
 
-export function buildClaimCandidates(results: readonly ResearchLaneResult[]): ResearchClaimCandidate[] {
+/** Distinct claims, most important first, bounded to {@link MAX_VERIFICATION_CLAIMS}; `overCap` counts the claims cut. */
+export function buildClaimCandidates(results: readonly ResearchLaneResult[]): { candidates: ResearchClaimCandidate[]; overCap: number } {
   const byClaim = new Map<string, { claim: string; importance: ResearchEvidence["importance"]; evidence: ResearchEvidence[] }>();
   for (const item of results.flatMap((result) => result.evidence.map(sanitizeEvidence).filter(isDefined))) {
     const key = item.claim.toLowerCase();
@@ -41,9 +42,8 @@ export function buildClaimCandidates(results: readonly ResearchLaneResult[]): Re
     if (IMPORTANCE_RANK[item.importance] < IMPORTANCE_RANK[current.importance]) current.importance = item.importance;
     current.evidence = dedupeEvidence([...current.evidence, item]);
   }
-  return [...byClaim.values()]
-    .sort((left, right) => IMPORTANCE_RANK[left.importance] - IMPORTANCE_RANK[right.importance])
-    .slice(0, MAX_VERIFICATION_CLAIMS);
+  const ranked = [...byClaim.values()].sort((left, right) => IMPORTANCE_RANK[left.importance] - IMPORTANCE_RANK[right.importance]);
+  return { candidates: ranked.slice(0, MAX_VERIFICATION_CLAIMS), overCap: Math.max(0, ranked.length - MAX_VERIFICATION_CLAIMS) };
 }
 
 export function sanitizeVerification(

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

@@ -438,7 +438,7 @@ export async function captureWorkflowResumeContext(
   if (mod.source.kind === "unverifiable") {
     return unverifiableWorkflowResumeContext(mod.meta.name, mod.source.reason);
   }
-  if (mod.source.kind === "fingerprint") {
+  if (mod.source.kind === "fingerprint" || mod.source.selfContained) {
     return mod.source.fingerprint.length > 0
       ? { kind: "verified", name: mod.meta.name, sourceFingerprint: mod.source.fingerprint }
       : unverifiableWorkflowResumeContext(mod.meta.name, "workflow source fingerprint is empty");