pi-extensible-workflows 1.0.0 → 2.0.0

package/src/index.ts

@@ -1,24 +1,25 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { fork, type ChildProcess } from "node:child_process";
+import { fork, spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { StringDecoder } from "node:string_decoder";
 import * as acorn from "acorn";
 import { Script } from "node:vm";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
-import { copyToClipboard, getAgentDir, parseFrontmatter, highlightCode, SessionManager, truncateToVisualLines, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createNativeAgentSession, FairAgentScheduler, WorkflowAgentExecutor, type AgentActivity, type AgentAccounting, type AgentAttempt, type AgentBudgetHooks, type AgentDefinition, type AgentProgress, type AgentSetupHook, type RegisteredAgentSetupHook, type SessionFactory } from "./agent-execution.js";
-import { transcriptLines } from "./session-inspector.js";
-import { acquireSessionLease, listRunIds, RunStore, SessionLease, structuralPath as operationPath } from "./persistence.js";
+import { copyToClipboard, getAgentDir, parseFrontmatter, highlightCode, truncateToVisualLines, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createNativeAgentSession, FairAgentScheduler, WorkflowAgentExecutor, type AgentActivity, type AgentAccounting, type AgentAttempt, type AgentBudgetHooks, type AgentDefinition, type AgentProgress, type AgentProviderFailure, type AgentProviderRecovery, type AgentSetupHook, type RegisteredAgentSetupHook, type SessionFactory } from "./agent-execution.js";
+import { herdrPaneId, openHerdrPane } from "./herdr.js";
+import { acquireSessionLease, atomicWriteFile, listRunIds, RunStore, SessionLease, structuralPath as operationPath } from "./persistence.js";
 import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
 
 export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"] as const;
 export const AGENT_STATES = ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"] as const;
-export const WORKFLOW_ASYNC_STARTED_EVENT = "workflow:async-started";
-export const WORKFLOW_ASYNC_COMPLETE_EVENT = "workflow:async-complete";
+export const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"] as const;
+export type WorkflowCallKind = (typeof WORKFLOW_CALL_KINDS)[number];
 export const WORKFLOW_RUN_STARTED_EVENT = "workflow:run-started";
 export const WORKFLOW_RUN_RESUMED_EVENT = "workflow:run-resumed";
 export const WORKFLOW_RUN_STATE_CHANGED_EVENT = "workflow:run-state-changed";
@@ -32,7 +33,7 @@ export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 const SETTLED_AGENT_STATES: ReadonlySet<AgentState> = new Set(["completed", "failed", "cancelled"]);
 export const ERROR_CODES = [
   "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
-  "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID",
+  "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",
   ] as const;
 
@@ -41,6 +42,8 @@ export type AgentState = (typeof AGENT_STATES)[number];
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type JsonSchema = { [key: string]: JsonValue };
+export interface ShellOptions { timeoutMs?: number; env?: Record<string, string> }
+export interface ShellResult { exitCode: number | null; stdout: string; stderr: string }
 export type BudgetDimension = "tokens" | "costUsd" | "durationMs" | "agentLaunches";
 export interface BudgetLimits { soft?: number; hard?: number }
 export type WorkflowBudget = Partial<Record<BudgetDimension, BudgetLimits>>;
@@ -69,35 +72,72 @@ export interface AgentResourcePolicy { globalSettingsPath: string; projectSettin
 export interface AgentSetupSummary { hookNames: readonly string[]; model: ModelSpec; tools: readonly string[]; cwd: string; disabledAgentResources?: { skills: readonly string[]; extensions: readonly string[]; unmatchedSkills: readonly string[]; unmatchedExtensions: readonly string[] } }
 export interface AgentAttemptSummary { attempt: number; sessionId: string; sessionFile: string; error?: { code: string; message: string }; accounting: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; setup?: AgentSetupSummary }
 export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase { owner: string; branch: string; path: string; base: string }
+export interface WorkflowWorktreeReference { readonly path: string; readonly branch: string }
 export interface AgentRecord { id: string; name: string; label?: string; path: string; state: AgentState; parentId?: string; structuralPath?: readonly string[]; parentBreadcrumb?: string; worktreeOwner?: string; role?: string; requestedModel?: string; model: ModelSpec; tools: readonly string[]; attempts: number; attemptDetails?: readonly AgentAttemptSummary[]; accounting?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; toolCalls?: readonly { id: string; name: string; state: "running" | "completed" | "failed" }[]; activity?: AgentActivity | undefined }
-export interface WorkflowRunEvent { type: "warning"; message: string }
-export interface RunRecord { id: string; workflowName: string; cwd: string; sessionId: string; state: RunState; phase?: string; agents: readonly AgentRecord[]; error?: WorkflowErrorShape; budget?: WorkflowBudget; budgetVersion?: number; usage?: WorkflowBudgetUsage; budgetEvents?: readonly BudgetEvent[]; events?: readonly WorkflowRunEvent[] }
-export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
-export interface LaunchSnapshot { identityVersion?: number; script: string; args: JsonValue; metadata: WorkflowMetadata; settings: WorkflowSettings; budget?: WorkflowBudget; settingsPath?: string; modelAliases?: Readonly<Record<string, string>>; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[]; roles?: Readonly<Record<string, AgentDefinition>>; projectRoles?: readonly string[]; schemas: readonly JsonSchema[] }
+export interface WorkflowRunEvent { type: string; message: string }
+export interface RunRecord { id: string; workflowName: string; cwd: string; sessionId: string; state: RunState; parentRunId?: string; phase?: string; agents: readonly AgentRecord[]; error?: WorkflowErrorShape; budget?: WorkflowBudget; budgetVersion?: number; usage?: WorkflowBudgetUsage; budgetEvents?: readonly BudgetEvent[]; events?: readonly WorkflowRunEvent[] }
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 4;
+export interface LaunchSnapshot { identityVersion?: number; launchKind?: "inline" | "function"; functionName?: string; script: string; args: JsonValue; metadata: WorkflowMetadata; settings: WorkflowSettings; budget?: WorkflowBudget; settingsPath?: string; modelAliases?: Readonly<Record<string, string>>; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[]; roles?: Readonly<Record<string, AgentDefinition>>; projectRoles?: readonly string[]; schemas: readonly JsonSchema[] }
 export interface PreflightCapabilities { models: ReadonlySet<string>; tools: ReadonlySet<string>; agentTypes: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; skipModelAvailability?: boolean }
 export interface PreflightResult { metadata: WorkflowMetadata; referenced: { phases: readonly string[]; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[] }; schemas: readonly JsonSchema[]; dynamicAgentRoles: boolean }
 export interface WorkflowOrchestrationContext {
   agent: (...args: readonly unknown[]) => Promise<JsonValue>;
+  shell: (command: string, options?: ShellOptions) => Promise<ShellResult>;
   prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string;
   parallel: (...args: readonly unknown[]) => Promise<JsonValue>;
   pipeline: (...args: readonly unknown[]) => Promise<JsonValue>;
-  withWorktree: (...args: readonly unknown[]) => Promise<JsonValue>;
+  withWorktree: {
+    (callback: WorkflowWorktreeCallback): Promise<JsonValue>;
+    (name: string, callback: WorkflowWorktreeCallback): Promise<JsonValue>;
+  };
   checkpoint: (...args: readonly unknown[]) => Promise<boolean>;
   phase: (name: string) => void;
   log: (message: string) => void;
 }
 export interface WorkflowRunContext { cwd: string; sessionId: string; runId: string; workflow: Readonly<WorkflowMetadata>; args: JsonValue; signal: AbortSignal }
-export interface WorkflowFunctionContext extends WorkflowOrchestrationContext { run: Readonly<WorkflowRunContext> }
+export interface WorkflowFunctionContext extends WorkflowOrchestrationContext {
+  run: Readonly<WorkflowRunContext>;
+  invoke: (name: string, input: Readonly<Record<string, JsonValue>>) => Promise<JsonValue>;
+}
+export type WorkflowWorktreeCallback = (reference: Readonly<WorkflowWorktreeReference>) => JsonValue | Promise<JsonValue>;
 export interface WorkflowFunction { description: string; input: JsonSchema; output: JsonSchema; run: (input: Readonly<Record<string, JsonValue>>, context: Readonly<WorkflowFunctionContext>) => Promise<JsonValue> | JsonValue }
 export interface WorkflowVariable { description: string; schema: JsonSchema; resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue }
-export interface WorkflowScriptDefinition { description: string; script: string }
-export interface WorkflowExtension { version: string; headline: string; description: string; functions?: Readonly<Record<string, WorkflowFunction>>; variables?: Readonly<Record<string, WorkflowVariable>>; workflows?: Readonly<Record<string, WorkflowScriptDefinition>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>> }
+export interface WorkflowExtension { version: string; headline: string; description: string; functions?: Readonly<Record<string, WorkflowFunction>>; variables?: Readonly<Record<string, WorkflowVariable>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>> }
 export interface WorkflowJournal { get(path: string): JsonValue | undefined; put(path: string, value: JsonValue): void }
 
 export class WorkflowError extends Error {
   constructor(public readonly code: WorkflowErrorCode, message: string) { super(message); this.name = "WorkflowError"; }
 }
 
+export interface WorkflowFailureAgent {
+  id: string;
+  label?: string;
+  role?: string;
+  structuralPath: readonly string[];
+  attempt: number;
+  sessionId?: string;
+  sessionFile?: string;
+}
+export interface WorkflowSiblingAgent {
+  id: string;
+  label?: string;
+  role?: string;
+  structuralPath: readonly string[];
+}
+export interface WorkflowFailureDiagnostics {
+  runId: string;
+  workflowName: string;
+  state: RunState;
+  failedAt: string | null;
+  error: WorkflowErrorShape;
+  failedAgent?: WorkflowFailureAgent;
+  completedSiblingAgents?: readonly WorkflowSiblingAgent[];
+  completedSiblingPaths: readonly (readonly string[])[];
+  artifacts: { runDirectory: string; statePath: string; journalPath: string };
+}
+
+const WORKFLOW_FAILURE_DIAGNOSTICS = Symbol("workflowFailureDiagnostics");
+
 const WORKFLOW_AUTHORED_ERROR = Symbol("workflowAuthoredError");
 type WorkerErrorShape = WorkflowErrorShape & { authored?: boolean; failedAt?: string };
 
@@ -127,12 +167,13 @@ const WORKFLOW_ERROR_PROSE: Record<WorkflowErrorCode, (detail: string) => string
   INVALID_SCHEMA: (detail) => `The workflow schema is invalid: ${detail}.`,
   REGISTRY_FROZEN: (detail) => `Workflow extension registration is closed: ${detail}.`,
   GLOBAL_COLLISION: (detail) => `The workflow global name is already in use: ${detail}.`,
-  MISSING_WORKFLOW: (detail) => `The workflow primitive is unavailable: ${detail}.`,
+  MISSING_WORKFLOW: (detail) => `The registered workflow function is unavailable: ${detail}.`,
   UNKNOWN_MODEL: (detail) => `The workflow requested the unavailable model ${detail.replace(/^(?:Unknown model(?: for role [^:]+)?|Invalid model spec):\s*/, "")}.`,
   UNKNOWN_TOOL: (detail) => `The workflow requested the unavailable tool ${detail.replace(/^Unknown tool:\s*/, "")}.`,
   UNKNOWN_AGENT_TYPE: (detail) => `The workflow requested the unavailable agent role ${detail.replace(/^Unknown agent role:\s*/, "")}.`,
   RUN_OWNED: (detail) => /already owned|active ownership/.test(detail) ? "The workflow session is already in use." : `The workflow session is already in use: ${detail}.`,
   RPC_LIMIT_EXCEEDED: (detail) => `The workflow communication data exceeded its size limit: ${detail}.`,
+  SHELL_FAILED: (detail) => `The workflow shell command failed: ${detail}.`,
   AGENT_TIMEOUT: (detail) => `The workflow agent timed out: ${detail}.`,
   AGENT_FAILED: (detail) => `The workflow agent failed: ${detail}.`,
   RESULT_INVALID: (detail) => `The workflow produced an invalid result: ${detail}.`,
@@ -234,6 +275,7 @@ export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ conc
 
 function fail(code: WorkflowErrorCode, message: string): never { throw new WorkflowError(code, message); }
 function object(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+export { object as isObject };
 function nonNegativeInteger(value: unknown): value is number { return Number.isInteger(value) && (value as number) >= 0; }
 function nonNegativeFinite(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
 export function validateBudget(value: unknown): WorkflowBudget | undefined {
@@ -496,9 +538,7 @@ export function saveModelAliases(path = workflowSettingsPath(), aliases: Readonl
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
   }
   mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, { mode: 0o600 });
-  renameSync(temporary, path);
+  atomicWriteFile(path, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, true);
 }
 
 export function parseRoleMarkdown(content: string, strict = false, rolePath?: string): AgentDefinition {
@@ -613,15 +653,25 @@ type WorkflowCall = acorn.CallExpression & { callee: acorn.Identifier };
 function astNode(value: unknown): value is acorn.AnyNode {
   return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
 }
+function astChildren(node: acorn.AnyNode): acorn.AnyNode[] {
+  const children: acorn.AnyNode[] = [];
+  for (const value of Object.values(node) as unknown[]) {
+    if (Array.isArray(value)) {
+      for (const child of value) if (astNode(child)) children.push(child);
+    } else if (astNode(value)) children.push(value);
+  }
+  return children;
+}
+function workflowCallKind(node: acorn.AnyNode): WorkflowCallKind | undefined {
+  if (node.type !== "CallExpression" || node.callee.type !== "Identifier") return undefined;
+  const kind = node.callee.name as WorkflowCallKind;
+  return WORKFLOW_CALL_KINDS.includes(kind) ? kind : undefined;
+}
 function workflowCalls(program: acorn.Program): WorkflowCall[] {
   const calls: WorkflowCall[] = [];
   const visit = (node: acorn.AnyNode): void => {
-    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) calls.push(node as WorkflowCall);
-    for (const value of Object.values(node) as unknown[]) {
-      if (Array.isArray(value)) {
-        for (const child of value as unknown[]) if (astNode(child)) visit(child);
-      } else if (astNode(value)) visit(value);
-    }
+    if (workflowCallKind(node)) calls.push(node as WorkflowCall);
+    for (const child of astChildren(node)) visit(child);
   };
   visit(program);
   return calls.sort((left, right) => left.start - right.start);
@@ -638,9 +688,9 @@ function workflowCallsWithStructure(program: acorn.Program): Array<{ call: Workf
       const key = node.key.type === "Identifier" ? node.key.name : node.key.type === "Literal" ? String(node.key.value) : undefined;
       if (scope?.key === null && key) current = { ...current, structure: [...current.structure.slice(0, -1), { ...scope, key }] };
     }
-    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) {
+    const operation = workflowCallKind(node);
+    if (operation) {
       const call = node as WorkflowCall;
-      const operation = call.callee.name as StaticWorkflowCall["kind"];
       const execution = operation === "parallel" ? "parallel" : operation === "pipeline" ? "sequential" : current.execution;
       calls.push({ call, execution, structure: current.structure });
       for (const [index, argument] of call.arguments.entries()) {
@@ -650,16 +700,11 @@ function workflowCallsWithStructure(program: acorn.Program): Array<{ call: Workf
       }
       return;
     }
-    for (const value of Object.values(node) as unknown[]) {
-      if (Array.isArray(value)) {
-        for (const child of value as unknown[]) if (astNode(child)) visit(child, current);
-      } else if (astNode(value)) visit(value, current);
-    }
+    for (const child of astChildren(node)) visit(child, current);
   };
   visit(program, { execution: "sequential", structure: [] });
   return calls.sort((left, right) => left.call.start - right.call.start);
 }
-
 function validateDirectPrimitiveReferences(program: acorn.AnyNode, name: string): void {
   const visit = (node: acorn.AnyNode, parent?: acorn.AnyNode): void => {
     if (node.type === "Identifier" && node.name === name) {
@@ -667,23 +712,19 @@ function validateDirectPrimitiveReferences(program: acorn.AnyNode, name: string)
       const propertyKey = parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand;
       if (!directCall && !propertyKey) fail("INVALID_METADATA", `${name} calls must use a direct ${name}(...) call; aliases and indirect calls are unsupported`);
     }
-    for (const value of Object.values(node) as unknown[]) {
-      if (Array.isArray(value)) {
-        for (const child of value as unknown[]) if (astNode(child)) visit(child, node);
-      } else if (astNode(value)) visit(value, node);
-    }
+    for (const child of astChildren(node)) visit(child, node);
   };
   visit(program);
 }
-
 function hasIdentifier(node: acorn.AnyNode, name: string): boolean {
   if (node.type === "Identifier" && node.name === name) return true;
-  return Object.values(node).some((value) => Array.isArray(value) ? value.some((child) => astNode(child) && hasIdentifier(child, name)) : astNode(value) && hasIdentifier(value, name));
+  return astChildren(node).some((child) => hasIdentifier(child, name));
 }
 
 const INTERNAL_AGENT_NAME = "__pi_extensible_workflows_agent";
 const INTERNAL_CONVERSATION_NAME = "__pi_extensible_workflows_conversation";
 const INTERNAL_WORKTREE_NAME = "__pi_extensible_workflows_withWorktree";
+const INTERNAL_SHELL_NAME = "__pi_extensible_workflows_shell";
 
 function callHasTrailingComma(source: string, call: WorkflowCall): boolean {
   let previous: acorn.Token | undefined;
@@ -702,12 +743,13 @@ function instrumentWorkflow(script: string): string {
   if (hasIdentifier(program, INTERNAL_AGENT_NAME)) fail("INVALID_METADATA", `${INTERNAL_AGENT_NAME} is reserved for workflow agent instrumentation`);
   if (hasIdentifier(program, INTERNAL_CONVERSATION_NAME)) fail("INVALID_METADATA", `${INTERNAL_CONVERSATION_NAME} is reserved for workflow conversation instrumentation`);
   if (hasIdentifier(program, INTERNAL_WORKTREE_NAME)) fail("INVALID_METADATA", `${INTERNAL_WORKTREE_NAME} is reserved for workflow withWorktree instrumentation`);
-  const calls = workflowCalls(program).filter((call) => ["agent", "conversation", "withWorktree"].includes(call.callee.name));
+  if (hasIdentifier(program, INTERNAL_SHELL_NAME)) fail("INVALID_METADATA", `${INTERNAL_SHELL_NAME} is reserved for workflow shell instrumentation`);
+  const calls = workflowCalls(program).filter((call) => ["agent", "conversation", "withWorktree", "shell"].includes(call.callee.name));
   const edits = calls.flatMap((call) => {
     const callSite = `${String(call.start)}:${String(call.end)}`;
     const hiddenArgument = call.arguments.length === 0 || callHasTrailingComma(body, call) ? "" : ", ";
     return [
-      { start: call.callee.start, end: call.callee.end, text: call.callee.name === "agent" ? INTERNAL_AGENT_NAME : call.callee.name === "conversation" ? INTERNAL_CONVERSATION_NAME : INTERNAL_WORKTREE_NAME },
+      { start: call.callee.start, end: call.callee.end, text: call.callee.name === "agent" ? INTERNAL_AGENT_NAME : call.callee.name === "conversation" ? INTERNAL_CONVERSATION_NAME : call.callee.name === "withWorktree" ? INTERNAL_WORKTREE_NAME : INTERNAL_SHELL_NAME },
       { start: call.end - 1, end: call.end - 1, text: `${hiddenArgument}${JSON.stringify(callSite)}` },
     ];
   }).sort((left, right) => right.start - left.start);
@@ -819,6 +861,18 @@ function validateAgentOptions(value: unknown): Readonly<Record<string, JsonValue
   if (typeof value.role === "string" && ["model", "thinking", "tools"].some((key) => Object.prototype.hasOwnProperty.call(value, key))) fail("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
   return value;
 }
+const SHELL_OPTION_KEYS = new Set(["timeoutMs", "env"]);
+function validateShellOptions(value: unknown): ShellOptions {
+  if (value === undefined) return {};
+  if (!object(value) || !jsonValue(value) || Object.keys(value).some((key) => !SHELL_OPTION_KEYS.has(key))) fail("INVALID_METADATA", "shell options must contain only timeoutMs and env");
+  if (value.timeoutMs !== undefined && !positiveInteger(value.timeoutMs)) fail("INVALID_METADATA", "shell timeoutMs must be a positive integer");
+  if (value.env !== undefined && (!object(value.env) || Object.values(value.env).some((entry) => typeof entry !== "string"))) fail("INVALID_METADATA", "shell env must be an object of strings");
+  return { ...(value.timeoutMs === undefined ? {} : { timeoutMs: value.timeoutMs }), ...(value.env === undefined ? {} : { env: value.env as Record<string, string> }) };
+}
+function validateShellCommand(value: unknown): string {
+  if (typeof value !== "string") fail("INVALID_METADATA", "shell command must be a string");
+  return value;
+}
 
 type StaticValue = { known: true; value: unknown } | { known: false };
 
@@ -854,7 +908,7 @@ function staticValue(node: acorn.AnyNode | undefined): StaticValue {
 }
 
 export interface StaticWorkflowCall {
-  kind: "agent" | "conversation" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+  kind: WorkflowCallKind;
   start: number;
   end: number;
   name: string | null;
@@ -899,6 +953,7 @@ export function inspectWorkflowScript(script: string): StaticWorkflowCall[] {
       return { ...base, ...(retries.known && typeof retries.value === "number" ? { retries: retries.value } : {}), ...(outputSchema.known && object(outputSchema.value) ? { outputSchema: outputSchema.value as JsonSchema } : {}), ...(optionKeys.length ? { options: knownOptions, optionKeys } : {}) };
     }
     if (kind === "checkpoint") return { ...placement, kind, start: call.start, end: call.end, name: staticString(propertyNode(first, "name")), prompt: staticString(propertyNode(first, "prompt")), model: null, role: null };
+    if (kind === "shell") return { ...placement, kind, start: call.start, end: call.end, name: staticString(first), prompt: null, model: null, role: null };
     return { ...placement, kind, start: call.start, end: call.end, name: staticString(first), prompt: null, model: null, role: null };
   });
 }
@@ -912,6 +967,14 @@ function validateStaticAgentOptions(node: acorn.AnyNode | undefined, aliases: Re
     if (value.known) validateAgentOption(key, value.value, aliases, knownModels, settingsPath);
   }
 }
+function validateStaticShellOptions(call: WorkflowCall): void {
+  if (call.arguments.some((argument) => argument.type === "SpreadElement")) return;
+  if (call.arguments.length !== 1 && call.arguments.length !== 2) fail("INVALID_METADATA", "shell requires a command string and optional options");
+  const command = staticValue(callArgument(call, 0));
+  if (command.known) validateShellCommand(command.value);
+  const options = staticValue(callArgument(call, 1));
+  if (options.known) validateShellOptions(options.value);
+}
 
 function validateStaticWithWorktree(call: WorkflowCall): void {
   if (call.arguments.some((argument) => argument.type === "SpreadElement")) return;
@@ -926,16 +989,18 @@ function validateStaticWithWorktree(call: WorkflowCall): void {
 
 export interface WorkflowCatalogFunction { name: string; version: string; headline: string; extensionDescription: string; description: string; input: JsonSchema; output: JsonSchema }
 export interface WorkflowCatalogVariable { name: string; version: string; headline: string; extensionDescription: string; description: string; schema: JsonSchema }
-export interface WorkflowCatalogWorkflow { name: string; version: string; headline: string; extensionDescription: string; description: string }
-export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; variables: readonly WorkflowCatalogVariable[]; workflows: readonly WorkflowCatalogWorkflow[]; modelAliases?: Readonly<Record<string, string>> }
-const RESERVED_GLOBALS = new Set(["agent", "conversation", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
+export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; variables: readonly WorkflowCatalogVariable[]; modelAliases?: Readonly<Record<string, string>> }
+export interface WorkflowCatalogIndexFunction { name: string; description: string; input: JsonSchema }
+export interface WorkflowCatalogIndexVariable { name: string; description: string; schema: JsonSchema }
+export interface WorkflowCatalogIndex { functions: readonly WorkflowCatalogIndexFunction[]; variables: readonly WorkflowCatalogIndexVariable[]; modelAliases?: Readonly<Record<string, string>> }
+export interface WorkflowCatalogError { error: { code: "NOT_FOUND"; name: string; message: string } }
+const RESERVED_GLOBALS = new Set(["agent", "conversation", "shell", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 
 export class WorkflowRegistry {
   readonly #extensions = new Set<Readonly<WorkflowExtension>>();
   readonly #globals = new Map<string, string>();
-  readonly #workflows = new Map<string, WorkflowScriptDefinition>();
   readonly #hooks = new Map<string, RegisteredAgentSetupHook>();
   #frozen = false;
 
@@ -944,12 +1009,12 @@ export class WorkflowRegistry {
 
   register(extension: WorkflowExtension): void {
     if (this.#frozen) fail("REGISTRY_FROZEN", "Workflow extension registration is closed after session_start");
-    if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "workflows", "agentSetupHooks"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
+    if (object(extension) && Object.prototype.hasOwnProperty.call(extension, "workflows")) fail("INVALID_METADATA", "Separate registered workflow definitions were removed; register a function with input and output schemas instead");
+    if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "agentSetupHooks"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
     const functions = extension.functions ?? {};
     const variables = extension.variables ?? {};
-    const workflows = extension.workflows ?? {};
     const agentSetupHooks = extension.agentSetupHooks ?? {};
-    if (!object(functions) || !object(variables) || !object(workflows) || !object(agentSetupHooks) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(workflows).length === 0 && Object.keys(agentSetupHooks).length === 0)) fail("INVALID_METADATA", "Workflow extensions require functions, variables, workflows, or agent setup hooks");
+    if (!object(functions) || !object(variables) || !object(agentSetupHooks) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(agentSetupHooks).length === 0)) fail("INVALID_METADATA", "Workflow extensions require functions, variables, or agent setup hooks");
     const names = [...Object.keys(functions), ...Object.keys(variables)];
     if (new Set(names).size !== names.length) fail("GLOBAL_COLLISION", "Global name collision inside extension");
     for (const name of names) {
@@ -967,46 +1032,54 @@ export class WorkflowRegistry {
       if (!object(variable) || Object.keys(variable).some((key) => !["description", "schema", "resolve"].includes(key)) || typeof variable.description !== "string" || !variable.description.trim() || typeof variable.resolve !== "function") fail("INVALID_METADATA", `Invalid workflow variable: ${name}`);
       validateSchema(variable.schema, `${name} schema`);
     }
-    for (const [name, workflow] of Object.entries(workflows)) {
-      if (!IDENTIFIER.test(name) || !object(workflow) || Object.keys(workflow).some((key) => !["description", "script"].includes(key)) || typeof workflow.description !== "string" || !workflow.description.trim() || typeof workflow.script !== "string" || !workflow.script.trim()) fail("INVALID_METADATA", `Invalid workflow script: ${name}`);
-      if (this.#workflows.has(name)) fail("DUPLICATE_NAME", `Reusable workflow already registered: ${name}`);
-      parseWorkflow(workflow.script);
-    }
     for (const [name, hook] of Object.entries(agentSetupHooks)) {
       if (!IDENTIFIER.test(name) || !object(hook) || Object.keys(hook).some((key) => !["priority", "setup"].includes(key)) || typeof hook.setup !== "function" || hook.priority !== undefined && (typeof hook.priority !== "number" || !Number.isFinite(hook.priority))) fail("INVALID_METADATA", `Invalid agent setup hook: ${name}`);
       if (this.#hooks.has(name)) fail("DUPLICATE_NAME", `Agent setup hook already registered: ${name}`);
     }
-    const stored = deepFreeze({ ...extension, functions, variables, workflows, agentSetupHooks });
+    const stored = deepFreeze({ ...extension, functions, variables, agentSetupHooks });
     this.#extensions.add(stored);
     for (const name of names) this.#globals.set(name, name);
-    for (const [name, workflow] of Object.entries(workflows)) this.#workflows.set(name, workflow);
     for (const [name, hook] of Object.entries(agentSetupHooks)) this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
   }
 
-  workflow(name: string): WorkflowScriptDefinition {
-    if (!IDENTIFIER.test(name)) fail("MISSING_WORKFLOW", `Registered workflows require an unqualified name: ${name}`);
-    const workflow = this.#workflows.get(name);
-    if (!workflow) fail("MISSING_WORKFLOW", `Workflow is unavailable: ${name}`);
-    return workflow;
+  function(name: string): WorkflowFunction {
+    if (!IDENTIFIER.test(name)) fail("MISSING_WORKFLOW", `Registered functions require an unqualified name: ${name}`);
+    const fn = [...this.#extensions].find((extension) => extension.functions?.[name])?.functions?.[name];
+    if (!fn) fail("MISSING_WORKFLOW", `Registered function is unavailable: ${name}; the separate registered-workflow format was removed`);
+    return fn;
   }
 
-  workflows(): Readonly<Record<string, WorkflowScriptDefinition>> {
-    return Object.freeze(Object.fromEntries(this.#workflows));
+  functions(): Readonly<Record<string, WorkflowFunction>> {
+    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.entries(extension.functions ?? {}))));
   }
 
   catalog(): WorkflowCatalog {
     const functions: WorkflowCatalogFunction[] = [];
     const variables: WorkflowCatalogVariable[] = [];
-    const workflows: WorkflowCatalogWorkflow[] = [];
     for (const extension of this.#extensions) {
       for (const [name, fn] of Object.entries(extension.functions ?? {})) functions.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: fn.description, input: structuredClone(fn.input), output: structuredClone(fn.output) });
       for (const [name, variable] of Object.entries(extension.variables ?? {})) variables.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: variable.description, schema: structuredClone(variable.schema) });
-      for (const [name, workflow] of Object.entries(extension.workflows ?? {})) workflows.push({ name, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: workflow.description });
     }
     let aliases: Readonly<Record<string, string>> | undefined;
     try { aliases = loadSettings().modelAliases; } catch { aliases = undefined; }
     const sort = (left: { name: string }, right: { name: string }) => left.name.localeCompare(right.name);
-    return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), workflows: workflows.sort(sort), ...(aliases ? { modelAliases: structuredClone(aliases) } : {}) });
+    return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), ...(aliases ? { modelAliases: structuredClone(aliases) } : {}) });
+  }
+
+  catalogIndex(): WorkflowCatalogIndex {
+    const catalog = this.catalog();
+    return deepFreeze({
+      functions: catalog.functions.map(({ name, description, input }) => ({ name, description, input: structuredClone(input) })),
+      variables: catalog.variables.map(({ name, description, schema }) => ({ name, description, schema: structuredClone(schema) })),
+      ...(catalog.modelAliases ? { modelAliases: structuredClone(catalog.modelAliases) } : {}),
+    });
+  }
+
+  catalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError {
+    const catalog = this.catalog();
+    const entry = catalog.functions.find((candidate) => candidate.name === name) ?? catalog.variables.find((candidate) => candidate.name === name);
+    if (entry) return entry;
+    return deepFreeze({ error: { code: "NOT_FOUND", name, message: `No registered workflow function or variable is available: ${name}` } });
   }
 
   globals(): Readonly<Record<string, { name: string }>> {
@@ -1014,15 +1087,14 @@ export class WorkflowRegistry {
   }
 
   async invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue> {
-    const fn = [...this.#extensions].find((extension) => extension.functions?.[name])?.functions?.[name];
-    if (!fn) fail("MISSING_WORKFLOW", `Workflow function is unavailable: ${name}`);
+    const fn = this.function(name);
     if (!object(input) || !jsonValue(input) || !Value.Check(fn.input, input)) fail("RESULT_INVALID", `Invalid input for ${name}`);
     const replayed = journal.get(path);
     if (replayed !== undefined) {
       if (!jsonValue(replayed) || !Value.Check(fn.output, replayed)) fail("RESULT_INVALID", `Invalid replay for ${name}`);
       return structuredClone(replayed);
     }
-    const result: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, agent: context.agent, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
+    const result: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, invoke: context.invoke, agent: context.agent, shell: context.shell, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
     if (!jsonValue(result) || !Value.Check(fn.output, result)) fail("RESULT_INVALID", `Invalid output from ${name}`);
     const stored = structuredClone(result);
     journal.put(path, stored);
@@ -1036,7 +1108,7 @@ export class WorkflowRegistry {
     return [...this.#hooks.values()].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
   }
 }
-type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "workflow" | "workflows" | "catalog" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
+type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
 interface WorkflowRegistryHost { api: WorkflowRegistryApi }
 const WORKFLOW_REGISTRY_KEY = Symbol.for("pi-extensible-workflows.workflow-registry");
 const globalRegistry = globalThis as typeof globalThis & Record<symbol, WorkflowRegistryHost | undefined>;
@@ -1045,9 +1117,11 @@ function createWorkflowRegistryApi(registry: WorkflowRegistry): WorkflowRegistry
     get frozen() { return registry.frozen; },
     freeze: () => { registry.freeze(); },
     register: (extension) => { registry.register(extension); },
-    workflow: (name) => registry.workflow(name),
-    workflows: () => registry.workflows(),
+    function: (name) => registry.function(name),
+    functions: () => registry.functions(),
     catalog: () => registry.catalog(),
+    catalogIndex: () => registry.catalogIndex(),
+    catalogDetail: (name) => registry.catalogDetail(name),
     globals: () => registry.globals(),
     invokeFunction: (...args) => registry.invokeFunction(...args),
     variables: () => registry.variables(),
@@ -1067,26 +1141,29 @@ function loadingRegistry(): WorkflowRegistryApi { return workflowRegistryHost().
 beginWorkflowExtensionLoading();
 export function registerWorkflowExtension(extension: WorkflowExtension): void { loadingRegistry().register(extension); }
 export function workflowCatalog(): WorkflowCatalog { return loadingRegistry().catalog(); }
-export function registeredWorkflowDefinitions(): Readonly<Record<string, WorkflowScriptDefinition>> { return loadingRegistry().workflows(); }
+export function workflowCatalogIndex(): WorkflowCatalogIndex { return loadingRegistry().catalogIndex(); }
+export function workflowCatalogDetail(name: string): WorkflowCatalogFunction | WorkflowCatalogVariable | WorkflowCatalogError { return loadingRegistry().catalogDetail(name); }
+export function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>> { return loadingRegistry().functions(); }
 
 
 export function formatWorkflowPreview(args: { script?: unknown; workflow?: unknown; name?: unknown; description?: unknown }): string {
   const name = typeof args.name === "string" && args.name.trim() ? args.name.trim() : typeof args.workflow === "string" && args.workflow.trim() ? args.workflow : "workflow";
-  if (typeof args.script !== "string" || !args.script.trim()) return `workflow ${name}${typeof args.workflow === "string" ? "\nRegistered workflow" : ""}`;
+  if (typeof args.script !== "string" || !args.script.trim()) return `workflow ${name}${typeof args.workflow === "string" ? "\nRegistered function" : ""}`;
   return [`workflow ${name}`, typeof args.description === "string" && args.description.trim() ? args.description.trim() : ""].filter(Boolean).join("\n");
 }
 export const WORKFLOW_TOOL_LABEL = "Workflow";
 export const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow";
-export const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow that orchestrates subagents. Inline scripts require a name; registered workflows use their workflow name. Runs in the background by default; completion arrives as a follow-up message.";
+export const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow that orchestrates subagents. Inline scripts require a name; registered functions use their function name. Runs in the background by default; completion arrives as a follow-up message. Foreground results include the completed run ID, and parentRunId reuses matching named worktrees from a terminal run.";
 export const WORKFLOW_TOOL_PARAMETERS = Type.Object({
   name: Type.Optional(Type.String({ description: "Workflow name for inline scripts" })),
   description: Type.Optional(Type.String({ description: "Optional human-readable workflow description" })),
   script: Type.Optional(Type.String({ description: "Immutable workflow source without metadata" })),
-  workflow: Type.Optional(Type.String({ description: "Registered reusable workflow as an unqualified name" })),
+  workflow: Type.Optional(Type.String({ description: "Registered reusable function as an unqualified name" })),
   args: Type.Optional(Type.Unknown({ description: "JSON-compatible workflow arguments" })),
   foreground: Type.Optional(Type.Boolean({ description: "Wait for completion instead of running in the background" })),
   concurrency: Type.Optional(Type.Integer({ minimum: 1, maximum: 16 })),
   budget: Type.Optional(Type.Unknown({ description: "Optional aggregate soft and hard run budgets" })),
+  parentRunId: Type.Optional(Type.String({ description: "Terminal run whose named worktrees may be reused" })),
 });
 
 function hasDynamicAgentRole(node: acorn.AnyNode | undefined): boolean {
@@ -1107,8 +1184,10 @@ export function preflight(script: string, capabilities: PreflightCapabilities, s
   if (hasIdentifier(program, INTERNAL_AGENT_NAME)) fail("INVALID_METADATA", `${INTERNAL_AGENT_NAME} is reserved for workflow agent instrumentation`);
   if (hasIdentifier(program, INTERNAL_CONVERSATION_NAME)) fail("INVALID_METADATA", `${INTERNAL_CONVERSATION_NAME} is reserved for workflow conversation instrumentation`);
   if (hasIdentifier(program, INTERNAL_WORKTREE_NAME)) fail("INVALID_METADATA", `${INTERNAL_WORKTREE_NAME} is reserved for workflow withWorktree instrumentation`);
+  if (hasIdentifier(program, INTERNAL_SHELL_NAME)) fail("INVALID_METADATA", `${INTERNAL_SHELL_NAME} is reserved for workflow shell instrumentation`);
   validateDirectPrimitiveReferences(program, "withWorktree");
   validateDirectPrimitiveReferences(program, "conversation");
+  validateDirectPrimitiveReferences(program, "shell");
   for (const [index, schema] of schemas.entries()) validateSchema(schema, `schema[${String(index)}]`);
   const calls = workflowCalls(program);
   const phases = calls.filter((call) => call.callee.name === "phase").map((call) => literalString(call.arguments[0])).filter((phase): phase is string => phase !== undefined);
@@ -1119,6 +1198,7 @@ export function preflight(script: string, capabilities: PreflightCapabilities, s
       validateStaticAgentOptions(call.arguments[1], capabilities.modelAliases ?? {}, capabilities.knownModels ?? capabilities.models, capabilities.settingsPath);
     }
     if (operation === "withWorktree") validateStaticWithWorktree(call);
+    if (operation === "shell") validateStaticShellOptions(call);
     if ((operation === "parallel" || operation === "pipeline") && call.arguments.some((argument) => argument.type === "SpreadElement")) continue;
     if (operation === "checkpoint" && stableName(call.arguments[0]) === false) fail("INVALID_METADATA", `${operation} requires a stable explicit name`);
     if (operation === "parallel" && (call.arguments.length !== 2 || !literalString(call.arguments[0])?.trim() || call.arguments[1]?.type !== "ObjectExpression")) fail("INVALID_METADATA", "parallel requires an operation name string and tasks record");
@@ -1153,6 +1233,7 @@ export interface WorkflowValidationParameters {
   description?: string;
   script?: string;
   workflow?: string;
+  args?: unknown;
 }
 
 export interface WorkflowValidationContext {
@@ -1163,6 +1244,7 @@ export interface WorkflowValidationContext {
   modelAliases?: Readonly<Record<string, string>>;
   knownModels?: ReadonlySet<string>;
   settingsPath?: string;
+  agentDir?: string;
 }
 
 
@@ -1172,21 +1254,27 @@ export interface ValidatedWorkflowLaunch {
   agentDefinitions: Readonly<Record<string, AgentDefinition>>;
   projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>;
   roleNames: readonly string[];
+  functionName?: string;
 }
 
+function functionLaunchScript(name: string): string { return `return await ${name}(args);`; }
+
 export function validateWorkflowLaunch(params: WorkflowValidationParameters, context: WorkflowValidationContext): ValidatedWorkflowLaunch {
   return validateWorkflowLaunchWithRegistry(params, context, loadingRegistry());
 }
 function validateWorkflowLaunchWithRegistry(params: WorkflowValidationParameters, context: WorkflowValidationContext, registry: WorkflowRegistryApi): ValidatedWorkflowLaunch {
   if (Object.prototype.hasOwnProperty.call(params, "maxAgentLaunches")) fail("INVALID_METADATA", "maxAgentLaunches has been removed; use budget.agentLaunches");
   if (params.script !== undefined && params.workflow !== undefined) fail("INVALID_METADATA", "Provide either script or workflow, not both");
-  const definition = typeof params.workflow === "string" ? registry.workflow(params.workflow) : undefined;
-  const script = typeof params.script === "string" && params.script.trim() ? params.script : definition?.script ?? "";
-  if (!script) fail("INVALID_SYNTAX", "Provide script or registered workflow");
-  const workflowName = typeof params.name === "string" && params.name.trim() ? params.name.trim() : typeof params.workflow === "string" ? params.workflow : "";
+  const functionName = typeof params.workflow === "string" ? params.workflow : undefined;
+  const fn = functionName === undefined ? undefined : registry.function(functionName);
+  const args = params.args === undefined ? null : params.args;
+  if (functionName !== undefined && fn && (!object(args) || !jsonValue(args) || !Value.Check(fn.input, args))) fail("RESULT_INVALID", `Invalid input for ${functionName}`);
+  const script = functionName !== undefined && fn ? functionLaunchScript(functionName) : typeof params.script === "string" && params.script.trim() ? params.script : "";
+  if (!script) fail("INVALID_SYNTAX", "Provide script or registered function");
+  const workflowName = functionName ?? (typeof params.name === "string" && params.name.trim() ? params.name.trim() : "");
   if (!workflowName) fail("INVALID_METADATA", "Inline workflows require name");
-  const metadata = validateWorkflowMetadata({ name: workflowName, ...(typeof params.description === "string" ? { description: params.description } : definition?.description ? { description: definition.description } : {}) });
-  const globalAgentDefinitions = loadAgentDefinitions(context.cwd, undefined, false);
+  const metadata = validateWorkflowMetadata({ name: workflowName, ...(typeof params.description === "string" ? { description: params.description } : fn?.description ? { description: fn.description } : {}) });
+  const globalAgentDefinitions = loadAgentDefinitions(context.cwd, context.agentDir, false);
   const projectAgentDefinitions = context.projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(context.cwd, ".pi"))) : {};
   const agentDefinitions = deepFreeze({ ...globalAgentDefinitions, ...projectAgentDefinitions });
   const aliases = context.modelAliases ?? {};
@@ -1194,7 +1282,7 @@ function validateWorkflowLaunchWithRegistry(params: WorkflowValidationParameters
   const checked = preflight(script, { models: context.availableModels, tools: context.rootTools, agentTypes: new Set(Object.keys(agentDefinitions)), modelAliases: aliases, knownModels, ...(context.settingsPath ? { settingsPath: context.settingsPath } : {}) }, [], metadata);
   const roleNames = checked.dynamicAgentRoles ? Object.keys(agentDefinitions) : checked.referenced.agentTypes;
   validateRolePolicies(agentDefinitions, roleNames, context.availableModels, context.rootTools, aliases, knownModels, context.settingsPath);
-  return { script, checked, agentDefinitions, projectAgentDefinitions, roleNames };
+  return { script, checked, agentDefinitions, projectAgentDefinitions, roleNames, ...(functionName ? { functionName } : {}) };
 }
 
 function deepFreeze<T>(value: T): T {
@@ -1208,22 +1296,34 @@ function deepFreeze<T>(value: T): T {
 type LaunchSnapshotInput = Omit<LaunchSnapshot, "identityVersion"> & { identityVersion?: number };
 
 export function createLaunchSnapshot(input: LaunchSnapshotInput): Readonly<LaunchSnapshot> {
-  return deepFreeze(structuredClone({ ...input, identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION }));
+  return deepFreeze(structuredClone({ ...input, launchKind: input.launchKind ?? (input.functionName ? "function" : "inline"), identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION }));
 }
 
 export function loadLaunchSnapshot(input: LaunchSnapshot): Readonly<LaunchSnapshot> {
-  if (object(input.settings) && Object.prototype.hasOwnProperty.call(input.settings, "maxAgentLaunches")) fail("RESUME_INCOMPATIBLE", "Persisted workflow settings contain removed maxAgentLaunches");
   return deepFreeze(structuredClone(input));
 }
 
+function launchScriptForSnapshot(snapshot: Readonly<LaunchSnapshot>, registry: WorkflowRegistryApi): string {
+  if (snapshot.launchKind === "function") {
+    if (!snapshot.functionName) fail("RESUME_INCOMPATIBLE", "Persisted registered function launch is missing its function name");
+    try { registry.function(snapshot.functionName); } catch (error) { if (error instanceof WorkflowError && error.code === "MISSING_WORKFLOW") throw new WorkflowError("RESUME_INCOMPATIBLE", `Persisted registered function is unavailable: ${snapshot.functionName}`); throw error; }
+    return functionLaunchScript(snapshot.functionName);
+  }
+  if (snapshot.launchKind === "inline") return snapshot.script;
+  fail("RESUME_INCOMPATIBLE", "This persisted run uses the removed registered-workflow format; launch it again as a registered function or inline script");
+}
+
 export const RPC_LIMIT_BYTES = 10 * 1024 * 1024;
 export const HEARTBEAT_TIMEOUT_MS = 5000;
 
 export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string; conversation?: { name: string; turn: number } }
+export interface ShellIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; worktreeOwner?: string }
 export interface WorkflowBridge {
   agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
+  shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>;
   checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>;
   function?: (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath?: readonly string[]) => Promise<JsonValue>;
+  worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>;
   functions?: Readonly<Record<string, { name: string }>>;
   variables?: Readonly<Record<string, JsonValue>>;
   phase?: (name: string) => void | Promise<void>;
@@ -1296,10 +1396,12 @@ const named = (value, kind) => { if (typeof value !== "string" || !value.trim())
 const path = (...names) => names.map(encodeURIComponent).join("/");
 const inheritedAgentPath = new AsyncLocalStorage();
 const agentOccurrences = new Map();
+const shellOccurrences = new Map();
 const conversationOccurrences = new Map();
 const worktreeOwners = new AsyncLocalStorage();
 const worktreeOccurrences = new Map();
 const rejectAgent = () => { throw workError("INVALID_METADATA", "Workflow agent calls must use a direct agent(...) call; aliases and indirect calls are unsupported"); };
+const rejectShell = () => { throw workError("INVALID_METADATA", "Workflow shell calls must use a direct shell(...) call; aliases and indirect calls are unsupported"); };
 const rejectWorktree = () => { throw workError("INVALID_METADATA", "withWorktree calls must use a direct withWorktree(...) call; aliases and indirect calls are unsupported"); };
 const internalWithWorktree = async (...values) => {
   const callSite = values.pop();
@@ -1318,7 +1420,9 @@ const internalWithWorktree = async (...values) => {
     worktreeOccurrences.set(occurrenceKey, occurrence);
     owner = path("worktree", "unnamed", ...inherited, "callsite:" + callSite, "occurrence:" + String(occurrence));
   }
-  return await worktreeOwners.run(owner, callback);
+  const reference = await rpc("worktree", [owner]);
+  if (!reference || typeof reference !== "object" || typeof reference.path !== "string" || typeof reference.branch !== "string") throw workError("WORKTREE_FAILED", "Worktree reference is invalid");
+  return await worktreeOwners.run(owner, () => callback(Object.freeze({ path: reference.path, branch: reference.branch })));
 };
 const internalConversation = (...values) => {
   const callSite = values.pop();
@@ -1377,6 +1481,31 @@ const internalAgent = (...values) => {
   });
   return result;
 };
+const internalShell = (...values) => {
+  const callSite = values.pop();
+  if (typeof callSite !== "string") throw workError("INTERNAL_ERROR", "Missing workflow shell call-site identity");
+  if (values.length !== 1 && values.length !== 2) throw workError("INVALID_METADATA", "shell requires a command string and optional options");
+  const command = values[0];
+  if (typeof command !== "string") throw workError("INVALID_METADATA", "shell command must be a string");
+  const options = values.length < 2 || values[1] === undefined ? {} : values[1];
+  if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "timeoutMs" && key !== "env")) throw workError("INVALID_METADATA", "shell options must contain only timeoutMs and env");
+  if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs <= 0)) throw workError("INVALID_METADATA", "shell timeoutMs must be a positive integer");
+  if (options.env !== undefined && (!options.env || typeof options.env !== "object" || Array.isArray(options.env) || Object.values(options.env).some(value => typeof value !== "string"))) throw workError("INVALID_METADATA", "shell env must be an object of strings");
+  const inherited = inheritedAgentPath.getStore() || [];
+  const worktreeOwner = worktreeOwners.getStore();
+  const occurrenceKey = JSON.stringify([inherited, callSite, worktreeOwner || null]);
+  const occurrence = (shellOccurrences.get(occurrenceKey) || 0) + 1;
+  shellOccurrences.set(occurrenceKey, occurrence);
+  const identity = { structuralPath: [...inherited], callSite, occurrence, ...(worktreeOwner ? { worktreeOwner } : {}) };
+  const result = rpc("shell", [command, options, identity]);
+  Object.defineProperties(result, {
+    toJSON: { value() { throw workError("INVALID_METADATA", "Workflow shell result is a Promise; await it before serialization"); } },
+    toString: { value() { throw workError("INVALID_METADATA", "Workflow shell result is a Promise; await it before interpolation"); } },
+    [Symbol.toPrimitive]: { value() { throw workError("INVALID_METADATA", "Workflow shell result is a Promise; await it before interpolation"); } },
+  });
+  return result;
+};
+const shell = rejectShell;
 const agent = rejectAgent;
 const promptPath = (at, key) => /^[A-Za-z_$][\w$]*$/.test(key) ? at + "." + key : at + "[" + JSON.stringify(key) + "]";
 const plainPromptObject = value => {
@@ -1498,13 +1627,13 @@ const pipeline = async (operationName, items, stages) => {
   return Object.fromEntries(results.map(result => [result.name, result.value]));
 };
 const safeMath = Object.fromEntries(Object.getOwnPropertyNames(Math).filter(name => name !== "random").map(name => [name, Math[name]]));
-const sandbox = { agent, conversation: internalConversation, withWorktree: rejectWorktree, prompt, checkpoint, parallel, pipeline, phase, log, args: config.args, Promise, JSON, Math: Object.freeze(safeMath) };
+const sandbox = { agent, conversation: internalConversation, shell, withWorktree: rejectWorktree, prompt, checkpoint, parallel, pipeline, phase, log, args: config.args, Promise, JSON, Math: Object.freeze(safeMath) };
 for (const [name, fn] of Object.entries(functions)) Object.defineProperty(sandbox, name, { value: fn, writable: false, configurable: false });
 for (const [name, value] of Object.entries(config.variables || {})) Object.defineProperty(sandbox, name, { value: freeze(value), writable: false, configurable: false });
 for (const name of ["Date","eval","Function","WebAssembly","process","require","module","exports","console","fetch","XMLHttpRequest","WebSocket","performance","crypto","setTimeout","setInterval","setImmediate","queueMicrotask","Intl","SharedArrayBuffer","Atomics"]) sandbox[name] = undefined;
 const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
 const body = config.script;
-Promise.resolve().then(() => new vm.Script("(async(__pi_extensible_workflows_agent,__pi_extensible_workflows_conversation,__pi_extensible_workflows_withWorktree)=>{" + body + "\n})", { filename: "workflow.js" }).runInContext(context)(internalAgent, internalConversation, internalWithWorktree))
+Promise.resolve().then(() => new vm.Script("(async(__pi_extensible_workflows_agent,__pi_extensible_workflows_conversation,__pi_extensible_workflows_withWorktree,__pi_extensible_workflows_shell)=>{" + body + "\n})", { filename: "workflow.js" }).runInContext(context)(internalAgent, internalConversation, internalWithWorktree, internalShell))
   .then(async value => { await Promise.all(inflight); send({ type: "result", value: value === undefined ? null : value }); })
   .catch(error => send({ type: "error", error: workerError(error) }))
   .finally(() => clearInterval(heartbeat));
@@ -1517,6 +1646,10 @@ function encoded(value: unknown): string {
   return json;
 }
 
+function encodedRpcResult(id: number, value: JsonValue): string {
+  return encoded({ type: "rpcResult", id, ok: true, value });
+}
+
 function readAgentIdentity(value: unknown): AgentIdentity {
   if (!object(value)) fail("INTERNAL_ERROR", "Invalid workflow agent identity");
   const structuralPath = value.structuralPath;
@@ -1529,10 +1662,17 @@ function readAgentIdentity(value: unknown): AgentIdentity {
   if (!Array.isArray(structuralPath) || !structuralPath.every((part): part is string => typeof part === "string" && Boolean(part.trim())) || typeof callSite !== "string" || !callSite || !positiveInteger(occurrence) || parentBreadcrumb !== undefined && (typeof parentBreadcrumb !== "string" || !parentBreadcrumb.trim()) || worktreeOwner !== undefined && (typeof worktreeOwner !== "string" || !worktreeOwner) || conversation !== undefined && !parsedConversation) fail("INTERNAL_ERROR", "Invalid workflow agent identity");
   return { structuralPath: [...structuralPath], callSite, occurrence, ...(typeof parentBreadcrumb === "string" ? { parentBreadcrumb } : {}), ...(typeof worktreeOwner === "string" ? { worktreeOwner } : {}), ...(parsedConversation ? { conversation: parsedConversation } : {}) };
 }
-
+function readShellIdentity(value: unknown): ShellIdentity {
+  const identity = readAgentIdentity(value);
+  if (identity.conversation) fail("INTERNAL_ERROR", "Shell identity cannot include a conversation");
+  return { structuralPath: identity.structuralPath, callSite: identity.callSite, occurrence: identity.occurrence, ...(identity.worktreeOwner ? { worktreeOwner: identity.worktreeOwner } : {}) };
+}
 function agentIdentityPath(identity: AgentIdentity): string {
   return operationPath("agent", ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
 }
+function shellIdentityPath(identity: ShellIdentity): string {
+  return operationPath("shell", ...(identity.worktreeOwner ? ["worktree", identity.worktreeOwner] : []), ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
+}
 function conversationIdentityPath(identity: AgentIdentity): string {
   if (!identity.conversation) throw new WorkflowError("INTERNAL_ERROR", "Missing conversation identity");
   return operationPath("conversation", identity.conversation.name, ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
@@ -1541,9 +1681,82 @@ function conversationTurnPath(identity: AgentIdentity): string {
   if (!identity.conversation) throw new WorkflowError("INTERNAL_ERROR", "Missing conversation identity");
   return operationPath(conversationIdentityPath(identity), `turn:${String(identity.conversation.turn)}`);
 }
+function readShellResult(value: unknown): ShellResult {
+  if (!object(value) || (value.exitCode !== null && !Number.isInteger(value.exitCode)) || typeof value.stdout !== "string" || typeof value.stderr !== "string") fail("SHELL_FAILED", "Shell bridge returned an invalid result");
+  return { exitCode: value.exitCode as number | null, stdout: value.stdout, stderr: value.stderr };
+}
 function agentWorktree(identity: AgentIdentity): { worktreeOwner?: string } {
   return identity.worktreeOwner ? { worktreeOwner: identity.worktreeOwner } : {};
 }
+function shellProcessKill(child: ChildProcess): void {
+  let forceKill: ReturnType<typeof setTimeout> | undefined;
+  const killProcessTree = (signal: "SIGTERM" | "SIGKILL") => {
+    try {
+      if (child.pid && process.platform !== "win32") process.kill(-child.pid, signal);
+      else if (child.pid && process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore", windowsHide: true });
+        killer.unref();
+      } else child.kill(signal);
+    } catch {
+      try { child.kill(signal); } catch { /* The process may already have exited. */ }
+    }
+  };
+  child.once("close", () => { if (forceKill) clearTimeout(forceKill); });
+  killProcessTree("SIGTERM");
+  forceKill = setTimeout(() => { forceKill = undefined; killProcessTree("SIGKILL"); }, 1000);
+  forceKill.unref();
+}
+function executeShellCommand(command: string, options: ShellOptions, signal: AbortSignal, cwd = process.cwd()): Promise<ShellResult> {
+  return new Promise((resolve, reject) => {
+    let child: ChildProcess;
+    try { child = spawn(command, { shell: true, cwd, env: { ...process.env, ...(options.env ?? {}) }, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] }); }
+    catch (error) { reject(new WorkflowError("SHELL_FAILED", errorText(error))); return; }
+    let settled = false;
+    let timedOut = false;
+    let outputBytes = 0;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    const stdoutDecoder = new StringDecoder("utf8");
+    const stderrDecoder = new StringDecoder("utf8");
+    let stdout = "";
+    let stderr = "";
+    const cleanup = () => {
+      if (timeout) clearTimeout(timeout);
+      signal.removeEventListener("abort", onAbort);
+    };
+    const failShell = (error: WorkflowError) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      shellProcessKill(child);
+      reject(error);
+    };
+    const onAbort = () => { failShell(new WorkflowError("CANCELLED", "Workflow cancelled")); };
+    const capture = (target: "stdout" | "stderr", chunk: Buffer) => {
+      if (settled) return;
+      outputBytes += chunk.byteLength;
+      if (outputBytes > RPC_LIMIT_BYTES) { failShell(new WorkflowError("RPC_LIMIT_EXCEEDED", "Shell result exceeds the 10 MB JSON boundary")); return; }
+      if (target === "stdout") stdout += stdoutDecoder.write(chunk); else stderr += stderrDecoder.write(chunk);
+    };
+    child.stdout?.on("data", (chunk: Buffer) => { capture("stdout", chunk); });
+    child.stderr?.on("data", (chunk: Buffer) => { capture("stderr", chunk); });
+    child.once("error", (error) => { failShell(new WorkflowError("SHELL_FAILED", errorText(error))); });
+    child.once("close", (exitCode) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      stdout += stdoutDecoder.end();
+      stderr += stderrDecoder.end();
+      if (signal.aborted) { reject(new WorkflowError("CANCELLED", "Workflow cancelled")); return; }
+      if (timedOut) { reject(new WorkflowError("SHELL_FAILED", `Shell command timed out after ${String(options.timeoutMs)}ms`)); return; }
+      const result = { exitCode: exitCode === null ? null : exitCode, stdout, stderr };
+      try { encodedRpcResult(Number.MAX_SAFE_INTEGER, result); } catch (error) { reject(error instanceof WorkflowError ? error : new WorkflowError("RPC_LIMIT_EXCEEDED", errorText(error))); return; }
+      resolve(result);
+    });
+    if (signal.aborted) { onAbort(); return; }
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (options.timeoutMs !== undefined) timeout = setTimeout(() => { timedOut = true; shellProcessKill(child); }, options.timeoutMs);
+  });
+}
 export function runWorkflow(script: string, args: JsonValue = null, bridge: WorkflowBridge = {}, signal?: AbortSignal): WorkflowExecution {
   encoded(args);
   const config = JSON.stringify({ script: instrumentWorkflow(script), args: structuredClone(args), functions: bridge.functions ?? {}, variables: bridge.variables ?? {} });
@@ -1613,6 +1826,12 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
           if (!OUTCOME_ERRORS.has(typed.code)) throw typed;
           value = branded({ name: label, ok: false, failedAt: path, error: { code: typed.code, message: typed.message, ...(isWorkflowAuthored(typed) ? { authored: true } : {}) } });
         }
+      } else if (method === "shell") {
+        if (!bridge.shell) fail("SHELL_FAILED", "No shell bridge is available");
+        const command = validateShellCommand(values[0]);
+        const options = validateShellOptions(values[1]);
+        const identity = readShellIdentity(values[2]);
+        value = readShellResult(await bridge.shell(command, options, controller.signal, identity)) as unknown as JsonValue;
       } else if (method === "checkpoint") {
         if (!bridge.checkpoint || !object(values[0])) fail("INTERNAL_ERROR", "checkpoint requires an available bridge and object input");
         const name = typeof values[0].name === "string" ? values[0].name : "checkpoint";
@@ -1639,6 +1858,9 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
           if (!OUTCOME_ERRORS.has(typed.code)) throw typed;
           value = branded({ name, ok: false, failedAt: name, error: { code: typed.code, message: typed.message, ...(isWorkflowAuthored(typed) ? { authored: true } : {}) } });
         }
+      } else if (method === "worktree") {
+        if (!bridge.worktree || typeof values[0] !== "string" || !values[0]) fail("INTERNAL_ERROR", "worktree requires an active host bridge and scope");
+        value = await bridge.worktree(values[0], controller.signal);
       } else if (method === "phase") {
         if (typeof values[0] !== "string") fail("INTERNAL_ERROR", "phase name must be a string");
         await bridge.phase?.(values[0]);
@@ -1648,7 +1870,7 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
       }
       else fail("INTERNAL_ERROR", `Unknown worker RPC method: ${method}`);
       encoded(value);
-      child.send(encoded({ type: "rpcResult", id, ok: true, value }));
+      child.send(encodedRpcResult(id, value));
     } catch (error) {
       const typed = asWorkflowError(error);
       child.send(encoded({ type: "rpcResult", id, ok: false, error: { code: typed.code, message: typed.message, ...(isWorkflowAuthored(typed) ? { authored: true } : {}) } }));
@@ -1845,13 +2067,9 @@ export function formatNavigatorDashboard(run: PersistedRun, checkpoints: readonl
   const render = ({ agent, depth }: { agent: AgentRecord; index: number; depth: number }, grouped: boolean) => {
     const icon = agent.state === "completed" ? "✓" : agent.state === "failed" || agent.state === "cancelled" ? "✗" : agent.state === "running" ? "⠦" : "○";
     const breadcrumb = grouped ? agent.label ?? agent.name : agentBreadcrumb(agent, byId);
-    const setup = agent.attemptDetails?.at(-1)?.setup;
-    const thinking = setup?.model.thinking ?? agent.model.thinking;
-    const model = `${setup?.model.provider ?? agent.model.provider}/${setup?.model.model ?? agent.model.model}${thinking ? `:${thinking}` : ""}`;
-    const policy = [`model=${model}`, agent.requestedModel ? `requested=${agent.requestedModel}` : "", `tools=${(setup?.tools ?? agent.tools).join(",") || "(none)"}`, agent.role ? `role=${agent.role}` : ""];
     const tokens = agent.accounting ? formatAccounting(agent.accounting) : "";
     const indent = "  ".repeat((grouped ? 2 : 1) + depth);
-    const result = [`${indent}${icon} ${breadcrumb} · ${agent.state} · ${policy.filter(Boolean).join(" · ")}${tokens ? ` · ${tokens}` : ""}`];
+    const result = [`${indent}${icon} ${breadcrumb} · ${agent.state}${tokens ? ` · ${tokens}` : ""}`];
     if (agent.state === "failed" && agent.attemptDetails?.length) {
       const last = agent.attemptDetails[agent.attemptDetails.length - 1];
       if (last?.error) result.push(`${indent}  error: ${last.error.code}: ${last.error.message}`);
@@ -1902,7 +2120,8 @@ export function formatNavigatorRun(loaded: { run: PersistedRun; snapshot: Readon
   return lines.join("\n");
 }
 function formatCheckpointReview(checkpoint: AwaitingCheckpoint): string {
-  return [`Name: ${checkpoint.name}`, "Prompt:", checkpoint.prompt, "Context:", JSON.stringify(checkpoint.context, null, 2)].join("\n");
+  const context = JSON.stringify(checkpoint.context, null, 2);
+  return [`Name: ${checkpoint.name}`, "Prompt:", checkpoint.prompt, context === "null" ? "Context: null" : "Context:", ...(context === "null" ? [] : [context])].join("\n");
 }
 
 const DELIVERY_LIMIT_BYTES = 4 * 1024;
@@ -1925,12 +2144,109 @@ function utf8Prefix(value: string, maxBytes: number): string {
   while (end < bytes.length && end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end -= 1;
   return bytes.subarray(0, end).toString("utf8");
 }
+const DIAGNOSTIC_LIMIT_BYTES = DELIVERY_LIMIT_BYTES - 512;
+function failureDiagnosticsFrom(error: unknown): WorkflowFailureDiagnostics | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  return (error as { [WORKFLOW_FAILURE_DIAGNOSTICS]?: WorkflowFailureDiagnostics })[WORKFLOW_FAILURE_DIAGNOSTICS];
+}
+
+function boundedWorkflowFailureDiagnostics(value: WorkflowFailureDiagnostics): WorkflowFailureDiagnostics {
+  let bounded: WorkflowFailureDiagnostics = {
+    runId: utf8Prefix(value.runId, 128),
+    workflowName: utf8Prefix(value.workflowName, 256),
+    state: value.state,
+    failedAt: value.failedAt === null ? null : utf8Prefix(value.failedAt, 1024),
+    error: { code: value.error.code, message: utf8Prefix(value.error.message, 1024) },
+    ...(value.failedAgent ? { failedAgent: {
+      id: utf8Prefix(value.failedAgent.id, 128),
+      ...(value.failedAgent.label ? { label: utf8Prefix(value.failedAgent.label, 128) } : {}),
+      ...(value.failedAgent.role ? { role: utf8Prefix(value.failedAgent.role, 128) } : {}),
+      structuralPath: value.failedAgent.structuralPath.slice(0, 8).map((part) => utf8Prefix(part, 128)),
+      attempt: value.failedAgent.attempt,
+      ...(value.failedAgent.sessionId ? { sessionId: utf8Prefix(value.failedAgent.sessionId, 256) } : {}),
+      ...(value.failedAgent.sessionFile ? { sessionFile: utf8Prefix(value.failedAgent.sessionFile, 1024) } : {}),
+    } } : {}),
+    completedSiblingAgents: (value.completedSiblingAgents ?? []).slice(0, 16).map((agent) => ({
+      id: utf8Prefix(agent.id, 128),
+      ...(agent.label ? { label: utf8Prefix(agent.label, 128) } : {}),
+      ...(agent.role ? { role: utf8Prefix(agent.role, 128) } : {}),
+      structuralPath: agent.structuralPath.slice(0, 8).map((part) => utf8Prefix(part, 128)),
+    })),
+    completedSiblingPaths: value.completedSiblingPaths.slice(0, 16).map((path) => path.slice(0, 8).map((part) => utf8Prefix(part, 128))),
+    artifacts: { runDirectory: utf8Prefix(value.artifacts.runDirectory, 1024), statePath: utf8Prefix(value.artifacts.statePath, 1024), journalPath: utf8Prefix(value.artifacts.journalPath, 1024) },
+  };
+  const size = () => Buffer.byteLength(JSON.stringify(bounded));
+  while (size() > DIAGNOSTIC_LIMIT_BYTES) {
+    if (bounded.completedSiblingAgents?.length || bounded.completedSiblingPaths.length) {
+      bounded = { ...bounded, completedSiblingAgents: bounded.completedSiblingAgents?.slice(0, -1) ?? [], completedSiblingPaths: bounded.completedSiblingPaths.slice(0, -1) };
+      continue;
+    }
+    if (bounded.failedAgent?.sessionFile) { const failedAgent = { ...bounded.failedAgent }; delete failedAgent.sessionFile; bounded = { ...bounded, failedAgent }; continue; }
+    if (bounded.failedAgent?.sessionId) { const failedAgent = { ...bounded.failedAgent }; delete failedAgent.sessionId; bounded = { ...bounded, failedAgent }; continue; }
+    if (Buffer.byteLength(bounded.artifacts.runDirectory) > 256) { bounded = { ...bounded, artifacts: { ...bounded.artifacts, runDirectory: utf8Prefix(bounded.artifacts.runDirectory, 256) } }; continue; }
+    if (Buffer.byteLength(bounded.error.message) > 256) { bounded = { ...bounded, error: { ...bounded.error, message: utf8Prefix(bounded.error.message, 256) } }; continue; }
+    if (bounded.failedAt !== null && Buffer.byteLength(bounded.failedAt) > 256) { bounded = { ...bounded, failedAt: utf8Prefix(bounded.failedAt, 256) }; continue; }
+    if (bounded.failedAgent && bounded.failedAgent.structuralPath.length > 4) { bounded = { ...bounded, failedAgent: { ...bounded.failedAgent, structuralPath: bounded.failedAgent.structuralPath.slice(0, 4) } }; continue; }
+    if (bounded.failedAgent?.structuralPath.some((part) => Buffer.byteLength(part) > 64)) { bounded = { ...bounded, failedAgent: { ...bounded.failedAgent, structuralPath: bounded.failedAgent.structuralPath.map((part) => utf8Prefix(part, 64)) } }; continue; }
+    if (Buffer.byteLength(bounded.artifacts.statePath) > 512 || Buffer.byteLength(bounded.artifacts.journalPath) > 512) { bounded = { ...bounded, artifacts: { ...bounded.artifacts, statePath: utf8Prefix(bounded.artifacts.statePath, 512), journalPath: utf8Prefix(bounded.artifacts.journalPath, 512) } }; continue; }
+    if (Buffer.byteLength(bounded.workflowName) > 128) { bounded = { ...bounded, workflowName: utf8Prefix(bounded.workflowName, 128) }; continue; }
+    break;
+  }
+  return bounded;
+}
+
+function createWorkflowFailureDiagnostics(store: RunStore, metadata: WorkflowMetadata, error: unknown, run: PersistedRun): WorkflowFailureDiagnostics {
+  const rawFailedAt = error && typeof error === "object" ? (error as { failedAt?: unknown }).failedAt : undefined;
+  const failedAt = typeof rawFailedAt === "string" && rawFailedAt ? rawFailedAt : null;
+  const failedAgents = run.agents.filter((agent) => agent.state === "failed");
+  const failedAgentRecord = failedAgents.find((agent) => {
+    if (failedAt === null) return false;
+    try { return failedAt.includes(`${operationPath("agent", ...(agent.structuralPath ?? []))}/`); } catch { return false; }
+  }) ?? failedAgents.at(-1);
+  const failedAttempt = failedAgentRecord ? [...(failedAgentRecord.attemptDetails ?? [])].reverse().find((attempt) => attempt.error) ?? failedAgentRecord.attemptDetails?.at(-1) : undefined;
+  const failedAgent = failedAgentRecord ? {
+    id: failedAgentRecord.id,
+    ...(failedAgentRecord.label ?? failedAgentRecord.name ? { label: failedAgentRecord.label ?? failedAgentRecord.name } : {}),
+    ...(failedAgentRecord.role ? { role: failedAgentRecord.role } : {}),
+    structuralPath: [...(failedAgentRecord.structuralPath ?? [])],
+    attempt: Math.max(1, failedAttempt?.attempt ?? failedAgentRecord.attempts),
+    ...(failedAttempt?.sessionId ? { sessionId: failedAttempt.sessionId } : {}),
+    ...(failedAttempt?.sessionFile ? { sessionFile: failedAttempt.sessionFile } : {}),
+  } satisfies WorkflowFailureAgent : undefined;
+  const completedSiblingAgents = run.agents.filter((agent) => {
+    if (agent.state !== "completed" || agent.id === failedAgentRecord?.id) return false;
+    return failedAgentRecord?.parentId === undefined ? agent.parentId === undefined : agent.parentId === failedAgentRecord.parentId;
+  }).map((agent) => ({
+    id: agent.id,
+    ...(agent.label ?? agent.name ? { label: agent.label ?? agent.name } : {}),
+    ...(agent.role ? { role: agent.role } : {}),
+    structuralPath: [...(agent.structuralPath ?? [])],
+  } satisfies WorkflowSiblingAgent));
+  const completedSiblingPaths = completedSiblingAgents.map((agent) => [...agent.structuralPath]);
+  return boundedWorkflowFailureDiagnostics({
+    runId: run.id, workflowName: metadata.name, state: run.state, failedAt,
+    error: { code: errorCode(error) ?? "INTERNAL_ERROR", message: errorText(error) || "The workflow failed without an error message." },
+    ...(failedAgent ? { failedAgent } : {}), completedSiblingAgents, completedSiblingPaths,
+    artifacts: { runDirectory: store.directory, statePath: join(store.directory, "state.json"), journalPath: join(store.directory, "journal.json") },
+  });
+}
 
+export function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string {
+  const failedAgent = diagnostic.failedAgent ? `${diagnostic.failedAgent.label ?? diagnostic.failedAgent.id}${diagnostic.failedAgent.role ? ` role=${diagnostic.failedAgent.role}` : ""} attempt=${String(diagnostic.failedAgent.attempt)} path=${diagnostic.failedAgent.structuralPath.join(" > ") || "(root)"}${diagnostic.failedAgent.sessionFile ? ` session=${diagnostic.failedAgent.sessionFile}` : ""}` : "(not persisted)";
+  const siblingAgents = diagnostic.completedSiblingAgents;
+  const siblings = siblingAgents ? siblingAgents.map((agent) => `${agent.label ?? agent.id}${agent.role ? ` role=${agent.role}` : ""} path=${agent.structuralPath.join(" > ") || "(root)"}`).join(", ") || "(none)" : diagnostic.completedSiblingPaths.map((path) => path.join(" > ") || "(root)").join(", ") || "(none)";
+  return [`✗ Workflow: ${diagnostic.workflowName}`, `  Run: ${diagnostic.runId}`, `  State: ${diagnostic.state}`, `  Error: ${diagnostic.error.code}: ${diagnostic.error.message}`, `  Failed at: ${diagnostic.failedAt ?? "(unknown)"}`, `  Failed agent: ${failedAgent}`, `  Completed sibling ${siblingAgents ? "agents" : "paths"}: ${siblings}`, `  Artifacts: state=${diagnostic.artifacts.statePath} journal=${diagnostic.artifacts.journalPath}`].join("\n");
+}
+
+function serializeWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string { return JSON.stringify(diagnostic); }
+function isWorkflowFailureDiagnostics(value: unknown): value is WorkflowFailureDiagnostics {
+  return object(value) && typeof value.runId === "string" && typeof value.workflowName === "string" && typeof value.state === "string" && "failedAt" in value && object(value.error) && object(value.artifacts);
+}
 function deliver(pi: ExtensionAPI, content: string): void {
   pi.sendMessage({ customType: "workflow", content, display: true }, { deliverAs: "followUp", triggerTurn: true });
 }
-function deliverFailure(pi: ExtensionAPI, name: string, error: unknown): void {
-  deliver(pi, `Workflow ${name} failed: ${formatWorkflowFailure(error)}`);
+function deliverFailure(pi: ExtensionAPI, diagnostic: WorkflowFailureDiagnostics): void {
+  deliver(pi, `Workflow ${utf8Prefix(diagnostic.workflowName, 128)} failure diagnostics: ${serializeWorkflowFailureDiagnostics(diagnostic)}`);
 }
 
 type WorkflowEventSink = { emit: (name: string, payload: unknown) => unknown };
@@ -1947,19 +2263,19 @@ class WorkflowEventPublisher {
 
   constructor(private readonly sink: WorkflowEventSink | undefined) {}
 
+  removeRun(runId: string): void {
+    this.#queues.delete(runId);
+    this.#budgetEvents.delete(runId);
+    this.#worktrees.delete(runId);
+  }
+
   seedBudget(runId: string, events: readonly BudgetEvent[] | undefined): void {
     const seen = this.#budgetEvents.get(runId) ?? new Set<string>();
     for (const event of events ?? []) seen.add(this.budgetKey(event));
     this.#budgetEvents.set(runId, seen);
   }
 
-  async runStarted(store: RunStore, metadata: WorkflowMetadata, background: boolean): Promise<void> {
-    await this.#publish(store, metadata, WORKFLOW_RUN_STARTED_EVENT, {});
-    if (background) await this.legacyStarted(store, metadata);
-  }
-
-  async legacyStarted(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_ASYNC_STARTED_EVENT, { id: store.runId, runId: store.runId, pid: process.pid, sessionId: store.sessionId, asyncDir: store.directory, agent: metadata.name }); }
-
+  async runStarted(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_STARTED_EVENT, {}); }
   async runResumed(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_RESUMED_EVENT, {}); }
 
   async runState(store: RunStore, metadata: WorkflowMetadata, previousState: RunState, state: RunState, reason?: string): Promise<void> {
@@ -1967,16 +2283,9 @@ class WorkflowEventPublisher {
     if ((previousState === "paused" || previousState === "interrupted" || previousState === "budget_exhausted") && state === "running") await this.runResumed(store, metadata);
   }
 
-  async runCompleted(store: RunStore, metadata: WorkflowMetadata, resultPath: string, background: boolean): Promise<void> {
-    await this.#publish(store, metadata, WORKFLOW_RUN_COMPLETED_EVENT, { resultPath });
-    if (background) await this.#publish(store, metadata, WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: true, state: "complete" });
-  }
-  async runFailed(store: RunStore, metadata: WorkflowMetadata, error: unknown, background: boolean, state: "failed" | "stopped" | "interrupted" | "budget_exhausted"): Promise<void> {
+  async runCompleted(store: RunStore, metadata: WorkflowMetadata, resultPath: string): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_COMPLETED_EVENT, { resultPath }); }
+  async runFailed(store: RunStore, metadata: WorkflowMetadata, error: unknown, state: "failed" | "stopped" | "interrupted" | "budget_exhausted"): Promise<void> {
     if (state === "failed") await this.#publish(store, metadata, WORKFLOW_RUN_FAILED_EVENT, { error: safeEventError(error) });
-    if (background) {
-      const legacyState = state === "interrupted" ? "failed" : state;
-      await this.#publish(store, metadata, WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: false, state: legacyState, ...(state === "stopped" ? { stopped: true } : {}), ...(legacyState === "budget_exhausted" || legacyState === "failed" ? { error: safeEventError(error).message } : {}) });
-    }
   }
 
   async agentState(store: RunStore, metadata: WorkflowMetadata, previous: AgentRecord | undefined, agent: AgentRecord): Promise<void> {
@@ -2037,7 +2346,11 @@ function namedRecord(value: unknown, kind: string): Array<[string, unknown]> {
   if (!object(value)) fail("INVALID_METADATA", `${kind} must be a record`);
   return Object.entries(value);
 }
-function hostWithWorktree(args: readonly unknown[], identity: string, occurrences: Map<string, number>): Promise<JsonValue> {
+function publicWorktreeReference(reference: WorkflowWorktreeReference): Readonly<WorkflowWorktreeReference> {
+  if (!object(reference) || typeof reference.path !== "string" || typeof reference.branch !== "string") fail("WORKTREE_FAILED", "Worktree reference is invalid");
+  return Object.freeze({ path: reference.path, branch: reference.branch });
+}
+async function hostWithWorktree(args: readonly unknown[], identity: string, occurrences: Map<string, number>, resolveWorktree: ((owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>) | undefined, signal: AbortSignal): Promise<JsonValue> {
   if (args.length !== 1 && args.length !== 2) fail("INVALID_METADATA", "withWorktree requires a callback or a name and callback");
   const callback = args[args.length - 1];
   if (typeof callback !== "function") fail("INVALID_METADATA", "withWorktree callback must be a function");
@@ -2052,7 +2365,9 @@ function hostWithWorktree(args: readonly unknown[], identity: string, occurrence
     occurrences.set(key, occurrence);
     owner = operationPath("worktree", "unnamed", "function", identity, ...structuralPath, `occurrence:${String(occurrence)}`);
   }
-  return inheritedHostWorktreeOwner.run(owner, async () => await (callback as () => unknown)()) as Promise<JsonValue>;
+  if (!resolveWorktree) fail("WORKTREE_FAILED", "No worktree bridge is available");
+  const reference = publicWorktreeReference(await resolveWorktree(owner, signal));
+  return inheritedHostWorktreeOwner.run(owner, async () => await (callback as (reference: Readonly<WorkflowWorktreeReference>) => unknown)(reference)) as Promise<JsonValue>;
 }
 function workflowRunContext(cwd: string, sessionId: string, runId: string, workflow: WorkflowMetadata, args: JsonValue, signal: AbortSignal): Readonly<WorkflowRunContext> {
   return Object.freeze({ cwd, sessionId, runId, workflow: deepFreeze(structuredClone(workflow)), args: deepFreeze(structuredClone(args)), signal });
@@ -2133,16 +2448,27 @@ function nextNamedOccurrence(counters: Map<string, number>, label: string): stri
   return count === 1 ? label : `${label}#${String(count)}`;
 }
 
-
 function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runContext: Readonly<WorkflowRunContext>, variables: Readonly<Record<string, JsonValue>>, registry: WorkflowRegistryApi): WorkflowBridge {
   const functionAgentOccurrences = new Map<string, number>();
+  const functionShellOccurrences = new Map<string, number>();
   const functionWorktreeOccurrences = new Map<string, number>();
-  return { ...bridge, functions: registry.globals(), variables, function: async (name, input, path, signal, worktreeOwner, structuralPath = []) => {
+  const functionInvokeOccurrences = new Map<string, number>();
+  const invokeFunction = async (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath: readonly string[] = [], breadcrumb?: string): Promise<JsonValue> => {
     const replayed = await store.replay(path);
     let stored: JsonValue | undefined;
     const sideEffects: Promise<void>[] = [];
+    const functionBreadcrumb = breadcrumb ?? name;
     const context: WorkflowFunctionContext = {
       run: runContext,
+      invoke: async (targetName, targetInput) => {
+        const inherited = inheritedHostAgentPath.getStore() ?? structuralPath;
+        const scopedWorktreeOwner = inheritedHostWorktreeOwner.getStore() ?? worktreeOwner;
+        const key = JSON.stringify([path, inherited, targetName]);
+        const occurrence = (functionInvokeOccurrences.get(key) ?? 0) + 1;
+        functionInvokeOccurrences.set(key, occurrence);
+        const nestedPath = operationPath("function", "nested", path, ...inherited, targetName, `occurrence:${String(occurrence)}`);
+        return invokeFunction(targetName, targetInput, nestedPath, signal, scopedWorktreeOwner, inherited, `${functionBreadcrumb} > ${targetName}`);
+      },
       agent: async (...args: readonly unknown[]) => {
         if (!bridge.agent || typeof args[0] !== "string") fail("AGENT_FAILED", "No agent bridge is available");
         const options = validateAgentOptions(args[1] === undefined ? {} : args[1]);
@@ -2151,12 +2477,23 @@ function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runConte
         const key = `${path}\0${JSON.stringify(inherited)}`;
         const occurrence = (functionAgentOccurrences.get(key) ?? 0) + 1;
         functionAgentOccurrences.set(key, occurrence);
-        return bridge.agent(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb: name, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
+        return bridge.agent(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb: functionBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
+      },
+      shell: async (...args: readonly unknown[]) => {
+        if (!bridge.shell) fail("SHELL_FAILED", "No shell bridge is available");
+        if (typeof args[0] !== "string") fail("INVALID_METADATA", "shell command must be a string");
+        const options = validateShellOptions(args[1] === undefined ? {} : args[1]);
+        const scopedWorktreeOwner = inheritedHostWorktreeOwner.getStore() ?? worktreeOwner;
+        const inherited = inheritedHostAgentPath.getStore() ?? [];
+        const key = `${path}\0${JSON.stringify([inherited, scopedWorktreeOwner ?? null])}`;
+        const occurrence = (functionShellOccurrences.get(key) ?? 0) + 1;
+        functionShellOccurrences.set(key, occurrence);
+        return bridge.shell(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
       },
       prompt: workflowPrompt,
       parallel: (...args: readonly unknown[]) => hostParallel(args[0], args[1]),
       pipeline: (...args: readonly unknown[]) => hostPipeline(args[0], args[1], args[2]),
-      withWorktree: (...args: readonly unknown[]) => hostWithWorktree(args, path, functionWorktreeOccurrences),
+      withWorktree: (...args: readonly unknown[]) => hostWithWorktree(args, path, functionWorktreeOccurrences, bridge.worktree, signal),
       checkpoint: async (...args: readonly unknown[]) => {
         if (!bridge.checkpoint || !object(args[0]) || !jsonValue(args[0])) fail("INTERNAL_ERROR", "No checkpoint bridge is available");
         return bridge.checkpoint(args[0], signal);
@@ -2168,14 +2505,73 @@ function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runConte
     await Promise.all(sideEffects);
     if (!replayed) await store.complete(path, stored ?? result);
     return result;
-  } };
+  };
+  return { ...bridge, functions: registry.globals(), variables, function: invokeFunction };
 }
 
 function projectTrusted(ctx: unknown): boolean {
   const check = object(ctx) ? ctx.isProjectTrusted : undefined;
   return typeof check === "function" ? Boolean(Reflect.apply(check, ctx, [])) : true;
 }
-
+type PiHostCapabilities = { registerEntryRenderer?: ExtensionAPI["registerEntryRenderer"]; events?: WorkflowEventSink };
+function isEntryRenderer(value: unknown): value is NonNullable<PiHostCapabilities["registerEntryRenderer"]> { return typeof value === "function"; }
+function isWorkflowEventSink(value: unknown): value is WorkflowEventSink { return object(value) && typeof value.emit === "function"; }
+function piHostCapabilities(pi: unknown): PiHostCapabilities {
+  if (!object(pi)) return {};
+  const registerEntryRenderer = pi.registerEntryRenderer;
+  const events = pi.events;
+  return { ...(isEntryRenderer(registerEntryRenderer) ? { registerEntryRenderer } : {}), ...(isWorkflowEventSink(events) ? { events } : {}) };
+}
+type ContextHostCapabilities = { modelRegistry?: ModelRegistryCapability };
+type ModelSummary = { provider: string; id: string };
+type ModelRegistryGetter = () => readonly ModelSummary[];
+type ModelRegistryCapability = { getAll?: ModelRegistryGetter; getAvailable?: ModelRegistryGetter };
+function isModelRegistryGetter(value: unknown): value is ModelRegistryGetter { return typeof value === "function"; }
+function contextHostCapabilities(ctx: unknown): ContextHostCapabilities {
+  if (!object(ctx) || !object(ctx.modelRegistry)) return {};
+  const registry = ctx.modelRegistry;
+  const getAll = registry.getAll;
+  const getAvailable = registry.getAvailable;
+  return { modelRegistry: { ...(isModelRegistryGetter(getAll) ? { getAll: () => getAll.call(registry) } : {}), ...(isModelRegistryGetter(getAvailable) ? { getAvailable: () => getAvailable.call(registry) } : {}) } };
+}
+type UiSelect = (title: string, options: string[]) => Promise<string | undefined>;
+type UiInput = (title: string, placeholder?: string) => Promise<string | undefined>;
+type UiSetStatus = (key: string, text?: string) => void;
+type UiHostCapabilities = { select?: UiSelect; input?: UiInput; setStatus?: UiSetStatus };
+function isUiSelect(value: unknown): value is UiSelect { return typeof value === "function"; }
+function isUiInput(value: unknown): value is UiInput { return typeof value === "function"; }
+function isUiSetStatus(value: unknown): value is UiSetStatus { return typeof value === "function"; }
+function uiHostCapabilities(ui: unknown): UiHostCapabilities | undefined {
+  if (!object(ui)) return undefined;
+  const select = ui.select;
+  const input = ui.input;
+  const setStatus = ui.setStatus;
+  return { ...(isUiSelect(select) ? { select } : {}), ...(isUiInput(input) ? { input } : {}), ...(isUiSetStatus(setStatus) ? { setStatus } : {}) };
+}
+type TuiHostCapabilities = { terminal?: { rows?: unknown } };
+function tuiHostCapabilities(tui: unknown): TuiHostCapabilities {
+  if (!object(tui) || !object(tui.terminal)) return {};
+  return { terminal: { ...(tui.terminal.rows === undefined ? {} : { rows: tui.terminal.rows }) } };
+}
+function tuiRows(tui: unknown): number { const rows = tuiHostCapabilities(tui).terminal?.rows; return typeof rows === "number" && Number.isFinite(rows) ? rows : 24; }
+const WORKFLOW_OVERLAY_BORDER_ROWS = 2;
+type WorkflowOverlayComponent = { render(width: number): string[]; invalidate(): void; handleInput?(data: string): void; dispose?(): void };
+function borderWorkflowOverlay(component: WorkflowOverlayComponent, theme: { fg(color: "border", text: string): string }): WorkflowOverlayComponent {
+  return {
+    ...component,
+    render(width: number) {
+      const border = theme.fg("border", "─".repeat(Math.max(1, width)));
+      return [border, ...component.render(width), border];
+    },
+  };
+}
+type KeybindingsHostCapabilities = { getKeys?: (name: string) => readonly string[] };
+function isKeybindingGetter(value: unknown): value is NonNullable<KeybindingsHostCapabilities["getKeys"]> { return typeof value === "function"; }
+function keybindingsHostCapabilities(keybindings: unknown): KeybindingsHostCapabilities {
+  if (!object(keybindings) || !isKeybindingGetter(keybindings.getKeys)) return {};
+  return { getKeys: keybindings.getKeys };
+}
+function keybindingKeys(keybindings: unknown, name: string): readonly string[] | undefined { const getKeys = keybindingsHostCapabilities(keybindings).getKeys; return typeof getKeys === "function" ? getKeys.call(keybindings, name) : undefined; }
 function parseThinking(value: unknown): ModelSpec["thinking"] | undefined {
   switch (value) {
     case "off": case "minimal": case "low": case "medium": case "high": case "xhigh": case "max": return value;
@@ -2183,10 +2579,11 @@ function parseThinking(value: unknown): ModelSpec["thinking"] | undefined {
   }
 }
 
-export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard = copyToClipboard, createSession: SessionFactory = createNativeAgentSession) {
+export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard = copyToClipboard, createSession: SessionFactory = createNativeAgentSession, agentDir?: string) {
   beginWorkflowExtensionLoading();
   const registry = loadingRegistry();
-  const registerEntryRenderer = (pi as unknown as Partial<Pick<ExtensionAPI, "registerEntryRenderer">>).registerEntryRenderer;
+  const extensionAgentDir = agentDir ?? getAgentDir();
+  const registerEntryRenderer = piHostCapabilities(pi).registerEntryRenderer;
   registerEntryRenderer?.<WorkflowLogEntry>(WORKFLOW_LOG_ENTRY, (entry) => {
     const data = entry.data;
     return textBlock(data ? `Workflow ${data.workflowName}: ${data.message}` : "");
@@ -2196,7 +2593,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     try { pi.appendEntry<WorkflowLogEntry>(WORKFLOW_LOG_ENTRY, { workflowName, message: utf8Prefix(message, DELIVERY_LIMIT_BYTES) }); }
     finally { await lifecycle.leave(); }
   };
-  const eventPublisher = new WorkflowEventPublisher((pi as unknown as { events?: WorkflowEventSink }).events);
+  const eventPublisher = new WorkflowEventPublisher(piHostCapabilities(pi).events);
   pi.on("resources_discover", () => {
     if (!pi.getActiveTools().includes("workflow")) return;
     const extensionDir = dirname(fileURLToPath(import.meta.url));
@@ -2204,7 +2601,54 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     return skillPath ? { skillPaths: [skillPath] } : undefined;
   });
   type BudgetDecisionResult = { state: "running" | "budget_exhausted"; approved: boolean };
-  const runs = new Map<string, { executor: WorkflowAgentExecutor; store: RunStore; metadata: WorkflowMetadata; model: ModelSpec; lifecycle: RunLifecycle; budget: WorkflowBudgetRuntime; abortController: AbortController; projectTrusted: () => boolean; execution?: WorkflowExecution; completion?: Promise<unknown>; checkpointResolvers: Map<string, (value: boolean) => void>; budgetResolvers: Map<string, (result: BudgetDecisionResult) => void>; update?: (result: WorkflowToolUpdate) => void }>();
+  const runs = new Map<string, { executor: WorkflowAgentExecutor; store: RunStore; metadata: WorkflowMetadata; model: ModelSpec; lifecycle: RunLifecycle; budget: WorkflowBudgetRuntime; abortController: AbortController; projectTrusted: () => boolean; providerErrorRecovery?: (failure: AgentProviderFailure) => Promise<AgentProviderRecovery>; execution?: WorkflowExecution; completion?: Promise<unknown>; checkpointResolvers: Map<string, (value: boolean) => void>; update?: (result: WorkflowToolUpdate) => void }>();
+  let providerRecoveryQueue = Promise.resolve();
+  const enqueueProviderRecovery = <T>(task: () => Promise<T>): Promise<T> => { const next = providerRecoveryQueue.then(task, task); providerRecoveryQueue = next.then(() => undefined, () => undefined); return next; };
+  const createProviderErrorRecovery = (host: unknown, fallbackModels: ReadonlySet<string>, abort: () => void) => {
+    if (!object(host) || host.mode !== "tui" || host.hasUI !== true) return undefined;
+    const ui = object(host.ui) ? host.ui : undefined;
+    const select = uiHostCapabilities(ui)?.select;
+    if (!select) return undefined;
+    const hostModels = contextHostCapabilities(host).modelRegistry;
+    const choose = (title: string, options: string[]) => select.call(ui, title, options);
+    return (failure: AgentProviderFailure): Promise<AgentProviderRecovery> => enqueueProviderRecovery(async () => {
+      const action = await choose(`Subagent "${failure.label}" failed\nCurrent provider/model: ${failure.provider}/${failure.model}\nProvider error: ${failure.error}\nChoose what to do`, ["Retry", "Change model", "Abort workflow"]);
+      if (action === "Retry") return "retry";
+      if (action === "Change model") {
+        const available = hostModels?.getAvailable?.().map((model) => `${model.provider}/${model.id}`) ?? [...fallbackModels];
+        const selected = await choose(`Available models for subagent "${failure.label}"`, [...new Set(available)].sort());
+        if (selected) return { model: selected };
+      }
+      abort();
+      return "abort";
+    });
+  };
+  const pendingFailureDiagnostics = new Map<string, WorkflowFailureDiagnostics>();
+  pi.on("tool_result", (event) => {
+    if (event.toolName !== "workflow" || !event.isError) return;
+    const diagnostic = pendingFailureDiagnostics.get(event.toolCallId);
+    if (!diagnostic) return;
+    pendingFailureDiagnostics.delete(event.toolCallId);
+    return { content: [{ type: "text" as const, text: serializeWorkflowFailureDiagnostics(diagnostic) }], details: diagnostic, isError: true };
+  });
+  const liveActivities = new Map<string, Map<string, AgentActivity>>();
+  const setLiveActivity = (runId: string, agentId: string, activity?: AgentActivity) => {
+    const activities = liveActivities.get(runId);
+    if (activity) {
+      if (activities) activities.set(agentId, activity);
+      else liveActivities.set(runId, new Map([[agentId, activity]]));
+    } else {
+      activities?.delete(agentId);
+      if (activities?.size === 0) liveActivities.delete(runId);
+    }
+  };
+  const withLiveActivities = (run: PersistedRun): PersistedRun => {
+    const activities = liveActivities.get(run.id);
+    return activities?.size ? { ...run, agents: run.agents.map((agent) => {
+      const activity = activities.get(agent.id);
+      return activity ? { ...agent, activity } : agent;
+    }) } : run;
+  };
   const conversationLocks = new Set<string>();
   const terminalRunStates = new Map<string, "completed" | "failed" | "stopped">();
   let sessionLease: SessionLease | undefined;
@@ -2229,9 +2673,30 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
   const persistWorktree = async (store: RunStore, metadata: WorkflowMetadata, owner: string): Promise<WorktreeReference> => {
     const existing = (await store.worktrees()).some((worktree) => worktree.owner === owner);
     const worktree = await store.worktree(owner);
-    if (!existing) await eventPublisher.worktree(store, metadata, worktree);
+    if (!existing && await store.ownsWorktree(owner)) await eventPublisher.worktree(store, metadata, worktree);
     return worktree;
   };
+  const resolveWorktree = async (store: RunStore, metadata: WorkflowMetadata, owner: string): Promise<Readonly<WorkflowWorktreeReference>> => {
+    const run = runs.get(store.runId);
+    if (!run) fail("INTERNAL_ERROR", `Unknown production run: ${store.runId}`);
+    await run.lifecycle.enter();
+    try {
+      const worktree = await persistWorktree(store, metadata, owner);
+      return { path: worktree.path, branch: worktree.branch };
+    } finally { await run.lifecycle.leave(); }
+  };
+  const shellForRun = async (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle, command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity): Promise<ShellResult> => {
+    await lifecycle.enter();
+    try {
+      const path = shellIdentityPath(identity);
+      const replayed = await store.replay(path);
+      if (replayed) return readShellResult(replayed.value);
+      const cwd = identity.worktreeOwner ? (await persistWorktree(store, metadata, identity.worktreeOwner)).cwd : store.cwd;
+      const result = await executeShellCommand(command, options, signal, cwd);
+      await store.complete(path, result as unknown as JsonValue);
+      return result;
+    } finally { await lifecycle.leave(); }
+  };
   const lifecycleFor = (store: RunStore, state: RunState, budget: WorkflowBudgetRuntime, metadata: WorkflowMetadata) => new RunLifecycle(state, async (next, previous, reason) => {
     if (next !== "pausing") budget.transition(next);
     const persisted = await persistRunState(store, metadata, (current) => {
@@ -2240,7 +2705,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       return nextRun;
     });
     await eventPublisher.runState(store, metadata, previous, next, reason);
-    runs.get(store.runId)?.update?.(workflowToolUpdate(persisted));
+    runs.get(store.runId)?.update?.(workflowToolUpdate(withLiveActivities(persisted)));
   });
   const scheduler = new FairAgentScheduler(async ({ id, runId, parentId, prompt, options, signal, setSteer }) => {
     const run = runs.get(runId);
@@ -2257,7 +2722,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           runState = { ...loaded.run, ...run.budget.snapshot(), agents: loaded.run.agents.map((agent) => agent.id === id ? { ...agent, accounting: progress.accounting, toolCalls: progress.toolCalls, activity: progress.activity } : agent) };
         }
         if (!runState.agents.some((agent) => agent.id === id)) return;
-        run.update?.(workflowToolUpdate(runState));
+        setLiveActivity(runId, id, progress.activity);
+        run.update?.(workflowToolUpdate(withLiveActivities(runState)));
       };
       const onAttempt = async (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => {
         await scheduler.flush();
@@ -2268,15 +2734,16 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         const active = (await run.store.load()).run;
         await eventPublisher.agentStates(run.store, run.metadata, before.agents, active.agents);
         const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
-        run.update?.(workflowToolUpdate(persisted));
+        run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
       };
-      const result = await run.executor.execute(prompt, { label: options.label, workflowName: run.metadata.name, onProgress, onAttempt, budget, ...(parentId ? { parent: parentId, cwd: options.cwd, ...(options.worktreeOwner ? { worktreeOwner: options.worktreeOwner } : {}) } : options.worktreeOwner ? { worktreeOwner: options.worktreeOwner } : {}), ...(options.model ? { model: options.model } : {}), ...(options.thinking ? { thinking: options.thinking } : {}), ...(options.role ? { role: options.role } : {}), ...(options.role ? {} : { tools: options.tools }), effectiveTools: options.tools, ...(options.schema ? { schema: options.schema } : {}), ...(options.retries === undefined ? {} : { retries: options.retries }), ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.agentOptions ? { agentOptions: options.agentOptions } : {}), ...(options.agentIdentity ? { agentIdentity: options.agentIdentity } : {}), ...(options.conversation ? { conversation: options.conversation } : {}) }, signal, scheduler.toolsFor(id, (role, tools, model, inheritedTools, thinking) => run.executor.resolve({ label: "child", workflowName: run.metadata.name, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(tools !== undefined ? { tools } : {}) }, inheritedTools).tools), setSteer, () => { scheduler.cancelChildren(id); scheduler.retry(id); });
+      const result = await run.executor.execute(prompt, { label: options.label, workflowName: run.metadata.name, onProgress, onAttempt, budget, ...(run.providerErrorRecovery ? { providerErrorRecovery: run.providerErrorRecovery } : {}), ...(parentId ? { parent: parentId, cwd: options.cwd, ...(options.worktreeOwner ? { worktreeOwner: options.worktreeOwner } : {}) } : options.worktreeOwner ? { worktreeOwner: options.worktreeOwner } : {}), ...(options.model ? { model: options.model } : {}), ...(options.thinking ? { thinking: options.thinking } : {}), ...(options.role ? { role: options.role } : {}), ...(options.role ? {} : { tools: options.tools }), effectiveTools: options.tools, ...(options.schema ? { schema: options.schema } : {}), ...(options.retries === undefined ? {} : { retries: options.retries }), ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.agentOptions ? { agentOptions: options.agentOptions } : {}), ...(options.agentIdentity ? { agentIdentity: options.agentIdentity } : {}), ...(options.conversation ? { conversation: options.conversation } : {}) }, signal, scheduler.toolsFor(id, (role, tools, model, inheritedTools, thinking) => run.executor.resolve({ label: "child", workflowName: run.metadata.name, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(tools !== undefined ? { tools } : {}) }, inheritedTools).tools), setSteer, () => { scheduler.cancelChildren(id); scheduler.retry(id); });
       const before = (await run.store.load()).run;
       await persistAgentAttempts(run.store, id, result.attempts);
       const completed = (await run.store.load()).run;
       await eventPublisher.agentStates(run.store, run.metadata, before.agents, completed.agents);
       const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
-      run.update?.(workflowToolUpdate(persisted));
+      setLiveActivity(runId, id);
+      run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
       return result.value;
     } catch (error) {
       const attempts = (error as WorkflowError & { attempts?: readonly AgentAttempt[] }).attempts;
@@ -2287,7 +2754,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         await eventPublisher.agentStates(run.store, run.metadata, before.agents, failed.agents);
       }
       const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
-      run.update?.(workflowToolUpdate(persisted));
+      setLiveActivity(runId, id);
+      run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
       throw error;
     }
   }, 16, async (runId, ownership) => {
@@ -2309,8 +2777,21 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       return { ...current, agents };
     });
     await eventPublisher.agentStates(run.store, run.metadata, previousAgents, runState.agents);
-    run.update?.(workflowToolUpdate(runState));
+    run.update?.(workflowToolUpdate(withLiveActivities(runState)));
   });
+  const cleanupTerminalRun = async (runId: string): Promise<void> => {
+    const run = runs.get(runId);
+    if (!run || !["completed", "failed", "stopped"].includes(run.lifecycle.state)) return;
+    await scheduler.cancelRun(runId);
+    await scheduler.flush();
+    if (runs.get(runId) !== run) return;
+    scheduler.removeRun(runId);
+    terminalRunStates.set(runId, run.lifecycle.state as "completed" | "failed" | "stopped");
+    run.checkpointResolvers.clear();
+    liveActivities.delete(runId);
+    eventPublisher.removeRun(runId);
+    runs.delete(runId);
+  };
   type WorkflowStopResult = { runId: string; state: RunState | "unknown"; stopped: boolean; reason?: "unknown_run" | "already_terminal" };
   const stopWorkflowRun = async (runId: string): Promise<WorkflowStopResult> => {
     const run = runs.get(runId);
@@ -2323,6 +2804,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     run.execution?.cancel();
     await scheduler.cancelRun(run.store.runId);
     await scheduler.flush();
+    await cleanupTerminalRun(runId);
     return { runId, state: "stopped", stopped: true };
   };
   const answerCheckpoint = async (runId: string, name: string, approved: boolean, silent = false) => {
@@ -2349,17 +2831,16 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     if (!request) return undefined;
     await appendBudgetDecisionEvent(run, request, approved ? "adjustment_approved" : "adjustment_rejected");
     const result = await applyBudgetDecision(request, approved);
-    run.budgetResolvers.get(proposalId)?.(result);
-    run.budgetResolvers.delete(proposalId);
     if (!silent) deliver(pi, `Workflow ${run.metadata.name} budget adjustment ${proposalId}: ${approved ? "Approved" : "Rejected"}.`);
     return result;
   };
-  const checkpointBridge = (runId: string, store: RunStore, metadata: WorkflowMetadata, foreground: boolean, ui?: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }) => {
+  const checkpointBridge = (runId: string, store: RunStore, metadata: WorkflowMetadata, foreground: boolean, ui?: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }, headless = false) => {
     const checkpointCounters = new Map<string, number>();
     return async (raw: Readonly<Record<string, JsonValue>>, signal: AbortSignal): Promise<boolean> => {
       const input = validateCheckpoint(raw);
       const label = nextNamedOccurrence(checkpointCounters, input.name);
       const path = operationPath("checkpoint", label);
+      if (headless) fail("RESUME_INCOMPATIBLE", "Headless CLI checkpoints are unsupported");
       if (foreground && !ui?.select) fail("RESUME_INCOMPATIBLE", "Foreground checkpoints require UI");
       const alreadyAwaiting = (await store.awaitingCheckpoints()).some((checkpoint) => checkpoint.path === path);
       const replayed = await store.awaitCheckpoint({ ...input, name: label, path });
@@ -2434,13 +2915,16 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     if (catalogRegistered || !pi.getActiveTools().includes("workflow")) return;
     const catalog = registry.catalog();
     const hasAliases = Object.keys(catalog.modelAliases ?? {}).length > 0;
-    if (!catalog.functions.length && !catalog.variables.length && !catalog.workflows.length && !hasAliases) return;
+    if (!catalog.functions.length && !catalog.variables.length && !hasAliases) return;
     pi.registerTool({
       name: "workflow_catalog",
       label: "Workflow Catalog",
-      description: "List global workflow functions, variables, and reusable workflows",
-      parameters: Type.Object({}, { additionalProperties: false }),
-      async execute() { return { content: [{ type: "text" as const, text: JSON.stringify(registry.catalog()) }], details: {} }; }
+      description: "List reusable workflow functions, variables, and model aliases, or load one entry in full",
+      parameters: Type.Object({ name: Type.Optional(Type.String({ description: "Registered function or variable name for full detail" })) }, { additionalProperties: false }),
+      async execute(_id, params = {}) {
+        const result = params.name === undefined ? registry.catalogIndex() : registry.catalogDetail(params.name);
+        return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: result };
+      }
     });
     catalogRegistered = true;
   };
@@ -2449,7 +2933,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     const active = new Set(pi.getActiveTools().filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_stop" && tool !== "workflow_catalog"));
     const missing = loaded.snapshot.tools.filter((tool) => tool !== "workflow_catalog").find((tool) => !active.has(tool));
     if (missing) throw new WorkflowError("RESUME_INCOMPATIBLE", `Required tool is unavailable: ${missing}`);
-    const settingsPath = workflowSettingsPath();
+    const settingsPath = workflowSettingsPath(extensionAgentDir);
     const currentSettings = loadSettings(settingsPath);
     resolveAgentResourcePolicy(run.store.cwd, run.projectTrusted(), settingsPath);
     const currentAliases = currentSettings.modelAliases ?? {};
@@ -2462,13 +2946,14 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     const blockedAliasTargets = Object.fromEntries(Object.entries(previousAliases).filter(([name]) => !Object.prototype.hasOwnProperty.call(currentAliases, name)));
     const snapshot = createLaunchSnapshot({ ...loaded.snapshot, settingsPath, settings: { ...loaded.snapshot.settings, modelAliases: currentAliases }, modelAliases: currentAliases });
     await run.store.saveSnapshot(snapshot);
-    run.executor = new WorkflowAgentExecutor({ cwd: run.store.cwd, model: run.model, tools: new Set(snapshot.tools.filter((tool) => pi.getActiveTools().includes(tool) && tool !== "workflow_catalog")), availableModels: resumeModels, knownModels: resumeModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: snapshot.roles ?? {}, runStore: run.store, providerPause: async () => { deliver(pi, `Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(run.store.cwd, run.projectTrusted(), settingsPath) }, createSession);
+    run.executor = new WorkflowAgentExecutor({ cwd: run.store.cwd, agentDir: extensionAgentDir, model: run.model, tools: new Set(snapshot.tools.filter((tool) => pi.getActiveTools().includes(tool) && tool !== "workflow_catalog")), availableModels: resumeModels, knownModels: resumeModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: snapshot.roles ?? {}, runStore: run.store, providerPause: async () => { deliver(pi, `Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(run.store.cwd, run.projectTrusted(), settingsPath) }, createSession);
     run.executor.setRunContext(workflowRunContext(run.store.cwd, run.store.sessionId, run.store.runId, loaded.snapshot.metadata, loaded.snapshot.args, run.abortController.signal));
     const drift = aliasDrift(previousAliases, currentAliases);
     if (drift.length) await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
   };
   const coldResumeRun = async (run: NonNullable<ReturnType<typeof runs.get>>, hasUI: boolean, ui: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }, trustedProject: boolean, context?: { model: { provider: string; id: string } | undefined; modelRegistry: { getAll?: () => Array<{ provider: string; id: string }>; getAvailable?: () => Array<{ provider: string; id: string }> } | undefined }) => {
     const loaded = await run.store.load();
+    await run.store.validateBorrowedWorktrees();
     if (loaded.snapshot.identityVersion !== LAUNCH_SNAPSHOT_IDENTITY_VERSION) throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow launch snapshot identity version is incompatible");
     if (loaded.snapshot.roles === undefined) throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow role definitions are missing from the launch snapshot");
     if ((loaded.snapshot.projectRoles?.length ?? 0) > 0 && !trustedProject) throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot restore project roles in an untrusted project");
@@ -2477,7 +2962,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     const active = new Set(pi.getActiveTools().filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_stop" && tool !== "workflow_catalog"));
     const missing = loaded.snapshot.tools.filter((tool) => tool !== "workflow_catalog").find((tool) => !active.has(tool));
     if (missing) throw new WorkflowError("RESUME_INCOMPATIBLE", `Required tool is unavailable: ${missing}`);
-    const settingsPath = workflowSettingsPath();
+    const settingsPath = workflowSettingsPath(extensionAgentDir);
     const currentSettings = loadSettings(settingsPath);
     resolveAgentResourcePolicy(run.store.cwd, trustedProject, settingsPath);
     const currentAliases = currentSettings.modelAliases ?? {};
@@ -2489,10 +2974,11 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     const resumeAliases = { ...previousAliases, ...currentAliases };
     const blockedAliases = new Set(Object.keys(previousAliases).filter((name) => !Object.prototype.hasOwnProperty.call(currentAliases, name)));
     const blockedAliasTargets = Object.fromEntries(Object.entries(previousAliases).filter(([name]) => !Object.prototype.hasOwnProperty.call(currentAliases, name)));
-    preflight(loaded.snapshot.script, { models: resumeModels, tools: active, agentTypes: new Set(loaded.snapshot.agentTypes), modelAliases: resumeAliases, knownModels: resumeModels, settingsPath, skipModelAvailability: true }, loaded.snapshot.schemas, loaded.snapshot.metadata);
+    const script = launchScriptForSnapshot(loaded.snapshot, registry);
+    preflight(script, { models: resumeModels, tools: active, agentTypes: new Set(loaded.snapshot.agentTypes), modelAliases: resumeAliases, knownModels: resumeModels, settingsPath, skipModelAvailability: true }, loaded.snapshot.schemas, loaded.snapshot.metadata);
     const snapshot = createLaunchSnapshot({ ...loaded.snapshot, settingsPath, settings: { ...loaded.snapshot.settings, modelAliases: currentAliases }, modelAliases: currentAliases });
     await run.store.saveSnapshot(snapshot);
-    run.executor = new WorkflowAgentExecutor({ cwd: run.store.cwd, model: run.model, tools: new Set(snapshot.tools.filter((tool) => pi.getActiveTools().includes(tool) && tool !== "workflow_catalog")), availableModels: resumeModels, knownModels: resumeModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: snapshot.roles ?? {}, runStore: run.store, providerPause: async () => { deliver(pi, `Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(run.store.cwd, run.projectTrusted(), settingsPath) }, createSession);
+    run.executor = new WorkflowAgentExecutor({ cwd: run.store.cwd, agentDir: extensionAgentDir, model: run.model, tools: new Set(snapshot.tools.filter((tool) => pi.getActiveTools().includes(tool) && tool !== "workflow_catalog")), availableModels: resumeModels, knownModels: resumeModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: snapshot.roles ?? {}, runStore: run.store, providerPause: async () => { deliver(pi, `Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(run.store.cwd, run.projectTrusted(), settingsPath) }, createSession);
     const drift = aliasDrift(previousAliases, currentAliases);
     if (drift.length) await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
     const controller = new AbortController();
@@ -2503,12 +2989,13 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     try { variables = await resolveWorkflowVariables(runContext, controller, registry); }
     catch (error) {
       const typed = asWorkflowError(error);
-      if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.lifecycle.terminal("failed", typed.code).catch(() => undefined); const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, error: { code: typed.code, message: typed.message } })); await eventPublisher.runFailed(run.store, run.metadata, typed, true, run.lifecycle.state === "interrupted" ? "interrupted" : "failed"); run.update?.(workflowToolUpdate(persisted)); }
+      if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.lifecycle.terminal("failed", typed.code).catch(() => undefined); const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, error: { code: typed.code, message: typed.message } })); await eventPublisher.runFailed(run.store, run.metadata, typed, run.lifecycle.state === "interrupted" ? "interrupted" : "failed"); run.update?.(workflowToolUpdate(persisted)); }
+      await cleanupTerminalRun(run.store.runId);
       throw typed;
     }
     await scheduler.cancelRun(run.store.runId);
     await run.lifecycle.resume();
-    const execution = runWorkflow(loaded.snapshot.script, loaded.snapshot.args, withWorkflowFunctions({ agent: async (prompt, options, signal, identity) => {
+    const execution = runWorkflow(script, loaded.snapshot.args, withWorkflowFunctions({ shell: (command, options, signal, identity) => shellForRun(run.store, run.metadata, run.lifecycle, command, options, signal, identity), agent: async (prompt, options, signal, identity) => {
       await run.lifecycle.enter();
       const conversationId = identity.conversation ? conversationIdentityPath(identity) : undefined;
       const conversationLock = conversationId ? `${run.store.runId}:${conversationId}` : "";
@@ -2546,14 +3033,14 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         await run.store.complete(path, outcome.value);
         return outcome.value;
       } finally { if (conversationLock) conversationLocks.delete(conversationLock); await run.lifecycle.leave(); }
-    }, checkpoint: checkpointBridge(run.store.runId, run.store, run.metadata, false, hasUI ? ui : undefined), phase: async (phase) => { await run.lifecycle.enter(); try { let previousPhase: string | undefined; const persisted = await persistRunState(run.store, run.metadata, (current) => { previousPhase = current.phase; return { ...current, phase }; }); await eventPublisher.phase(run.store, run.metadata, previousPhase, phase); runs.get(run.store.runId)?.update?.(workflowToolUpdate(persisted)); } finally { await run.lifecycle.leave(); } }, log: logBridge(run.lifecycle, run.metadata.name) }, run.store, runContext, variables, registry), controller.signal);
+      }, worktree: async (owner) => resolveWorktree(run.store, run.metadata, owner), checkpoint: checkpointBridge(run.store.runId, run.store, run.metadata, false, hasUI ? ui : undefined), phase: async (phase) => { await run.lifecycle.enter(); try { let previousPhase: string | undefined; const persisted = await persistRunState(run.store, run.metadata, (current) => { previousPhase = current.phase; return { ...current, phase }; }); await eventPublisher.phase(run.store, run.metadata, previousPhase, phase); runs.get(run.store.runId)?.update?.(workflowToolUpdate(persisted)); } finally { await run.lifecycle.leave(); } }, log: logBridge(run.lifecycle, run.metadata.name) }, run.store, runContext, variables, registry), controller.signal);
     run.execution = execution;
     const completion = execution.result.then(async (value) => {
       await scheduler.flush();
       if (run.budget.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
       const resultPath = await run.store.saveResult(value);
       await run.lifecycle.terminal("completed", "completed");
-      await eventPublisher.runCompleted(run.store, run.metadata, resultPath, true);
+      await eventPublisher.runCompleted(run.store, run.metadata, resultPath);
       return { value, resultPath };
     }).catch(async (error: unknown) => {
       await scheduler.flush();
@@ -2561,10 +3048,11 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) await run.lifecycle.terminal(typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
       const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot(), error: { code: typed.code, message: typed.message } }));
       const state = run.lifecycle.state === "stopped" || run.lifecycle.state === "interrupted" || run.lifecycle.state === "budget_exhausted" ? run.lifecycle.state : "failed";
-      await eventPublisher.runFailed(run.store, run.metadata, typed, true, state);
+      await eventPublisher.runFailed(run.store, run.metadata, typed, state);
       run.update?.(workflowToolUpdate(persisted));
-      if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) deliverFailure(pi, run.metadata.name, error);
-    });
+      if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) deliverFailure(pi, createWorkflowFailureDiagnostics(run.store, run.metadata, typed, persisted));
+    }).finally(() => cleanupTerminalRun(run.store.runId));
+    run.completion = completion;
     void completion;
   };
   const applyBudgetDecision = async (request: BudgetApprovalRequest, approved: boolean): Promise<BudgetDecisionResult> => {
@@ -2592,11 +3080,10 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     if (budgetRelaxed(currentBudget, nextBudget)) {
       const proposalId = randomUUID();
       const request: BudgetApprovalRequest = { kind: "budget", proposalId, runId, consumed: usage, previous: currentBudget ?? {}, proposed: nextBudget ?? {}, budgetVersion: loaded.run.budgetVersion ?? 1 };
-      const decision = new Promise<BudgetDecisionResult>((resolve) => { run.budgetResolvers.set(proposalId, resolve); });
-      try { await run.store.requestWorkflowDecision(request); await appendBudgetDecisionEvent(run, request, "adjustment_requested"); } catch (error) { run.budgetResolvers.delete(proposalId); throw error; }
+      await run.store.requestWorkflowDecision(request);
+      await appendBudgetDecisionEvent(run, request, "adjustment_requested");
       deliver(pi, budgetDecisionDelivery(run.metadata, request));
-      const decisionResult = await decision;
-      return { state: decisionResult.state };
+      return { state: "awaiting_approval", proposalId };
     }
     const changed = JSON.stringify(currentBudget ?? {}) !== JSON.stringify(nextBudget ?? {});
     if (changed) {
@@ -2645,12 +3132,14 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       const lifecycle = lifecycleFor(store, loaded.run.state, budgetRuntime, loaded.snapshot.metadata);
       const providerPause = async () => { deliver(pi, `Workflow ${loaded.snapshot.metadata.name} paused: provider limit.`); await lifecycle.providerPause(); };
       const roleDefinitions = loaded.snapshot.roles ?? {};
-      runs.set(runId, { executor: new WorkflowAgentExecutor({ cwd: ctx.cwd, model, tools: new Set(loaded.snapshot.tools.filter((tool) => pi.getActiveTools().includes(tool) && tool !== "workflow_catalog")), availableModels: new Set(loaded.snapshot.models), knownModels: new Set(loaded.snapshot.models), ...(loaded.snapshot.modelAliases ?? loaded.snapshot.settings.modelAliases ? { modelAliases: loaded.snapshot.modelAliases ?? loaded.snapshot.settings.modelAliases } : {}), ...(loaded.snapshot.settingsPath ? { settingsPath: loaded.snapshot.settingsPath } : {}), agentDefinitions: roleDefinitions, runStore: store, providerPause, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(store.cwd, projectTrusted(ctx)) }, createSession), store, metadata: loaded.snapshot.metadata, model, lifecycle, budget: budgetRuntime, abortController: new AbortController(), projectTrusted: () => projectTrusted(ctx), checkpointResolvers: new Map(), budgetResolvers: new Map() });
+      const abortController = new AbortController();
+      const providerErrorRecovery = createProviderErrorRecovery(ctx, new Set(loaded.snapshot.models), () => { abortController.abort(); });
+      runs.set(runId, { executor: new WorkflowAgentExecutor({ cwd: ctx.cwd, agentDir: extensionAgentDir, model, tools: new Set(loaded.snapshot.tools.filter((tool) => pi.getActiveTools().includes(tool) && tool !== "workflow_catalog")), availableModels: new Set(loaded.snapshot.models), knownModels: new Set(loaded.snapshot.models), ...(loaded.snapshot.modelAliases ?? loaded.snapshot.settings.modelAliases ? { modelAliases: loaded.snapshot.modelAliases ?? loaded.snapshot.settings.modelAliases } : {}), ...(loaded.snapshot.settingsPath ? { settingsPath: loaded.snapshot.settingsPath } : {}), agentDefinitions: roleDefinitions, runStore: store, providerPause, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(store.cwd, projectTrusted(ctx), loaded.snapshot.settingsPath ?? workflowSettingsPath(extensionAgentDir)) }, createSession), store, metadata: loaded.snapshot.metadata, model, lifecycle, budget: budgetRuntime, abortController, projectTrusted: () => projectTrusted(ctx), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}) });
       for (const checkpoint of await store.awaitingCheckpoints()) deliver(pi, `Workflow ${loaded.snapshot.metadata.name} checkpoint ${checkpoint.name}: ${checkpoint.prompt}\nContext: ${JSON.stringify(checkpoint.context)}\nRespond with workflow_respond.`);
       for (const decision of await store.pendingWorkflowDecisions()) deliver(pi, budgetDecisionDelivery(loaded.snapshot.metadata, decision));
       scheduler.restoreRun(runId, loaded.snapshot.settings.concurrency, loaded.snapshot.identityVersion === LAUNCH_SNAPSHOT_IDENTITY_VERSION ? await store.loadOwnership() : [], () => runs.get(runId)?.budget.checkAgentLaunch());
     }
