pi-extensible-workflows 1.0.1 → 2.0.0

package/dist/src/index.js

@@ -1,21 +1,22 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { fork } from "node:child_process";
+import { fork, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 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 } from "@earendil-works/pi-coding-agent";
+import { copyToClipboard, getAgentDir, parseFrontmatter, highlightCode, truncateToVisualLines } from "@earendil-works/pi-coding-agent";
 import { createNativeAgentSession, FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
-import { transcriptLines } from "./session-inspector.js";
+import { herdrPaneId, openHerdrPane } from "./herdr.js";
 import { acquireSessionLease, atomicWriteFile, listRunIds, RunStore, structuralPath as operationPath } from "./persistence.js";
 export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
 export const AGENT_STATES = ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
-export const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"];
+export const WORKFLOW_CALL_KINDS = ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"];
 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";
@@ -29,10 +30,10 @@ export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 const SETTLED_AGENT_STATES = 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",
 ];
-export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 4;
 export class WorkflowError extends Error {
     code;
     constructor(code, message) {
@@ -41,6 +42,7 @@ export class WorkflowError extends Error {
         this.name = "WorkflowError";
     }
 }
+const WORKFLOW_FAILURE_DIAGNOSTICS = Symbol("workflowFailureDiagnostics");
 const WORKFLOW_AUTHORED_ERROR = Symbol("workflowAuthoredError");
 function errorText(error) { return error && typeof error === "object" && typeof error.message === "string" ? error.message : error instanceof Error ? error.message : String(error); }
 function errorCode(error) {
@@ -70,12 +72,13 @@ const WORKFLOW_ERROR_PROSE = {
     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}.`,
@@ -778,6 +781,7 @@ function hasIdentifier(node, 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, call) {
     let previous;
     let current;
@@ -798,12 +802,14 @@ function instrumentWorkflow(script) {
         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);
@@ -942,6 +948,23 @@ function validateAgentOptions(value) {
         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) {
+    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 }) };
+}
+function validateShellCommand(value) {
+    if (typeof value !== "string")
+        fail("INVALID_METADATA", "shell command must be a string");
+    return value;
+}
 function staticValue(node) {
     if (!node)
         return { known: false };
@@ -1007,6 +1030,8 @@ export function inspectWorkflowScript(script) {
         }
         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 };
     });
 }
@@ -1022,6 +1047,18 @@ function validateStaticAgentOptions(node, aliases = {}, knownModels, settingsPat
             validateAgentOption(key, value.value, aliases, knownModels, settingsPath);
     }
 }
+function validateStaticShellOptions(call) {
+    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) {
     if (call.arguments.some((argument) => argument.type === "SpreadElement"))
         return;
@@ -1036,13 +1073,12 @@ function validateStaticWithWorktree(call) {
             fail("INVALID_METADATA", "withWorktree name must be a non-empty 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"]);
+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 {
     #extensions = new Set();
     #globals = new Map();
-    #workflows = new Map();
     #hooks = new Map();
     #frozen = false;
     get frozen() { return this.#frozen; }
@@ -1050,14 +1086,15 @@ export class WorkflowRegistry {
     register(extension) {
         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())
+        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");
@@ -1082,50 +1119,38 @@ export class WorkflowRegistry {
                 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) {
+    function(name) {
         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;
+            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() {
-        return Object.freeze(Object.fromEntries(this.#workflows));
+    functions() {
+        return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.entries(extension.functions ?? {}))));
     }
     catalog() {
         const functions = [];
         const variables = [];
-        const workflows = [];
         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;
         try {
@@ -1135,15 +1160,28 @@ export class WorkflowRegistry {
             aliases = undefined;
         }
         const sort = (left, right) => 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() {
+        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) {
+        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() {
         return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.keys(extension.functions ?? {}).map((name) => [name, { name }]))));
     }
     async invokeFunction(name, input, context, path, journal) {
-        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);
@@ -1152,7 +1190,7 @@ export class WorkflowRegistry {
                 fail("RESULT_INVALID", `Invalid replay for ${name}`);
             return structuredClone(replayed);
         }
-        const result = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, invoke: context.invoke, 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 = 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);
@@ -1173,9 +1211,11 @@ function createWorkflowRegistryApi(registry) {
         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(),
@@ -1196,25 +1236,28 @@ function loadingRegistry() { return workflowRegistryHost().api; }
 beginWorkflowExtensionLoading();
 export function registerWorkflowExtension(extension) { loadingRegistry().register(extension); }
 export function workflowCatalog() { return loadingRegistry().catalog(); }
-export function registeredWorkflowDefinitions() { return loadingRegistry().workflows(); }
+export function workflowCatalogIndex() { return loadingRegistry().catalogIndex(); }
+export function workflowCatalogDetail(name) { return loadingRegistry().catalogDetail(name); }
+export function registeredWorkflowFunctions() { return loadingRegistry().functions(); }
 export function formatWorkflowPreview(args) {
     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" : ""}`;
+        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) {
     if (!node)
@@ -1240,8 +1283,11 @@ export function preflight(script, capabilities, schemas = [], metadata = { 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);
@@ -1255,6 +1301,8 @@ export function preflight(script, capabilities, schemas = [], metadata = { name:
         }
         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)
@@ -1291,6 +1339,7 @@ export function preflight(script, capabilities, schemas = [], metadata = { name:
         fail("UNKNOWN_AGENT_TYPE", `Unknown agent type: ${missingType}`);
     return Object.freeze({ metadata: deepFreeze(checkedMetadata), referenced: deepFreeze({ phases, models, tools, agentTypes }), schemas: deepFreeze(checkedSchemas), dynamicAgentRoles });
 }
+function functionLaunchScript(name) { return `return await ${name}(args);`; }
 export function validateWorkflowLaunch(params, context) {
     return validateWorkflowLaunchWithRegistry(params, context, loadingRegistry());
 }
@@ -1299,15 +1348,19 @@ function validateWorkflowLaunchWithRegistry(params, context, registry) {
         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 ?? "";
+    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 workflow");
-    const workflowName = typeof params.name === "string" && params.name.trim() ? params.name.trim() : typeof params.workflow === "string" ? params.workflow : "";
+        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 ?? {};
@@ -1315,7 +1368,7 @@ function validateWorkflowLaunchWithRegistry(params, context, registry) {
     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(value) {
     if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
@@ -1326,11 +1379,29 @@ function deepFreeze(value) {
     return value;
 }
 export function createLaunchSnapshot(input) {
-    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) {
     return deepFreeze(structuredClone(input));
 }
+function launchScriptForSnapshot(snapshot, registry) {
+    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;
 const OUTCOME_ERRORS = new Set(["AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID"]);
@@ -1396,10 +1467,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();
@@ -1418,7 +1491,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();
@@ -1477,6 +1552,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 => {
@@ -1598,13 +1698,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));
@@ -1617,6 +1717,9 @@ function encoded(value) {
         fail("RPC_LIMIT_EXCEEDED", "RPC value exceeds the 10 MB JSON boundary");
     return json;
 }
+function encodedRpcResult(id, value) {
+    return encoded({ type: "rpcResult", id, ok: true, value });
+}
 function readAgentIdentity(value) {
     if (!object(value))
         fail("INTERNAL_ERROR", "Invalid workflow agent identity");
@@ -1631,9 +1734,18 @@ function readAgentIdentity(value) {
         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) {
+    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) {
     return operationPath("agent", ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
 }
+function shellIdentityPath(identity) {
+    return operationPath("shell", ...(identity.worktreeOwner ? ["worktree", identity.worktreeOwner] : []), ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
+}
 function conversationIdentityPath(identity) {
     if (!identity.conversation)
         throw new WorkflowError("INTERNAL_ERROR", "Missing conversation identity");
@@ -1644,9 +1756,122 @@ function conversationTurnPath(identity) {
         throw new WorkflowError("INTERNAL_ERROR", "Missing conversation identity");
     return operationPath(conversationIdentityPath(identity), `turn:${String(identity.conversation.turn)}`);
 }
+function readShellResult(value) {
+    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, stdout: value.stdout, stderr: value.stderr };
+}
 function agentWorktree(identity) {
     return identity.worktreeOwner ? { worktreeOwner: identity.worktreeOwner } : {};
 }
+function shellProcessKill(child) {
+    let forceKill;
+    const killProcessTree = (signal) => {
+        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, options, signal, cwd = process.cwd()) {
+    return new Promise((resolve, reject) => {
+        let child;
+        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;
+        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) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            shellProcessKill(child);
+            reject(error);
+        };
+        const onAbort = () => { failShell(new WorkflowError("CANCELLED", "Workflow cancelled")); };
+        const capture = (target, chunk) => {
+            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) => { capture("stdout", chunk); });
+        child.stderr?.on("data", (chunk) => { 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, args = null, bridge = {}, signal) {
     encoded(args);
     const config = JSON.stringify({ script: instrumentWorkflow(script), args: structuredClone(args), functions: bridge.functions ?? {}, variables: bridge.variables ?? {} });
@@ -1750,6 +1975,14 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
                     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));
+            }
             else if (method === "checkpoint") {
                 if (!bridge.checkpoint || !object(values[0]))
                     fail("INTERNAL_ERROR", "checkpoint requires an available bridge and object input");
@@ -1786,6 +2019,11 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
                     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");
@@ -1799,7 +2037,7 @@ export function runWorkflow(script, args = null, bridge = {}, signal) {
             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);
@@ -1999,13 +2237,9 @@ export function formatNavigatorDashboard(run, checkpoints, worktrees) {
     const render = ({ agent, depth }, grouped) => {
         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)
@@ -2069,7 +2303,8 @@ export function formatNavigatorRun(loaded, checkpoints, _worktrees) {
     return lines.join("\n");
 }
 function formatCheckpointReview(checkpoint) {
-    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;
 const WORKFLOW_LOG_ENTRY = "workflow-log";
@@ -2091,11 +2326,144 @@ function utf8Prefix(value, maxBytes) {
         end -= 1;
     return bytes.subarray(0, end).toString("utf8");
 }
+const DIAGNOSTIC_LIMIT_BYTES = DELIVERY_LIMIT_BYTES - 512;
+function failureDiagnosticsFrom(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    return error[WORKFLOW_FAILURE_DIAGNOSTICS];
+}
+function boundedWorkflowFailureDiagnostics(value) {
+    let bounded = {
+        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, metadata, error, run) {
+    const rawFailedAt = error && typeof error === "object" ? error.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 } : {}),
+    } : 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 ?? [])],
+    }));
+    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) {
+    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) { return JSON.stringify(diagnostic); }
+function isWorkflowFailureDiagnostics(value) {
+    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, content) {
     pi.sendMessage({ customType: "workflow", content, display: true }, { deliverAs: "followUp", triggerTurn: true });
 }
-function deliverFailure(pi, name, error) {
-    deliver(pi, `Workflow ${name} failed: ${formatWorkflowFailure(error)}`);
+function deliverFailure(pi, diagnostic) {
+    deliver(pi, `Workflow ${utf8Prefix(diagnostic.workflowName, 128)} failure diagnostics: ${serializeWorkflowFailureDiagnostics(diagnostic)}`);
 }
 function safeEventError(error) {
     const code = errorCode(error) ?? "INTERNAL_ERROR";
@@ -2109,6 +2477,11 @@ class WorkflowEventPublisher {
     constructor(sink) {
         this.sink = sink;
     }
+    removeRun(runId) {
+        this.#queues.delete(runId);
+        this.#budgetEvents.delete(runId);
+        this.#worktrees.delete(runId);
+    }
     seedBudget(runId, events) {
         const seen = this.#budgetEvents.get(runId) ?? new Set();
         for (const event of events ?? [])
@@ -2183,7 +2556,12 @@ function namedRecord(value, kind) {
         fail("INVALID_METADATA", `${kind} must be a record`);
     return Object.entries(value);
 }
-function hostWithWorktree(args, identity, occurrences) {
+function publicWorktreeReference(reference) {
+    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, identity, occurrences, resolveWorktree, signal) {
     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];
@@ -2202,7 +2580,10 @@ function hostWithWorktree(args, identity, occurrences) {
         occurrences.set(key, occurrence);
         owner = operationPath("worktree", "unnamed", "function", identity, ...structuralPath, `occurrence:${String(occurrence)}`);
     }
-    return inheritedHostWorktreeOwner.run(owner, async () => await callback());
+    if (!resolveWorktree)
+        fail("WORKTREE_FAILED", "No worktree bridge is available");
+    const reference = publicWorktreeReference(await resolveWorktree(owner, signal));
+    return inheritedHostWorktreeOwner.run(owner, async () => await callback(reference));
 }
 function workflowRunContext(cwd, sessionId, runId, workflow, args, signal) {
     return Object.freeze({ cwd, sessionId, runId, workflow: deepFreeze(structuredClone(workflow)), args: deepFreeze(structuredClone(args)), signal });
@@ -2301,6 +2682,7 @@ function nextNamedOccurrence(counters, label) {
 }
 function withWorkflowFunctions(bridge, store, runContext, variables, registry) {
     const functionAgentOccurrences = new Map();
+    const functionShellOccurrences = new Map();
     const functionWorktreeOccurrences = new Map();
     const functionInvokeOccurrences = new Map();
     const invokeFunction = async (name, input, path, signal, worktreeOwner, structuralPath = [], breadcrumb) => {
@@ -2330,10 +2712,23 @@ function withWorkflowFunctions(bridge, store, runContext, variables, registry) {
                 functionAgentOccurrences.set(key, occurrence);
                 return bridge.agent(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb: functionBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
             },
+            shell: async (...args) => {
+                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) => hostParallel(args[0], args[1]),
             pipeline: (...args) => hostPipeline(args[0], args[1], args[2]),
-            withWorktree: (...args) => hostWithWorktree(args, path, functionWorktreeOccurrences),
+            withWorktree: (...args) => hostWithWorktree(args, path, functionWorktreeOccurrences, bridge.worktree, signal),
             checkpoint: async (...args) => {
                 if (!bridge.checkpoint || !object(args[0]) || !jsonValue(args[0]))
                     fail("INTERNAL_ERROR", "No checkpoint bridge is available");
@@ -2389,6 +2784,16 @@ function tuiHostCapabilities(tui) {
     return { terminal: { ...(tui.terminal.rows === undefined ? {} : { rows: tui.terminal.rows }) } };
 }
 function tuiRows(tui) { const rows = tuiHostCapabilities(tui).terminal?.rows; return typeof rows === "number" && Number.isFinite(rows) ? rows : 24; }
+const WORKFLOW_OVERLAY_BORDER_ROWS = 2;
+function borderWorkflowOverlay(component, theme) {
+    return {
+        ...component,
+        render(width) {
+            const border = theme.fg("border", "─".repeat(Math.max(1, width)));
+            return [border, ...component.render(width), border];
+        },
+    };
+}
 function isKeybindingGetter(value) { return typeof value === "function"; }
 function keybindingsHostCapabilities(keybindings) {
     if (!object(keybindings) || !isKeybindingGetter(keybindings.getKeys))
@@ -2408,9 +2813,10 @@ function parseThinking(value) {
         default: return undefined;
     }
 }
-export default function workflowExtension(pi, home, clipboard = copyToClipboard, createSession = createNativeAgentSession) {
+export default function workflowExtension(pi, home, clipboard = copyToClipboard, createSession = createNativeAgentSession, agentDir) {
     beginWorkflowExtensionLoading();
     const registry = loadingRegistry();
+    const extensionAgentDir = agentDir ?? getAgentDir();
     const registerEntryRenderer = piHostCapabilities(pi).registerEntryRenderer;
     registerEntryRenderer?.(WORKFLOW_LOG_ENTRY, (entry) => {
         const data = entry.data;
@@ -2434,6 +2840,41 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         return skillPath ? { skillPaths: [skillPath] } : undefined;
     });
     const runs = new Map();
+    let providerRecoveryQueue = Promise.resolve();
+    const enqueueProviderRecovery = (task) => { const next = providerRecoveryQueue.then(task, task); providerRecoveryQueue = next.then(() => undefined, () => undefined); return next; };
+    const createProviderErrorRecovery = (host, fallbackModels, abort) => {
+        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, options) => select.call(ui, title, options);
+        return (failure) => 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();
+    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", text: serializeWorkflowFailureDiagnostics(diagnostic) }], details: diagnostic, isError: true };
+    });
     const liveActivities = new Map();
     const setLiveActivity = (runId, agentId, activity) => {
         const activities = liveActivities.get(runId);
@@ -2486,10 +2927,39 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
     const persistWorktree = async (store, metadata, owner) => {
         const existing = (await store.worktrees()).some((worktree) => worktree.owner === owner);
         const worktree = await store.worktree(owner);
-        if (!existing)
+        if (!existing && await store.ownsWorktree(owner))
             await eventPublisher.worktree(store, metadata, worktree);
         return worktree;
     };
+    const resolveWorktree = async (store, metadata, owner) => {
+        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, metadata, lifecycle, command, options, signal, identity) => {
+        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);
+            return result;
+        }
+        finally {
+            await lifecycle.leave();
+        }
+    };
     const lifecycleFor = (store, state, budget, metadata) => new RunLifecycle(state, async (next, previous, reason) => {
         if (next !== "pausing")
             budget.transition(next);
@@ -2535,7 +3005,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
                 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;
@@ -2584,6 +3054,21 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         await eventPublisher.agentStates(run.store, run.metadata, previousAgents, runState.agents);
         run.update?.(workflowToolUpdate(withLiveActivities(runState)));
     });
+    const cleanupTerminalRun = async (runId) => {
+        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);
+        run.checkpointResolvers.clear();
+        liveActivities.delete(runId);
+        eventPublisher.removeRun(runId);
+        runs.delete(runId);
+    };
     const stopWorkflowRun = async (runId) => {
         const run = runs.get(runId);
         const terminalState = terminalRunStates.get(runId);
@@ -2597,6 +3082,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         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, name, approved, silent = false) => {
@@ -2629,18 +3115,18 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
             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, store, metadata, foreground, ui) => {
+    const checkpointBridge = (runId, store, metadata, foreground, ui, headless = false) => {
         const checkpointCounters = new Map();
         return async (raw, signal) => {
             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);
@@ -2731,14 +3217,17 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
             return;
         const catalog = registry.catalog();
         const hasAliases = Object.keys(catalog.modelAliases ?? {}).length > 0;
-        if (!catalog.functions.length && !catalog.variables.length && !catalog.workflows.length && !hasAliases)
+        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", 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", text: JSON.stringify(result) }], details: result };
+            }
         });
         catalogRegistered = true;
     };
@@ -2748,7 +3237,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         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 ?? {};
@@ -2762,7 +3251,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         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)
@@ -2770,6 +3259,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
     };
     const coldResumeRun = async (run, hasUI, ui, trustedProject, context) => {
         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)
@@ -2783,7 +3273,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         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 ?? {};
@@ -2796,10 +3286,11 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         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("; ")}` });
@@ -2819,11 +3310,12 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 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}` : "";
@@ -2870,7 +3362,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                         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 {
+            }, 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;
                 const persisted = await persistRunState(run.store, run.metadata, (current) => { previousPhase = current.phase; return { ...current, phase }; });
                 await eventPublisher.phase(run.store, run.metadata, previousPhase, phase);
@@ -2898,8 +3390,9 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
             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);
-        });
+                deliverFailure(pi, createWorkflowFailureDiagnostics(run.store, run.metadata, typed, persisted));
+        }).finally(() => cleanupTerminalRun(run.store.runId));
+        run.completion = completion;
         void completion;
     };
     const applyBudgetDecision = async (request, approved) => {
@@ -2935,18 +3428,10 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         if (budgetRelaxed(currentBudget, nextBudget)) {
             const proposalId = randomUUID();
             const request = { kind: "budget", proposalId, runId, consumed: usage, previous: currentBudget ?? {}, proposed: nextBudget ?? {}, budgetVersion: loaded.run.budgetVersion ?? 1 };
-            const decision = new Promise((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) {
@@ -3015,7 +3500,9 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 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())
@@ -3052,7 +3539,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
     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")}`;
@@ -3064,9 +3551,10 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         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");
@@ -3082,8 +3570,8 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 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);
@@ -3096,24 +3584,28 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 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]]));
                 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", 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}` : "";
