@marcoscale98/pi-extensible-workflows 5.19.1-fork.1 → 6.2.1-fork.1

package/dist/src/host-runtime.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { deepFreeze, errorCode, errorText, fail, isWorkflowErrorCode, jsonValue, object } from "./utils.js";
+import { FUNCTION_HANDLE_PREFIX } from "./execution.js";
+import { deepFreeze, errorCode, errorText, fail, isWorkflowErrorCode, jsonDigest, jsonValue, object } from "./utils.js";
 import { validateAgentOptions, validateShellOptions, workflowPrompt } from "./validation.js";
 import { HARD_TERMINAL_RUN_STATES, WORKFLOW_AGENT_STATE_CHANGED_EVENT, WORKFLOW_BUDGET_EVENT, WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT, WORKFLOW_PHASE_CHANGED_EVENT, WORKFLOW_RUN_COMPLETED_EVENT, WORKFLOW_RUN_FAILED_EVENT, WORKFLOW_RUN_RESUMED_EVENT, WORKFLOW_RUN_STARTED_EVENT, WORKFLOW_RUN_STATE_CHANGED_EVENT, WORKFLOW_WORKTREE_CREATED_EVENT, WorkflowError } from "./types.js";
 import { structuralPath as operationPath } from "./persistence.js";