-    const resumeSelect = (ctx.ui as unknown as { select?: (prompt: string, options: string[]) => Promise<string | undefined> } | undefined)?.select;
+    const resumeSelect = uiHostCapabilities(ctx.ui)?.select;
     if (ctx.hasUI && resumeSelect) {
       const interrupted = [...runs.values()].filter((r) => r.lifecycle.state === "interrupted");
       if (interrupted.length > 0) {
@@ -2670,7 +3159,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
   });
   pi.on("before_agent_start", (event, ctx) => {
     if (!pi.getActiveTools().includes("workflow")) return;
-    const roles = Object.entries(loadAgentDefinitions(ctx.cwd, undefined, projectTrusted(ctx))).filter(([, definition]) => definition.description);
+    const roles = Object.entries(loadAgentDefinitions(ctx.cwd, extensionAgentDir, projectTrusted(ctx))).filter(([, definition]) => definition.description);
     if (!roles.length) return;
     const content = `Workflow role descriptions:\n${roles.map(([name, definition]) => `- \`${name}\`: ${String(definition.description)}`).join("\n")}`;
     return { systemPrompt: `${event.systemPrompt}\n\n${content}` };
@@ -2681,24 +3170,25 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     description: WORKFLOW_TOOL_DESCRIPTION,
     promptSnippet: WORKFLOW_TOOL_PROMPT_SNIPPET,
     parameters: WORKFLOW_TOOL_PARAMETERS,
-    async execute(_id, params, signal, onUpdate, ctx) {
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
       try {
-      const settingsPath = workflowSettingsPath();
+      const headless = object(ctx) && ctx.headless === true;
+      const settingsPath = workflowSettingsPath(extensionAgentDir);
       const defaults = loadSettings(settingsPath);
       if (!ctx.model) throw new WorkflowError("UNKNOWN_MODEL", "A launching model is required");
       const settings = Object.freeze({ concurrency: params.concurrency ?? defaults.concurrency, ...(defaults.modelAliases ? { modelAliases: defaults.modelAliases } : {}) });
       const budget = validateBudget(params.budget);
       const rootModel: ModelSpec = { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() };
       const rootModelName = `${rootModel.provider}/${rootModel.model}`;
-      const modelRegistry = (ctx as unknown as { modelRegistry?: { getAll?: () => Array<{ provider: string; id: string }>; getAvailable?: () => Array<{ provider: string; id: string }> } }).modelRegistry;
+      const modelRegistry = contextHostCapabilities(ctx).modelRegistry;
       const knownModels = new Set((modelRegistry?.getAll?.() ?? modelRegistry?.getAvailable?.() ?? [ctx.model]).map((model) => `${model.provider}/${model.id}`));
       knownModels.add(rootModelName);
       const availableModels = knownModels;
       const rootTools = pi.getActiveTools().filter((name) => name !== "workflow" && name !== "workflow_respond" && name !== "workflow_stop" && name !== "workflow_catalog");
       const trustedProject = projectTrusted(ctx);
       if (typeof ctx.cwd === "string") resolveAgentResourcePolicy(ctx.cwd, trustedProject, settingsPath);
-      const validated = validateWorkflowLaunchWithRegistry(params, { cwd: ctx.cwd, projectTrusted: trustedProject, availableModels, rootTools: new Set(rootTools), modelAliases: defaults.modelAliases ?? {}, knownModels, settingsPath }, registry);
-      const { script, checked, agentDefinitions, projectAgentDefinitions, roleNames } = validated;
+      const validated = validateWorkflowLaunchWithRegistry({ ...params, args: params.args }, { cwd: ctx.cwd, agentDir: extensionAgentDir, projectTrusted: trustedProject, availableModels, rootTools: new Set(rootTools), modelAliases: defaults.modelAliases ?? {}, knownModels, settingsPath }, registry);
+      const { script, checked, agentDefinitions, projectAgentDefinitions, roleNames, functionName } = validated;
       await ensureSessionLease(ctx.cwd, ctx.sessionManager.getSessionId());
       const runId = randomUUID();
       const args = (params.args ?? null) as JsonValue;
@@ -2708,22 +3198,25 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       const runContext = workflowRunContext(ctx.cwd, ctx.sessionManager.getSessionId(), runId, checked.metadata, args, runController.signal);
       const variables = await resolveWorkflowVariables(runContext, runController, registry);
       const store = new RunStore(ctx.cwd, ctx.sessionManager.getSessionId(), runId, home);
+      const parentRunId = params.parentRunId;
+      if (parentRunId !== undefined) await store.validateParentRun(parentRunId);
       const roles = Object.fromEntries(roleNames.map((role) => [role, agentDefinitions[role]])) as Record<string, AgentDefinition>;
       const projectRoles = roleNames.filter((role) => projectAgentDefinitions[role] !== undefined);
       const roleModels = roleNames.flatMap((role) => { const model = agentDefinitions[role]?.model; return model ? [modelCapability(model, defaults.modelAliases, knownModels, settingsPath)] : []; });
       const snapshotModels = [...new Set([rootModelName, ...checked.referenced.models, ...roleModels])];
-      const snapshot = createLaunchSnapshot({ script, args, metadata: checked.metadata, settings, settingsPath, ...(defaults.modelAliases ? { modelAliases: defaults.modelAliases } : {}), ...(budget ? { budget } : {}), models: snapshotModels, tools: rootTools, agentTypes: checked.referenced.agentTypes, roles, projectRoles, schemas: checked.schemas });
+      const snapshot = createLaunchSnapshot({ script, args, metadata: checked.metadata, settings, settingsPath, ...(functionName ? { launchKind: "function" as const, functionName } : {}), ...(defaults.modelAliases ? { modelAliases: defaults.modelAliases } : {}), ...(budget ? { budget } : {}), models: snapshotModels, tools: rootTools, agentTypes: checked.referenced.agentTypes, roles, projectRoles, schemas: checked.schemas });
       const budgetRuntime = new WorkflowBudgetRuntime(budget);
       const initialBudget = budgetRuntime.snapshot();
-      await store.create({ id: runId, workflowName: checked.metadata.name, cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId(), state: "running", agents: [], nativeSessions: [], ...(budget ? { budget } : {}), budgetVersion: 1, ...initialBudget }, snapshot);
+      await store.create({ id: runId, workflowName: checked.metadata.name, cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId(), state: "running", ...(parentRunId !== undefined ? { parentRunId } : {}), agents: [], nativeSessions: [], ...(budget ? { budget } : {}), budgetVersion: 1, ...initialBudget }, snapshot);
       const lifecycle = lifecycleFor(store, "running", budgetRuntime, checked.metadata);
       const background = !params.foreground;
       const providerPause = async () => { if (background) deliver(pi, `Workflow ${checked.metadata.name} paused: provider limit.`); await lifecycle.providerPause(); };
-      const executor = new WorkflowAgentExecutor({ cwd: ctx.cwd, model: rootModel, tools: new Set(rootTools), availableModels, knownModels, modelAliases: defaults.modelAliases ?? {}, settingsPath, agentDefinitions, runStore: store, providerPause, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(ctx.cwd, projectTrusted(ctx)), runContext }, createSession);
-      runs.set(runId, { executor, store, metadata: checked.metadata, model: rootModel, lifecycle, budget: budgetRuntime, abortController: runController, projectTrusted: () => projectTrusted(ctx), checkpointResolvers: new Map(), budgetResolvers: new Map(), ...(params.foreground && onUpdate ? { update: onUpdate } : {}) });
+      const providerErrorRecovery = createProviderErrorRecovery(ctx, availableModels, () => { runController.abort(); });
+      const executor = new WorkflowAgentExecutor({ cwd: ctx.cwd, agentDir: extensionAgentDir, model: rootModel, tools: new Set(rootTools), availableModels, knownModels, modelAliases: defaults.modelAliases ?? {}, settingsPath, agentDefinitions, runStore: store, providerPause, agentSetupHooks: registry.agentSetupHooks(), agentResourcePolicy: () => resolveAgentResourcePolicy(ctx.cwd, projectTrusted(ctx), settingsPath), runContext }, createSession);
+      runs.set(runId, { executor, store, metadata: checked.metadata, model: rootModel, lifecycle, budget: budgetRuntime, abortController: runController, projectTrusted: () => projectTrusted(ctx), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}), ...(params.foreground && onUpdate ? { update: onUpdate } : {}) });
       if (params.foreground && onUpdate) onUpdate(workflowToolUpdate((await store.load()).run));
       scheduler.addRun(runId, settings.concurrency, () => runs.get(runId)?.budget.checkAgentLaunch());
-      const execution = runWorkflow(script, args, withWorkflowFunctions({ agent: async (prompt, options, agentSignal, identity) => {
+      const execution = runWorkflow(script, args, withWorkflowFunctions({ shell: (command, options, signal, identity) => shellForRun(store, checked.metadata, lifecycle, command, options, signal, identity), agent: async (prompt, options, agentSignal, identity) => {
         await lifecycle.enter();
         const conversationId = identity.conversation ? conversationIdentityPath(identity) : undefined;
         const conversationLock = conversationId ? `${runId}:${conversationId}` : "";
@@ -2761,7 +3254,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           await store.complete(path, outcome.value);
           return outcome.value;
         } finally { if (conversationLock) conversationLocks.delete(conversationLock); await lifecycle.leave(); }
-      }, checkpoint: checkpointBridge(runId, store, checked.metadata, Boolean(params.foreground), params.foreground && ctx.hasUI ? ctx.ui : undefined), phase: async (phase) => {
+      }, worktree: async (owner) => resolveWorktree(store, checked.metadata, owner), checkpoint: checkpointBridge(runId, store, checked.metadata, Boolean(params.foreground), params.foreground && ctx.hasUI ? ctx.ui : undefined, headless), phase: async (phase) => {
         await lifecycle.enter();
         try {
           let previousPhase: string | undefined;
@@ -2771,33 +3264,41 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         } finally { await lifecycle.leave(); }
       }, log: logBridge(lifecycle, checked.metadata.name) }, store, runContext, variables, registry), runController.signal);
       (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).execution = execution;
-      await eventPublisher.runStarted(store, checked.metadata, background);
+      await eventPublisher.runStarted(store, checked.metadata);
       const finish = execution.result.then(async (value) => {
         await scheduler.flush();
         if (budgetRuntime.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
         const resultPath = await store.saveResult(value);
         await lifecycle.terminal("completed", "completed");
-        await eventPublisher.runCompleted(store, checked.metadata, resultPath, background);
+        await eventPublisher.runCompleted(store, checked.metadata, resultPath);
         return { value, resultPath };
       }).catch(async (error: unknown) => {
         await scheduler.flush();
         const typed = error instanceof WorkflowError ? error : new WorkflowError("INTERNAL_ERROR", String(error));
         if (!["stopped", "interrupted", "budget_exhausted"].includes(lifecycle.state)) await lifecycle.terminal(typed.code === "CANCELLED" ? "stopped" : typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
-        await persistRunState(store, checked.metadata, (current) => ({ ...current, ...budgetRuntime.snapshot(), error: { code: typed.code, message: typed.message } }));
+        const persisted = await persistRunState(store, checked.metadata, (current) => ({ ...current, ...budgetRuntime.snapshot(), error: { code: typed.code, message: typed.message } }));
         const state = lifecycle.state === "stopped" || lifecycle.state === "interrupted" || lifecycle.state === "budget_exhausted" ? lifecycle.state : "failed";
-        await eventPublisher.runFailed(store, checked.metadata, typed, background, state);
+        await eventPublisher.runFailed(store, checked.metadata, typed, state);
+        const diagnostic = createWorkflowFailureDiagnostics(store, checked.metadata, typed, persisted);
+        Object.defineProperty(typed, WORKFLOW_FAILURE_DIAGNOSTICS, { value: diagnostic });
+        if (params.foreground) pendingFailureDiagnostics.set(toolCallId, diagnostic);
         throw typed;
       });
-      (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).completion = finish;
+      const completion = finish.finally(() => cleanupTerminalRun(runId));
+      (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).completion = completion;
       if (background) {
-        void finish.then(async ({ value, resultPath }) => {
+        void completion.then(async ({ value, resultPath }) => {
           deliver(pi, completionDelivery(checked.metadata.name, value, resultPath, await store.changedWorktrees()));
-        }, (error: unknown) => { deliverFailure(pi, checked.metadata.name, error); });
+        }, (error: unknown) => {
+          const diagnostic = failureDiagnosticsFrom(error);
+          if (diagnostic) deliverFailure(pi, diagnostic);
+          else deliver(pi, `Workflow ${checked.metadata.name} failed: ${formatWorkflowFailure(error)}`);
+        });
         return { content: [{ type: "text" as const, text: JSON.stringify({ runId, state: "running" }) }], details: { runId, preview: `Started workflow ${runId}.` } };
       }
-      const { value } = await finish;
+      const { value } = await completion;
       const run = (await store.load()).run;
-      return { content: [{ type: "text" as const, text: JSON.stringify(value) }], details: { runId, value, run } };
+      return { content: [{ type: "text" as const, text: JSON.stringify(value) }, { type: "text" as const, text: `Workflow run ID: ${runId}` }], details: { runId, value, run } };
       } catch (error) {
         throw mainAgentError(error);
       }
@@ -2806,18 +3307,20 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       return textBlock(formatWorkflowPreview(args));
     },
     renderResult(result, { isPartial }, _theme, context) {
-      const details = result.details as { run?: PersistedRun; value?: JsonValue; preview?: string } | undefined;
+      const details = result.details;
+      if (isWorkflowFailureDiagnostics(details)) return textBlock(formatWorkflowFailureDiagnostics(details));
+      const runDetails = details as { run?: PersistedRun; value?: JsonValue; preview?: string } | undefined;
       const state = context.state as { workflowSpinner?: ReturnType<typeof setInterval> };
-      if (details?.run && isPartial && details.run.state === "running" && !state.workflowSpinner) {
+      if (runDetails?.run && isPartial && runDetails.run.state === "running" && !state.workflowSpinner) {
         state.workflowSpinner = setInterval(context.invalidate, 80);
         state.workflowSpinner.unref();
-      } else if ((!isPartial || details?.run?.state !== "running") && state.workflowSpinner) {
+      } else if ((!isPartial || runDetails?.run?.state !== "running") && state.workflowSpinner) {
         clearInterval(state.workflowSpinner);
         delete state.workflowSpinner;
       }
-      if (details?.run) return workflowProgressBlock(details.run);
+      if (runDetails?.run) return workflowProgressBlock(runDetails.run);
       const content = result.content[0];
-      return textBlock(isPartial ? "Workflow starting..." : details?.preview ?? (content?.type === "text" ? content.text : "Workflow finished"));
+      return textBlock(isPartial ? "Workflow starting..." : runDetails?.preview ?? (content?.type === "text" ? content.text : "Workflow finished"));
     },
   });
   pi.registerCommand("workflow", {
@@ -2842,7 +3345,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       let stores = await loadStores();
       const usage = "Usage: /workflow [doctor|model-aliases], or /workflow pause|resume|stop|approve|reject|delete <run-id> [checkpoint or proposal-id]. Use workflow_resume for budget patches."
       const setWorkflowStatus = (text: string | undefined) => {
-        const setStatus = (ctx.ui as unknown as { setStatus?: (key: string, text?: string) => void }).setStatus;
+        const setStatus = uiHostCapabilities(ctx.ui)?.setStatus;
         setStatus?.call(ctx.ui, "workflow-stop", text);
       };
       const runAction = async (actionCommand: string, keepContext: boolean, status: (text: string | undefined) => void = setWorkflowStatus): Promise<"dashboard" | "picker" | "done"> => {
@@ -2883,7 +3386,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             return keepContext ? "dashboard" : "done";
           }
           if (action === "adjust" && run?.lifecycle.state === "budget_exhausted") {
-            const input = await (ctx.ui as unknown as { input?: (title: string, placeholder?: string) => Promise<string | undefined> }).input?.("Budget patch (JSON)", "{\"tokens\":{\"hard\":null}}" );
+            const input = await uiHostCapabilities(ctx.ui)?.input?.call(ctx.ui, "Budget patch (JSON)", "{\"tokens\":{\"hard\":null}}" );
             if (input === undefined) return keepContext ? "dashboard" : "done";
             const result = await resumeWorkflowRun(run.store.runId, JSON.parse(input));
             ctx.ui.notify(result.state === "running" ? `Resumed workflow ${run.store.runId}.` : `Budget adjustment for ${run.store.runId} is awaiting approval.`, result.state === "running" ? "info" : "warning");
@@ -2909,8 +3412,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         }
       };
       const manageAliases = async (): Promise<void> => {
-        const settingsPath = workflowSettingsPath();
-        const modelRegistry = (ctx as unknown as { modelRegistry?: { getAvailable?: () => Array<{ provider: string; id: string }> } }).modelRegistry;
+        const settingsPath = workflowSettingsPath(extensionAgentDir);
+        const modelRegistry = contextHostCapabilities(ctx).modelRegistry;
         const available = () => [...new Set((modelRegistry?.getAvailable?.() ?? []).map((model) => `${model.provider}/${model.id}`))].sort();
         const selectTarget = async (): Promise<string | undefined> => {
           const models = available();
@@ -2985,9 +3488,18 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           const labels = navigatorRunLabels(sorted);
           const terminalStates = new Set(["completed", "failed", "stopped"]);
           const hasCompleted = sorted.some(({ loaded: { run } }) => run.state === "completed");
-          const pickerOptions = [...labels, "Model aliases", "Close", ...(hasCompleted ? ["Delete all completed"] : [])];
+          const pickerOptions = [...labels, ...(herdrPaneId() ? ["Inspect session in pane"] : []), "Model aliases", "Close", ...(hasCompleted ? ["Delete all completed"] : [])];
           const runChoice = await ctx.ui.select("Workflows\n", pickerOptions);
           if (!runChoice || runChoice === "Close") return;
+          if (runChoice === "Inspect session in pane") {
+            try {
+              await openHerdrPane({ action: "inspect", cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId() });
+              ctx.ui.notify("Opened session inspector in pane.", "info");
+            } catch (error) {
+              ctx.ui.notify(`Cannot open session inspector in pane: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            }
+            continue;
+          }
           if (runChoice === "Model aliases") { await manageAliases(); stores = await loadStores(); continue; }
           if (runChoice === "Delete all completed") {
             if (!await ctx.ui.confirm("Delete completed runs?", "Delete all completed workflow runs and their artifacts? This cannot be undone.")) continue;
@@ -3009,38 +3521,6 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
               ctx.ui.notify(`Failed to copy ${artifact}: ${error instanceof Error ? error.message : String(error)}`, "error");
             }
           };