@@ -3163,7 +3655,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 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;
@@ -3190,21 +3682,32 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                     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, 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).completion = finish;
+                const completion = finish.finally(() => cleanupTerminalRun(runId));
+                runs.get(runId).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) => { deliverFailure(pi, checked.metadata.name, error); });
+                    }, (error) => {
+                        const diagnostic = failureDiagnosticsFrom(error);
+                        if (diagnostic)
+                            deliverFailure(pi, diagnostic);
+                        else
+                            deliver(pi, `Workflow ${checked.metadata.name} failed: ${formatWorkflowFailure(error)}`);
+                    });
                     return { content: [{ type: "text", 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", text: JSON.stringify(value) }], details: { runId, value, run } };
+                return { content: [{ type: "text", text: JSON.stringify(value) }, { type: "text", text: `Workflow run ID: ${runId}` }], details: { runId, value, run } };
             }
             catch (error) {
                 throw mainAgentError(error);
@@ -3215,19 +3718,22 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         },
         renderResult(result, { isPartial }, _theme, context) {
             const details = result.details;
+            if (isWorkflowFailureDiagnostics(details))
+                return textBlock(formatWorkflowFailureDiagnostics(details));
+            const runDetails = details;
             const state = context.state;
-            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", {
@@ -3351,7 +3857,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 }
             };
             const manageAliases = async () => {
-                const settingsPath = workflowSettingsPath();
+                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 () => {
@@ -3469,10 +3975,20 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                     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();
@@ -3508,49 +4024,6 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                             ctx.ui.notify(`Failed to copy ${artifact}: ${error instanceof Error ? error.message : String(error)}`, "error");
                         }
                     };
-                    const openTranscript = async (transcript) => {
-                        try {
-                            const entries = SessionManager.open(transcript).buildContextEntries();
-                            if (ctx.mode !== "tui") {
-                                ctx.ui.notify(`Transcript: ${transcript}`, "info");
-                                return;
-                            }
-                            await ctx.ui.custom((tui, theme, keybindings, done) => {
-                                let offset = 0;
-                                let renderedLines = [];
-                                const viewport = () => Math.max(1, tuiRows(tui) - 3);
-                                const move = (delta) => { offset = Math.max(0, Math.min(Math.max(0, renderedLines.length - viewport()), offset + delta)); };
-                                return {
-                                    render(width) {
-                                        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) {
-                                        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();
@@ -3590,20 +4063,15 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                             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) => {
                         const byId = new Map(dashboard.agents.map((agent) => [agent.id, agent]));
@@ -3626,14 +4094,14 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                         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 () => {
                             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;
                         };
@@ -3653,14 +4121,20 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 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");
+                                }
                             }
                         }
                     };
@@ -3675,7 +4149,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 let disposed = false;
                                 let stopRequested = false;
                                 let stopStatus;
-                                const terminalRows = () => Math.max(1, tuiRows(tui));
+                                const terminalRows = () => Math.max(1, tuiRows(tui) - WORKFLOW_OVERLAY_BORDER_ROWS);
                                 const keyLabels = { up: "↑", down: "↓", pageUp: "pgup", pageDown: "pgdn", escape: "esc" };
                                 const keyLabel = (binding, fallback) => {
                                     const keys = keybindingKeys(keybindings, binding);
@@ -3684,9 +4158,9 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 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) => {
@@ -3729,7 +4203,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                     void updateDashboard(selectedOption).catch(() => undefined).finally(() => { refreshing = false; });
                                 }, 1000);
                                 timer.unref();
-                                return {
+                                return borderWorkflowOverlay({
                                     render(width) {
                                         const dashboard = stopStatus ? `${view.dashboard}\n\n${stopStatus}` : view.dashboard;
                                         const dashboardLines = truncateToVisualLines(theme.fg("accent", dashboard), Number.MAX_SAFE_INTEGER, width, 1).visualLines;
@@ -3776,7 +4250,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                         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")
@@ -3792,12 +4266,12 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 const highlighted = highlightCode(view.script, "javascript");
                                 let offset = 0;
                                 let renderedLines = [];
-                                const viewport = () => Math.max(1, tuiRows(tui) - 3);
+                                const viewport = () => Math.max(1, tuiRows(tui) - 3 - WORKFLOW_OVERLAY_BORDER_ROWS);
                                 const move = (delta) => {
                                     const maxOffset = Math.max(0, renderedLines.length - viewport());
                                     offset = Math.max(0, Math.min(maxOffset, offset + delta));
                                 };
-                                return {
+                                return borderWorkflowOverlay({
                                     render(width) {
                                         renderedLines = highlighted.flatMap((line) => line ? truncateToVisualLines(line, Number.MAX_SAFE_INTEGER, width, 0).visualLines : [""]);
                                         const maxOffset = Math.max(0, renderedLines.length - viewport());
@@ -3823,24 +4297,8 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                             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);
@@ -3858,11 +4316,11 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 let offset = 0;
                                 let renderedLines = [];
                                 const layout = () => {
-                                    const rows = Math.max(1, tuiRows(tui));
+                                    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 };
@@ -3871,7 +4329,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                     const maxOffset = Math.max(0, renderedLines.length - layout().contentViewport);
                                     offset = Math.max(0, Math.min(maxOffset, offset + delta));
                                 };
-                                return {
+                                return borderWorkflowOverlay({
                                     render(width) {
                                         renderedLines = truncateToVisualLines(formatCheckpointReview(checkpoint), Number.MAX_SAFE_INTEGER, width, 0).visualLines;
                                         const currentLayout = layout();
@@ -3886,7 +4344,6 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                             ...renderedLines.slice(offset, offset + currentLayout.contentViewport),
                                             ...(currentLayout.separatorRows ? [""] : []),
                                             ...controls,
-                                            ...(currentLayout.separatorRows ? [""] : []),
                                             ...(currentLayout.hintRows ? [hint] : []),
                                         ];
                                     },
@@ -3906,8 +4363,8 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                             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)