@@ -130,7 +131,7 @@ export class WorkflowEventPublisher {
             await this.#publish(store, metadata, WORKFLOW_RUN_FAILED_EVENT, { error: safeEventError(error) });
     }
     async agentState(store, metadata, previous, agent) {
-        await this.#publish(store, metadata, WORKFLOW_AGENT_STATE_CHANGED_EVENT, { agentId: agent.id, displayLabel: agent.label ?? agent.name, ...(agent.role ? { role: agent.role } : {}), structuralPath: [...(agent.structuralPath ?? [])], ...(agent.parentId ? { parentId: agent.parentId } : {}), ...(agent.parentBreadcrumb ? { parentBreadcrumb: agent.parentBreadcrumb } : {}), ...(agent.worktreeOwner ? { worktreeOwner: agent.worktreeOwner } : {}), ...(previous ? { previousState: previous.state } : {}), state: agent.state, attempt: agent.attempts });
+        await this.#publish(store, metadata, WORKFLOW_AGENT_STATE_CHANGED_EVENT, { agentId: agent.id, displayLabel: agent.label ?? agent.name, structuralPath: [...(agent.structuralPath ?? [])], ...(agent.parentId ? { parentId: agent.parentId } : {}), ...(agent.parentBreadcrumb ? { parentBreadcrumb: agent.parentBreadcrumb } : {}), ...(agent.worktreeOwner ? { worktreeOwner: agent.worktreeOwner } : {}), ...(previous ? { previousState: previous.state } : {}), state: agent.state, attempt: agent.attempts });
     }
     async agentStates(store, metadata, previous, current) {
         const previousById = new Map(previous.map((agent) => [agent.id, agent]));
@@ -285,6 +286,7 @@ export function nextNamedOccurrence(counters, label) {
 function functionBreadcrumb(name, occurrence) { return occurrence === 1 ? name : `${name} #${String(occurrence)}`; }
 export function withWorkflowFunctions(bridge, store, runContext, registry, settings = Object.freeze({})) {
     const functionAgentOccurrences = new Map();
+    const functionHandles = new Set();
     const functionShellOccurrences = new Map();
     const functionInvokeOccurrences = new Map();
     const functionInvokeBreadcrumbOccurrences = new Map();
@@ -307,6 +309,7 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
             // Own rejection immediately; Promise.all below still propagates it after the function completes.
             void sideEffect.catch(() => undefined);
         };
+        let closed = false;
         const parentBreadcrumb = breadcrumb ?? functionBreadcrumb(name, identity.occurrence);
         const context = {
             settings: deepFreeze(structuredClone(settings)),
@@ -327,7 +330,7 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
                 const nestedIdentity = { path: nestedPath, structuralPath: [...inherited], occurrence, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) };
                 return invokeFunction(targetName, targetInput, signal, nestedIdentity, `${parentBreadcrumb} > ${functionBreadcrumb(breadcrumbName, breadcrumbOccurrence)}`);
             },
-            agent: async (prompt, options) => {
+            agent: Object.assign(async (prompt, options) => {
                 if (!bridge.agent || typeof prompt !== "string")
                     fail("AGENT_FAILED", "No agent bridge is available");
                 const validatedOptions = validateAgentOptions(options === undefined ? {} : options);
@@ -337,7 +340,55 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
                 const occurrence = (functionAgentOccurrences.get(key) ?? 0) + 1;
                 functionAgentOccurrences.set(key, occurrence);
                 return bridge.agent(prompt, validatedOptions, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
-            },
+            }, {
+                create: (...created) => {
+                    if (created.length !== 1 || !object(created[0]))
+                        fail("INVALID_METADATA", "agent.create requires one options object");
+                    const { name, ...rest } = created[0];
+                    if (typeof name !== "string" || !name.trim())
+                        fail("INVALID_METADATA", "agent.create requires a stable explicit name");
+                    const config = deepFreeze(structuredClone(validateAgentOptions(rest)));
+                    const scopedStructuralPath = [...(inheritedHostAgentPath.getStore() ?? [])];
+                    const scopedWorktreeOwner = inheritedHostWorktreeOwner.getStore() ?? worktreeOwner;
+                    const scope = JSON.stringify([scopedStructuralPath, scopedWorktreeOwner ?? null]);
+                    // The registered-function path makes repeated and nested invocations distinct; scope separates branches and worktrees. The digest bounds the journal and turn-copy file names.
+                    const handle = operationPath(FUNCTION_HANDLE_PREFIX, jsonDigest([path, scopedStructuralPath, scopedWorktreeOwner ?? null]), name);
+                    if (functionHandles.has(handle))
+                        fail("INVALID_METADATA", `Duplicate agent handle name: ${name}`);
+                    functionHandles.add(handle);
+                    let turn = 0;
+                    let inflight = false;
+                    // Not a nested promise chain: the caller owns the one returned promise, and inflight clears in finally on every outcome.
+                    const send = async (...sent) => {
+                        if (!bridge.agent)
+                            fail("AGENT_FAILED", "No agent bridge is available");
+                        if (sent.length < 1 || sent.length > 2)
+                            fail("INVALID_METADATA", "send requires a prompt and optional options");
+                        if (closed)
+                            fail("INVALID_METADATA", `Agent handle outlived the function invocation that created it: ${name}`);
+                        if (typeof sent[0] !== "string")
+                            fail("INVALID_METADATA", "send prompt must be a string");
+                        const sendOptions = sent[1] === undefined ? {} : sent[1];
+                        if (!object(sendOptions) || Object.keys(sendOptions).some((key) => key !== "outputSchema" && key !== "timeoutMs"))
+                            fail("INVALID_METADATA", "send options must contain only outputSchema and timeoutMs");
+                        const sendStructuralPath = [...(inheritedHostAgentPath.getStore() ?? [])];
+                        if (JSON.stringify([sendStructuralPath, inheritedHostWorktreeOwner.getStore() ?? worktreeOwner ?? null]) !== scope)
+                            fail("INVALID_METADATA", `Agent handle sends must run in the scope that created the handle: ${name}`);
+                        if (inflight)
+                            fail("INVALID_METADATA", "Concurrent send(...) calls on one agent handle are unsupported; await each turn");
+                        const validatedOptions = validateAgentOptions({ ...config, ...sendOptions });
+                        inflight = true;
+                        turn += 1;
+                        try {
+                            return await bridge.agent(sent[0], validatedOptions, signal, { structuralPath: sendStructuralPath, callSite: `function:${path}:handle:${name}`, occurrence: turn, handle, turn, parentBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
+                        }
+                        finally {
+                            inflight = false;
+                        }
+                    };
+                    return Object.freeze({ name, send });
+                },
+            }),
             shell: async (...args) => {
                 if (!bridge.shell)
                     fail("SHELL_FAILED", "No shell bridge is available");
@@ -363,7 +414,7 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
             phase: (name) => { ownSideEffect(() => bridge.phase?.(name)); },
             log: (message) => { ownSideEffect(() => bridge.log?.(message)); },
         };
-        const result = await inheritedHostAgentPath.run([...structuralPath], async () => registry.invokeFunction(name, input, context, path, { get: () => replayed?.value, put: (_path, value) => { stored = value; } }));
+        const result = await inheritedHostAgentPath.run([...structuralPath], async () => registry.invokeFunction(name, input, context, path, { get: () => replayed?.value, put: (_path, value) => { stored = value; } })).finally(() => { closed = true; });
         await Promise.all(sideEffects);
         if (!replayed)
             await store.complete(path, stored ?? result);

package/dist/src/host-view.d.ts

@@ -95,7 +95,6 @@ export interface AgentDetailPresentation {
     readonly lastEventAt?: number;
     readonly structuralPath?: readonly string[];
     readonly model?: AgentRecord["model"];
-    readonly role?: string;
     readonly tools?: readonly string[];
     readonly attempts?: number;
     readonly startedAt?: number;
@@ -132,5 +131,6 @@ export declare function formatWorkflowPhaseDashboard(run: PersistedRun, snapshot
 export declare function formatNavigatorColumns(sidebar: readonly string[], detail: readonly string[], width: number, layout?: Readonly<{
     treeOnly?: boolean | undefined;
     detailsOnly?: boolean | undefined;
+    detailOffset?: number | undefined;
 }>): string[];
 export declare function formatCheckpointReview(checkpoint: AwaitingCheckpoint): string;

package/dist/src/host-view.js

@@ -686,7 +686,6 @@ export function formatAgentDetail(agent, styles = PLAIN_WORKFLOW_PROGRESS_STYLES
         `State: ${state(agent.state)}`,
         ...(agent.structuralPath?.length ? [`Structural path: ${agent.structuralPath.join(" > ")}`] : []),
         ...(model === undefined ? [] : [`Model: ${model}`]),
-        `Role: ${agent.role ?? "(none)"}`,
         `Tools: ${tools}`,
         ...(agent.attempts !== undefined && Number.isFinite(agent.attempts) && agent.attempts > 1 ? [`Attempts: ${String(agent.attempts)}`] : []),
         ...(duration === undefined ? [] : [`Duration: ${formatWorkflowRuntime(duration)}`]),
@@ -812,11 +811,10 @@ export function formatNavigatorRun(loaded, checkpoints, worktrees, now = Date.no
     const byId = new Map(run.agents.map((agent) => [agent.id, agent]));
     lines.push(...renderGroupedAgents(run.agents, ({ agent, index, depth }, grouped) => {
         const model = `${agent.model.provider}/${agent.model.model}${agent.model.thinking ? `:${agent.model.thinking}` : ""}`;
-        const role = agent.role ? ` role=${agent.role}` : "";
         const tools = ` tools=${agent.tools.join(",") || "(none)"}`;
         const accounting = agent.accounting ? ` input=${String(agent.accounting.input)} output=${String(agent.accounting.output)} cache-read=${String(agent.accounting.cacheRead)} cache-write=${String(agent.accounting.cacheWrite)} cost=${formatCost(agent.accounting.cost) || "$0.00"}` : "";
         const indent = "  ".repeat((grouped ? 2 : 1) + depth);
-        const result = [`${indent}#${String(index + 1)} ${grouped ? agent.label ?? agent.name : agentBreadcrumb(agent, byId)} state=${agent.state} model=${model}${agent.requestedModel ? ` requested=${agent.requestedModel}` : ""}${role}${tools} attempts=${String(agent.attempts)} retries=${String(Math.max(0, agent.attempts - 1))}${accounting}`];
+        const result = [`${indent}#${String(index + 1)} ${grouped ? agent.label ?? agent.name : agentBreadcrumb(agent, byId)} state=${agent.state} model=${model}${agent.requestedModel ? ` requested=${agent.requestedModel}` : ""}${tools} attempts=${String(agent.attempts)} retries=${String(Math.max(0, agent.attempts - 1))}${accounting}`];
         for (const attempt of agent.attemptDetails ?? [])
             result.push(`${indent}  attempt ${String(attempt.attempt)}${attempt.error ? ` error=${attempt.error.code}: ${attempt.error.message}` : ""}`);
         for (const call of agent.toolCalls ?? [])
@@ -856,17 +854,17 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
                 return;
             if (child.agent)
                 agents.push(child.agent);
-            else
-                for (const childId of child.children)
-                    visit(childId);
-        };
-        if (node.agent)
-            agents.push(node.agent);
-        else
-            for (const childId of node.children)
+            for (const childId of child.children)
                 visit(childId);
+        };
+        visit(node.id);
         return agents;
     };
+    const usageLines = (agents) => {
+        const spans = agents.flatMap((agent) => agent.startedAt === undefined ? [] : [[agent.startedAt, agent.startedAt + (elapsedDurationMs(agent, now) ?? 0)]]);
+        const elapsed = spans.length ? formatWorkflowRuntime(Math.max(...spans.map(([, end]) => end)) - Math.min(...spans.map(([start]) => start))) : "";
+        return [...formatAgentAccounting(sumAccounting(agents.map((agent) => agent.accounting ?? zeroAccounting()))), ...(elapsed ? [`Elapsed: ${elapsed}`] : [])];
+    };
     const nodeStatus = (node) => phaseStyle(node.state)(node.state);
     const nodeIcon = (node) => node.children.length ? expanded.has(node.id) ? "▾" : "▸" : node.kind === "agent" ? "•" : node.kind === "shell" ? "◇" : " ";
     const treeLine = (node) => {
@@ -887,12 +885,12 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
             const selected = node.phase;
             const counts = selected?.counts ?? phaseAgentCounts(agents);
             const hint = node.children.length ? "enter expand/collapse" : "enter phase details";
-            return [styles.bold(`Selected phase: ${node.label}`), `Status: ${nodeStatus(node)}`, `agents completed=${String(counts.completed)} running=${String(counts.running)} failed=${String(counts.failed)} cancelled=${String(counts.cancelled)} pending=${String(counts.pending)}`, `Agents: ${String(agents.length)}`, ...(selection.actions ? [] : [styles.muted(hint)])];
+            return [styles.bold(`Selected phase: ${node.label}`), `Status: ${nodeStatus(node)}`, `agents completed=${String(counts.completed)} running=${String(counts.running)} failed=${String(counts.failed)} cancelled=${String(counts.cancelled)} pending=${String(counts.pending)}`, `Agents: ${String(agents.length)}`, ...usageLines(agents), ...(selection.actions ? [] : [styles.muted(hint)])];
         }
         if (node.kind === "operation") {
             const states = phaseAgentCounts(agents);
             const hint = node.children.length ? "enter expand/collapse" : "enter phase details";
-            return [styles.bold(`Selected operation: ${node.operationPath.join(" > ")}`), `Phase: ${node.phase?.name ?? node.phaseId}`, `Status: ${nodeStatus(node)}`, `agents completed=${String(states.completed)} running=${String(states.running)} failed=${String(states.failed)} cancelled=${String(states.cancelled)} pending=${String(states.pending)}`, `Agents: ${String(agents.length)}`, ...(selection.actions ? [] : [styles.muted(hint)])];
+            return [styles.bold(`Selected operation: ${node.operationPath.join(" > ")}`), `Phase: ${node.phase?.name ?? node.phaseId}`, `Status: ${nodeStatus(node)}`, `agents completed=${String(states.completed)} running=${String(states.running)} failed=${String(states.failed)} cancelled=${String(states.cancelled)} pending=${String(states.pending)}`, `Agents: ${String(agents.length)}`, ...usageLines(agents), ...(selection.actions ? [] : [styles.muted(hint)])];
         }
         if (node.kind === "shell") {
             return [styles.bold("Selected shell"), formatShellActivity(node.shellActivity?.active, node.shellActivity?.startedAt, "⠦", styles, now) ?? "shell [running]"];
@@ -928,7 +926,8 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
         return ["", styles.bold(actions.title), ...actions.options.map((option, index) => `${index === actions.index ? "→ " : "  "}${index === actions.index ? styles.accent(option) : option}`)];
     };
     const treeRows = [styles.bold("Tree"), ...(visibleNodes.length ? visibleNodes.map(treeLine) : [styles.muted("(empty)")])];
-    lines.push(...formatNavigatorColumns(treeRows, [...details(selectedNode), ...actionRows()], safeWidth, selection));
+    const detailOffset = Math.max(0, (selection.scrollTop ?? 0) - lines.flatMap(wrap).length);
+    lines.push(...formatNavigatorColumns(treeRows, [...details(selectedNode), ...actionRows()], safeWidth, { ...selection, detailOffset }));
     if (model.unassignedAgents?.length && !tree.nodes.some((node) => node.phaseId === "unassigned"))
         lines.push(...wrap(styles.muted(`Unassigned agents: ${String(model.unassignedAgents.length)}`)));
     return lines.flatMap((line) => wrap(line));
@@ -942,7 +941,10 @@ export function formatNavigatorColumns(sidebar, detail, width, layout = {}) {
     if (safeWidth >= 80) {
         const sidebarWidth = Math.min(42, Math.max(24, Math.floor((safeWidth - 3) * 0.38)));
         const left = sidebar.flatMap((line) => wrapNavigatorLine(line, sidebarWidth));
-        const right = detail.flatMap((line) => wrapNavigatorLine(line, safeWidth - sidebarWidth - 3));
+        const wrapped = detail.flatMap((line) => wrapNavigatorLine(line, safeWidth - sidebarWidth - 3));
+        // Keep the details in view when the tree is scrolled, without making the block taller than the tree.
+        const shift = Math.min(Math.max(0, layout.detailOffset ?? 0), Math.max(0, left.length - wrapped.length));
+        const right = [...Array(shift).fill(""), ...wrapped];
         return Array.from({ length: Math.max(left.length, right.length) }, (_, index) => {
             const cell = left[index] ?? "";
             return `${cell}${" ".repeat(Math.max(0, sidebarWidth - visibleWidth(cell)))} | ${right[index] ?? ""}`;

package/dist/src/host.js

@@ -12,9 +12,8 @@ import { registerWorkflowNavigator, uiHostCapabilities } from "./host-navigator.
 import { acquireSessionLease, isPersistedRun, listPersistedSessionIds, listRunIds, RunStore, structuralPath as operationPath } from "./persistence.js";
 import { retainTerminalRuns } from "./retention.js";
 import { validateBudget, WorkflowBudgetRuntime } from "./budget.js";
-import { SerialLane, asWorkflowError, createLaunchSnapshot, errorCode, errorText, fail, isNodeError, jsonValue, mergeWorkflowExtensionSettings, modelAliasErrorName, modelCapability, object, parseModelReference, positiveInteger, reachableTools, resolveModelReference, VIRTUAL_MODEL_PROVIDER, sanitizeDisplayText, validateModelAliases } from "./utils.js";
-import { loadCodemodeToolsSetting, loadSettings, preflight, resolveAgentResourcePolicy, resolveWorkflowSettings, validateCheckpoint, validateModelAliasAvailability, validateWorkflowLaunchWithRegistry, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./validation.js";
-import { loadAgentDefinitions, loadProjectAgentDefinitions } from "./roles.js";
+import { SerialLane, asWorkflowError, createLaunchSnapshot, errorCode, errorText, fail, isNodeError, jsonValue, modelAliasErrorName, object, parseModelReference, positiveInteger, reachableTools, resolveModelReference, VIRTUAL_MODEL_PROVIDER, sanitizeDisplayText, validateModelAliases } from "./utils.js";
+import { loadCodemodeToolsSetting, preflight, resolveAgentResourcePolicy, staticAgentPreparationOptions, resolveWorkflowSettings, validateCheckpoint, validateModelAliasAvailability, validateWorkflowLaunchWithRegistry, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./validation.js";
 import { beginWorkflowExtensionLoading, loadingRegistry, resetWorkflowRegistryIfIdle, retainWorkflowRegistry } from "./registry.js";
 import { agentHandleTurnPath, agentIdentityPath, agentWorktree, encoded, executeShellCommand, persistActiveAgentAttempt, persistAgentAttempts, readShellResult, runWorkflow, shellIdentityPath, toolIdentityPath } from "./execution.js";
 import { prepareScriptToolLoadout, scriptTool, scriptToolContext, scriptToolValue, validateScriptToolReferences } from "./script-tools.js";
@@ -23,9 +22,9 @@ import { showChangelogNotice } from "./changelog.js";
 import { createTrajectoryRunLoader, createTrajectoryRunMetadataLoader, createTrajectorySubagentLoader, createTrajectorySubagentMetadataLoader, createTrajectoryTranscriptLoader } from "./trajectory.js";
 import { getTrajectoryHost } from "./trajectory-host-handle.js";
 import { getSubagentManager } from "./subagent-manager-handle.js";
-import { HARD_TERMINAL_RUN_STATES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WORKFLOW_BLOCKED_EVENT, WorkflowError, isContextFileScope, isExternallyEndedRunState, isHardTerminalRunState, roleNameOf } from "./types.js";
-import { SETTLED_AGENT_STATES, catalogResultValue, formatWorkflowCatalog, styledTextBlock, textBlock, workflowCatalogBlock, workflowControlCall, workflowControlResult, workflowProgressBlock, } from "./host-view.js";
-import { DELIVERY_LIMIT_BYTES, ForegroundDeliveryController, markWorkflowFailureDiagnostics, WORKFLOW_LOG_ENTRY, completionDescriptor, completionDeliveryFromStore, createWorkflowFailureDiagnostics, failureDiagnosticsFrom, formatWorkflowFailure, formatWorkflowFailureDelivery, formatWorkflowFailureDeliveryFallback, formatWorkflowFailureDiagnostics, isWorkflowFailureDiagnostics, serializeWorkflowFailureDiagnostics, utf8Prefix, } from "./host-delivery.js";
+import { HARD_TERMINAL_RUN_STATES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WORKFLOW_BLOCKED_EVENT, WorkflowError, isContextFileScope, isExternallyEndedRunState, isHardTerminalRunState } from "./types.js";
+import { SETTLED_AGENT_STATES, catalogResultValue, formatWorkflowCatalog, styledTextBlock, textBlock, workflowCatalogBlock, workflowControlCall, workflowControlResult, workflowProgressBlock } from "./host-view.js";
+import { DELIVERY_LIMIT_BYTES, ForegroundDeliveryController, markWorkflowFailureDiagnostics, WORKFLOW_LOG_ENTRY, completionDescriptor, completionDeliveryFromStore, createWorkflowFailureDiagnostics, failureDiagnosticsFrom, formatWorkflowFailure, formatWorkflowFailureDelivery, formatWorkflowFailureDeliveryFallback, formatWorkflowFailureDiagnostics, isWorkflowFailureDiagnostics, serializeWorkflowFailureDiagnostics, utf8Prefix } from "./host-delivery.js";
 export { agentBreadcrumb, agentBreadcrumbParts, formatBudgetStatus, formatNavigatorDashboard, formatNavigatorRun, formatStalledDuration, formatWorkflowPhaseDashboard, formatWorkflowProgress, navigatorAttentionSort, truncateWorkflowProgress, } from "./host-view.js";
 export { buildWorkflowPhaseModel, buildWorkflowPhaseTree, navigateWorkflowPhaseTree, preserveWorkflowPhaseSelection, preserveWorkflowPhaseTreeSelection, workflowPhaseTreeInitialExpanded, workflowPhaseTreeVisibleNodes } from "./host-phases.js";
 export { formatWorkflowFailure, formatWorkflowFailureDelivery, formatWorkflowFailureDiagnostics } from "./host-delivery.js";
@@ -84,27 +83,6 @@ function completionControlContent(result, controlRunId) {
     delete record.run;
     return JSON.stringify({ ...record, value });
 }
-/** Persists a role definition (and its model) into the launch snapshot the first time an agent uses it, so later replays and retries see the definition the run actually ran with. */
-function roleCapture(store, initial, definitions, projectDefinitions) {
-    let persisted = initial;
-    return {
-        get snapshot() { return persisted; },
-        async capture(role, model) {
-            const definition = definitions[role];
-            if (!definition)
-                return;
-            const modelName = `${model.provider}/${model.model}`;
-            const hasProjectRole = projectDefinitions[role] !== undefined;
-            if (persisted.roles?.[role] !== undefined && (!hasProjectRole || persisted.projectRoles?.includes(role)) && persisted.models.includes(modelName))
-                return;
-            const roles = { ...(persisted.roles ?? {}), [role]: definition };
-            const projectRoles = hasProjectRole ? [...new Set([...(persisted.projectRoles ?? []), role])] : persisted.projectRoles ?? [];
-            const models = [...new Set([...persisted.models, modelName])];
-            persisted = createLaunchSnapshot({ ...persisted, models, roles, projectRoles });
-            await store.saveSnapshot(persisted);
-        },
-    };
-}
 export function formatWorkflowPreview(args) {
     const name = typeof args.name === "string" && args.name.trim() ? args.name.trim() : "workflow";
     if (typeof args.script !== "string" || !args.script.trim())
@@ -283,6 +261,21 @@ async function resolveLaunchAliases(registry, staticAliases, context, availableM
         throw error;
     }
 }
+/**
+ * Prepares each completely static agent configuration in inspection mode, so preparation plugins resolve their own aliases
+ * and options without persisting a configuration. Any preparation failure rejects launch before effects; cancellation stops
+ * the remaining inspections.
+ */
+async function inspectStaticAgentConfigurations(executor, script, workflowName, signal, functions) {
+    // NOTE: inspection uses the launch cwd; agents inside withWorktree(...) prepare against their checkout at runtime.
+    for (const agentOptions of staticAgentPreparationOptions(script, functions)) {
+        if (signal.aborted)
+            throw new WorkflowError("CANCELLED", "Workflow launch cancelled");
+        await executor.prepare({ label: "agent", workflowName, agentOptions }, undefined, signal, "inspection");
+    }
+    if (signal.aborted)
+        throw new WorkflowError("CANCELLED", "Workflow launch cancelled");
+}
 export default function workflowExtension(pi, home, clipboard = copyToClipboard, transport = localAgentTransport, agentDir, additionalSkillPaths = []) {
     beginWorkflowExtensionLoading();
     const registry = loadingRegistry();
@@ -298,7 +291,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
     });
     let backgroundWidgetEnabled = true;
     try {
-        const globalSettings = loadSettings(workflowSettingsPath(extensionAgentDir));
+        const globalSettings = resolveWorkflowSettings(process.cwd(), false, workflowSettingsPath(extensionAgentDir)).effective;
         backgroundWidgetEnabled = globalSettings.backgroundWidget ?? true;
         // Registered at load, before Pi resolves --model and restores the session model. Project aliases need project trust, which is unknown here.
         registerAliasVirtualModels(pi, Object.keys(globalSettings.modelAliases ?? {}), workflowSettingsPath(extensionAgentDir));
@@ -338,6 +331,9 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         return skillPath ? { skillPaths: [skillPath] } : undefined;
     });
     const runs = new Map();
+    // Extension load failures a headless launcher reported for this host. They hold for the whole process, so every executor,
+    // including those that paused resume, cold resume and retry create, keeps failing ownerless options closed.
+    let extensionLoad;
     const deliveryController = new ForegroundDeliveryController({ runs, ...(typeof pi.sendMessage === "function" ? { deliver: (content) => { deliver(pi, content); } } : {}) });
     let releaseWorkflowRegistry;
     const providerRecoveryLane = new SerialLane();
@@ -817,7 +813,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot(), agents: current.agents.map((agent) => agent.id === id ? { ...agent, lastEventAt } : agent) }));
                 run.update?.(workflowToolUpdate(withLiveActivities(persisted)));
             };
-            const result = await run.executor.execute(prompt, { label: options.label, workflowName: run.metadata.name, tuiIndex, tuiLabel: options.requestedLabel ?? options.label, agentNodeId: id, ...(options.extensionSettings === undefined ? {} : { inheritedExtensionSettings: options.extensionSettings }), 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.role ? { role: options.role } : {}), ...(options.contextFiles ? { contextFiles: options.contextFiles } : {}), tools: options.tools, ...(options.skills ? { skills: options.skills } : {}), ...(options.extensions ? { extensions: options.extensions } : {}), effectiveTools: options.tools, ...(options.schema ? { schema: options.schema } : {}), ...(options.retries === undefined ? {} : { retries: options.retries }), ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.sessionPath ? { sessionPath: options.sessionPath } : {}), ...(options.agentOptions ? { agentOptions: options.agentOptions } : {}), ...(options.agentIdentity ? { agentIdentity: options.agentIdentity } : {}) }, signal, scheduler.toolsFor(id, (role, tools, model, inheritedTools, skills, extensions) => run.executor.resolve({ label: "child", workflowName: run.metadata.name, ...(model ? { model } : {}), ...(role ? { role } : {}), ...(tools !== undefined ? { tools } : {}), ...(skills !== undefined ? { skills } : {}), ...(extensions !== undefined ? { extensions } : {}) }, inheritedTools).tools), setSteer, () => { scheduler.cancelChildren(id); scheduler.retry(id); });
+            const result = await run.executor.execute(prompt, { label: options.label, workflowName: run.metadata.name, tuiIndex, tuiLabel: options.requestedLabel ?? options.label, agentNodeId: id, ...(options.extensionSettings === undefined ? {} : { inheritedExtensionSettings: options.extensionSettings }), 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.contextFiles ? { contextFiles: options.contextFiles } : {}), tools: options.tools, ...(options.skills ? { skills: options.skills } : {}), ...(options.extensions ? { extensions: options.extensions } : {}), effectiveTools: options.tools, ...(options.schema ? { schema: options.schema } : {}), ...(options.retries === undefined ? {} : { retries: options.retries }), ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.sessionPath ? { sessionPath: options.sessionPath } : {}), ...(options.agentOptions ? { agentOptions: options.agentOptions } : {}), ...(options.agentIdentity ? { agentIdentity: options.agentIdentity } : {}), ...(options.configuration ? { configuration: options.configuration } : {}), ...(options.capabilities ? { capabilities: options.capabilities } : {}), ...(options.projectTrusted === undefined ? {} : { projectTrusted: options.projectTrusted }), ...(options.inheritedExcludeTools ? { inheritedExcludeTools: options.inheritedExcludeTools } : {}), onConfiguration: (configuration) => scheduler.setConfiguration(id, configuration) }, signal, scheduler.toolsFor(id), setSteer, () => { scheduler.cancelChildren(id); scheduler.retry(id); });
             cancelDeferredProgress();
             const before = (await run.store.load()).run;
             await persistAgentAttempts(run.store, id, result.attempts);
@@ -855,7 +851,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
             const existing = new Map(current.agents.map((agent) => [agent.id, agent]));
             const agents = ownership.map((node) => {
                 const previous = existing.get(node.id);
-                const requested = { label: node.options.label, workflowName: run.metadata.name, ...(node.options.skills ? { skills: node.options.skills } : {}), ...(node.options.extensions ? { extensions: node.options.extensions } : {}), ...(node.options.model ? { model: node.options.model } : {}), ...(node.options.role ? { role: node.options.role } : {}), ...(node.options.contextFiles ? { contextFiles: node.options.contextFiles } : {}) };
+                const requested = { label: node.options.label, workflowName: run.metadata.name, ...(node.options.skills ? { skills: node.options.skills } : {}), ...(node.options.extensions ? { extensions: node.options.extensions } : {}), ...(node.options.model ? { model: node.options.model } : {}), ...(node.options.contextFiles ? { contextFiles: node.options.contextFiles } : {}), ...(node.options.configuration ? { configuration: node.options.configuration } : {}) };
                 let effective;
                 try {
                     effective = { ...run.executor.resolve({ ...requested, effectiveTools: node.options.tools }), tools: node.options.tools };
@@ -864,12 +860,11 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                     effective = previous ? { model: previous.model, ...(previous.requestedModel ? { requestedModel: previous.requestedModel } : {}), tools: previous.tools } : { model: node.options.model ? modelSpec(node.options.model, run.model) : run.model, ...(node.options.model ? { requestedModel: node.options.model } : {}), tools: node.options.tools };
                 }
                 const resultPath = !node.parentId && node.options.agentIdentity ? agentIdentityPath(node.options.agentIdentity) : undefined;
-                const nodeRole = roleNameOf(node.options.role);
                 const now = Date.now();
                 const lastEventAt = node.state === "running" ? previous?.state === "running" && previous.lastEventAt !== undefined ? previous.lastEventAt : now : previous?.lastEventAt;
                 const startedAt = previous?.startedAt ?? (node.state === "running" ? now : undefined);
                 const durationMs = previous?.durationMs ?? (SETTLED_AGENT_STATES.has(node.state) && startedAt !== undefined ? Math.max(0, now - startedAt) : undefined);
-                return { ...(previous?.systemPrompt === undefined ? {} : { systemPrompt: previous.systemPrompt }), ...(node.prompt !== undefined ? { prompt: node.prompt } : previous?.prompt !== undefined ? { prompt: previous.prompt } : {}), id: node.id, name: node.label, ...(node.options.requestedLabel ? { label: node.options.requestedLabel } : {}), path: node.id, state: node.state, ...(node.parentId ? { parentId: node.parentId } : {}), structuralPath: [...(node.options.agentIdentity?.structuralPath ?? [])], ...(resultPath ? { resultPath } : {}), ...(node.options.parentBreadcrumb ? { parentBreadcrumb: node.options.parentBreadcrumb } : {}), ...(node.options.worktreeOwner ? { worktreeOwner: node.options.worktreeOwner } : {}), ...(node.options.agentIdentity?.handle === undefined ? {} : { handle: node.options.agentIdentity.handle, ...(node.options.agentIdentity.turn === undefined ? {} : { turn: node.options.agentIdentity.turn }), ...(node.options.continuity ? { continuity: node.options.continuity } : {}) }), ...(nodeRole ? { role: nodeRole } : {}), ...(effective.requestedModel ? { requestedModel: effective.requestedModel } : {}), model: effective.model, tools: effective.tools, attempts: previous?.attempts ?? 0, ...(startedAt === undefined ? {} : { startedAt }), ...(durationMs === undefined ? {} : { durationMs }), ...(previous?.attemptDetails ? { attemptDetails: previous.attemptDetails } : {}), ...(previous?.accounting ? { accounting: previous.accounting } : {}), ...(previous?.toolCalls ? { toolCalls: previous.toolCalls } : {}), ...(previous?.activity ? { activity: previous.activity } : {}), ...(lastEventAt === undefined ? {} : { lastEventAt }) };
+                return { ...(previous?.systemPrompt === undefined ? {} : { systemPrompt: previous.systemPrompt }), ...(node.prompt !== undefined ? { prompt: node.prompt } : previous?.prompt !== undefined ? { prompt: previous.prompt } : {}), id: node.id, name: node.label, ...(node.options.requestedLabel ? { label: node.options.requestedLabel } : {}), path: node.id, state: node.state, ...(node.parentId ? { parentId: node.parentId } : {}), structuralPath: [...(node.options.agentIdentity?.structuralPath ?? [])], ...(resultPath ? { resultPath } : {}), ...(node.options.parentBreadcrumb ? { parentBreadcrumb: node.options.parentBreadcrumb } : {}), ...(node.options.worktreeOwner ? { worktreeOwner: node.options.worktreeOwner } : {}), ...(node.options.agentIdentity?.handle === undefined ? {} : { handle: node.options.agentIdentity.handle, ...(node.options.agentIdentity.turn === undefined ? {} : { turn: node.options.agentIdentity.turn }), ...(node.options.continuity ? { continuity: node.options.continuity } : {}) }), ...(effective.requestedModel ? { requestedModel: effective.requestedModel } : {}), model: effective.model, tools: effective.tools, attempts: previous?.attempts ?? 0, ...(startedAt === undefined ? {} : { startedAt }), ...(durationMs === undefined ? {} : { durationMs }), ...(previous?.attemptDetails ? { attemptDetails: previous.attemptDetails } : {}), ...(previous?.accounting ? { accounting: previous.accounting } : {}), ...(previous?.toolCalls ? { toolCalls: previous.toolCalls } : {}), ...(previous?.activity ? { activity: previous.activity } : {}), ...(lastEventAt === undefined ? {} : { lastEventAt }) };
             });
             return { ...current, agents };
         });
@@ -1093,21 +1088,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         });
         catalogRegistered = true;
     };
