pi-extensible-workflows 3.2.0 → 3.3.0

package/dist/src/index.d.ts

@@ -6,9 +6,10 @@ export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";
 export * from "./workflow-artifacts.js";
+export * from "./bundles.js";
 export { default } from "./host.js";
-export { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
-export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PendingWorkflowDecision, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
+export { acquireSessionLease, hasLiveSessionLease, listPersistedSessionIds, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
+export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PendingWorkflowDecision, PersistedOwnershipNode, PersistedRun, RunSummary, RunSummaryAgent, RunSummaryArtifacts, WorktreeReference } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
 export type { AgentAttempt, AgentBudgetHooks, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentProviderFailure, AgentProviderRecovery, AgentToolCallProgress, AgentSetup, AgentSetupContext, AgentSetupHook, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";

package/dist/src/index.js

@@ -6,8 +6,9 @@ export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";
 export * from "./workflow-artifacts.js";
+export * from "./bundles.js";
 export { default } from "./host.js";
-export { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
+export { acquireSessionLease, hasLiveSessionLease, listPersistedSessionIds, projectSessionsDirectory, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 export { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";

package/dist/src/persistence.d.ts

@@ -1,4 +1,4 @@
-import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowRunEvent } from "./types.js";
+import type { BudgetApprovalRequest, JsonValue, LaunchSnapshot, RunRecord, WorkflowBudgetUsage, WorkflowRunEvent } from "./types.js";
 import type { OwnershipRecord } from "./agent-execution.js";
 export interface NativeSessionReference {
     sessionId: string;
@@ -14,6 +14,40 @@ export interface EffectiveSystemPrompt {
 export interface PersistedRun extends RunRecord {
     nativeSessions: readonly NativeSessionReference[];
 }
+export interface RunSummaryAgent {
+    id: string;
+    name: string;
+    label?: string;
+    state: string;
+    role?: string;
+    attempts: number;
+}
+export interface RunSummaryArtifacts {
+    runDirectory: string;
+    statePath: string;
+    journalPath: string;
+    snapshotPath: string;
+    workflowPath: string;
+    resultPath: string;
+    summaryPath: string;
+}
+export interface RunSummary {
+    schemaVersion: 1;
+    runId: string;
+    sessionId: string;
+    workflowName: string;
+    state: RunRecord["state"];
+    createdAt: string;
+    updatedAt: string;
+    terminalAt?: string;
+    usage: WorkflowBudgetUsage;
+    agents: readonly RunSummaryAgent[];
+    error?: RunRecord["error"];
+    failedAt?: string;
+    replayablePaths: readonly string[];
+    incompletePaths: readonly string[];
+    artifacts: RunSummaryArtifacts;
+}
 export interface CompletedOperation {
     path: string;
     value: JsonValue;
@@ -41,6 +75,7 @@ export interface BorrowedWorktreeBinding {
 export declare function projectStorageKey(cwd: string): string;
 export declare function projectSessionsDirectory(cwd: string, home?: string): string;
 export declare function runsDirectory(cwd: string, sessionId: string, home?: string): string;
+export declare function listPersistedSessionIds(cwd: string, home?: string): Promise<string[]>;
 export declare function hasLiveSessionLease(cwd: string, sessionId: string, home?: string): Promise<boolean>;
 export declare class SessionLease {
     #private;
@@ -63,6 +98,7 @@ export declare class RunStore {
     readonly directory: string;
     private journalWrite;
     private stateWrite;
+    private summaryWrite;
     private worktreeWrite;
     private borrowedWorktreeWrite;
     private snapshotWrite;
@@ -70,11 +106,14 @@ export declare class RunStore {
     private systemPromptWrite;
     constructor(cwd: string, sessionId: string, runId: string, home?: string);
     create(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>): Promise<void>;
+    private refreshSummary;
+    private refreshSummaryBestEffort;
     isComplete(): Promise<boolean>;
     load(): Promise<{
         run: PersistedRun;
         snapshot: Readonly<LaunchSnapshot>;
     }>;
+    loadSummary(): Promise<RunSummary>;
     saveState(run: PersistedRun): Promise<void>;
     updateState(update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>): Promise<PersistedRun>;
     saveSnapshot(snapshot: Readonly<LaunchSnapshot>): Promise<void>;

package/dist/src/persistence.js

@@ -7,6 +7,16 @@ import { homedir } from "node:os";
 import { promisify } from "node:util";
 import { WorkflowError } from "./types.js";
 import { loadLaunchSnapshot } from "./utils.js";
+const TERMINAL_SUMMARY_STATES = new Set(["completed", "failed", "stopped"]);
+const EMPTY_USAGE = { tokens: 0, costUsd: 0, durationMs: 0, agentLaunches: 0 };
+function summaryArtifacts(directory) { return { runDirectory: directory, statePath: join(directory, "state.json"), journalPath: join(directory, "journal.json"), snapshotPath: join(directory, "snapshot.json"), workflowPath: join(directory, "workflow.js"), resultPath: join(directory, "result.json"), summaryPath: join(directory, "summary.json") }; }
+function summaryFromRun(run, directory, journal, previous, fallbackCreatedAt, now = new Date().toISOString()) {
+    const createdAt = typeof previous?.createdAt === "string" ? previous.createdAt : fallbackCreatedAt;
+    const failedAt = run.failedAt ?? run.error?.failedAt;
+    const replayablePaths = [...new Set([...(run.retry?.completedPaths ?? []), ...Object.keys(journal.completed)])];
+    const incompletePaths = [...new Set([...(run.retry?.incompletePaths ?? []), ...(failedAt ? [failedAt] : [])])];
+    return { schemaVersion: 1, runId: run.id, sessionId: run.sessionId, workflowName: run.workflowName, state: run.state, createdAt, updatedAt: now, ...(previous?.terminalAt || TERMINAL_SUMMARY_STATES.has(run.state) ? { terminalAt: previous?.terminalAt ?? now } : {}), usage: { ...EMPTY_USAGE, ...(run.usage ?? {}) }, agents: run.agents.map(({ id, name, label, state, role, attempts }) => ({ id, name, ...(label ? { label } : {}), state, ...(role ? { role } : {}), attempts })), ...(run.error ? { error: run.error } : {}), ...(failedAt ? { failedAt } : {}), replayablePaths, incompletePaths, artifacts: summaryArtifacts(directory) };
+}
 const execute = promisify(execFile);
 const gitIdentity = {
     GIT_AUTHOR_NAME: "pi-extensible-workflows", GIT_AUTHOR_EMAIL: "pi-extensible-workflows@localhost", GIT_COMMITTER_NAME: "pi-extensible-workflows", GIT_COMMITTER_EMAIL: "pi-extensible-workflows@localhost",
@@ -24,6 +34,17 @@ export function projectSessionsDirectory(cwd, home = homedir()) {
 export function runsDirectory(cwd, sessionId, home = homedir()) {
     return join(projectSessionsDirectory(cwd, home), safePart(sessionId), "runs");
 }
+export async function listPersistedSessionIds(cwd, home = homedir()) {
+    try {
+        const entries = await readdir(projectSessionsDirectory(cwd, home), { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map(({ name }) => name);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
 const SESSION_OWNER_FILE = "owner.json";
 const SESSION_OWNER_WRITE_GRACE_MS = 30_000;
 const RUN_CREATE_TEMP = /^\.([a-zA-Z0-9._-]+)\.(\d+)\.[0-9a-f-]+\.tmp$/;
@@ -236,6 +257,7 @@ export class RunStore {
     journalWrite = Promise.resolve();
     // ponytail: serializes one RunStore instance; cross-process run sharing remains unsupported.
     stateWrite = Promise.resolve();
+    summaryWrite = Promise.resolve();
     worktreeWrite = Promise.resolve();
     borrowedWorktreeWrite = Promise.resolve();
     snapshotWrite = Promise.resolve();
@@ -265,6 +287,7 @@ export class RunStore {
             await atomicJson(join(temporary, "borrowed-worktrees.json"), []);
             await atomicJson(join(temporary, "state.json"), run);
             await atomicJson(join(temporary, "system-prompts.json"), { version: 1, entries: [] });
+            await atomicJson(join(temporary, "summary.json"), summaryFromRun(run, this.directory, { completed: {} }, undefined, new Date().toISOString()));
             await rename(temporary, this.directory);
         }
         catch (error) {
@@ -272,6 +295,18 @@ export class RunStore {
             throw error;
         }
     }
+    async refreshSummary() {
+        const write = this.summaryWrite.then(async () => {
+            const run = await json(join(this.directory, "state.json"));
+            const journal = await json(join(this.directory, "journal.json"));
+            const previous = await json(join(this.directory, "summary.json")).catch(() => undefined);
+            const fallbackCreatedAt = await stat(join(this.directory, "state.json")).then((value) => new Date(value.mtimeMs).toISOString());
+            await atomicJson(join(this.directory, "summary.json"), summaryFromRun(run, this.directory, journal, previous, fallbackCreatedAt));
+        });
+        this.summaryWrite = write.catch(() => undefined);
+        await write;
+    }
+    refreshSummaryBestEffort() { void this.refreshSummary().catch(() => undefined); }
     async isComplete() {
         try {
             await Promise.all([access(join(this.directory, "snapshot.json")), access(join(this.directory, "journal.json")), access(join(this.directory, "ownership.json")), access(join(this.directory, "state.json"))]);
@@ -288,11 +323,25 @@ export class RunStore {
             throw new WorkflowError("RESUME_INCOMPATIBLE", "Persisted run belongs to another cwd or Pi session");
         return { run, snapshot: loadLaunchSnapshot(await json(join(this.directory, "snapshot.json"))) };
     }
+    async loadSummary() {
+        await this.stateWrite;
+        await this.journalWrite;
+        await this.summaryWrite;
+        const run = await json(join(this.directory, "state.json"));
+        const journal = await json(join(this.directory, "journal.json"));
+        const previous = await json(join(this.directory, "summary.json")).catch(() => undefined);
+        const [stateStat, journalStat] = await Promise.all([stat(join(this.directory, "state.json")), stat(join(this.directory, "journal.json"))]);
+        const fallbackCreatedAt = new Date(stateStat.mtimeMs).toISOString();
+        const previousUpdatedAt = previous?.updatedAt === undefined ? Number.NaN : Date.parse(previous.updatedAt);
+        const updatedAt = new Date(Math.max(stateStat.mtimeMs, journalStat.mtimeMs, Number.isNaN(previousUpdatedAt) ? 0 : previousUpdatedAt)).toISOString();
+        return summaryFromRun(run, this.directory, journal, previous, fallbackCreatedAt, updatedAt);
+    }
     async saveState(run) {
         const write = this.stateWrite.then(async () => {
             if (resolve(run.cwd) !== this.cwd || run.sessionId !== this.sessionId || run.id !== this.runId)
                 throw new WorkflowError("INTERNAL_ERROR", "Run identity does not match its session-scoped store");
             await atomicJson(join(this.directory, "state.json"), run);
+            this.refreshSummaryBestEffort();
         });
         this.stateWrite = write.catch(() => undefined);
         await write;
@@ -307,6 +356,7 @@ export class RunStore {
             if (resolve(result.cwd) !== this.cwd || result.sessionId !== this.sessionId || result.id !== this.runId)
                 throw new WorkflowError("INTERNAL_ERROR", "Run identity does not match its session-scoped store");
             await atomicJson(join(this.directory, "state.json"), result);
+            this.refreshSummaryBestEffort();
         });
         this.stateWrite = write.catch(() => undefined);
         await write;
@@ -351,6 +401,7 @@ export class RunStore {
             journal.awaiting ??= {};
             result = await update(journal);
             await atomicJson(journalPath, journal);
+            this.refreshSummaryBestEffort();
         });
         this.journalWrite = write.catch(() => undefined);
         await write;

package/dist/src/session-inspector.d.ts

@@ -1,6 +1,6 @@
 import { type SessionEntry, type SessionInfo } from "@earendil-works/pi-coding-agent";
 import { type AgentSetupSummary, type ModelSpec, type StaticWorkflowCall } from "./index.js";
-import { type PersistedRun } from "./persistence.js";
+import { type PersistedRun, type RunSummary } from "./persistence.js";
 export interface ModelUsage {
     model: string;
     cost: number;
@@ -62,11 +62,21 @@ export interface InspectorViewState {
     selected: number;
     scroll: number;
 }
+export type InspectMode = "tui" | "json" | "summary";
+export interface PersistedSessionSummary {
+    schemaVersion: 1;
+    cwd: string;
+    sessionId: string;
+    runs: readonly RunSummary[];
+}
 export declare function transcriptLines(entries: readonly SessionEntry[]): string[];
 export declare function transcriptFileLines(path: string): string[];
 export declare function matchSession(query: string, sessions: readonly SessionInfo[]): SessionInfo;
 export declare function loadSessionReport(path: string, home?: string): Promise<SessionReport>;
 export declare function renderInspector(report: SessionReport, state: InspectorViewState, width?: number, height?: number, highlighter?: (script: string) => string[]): string[];
+export declare function loadPersistedSessionSummary(cwd: string, sessionId: string, home?: string, failedOnly?: boolean): Promise<PersistedSessionSummary>;
+export declare function loadPersistedSummaries(cwd: string, sessionId: string | undefined, home?: string, failedOnly?: boolean): Promise<readonly PersistedSessionSummary[]>;
+export declare function formatPersistedRunSummary(summary: RunSummary, sessionId?: string): string;
 export declare function showSessionInspector(report: SessionReport): Promise<void>;
 export declare function resolveSession(query: string, sessionDir?: string | undefined): Promise<SessionInfo>;
-export declare function runSessionInspector(sessionId?: string): Promise<void>;
+export declare function runSessionInspector(sessionId?: string, mode?: InspectMode, cwd?: string, home?: string, write?: (text: string) => void, failedOnly?: boolean): Promise<void>;

package/dist/src/session-inspector.js

@@ -5,7 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { highlightCode, initTheme, SessionManager, truncateToVisualLines } from "@earendil-works/pi-coding-agent";
 import { formatBudgetStatus, inspectWorkflowScript } from "./index.js";
-import { listRunIds, RunStore } from "./persistence.js";
+import { listPersistedSessionIds, listRunIds, RunStore } from "./persistence.js";
 function text(content) {
     if (typeof content === "string")
         return content;
@@ -346,6 +346,28 @@ export function renderInspector(report, state, width = 80, height = 24, highligh
     const scroll = Math.max(0, Math.min(state.scroll, Math.max(0, fitted.length - room)));
     return [...header, ...fitted.slice(scroll, scroll + room), ...footer].slice(0, height);
 }
+export async function loadPersistedSessionSummary(cwd, sessionId, home = homedir(), failedOnly = false) {
+    const runs = [];
+    for (const runId of (await listRunIds(cwd, sessionId, home)).sort()) {
+        try {
+            const summary = await new RunStore(cwd, sessionId, runId, home).loadSummary();
+            if (!failedOnly || summary.state === "failed")
+                runs.push(summary);
+        }
+        catch { /* Ignore corrupt or concurrently removed runs. */ }
+    }
+    return { schemaVersion: 1, cwd, sessionId, runs };
+}
+export async function loadPersistedSummaries(cwd, sessionId, home = homedir(), failedOnly = false) {
+    const sessionIds = sessionId ? [sessionId] : (await listPersistedSessionIds(cwd, home)).sort();
+    const sessions = await Promise.all(sessionIds.map((id) => loadPersistedSessionSummary(cwd, id, home, failedOnly)));
+    return sessionId || !failedOnly ? sessions : sessions.filter((session) => session.runs.length > 0);
+}
+export function formatPersistedRunSummary(summary, sessionId = summary.sessionId) {
+    const counts = summary.agents.reduce((result, agent) => { result[agent.state] = (result[agent.state] ?? 0) + 1; return result; }, {});
+    const status = Object.entries(counts).map(([state, count]) => `${state}=${String(count)}`).join(", ") || "agents=0";
+    return `${sessionId} ${summary.runId} ${summary.workflowName} ${summary.state} ${status} updated=${summary.updatedAt}`;
+}
 function nextState(current, key, workflowCount) {
     if (current.view === "list") {
         if (key === "up")
@@ -410,7 +432,19 @@ async function askSessionId() {
 export async function resolveSession(query, sessionDir = process.env.PI_CODING_AGENT_SESSION_DIR) {
     return matchSession(query, await SessionManager.listAll(sessionDir));
 }
-export async function runSessionInspector(sessionId) {
+export async function runSessionInspector(sessionId, mode = "tui", cwd = process.cwd(), home = homedir(), write = (text) => { stdout.write(text); }, failedOnly = false) {
+    if (mode !== "tui") {
+        const sessions = await loadPersistedSummaries(cwd, sessionId?.trim() || undefined, home, failedOnly);
+        if (mode === "json") {
+            const value = sessionId?.trim() ? sessions[0] : undefined;
+            write(`${JSON.stringify(value ?? { schemaVersion: 1, cwd, sessions })}\n`);
+            return;
+        }
+        const emptyLabel = failedOnly ? "no failed runs" : "no persisted runs";
+        const lines = sessions.flatMap((session) => session.runs.length ? session.runs.map((run) => formatPersistedRunSummary(run, session.sessionId)) : [`${session.sessionId} (${emptyLabel})`]);
+        write(`${lines.length ? lines.join("\n") : failedOnly ? "No failed workflow runs." : "No persisted workflow runs."}\n`);
+        return;
+    }
     const query = sessionId?.trim() || await askSessionId();
     if (!query)
         throw new Error("Session ID is required.");

package/dist/src/types.d.ts

@@ -83,6 +83,7 @@ export interface BudgetApprovalRequest {
 export interface WorkflowErrorShape {
     code: WorkflowErrorCode;
     message: string;
+    failedAt?: string;
 }
 export interface WorkflowEventBase {
     runId: string;
@@ -201,6 +202,7 @@ export interface AgentActivity {
     kind: "reasoning" | "tool" | "text";
     text: string;
 }
+export declare const WORKFLOW_AGENT_STALL_THRESHOLD_MS: number;
 export interface AgentAccounting {
     input: number;
     output: number;
@@ -279,6 +281,14 @@ export interface AgentRecord {
         state: "running" | "completed" | "failed";
     }[];
     activity?: AgentActivity | undefined;
+    lastEventAt?: number;
+}
+export type WorkflowDeliveryMode = "foreground" | "background";
+export type WorkflowDeliveryStatus = "attached" | "pending" | "delivered";
+export interface WorkflowRunDelivery {
+    mode: WorkflowDeliveryMode;
+    state: WorkflowDeliveryStatus;
+    toolCallId?: string;
 }
 export interface WorkflowRunEvent {
     type: string;
@@ -306,26 +316,32 @@ export interface RunRecord {
     phase?: string;
     phaseHistory?: readonly WorkflowPhaseRecord[];
     agents: readonly AgentRecord[];
+    activeShells?: number;
     error?: WorkflowErrorShape;
+    failedAt?: string;
     budget?: WorkflowBudget;
     budgetVersion?: number;
     usage?: WorkflowBudgetUsage;
     budgetEvents?: readonly BudgetEvent[];
     events?: readonly WorkflowRunEvent[];
+    delivery?: WorkflowRunDelivery;
 }
 export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export type WorkflowLaunchMode = "foreground" | "background";
 export interface AgentDefinition {
     prompt?: string;
     description?: string;
     model?: string;
     thinking?: NonNullable<ModelSpec["thinking"]>;
     tools?: readonly string[];
+    overrideSystemPrompt?: boolean;
     disabledAgentResources?: AgentResourceExclusions;
 }
 export interface LaunchSnapshot {
     identityVersion?: number;
     launchKind?: "inline" | "function";
     functionName?: string;
+    launchMode?: WorkflowLaunchMode;
     script: string;
     args: JsonValue;
     metadata: WorkflowMetadata;
@@ -449,8 +465,10 @@ export interface SessionInput {
     agentDir?: string;
     customTools?: SessionCustomTools;
     resultTool?: ToolDefinition;
+    systemPrompt?: string;
     systemPromptAppend?: string;
     extensionFactories?: InlineExtension[];
+    additionalSkillPaths?: readonly string[];
     resourcePolicy?: AgentResourcePolicy;
     options?: AgentOptions;
 }

package/dist/src/types.js

@@ -16,6 +16,7 @@ export const ERROR_CODES = [
     "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID",
     "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
 ];
+export const WORKFLOW_AGENT_STALL_THRESHOLD_MS = 10 * 60 * 1000;
 export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
 export class WorkflowError extends Error {
     code;

package/dist/src/validation.js

@@ -180,7 +180,7 @@ export function parseRoleMarkdown(content, strict = false, rolePath) {
             return { prompt: content };
         const meta = {};
         for (const line of content.slice(4, end).split("\n")) {
-            const match = /^(model|thinking|tools|description)\s*:\s*(.+)$/.exec(line.trim());
+            const match = /^(model|thinking|tools|description|overrideSystemPrompt|override_system_prompt|is_system_prompt)\s*:\s*(.+)$/.exec(line.trim());
             if (match?.[1] && match[2])
                 meta[match[1]] = match[2].trim();
         }
@@ -197,6 +197,9 @@ export function parseRoleMarkdown(content, strict = false, rolePath) {
             definition.thinking = thinking;
         if (tools)
             definition.tools = tools;
+        const overrideSystemPrompt = meta.overrideSystemPrompt ?? meta.override_system_prompt ?? meta.is_system_prompt;
+        if (overrideSystemPrompt)
+            definition.overrideSystemPrompt = overrideSystemPrompt === "true";
         return definition;
     }
     const normalized = content.replace(/\r\n?/g, "\n");
@@ -212,16 +215,19 @@ export function parseRoleMarkdown(content, strict = false, rolePath) {
     if (!object(parsed.frontmatter))
         fail("INVALID_METADATA", "Role frontmatter must be an object");
     const { model, thinking, tools, description, disabledAgentResources } = parsed.frontmatter;
+    const overrideSystemPrompt = parsed.frontmatter.overrideSystemPrompt ?? parsed.frontmatter.override_system_prompt ?? parsed.frontmatter.is_system_prompt;
     if (model !== undefined && (typeof model !== "string" || model.trim() === ""))
         fail("INVALID_METADATA", "Role model must be a non-empty string");
     if (thinking !== undefined && (typeof thinking !== "string" || !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinking)))
         fail("INVALID_METADATA", `Invalid role thinking level: ${typeof thinking === "string" ? thinking : typeof thinking}`);
     if (description !== undefined && (typeof description !== "string" || description.trim() === "" || description.length > 1024 || /[\r\n]/.test(description)))
         fail("INVALID_METADATA", "Role description must be a non-empty single-line string of at most 1024 characters");
+    if (overrideSystemPrompt !== undefined && typeof overrideSystemPrompt !== "boolean")
+        fail("INVALID_METADATA", "Role overrideSystemPrompt must be a boolean");
     if (tools !== undefined && (!Array.isArray(tools) || tools.some((tool) => typeof tool !== "string" || tool.trim() === "")))
         fail("INVALID_METADATA", "Role tools must be an array of non-empty strings");
     const normalizedResources = validateAgentResourceExclusions(disabledAgentResources, rolePath ?? "<role>", "INVALID_METADATA");
-    return { prompt: parsed.body, ...(typeof description === "string" ? { description: description.trim() } : {}), ...(typeof model === "string" ? { model: model.trim() } : {}), ...(typeof thinking === "string" ? { thinking: thinking } : {}), ...(Array.isArray(tools) ? { tools: tools.map((tool) => tool.trim()) } : {}), ...(normalizedResources ? { disabledAgentResources: normalizedResources } : {}) };
+    return { prompt: parsed.body, ...(typeof description === "string" ? { description: description.trim() } : {}), ...(typeof model === "string" ? { model: model.trim() } : {}), ...(typeof thinking === "string" ? { thinking: thinking } : {}), ...(Array.isArray(tools) ? { tools: tools.map((tool) => tool.trim()) } : {}), ...(typeof overrideSystemPrompt === "boolean" ? { overrideSystemPrompt } : {}), ...(normalizedResources ? { disabledAgentResources: normalizedResources } : {}) };
 }
 const ROLE_DIRECTORY = "pi-extensible-workflows";
 export function workflowRoleDirectories(agentDir = getAgentDir()) {

package/dist/src/workflow-evals.d.ts

@@ -74,6 +74,10 @@ export interface ParentToolResult {
     isError?: boolean;
     text?: string;
 }
+export interface ParentToolCall {
+    name: string;
+    arguments: JsonValue;
+}
 export interface ParentUsage {
     input: number;
     output: number;
@@ -216,13 +220,14 @@ export interface EvalCaseResult {
         realWorkflowAgentsLaunched: number | null;
     };
 }
-export declare const SAFE_PARENT_EVAL_TOOLS: readonly ["read", "grep", "find", "bash", "workflow"];
+export declare const SAFE_PARENT_EVAL_TOOLS: readonly ["read", "grep", "find", "bash", "workflow", "workflow_retry"];
 export declare function validateWorkflowEvalCases(values: readonly unknown[], source?: string): readonly WorkflowEvalCase[];
 export declare function loadWorkflowEvalCases(directory?: string): readonly WorkflowEvalCase[];
 export declare const INITIAL_WORKFLOW_EVAL_CASES: readonly WorkflowEvalCase[];
 export declare function matchesJsonResult(shape: JsonResultShape, value: JsonValue): boolean;
 export declare function matchesOutputSchema(shape: OutputSchemaShape, schema: JsonSchema): boolean;
 export declare function extractParentOracle(entries: readonly unknown[]): ParentOracle;
+export declare function extractParentToolCalls(oracle: ParentOracle): ParentToolCall[];
 export declare function extractParentOracleFile(path: string): ParentOracle;
 export declare function extractCapturedWorkflows(oracle: ParentOracle): CapturedWorkflowCall[];
 export declare function captureValidationReports(oracle: ParentOracle, calls: readonly CapturedWorkflowCall[]): {
@@ -231,6 +236,7 @@ export declare function captureValidationReports(oracle: ParentOracle, calls: re
     verified: boolean;
 };
 export declare function evalExpectationErrors(oracle: ParentOracle, expectations: EvalExpectations): string[];
+export declare function recoverySelectionErrors(evalCase: Pick<WorkflowEvalCase, "id">, oracle: ParentOracle): string[];
 export declare function replayExpectationErrors(calls: readonly CapturedWorkflowCall[], reports: readonly ReplayReport[], expectations: EvalExpectations): string[];
 export declare function staticExpectationResults(calls: readonly CapturedWorkflowCall[], expectations: EvalExpectations): CriterionResult[];
 export declare function selectStaticCandidate(calls: readonly CapturedWorkflowCall[], validations: readonly ProductionValidationReport[], expectations: EvalExpectations, requiredCount?: number): {

package/dist/src/workflow-evals.js

@@ -10,7 +10,7 @@ import { CAPTURE_ERROR_PREFIX, CAPTURE_IDENTITY, resolveWorkflowSkillPath } from
 export { resolveWorkflowSkillPath } from "./eval-capture-extension.js";
 import { ERROR_CODES, inspectWorkflowScript, isObject, loadAgentDefinitions, runWorkflow, WORKFLOW_CALL_KINDS, WorkflowError } from "./index.js";
 const CASE_PROCESS_GRACE_MS = 1_000;
-export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "bash", "workflow"]);
+export const SAFE_PARENT_EVAL_TOOLS = Object.freeze(["read", "grep", "find", "bash", "workflow", "workflow_retry"]);
 const EVAL_MODEL_TOKEN = "$EVAL_MODEL";
 const semantic = (description) => [{ id: "intent", description }];
 const JSON_RESULT_TYPES = ["null", "boolean", "number", "integer", "string", "array", "object"];
@@ -367,6 +367,13 @@ export function extractParentOracle(entries) {
     }
     return { assistantBatches: batches, workflowToolResults, skillReads, ...(firstSignificantAction ? { firstSignificantAction } : {}), ...(parentToolSequence[0] ? { firstTool: parentToolSequence[0] } : {}), firstBatchToolSequence: firstBatch?.tools ?? [], toolsBeforeFirstWorkflow: firstWorkflowIndex < 0 ? parentToolSequence : parentToolSequence.slice(0, firstWorkflowIndex), firstWorkflowBatchToolSequence: firstWorkflowBatch?.tools ?? [], parentToolSequence, workflowCallCount: parentToolSequence.filter((name) => name === "workflow").length, usage: { ...totals, models: [...modelCosts].map(([model, cost]) => ({ model, cost })) } };
 }
+export function extractParentToolCalls(oracle) {
+    return oracle.assistantBatches.flatMap(({ parts }) => parts.flatMap((part) => {
+        if (!isObject(part) || part.type !== "toolCall" || typeof part.name !== "string")
+            return [];
+        return [{ name: part.name, arguments: isJson(part.arguments) ? part.arguments : null }];
+    }));
+}
 export function extractParentOracleFile(path) {
     const entries = readFileSync(path, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
     return extractParentOracle(entries);
@@ -434,6 +441,19 @@ export function evalExpectationErrors(oracle, expectations) {
     }
     return errors;
 }
+const RECOVERY_SELECTIONS = {
+    "recovery-failed-run": { tool: "workflow_retry", arguments: { runId: "failed-run-42" } },
+    "recovery-completed-worktree": { tool: "workflow", arguments: { name: "borrow-worktree", script: "return true;", parentRunId: "completed-run-42" } },
+};
+export function recoverySelectionErrors(evalCase, oracle) {
+    const expected = RECOVERY_SELECTIONS[evalCase.id];
+    if (!expected)
+        return [];
+    const actual = extractParentToolCalls(oracle);
+    if (actual.length === 1 && actual[0]?.name === expected.tool && equalJson(actual[0].arguments, expected.arguments))
+        return [];
+    return [`${evalCase.id} parent tool calls were ${JSON.stringify(actual)}; expected ${JSON.stringify([expected])}`];
+}
 export function replayExpectationErrors(calls, reports, expectations) {
     const errors = [];
     const staticCalls = calls.flatMap((call) => { try {
@@ -862,7 +882,7 @@ function semanticJudgePrompt(evalCase, calls, cwd, home) {
     } }));
     const roleText = [...usedRoles].map((role) => `${role}: ${roles[role]?.description ?? "no description"}`).join("\n") || "none";
     const docs = "agent(prompt, options) delegates; shell(command, options) runs a deterministic host command and returns exitCode/stdout/stderr; parallel(name, tasks) runs independent tasks concurrently; pipeline(name, items, stages) applies ordered stages; prompt(template, data) carries values into prompts. A role owns model/thinking/tools policy.";
-    return `Judge whether the captured workflow design satisfies each criterion. Do not execute it. Return only JSON: {"criteria":[{"id":"criterion id","pass":true,"evidence":"specific script evidence"}]}.\n\nOriginal request:\n${evalCase.prompt}\n\nCriteria:\n${JSON.stringify(evalCase.semanticCriteria ?? [])}\n\nDSL:\n${docs}\n\nRelevant roles:\n${roleText}\n\nCaptured workflow script(s):\n${calls.map((call, index) => `--- ${String(index)} ---\n${call.script ?? "<missing>"}`).join("\n")}`;
+    return `Judge whether the captured workflow design satisfies each criterion. Do not execute it. Return only JSON: {"criteria":[{"id":"criterion id","pass":true,"evidence":"specific script evidence"}]}.\n\nOriginal request:\n${evalCase.prompt}\n\nCriteria:\n${JSON.stringify(evalCase.semanticCriteria ?? [])}\n\nDSL:\n${docs}\n\nRelevant roles:\n${roleText}\n\nCaptured workflow call(s):\n${calls.map((call, index) => `--- ${String(index)} ---\nArguments:\n${JSON.stringify(call.arguments)}\nScript:\n${call.script ?? "<missing>"}`).join("\n")}`;
 }
 async function runSemanticJudge(input, calls, cwd, home, sessionDir, maxCost) {
     const args = ["--offline", "--no-extensions", "--no-skills", "--no-context-files", "--no-tools", "--mode", "json", "--session-dir", sessionDir, "--session-id", randomUUID()];
@@ -1045,7 +1065,7 @@ export async function captureEvalCase(input) {
         const parentUsageThroughCandidate = usageThroughCandidate(oracle, workflows, selection.callIndices);
         const parentAccounting = parentUsageThroughCandidate ?? oracle.usage;
         const unsafeTool = oracle.parentToolSequence.find((tool) => !SAFE_PARENT_EVAL_TOOLS.includes(tool));
-        const errors = [...evalExpectationErrors(oracle, input.case.expectations), ...validation.errors, ...(unsafeTool ? [`parent tool is outside the safe eval allowlist: ${unsafeTool}`] : [])];
+        const errors = [...evalExpectationErrors(oracle, input.case.expectations), ...recoverySelectionErrors(input.case, oracle), ...validation.errors, ...(unsafeTool ? [`parent tool is outside the safe eval allowlist: ${unsafeTool}`] : [])];
         if (requiredCount > 0 && selection.callIndices.length === 0)
             errors.push("Catastrophic validity failure: no production-valid workflow candidate satisfied static expectations.");
         let judge;

package/evals/cases/recovery-completed-worktree.yaml

@@ -0,0 +1,17 @@
+id: recovery-completed-worktree
+prompt: >-
+  The completed workflow run ID is "completed-run-42". You need a new workflow to do named worktree work,
+  so launch the workflow with exactly parentRunId "completed-run-42". Use exactly the workflow arguments {"name":"borrow-worktree","script":"return true;","parentRunId":"completed-run-42"}.
+  Do not call workflow_retry because the source is completed and parentRunId only borrows the named worktree; it does not replay or resume.
+maxCost: 0.1
+expectations:
+  firstTool: workflow
+  firstBatchToolSequence:
+    startsWith: [workflow]
+  parentToolSequence:
+    startsWith: [workflow]
+  workflowCallCount: 1
+expectedWorkflowCalls: 1
+semanticCriteria:
+  - id: parent-run-id
+    description: The captured workflow call has exactly name borrow-worktree, script return true;, and parentRunId completed-run-42; it does not call workflow_retry.

package/evals/cases/recovery-failed-run.yaml

@@ -0,0 +1,14 @@
+id: recovery-failed-run
+prompt: >-
+  A workflow failure diagnostic identifies the persisted failed run ID "failed-run-42" and says the exact next action is
+  workflow_retry({ runId: "failed-run-42" }). Select that recovery tool now with exactly {"runId":"failed-run-42"}.
+  Do not launch a new workflow, use parentRunId, or answer with prose.
+maxCost: 0.1
+expectedWorkflowCalls: 0
+expectations:
+  firstTool: workflow_retry
+  firstBatchToolSequence:
+    equals: [workflow_retry]
+  parentToolSequence:
+    equals: [workflow_retry]
+  workflowCallCount: 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {

package/skills/pi-extensible-workflows/SKILL.md

@@ -32,9 +32,9 @@ Inline launches require a non-empty `name`. Registered function launches must om
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
-Recovery map: `agent(..., { retries })` reruns one agent call in the same run for transient failures; `workflow_retry({ runId })` replays a failed run into a child; `workflow_resume({ runId, budget? })` continues a `budget_exhausted` run; `parentRunId` on a new launch only borrows named worktrees and never replays or resumes. Use each only for its stated case.
+Recovery map: `agent(..., { retries })` reruns one agent call in the same run for transient failures; `workflow_retry({ runId, foreground? })` replays a failed run into a child; `workflow_resume({ runId, budget?, foreground? })` continues a `budget_exhausted` run; recovery inherits the source snapshot's foreground/background launch mode, while legacy snapshots without `launchMode` recover in background; set `foreground: true` or `false` to override it; `parentRunId` on a new launch only borrows named worktrees and never replays or resumes. Use each only for its stated case.
 For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. External side effects before failure are not guaranteed exactly once.
-Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
+Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground launches and foreground recovery retain their terminal value and completed `runId`, while background launches and recovery return `runId` immediately and deliver completion or failure as a follow-up. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
 Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task.
 
 Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.