-          const openTranscript = async (transcript: string): Promise<void> => {
-            try {
-              const entries = SessionManager.open(transcript).buildContextEntries();
-              if (ctx.mode !== "tui") { ctx.ui.notify(`Transcript: ${transcript}`, "info"); return; }
-              await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
-                let offset = 0;
-                let renderedLines: string[] = [];
-                const viewport = () => Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24) - 3);
-                const move = (delta: number) => { offset = Math.max(0, Math.min(Math.max(0, renderedLines.length - viewport()), offset + delta)); };
-                return {
-                  render(width: number) {
-                    renderedLines = transcriptLines(entries).flatMap((line) => line ? truncateToVisualLines(line, Number.MAX_SAFE_INTEGER, width, 0).visualLines : [""]);
-                    offset = Math.min(offset, Math.max(0, renderedLines.length - viewport()));
-                    return [theme.fg("accent", "Native Pi transcript"), ...renderedLines.slice(offset, offset + viewport()), "", theme.fg("dim", "↑↓/pgup/pgdn scroll · esc close")];
-                  },
-                  invalidate() {},
-                  handleInput(data: string) {
-                    if (keybindings.matches(data, "tui.select.up")) move(-1);
-                    else if (keybindings.matches(data, "tui.select.down")) move(1);
-                    else if (keybindings.matches(data, "tui.select.pageUp")) move(-viewport());
-                    else if (keybindings.matches(data, "tui.select.pageDown")) move(viewport());
-                    else if (keybindings.matches(data, "tui.editor.cursorLineStart")) offset = 0;
-                    else if (keybindings.matches(data, "tui.editor.cursorLineEnd")) offset = Math.max(0, renderedLines.length - viewport());
-                    else if (keybindings.matches(data, "tui.select.cancel")) done(undefined);
-                    tui.requestRender();
-                  },
-                };
-              }, { overlay: true });
-            } catch (error) {
-              ctx.ui.notify(`Cannot open transcript: ${error instanceof Error ? error.message : String(error)}`, "warning");
-            }
-          };
           const loadDashboard = async () => {
             const loaded = await store.load();
             const checkpoints = await store.awaitingCheckpoints();
@@ -3071,16 +3551,13 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             }
             if (ctx.mode !== "tui") actions.set("Refresh", "refresh");
             else actions.set("View script", "view-script");