-    const createAgentExecutor = (root) => new WorkflowAgentExecutor({ ...root, agentDir: extensionAgentDir, ...(additionalSkillPaths.length ? { additionalSkillPaths } : {}), agentSetupHooks: registry.agentSetupHooks(), validateExtensionSettings: registry.validateExtensionSettings, onResourceWarning: (message) => { deliverWarning(pi, message); }, onAgentSettings: (agentId, settings) => { scheduler.setExtensionSettings(agentId, settings); } }, transport);
-    // Resumed runs keep the role definitions frozen in their snapshot and fall back to the current definitions for roles a
-    // registered function reaches for the first time after the restart; those are captured into the snapshot like at launch.
-    const resumeRoles = (store, snapshot, cwd, trustedProject) => {
-        let current = {};
-        let project = {};
-        try {
-            current = loadAgentDefinitions(cwd, extensionAgentDir, trustedProject, registry.roleDirectoryRegistrations());
-            project = trustedProject ? loadProjectAgentDefinitions(cwd) : {};
-        }
-        catch { /* Unreadable current roles leave the resume with the snapshot roles, as before. */ }
-        const definitions = { ...current, ...(snapshot.roles ?? {}) };
-        const captured = roleCapture(store, snapshot, definitions, project);
-        return { definitions, capture: (role, model) => captured.capture(role, model) };
-    };
+    const createAgentExecutor = (root) => new WorkflowAgentExecutor({ ...root, ...(extensionLoad ? { extensionLoad } : {}), agentDir: extensionAgentDir, ...(additionalSkillPaths.length ? { additionalSkillPaths } : {}), agentPreparationHooks: registry.agentPreparationHooks(), agentSetupHooks: registry.agentSetupHooks(), validateExtensionSettings: registry.validateExtensionSettings, onResourceWarning: root.onResourceWarning ?? ((message) => { deliverWarning(pi, message); }), onAgentSettings: (agentId, settings) => { scheduler.setExtensionSettings(agentId, settings); }, onAgentCapabilities: (agentId, capabilities, projectTrusted) => { scheduler.setAttemptCapabilities(agentId, capabilities, projectTrusted); } }, transport);
     const activeSnapshotTools = (tools, active) => active === "session"
         ? new Set(tools.filter((tool) => reachableTools(pi).includes(tool) && tool !== "workflow_catalog"))
         : new Set(tools.filter((tool) => active.has(tool) || tool === "workflow_catalog"));
@@ -1121,27 +1102,27 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         const extensionSettings = input.snapshot.settings.extensionSettings;
         const extensionSettingsPath = input.snapshot.settingsSources?.extensionSettings ?? input.snapshot.settingsPath ?? settingsPath;
         registry.validateExtensionSettings(extensionSettings, { source: "effective", cwd: input.cwd, projectTrusted: input.trustedProject, settingsPath: extensionSettingsPath });
-        for (const [role, definition] of Object.entries(input.snapshot.roles ?? {}))
-            registry.validateExtensionSettings(mergeWorkflowExtensionSettings(extensionSettings, definition.extensionSettings), { source: "role", cwd: input.cwd, projectTrusted: input.trustedProject, settingsPath: extensionSettingsPath, role });
         const currentPolicy = resolveAgentResourcePolicy(input.cwd, input.trustedProject, settingsPath);
         const staticAliases = resolution.effective.modelAliases ?? {};
         const previousAliases = input.snapshot.modelAliases ?? input.snapshot.settings.modelAliases ?? {};
         const inventory = modelInventory(input.rootModel, input.modelRegistry);
         const knownModels = input.modelRegistry ? inventory.knownModels : new Set([...input.snapshot.models, ...inventory.knownModels]);
         const availableModels = input.modelRegistry ? inventory.availableModels : new Set([...input.snapshot.models, ...inventory.availableModels]);