-            const transcripts = [...new Set([...loaded.run.agents.flatMap((agent) => (agent.attemptDetails ?? []).map((attempt) => attempt.sessionFile)), ...loaded.run.nativeSessions.map(({ sessionFile }) => sessionFile)])];
             if (loaded.run.agents.length) actions.set("Agents...", "agents");
-            if (!loaded.run.agents.length && ctx.mode === "tui" && transcripts.length) actions.set("View transcript", "view-transcript");
-            if (!loaded.run.agents.length && transcripts.length) actions.set("Transcript paths", "transcripts");
             if (terminalStates.has(loaded.run.state)) add("Delete", "delete");
             if (ctx.mode === "tui") {
               addCopy("Copy run path", store.directory, "run path");
               addCopy("Copy run ID", store.runId, "run ID");
             }
-            return { dashboard: formatNavigatorDashboard(loaded.run, checkpoints, worktrees), actions, copies, reviews, transcripts, script: loaded.snapshot.script, agents: loaded.run.agents, worktrees };
+            return { dashboard: formatNavigatorDashboard(loaded.run, checkpoints, worktrees), actions, copies, reviews, script: loaded.snapshot.script, agents: loaded.run.agents, worktrees, cwd: loaded.run.cwd };
           };
           const selectAgent = async (dashboard: Awaited<ReturnType<typeof loadDashboard>>): Promise<void> => {
             const byId = new Map(dashboard.agents.map((agent) => [agent.id, agent]));
@@ -3101,14 +3578,14 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             const attempts = [...(selected.attemptDetails ?? [])].sort((left, right) => left.attempt - right.attempt);
             const worktree = selected.worktreeOwner ? dashboard.worktrees.find((candidate) => candidate.owner === selected.worktreeOwner) : undefined;
             const actions = [
-              ...(attempts.length ? ["View transcript", "Copy transcript path"] : []),
+              ...(attempts.length && herdrPaneId() ? ["Fork as Pi session in pane"] : []),
               ...(worktree ? ["Copy branch", "Copy worktree path"] : []),
               "Copy agent ID",
               "Back",
             ];
             const chooseAttempt = async (): Promise<AgentAttemptSummary | undefined> => {
               const choices = attempts.map((attempt) => `Attempt ${String(attempt.attempt)}`);
-              const choice = choices.length === 1 ? choices[0] : await ctx.ui.select("Transcript attempts", [...choices, "Back"]);
+              const choice = choices.length === 1 ? choices[0] : await ctx.ui.select("Fork attempts", [...choices, "Back"]);
               const index = choice ? choices.indexOf(choice) : -1;
               return index >= 0 ? attempts[index] : undefined;
             };
@@ -3118,11 +3595,17 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
               if (action === "Copy agent ID") { await copyArtifact(selected.id, "agent ID"); continue; }
               if (action === "Copy branch" && worktree) { await copyArtifact(worktree.branch, "branch"); continue; }
               if (action === "Copy worktree path" && worktree) { await copyArtifact(worktree.path, "worktree path"); continue; }
-              if (action === "View transcript" || action === "Copy transcript path") {
+              if (action === "Fork as Pi session in pane") {
                 const attempt = await chooseAttempt();
                 if (!attempt) continue;
-                if (action === "Copy transcript path") await copyArtifact(attempt.sessionFile, "transcript path");
-                else await openTranscript(attempt.sessionFile);
+                const running = !SETTLED_AGENT_STATES.has(selected.state) && attempt.attempt === attempts.at(-1)?.attempt && !attempt.error;
+                if (running && !await ctx.ui.confirm("Fork running attempt?", "This attempt is still running. The snapshot may end mid-turn and will not receive later updates. It opens read-only to avoid concurrent changes to the workflow agent's working directory. Continue?")) continue;
+                try {
+                  await openHerdrPane({ action: "fork", cwd: worktree?.cwd ?? attempt.setup?.cwd ?? dashboard.cwd, original: attempt.sessionFile, ...(running ? { readOnly: true } : {}) });
+                  ctx.ui.notify("Forked Pi session in pane.", "info");
+                } catch (error) {
+                  ctx.ui.notify(`Cannot fork Pi session in pane: ${error instanceof Error ? error.message : String(error)}`, "warning");
+                }
               }
             }
           };