-        const currentAliases = input.resolvedAliases ?? (await resolveLaunchAliases(registry, staticAliases, { cwd: input.cwd, projectTrusted: input.trustedProject, rootModel: input.rootModel, knownModels, availableModels, signal: input.signal }, availableModels, knownModels, settingsPath)).aliases;
+        const resolved = input.resolvedAliases ? { aliases: input.resolvedAliases, dynamicNames: input.resolvedDynamicAliasNames ?? [] } : await resolveLaunchAliases(registry, staticAliases, { cwd: input.cwd, projectTrusted: input.trustedProject, rootModel: input.rootModel, knownModels, availableModels, signal: input.signal }, availableModels, knownModels, settingsPath);
+        const currentAliases = resolved.aliases;
+        const dynamicAliasNames = resolved.dynamicNames;
         const blockedAliases = input.blockedAliases ?? new Set(Object.keys(previousAliases).filter((name) => !Object.prototype.hasOwnProperty.call(currentAliases, name)));
         const blockedAliasTargets = input.blockedAliasTargets ?? Object.fromEntries(Object.entries(previousAliases).filter(([name]) => !Object.prototype.hasOwnProperty.call(currentAliases, name)));
         const script = input.withPreflight ? input.snapshot.script : undefined;
         if (script !== undefined) {
             const resumeAliases = { ...previousAliases, ...currentAliases };
-            preflight(script, { models: availableModels, tools: active, agentTypes: new Set(input.snapshot.agentTypes), modelAliases: resumeAliases, knownModels, settingsPath, skipModelAvailability: true }, input.snapshot.schemas, input.snapshot.metadata, true);
+            preflight(script, { models: availableModels, tools: active, modelAliases: resumeAliases, knownModels, settingsPath, skipModelAvailability: true }, input.snapshot.schemas, input.snapshot.metadata, true);
         }
         const refreshed = resumedSnapshotSettings(input.snapshot, resolution, currentAliases);
         const snapshot = createLaunchSnapshot({ ...input.snapshot, settingsPath, ...refreshed, modelAliases: currentAliases });