@@ -3137,19 +3620,18 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                   let disposed = false;
                   let stopRequested = false;
                   let stopStatus: string | undefined;
-                  const terminalRows = () => Math.max(1, ((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24);
+                  const terminalRows = () => Math.max(1, tuiRows(tui) - WORKFLOW_OVERLAY_BORDER_ROWS);
                   const keyLabels: Record<string, string> = { up: "↑", down: "↓", pageUp: "pgup", pageDown: "pgdn", escape: "esc" };
                   const keyLabel = (binding: string, fallback: string) => {
-                    const getKeys = (keybindings as unknown as { getKeys?: (name: string) => readonly string[] }).getKeys;
-                    const keys = getKeys?.call(keybindings, binding);
+                    const keys = keybindingKeys(keybindings, binding);
                     return keys?.length ? keys.map((key) => keyLabels[key] ?? key).join("/") : fallback;
                   };
                   const dashboardLayout = () => {
                     const rows = terminalRows();
                     const hintRows = rows >= 4 ? 1 : 0;
-                    const separatorRows = rows >= 6 ? 1 : 0;
+                    const separatorRows = rows >= 8 ? 1 : 0;
                     const available = Math.max(1, rows - hintRows - separatorRows);
-                    const actionViewport = Math.min(options.length, Math.max(1, Math.floor(available / 2)));
+                    const actionViewport = Math.min(options.length, Math.max(1, Math.ceil(available / 2)));
                     return { rows, hintRows, separatorRows, actionViewport, dashboardViewport: available - actionViewport };
                   };
                   const updateDashboard = async (selectedOption: string | undefined) => {
@@ -3186,7 +3668,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                     void updateDashboard(selectedOption).catch(() => undefined).finally(() => { refreshing = false; });
                   }, 1000);
                   timer.unref();
-                  return {
+                  return borderWorkflowOverlay({
                     render(width: number) {
                       const dashboard = stopStatus ? `${view.dashboard}\n\n${stopStatus}` : view.dashboard;
                       const dashboardLines = truncateToVisualLines(theme.fg("accent", dashboard), Number.MAX_SAFE_INTEGER, width, 1).visualLines;
@@ -3224,7 +3706,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                       tui.requestRender();
                     },
                     dispose() { disposed = true; clearInterval(timer); setWorkflowStatus(undefined); },
-                  };
+                  }, theme);
                 }, { overlay: true })
               : await ctx.ui.select(view.dashboard, [...view.actions.keys(), "Close"]);
             if (!actionChoice || actionChoice === "Close") return;
@@ -3235,12 +3717,12 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                 const highlighted = highlightCode(view.script, "javascript");
                 let offset = 0;
                 let renderedLines: string[] = [];
-                const viewport = () => Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24) - 3);
+                const viewport = () => Math.max(1, tuiRows(tui) - 3 - WORKFLOW_OVERLAY_BORDER_ROWS);
                 const move = (delta: number) => {
                   const maxOffset = Math.max(0, renderedLines.length - viewport());
                   offset = Math.max(0, Math.min(maxOffset, offset + delta));
                 };
-                return {
+                return borderWorkflowOverlay({
                   render(width: number) {
                     renderedLines = highlighted.flatMap((line) => line ? truncateToVisualLines(line, Number.MAX_SAFE_INTEGER, width, 0).visualLines : [""]);
                     const maxOffset = Math.max(0, renderedLines.length - viewport());
@@ -3261,21 +3743,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                     else if (keybindings.matches(data, "tui.select.cancel")) done(undefined);
                     tui.requestRender();
                   },
-                };
-              });
-              continue;
-            }
-            if (actionChoice === "View transcript") {
-              const transcript = await ctx.ui.select("Native Pi transcripts", [...view.transcripts, "Back"]);
-              if (transcript && transcript !== "Back") await openTranscript(transcript);
-              continue;
-            }
-            if (actionChoice === "Transcript paths") {
-              const transcript = await ctx.ui.select("Native Pi transcript paths", [...view.transcripts, "Back"]);
-              if (transcript && transcript !== "Back") {
-                if (ctx.mode === "tui") await copyArtifact(transcript, "transcript path");
-                else ctx.ui.notify(transcript, "info");
-              }
+                }, theme);
+              }, { overlay: true, overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%" } });
               continue;
             }
             const copy = view.copies.get(actionChoice);