-        return { active, settingsPath, resolution, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot, script };
+        return { active, settingsPath, resolution, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, dynamicAliasNames, blockedAliases, blockedAliasTargets, snapshot, script };
     };
-    const workflowAgentHandler = (store, metadata, lifecycle, executor, cwd, runId, captureRole) => {
+    const workflowAgentHandler = (store, metadata, lifecycle, executor, cwd, runId) => {
         // Replay lookup and spawn are serialised per run so concurrent agent(...) calls reach the scheduler in call order.
         const admission = new SerialLane();
         return async (prompt, options, agentSignal, identity) => {
@@ -1154,21 +1135,21 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                         return { replayed };
                     const worktree = agentWorktree(identity);
                     const agentCwd = worktree.worktreeOwner ? (await persistWorktree(store, metadata, worktree.worktreeOwner)).cwd : cwd;
-                    const role = typeof options.role === "string" ? options.role : undefined;
                     const model = typeof options.model === "string" ? options.model : undefined;
                     const requestedLabel = typeof options.label === "string" ? options.label : undefined;
                     const skills = Array.isArray(options.skills) ? options.skills : undefined;
                     const extensions = Array.isArray(options.extensions) ? options.extensions : undefined;
                     const contextFiles = Array.isArray(options.contextFiles) && options.contextFiles.every(isContextFileScope) ? options.contextFiles : undefined;
-                    const resolved = executor.resolve({ label: requestedLabel ?? role ?? "agent", workflowName: metadata.name, ...(model ? { model } : {}), ...(role ? { role } : {}), ...(contextFiles ? { contextFiles } : {}), ...(Array.isArray(options.tools) ? { tools: options.tools } : {}), ...(skills ? { skills } : {}), ...(extensions ? { extensions } : {}) });
-                    if (role)
-                        await captureRole?.(role, resolved.model);
-                    const label = displayAgentName(requestedLabel, role, resolved.model);
+                    // A paused resume replaces the run executor with refreshed aliases; new identities must prepare against it.
+                    const current = runs.get(runId)?.executor ?? executor;
+                    const configuration = await current.prepare({ label: requestedLabel ?? "agent", workflowName: metadata.name, agentOptions: options, agentIdentity: identity, ...(worktree.worktreeOwner ? { worktreeOwner: worktree.worktreeOwner } : {}) }, agentCwd, agentSignal);
+                    const resolved = configuration;
+                    const label = requestedLabel ?? configuration.label ?? resolved.model.model;
                     const tools = resolved.tools;
                     const schema = object(options.outputSchema) ? options.outputSchema : undefined;
                     const sessionPath = identity.handle !== undefined && identity.turn !== undefined ? await handleTurnInput(store, identity.handle, identity.turn) : undefined;
                     const continuity = identity.handle === undefined ? undefined : sessionPath ? "continued" : "fresh";
-                    return { spawned: scheduler.spawn(runId, prompt, { label, ...(requestedLabel ? { requestedLabel } : {}), ...(identity.parentBreadcrumb ? { parentBreadcrumb: identity.parentBreadcrumb } : {}), cwd: agentCwd, tools, ...(skills ? { skills } : {}), ...(extensions ? { extensions } : {}), ...worktree, ...(model ? { model } : {}), ...(role ? { role } : {}), ...(contextFiles ? { contextFiles } : {}), ...(schema ? { schema } : {}), ...(typeof options.retries === "number" ? { retries: options.retries } : {}), ...(positiveInteger(options.timeoutMs) || options.timeoutMs === null ? { timeoutMs: options.timeoutMs } : {}), ...(sessionPath ? { sessionPath } : {}), ...(continuity ? { continuity } : {}), agentOptions: options, agentIdentity: identity }) };
+                    return { spawned: scheduler.spawn(runId, prompt, { label, ...(requestedLabel ? { requestedLabel } : {}), ...(identity.parentBreadcrumb ? { parentBreadcrumb: identity.parentBreadcrumb } : {}), cwd: agentCwd, tools, ...(skills ? { skills } : {}), ...(extensions ? { extensions } : {}), ...worktree, ...(model ? { model } : {}), ...(contextFiles ? { contextFiles } : {}), ...(schema ? { schema } : {}), ...(typeof options.retries === "number" ? { retries: options.retries } : {}), ...(positiveInteger(options.timeoutMs) || options.timeoutMs === null ? { timeoutMs: options.timeoutMs } : {}), ...(sessionPath ? { sessionPath } : {}), ...(continuity ? { continuity } : {}), agentOptions: options, agentIdentity: identity, configuration }) };
                 });
                 if ("replayed" in admitted)
                     return admitted.replayed.value;
@@ -1191,7 +1172,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
         };
     };
     const recovery = createWorkflowRecovery({
-        pi, home, runs, scheduler, eventPublisher, persistRunState, projectTrusted, resumeHostContext, ensureSessionLease, coordinateRunMutation, createAgentExecutor, activeSnapshotTools, frozenResourcePolicy, resolveLaunchPrologue: resumeLaunchPrologue, resumeRoles, workflowAgentHandler, shellForRun, toolForRun, resolveWorktree, checkpointBridge, phaseBridge, logBridge, lifecycleFor, createProviderErrorRecovery, cleanupTerminalRun, deliver: (content) => { deliver(pi, content); }, deliverTerminal: deliveryController.deliverTerminal, workflowToolUpdate, registry, modelSpec,
+        pi, home, runs, scheduler, eventPublisher, persistRunState, projectTrusted, resumeHostContext, ensureSessionLease, coordinateRunMutation, createAgentExecutor, activeSnapshotTools, frozenResourcePolicy, resolveLaunchPrologue: resumeLaunchPrologue, workflowAgentHandler, shellForRun, toolForRun, resolveWorktree, checkpointBridge, phaseBridge, logBridge, lifecycleFor, createProviderErrorRecovery, cleanupTerminalRun, deliver: (content) => { deliver(pi, content); }, deliverTerminal: deliveryController.deliverTerminal, workflowToolUpdate, registry, modelSpec,
     });
     const resumeSelectedWorkflow = async (runId, foreground, context, budgetPatch) => {
         const run = runs.get(runId);
@@ -1212,9 +1193,8 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 await deliveryController.moveForegroundToBackground(runId);
             if (foreground && !wasAttached) {
                 run.foreground = true;
-                const loaded = await run.store.load();
                 await persistRunState(run.store, run.metadata, (current) => ({ ...current, delivery: { ...(current.delivery ?? {}), mode: "foreground", state: "attached" } }));
-                await run.store.saveSnapshot(createLaunchSnapshot({ ...loaded.snapshot, launchMode: "foreground" }));
+                await run.store.setLaunchMode("foreground");
             }
             else if (!foreground)
                 run.foreground = false;
@@ -1349,10 +1329,9 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 const budgetRuntime = new WorkflowBudgetRuntime(budget, loaded.run.budgetVersion ?? 1, loaded.run.usage, loaded.run.budgetEvents, { active: loaded.run.state === "running" });
                 const lifecycle = lifecycleFor(store, loaded.run.state, loaded.snapshot.metadata);
                 const providerPause = async () => { deliver(pi, `Workflow ${loaded.snapshot.metadata.name} paused: provider limit.`); await lifecycle.providerPause(); };
-                const roleDefinitions = loaded.snapshot.roles ?? {};
                 const abortController = new AbortController();
                 const providerErrorRecovery = createProviderErrorRecovery(ctx, new Set(loaded.snapshot.models), () => { abortController.abort(); });
-                runs.set(runId, { executor: createAgentExecutor({ cwd: ctx.cwd, model, tools: activeSnapshotTools(loaded.snapshot.tools, "session"), resourceSelectors: snapshotResourcePolicy(loaded.snapshot, store.cwd, projectTrusted(ctx), workflowSettingsPath(extensionAgentDir)).effective, extensionSettings: loaded.snapshot.settings.extensionSettings, 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.settingsSources?.modelAliases ? { settingsPath: loaded.snapshot.settingsSources.modelAliases } : loaded.snapshot.settingsPath ? { settingsPath: loaded.snapshot.settingsPath } : {}), agentDefinitions: roleDefinitions, runStore: store, providerPause, agentResourcePolicy: frozenResourcePolicy(snapshotResourcePolicy(loaded.snapshot, store.cwd, projectTrusted(ctx), workflowSettingsPath(extensionAgentDir))) }), store, metadata: loaded.snapshot.metadata, model, lifecycle, budget: budgetRuntime, abortController, projectTrusted: () => projectTrusted(ctx), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}) });
+                runs.set(runId, { executor: createAgentExecutor({ cwd: ctx.cwd, projectTrusted: projectTrusted(ctx), model, tools: activeSnapshotTools(loaded.snapshot.tools, "session"), resourceSelectors: snapshotResourcePolicy(loaded.snapshot, store.cwd, projectTrusted(ctx), workflowSettingsPath(extensionAgentDir)).effective, extensionSettings: loaded.snapshot.settings.extensionSettings, 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.settingsSources?.modelAliases ? { settingsPath: loaded.snapshot.settingsSources.modelAliases } : loaded.snapshot.settingsPath ? { settingsPath: loaded.snapshot.settingsPath } : {}), runStore: store, providerPause, agentResourcePolicy: frozenResourcePolicy(snapshotResourcePolicy(loaded.snapshot, store.cwd, projectTrusted(ctx), workflowSettingsPath(extensionAgentDir))) }), 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())
@@ -1391,15 +1370,6 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
             throw error;
         }
     });