@@ -3289,11 +3758,11 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                 let offset = 0;
                 let renderedLines: string[] = [];
                 const layout = () => {
-                  const rows = Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24));
+                  const rows = Math.max(1, tuiRows(tui) - WORKFLOW_OVERLAY_BORDER_ROWS);
                   const compactControls = rows < 4;
                   const titleRows = rows >= 5 ? 1 : 0;
                   const hintRows = rows >= 8 ? 1 : 0;
-                  const separatorRows = rows >= 8 ? 2 : 0;
+                  const separatorRows = rows >= 8 ? 1 : 0;
                   const controlRows = compactControls ? 1 : options.length;
                   const contentViewport = Math.max(0, rows - titleRows - hintRows - separatorRows - controlRows);
                   return { rows, compactControls, titleRows, hintRows, separatorRows, contentViewport };
@@ -3302,7 +3771,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                   const maxOffset = Math.max(0, renderedLines.length - layout().contentViewport);
                   offset = Math.max(0, Math.min(maxOffset, offset + delta));
                 };
-                return {
+                return borderWorkflowOverlay({
                   render(width: number) {
                     renderedLines = truncateToVisualLines(formatCheckpointReview(checkpoint), Number.MAX_SAFE_INTEGER, width, 0).visualLines;
                     const currentLayout = layout();
@@ -3317,7 +3786,6 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                       ...renderedLines.slice(offset, offset + currentLayout.contentViewport),
                       ...(currentLayout.separatorRows ? [""] : []),
                       ...controls,
-                      ...(currentLayout.separatorRows ? [""] : []),
                       ...(currentLayout.hintRows ? [hint] : []),
                     ];
                   },
@@ -3331,8 +3799,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                     else if (keybindings.matches(data, "tui.select.cancel")) done(undefined);
                     tui.requestRender();
                   },
-                };
-              });
+                }, theme);
+              }, { overlay: true, overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%" } });
               if (decision) {
                 const accepted = await answerCheckpoint(store.runId, checkpoint.name, decision === "Approve", true);
                 if (!accepted) ctx.ui.notify("Checkpoint is not awaiting a response.", "warning");
@@ -3385,6 +3853,6 @@ function modelSpec(value: string, fallback: ModelSpec): ModelSpec {
 export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
 export type { AwaitingCheckpoint, CompletedOperation, ConversationHead, NativeSessionReference, PendingWorkflowDecision, PersistedConversation, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
-export type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentSetup, AgentSetupContext, AgentSetupHook, AgentToolCallProgress, RegisteredAgentSetupHook, SessionInput } from "./agent-execution.js";
+export type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentProviderFailure, AgentProviderRecovery, AgentSetup, AgentSetupContext, AgentSetupHook, AgentToolCallProgress, RegisteredAgentSetupHook, SessionInput } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
-export type { DoctorDiagnostic, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust, DoctorWorkflow } from "./doctor.js";
+export type { DoctorDiagnostic, DoctorFunction, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust } from "./doctor.js";