-    pi.on("before_agent_start", (event, ctx) => {
-        if (!pi.getActiveTools().includes("workflow"))
-            return;
-        const roles = Object.entries(loadAgentDefinitions(ctx.cwd, extensionAgentDir, projectTrusted(ctx), typeof registry.roleDirectoryRegistrations === "function" ? registry.roleDirectoryRegistrations() : undefined)).filter(([, definition]) => definition.description);
-        if (!roles.length)
-            return;
-        const content = `Workflow role descriptions:\n${roles.map(([name, definition]) => `- \`${name}\`: ${String(definition.description)}`).join("\n")}`;
-        return { systemPrompt: `${event.systemPrompt}\n\n${content}` };
-    });
     const workflowTool = {
         name: "workflow",
         label: WORKFLOW_TOOL_LABEL,
@@ -1448,25 +1418,33 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 if (trustedProject && launch.resolution.project.extensionSettings !== undefined)
                     registry.validateExtensionSettings(launch.resolution.project.extensionSettings, { source: "project", cwd: ctx.cwd, projectTrusted: true, settingsPath: launch.resolution.projectSettingsPath });
                 const validated = validateWorkflowLaunchWithRegistry(params, { cwd: ctx.cwd, agentDir: extensionAgentDir, projectTrusted: trustedProject, availableModels, rootTools: new Set(rootTools), modelAliases, knownModels, settingsPath, ...(settings.extensionSettings === undefined ? {} : { extensionSettings: settings.extensionSettings }) }, registry);
-                const { script, checked, agentDefinitions, projectAgentDefinitions, roleNames } = validated;
+                const { script, checked } = validated;
                 const toolContext = scriptToolContext(ctx);
                 validateScriptToolReferences(script, toolContext);
+                // Headless hosts that tolerated extension load failures report them with the extensions they loaded.
+                const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+                const loadErrors = object(ctx) ? strings(ctx.extensionLoadErrors) : [];
+                if (loadErrors.length)
+                    extensionLoad = Object.freeze({ errors: loadErrors, loaded: object(ctx) ? strings(ctx.loadedExtensionPaths) : [] });
+                const executorRoot = { cwd: ctx.cwd, projectTrusted: launch.resourcePolicy.projectTrusted, model: rootModel, tools: new Set(rootTools), resourceSelectors: launch.resourcePolicy.effective, extensionSettings: settings.extensionSettings, availableModels, knownModels, modelAliases, dynamicModelAliasNames: resolvedAliases.dynamicNames, settingsPath, agentResourcePolicy: frozenResourcePolicy(launch.resourcePolicy) };
+                // Runtime emits the same resource warnings, so inspection stays silent.
+                await inspectStaticAgentConfigurations(createAgentExecutor({ ...executorRoot, onResourceWarning: () => undefined }), script, checked.metadata.name, runController.signal, registry.functions());
                 await ensureSessionLease(ctx.cwd, ctx.sessionManager.getSessionId());
+                // Cancellation can arrive while the lease or a queued parent validation is pending; no run may be created after it.
+                const assertLaunchActive = () => { if (runController.signal.aborted)
+                    throw new WorkflowError("CANCELLED", "Workflow launch cancelled"); };
+                assertLaunchActive();
                 const runId = randomUUID();
                 const args = params.args ?? null;
                 encoded(args);
                 const runContext = workflowRunContext(ctx.cwd, ctx.sessionManager.getSessionId(), runId, checked.metadata, args, runController.signal);
                 const store = new RunStore(ctx.cwd, ctx.sessionManager.getSessionId(), runId, home);
                 const parentRunId = params.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, modelAliases, knownModels, settingsPath)] : []; });
-                const snapshotModels = [...new Set([rootModelName, ...checked.referenced.models, ...roleModels])];
-                const snapshot = createLaunchSnapshot({ script, args, metadata: checked.metadata, launchMode: params.foreground ? "foreground" : "background", settings, settingsPath, settingsSources: { ...launch.resolution.sources, concurrency: params.concurrency === undefined ? launch.resolution.sources.concurrency : "per-run options" }, ...(Object.keys(modelAliases).length ? { modelAliases } : {}), ...(budget ? { budget } : {}), ...(checked.referenced.phases.length ? { phases: checked.referenced.phases } : {}), models: snapshotModels, tools: rootTools, agentTypes: checked.referenced.agentTypes, roles, projectRoles, schemas: checked.schemas });
-                const capturedRoles = roleCapture(store, snapshot, agentDefinitions, projectAgentDefinitions);
+                const snapshotModels = [...new Set([rootModelName, ...checked.referenced.models])];
+                const snapshot = createLaunchSnapshot({ script, args, metadata: checked.metadata, launchMode: params.foreground ? "foreground" : "background", settings, settingsPath, settingsSources: { ...launch.resolution.sources, concurrency: params.concurrency === undefined ? launch.resolution.sources.concurrency : "per-run options" }, ...(Object.keys(modelAliases).length ? { modelAliases } : {}), ...(budget ? { budget } : {}), ...(checked.referenced.phases.length ? { phases: checked.referenced.phases } : {}), models: snapshotModels, tools: rootTools, agentConfigurations: {}, schemas: checked.schemas });
                 const budgetRuntime = new WorkflowBudgetRuntime(budget);
                 const initialBudget = budgetRuntime.snapshot();
-                const createRun = () => store.create({ id: runId, workflowName: checked.metadata.name, cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId(), state: "running", ...(parentRunId !== undefined ? { parentRunId } : {}), agents: [], agentSessions: [], delivery: params.foreground ? { mode: "foreground", state: "attached", toolCallId } : { mode: "background", state: "pending" }, ...(budget ? { budget } : {}), budgetVersion: 1, ...initialBudget }, snapshot);
+                const createRun = () => { assertLaunchActive(); return store.create({ id: runId, workflowName: checked.metadata.name, cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId(), state: "running", ...(parentRunId !== undefined ? { parentRunId } : {}), agents: [], agentSessions: [], delivery: params.foreground ? { mode: "foreground", state: "attached", toolCallId } : { mode: "background", state: "pending" }, ...(budget ? { budget } : {}), budgetVersion: 1, ...initialBudget }, snapshot); };
                 // Parent validation and persistence share the mutation lane so a manual deletion cannot remove the parent between the two.
                 if (parentRunId !== undefined)
                     await coordinateRunMutation(async () => { await store.validateParentRun(parentRunId); await createRun(); });
@@ -1494,7 +1472,7 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                                 activeRun.foreground = false;
                                 delete activeRun.update;
                             }
-                            await store.saveSnapshot(createLaunchSnapshot({ ...capturedRoles.snapshot, launchMode: "background" }));
+                            await store.setLaunchMode("background");
                             for (const checkpoint of await store.awaitingCheckpoints())
                                 deliverBackgroundCheckpoint(checked.metadata.name, runId, checkpoint);
                             signal?.removeEventListener("abort", onForegroundAbort);
@@ -1511,13 +1489,13 @@ export default function workflowExtension(pi, home, clipboard = copyToClipboard,
                 const providerPause = async () => { if (!foregroundAttached)
                     deliver(pi, `Workflow ${checked.metadata.name} paused: provider limit.`); await lifecycle.providerPause(); };
                 const providerErrorRecovery = createProviderErrorRecovery(ctx, availableModels, () => { runController.abort(); });
-                const executor = createAgentExecutor({ cwd: ctx.cwd, model: rootModel, tools: new Set(rootTools), resourceSelectors: launch.resourcePolicy.effective, extensionSettings: settings.extensionSettings, availableModels, knownModels, modelAliases, settingsPath, agentDefinitions, runStore: store, providerPause, agentResourcePolicy: frozenResourcePolicy(launch.resourcePolicy), runContext });
+                const executor = createAgentExecutor({ ...executorRoot, runStore: store, providerPause, runContext });
                 const runRecord = { executor, store, metadata: checked.metadata, model: rootModel, lifecycle, budget: budgetRuntime, abortController: runController, foreground: foregroundAttached, projectTrusted: () => projectTrusted(ctx), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}), ...(params.foreground && onUpdate ? { update: onUpdate } : {}) };
                 runs.set(runId, runRecord);
                 if (params.foreground && onUpdate)
                     onUpdate(workflowToolUpdate((await store.load()).run));
                 scheduler.addRun(runId, settings.concurrency, () => runs.get(runId)?.budget.checkAgentLaunch(), settings.extensionSettings);
-                const execution = runWorkflow(script, args, withWorkflowFunctions({ tool: (identifier, toolArgs, signal, identity) => toolForRun(store, lifecycle, toolContext, identifier, toolArgs, signal, identity), shell: (command, options, signal, identity) => shellForRun(store, checked.metadata, lifecycle, command, options, signal, identity), agent: workflowAgentHandler(store, checked.metadata, lifecycle, executor, ctx.cwd, runId, (role, model) => capturedRoles.capture(role, model)), worktree: async (owner) => resolveWorktree(store, checked.metadata, owner), checkpoint: checkpointBridge(runId, store, checked.metadata, () => runs.get(runId)?.foreground ?? foregroundAttached, ctx.hasUI ? ctx.ui : undefined, headless), phase: phaseBridge(store, checked.metadata, lifecycle), log: logBridge(store, lifecycle, checked.metadata.name) }, store, runContext, registry, settings.extensionSettings), runController.signal);
+                const execution = runWorkflow(script, args, withWorkflowFunctions({ tool: (identifier, toolArgs, signal, identity) => toolForRun(store, lifecycle, toolContext, identifier, toolArgs, signal, identity), shell: (command, options, signal, identity) => shellForRun(store, checked.metadata, lifecycle, command, options, signal, identity), agent: workflowAgentHandler(store, checked.metadata, lifecycle, executor, ctx.cwd, runId), worktree: async (owner) => resolveWorktree(store, checked.metadata, owner), checkpoint: checkpointBridge(runId, store, checked.metadata, () => runs.get(runId)?.foreground ?? foregroundAttached, ctx.hasUI ? ctx.ui : undefined, headless), phase: phaseBridge(store, checked.metadata, lifecycle), log: logBridge(store, lifecycle, checked.metadata.name) }, store, runContext, registry, settings.extensionSettings), runController.signal);
                 runRecord.execution = execution;
                 await eventPublisher.runStarted(store, checked.metadata);
                 const finish = execution.result.then(async (value) => {
@@ -1813,9 +1791,6 @@ async function handleTurnInput(store, handle, turn) {
     }
     return target;
 }
-function displayAgentName(label, role, model) {
-    return label ?? role ?? model.model;
-}
 function modelSpec(value, fallback) {
     try {
         const parsed = parseModelReference(value);

package/dist/src/index.d.ts

@@ -3,10 +3,9 @@ export * from "./package-identity.js";
 export { createToolTimingExtension, TOOL_TIMING_ENTRY_TYPE } from "./tool-timing.js";
 export type { ToolTimingEntry } from "./tool-timing.js";
 export * from "./utils.js";
-export { canonicalPath, sameFilesystemPath } from "./paths.js";
+export { canonicalPath, extensionIdentity, sameFilesystemPath } from "./paths.js";
 export * from "./budget.js";
 export * from "./validation.js";
-export * from "./roles.js";
 export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";