pi-extensible-workflows 0.3.2 → 1.0.0

package/src/index.ts

@@ -1,47 +1,80 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { fork, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, extname, join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, 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 * as acorn from "acorn";
 import { Script } from "node:vm";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
 import { copyToClipboard, getAgentDir, parseFrontmatter, highlightCode, SessionManager, truncateToVisualLines, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createNativeAgentSession, FairAgentScheduler, WorkflowAgentExecutor, type AgentActivity, type AgentAttempt, type AgentDefinition, type AgentProgress, type SessionFactory } from "./agent-execution.js";
+import { createNativeAgentSession, FairAgentScheduler, WorkflowAgentExecutor, type AgentActivity, type AgentAccounting, type AgentAttempt, type AgentBudgetHooks, type AgentDefinition, type AgentProgress, type AgentSetupHook, type RegisteredAgentSetupHook, type SessionFactory } from "./agent-execution.js";
 import { transcriptLines } from "./session-inspector.js";
 import { acquireSessionLease, listRunIds, RunStore, SessionLease, structuralPath as operationPath } from "./persistence.js";
 import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
 
-export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted"] as const;
+export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"] as const;
 export const AGENT_STATES = ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"] as const;
 export const WORKFLOW_ASYNC_STARTED_EVENT = "workflow:async-started";
 export const WORKFLOW_ASYNC_COMPLETE_EVENT = "workflow:async-complete";
+export const WORKFLOW_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";
+export const WORKFLOW_RUN_COMPLETED_EVENT = "workflow:run-completed";
+export const WORKFLOW_RUN_FAILED_EVENT = "workflow:run-failed";
+export const WORKFLOW_AGENT_STATE_CHANGED_EVENT = "workflow:agent-state-changed";
+export const WORKFLOW_PHASE_CHANGED_EVENT = "workflow:phase-changed";
+export const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpoint-state-changed";
+export const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
+export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 const SETTLED_AGENT_STATES: ReadonlySet<AgentState> = new Set(["completed", "failed", "cancelled"]);
 export const ERROR_CODES = [
-  "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
-  "RUN_LIMIT_EXCEEDED", "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID",
-  "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "INTERNAL_ERROR",
-] as const;
+  "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",
+  "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+  ] as const;
 
 export type RunState = (typeof RUN_STATES)[number];
 export type AgentState = (typeof AGENT_STATES)[number];
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export type JsonSchema = { [key: string]: JsonValue };
-
+export type BudgetDimension = "tokens" | "costUsd" | "durationMs" | "agentLaunches";
+export interface BudgetLimits { soft?: number; hard?: number }
+export type WorkflowBudget = Partial<Record<BudgetDimension, BudgetLimits>>;
+export type WorkflowBudgetPatch = Partial<Record<BudgetDimension, BudgetLimits | { soft?: number | null; hard?: number | null } | null>>;
+export interface WorkflowBudgetUsage { tokens: number; costUsd: number; durationMs: number; agentLaunches: number }
+export type BudgetEventType = "soft_crossed" | "hard_overrun" | "hard_exhausted" | "adjustment_requested" | "adjustment_approved" | "adjustment_rejected";
+export interface BudgetEvent { type: BudgetEventType; budgetVersion: number; dimensions: readonly BudgetDimension[]; usage: WorkflowBudgetUsage; limits: WorkflowBudget; at: number; proposalId?: string; previous?: WorkflowBudget; proposed?: WorkflowBudget }
+export interface BudgetApprovalRequest { kind: "budget"; proposalId: string; runId: string; consumed: WorkflowBudgetUsage; previous: WorkflowBudget; proposed: WorkflowBudget; budgetVersion: number }
 export interface WorkflowErrorShape { code: WorkflowErrorCode; message: string }
+export interface WorkflowEventBase { runId: string; sessionId: string; workflowName: string; cwd: string; runDirectory: string; timestamp: number }
+export type WorkflowRunStartedEvent = WorkflowEventBase;
+export type WorkflowRunResumedEvent = WorkflowEventBase;
+export interface WorkflowRunStateChangedEvent extends WorkflowEventBase { previousState: RunState; state: RunState; reason?: string; errorCode?: WorkflowErrorCode }
+export interface WorkflowRunCompletedEvent extends WorkflowEventBase { resultPath: string }
+export interface WorkflowRunFailedEvent extends WorkflowEventBase { error: WorkflowErrorShape }
+export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase { agentId: string; displayLabel: string; role?: string; structuralPath: readonly string[]; parentId?: string; parentBreadcrumb?: string; worktreeOwner?: string; previousState?: AgentState; state: AgentState; attempt: number }
+export interface WorkflowPhaseChangedEvent extends WorkflowEventBase { previousPhase?: string; phase: string }
+export type WorkflowCheckpointState = "awaiting" | "approved" | "rejected";
+export interface WorkflowCheckpointStateChangedEvent extends WorkflowEventBase { name: string; state: WorkflowCheckpointState }
+export interface WorkflowBudgetEvent extends WorkflowEventBase { type: BudgetEventType; budgetVersion: number; dimensions: readonly BudgetDimension[]; usage: WorkflowBudgetUsage; limits: WorkflowBudget; proposalId?: string; previous?: WorkflowBudget; proposed?: WorkflowBudget }
 export interface ModelSpec { provider: string; model: string; thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" }
 export interface WorkflowMetadata { name: string; description?: string }
-export interface WorkflowSettings { concurrency: number; maxAgentLaunches: number }
-export interface AgentAttemptSummary { attempt: number; sessionId: string; sessionFile: string; error?: { code: string; message: string }; accounting: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number } }
-export interface AgentRecord { id: string; name: string; label?: string; path: string; state: AgentState; parentId?: string; parentBreadcrumb?: string; role?: string; model: ModelSpec; tools: readonly string[]; attempts: number; attemptDetails?: readonly AgentAttemptSummary[]; accounting?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; toolCalls?: readonly { id: string; name: string; state: "running" | "completed" | "failed" }[]; activity?: AgentActivity | undefined }
-export interface RunRecord { id: string; workflowName: string; cwd: string; sessionId: string; state: RunState; phase?: string; agents: readonly AgentRecord[]; error?: WorkflowErrorShape }
-const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 2;
-export interface LaunchSnapshot { identityVersion?: number; script: string; args: JsonValue; metadata: WorkflowMetadata; settings: WorkflowSettings; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[]; roles?: Readonly<Record<string, AgentDefinition>>; projectRoles?: readonly string[]; schemas: readonly JsonSchema[] }
-export interface PreflightCapabilities { models: ReadonlySet<string>; tools: ReadonlySet<string>; agentTypes: ReadonlySet<string> }
+export interface WorkflowSettings { concurrency: number; modelAliases?: Readonly<Record<string, string>>; disabledAgentResources?: Readonly<AgentResourceExclusions> }
+export interface AgentResourceExclusions { skills: readonly string[]; extensions: readonly string[] }
+export interface AgentResourcePolicy { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: AgentResourceExclusions; project: AgentResourceExclusions; effective: AgentResourceExclusions; unmatchedSkills: string[]; unmatchedExtensions: string[] }
+export interface AgentSetupSummary { hookNames: readonly string[]; model: ModelSpec; tools: readonly string[]; cwd: string; disabledAgentResources?: { skills: readonly string[]; extensions: readonly string[]; unmatchedSkills: readonly string[]; unmatchedExtensions: readonly string[] } }
+export interface AgentAttemptSummary { attempt: number; sessionId: string; sessionFile: string; error?: { code: string; message: string }; accounting: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; setup?: AgentSetupSummary }
+export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase { owner: string; branch: string; path: string; base: string }
+export interface AgentRecord { id: string; name: string; label?: string; path: string; state: AgentState; parentId?: string; structuralPath?: readonly string[]; parentBreadcrumb?: string; worktreeOwner?: string; role?: string; requestedModel?: string; model: ModelSpec; tools: readonly string[]; attempts: number; attemptDetails?: readonly AgentAttemptSummary[]; accounting?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number }; toolCalls?: readonly { id: string; name: string; state: "running" | "completed" | "failed" }[]; activity?: AgentActivity | undefined }
+export interface WorkflowRunEvent { type: "warning"; message: string }
+export interface RunRecord { id: string; workflowName: string; cwd: string; sessionId: string; state: RunState; phase?: string; agents: readonly AgentRecord[]; error?: WorkflowErrorShape; budget?: WorkflowBudget; budgetVersion?: number; usage?: WorkflowBudgetUsage; budgetEvents?: readonly BudgetEvent[]; events?: readonly WorkflowRunEvent[] }
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
+export interface LaunchSnapshot { identityVersion?: number; script: string; args: JsonValue; metadata: WorkflowMetadata; settings: WorkflowSettings; budget?: WorkflowBudget; settingsPath?: string; modelAliases?: Readonly<Record<string, string>>; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[]; roles?: Readonly<Record<string, AgentDefinition>>; projectRoles?: readonly string[]; schemas: readonly JsonSchema[] }
+export interface PreflightCapabilities { models: ReadonlySet<string>; tools: ReadonlySet<string>; agentTypes: ReadonlySet<string>; modelAliases?: Readonly<Record<string, string>>; knownModels?: ReadonlySet<string>; settingsPath?: string; skipModelAvailability?: boolean }
 export interface PreflightResult { metadata: WorkflowMetadata; referenced: { phases: readonly string[]; models: readonly string[]; tools: readonly string[]; agentTypes: readonly string[] }; schemas: readonly JsonSchema[]; dynamicAgentRoles: boolean }
 export interface WorkflowOrchestrationContext {
   agent: (...args: readonly unknown[]) => Promise<JsonValue>;
@@ -58,7 +91,7 @@ export interface WorkflowFunctionContext extends WorkflowOrchestrationContext {
 export interface WorkflowFunction { description: string; input: JsonSchema; output: JsonSchema; run: (input: Readonly<Record<string, JsonValue>>, context: Readonly<WorkflowFunctionContext>) => Promise<JsonValue> | JsonValue }
 export interface WorkflowVariable { description: string; schema: JsonSchema; resolve: (run: Readonly<WorkflowRunContext>) => Promise<JsonValue> | JsonValue }
 export interface WorkflowScriptDefinition { description: string; script: string }
-export interface WorkflowExtension { namespace: string; version: string; headline: string; description: string; functions?: Readonly<Record<string, WorkflowFunction>>; variables?: Readonly<Record<string, WorkflowVariable>>; workflows?: Readonly<Record<string, WorkflowScriptDefinition>> }
+export interface WorkflowExtension { version: string; headline: string; description: string; functions?: Readonly<Record<string, WorkflowFunction>>; variables?: Readonly<Record<string, WorkflowVariable>>; workflows?: Readonly<Record<string, WorkflowScriptDefinition>>; agentSetupHooks?: Readonly<Record<string, AgentSetupHook>> }
 export interface WorkflowJournal { get(path: string): JsonValue | undefined; put(path: string, value: JsonValue): void }
 
 export class WorkflowError extends Error {
@@ -86,6 +119,7 @@ function workflowDetail(message: string): string {
 }
 
 const WORKFLOW_ERROR_PROSE: Record<WorkflowErrorCode, (detail: string) => string> = {
+  CONFIG_ERROR: (detail) => `The workflow configuration is invalid: ${detail}.`,
   INVALID_SETTINGS: (detail) => `The workflow settings are invalid: ${detail}.`,
   INVALID_SYNTAX: (detail) => `The workflow source is invalid: ${detail}.`,
   INVALID_METADATA: (detail) => `The workflow metadata is invalid: ${detail}.`,
@@ -97,7 +131,6 @@ const WORKFLOW_ERROR_PROSE: Record<WorkflowErrorCode, (detail: string) => string
   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_LIMIT_EXCEEDED: (detail) => `The workflow exceeded its agent launch limit: ${detail.replace(/^Run\s+exceeded\s+/i, "")}.`,
   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}.`,
   AGENT_TIMEOUT: (detail) => `The workflow agent timed out: ${detail}.`,
@@ -107,6 +140,7 @@ const WORKFLOW_ERROR_PROSE: Record<WorkflowErrorCode, (detail: string) => string
   WORKER_UNRESPONSIVE: (detail) => `The workflow worker stopped responding: ${detail}.`,
   WORKTREE_FAILED: (detail) => `The workflow worktree operation failed: ${detail}.`,
   RESUME_INCOMPATIBLE: (detail) => `The workflow cannot resume this run: ${detail}.`,
+  BUDGET_EXHAUSTED: (detail) => `The workflow budget was exhausted: ${detail}.`,
   INTERNAL_ERROR: (detail) => `The workflow encountered an internal error: ${detail}.`,
 };
 export function formatWorkflowFailure(error: unknown): string {
@@ -133,13 +167,12 @@ function mainAgentError(error: unknown): WorkflowError {
   return presented;
 }
 
-
 export class RunLifecycle {
   #state: RunState;
   #active = 0;
   #waiters: Array<() => void> = [];
 
-  constructor(state: RunState = "running", private readonly changed?: (state: RunState) => void | Promise<void>) { this.#state = state; }
+  constructor(state: RunState = "running", private readonly changed?: (state: RunState, previousState: RunState, reason?: string) => void | Promise<void>) { this.#state = state; }
   get state(): RunState { return this.#state; }
 
   async enter(): Promise<void> {
@@ -150,31 +183,31 @@ export class RunLifecycle {
 
   async leave(): Promise<void> {
     if (this.#active > 0) this.#active -= 1;
-    if (this.#state === "pausing" && this.#active === 0) await this.#set("paused");
+    if (this.#state === "pausing" && this.#active === 0) await this.#set("paused", "pause");
   }
 
   async enterAwaitingInput(): Promise<void> {
     while (this.#state === "pausing" || this.#state === "paused") await new Promise<void>((resolve) => { this.#waiters.push(resolve); });
     if (this.#state === "awaiting_input") return;
     if (this.#state !== "running") throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot await input for ${this.#state} run`);
-    await this.#set("awaiting_input");
+    await this.#set("awaiting_input", "awaiting_input");
   }
 
   async resolveAwaitingInput(): Promise<void> {
     if (this.#state !== "awaiting_input") return;
-    await this.#set("running");
+    await this.#set("running", "checkpoint_resolved");
     for (const resolve of this.#waiters.splice(0)) resolve();
   }
 
   async pause(): Promise<void> {
     if (this.#state !== "running") throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot pause ${this.#state} run`);
-    await this.#set("pausing");
-    if (this.#active === 0) await this.#set("paused");
+    await this.#set("pausing", "pause");
+    if (this.#active === 0) await this.#set("paused", "pause");
   }
 
   async resume(): Promise<void> {
-    if (this.#state !== "paused" && this.#state !== "interrupted") throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot resume ${this.#state} run`);
-    await this.#set("running");
+    if (this.#state !== "paused" && this.#state !== "interrupted" && this.#state !== "budget_exhausted") throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot resume ${this.#state} run`);
+    await this.#set("running", "resume");
     for (const resolve of this.#waiters.splice(0)) resolve();
   }
 
@@ -184,33 +217,209 @@ export class RunLifecycle {
     await this.enter();
   }
 
-  async terminal(state: "completed" | "failed" | "stopped" | "interrupted"): Promise<void> {
+  async terminal(state: "completed" | "failed" | "stopped" | "interrupted" | "budget_exhausted", reason?: string): Promise<void> {
     if (["completed", "failed", "stopped"].includes(this.#state)) throw new WorkflowError("RESUME_INCOMPATIBLE", `${this.#state} runs are terminal`);
-    await this.#set(state);
+    await this.#set(state, reason ?? state);
     for (const resolve of this.#waiters.splice(0)) resolve();
   }
 
-  async #set(state: RunState): Promise<void> { this.#state = state; await this.changed?.(state); }
+  async #set(state: RunState, reason?: string): Promise<void> {
+    const previousState = this.#state;
+    this.#state = state;
+    await this.changed?.(state, previousState, reason);
+  }
 }
 
-export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ concurrency: 8, maxAgentLaunches: 1000 });
+export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ concurrency: 8 });
 
 function fail(code: WorkflowErrorCode, message: string): never { throw new WorkflowError(code, message); }
 function object(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function nonNegativeInteger(value: unknown): value is number { return Number.isInteger(value) && (value as number) >= 0; }
+function nonNegativeFinite(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+export function validateBudget(value: unknown): WorkflowBudget | undefined {
+  if (value === undefined) return undefined;
+  if (!object(value)) fail("INVALID_METADATA", "budget must be an object");
+  const result: WorkflowBudget = {};
+  for (const [dimension, raw] of Object.entries(value)) {
+    if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension)) fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+    if (!object(raw)) fail("INVALID_METADATA", `${dimension} budget must be an object`);
+    if (Object.keys(raw).some((key) => key !== "soft" && key !== "hard")) fail("INVALID_METADATA", `${dimension} budget has an unknown limit`);
+    const isCost = dimension === "costUsd";
+    for (const key of ["soft", "hard"] as const) if (raw[key] !== undefined && !(isCost ? nonNegativeFinite(raw[key]) : nonNegativeInteger(raw[key]))) fail("INVALID_METADATA", `${dimension}.${key} must be a non-negative ${isCost ? "finite number" : "integer"}`);
+    if (raw.soft !== undefined && raw.soft !== null && raw.hard !== undefined && raw.hard !== null && raw.soft >= raw.hard) fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+    const limits: BudgetLimits = {};
+    if (raw.soft !== undefined) limits.soft = raw.soft as number;
+    if (raw.hard !== undefined) limits.hard = raw.hard as number;
+    if (Object.keys(limits).length) (result as Record<string, BudgetLimits>)[dimension] = limits;
+  }
+  return Object.freeze(result);
+}
+export function validateBudgetPatch(value: unknown): WorkflowBudgetPatch {
+  if (!object(value)) fail("INVALID_METADATA", "budget patch must be an object");
+  const result: WorkflowBudgetPatch = {};
+  for (const [dimension, raw] of Object.entries(value)) {
+    if (!["tokens", "costUsd", "durationMs", "agentLaunches"].includes(dimension)) fail("INVALID_METADATA", `Unknown budget dimension: ${dimension}`);
+    if (raw === null) { (result as Record<string, null>)[dimension] = null; continue; }
+    if (!object(raw) || Object.keys(raw).some((key) => key !== "soft" && key !== "hard")) fail("INVALID_METADATA", `${dimension} budget patch must contain only soft and hard`);
+    const limits: { soft?: number | null; hard?: number | null } = {};
+    for (const key of ["soft", "hard"] as const) if (Object.prototype.hasOwnProperty.call(raw, key)) {
+      if (raw[key] === null) limits[key] = null;
+      else { const checked = validateBudget({ [dimension]: { [key]: raw[key] } })?.[dimension as BudgetDimension]; if (checked?.[key] !== undefined) limits[key] = checked[key]; }
+    }
+    if (limits.soft !== null && limits.hard !== null && limits.soft !== undefined && limits.hard !== undefined && limits.soft >= limits.hard) fail("INVALID_METADATA", `${dimension}.soft must be less than hard`);
+    (result as Record<string, { soft?: number | null; hard?: number | null }>)[dimension] = limits;
+  }
+  return result;
+}
+function budgetUsage(value?: Partial<WorkflowBudgetUsage>): WorkflowBudgetUsage { return { tokens: value?.tokens ?? 0, costUsd: value?.costUsd ?? 0, durationMs: value?.durationMs ?? 0, agentLaunches: value?.agentLaunches ?? 0 }; }
+export class WorkflowBudgetRuntime {
+  readonly #now: () => number;
+  readonly #onChange: (() => void) | undefined;
+  readonly #injected = new Set<string>();
+  readonly #seen = new Set<string>();
+  #active: boolean;
+  #activeSince: number | undefined;
+  #usage: WorkflowBudgetUsage;
+  #events: BudgetEvent[];
+  #turnAccounting?: { input: number; output: number; cost: number };
+  constructor(readonly budget: WorkflowBudget | undefined, readonly version = 1, usage?: Partial<WorkflowBudgetUsage>, events: readonly BudgetEvent[] = [], options: { now?: () => number; onChange?: () => void; active?: boolean } = {}) {
+    this.#now = options.now ?? (() => Date.now());
+    this.#onChange = options.onChange;
+    this.#active = options.active ?? true;
+    this.#activeSince = this.#active ? this.#now() : undefined;
+    this.#usage = budgetUsage(usage);
+    this.#events = [...events];
+    for (const event of events) if (event.budgetVersion === version) this.#seen.add(event.type);
+  }
+  get usage(): WorkflowBudgetUsage { this.#syncDuration(); return { ...this.#usage }; }
+  get events(): readonly BudgetEvent[] { return this.#events; }
+  get hardExhausted(): boolean { return this.#events.some((event) => event.type === "hard_exhausted" && event.budgetVersion === this.version); }
+  checkAgentLaunch(): void { this.#checkHard(["agentLaunches"]); }
+  beforeAttempt(): void { this.#checkHard(["agentLaunches"]); this.#usage.agentLaunches += 1; this.#evaluate(); }
+  beforeTurn(): void { this.#syncDuration(); this.#evaluate(); this.#checkHard(["tokens", "costUsd", "durationMs"]); }
+  afterTurn(accounting: AgentAccounting, final: boolean): void { this.#syncDuration(); this.#applyTurn(accounting, final, this.#turnAccounting); this.#turnAccounting = { input: accounting.input, output: accounting.output, cost: accounting.cost }; }
+  #applyTurn(accounting: AgentAccounting, final: boolean, previous = { input: 0, output: 0, cost: 0 }): void {
+    this.#usage.tokens += Math.max(0, accounting.input - previous.input) + Math.max(0, accounting.output - previous.output);
+    this.#usage.costUsd += Math.max(0, accounting.cost - previous.cost);
+    this.#evaluate();
+    if (!final) this.#checkHard(["tokens", "costUsd", "durationMs"]);
+  }
+  instruction(agentId = "agent"): string | undefined {
+    if (!this.#hasSoftCrossed() || this.#injected.has(agentId)) return undefined;
+    this.#injected.add(agentId);
+    return `The workflow budget soft limit has been reached. Finish the requested output now, preserving any required output schema. Current usage: ${JSON.stringify(this.usage)}. Do not start additional model work unless it is required to produce the final requested result.`;
+  }
+  forAgent(agentId: string): AgentBudgetHooks {
+    let attempt = 0;
+    let previous: { input: number; output: number; cost: number } | undefined;
+    return {
+      beforeAttempt: () => { attempt += 1; previous = undefined; this.beforeAttempt(); },
+      beforeTurn: () => { this.beforeTurn(); },
+      afterTurn: (accounting, final) => { this.#applyTurn(accounting, final, previous); previous = { input: accounting.input, output: accounting.output, cost: accounting.cost }; },
+      instruction: () => this.instruction(`${agentId}:${String(attempt + 1)}`),
+    };
+  }
+  transition(state: RunState): void {
+    const active = state === "running";
+    if (active === this.#active) return;
+    if (active) { this.#active = true; this.#activeSince = this.#now(); }
+    else { this.#syncDuration(); this.#evaluate(); this.#active = false; this.#activeSince = undefined; }
+    this.#onChange?.();
+  }
+  #syncDuration(): void { if (this.#active && this.#activeSince !== undefined) { const now = this.#now(); this.#usage.durationMs += Math.max(0, now - this.#activeSince); this.#activeSince = now; } }
+  #hasSoftCrossed(): boolean { return !!this.budget && (Object.entries(this.budget) as [BudgetDimension, BudgetLimits][]).some(([dimension, limits]) => limits.soft !== undefined && this.#usage[dimension] >= limits.soft); }
+  #checkHard(dimensions: readonly BudgetDimension[]): void {
+    const exhausted = dimensions.filter((dimension) => { const hard = this.budget?.[dimension]?.hard; return hard !== undefined && this.#usage[dimension] >= hard; });
+    if (!exhausted.length) return;
+    this.#record("hard_exhausted", exhausted);
+    const detail = exhausted.map((dimension) => `${dimension} usage=${String(this.#usage[dimension])} hard=${String(this.budget?.[dimension]?.hard)}`).join(", ");
+    throw new WorkflowError("BUDGET_EXHAUSTED", `Budget version ${String(this.version)} exhausted: ${detail}`);
+  }
+  #evaluate(): void {
+    const budget = this.budget;
+    if (!budget) return;
+    const soft = (Object.keys(budget) as BudgetDimension[]).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.soft !== undefined && this.#usage[dimension] >= limits.soft; });
+    if (soft.length) this.#record("soft_crossed", soft);
+    const overrun = (Object.keys(budget) as BudgetDimension[]).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && this.#usage[dimension] > limits.hard; });
+    if (overrun.length) this.#record("hard_overrun", overrun);
+  }
+  #record(type: BudgetEvent["type"], dimensions: readonly BudgetDimension[]): void { if (this.#seen.has(type)) return; this.#seen.add(type); this.#events.push({ type, budgetVersion: this.version, dimensions: [...dimensions], usage: this.usage, limits: structuredClone(this.budget ?? {}), at: this.#now() }); this.#onChange?.(); }
+  recordEvent(event: BudgetEvent): void { this.#events.push(structuredClone(event)); }
+  snapshot(): { usage: WorkflowBudgetUsage; budgetEvents: readonly BudgetEvent[] } { return { usage: this.usage, budgetEvents: [...this.#events] }; }
+}
+export function mergeBudget(budget: WorkflowBudget | undefined, patch: WorkflowBudgetPatch): WorkflowBudget | undefined {
+  const merged: WorkflowBudget = structuredClone(budget ?? {});
+  for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"] as const) if (Object.prototype.hasOwnProperty.call(patch, dimension)) {
+    const value = patch[dimension];
+    if (value === null) { Reflect.deleteProperty(merged, dimension); continue; }
+    const next: BudgetLimits = { ...(merged[dimension] ?? {}) };
+    for (const key of ["soft", "hard"] as const) if (value && Object.prototype.hasOwnProperty.call(value, key)) { const limit = value[key]; if (limit === null) Reflect.deleteProperty(next, key); else if (limit !== undefined) next[key] = limit; }
+    if (Object.keys(next).length) (merged as Record<string, BudgetLimits>)[dimension] = next; else Reflect.deleteProperty(merged, dimension);
+  }
+  return validateBudget(merged);
+}
+export function budgetRelaxed(previous: WorkflowBudget | undefined, next: WorkflowBudget | undefined): boolean { for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"] as const) { const oldLimit = previous?.[dimension]; const newLimit = next?.[dimension]; for (const key of ["soft", "hard"] as const) if ((oldLimit?.[key] !== undefined && newLimit?.[key] === undefined) || (oldLimit?.[key] !== undefined && newLimit?.[key] !== undefined && newLimit[key] > oldLimit[key])) return true; } return false; }
+export function exhaustedBudgetDimensions(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): BudgetDimension[] {
+  if (!budget) return [];
+  return (Object.keys(budget) as BudgetDimension[]).filter((dimension) => { const limits = budget[dimension]; return limits !== undefined && limits.hard !== undefined && usage[dimension] >= limits.hard; });
+}
+export function resumeBudgetAllowed(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): boolean { return exhaustedBudgetDimensions(budget, usage).length === 0; }
 function positiveInteger(value: unknown): value is number { return Number.isInteger(value) && (value as number) > 0; }
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const MODEL_ALIAS_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
 export function parseModelReference(value: string): ModelSpec {
   const match = /^([^/:\s]+)\/([^:\s]+)(?::([^:\s]+))?$/.exec(value);
   if (!match?.[1] || !match[2]) fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
   const thinking = match[3];
-  if (thinking && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinking)) fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
+  if (thinking && !THINKING_LEVELS.includes(thinking as (typeof THINKING_LEVELS)[number])) fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
   return { provider: match[1], model: match[2], ...(thinking ? { thinking: thinking as NonNullable<ModelSpec["thinking"]> } : {}) };
 }
 
-function modelCapability(value: string): string {
-  const parsed = parseModelReference(value);
+function aliasError(message: string, settingsPath: string): never { fail("CONFIG_ERROR", `${message} (settings: ${settingsPath})`); }
+export function validateModelAliases(value: unknown, settingsPath = "workflow settings"): Readonly<Record<string, string>> {
+  if (!object(value)) aliasError("modelAliases must be an object", settingsPath);
+  const aliases: Record<string, string> = {};
+  for (const [name, target] of Object.entries(value)) {
+    if (!MODEL_ALIAS_NAME.test(name)) aliasError(`Invalid model alias name: ${name}`, settingsPath);
+    if (typeof target !== "string" || !target.trim()) aliasError(`Invalid model alias target for ${name}`, settingsPath);
+    try { parseModelReference(target); } catch (error) { aliasError(`Invalid model alias target for ${name}: ${errorText(error)}`, settingsPath); }
+    aliases[name] = target;
+  }
+  return Object.freeze(aliases);
+}
+
+function unknownModel(value: string, target: string | undefined, settingsPath?: string): never {
+  const resolved = target ? ` resolved to ${target}` : "";
+  const path = settingsPath ? ` (settings: ${settingsPath})` : "";
+  fail("UNKNOWN_MODEL", `Unknown model${target ? " alias" : ""} ${value}${resolved}${path}`);
+}
+
+export function resolveModelReference(value: string, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec {
+  const target = Object.prototype.hasOwnProperty.call(aliases, value) ? aliases[value] : undefined;
+  if (target !== undefined) {
+    try { return parseModelReference(target); } catch { unknownModel(value, target, settingsPath); }
+  }
+  if (value.includes("/")) return parseModelReference(value);
+  const match = /^([^:\s]+)(?::([^:\s]+))?$/.exec(value);
+  const thinking = match?.[2];
+  if (!match?.[1] || thinking && !THINKING_LEVELS.includes(thinking as (typeof THINKING_LEVELS)[number])) unknownModel(value, undefined, settingsPath);
+  const candidates = [...(knownModels ?? [])].filter((model) => model.slice(model.indexOf("/") + 1) === match[1]);
+  if (candidates.length === 1) {
+    const parsed = parseModelReference(candidates[0] as string);
+    return thinking ? { ...parsed, thinking: thinking as NonNullable<ModelSpec["thinking"]> } : parsed;
+  }
+  unknownModel(value, undefined, settingsPath);
+}
+
+function modelCapability(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string {
+  const parsed = resolveModelReference(value, aliases, knownModels, settingsPath);
   return `${parsed.provider}/${parsed.model}`;
 }
 
+function aliasDrift(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): string[] {
+  return [...new Set([...Object.keys(previous), ...Object.keys(current)])].sort().flatMap((name) => previous[name] === current[name] ? [] : [`${name}: ${previous[name] ?? "(missing)"} -> ${current[name] ?? "(missing)"}`]);
+}
+
 export interface CheckpointInput { name: string; prompt: string; context: JsonValue }
 export function validateCheckpoint(value: unknown): CheckpointInput {
   if (!object(value) || Object.keys(value).some((key) => !["name", "prompt", "context"].includes(key)) || typeof value.name !== "string" || value.name.trim() === "" || typeof value.prompt !== "string" || !jsonValue(value.context)) fail("INVALID_METADATA", "checkpoint requires only name, prompt, and JSON context");
@@ -220,25 +429,79 @@ export function validateCheckpoint(value: unknown): CheckpointInput {
 }
 
 export function workflowSettingsPath(agentDir = getAgentDir()): string { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
+export function workflowProjectSettingsPath(cwd: string): string { return join(cwd, ".pi", ROLE_DIRECTORY, "settings.json"); }
+const EMPTY_AGENT_RESOURCE_EXCLUSIONS: AgentResourceExclusions = Object.freeze({ skills: [], extensions: [] });
+function normalizedResourcePath(value: string, settingsPath: string): string {
+  let expanded = value === "~" ? homedir() : value.startsWith("~/") || value.startsWith("~\\") ? join(homedir(), value.slice(2)) : value;
+  if (expanded.startsWith("file://")) expanded = fileURLToPath(expanded);
+  const resolved = resolve(dirname(settingsPath), expanded);
+  try { return realpathSync(resolved); } catch { return resolved; }
+}
+export function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions {
+  return { skills: [...new Set(values.flatMap((value) => value?.skills ?? []))], extensions: [...new Set(values.flatMap((value) => value?.extensions ?? []))] };
+}
+function validateAgentResourceExclusions(value: unknown, settingsPath: string, errorCode: "INVALID_SETTINGS" | "INVALID_METADATA" = "INVALID_SETTINGS"): AgentResourceExclusions | undefined {
+  if (value === undefined) return undefined;
+  const base = `${settingsPath}.disabledAgentResources`;
+  if (!object(value)) fail(errorCode, `${base} must be an object`);
+  for (const key of Object.keys(value)) if (key !== "skills" && key !== "extensions") fail(errorCode, `${base}.${key} is not supported`);
+  const normalized: { skills: string[]; extensions: string[] } = { skills: [], extensions: [] };
+  for (const kind of ["skills", "extensions"] as const) {
+    const entries = value[kind];
+    if (entries === undefined) continue;
+    if (!Array.isArray(entries)) fail(errorCode, `${base}.${kind} must be an array`);
+    const seen = new Set<string>();
+    for (const [index, entry] of entries.entries()) {
+      if (typeof entry !== "string" || !entry.trim()) fail(errorCode, `${base}.${kind}[${String(index)}] must be a non-empty string`);
+      let selector = entry.trim();
+      if (kind === "extensions") {
+        try { selector = normalizedResourcePath(selector, settingsPath); } catch (error) { fail(errorCode, `${base}.${kind}[${String(index)}] must be a valid path: ${errorText(error)}`); }
+      }
+      if (!seen.has(selector)) { seen.add(selector); normalized[kind].push(selector); }
+    }
+  }
+  return Object.freeze({ skills: Object.freeze(normalized.skills), extensions: Object.freeze(normalized.extensions) });
+}
 export function loadSettings(path = workflowSettingsPath()): Readonly<WorkflowSettings> {
   let parsed: unknown;
   try { parsed = JSON.parse(readFileSync(path, "utf8")); }
   catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return DEFAULT_SETTINGS;
-    fail("INVALID_SETTINGS", `Invalid workflow settings: ${errorText(error)}`);
+    fail("CONFIG_ERROR", `Invalid workflow settings JSON at ${path}: ${errorText(error)}`);
   }
-  if (!object(parsed)) fail("INVALID_SETTINGS", "Workflow settings must be an object");
-  const allowed = new Set(["concurrency", "maxAgentLaunches"]);
+  if (!object(parsed)) fail("INVALID_SETTINGS", `Workflow settings at ${path} must be an object`);
+  const allowed = new Set(["concurrency", "modelAliases", "disabledAgentResources"]);
   const unknown = Object.keys(parsed).find((key) => !allowed.has(key));
-  if (unknown) fail("INVALID_SETTINGS", `Unknown workflow setting: ${unknown}`);
+  if (unknown) fail("INVALID_SETTINGS", `Unknown workflow setting at ${path}: ${unknown}`);
   const concurrency = parsed.concurrency === undefined ? DEFAULT_SETTINGS.concurrency : parsed.concurrency;
-  const maxAgentLaunches = parsed.maxAgentLaunches === undefined ? DEFAULT_SETTINGS.maxAgentLaunches : parsed.maxAgentLaunches;
-  if (!positiveInteger(concurrency) || concurrency > 16) fail("INVALID_SETTINGS", "concurrency must be an integer from 1 to 16");
-  if (!positiveInteger(maxAgentLaunches)) fail("INVALID_SETTINGS", "maxAgentLaunches must be a positive integer");
-  return Object.freeze({ concurrency, maxAgentLaunches });
+  if (!positiveInteger(concurrency) || concurrency > 16) fail("INVALID_SETTINGS", `${path}.concurrency must be an integer from 1 to 16`);
+  const modelAliases = parsed.modelAliases === undefined ? undefined : validateModelAliases(parsed.modelAliases, path);
+  const disabledAgentResources = validateAgentResourceExclusions(parsed.disabledAgentResources, path);
+  return Object.freeze({ concurrency, ...(modelAliases ? { modelAliases } : {}), ...(disabledAgentResources ? { disabledAgentResources } : {}) });
+}
+export function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath = workflowSettingsPath()): AgentResourcePolicy {
+  const projectSettingsPath = workflowProjectSettingsPath(cwd);
+  const global = loadSettings(globalSettingsPath).disabledAgentResources ?? EMPTY_AGENT_RESOURCE_EXCLUSIONS;
+  const project = projectTrusted ? loadSettings(projectSettingsPath).disabledAgentResources ?? EMPTY_AGENT_RESOURCE_EXCLUSIONS : EMPTY_AGENT_RESOURCE_EXCLUSIONS;
+  const effective = mergeAgentResourceExclusions(global, project);
+  return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [] };
+}
+export function saveModelAliases(path = workflowSettingsPath(), aliases: Readonly<Record<string, string>> = {}): void {
+  const normalized = validateModelAliases(aliases, path);
+  let parsed: Record<string, unknown> = {};
+  try {
+    loadSettings(path);
+    parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${String(process.pid)}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
 }
 
-export function parseRoleMarkdown(content: string, strict = false): AgentDefinition {
+export function parseRoleMarkdown(content: string, strict = false, rolePath?: string): AgentDefinition {
   if (!strict) {
     if (!content.startsWith("---\n")) return { prompt: content };
     const end = content.indexOf("\n---", 4);
@@ -264,12 +527,13 @@ export function parseRoleMarkdown(content: string, strict = false): AgentDefinit
   try { parsed = parseFrontmatter(content); }
   catch (error) { fail("INVALID_METADATA", `Invalid role frontmatter: ${errorText(error)}`); }
   if (!object(parsed.frontmatter)) fail("INVALID_METADATA", "Role frontmatter must be an object");
-  const { model, thinking, tools, description } = parsed.frontmatter;
+  const { model, thinking, tools, description, disabledAgentResources } = parsed.frontmatter;
   if (model !== undefined && (typeof model !== "string" || model.trim() === "")) fail("INVALID_METADATA", "Role model must be a non-empty string");
   if (thinking !== undefined && (typeof thinking !== "string" || !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinking))) fail("INVALID_METADATA", `Invalid role thinking level: ${typeof thinking === "string" ? thinking : typeof thinking}`);
   if (description !== undefined && (typeof description !== "string" || description.trim() === "" || description.length > 1024 || /[\r\n]/.test(description))) fail("INVALID_METADATA", "Role description must be a non-empty single-line string of at most 1024 characters");
   if (tools !== undefined && (!Array.isArray(tools) || tools.some((tool) => typeof tool !== "string" || tool.trim() === ""))) fail("INVALID_METADATA", "Role tools must be an array of non-empty strings");
-  return { prompt: parsed.body, ...(typeof description === "string" ? { description: description.trim() } : {}), ...(typeof model === "string" ? { model: model.trim() } : {}), ...(typeof thinking === "string" ? { thinking: thinking as NonNullable<AgentDefinition["thinking"]> } : {}), ...(Array.isArray(tools) ? { tools: tools.map((tool) => (tool as string).trim()) } : {}) };
+  const normalizedResources = validateAgentResourceExclusions(disabledAgentResources, rolePath ?? "<role>", "INVALID_METADATA");
+  return { prompt: parsed.body, ...(typeof description === "string" ? { description: description.trim() } : {}), ...(typeof model === "string" ? { model: model.trim() } : {}), ...(typeof thinking === "string" ? { thinking: thinking as NonNullable<AgentDefinition["thinking"]> } : {}), ...(Array.isArray(tools) ? { tools: tools.map((tool) => (tool as string).trim()) } : {}), ...(normalizedResources ? { disabledAgentResources: normalizedResources } : {}) };
 }
 
 const ROLE_DIRECTORY = "pi-extensible-workflows";
@@ -286,7 +550,7 @@ function readAgentDefinitions(dir: string): Record<string, AgentDefinition> {
   try {
     return Object.fromEntries(readdirSync(dir, { withFileTypes: true })
       .filter((entry) => entry.isFile() && extname(entry.name) === ".md")
-      .map((entry) => [basename(entry.name, ".md"), parseRoleMarkdown(readFileSync(join(dir, entry.name), "utf8"), true)]));
+      .map((entry) => { const path = join(dir, entry.name); return [basename(entry.name, ".md"), parseRoleMarkdown(readFileSync(path, "utf8"), true, path)]; }));
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
     throw error;
@@ -300,11 +564,17 @@ function readRoleDefinitions(dirs: readonly string[]): Record<string, AgentDefin
 export function loadAgentDefinitions(cwd: string, agentDir = getAgentDir(), projectTrusted = true): Readonly<Record<string, AgentDefinition>> {
   return deepFreeze({ ...readRoleDefinitions(workflowRoleDirectories(agentDir)), ...(projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(cwd, ".pi"))) : {}) });
 }
-function validateRolePolicies(definitions: Readonly<Record<string, AgentDefinition>>, roles: readonly string[], availableModels: ReadonlySet<string>, rootTools: ReadonlySet<string>): void {
+function validateRolePolicies(definitions: Readonly<Record<string, AgentDefinition>>, roles: readonly string[], availableModels: ReadonlySet<string>, rootTools: ReadonlySet<string>, aliases: Readonly<Record<string, string>> = {}, knownModels = availableModels, settingsPath?: string): void {
   for (const role of roles) {
     const definition = definitions[role];
     if (!definition) continue;
-    if (definition.model !== undefined && !availableModels.has(modelCapability(definition.model))) fail("UNKNOWN_MODEL", `Unknown model for role ${role}: ${definition.model}`);
+    if (definition.model !== undefined) {
+      const resolved = modelCapability(definition.model, aliases, knownModels, settingsPath);
+      if (!availableModels.has(resolved)) {
+        if (Object.prototype.hasOwnProperty.call(aliases, definition.model)) unknownModel(definition.model, resolved, settingsPath);
+        fail("UNKNOWN_MODEL", `Unknown model for role ${role}: ${resolved}`);
+      }
+    }
     const missingTool = (definition.tools ?? [...rootTools]).find((tool) => !rootTools.has(tool));
     if (missingTool) fail("UNKNOWN_TOOL", `Unknown tool for role ${role}: ${missingTool}`);
   }
@@ -346,7 +616,7 @@ function astNode(value: unknown): value is acorn.AnyNode {
 function workflowCalls(program: acorn.Program): WorkflowCall[] {
   const calls: WorkflowCall[] = [];
   const visit = (node: acorn.AnyNode): void => {
-    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) calls.push(node as WorkflowCall);
+    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) calls.push(node as WorkflowCall);
     for (const value of Object.values(node) as unknown[]) {
       if (Array.isArray(value)) {
         for (const child of value as unknown[]) if (astNode(child)) visit(child);
@@ -368,7 +638,7 @@ function workflowCallsWithStructure(program: acorn.Program): Array<{ call: Workf
       const key = node.key.type === "Identifier" ? node.key.name : node.key.type === "Literal" ? String(node.key.value) : undefined;
       if (scope?.key === null && key) current = { ...current, structure: [...current.structure.slice(0, -1), { ...scope, key }] };
     }
-    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) {
+    if (node.type === "CallExpression" && node.callee.type === "Identifier" && ["agent", "conversation", "parallel", "pipeline", "checkpoint", "phase", "withWorktree"].includes(node.callee.name)) {
       const call = node as WorkflowCall;
       const operation = call.callee.name as StaticWorkflowCall["kind"];
       const execution = operation === "parallel" ? "parallel" : operation === "pipeline" ? "sequential" : current.execution;
@@ -412,6 +682,7 @@ function hasIdentifier(node: acorn.AnyNode, name: string): boolean {
 }
 
 const INTERNAL_AGENT_NAME = "__pi_extensible_workflows_agent";
+const INTERNAL_CONVERSATION_NAME = "__pi_extensible_workflows_conversation";
 const INTERNAL_WORKTREE_NAME = "__pi_extensible_workflows_withWorktree";
 
 function callHasTrailingComma(source: string, call: WorkflowCall): boolean {
@@ -429,13 +700,14 @@ function instrumentWorkflow(script: string): string {
   if (!body.trim()) return body;
   const program = parseWorkflow(body);
   if (hasIdentifier(program, INTERNAL_AGENT_NAME)) fail("INVALID_METADATA", `${INTERNAL_AGENT_NAME} is reserved for workflow agent instrumentation`);
+  if (hasIdentifier(program, INTERNAL_CONVERSATION_NAME)) fail("INVALID_METADATA", `${INTERNAL_CONVERSATION_NAME} is reserved for workflow conversation instrumentation`);
   if (hasIdentifier(program, INTERNAL_WORKTREE_NAME)) fail("INVALID_METADATA", `${INTERNAL_WORKTREE_NAME} is reserved for workflow withWorktree instrumentation`);
-  const calls = workflowCalls(program).filter((call) => ["agent", "withWorktree"].includes(call.callee.name));
+  const calls = workflowCalls(program).filter((call) => ["agent", "conversation", "withWorktree"].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 : 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 : INTERNAL_WORKTREE_NAME },
       { start: call.end - 1, end: call.end - 1, text: `${hiddenArgument}${JSON.stringify(callSite)}` },
     ];
   }).sort((left, right) => right.start - left.start);
@@ -512,14 +784,14 @@ function validateSchema(schema: unknown, at = "schema"): asserts schema is JsonS
 }
 
 const AGENT_OPTION_KEYS = new Set(["label", "model", "thinking", "tools", "role", "outputSchema", "retries", "timeoutMs"]);
-function validateAgentOption(key: string, value: unknown): void {
+function validateAgentOption(key: string, value: unknown, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): void {
   switch (key) {
     case "label":
       if (typeof value !== "string" || !value.trim()) fail("INVALID_METADATA", "agent label must be a non-empty string");
       break;
     case "model":
-      if (typeof value !== "string") fail("INVALID_METADATA", "agent model must be a string");
-      parseModelReference(value);
+      if (typeof value !== "string" || !value.trim()) fail("INVALID_METADATA", "agent model must be a non-empty string");
+      if (aliases !== undefined) resolveModelReference(value, aliases, knownModels, settingsPath);
       break;
     case "thinking":
       if (typeof value !== "string" || !parseThinking(value)) fail("INVALID_METADATA", "agent thinking must be off, minimal, low, medium, high, xhigh, or max");
@@ -541,12 +813,9 @@ function validateAgentOption(key: string, value: unknown): void {
       break;
   }
 }
-
 function validateAgentOptions(value: unknown): Readonly<Record<string, JsonValue>> {
   if (!object(value) || !jsonValue(value)) fail("INVALID_METADATA", "agent options must be a JSON object");
-  const unknown = Object.keys(value).find((key) => !AGENT_OPTION_KEYS.has(key));
-  if (unknown) fail("INVALID_METADATA", `Unknown agent option: ${unknown}`);
-  for (const [key, option] of Object.entries(value)) validateAgentOption(key, option);
+  for (const [key, option] of Object.entries(value)) if (AGENT_OPTION_KEYS.has(key)) validateAgentOption(key, option);
   if (typeof value.role === "string" && ["model", "thinking", "tools"].some((key) => Object.prototype.hasOwnProperty.call(value, key))) fail("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
   return value;
 }
@@ -585,7 +854,7 @@ function staticValue(node: acorn.AnyNode | undefined): StaticValue {
 }
 
 export interface StaticWorkflowCall {
-  kind: "agent" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+  kind: "agent" | "conversation" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
   start: number;
   end: number;
   name: string | null;
@@ -617,7 +886,7 @@ export function inspectWorkflowScript(script: string): StaticWorkflowCall[] {
     const first = callArgument(call, 0);
     const options = callArgument(call, 1);
     const placement = { execution, structure };
-    if (kind === "agent") {
+    if (kind === "agent" || kind === "conversation") {
       const retries = staticValue(propertyNode(options, "retries"));
       const outputSchema = staticValue(propertyNode(options, "outputSchema"));
       const optionKeys = options?.type === "ObjectExpression" ? options.properties.flatMap((property) => {
@@ -626,7 +895,7 @@ export function inspectWorkflowScript(script: string): StaticWorkflowCall[] {
         return key ? [key] : [];
       }) : [];
       const knownOptions = Object.fromEntries(optionKeys.flatMap((key) => { const value = staticValue(propertyNode(options, key)); return value.known && jsonValue(value.value) ? [[key, value.value]] : []; })) as Record<string, JsonValue>;
-      const base = { ...placement, kind, start: call.start, end: call.end, name: null, prompt: staticString(first), model: staticString(propertyNode(options, "model")), label: staticString(propertyNode(options, "label")), role: staticString(propertyNode(options, "role")) };
+      const base = { ...placement, kind, start: call.start, end: call.end, name: kind === "conversation" ? staticString(first) : null, prompt: kind === "conversation" ? null : staticString(first), model: staticString(propertyNode(options, "model")), label: staticString(propertyNode(options, "label")), role: staticString(propertyNode(options, "role")) };
       return { ...base, ...(retries.known && typeof retries.value === "number" ? { retries: retries.value } : {}), ...(outputSchema.known && object(outputSchema.value) ? { outputSchema: outputSchema.value as JsonSchema } : {}), ...(optionKeys.length ? { options: knownOptions, optionKeys } : {}) };
     }
     if (kind === "checkpoint") return { ...placement, kind, start: call.start, end: call.end, name: staticString(propertyNode(first, "name")), prompt: staticString(propertyNode(first, "prompt")), model: null, role: null };
@@ -634,21 +903,14 @@ export function inspectWorkflowScript(script: string): StaticWorkflowCall[] {
   });
 }
 
-function validateStaticAgentOptions(node: acorn.AnyNode | undefined): void {
+function validateStaticAgentOptions(node: acorn.AnyNode | undefined, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): void {
   if (node?.type !== "ObjectExpression") return;
-  for (const property of node.properties) {
-    if (property.type === "SpreadElement" || property.computed) continue;
-    const key = property.key.type === "Identifier" ? property.key.name : property.key.type === "Literal" ? String(property.key.value) : undefined;
-    if (key && !AGENT_OPTION_KEYS.has(key)) fail("INVALID_METADATA", `Unknown agent option: ${key}`);
-  }
-  const role = propertyNode(node, "role");
-  if (role && ["model", "thinking", "tools"].some((key) => propertyNode(node, key) !== undefined)) fail("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
+  const options = staticValue(node);
+  if (options.known && object(options.value) && typeof options.value.role === "string" && ["model", "thinking", "tools"].some((key) => Object.prototype.hasOwnProperty.call(options.value as Record<string, unknown>, key))) fail("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
   for (const key of AGENT_OPTION_KEYS) {
     const value = staticValue(propertyNode(node, key));
-    if (value.known) validateAgentOption(key, value.value);
+    if (value.known) validateAgentOption(key, value.value, aliases, knownModels, settingsPath);
   }
-  const options = staticValue(node);
-  if (options.known && object(options.value) && typeof options.value.role === "string" && ["model", "thinking", "tools"].some((key) => Object.prototype.hasOwnProperty.call(options.value as Record<string, unknown>, key))) fail("INVALID_METADATA", "Role agents must not specify model, thinking, or tools");
 }
 
 function validateStaticWithWorktree(call: WorkflowCall): void {
@@ -662,17 +924,19 @@ function validateStaticWithWorktree(call: WorkflowCall): void {
   }
 }
 
-export interface WorkflowCatalogFunction { name: string; namespace: string; version: string; headline: string; extensionDescription: string; description: string; input: JsonSchema; output: JsonSchema }
-export interface WorkflowCatalogVariable { name: string; namespace: string; version: string; headline: string; extensionDescription: string; description: string; schema: JsonSchema }
-export interface WorkflowCatalogWorkflow { name: string; namespace: string; version: string; headline: string; extensionDescription: string; description: string }
-export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; variables: readonly WorkflowCatalogVariable[]; workflows: readonly WorkflowCatalogWorkflow[] }
-const RESERVED_GLOBALS = new Set(["agent", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
+export interface WorkflowCatalogFunction { name: string; version: string; headline: string; extensionDescription: string; description: string; input: JsonSchema; output: JsonSchema }
+export interface WorkflowCatalogVariable { name: string; version: string; headline: string; extensionDescription: string; description: string; schema: JsonSchema }
+export interface WorkflowCatalogWorkflow { name: string; version: string; headline: string; extensionDescription: string; description: string }
+export interface WorkflowCatalog { functions: readonly WorkflowCatalogFunction[]; variables: readonly WorkflowCatalogVariable[]; workflows: readonly WorkflowCatalogWorkflow[]; modelAliases?: Readonly<Record<string, string>> }
+const RESERVED_GLOBALS = new Set(["agent", "conversation", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 
 export class WorkflowRegistry {
-  readonly #extensions = new Map<string, Readonly<WorkflowExtension>>();
+  readonly #extensions = new Set<Readonly<WorkflowExtension>>();
   readonly #globals = new Map<string, string>();
+  readonly #workflows = new Map<string, WorkflowScriptDefinition>();
+  readonly #hooks = new Map<string, RegisteredAgentSetupHook>();
   #frozen = false;
 
   get frozen(): boolean { return this.#frozen; }
@@ -680,89 +944,99 @@ export class WorkflowRegistry {
 
   register(extension: WorkflowExtension): void {
     if (this.#frozen) fail("REGISTRY_FROZEN", "Workflow extension registration is closed after session_start");
-    if (!object(extension) || Object.keys(extension).some((key) => !["namespace", "version", "headline", "description", "functions", "variables", "workflows"].includes(key)) || typeof extension.namespace !== "string" || typeof extension.version !== "string" || !IDENTIFIER.test(extension.namespace) || !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 namespace, semantic version, headline, and description");
-    if (this.#extensions.has(extension.namespace)) fail("DUPLICATE_NAME", `Workflow extension already registered: ${extension.namespace}`);
+    if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "functions", "variables", "workflows", "agentSetupHooks"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim() || typeof extension.description !== "string" || !extension.description.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version, headline, and description");
     const functions = extension.functions ?? {};
     const variables = extension.variables ?? {};
     const workflows = extension.workflows ?? {};
-    if (!object(functions) || !object(variables) || !object(workflows) || (Object.keys(functions).length === 0 && Object.keys(variables).length === 0 && Object.keys(workflows).length === 0)) fail("INVALID_METADATA", "Workflow extensions require functions, variables, or 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");
     const names = [...Object.keys(functions), ...Object.keys(variables)];
-    if (new Set(names).size !== names.length) fail("GLOBAL_COLLISION", `Global name collision inside ${extension.namespace}`);
+    if (new Set(names).size !== names.length) fail("GLOBAL_COLLISION", "Global name collision inside extension");
     for (const name of names) {
-      if (!IDENTIFIER.test(name) || name.startsWith("__pi_extensible_workflows_")) fail("INVALID_METADATA", `Invalid global name: ${extension.namespace}.${name}`);
+      if (!IDENTIFIER.test(name) || name.startsWith("__pi_extensible_workflows_")) fail("INVALID_METADATA", `Invalid global name: ${name}`);
       if (RESERVED_GLOBALS.has(name)) fail("GLOBAL_COLLISION", `Global name is reserved: ${name}`);
-      const owner = this.#globals.get(name);
-      if (owner) fail("GLOBAL_COLLISION", `Global name ${name} is already owned by ${owner}; cannot register ${extension.namespace}.${name}`);
+      if (this.#globals.has(name)) fail("GLOBAL_COLLISION", `Global name is already registered: ${name}`);
     }
     for (const [name, fn] of Object.entries(functions)) {
-      if (!object(fn) || Object.keys(fn).some((key) => !["description", "input", "output", "run"].includes(key)) || typeof fn.description !== "string" || !fn.description.trim() || typeof fn.run !== "function") fail("INVALID_METADATA", `Invalid workflow function: ${extension.namespace}.${name}`);
-      validateSchema(fn.input, `${extension.namespace}.${name} input`);
-      validateSchema(fn.output, `${extension.namespace}.${name} output`);
-      if (fn.input.type !== "object") fail("INVALID_SCHEMA", `${extension.namespace}.${name} input must describe one object`);
+      if (!object(fn) || Object.keys(fn).some((key) => !["description", "input", "output", "run"].includes(key)) || typeof fn.description !== "string" || !fn.description.trim() || typeof fn.run !== "function") fail("INVALID_METADATA", `Invalid workflow function: ${name}`);
+      validateSchema(fn.input, `${name} input`);
+      validateSchema(fn.output, `${name} output`);
+      if (fn.input.type !== "object") fail("INVALID_SCHEMA", `${name} input must describe one object`);
     }
     for (const [name, variable] of Object.entries(variables)) {
-      if (!object(variable) || Object.keys(variable).some((key) => !["description", "schema", "resolve"].includes(key)) || typeof variable.description !== "string" || !variable.description.trim() || typeof variable.resolve !== "function") fail("INVALID_METADATA", `Invalid workflow variable: ${extension.namespace}.${name}`);
-      validateSchema(variable.schema, `${extension.namespace}.${name} schema`);
+      if (!object(variable) || Object.keys(variable).some((key) => !["description", "schema", "resolve"].includes(key)) || typeof variable.description !== "string" || !variable.description.trim() || typeof variable.resolve !== "function") fail("INVALID_METADATA", `Invalid workflow variable: ${name}`);
+      validateSchema(variable.schema, `${name} schema`);
     }
     for (const [name, workflow] of Object.entries(workflows)) {
-      if (!IDENTIFIER.test(name) || !object(workflow) || Object.keys(workflow).some((key) => !["description", "script"].includes(key)) || typeof workflow.description !== "string" || !workflow.description.trim() || typeof workflow.script !== "string" || !workflow.script.trim()) fail("INVALID_METADATA", `Invalid workflow script: ${extension.namespace}.${name}`);
+      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);
     }
-    const stored = deepFreeze({ ...extension, functions, variables, workflows });
-    this.#extensions.set(extension.namespace, stored);
-    for (const name of names) this.#globals.set(name, `${extension.namespace}.${name}`);
+    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 });
+    this.#extensions.add(stored);
+    for (const name of names) this.#globals.set(name, name);
+    for (const [name, workflow] of Object.entries(workflows)) this.#workflows.set(name, workflow);
+    for (const [name, hook] of Object.entries(agentSetupHooks)) this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
   }
 
   workflow(name: string): WorkflowScriptDefinition {
-    const separator = name.indexOf(".");
-    if (separator <= 0 || separator !== name.lastIndexOf(".") || !IDENTIFIER.test(name.slice(0, separator)) || !IDENTIFIER.test(name.slice(separator + 1))) fail("MISSING_WORKFLOW", `Registered workflows require a qualified namespace.name: ${name}`);
-    const workflow = this.#extensions.get(name.slice(0, separator))?.workflows?.[name.slice(separator + 1)];
+    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;
   }
 
   workflows(): Readonly<Record<string, WorkflowScriptDefinition>> {
-    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap(([namespace, extension]) => Object.entries(extension.workflows ?? {}).map(([name, workflow]) => [`${namespace}.${name}`, workflow]))));
+    return Object.freeze(Object.fromEntries(this.#workflows));
   }
 
   catalog(): WorkflowCatalog {
     const functions: WorkflowCatalogFunction[] = [];
     const variables: WorkflowCatalogVariable[] = [];
     const workflows: WorkflowCatalogWorkflow[] = [];
-    for (const [namespace, extension] of this.#extensions) {
-      for (const [name, fn] of Object.entries(extension.functions ?? {})) functions.push({ name, namespace, 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, namespace, 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: `${namespace}.${name}`, namespace, version: extension.version, headline: extension.headline, extensionDescription: extension.description, description: workflow.description });
+    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 });
     }
-    const sort = (left: { namespace: string; name: string }, right: { namespace: string; name: string }) => left.namespace.localeCompare(right.namespace) || left.name.localeCompare(right.name);
-    return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), workflows: workflows.sort((left, right) => left.name.localeCompare(right.name)) });
+    let aliases: Readonly<Record<string, string>> | undefined;
+    try { aliases = loadSettings().modelAliases; } catch { aliases = undefined; }
+    const sort = (left: { name: string }, right: { name: string }) => left.name.localeCompare(right.name);
+    return deepFreeze({ functions: functions.sort(sort), variables: variables.sort(sort), workflows: workflows.sort(sort), ...(aliases ? { modelAliases: structuredClone(aliases) } : {}) });
   }
 
-  globals(): Readonly<Record<string, { namespace: string; name: string }>> {
-    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap(([namespace, extension]) => Object.keys(extension.functions ?? {}).map((name) => [name, { namespace, name }]))));
+  globals(): Readonly<Record<string, { name: string }>> {
+    return Object.freeze(Object.fromEntries([...this.#extensions].flatMap((extension) => Object.keys(extension.functions ?? {}).map((name) => [name, { name }]))));
   }
 
-  async invokeFunction(namespace: string, name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue> {
-    const fn = this.#extensions.get(namespace)?.functions?.[name];
-    if (!fn) fail("MISSING_WORKFLOW", `Workflow function is unavailable: ${namespace}.${name}`);
-    if (!object(input) || !jsonValue(input) || !Value.Check(fn.input, input)) fail("RESULT_INVALID", `Invalid input for ${namespace}.${name}`);
+  async invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue> {
+    const fn = [...this.#extensions].find((extension) => extension.functions?.[name])?.functions?.[name];
+    if (!fn) fail("MISSING_WORKFLOW", `Workflow function is unavailable: ${name}`);
+    if (!object(input) || !jsonValue(input) || !Value.Check(fn.input, input)) fail("RESULT_INVALID", `Invalid input for ${name}`);
     const replayed = journal.get(path);
     if (replayed !== undefined) {
-      if (!jsonValue(replayed) || !Value.Check(fn.output, replayed)) fail("RESULT_INVALID", `Invalid replay for ${namespace}.${name}`);
+      if (!jsonValue(replayed) || !Value.Check(fn.output, replayed)) fail("RESULT_INVALID", `Invalid replay for ${name}`);
       return structuredClone(replayed);
     }
     const result: unknown = await fn.run(deepFreeze(structuredClone(input)), Object.freeze({ run: context.run, agent: context.agent, prompt: context.prompt, parallel: context.parallel, pipeline: context.pipeline, withWorktree: context.withWorktree, checkpoint: context.checkpoint, phase: context.phase, log: context.log }));
-    if (!jsonValue(result) || !Value.Check(fn.output, result)) fail("RESULT_INVALID", `Invalid output from ${namespace}.${name}`);
+    if (!jsonValue(result) || !Value.Check(fn.output, result)) fail("RESULT_INVALID", `Invalid output from ${name}`);
     const stored = structuredClone(result);
     journal.put(path, stored);
     return structuredClone(stored);
   }
 
-  variables(): readonly { namespace: string; name: string; variable: WorkflowVariable }[] {
-    return [...this.#extensions].flatMap(([namespace, extension]) => Object.entries(extension.variables ?? {}).map(([name, variable]) => ({ namespace, name, variable })));
+  variables(): readonly { name: string; variable: WorkflowVariable }[] {
+    return [...this.#extensions].flatMap((extension) => Object.entries(extension.variables ?? {}).map(([name, variable]) => ({ name, variable })));
+  }
+  agentSetupHooks(): readonly RegisteredAgentSetupHook[] {
+    return [...this.#hooks.values()].sort((left, right) => left.priority - right.priority || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
   }
 }
-type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "workflow" | "workflows" | "catalog" | "globals" | "invokeFunction" | "variables">;
+type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "workflow" | "workflows" | "catalog" | "globals" | "invokeFunction" | "variables" | "agentSetupHooks">;
 interface WorkflowRegistryHost { api: WorkflowRegistryApi }
 const WORKFLOW_REGISTRY_KEY = Symbol.for("pi-extensible-workflows.workflow-registry");
 const globalRegistry = globalThis as typeof globalThis & Record<symbol, WorkflowRegistryHost | undefined>;
@@ -777,6 +1051,7 @@ function createWorkflowRegistryApi(registry: WorkflowRegistry): WorkflowRegistry
     globals: () => registry.globals(),
     invokeFunction: (...args) => registry.invokeFunction(...args),
     variables: () => registry.variables(),
+    agentSetupHooks: () => registry.agentSetupHooks(),
   };
 }
 function workflowRegistryHost(): WorkflowRegistryHost {
@@ -807,11 +1082,11 @@ 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 namespace.name" })),
+  workflow: Type.Optional(Type.String({ description: "Registered reusable workflow 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 })),
-  maxAgentLaunches: Type.Optional(Type.Integer({ minimum: 1, description: "Total logical agent launches for the run, including nested agents; not concurrency" })),
+  budget: Type.Optional(Type.Unknown({ description: "Optional aggregate soft and hard run budgets" })),
 });
 
 function hasDynamicAgentRole(node: acorn.AnyNode | undefined): boolean {
@@ -830,33 +1105,42 @@ export function preflight(script: string, capabilities: PreflightCapabilities, s
   const checkedMetadata = validateWorkflowMetadata(metadata);
   const program = parseWorkflow(script);
   if (hasIdentifier(program, INTERNAL_AGENT_NAME)) fail("INVALID_METADATA", `${INTERNAL_AGENT_NAME} is reserved for workflow agent instrumentation`);
+  if (hasIdentifier(program, INTERNAL_CONVERSATION_NAME)) fail("INVALID_METADATA", `${INTERNAL_CONVERSATION_NAME} is reserved for workflow conversation instrumentation`);
   if (hasIdentifier(program, INTERNAL_WORKTREE_NAME)) fail("INVALID_METADATA", `${INTERNAL_WORKTREE_NAME} is reserved for workflow withWorktree instrumentation`);
   validateDirectPrimitiveReferences(program, "withWorktree");
+  validateDirectPrimitiveReferences(program, "conversation");
   for (const [index, schema] of schemas.entries()) validateSchema(schema, `schema[${String(index)}]`);
   const calls = workflowCalls(program);
   const phases = calls.filter((call) => call.callee.name === "phase").map((call) => literalString(call.arguments[0])).filter((phase): phase is string => phase !== undefined);
   for (const call of calls) {
     const operation = call.callee.name;
-    if (operation === "agent") validateStaticAgentOptions(call.arguments[1]);
+    if (operation === "agent" || operation === "conversation") {
+      if (operation === "conversation" && (!literalString(call.arguments[0])?.trim() || call.arguments.length > 2)) fail("INVALID_METADATA", "conversation requires a stable name and optional options object");
+      validateStaticAgentOptions(call.arguments[1], capabilities.modelAliases ?? {}, capabilities.knownModels ?? capabilities.models, capabilities.settingsPath);
+    }
     if (operation === "withWorktree") validateStaticWithWorktree(call);
     if ((operation === "parallel" || operation === "pipeline") && call.arguments.some((argument) => argument.type === "SpreadElement")) continue;
     if (operation === "checkpoint" && stableName(call.arguments[0]) === false) fail("INVALID_METADATA", `${operation} requires a stable explicit name`);
     if (operation === "parallel" && (call.arguments.length !== 2 || !literalString(call.arguments[0])?.trim() || call.arguments[1]?.type !== "ObjectExpression")) fail("INVALID_METADATA", "parallel requires an operation name string and tasks record");
     if (operation === "pipeline" && (call.arguments.length !== 3 || !literalString(call.arguments[0])?.trim() || call.arguments[1]?.type !== "ObjectExpression" || call.arguments[2]?.type !== "ObjectExpression")) fail("INVALID_METADATA", "pipeline requires an operation name string, items record, and stages record");
   }
-  const agentCalls = calls.filter((call) => call.callee.name === "agent");
+  const agentCalls = calls.filter((call) => call.callee.name === "agent" || call.callee.name === "conversation");
   const dynamicAgentRoles = agentCalls.some((call) => hasDynamicAgentRole(call.arguments[1]));
   const staticSchemas = agentCalls.flatMap((call) => { const value = staticValue(propertyNode(call.arguments[1], "outputSchema")); return value.known ? [value.value] : []; });
   for (const [index, schema] of staticSchemas.entries()) validateSchema(schema, `agent outputSchema[${String(index)}]`);
   const checkedSchemas = [...schemas, ...staticSchemas];
-  const models = agentCalls.flatMap((call) => { const value = literalString(propertyNode(call.arguments[1], "model")); return value === undefined ? [] : [modelCapability(value)]; });
+  const modelRefs = agentCalls.flatMap((call) => { const requested = literalString(propertyNode(call.arguments[1], "model")); return requested === undefined ? [] : [{ requested, resolved: modelCapability(requested, capabilities.modelAliases, capabilities.knownModels ?? capabilities.models, capabilities.settingsPath) }]; });
+  const models = modelRefs.map(({ resolved }) => resolved);
   const tools = agentCalls.flatMap((call) => {
     const value = propertyNode(call.arguments[1], "tools");
     return value?.type === "ArrayExpression" ? value.elements.flatMap((element) => { const tool = element && element.type !== "SpreadElement" ? literalString(element) : undefined; return tool === undefined ? [] : [tool]; }) : [];
   });
   const agentTypes = agentCalls.flatMap((call) => { const value = literalString(propertyNode(call.arguments[1], "role")); return value === undefined ? [] : [value]; });
-  const missingModel = models.find((model) => !capabilities.models.has(model));
-  if (missingModel) fail("UNKNOWN_MODEL", `Unknown model: ${missingModel}`);
+  const missingModel = capabilities.skipModelAvailability ? undefined : modelRefs.find(({ resolved }) => !capabilities.models.has(resolved));
+  if (missingModel) {
+    if (Object.prototype.hasOwnProperty.call(capabilities.modelAliases ?? {}, missingModel.requested)) unknownModel(missingModel.requested, missingModel.resolved, capabilities.settingsPath);
+    fail("UNKNOWN_MODEL", `Unknown model: ${missingModel.resolved}`);
+  }
   const missingTool = tools.find((tool) => !capabilities.tools.has(tool));
   if (missingTool) fail("UNKNOWN_TOOL", `Unknown tool: ${missingTool}`);
   const missingType = agentTypes.find((type) => !capabilities.agentTypes.has(type));
@@ -876,6 +1160,9 @@ export interface WorkflowValidationContext {
   projectTrusted: boolean;
   availableModels: ReadonlySet<string>;
   rootTools: ReadonlySet<string>;
+  modelAliases?: Readonly<Record<string, string>>;
+  knownModels?: ReadonlySet<string>;
+  settingsPath?: string;
 }
 
 
@@ -891,6 +1178,7 @@ export function validateWorkflowLaunch(params: WorkflowValidationParameters, con
   return validateWorkflowLaunchWithRegistry(params, context, loadingRegistry());
 }
 function validateWorkflowLaunchWithRegistry(params: WorkflowValidationParameters, context: WorkflowValidationContext, registry: WorkflowRegistryApi): ValidatedWorkflowLaunch {
+  if (Object.prototype.hasOwnProperty.call(params, "maxAgentLaunches")) fail("INVALID_METADATA", "maxAgentLaunches has been removed; use budget.agentLaunches");
   if (params.script !== undefined && params.workflow !== undefined) fail("INVALID_METADATA", "Provide either script or workflow, not both");
   const definition = typeof params.workflow === "string" ? registry.workflow(params.workflow) : undefined;
   const script = typeof params.script === "string" && params.script.trim() ? params.script : definition?.script ?? "";
@@ -901,9 +1189,11 @@ function validateWorkflowLaunchWithRegistry(params: WorkflowValidationParameters
   const globalAgentDefinitions = loadAgentDefinitions(context.cwd, undefined, false);
   const projectAgentDefinitions = context.projectTrusted ? readRoleDefinitions(projectRoleDirectories(join(context.cwd, ".pi"))) : {};
   const agentDefinitions = deepFreeze({ ...globalAgentDefinitions, ...projectAgentDefinitions });
-  const checked = preflight(script, { models: context.availableModels, tools: context.rootTools, agentTypes: new Set(Object.keys(agentDefinitions)) }, [], metadata);
+  const aliases = context.modelAliases ?? {};
+  const knownModels = context.knownModels ?? context.availableModels;
+  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);
+  validateRolePolicies(agentDefinitions, roleNames, context.availableModels, context.rootTools, aliases, knownModels, context.settingsPath);
   return { script, checked, agentDefinitions, projectAgentDefinitions, roleNames };
 }
 
@@ -922,18 +1212,19 @@ export function createLaunchSnapshot(input: LaunchSnapshotInput): Readonly<Launc
 }
 
 export function loadLaunchSnapshot(input: LaunchSnapshot): Readonly<LaunchSnapshot> {
+  if (object(input.settings) && Object.prototype.hasOwnProperty.call(input.settings, "maxAgentLaunches")) fail("RESUME_INCOMPATIBLE", "Persisted workflow settings contain removed maxAgentLaunches");
   return deepFreeze(structuredClone(input));
 }
 
 export const RPC_LIMIT_BYTES = 10 * 1024 * 1024;
 export const HEARTBEAT_TIMEOUT_MS = 5000;
 
-export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string }
+export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string; conversation?: { name: string; turn: number } }
 export interface WorkflowBridge {
   agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
   checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>;
-  function?: (namespace: string, name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string) => Promise<JsonValue>;
-  functions?: Readonly<Record<string, { namespace: string; name: string }>>;
+  function?: (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath?: readonly string[]) => Promise<JsonValue>;
+  functions?: Readonly<Record<string, { name: string }>>;
   variables?: Readonly<Record<string, JsonValue>>;
   phase?: (name: string) => void | Promise<void>;
   log?: (message: string) => void | Promise<void>;
@@ -1005,6 +1296,7 @@ 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 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"); };
@@ -1028,6 +1320,44 @@ const internalWithWorktree = async (...values) => {
   }
   return await worktreeOwners.run(owner, callback);
 };
+const internalConversation = (...values) => {
+  const callSite = values.pop();
+  if (typeof callSite !== "string") throw workError("INTERNAL_ERROR", "Missing workflow conversation call-site identity");
+  const name = values[0];
+  if (typeof name !== "string" || !name.trim()) throw workError("INVALID_METADATA", "conversation requires a non-empty name");
+  const conversationOptions = values.length < 2 || values[1] === undefined ? {} : values[1];
+  if (!conversationOptions || typeof conversationOptions !== "object" || Array.isArray(conversationOptions)) throw workError("INVALID_METADATA", "conversation options must be a JSON object");
+  const inherited = inheritedAgentPath.getStore() || [];
+  const occurrenceKey = JSON.stringify([inherited, callSite, name]);
+  const occurrence = (conversationOccurrences.get(occurrenceKey) || 0) + 1;
+  conversationOccurrences.set(occurrenceKey, occurrence);
+  const fixedOptions = structuredClone(conversationOptions);
+  const defaultTimeout = fixedOptions.timeoutMs;
+  const defaultRetries = fixedOptions.retries;
+  delete fixedOptions.timeoutMs;
+  delete fixedOptions.retries;
+  const worktreeOwner = worktreeOwners.getStore();
+  let turn = 0;
+  let active = false;
+  return Object.freeze({
+    run(prompt, turnOptions = {}) {
+      if (typeof prompt !== "string") throw workError("INVALID_METADATA", "conversation.run prompt must be a string");
+      if (!turnOptions || typeof turnOptions !== "object" || Array.isArray(turnOptions) || Object.keys(turnOptions).some(key => key !== "timeoutMs" && key !== "retries")) throw workError("INVALID_METADATA", "conversation.run options only support timeoutMs and retries");
+      if (active) throw workError("RESUME_INCOMPATIBLE", "Conversation turns cannot overlap");
+      active = true;
+      const turnNumber = turn + 1;
+      const options = { ...fixedOptions, ...(defaultTimeout !== undefined && turnOptions.timeoutMs === undefined ? { timeoutMs: defaultTimeout } : {}), ...(defaultRetries !== undefined && turnOptions.retries === undefined ? { retries: defaultRetries } : {}), ...turnOptions };
+      const identity = { structuralPath: [...inherited], callSite, occurrence, ...(worktreeOwner ? { worktreeOwner } : {}), conversation: { name: name.trim(), turn: turnNumber } };
+      const result = rpc("agent", [prompt, options, identity]).then(value => { const unwrapped = unwrap(value); turn = turnNumber; return unwrapped; }).finally(() => { active = false; });
+      Object.defineProperties(result, {
+        toJSON: { value() { throw workError("INVALID_METADATA", "Workflow conversation result is a Promise; await it before serialization"); } },
+        toString: { value() { throw workError("INVALID_METADATA", "Workflow conversation result is a Promise; await it before interpolation"); } },
+        [Symbol.toPrimitive]: { value() { throw workError("INVALID_METADATA", "Workflow conversation result is a Promise; await it before interpolation"); } },
+      });
+      return result;
+    },
+  });
+};
 const internalAgent = (...values) => {
   const callSite = values.pop();
   if (typeof callSite !== "string") throw workError("INTERNAL_ERROR", "Missing workflow agent call-site identity");
@@ -1097,16 +1427,17 @@ const checkpoint = input => rpc("checkpoint", [input]).then(unwrap);
 const phase = name => rpc("phase", [name]);
 const log = message => rpc("log", [message]);
 const functionOccurrences = new Map();
-const functionPath = (namespace, name) => {
+const functionPath = name => {
   const inherited = inheritedAgentPath.getStore() || [];
-  const key = JSON.stringify([inherited, namespace, name]);
+  const key = JSON.stringify([inherited, name]);
   const occurrence = (functionOccurrences.get(key) || 0) + 1;
   functionOccurrences.set(key, occurrence);
-  return path("function", ...inherited, namespace, name, String(occurrence));
+  return path("function", ...inherited, name, String(occurrence));
 };
 const functions = Object.freeze(Object.fromEntries(Object.entries(config.functions || {}).map(([local, target]) => [local, (...values) => {
   if (values.length !== 1 || !values[0] || typeof values[0] !== "object" || Array.isArray(values[0])) throw workError("RESULT_INVALID", local + " requires exactly one JSON object argument");
-  const result = rpc("function", [target.namespace, target.name, values[0], functionPath(target.namespace, target.name), worktreeOwners.getStore() || null]).then(unwrap);
+  const inherited = inheritedAgentPath.getStore() || [];
+  const result = rpc("function", [target.name, values[0], functionPath(target.name), worktreeOwners.getStore() || null, inherited]).then(unwrap);
   Object.defineProperty(result, "toJSON", { value() { throw workError("INVALID_METADATA", "Workflow function result is a Promise; await it before serialization"); } });
   return result;
 }])));
@@ -1167,13 +1498,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, withWorktree: rejectWorktree, prompt, checkpoint, parallel, pipeline, phase, log, args: config.args, Promise, JSON, Math: Object.freeze(safeMath) };
+const sandbox = { agent, conversation: internalConversation, 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_withWorktree)=>{" + body + "\n})", { filename: "workflow.js" }).runInContext(context)(internalAgent, internalWithWorktree))
+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))
   .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));
@@ -1193,13 +1524,23 @@ function readAgentIdentity(value: unknown): AgentIdentity {
   const occurrence = value.occurrence;
   const worktreeOwner = value.worktreeOwner;
   const parentBreadcrumb = value.parentBreadcrumb;
-  if (!Array.isArray(structuralPath) || !structuralPath.every((part): part is string => typeof part === "string" && Boolean(part.trim())) || typeof callSite !== "string" || !callSite || !positiveInteger(occurrence) || parentBreadcrumb !== undefined && (typeof parentBreadcrumb !== "string" || !parentBreadcrumb.trim()) || worktreeOwner !== undefined && (typeof worktreeOwner !== "string" || !worktreeOwner)) fail("INTERNAL_ERROR", "Invalid workflow agent identity");
-  return { structuralPath: [...structuralPath], callSite, occurrence, ...(typeof parentBreadcrumb === "string" ? { parentBreadcrumb } : {}), ...(typeof worktreeOwner === "string" ? { worktreeOwner } : {}) };
+  const conversation = value.conversation;
+  const parsedConversation = object(conversation) && typeof conversation.name === "string" && Boolean(conversation.name.trim()) && positiveInteger(conversation.turn) ? { name: conversation.name, turn: conversation.turn } : undefined;
+  if (!Array.isArray(structuralPath) || !structuralPath.every((part): part is string => typeof part === "string" && Boolean(part.trim())) || typeof callSite !== "string" || !callSite || !positiveInteger(occurrence) || parentBreadcrumb !== undefined && (typeof parentBreadcrumb !== "string" || !parentBreadcrumb.trim()) || worktreeOwner !== undefined && (typeof worktreeOwner !== "string" || !worktreeOwner) || conversation !== undefined && !parsedConversation) fail("INTERNAL_ERROR", "Invalid workflow agent identity");
+  return { structuralPath: [...structuralPath], callSite, occurrence, ...(typeof parentBreadcrumb === "string" ? { parentBreadcrumb } : {}), ...(typeof worktreeOwner === "string" ? { worktreeOwner } : {}), ...(parsedConversation ? { conversation: parsedConversation } : {}) };
 }
 
 function agentIdentityPath(identity: AgentIdentity): string {
   return operationPath("agent", ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
 }
+function conversationIdentityPath(identity: AgentIdentity): string {
+  if (!identity.conversation) throw new WorkflowError("INTERNAL_ERROR", "Missing conversation identity");
+  return operationPath("conversation", identity.conversation.name, ...identity.structuralPath, `callsite:${identity.callSite}`, `occurrence:${String(identity.occurrence)}`);
+}
+function conversationTurnPath(identity: AgentIdentity): string {
+  if (!identity.conversation) throw new WorkflowError("INTERNAL_ERROR", "Missing conversation identity");
+  return operationPath(conversationIdentityPath(identity), `turn:${String(identity.conversation.turn)}`);
+}
 function agentWorktree(identity: AgentIdentity): { worktreeOwner?: string } {
   return identity.worktreeOwner ? { worktreeOwner: identity.worktreeOwner } : {};
 }
@@ -1285,11 +1626,13 @@ export function runWorkflow(script: string, args: JsonValue = null, bridge: Work
           value = branded({ name, ok: false, failedAt: name, error: { code: typed.code, message: typed.message, ...(isWorkflowAuthored(typed) ? { authored: true } : {}) } });
         }
       } else if (method === "function") {
-        const worktreeOwner = values[4] === undefined || values[4] === null ? undefined : typeof values[4] === "string" && values[4] ? values[4] : fail("INTERNAL_ERROR", "function worktree scope is invalid");
-        if (!bridge.function || typeof values[0] !== "string" || typeof values[1] !== "string" || !object(values[2]) || typeof values[3] !== "string") fail("INTERNAL_ERROR", "function requires an available bridge, names, object input, and path");
-        const name = values[0] + "." + values[1];
+        const worktreeOwner = values[3] === undefined || values[3] === null ? undefined : typeof values[3] === "string" && values[3] ? values[3] : fail("INTERNAL_ERROR", "function worktree scope is invalid");
+        const structuralPath = values[4] === undefined ? [] : values[4];
+        if (!Array.isArray(structuralPath) || !structuralPath.every((part): part is string => typeof part === "string" && Boolean(part.trim()))) fail("INTERNAL_ERROR", "function structural scope is invalid");
+        if (!bridge.function || typeof values[0] !== "string" || !object(values[1]) || typeof values[2] !== "string") fail("INTERNAL_ERROR", "function requires an available bridge, name, object input, and path");
+        const name = values[0];
         try {
-          const result = await bridge.function(values[0], values[1], values[2], values[3], controller.signal, worktreeOwner);
+          const result = await bridge.function(values[0], values[1], values[2], controller.signal, worktreeOwner, structuralPath);
           value = branded({ name, ok: true, value: result ?? null });
         } catch (error) {
           const typed = asWorkflowError(error);
@@ -1324,13 +1667,14 @@ function nativeSessionReference(attempt: Pick<AgentAttempt, "sessionId" | "sessi
   return { sessionId: attempt.sessionId, sessionFile: attempt.sessionFile };
 }
 
-export async function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile">): Promise<void> {
+export async function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">): Promise<void> {
   await store.updateState((run) => {
     const agent = run.agents.find((candidate) => candidate.id === id);
     if (!agent) throw new WorkflowError("INTERNAL_ERROR", `Missing production ownership record: ${id}`);
     const accounting = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+    const details = [...(agent.attemptDetails ?? []).filter((candidate) => candidate.attempt !== active.attempt), { ...active, accounting }];
     const nativeSessions = run.nativeSessions.some(({ sessionId }) => sessionId === active.sessionId) ? run.nativeSessions : [...run.nativeSessions, nativeSessionReference(active)];
-    return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: active.attempt, attemptDetails: [{ ...active, accounting }] } : candidate), nativeSessions };
+    return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: Math.max(candidate.attempts, active.attempt), attemptDetails: details } : candidate), nativeSessions };
   });
 }
 
@@ -1339,7 +1683,7 @@ export async function persistAgentAttempts(store: RunStore, id: string, attempts
     const agent = run.agents.find((candidate) => candidate.id === id);
     if (!agent) throw new WorkflowError("INTERNAL_ERROR", `Missing production ownership record: ${id}`);
     const total = attempts.reduce((sum, attempt) => ({ input: sum.input + attempt.accounting.input, output: sum.output + attempt.accounting.output, cacheRead: sum.cacheRead + attempt.accounting.cacheRead, cacheWrite: sum.cacheWrite + attempt.accounting.cacheWrite, cost: sum.cost + attempt.accounting.cost }), { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 });
-    const attemptDetails = attempts.map(({ attempt, sessionId, sessionFile, error, accounting }) => ({ attempt, sessionId, sessionFile, ...(error ? { error } : {}), accounting }));
+    const attemptDetails = attempts.map(({ attempt, sessionId, sessionFile, error, accounting, setup }) => ({ attempt, sessionId, sessionFile, ...(error ? { error } : {}), accounting, ...(setup ? { setup } : {}) }));
     const sessionIds = new Set(attempts.map(({ sessionId }) => sessionId));
     return { ...run, agents: run.agents.map((candidate) => candidate.id === id ? { ...candidate, attempts: attempts.length, attemptDetails, accounting: total } : candidate), nativeSessions: [...run.nativeSessions.filter(({ sessionId }) => !sessionIds.has(sessionId)), ...attempts.map((attempt) => nativeSessionReference(attempt))] };
   });
@@ -1347,19 +1691,47 @@ export async function persistAgentAttempts(store: RunStore, id: string, attempts
 
 type WorkflowToolUpdate = { content: [{ type: "text"; text: string }]; details: { runId: string; run: PersistedRun } };
 
+type AgentGroup = { label: string; entries: readonly { agent: AgentRecord; index: number; depth: number }[] };
+function agentGroupKey(agent: AgentRecord): string { return JSON.stringify([agent.structuralPath ?? [], agent.parentBreadcrumb ?? null]); }
+function agentGroupLabel(agents: readonly AgentRecord[]): string {
+  const structural = agents[0]?.structuralPath ?? [];
+  const breadcrumbs = [...new Set(agents.map((agent) => agent.parentBreadcrumb).filter((value): value is string => Boolean(value)))];
+  return [...(structural.length ? [structural.join(" > ")] : []), ...(breadcrumbs.length === 1 ? breadcrumbs : breadcrumbs.length ? [breadcrumbs.join(" | ")] : [])].join(" > ") || "Agents";
+}
+function agentGroups(agents: readonly AgentRecord[]): AgentGroup[] {
+  const byId = new Map(agents.map((agent) => [agent.id, agent]));
+  const groups = new Map<string, { agents: Array<{ agent: AgentRecord; index: number; depth: number }> }>();
+  for (const [index, agent] of agents.entries()) {
+    let depth = 0;
+    for (let parent = agent.parentId; parent && byId.has(parent); parent = byId.get(parent)?.parentId) depth += 1;
+    const key = agentGroupKey(agent);
+    const group = groups.get(key) ?? { agents: [] };
+    group.agents.push({ agent, index, depth });
+    groups.set(key, group);
+  }
+  return [...groups].map(([, group]) => ({ label: agentGroupLabel(group.agents.map(({ agent }) => agent)), entries: group.agents }));
+}
+function renderGroupedAgents(agents: readonly AgentRecord[], render: (entry: { agent: AgentRecord; index: number; depth: number }, grouped: boolean) => string): string[] {
+  const groups = agentGroups(agents);
+  const grouped = groups.length > 1 || groups.some(({ label }) => label !== "Agents");
+  return groups.flatMap((group) => [
+    ...(grouped ? [`  ${group.label}`] : []),
+    ...group.entries.map((entry) => render(entry, grouped)),
+  ]);
+}
 export function formatWorkflowProgress(run: PersistedRun, spinner = "◇"): string {
   const done = run.agents.filter((agent) => SETTLED_AGENT_STATES.has(agent.state)).length;
-  const lines = [`${run.state === "completed" ? "✓" : run.state === "failed" || run.state === "stopped" ? "✗" : run.state === "running" ? spinner : "◆"} Workflow: ${run.workflowName} (${String(done)}/${String(run.agents.length)} done)`];
+  const lines = [`${run.state === "completed" ? "✓" : run.state === "failed" || run.state === "stopped" ? "✗" : run.state === "budget_exhausted" ? "!" : run.state === "running" ? spinner : "◆"} Workflow: ${run.workflowName} (${String(done)}/${String(run.agents.length)} done)`];
   if (run.phase) lines.push(`  Phase: ${run.phase}`);
+  lines.push(...formatCompactBudgetStatus(run).map((line) => `  ${line}`));
   const byId = new Map(run.agents.map((agent) => [agent.id, agent]));
-  for (const [index, agent] of run.agents.entries()) {
-    let depth = 0;
-    for (let parent = agent.parentId; parent && byId.has(parent); parent = byId.get(parent)?.parentId) depth += 1;
+  lines.push(...renderGroupedAgents(run.agents, ({ agent, index, depth }, grouped) => {
     const icon = agent.state === "completed" ? "✓" : agent.state === "failed" || agent.state === "cancelled" ? "✗" : agent.state === "running" ? spinner : "○";
-    const indent = "  ".repeat(depth + 1);
+    const indent = "  ".repeat((grouped ? 2 : 1) + depth);
     const activity = SETTLED_AGENT_STATES.has(agent.state) ? "" : formatAgentActivity(agent, spinner);
-    lines.push(`${indent}#${String(index + 1)} ${icon} ${agent.parentBreadcrumb ? `${agent.parentBreadcrumb} > ` : ""}${agent.label ?? agent.name} [${agent.state}]${activity ? ` ${activity}` : ""}`);
-  }
+    const name = grouped ? agent.label ?? agent.name : agentBreadcrumb(agent, byId);
+    return `${indent}#${String(index + 1)} ${icon} ${name} [${agent.state}]${activity ? ` ${activity}` : ""}`;
+  }));
   return lines.join("\n");
 }
 
@@ -1387,8 +1759,29 @@ function workflowProgressBlock(run: PersistedRun) {
     invalidate() {},
   };
 }
+export function formatBudgetStatus(run: Pick<PersistedRun, "budget" | "budgetVersion" | "usage" | "budgetEvents">): string[] {
+  const usage = budgetUsage(run.usage);
+  if (!run.budget || !Object.keys(run.budget).length) return ["Budget: unlimited"];
+  const lines = [`Budget version ${String(run.budgetVersion ?? 1)}`];
+  for (const dimension of ["tokens", "costUsd", "durationMs", "agentLaunches"] as const) {
+    const limits = run.budget[dimension];
+    if (!limits || (limits.soft === undefined && limits.hard === undefined)) continue;
+    const limit = limits.hard ?? limits.soft;
+    const percent = limit === undefined ? "" : ` ${limit === 0 ? "100.0" : ((usage[dimension] / limit) * 100).toFixed(1)}%`;
+    const state = (run.budgetEvents ?? []).filter((event) => event.dimensions.includes(dimension)).at(-1)?.type;
+    lines.push(`  ${dimension}: ${String(usage[dimension])}${limits.soft !== undefined ? ` soft=${String(limits.soft)}` : ""}${limits.hard !== undefined ? ` hard=${String(limits.hard)}` : ""}${percent}${state ? ` state=${state}` : ""}`);
+  }
+  const events = run.budgetEvents ?? [];
+  if (events.length) lines.push(`  events: ${events.map((event) => `${event.type}@v${String(event.budgetVersion)}`).join(", ")}`);
+  return lines;
+}
+
+function formatCompactBudgetStatus(run: Pick<PersistedRun, "budget" | "budgetVersion" | "usage" | "budgetEvents">): string[] {
+  if (!Object.values(run.budget ?? {}).some((limits) => limits.soft !== undefined || limits.hard !== undefined)) return [];
+  return formatBudgetStatus(run);
+}
 
-const ATTENTION_ORDER: Record<string, number> = { awaiting_input: 0, running: 1, pausing: 2, paused: 3, interrupted: 4, failed: 5, queued: 6, stopped: 7, completed: 8 };
+const ATTENTION_ORDER: Record<string, number> = { awaiting_input: 0, budget_exhausted: 1, running: 2, pausing: 3, paused: 4, interrupted: 5, failed: 6, queued: 7, stopped: 8, completed: 9 };
 
 function navigatorAttentionSort<T extends { loaded: { run: PersistedRun } }>(entries: readonly T[]): T[] {
   return [...entries].sort((a, b) => (ATTENTION_ORDER[a.loaded.run.state] ?? 9) - (ATTENTION_ORDER[b.loaded.run.state] ?? 9));
@@ -1399,7 +1792,7 @@ function navigatorRunLabels(entries: readonly { store: RunStore; loaded: { run:
   for (const { loaded: { run } } of entries) nameCount.set(run.workflowName, (nameCount.get(run.workflowName) ?? 0) + 1);
   return entries.map(({ store, loaded: { run } }) => {
     const done = run.agents.filter((a) => SETTLED_AGENT_STATES.has(a.state)).length;
-    const glyph = run.state === "completed" ? "✓" : run.state === "failed" || run.state === "stopped" ? "✗" : run.state === "running" ? "⠦" : run.state === "awaiting_input" ? "●" : "◆";
+    const glyph = run.state === "completed" ? "✓" : run.state === "failed" || run.state === "stopped" ? "✗" : run.state === "budget_exhausted" ? "!" : run.state === "running" ? "⠦" : run.state === "awaiting_input" ? "●" : "◆";
     const suffix = (nameCount.get(run.workflowName) ?? 0) > 1 ? ` ${store.runId.slice(0, 8)}` : "";
     const cost = run.agents.reduce((sum, a) => sum + (a.accounting?.cost ?? 0), 0);
     const costStr = cost > 0 ? ` $${cost.toFixed(2)}` : "";
@@ -1409,15 +1802,16 @@ function navigatorRunLabels(entries: readonly { store: RunStore; loaded: { run:
 
 function agentBreadcrumb(agent: AgentRecord, byId: Map<string, AgentRecord>): string {
   const name = agent.label ?? agent.name;
-  const parts: string[] = [name];
+  const parts: string[] = agent.parentBreadcrumb ? [agent.parentBreadcrumb] : [];
   const seen = new Set<string>([agent.id]);
   for (let parentId = agent.parentId; parentId; parentId = byId.get(parentId)?.parentId) {
     if (seen.has(parentId)) break; // ponytail: cycle guard for corrupt data
     seen.add(parentId);
     const parent = byId.get(parentId);
-    if (parent) parts.unshift(parent.label ?? parent.name);
+    if (parent) parts.push(parent.label ?? parent.name);
     else break;
   }
+  parts.push(name);
   return parts.length > 1 ? parts.join(" > ") : name;
 }
 
@@ -1434,44 +1828,44 @@ function formatAccounting(accounting: NonNullable<AgentRecord["accounting"]>): s
   return `${new Intl.NumberFormat("en", { notation: "compact", maximumFractionDigits: 1 }).format(total).toLowerCase()} tok`;
 }
 
+
 export function formatNavigatorDashboard(run: PersistedRun, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string {
+  void worktrees;
   const done = run.agents.filter((a) => SETTLED_AGENT_STATES.has(a.state)).length;
   const totalAccounting = run.agents.reduce((sum, a) => ({ input: sum.input + (a.accounting?.input ?? 0), output: sum.output + (a.accounting?.output ?? 0), cacheRead: sum.cacheRead + (a.accounting?.cacheRead ?? 0), cacheWrite: sum.cacheWrite + (a.accounting?.cacheWrite ?? 0), cost: sum.cost + (a.accounting?.cost ?? 0) }), { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 });
   const hasAccounting = run.agents.some((a) => a.accounting);
-  const glyph = run.state === "completed" ? "✓" : run.state === "failed" || run.state === "stopped" ? "✗" : run.state === "running" ? "⠦" : run.state === "awaiting_input" ? "●" : "◆";
+  const glyph = run.state === "completed" ? "✓" : run.state === "failed" || run.state === "stopped" ? "✗" : run.state === "budget_exhausted" ? "!" : run.state === "running" ? "⠦" : run.state === "awaiting_input" ? "●" : "◆";
   const header = `${glyph} ${run.workflowName}`;
   const meta = [run.state, run.phase ? `phase: ${run.phase}` : "", `${String(done)}/${String(run.agents.length)} agents`, hasAccounting ? formatAccounting(totalAccounting) : "", totalAccounting.cost > 0 ? `$${totalAccounting.cost.toFixed(2)}` : ""].filter(Boolean).join(" · ");
-  const lines = [header, meta];
+  const lines = [header, meta, ...formatCompactBudgetStatus(run)];
   if (run.error) lines.push(`Error: ${run.error.code}: ${run.error.message}`);
+  if (run.events?.length) lines.push(...run.events.map((event) => `Warning: ${event.message}`));
   lines.push("");
   const byId = new Map(run.agents.map((a) => [a.id, a]));
-  const activeStates = new Set(["running", "waiting_for_child", "queued", "retrying", "paused"]);
-  const prioritised = [...run.agents].sort((a, b) => {
-    const aActive = activeStates.has(a.state) || a.state === "failed" ? 0 : 1;
-    const bActive = activeStates.has(b.state) || b.state === "failed" ? 0 : 1;
-    return aActive - bActive;
-  });
-  for (const agent of prioritised) {
+  const render = ({ agent, depth }: { agent: AgentRecord; index: number; depth: number }, grouped: boolean) => {
     const icon = agent.state === "completed" ? "✓" : agent.state === "failed" || agent.state === "cancelled" ? "✗" : agent.state === "running" ? "⠦" : "○";
-    const breadcrumb = agentBreadcrumb(agent, byId);
-    const model = `${agent.model.provider}/${agent.model.model}${agent.model.thinking ? `:${agent.model.thinking}` : ""}`;
-    const policy = [`model=${model}`, `tools=${agent.tools.join(",") || "(none)"}`, agent.role ? `role=${agent.role}` : ""];
+    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 parts = [`${icon} ${breadcrumb}`, agent.state, ...policy, tokens].filter(Boolean);
-    lines.push(parts.join(" · "));
+    const indent = "  ".repeat((grouped ? 2 : 1) + depth);
+    const result = [`${indent}${icon} ${breadcrumb} · ${agent.state} · ${policy.filter(Boolean).join(" · ")}${tokens ? ` · ${tokens}` : ""}`];
     if (agent.state === "failed" && agent.attemptDetails?.length) {
       const last = agent.attemptDetails[agent.attemptDetails.length - 1];
-      if (last?.error) lines.push(`  error: ${last.error.code}: ${last.error.message}`);
+      if (last?.error) result.push(`${indent}  error: ${last.error.code}: ${last.error.message}`);
     }
     const activity = !SETTLED_AGENT_STATES.has(agent.state) ? formatAgentActivity(agent, "⠦") : "";
-    if (activity) lines.push(`  ${activity}`);
-  }
+    if (activity) result.push(`${indent}  ${activity}`);
+    return result.join("\n");
+  };
+  lines.push(...renderGroupedAgents(run.agents, render));
   if (checkpoints.length) { lines.push(""); for (const cp of checkpoints) lines.push(`● checkpoint ${cp.name}: ${cp.prompt}`); }
-  if (worktrees.length) { lines.push(""); for (const wt of worktrees) lines.push(`branch ${wt.branch} (${wt.path})`); }
   return lines.join("\n");
 }
 
-export function formatNavigatorRun(loaded: { run: PersistedRun; snapshot: Readonly<LaunchSnapshot> }, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string {
+export function formatNavigatorRun(loaded: { run: PersistedRun; snapshot: Readonly<LaunchSnapshot> }, checkpoints: readonly AwaitingCheckpoint[], _worktrees: readonly WorktreeReference[]): string {
   const { run, snapshot } = loaded;
   const lines = [
     `Workflow: ${run.workflowName}`,
@@ -1479,29 +1873,32 @@ export function formatNavigatorRun(loaded: { run: PersistedRun; snapshot: Readon
     `Status: ${run.state}`,
     `Phase: ${run.phase ?? "(none)"}`,
     `Launch cwd: ${run.cwd}`,
+    ...formatCompactBudgetStatus(run),
     `Launch models: ${snapshot.models.join(", ") || "(none)"}`,
   ];
   if (run.error) lines.push(`Run error: ${run.error.code}: ${run.error.message}`);
+  if (run.events?.length) lines.push(...run.events.map((event) => `Warning: ${event.message}`));
+  const aliases = snapshot.modelAliases ?? snapshot.settings.modelAliases;
+  if (aliases && Object.keys(aliases).length) lines.push(`Model aliases: ${Object.entries(aliases).map(([name, target]) => `${name}=${target}`).join(", ")}`);
   lines.push("Agents / ownership:");
   if (!run.agents.length) lines.push("  (none)");
-  for (const agent of run.agents) {
+  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=${String(agent.accounting.cost)}` : "";
-    lines.push(`  ${agent.label ?? agent.name} (${agent.id}) state=${agent.state} parent=${agent.parentId ?? "root"} model=${model}${role}${tools} attempts=${String(agent.attempts)} retries=${String(Math.max(0, agent.attempts - 1))}${accounting}`);
-    for (const attempt of agent.attemptDetails ?? []) lines.push(`    attempt ${String(attempt.attempt)} transcript=${attempt.sessionFile}${attempt.error ? ` error=${attempt.error.code}: ${attempt.error.message}` : ""}`);
-    for (const call of agent.toolCalls ?? []) lines.push(`    tool ${call.name} state=${call.state}`);
-  }
+    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}`];
+    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 ?? []) result.push(`${indent}  tool ${call.name} state=${call.state}`);
+    return result.join("\n");
+  }));
   lines.push("Checkpoints:");
   if (!checkpoints.length) lines.push("  (none)");
   for (const checkpoint of checkpoints) lines.push(`  ${checkpoint.name}: ${checkpoint.prompt} context=${JSON.stringify(checkpoint.context)}`);
-  lines.push("Worktrees / branches:");
-  if (!worktrees.length) lines.push("  (none)");
-  for (const worktree of worktrees) lines.push(`  ${worktree.owner}: branch=${worktree.branch} path=${worktree.path} cwd=${worktree.cwd}`);
-  lines.push("Native Pi transcript paths:");
-  if (!run.nativeSessions.length) lines.push("  (none)");
-  for (const session of run.nativeSessions) lines.push(`  ${session.sessionId}: ${session.sessionFile}`);
+  lines.push(`Worktrees: ${String(_worktrees.length)}`);
+  lines.push(`Native Pi transcripts: ${String(run.nativeSessions.length)}`);
   return lines.join("\n");
 }
 function formatCheckpointReview(checkpoint: AwaitingCheckpoint): string {
@@ -1535,6 +1932,103 @@ function deliver(pi: ExtensionAPI, content: string): void {
 function deliverFailure(pi: ExtensionAPI, name: string, error: unknown): void {
   deliver(pi, `Workflow ${name} failed: ${formatWorkflowFailure(error)}`);
 }
+
+type WorkflowEventSink = { emit: (name: string, payload: unknown) => unknown };
+
+function safeEventError(error: unknown): WorkflowErrorShape {
+  const code = errorCode(error) ?? "INTERNAL_ERROR";
+  return { code, message: `Workflow execution failed (${code})` };
+}
+
+class WorkflowEventPublisher {
+  #queues = new Map<string, Promise<void>>();
+  #budgetEvents = new Map<string, Set<string>>();
+  #worktrees = new Map<string, Set<string>>();
+
+  constructor(private readonly sink: WorkflowEventSink | undefined) {}
+
+  seedBudget(runId: string, events: readonly BudgetEvent[] | undefined): void {
+    const seen = this.#budgetEvents.get(runId) ?? new Set<string>();
+    for (const event of events ?? []) seen.add(this.budgetKey(event));
+    this.#budgetEvents.set(runId, seen);
+  }
+
+  async runStarted(store: RunStore, metadata: WorkflowMetadata, background: boolean): Promise<void> {
+    await this.#publish(store, metadata, WORKFLOW_RUN_STARTED_EVENT, {});
+    if (background) await this.legacyStarted(store, metadata);
+  }
+
+  async legacyStarted(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_ASYNC_STARTED_EVENT, { id: store.runId, runId: store.runId, pid: process.pid, sessionId: store.sessionId, asyncDir: store.directory, agent: metadata.name }); }
+
+  async runResumed(store: RunStore, metadata: WorkflowMetadata): Promise<void> { await this.#publish(store, metadata, WORKFLOW_RUN_RESUMED_EVENT, {}); }
+
+  async runState(store: RunStore, metadata: WorkflowMetadata, previousState: RunState, state: RunState, reason?: string): Promise<void> {
+    await this.#publish(store, metadata, WORKFLOW_RUN_STATE_CHANGED_EVENT, { previousState, state, ...(reason ? { reason } : {}), ...(ERROR_CODES.includes(reason as WorkflowErrorCode) ? { errorCode: reason } : {}) });
+    if ((previousState === "paused" || previousState === "interrupted" || previousState === "budget_exhausted") && state === "running") await this.runResumed(store, metadata);
+  }
+
+  async runCompleted(store: RunStore, metadata: WorkflowMetadata, resultPath: string, background: boolean): Promise<void> {
+    await this.#publish(store, metadata, WORKFLOW_RUN_COMPLETED_EVENT, { resultPath });
+    if (background) await this.#publish(store, metadata, WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: true, state: "complete" });
+  }
+  async runFailed(store: RunStore, metadata: WorkflowMetadata, error: unknown, background: boolean, state: "failed" | "stopped" | "interrupted" | "budget_exhausted"): Promise<void> {
+    if (state === "failed") await this.#publish(store, metadata, WORKFLOW_RUN_FAILED_EVENT, { error: safeEventError(error) });
+    if (background) {
+      const legacyState = state === "interrupted" ? "failed" : state;
+      await this.#publish(store, metadata, WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: false, state: legacyState, ...(state === "stopped" ? { stopped: true } : {}), ...(legacyState === "budget_exhausted" || legacyState === "failed" ? { error: safeEventError(error).message } : {}) });
+    }
+  }
+
+  async agentState(store: RunStore, metadata: WorkflowMetadata, previous: AgentRecord | undefined, agent: AgentRecord): Promise<void> {
+    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 });
+  }
+
+  async agentStates(store: RunStore, metadata: WorkflowMetadata, previous: readonly AgentRecord[], current: readonly AgentRecord[]): Promise<void> {
+    const previousById = new Map(previous.map((agent) => [agent.id, agent]));
+    for (const agent of current) {
+      const old = previousById.get(agent.id);
+      if (!old || old.state !== agent.state || old.attempts !== agent.attempts) await this.agentState(store, metadata, old, agent);
+    }
+  }
+
+  async phase(store: RunStore, metadata: WorkflowMetadata, previousPhase: string | undefined, phase: string): Promise<void> {
+    if (previousPhase !== phase) await this.#publish(store, metadata, WORKFLOW_PHASE_CHANGED_EVENT, { ...(previousPhase !== undefined ? { previousPhase } : {}), phase });
+  }
+
+  async checkpoint(store: RunStore, metadata: WorkflowMetadata, name: string, state: WorkflowCheckpointState): Promise<void> { await this.#publish(store, metadata, WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT, { name, state }); }
+
+  async budget(store: RunStore, metadata: WorkflowMetadata, run: Pick<PersistedRun, "budgetEvents">): Promise<void> {
+    const seen = this.#budgetEvents.get(store.runId) ?? new Set<string>();
+    this.#budgetEvents.set(store.runId, seen);
+    for (const event of run.budgetEvents ?? []) {
+      const key = this.budgetKey(event);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      await this.#publish(store, metadata, WORKFLOW_BUDGET_EVENT, { ...event, timestamp: event.at });
+    }
+  }
+
+  async worktree(store: RunStore, metadata: WorkflowMetadata, worktree: WorktreeReference): Promise<void> {
+    const seen = this.#worktrees.get(store.runId) ?? new Set<string>();
+    this.#worktrees.set(store.runId, seen);
+    if (seen.has(worktree.owner)) return;
+    seen.add(worktree.owner);
+    await this.#publish(store, metadata, WORKFLOW_WORKTREE_CREATED_EVENT, { owner: worktree.owner, branch: worktree.branch, path: worktree.path, base: worktree.base });
+  }
+
+  async #publish(store: RunStore, metadata: WorkflowMetadata, name: string, payload: Record<string, unknown>): Promise<void> {
+    const base: WorkflowEventBase = { runId: store.runId, sessionId: store.sessionId, workflowName: metadata.name, cwd: store.cwd, runDirectory: store.directory, timestamp: Date.now() };
+    const previous = this.#queues.get(store.runId) ?? Promise.resolve();
+    const next = previous.then(() => {
+      try { void Promise.resolve(this.sink?.emit(name, { ...base, ...payload })).catch(() => undefined); } catch { /* Best effort: listeners cannot affect a run. */ }
+    });
+    this.#queues.set(store.runId, next.catch(() => undefined));
+    await next;
+  }
+
+  private budgetKey(event: BudgetEvent): string { return `${String(event.budgetVersion)}:${event.type}:${event.proposalId ?? ""}`; }
+}
+
 const inheritedHostAgentPath = new AsyncLocalStorage<readonly string[]>();
 const inheritedHostWorktreeOwner = new AsyncLocalStorage<string>();
 
@@ -1566,13 +2060,13 @@ function workflowRunContext(cwd: string, sessionId: string, runId: string, workf
 
 async function resolveWorkflowVariables(run: Readonly<WorkflowRunContext>, controller: AbortController, registry: WorkflowRegistryApi): Promise<Readonly<Record<string, JsonValue>>> {
   let first: WorkflowError | undefined;
-  const tasks = registry.variables().map(async ({ namespace, name, variable }) => {
+  const tasks = registry.variables().map(async ({ name, variable }) => {
     try {
       const result: unknown = await variable.resolve(run);
-      if (!jsonValue(result) || !Value.Check(variable.schema, result)) fail("RESULT_INVALID", `Invalid output from ${namespace}.${name}`);
+      if (!jsonValue(result) || !Value.Check(variable.schema, result)) fail("RESULT_INVALID", `Invalid output from ${name}`);
       return [name, deepFreeze(structuredClone(result))] as const;
     } catch (error) {
-      const typed = errorCode(error) ? new WorkflowError(errorCode(error) as WorkflowErrorCode, `${namespace}.${name}: ${errorText(error)}`) : new WorkflowError("INTERNAL_ERROR", `${namespace}.${name}: ${errorText(error)}`);
+      const typed = errorCode(error) ? new WorkflowError(errorCode(error) as WorkflowErrorCode, `${name}: ${errorText(error)}`) : new WorkflowError("INTERNAL_ERROR", `${name}: ${errorText(error)}`);
       if (!first) { first = typed; controller.abort(); }
       throw typed;
     }
@@ -1643,7 +2137,7 @@ function nextNamedOccurrence(counters: Map<string, number>, label: string): stri
 function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runContext: Readonly<WorkflowRunContext>, variables: Readonly<Record<string, JsonValue>>, registry: WorkflowRegistryApi): WorkflowBridge {
   const functionAgentOccurrences = new Map<string, number>();
   const functionWorktreeOccurrences = new Map<string, number>();
-  return { ...bridge, functions: registry.globals(), variables, function: async (namespace, name, input, path, signal, worktreeOwner) => {
+  return { ...bridge, functions: registry.globals(), variables, function: async (name, input, path, signal, worktreeOwner, structuralPath = []) => {
     const replayed = await store.replay(path);
     let stored: JsonValue | undefined;
     const sideEffects: Promise<void>[] = [];
@@ -1653,11 +2147,11 @@ function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runConte
         if (!bridge.agent || typeof args[0] !== "string") fail("AGENT_FAILED", "No agent bridge is available");
         const options = validateAgentOptions(args[1] === undefined ? {} : args[1]);
         const scopedWorktreeOwner = inheritedHostWorktreeOwner.getStore() ?? worktreeOwner;
-        const structuralPath = inheritedHostAgentPath.getStore() ?? [];
-        const key = `${path}\0${JSON.stringify(structuralPath)}`;
+        const inherited = inheritedHostAgentPath.getStore() ?? [];
+        const key = `${path}\0${JSON.stringify(inherited)}`;
         const occurrence = (functionAgentOccurrences.get(key) ?? 0) + 1;
         functionAgentOccurrences.set(key, occurrence);
-        return bridge.agent(args[0], options, signal, { structuralPath: [...structuralPath], callSite: `function:${path}`, occurrence, parentBreadcrumb: `${namespace}.${name}`, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
+        return bridge.agent(args[0], options, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb: name, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
       },
       prompt: workflowPrompt,
       parallel: (...args: readonly unknown[]) => hostParallel(args[0], args[1]),
@@ -1670,7 +2164,7 @@ function withWorkflowFunctions(bridge: WorkflowBridge, store: RunStore, runConte
       phase: (name: string) => { sideEffects.push(Promise.resolve(bridge.phase?.(name))); },
       log: (message: string) => { sideEffects.push(Promise.resolve(bridge.log?.(message))); },
     };
-    const result = await registry.invokeFunction(namespace, 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; } }));
     await Promise.all(sideEffects);
     if (!replayed) await store.complete(path, stored ?? result);
     return result;
@@ -1702,20 +2196,17 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     try { pi.appendEntry<WorkflowLogEntry>(WORKFLOW_LOG_ENTRY, { workflowName, message: utf8Prefix(message, DELIVERY_LIMIT_BYTES) }); }
     finally { await lifecycle.leave(); }
   };
-  const events = (pi as unknown as { events?: ExtensionAPI["events"] }).events;
+  const eventPublisher = new WorkflowEventPublisher((pi as unknown as { events?: WorkflowEventSink }).events);
   pi.on("resources_discover", () => {
     if (!pi.getActiveTools().includes("workflow")) return;
     const extensionDir = dirname(fileURLToPath(import.meta.url));
     const skillPath = [join(extensionDir, "../skills"), join(extensionDir, "../../skills")].find((path) => existsSync(path));
     return skillPath ? { skillPaths: [skillPath] } : undefined;
   });
-  const emitAsyncStarted = (store: RunStore, metadata: WorkflowMetadata) => {
-    events?.emit(WORKFLOW_ASYNC_STARTED_EVENT, { id: store.runId, runId: store.runId, pid: process.pid, sessionId: store.sessionId, asyncDir: store.directory, agent: metadata.name });
-  };
-  const emitAsyncComplete = (store: RunStore, state: "complete" | "failed" | "stopped", error?: Error) => {
-    events?.emit(WORKFLOW_ASYNC_COMPLETE_EVENT, { id: store.runId, runId: store.runId, sessionId: store.sessionId, asyncDir: store.directory, success: state === "complete", state, ...(state === "stopped" ? { stopped: true } : {}), ...(error ? { error: error.message } : {}) });
-  };
-  const runs = new Map<string, { executor: WorkflowAgentExecutor; store: RunStore; metadata: WorkflowMetadata; model: ModelSpec; lifecycle: RunLifecycle; abortController: AbortController; execution?: WorkflowExecution; completion?: Promise<unknown>; checkpointResolvers: Map<string, (value: boolean) => void>; update?: (result: WorkflowToolUpdate) => void }>();
+  type BudgetDecisionResult = { state: "running" | "budget_exhausted"; approved: boolean };
+  const runs = new Map<string, { executor: WorkflowAgentExecutor; store: RunStore; metadata: WorkflowMetadata; model: ModelSpec; lifecycle: RunLifecycle; budget: WorkflowBudgetRuntime; abortController: AbortController; projectTrusted: () => boolean; execution?: WorkflowExecution; completion?: Promise<unknown>; checkpointResolvers: Map<string, (value: boolean) => void>; budgetResolvers: Map<string, (result: BudgetDecisionResult) => void>; update?: (result: WorkflowToolUpdate) => void }>();
+  const conversationLocks = new Set<string>();
+  const terminalRunStates = new Map<string, "completed" | "failed" | "stopped">();
   let sessionLease: SessionLease | undefined;
   let sessionLeasePromise: Promise<SessionLease> | undefined;
   const ensureSessionLease = async (cwd: string, sessionId: string) => {
@@ -1730,121 +2221,208 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     sessionLeasePromise = undefined;
     await lease?.release();
   };
-  const lifecycleFor = (store: RunStore, state: RunState) => new RunLifecycle(state, async (next) => {
-    const run = await store.updateState((current) => {
-      const nextRun = { ...current, state: next };
+  const persistRunState = async (store: RunStore, metadata: WorkflowMetadata, update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>): Promise<PersistedRun> => {
+    const persisted = await store.updateState(update);
+    await eventPublisher.budget(store, metadata, persisted);
+    return persisted;
+  };
+  const persistWorktree = async (store: RunStore, metadata: WorkflowMetadata, owner: string): Promise<WorktreeReference> => {
+    const existing = (await store.worktrees()).some((worktree) => worktree.owner === owner);
+    const worktree = await store.worktree(owner);
+    if (!existing) await eventPublisher.worktree(store, metadata, worktree);
+    return worktree;
+  };
+  const lifecycleFor = (store: RunStore, state: RunState, budget: WorkflowBudgetRuntime, metadata: WorkflowMetadata) => new RunLifecycle(state, async (next, previous, reason) => {
+    if (next !== "pausing") budget.transition(next);
+    const persisted = await persistRunState(store, metadata, (current) => {
+      const nextRun = { ...current, state: next, ...budget.snapshot() };
       if (next === "running" || next === "completed") delete nextRun.error;
       return nextRun;
     });
-    runs.get(store.runId)?.update?.(workflowToolUpdate(run));
+    await eventPublisher.runState(store, metadata, previous, next, reason);
+    runs.get(store.runId)?.update?.(workflowToolUpdate(persisted));
   });
   const scheduler = new FairAgentScheduler(async ({ id, runId, parentId, prompt, options, signal, setSteer }) => {
     const run = runs.get(runId);
     if (!run) throw new WorkflowError("INTERNAL_ERROR", `Unknown production run: ${runId}`);
     try {
+      const budget = run.budget.forAgent(id);
       const onProgress = async (progress: AgentProgress) => {
         let runState: PersistedRun;
         if (progress.persist) {
-          runState = await run.store.updateState((current) => current.agents.some((agent) => agent.id === id) ? { ...current, agents: current.agents.map((agent) => agent.id === id ? { ...agent, accounting: progress.accounting, toolCalls: progress.toolCalls, activity: progress.activity } : agent) } : current);
+          runState = await persistRunState(run.store, run.metadata, (current) => current.agents.some((agent) => agent.id === id) ? { ...current, ...run.budget.snapshot(), agents: current.agents.map((agent) => agent.id === id ? { ...agent, accounting: progress.accounting, toolCalls: progress.toolCalls, activity: progress.activity } : agent) } : current);
         } else {
           const loaded = await run.store.load();
           if (!loaded.run.agents.some((agent) => agent.id === id)) return;
-          runState = { ...loaded.run, agents: loaded.run.agents.map((agent) => agent.id === id ? { ...agent, accounting: progress.accounting, toolCalls: progress.toolCalls, activity: progress.activity } : agent) };
+          runState = { ...loaded.run, ...run.budget.snapshot(), agents: loaded.run.agents.map((agent) => agent.id === id ? { ...agent, accounting: progress.accounting, toolCalls: progress.toolCalls, activity: progress.activity } : agent) };
         }
         if (!runState.agents.some((agent) => agent.id === id)) return;
         run.update?.(workflowToolUpdate(runState));
       };
-      const onAttempt = async (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile">) => {
+      const onAttempt = async (attempt: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">) => {
         await scheduler.flush();
+        scheduler.attemptStarted(id);
+        await scheduler.flush();
+        const before = (await run.store.load()).run;
         await persistActiveAgentAttempt(run.store, id, attempt);
-        run.update?.(workflowToolUpdate((await run.store.load()).run));
+        const active = (await run.store.load()).run;
+        await eventPublisher.agentStates(run.store, run.metadata, before.agents, active.agents);
+        const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
+        run.update?.(workflowToolUpdate(persisted));
       };
-      const result = await run.executor.execute(prompt, { label: options.label, workflowName: run.metadata.name, onProgress, onAttempt, ...(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 }) }, 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); });
+      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 before = (await run.store.load()).run;
       await persistAgentAttempts(run.store, id, result.attempts);
+      const completed = (await run.store.load()).run;
+      await eventPublisher.agentStates(run.store, run.metadata, before.agents, completed.agents);
+      const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
+      run.update?.(workflowToolUpdate(persisted));
       return result.value;
     } catch (error) {
       const attempts = (error as WorkflowError & { attempts?: readonly AgentAttempt[] }).attempts;
-      if (attempts?.length) await persistAgentAttempts(run.store, id, attempts);
+      if (attempts?.length) {
+        const before = (await run.store.load()).run;
+        await persistAgentAttempts(run.store, id, attempts);
+        const failed = (await run.store.load()).run;
+        await eventPublisher.agentStates(run.store, run.metadata, before.agents, failed.agents);
+      }
+      const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
+      run.update?.(workflowToolUpdate(persisted));
       throw error;
     }
   }, 16, async (runId, ownership) => {
     const run = runs.get(runId);
     if (!run) return;
     await run.store.saveOwnership(ownership);
-    const runState = await run.store.updateState((current) => {
+    let previousAgents: readonly AgentRecord[] = [];
+    const runState = await persistRunState(run.store, run.metadata, (current) => {
+      previousAgents = current.agents;
       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.model ? { model: node.options.model } : {}), ...(node.options.thinking ? { thinking: node.options.thinking } : {}), ...(node.options.role ? { role: node.options.role } : {}), effectiveTools: node.options.tools };
-        let effective: { model: ModelSpec; tools: readonly string[] };
+        let effective: { model: ModelSpec; requestedModel?: string; tools: readonly string[] };
         try { effective = run.executor.resolve(requested); }
-        catch { effective = previous ? { model: previous.model, tools: previous.tools } : { model: node.options.model ? modelSpec(node.options.model, run.model) : { ...run.model, ...(node.options.thinking ? { thinking: node.options.thinking } : {}) }, tools: node.options.tools }; }
-        return { id: node.id, name: node.label, ...(node.options.requestedLabel ? { label: node.options.requestedLabel } : {}), path: node.id, state: node.state, ...(node.parentId ? { parentId: node.parentId } : {}), ...(node.options.parentBreadcrumb ? { parentBreadcrumb: node.options.parentBreadcrumb } : {}), ...(node.options.role ? { role: node.options.role } : {}), model: effective.model, tools: effective.tools, attempts: previous?.attempts ?? 0, ...(previous?.attemptDetails ? { attemptDetails: previous.attemptDetails } : {}), ...(previous?.accounting ? { accounting: previous.accounting } : {}), ...(previous?.toolCalls ? { toolCalls: previous.toolCalls } : {}), ...(previous?.activity ? { activity: previous.activity } : {}) };
+        catch { 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.thinking ? { thinking: node.options.thinking } : {}) }, ...(node.options.model ? { requestedModel: node.options.model } : {}), tools: node.options.tools }; }
+        return { 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 ?? [])], ...(node.options.parentBreadcrumb ? { parentBreadcrumb: node.options.parentBreadcrumb } : {}), ...(node.options.worktreeOwner ? { worktreeOwner: node.options.worktreeOwner } : {}), ...(node.options.role ? { role: node.options.role } : {}), ...(effective.requestedModel ? { requestedModel: effective.requestedModel } : {}), model: effective.model, tools: effective.tools, attempts: previous?.attempts ?? 0, ...(previous?.attemptDetails ? { attemptDetails: previous.attemptDetails } : {}), ...(previous?.accounting ? { accounting: previous.accounting } : {}), ...(previous?.toolCalls ? { toolCalls: previous.toolCalls } : {}), ...(previous?.activity ? { activity: previous.activity } : {}) };
       });
       return { ...current, agents };
     });
+    await eventPublisher.agentStates(run.store, run.metadata, previousAgents, runState.agents);
     run.update?.(workflowToolUpdate(runState));
   });
+  type WorkflowStopResult = { runId: string; state: RunState | "unknown"; stopped: boolean; reason?: "unknown_run" | "already_terminal" };
+  const stopWorkflowRun = async (runId: string): Promise<WorkflowStopResult> => {
+    const run = runs.get(runId);
+    const terminalState = terminalRunStates.get(runId);
+    if (!run) return terminalState ? { runId, state: terminalState, stopped: false, reason: "already_terminal" } : { runId, state: "unknown", stopped: false, reason: "unknown_run" };
+    const state = run.lifecycle.state;
+    if (state === "completed" || state === "failed" || state === "stopped") return { runId, state, stopped: false, reason: "already_terminal" };
+    await run.lifecycle.terminal("stopped");
+    run.abortController.abort();
+    run.execution?.cancel();
+    await scheduler.cancelRun(run.store.runId);
+    await scheduler.flush();
+    return { runId, state: "stopped", stopped: true };
+  };
   const answerCheckpoint = async (runId: string, name: string, approved: boolean, silent = false) => {
     const run = runs.get(runId);
     if (!run) return false;
     const checkpoint = await run.store.answerCheckpoint(name, approved);
     if (!checkpoint) return false;
+    await eventPublisher.checkpoint(run.store, run.metadata, checkpoint.name, approved ? "approved" : "rejected");
     if ((await run.store.awaitingCheckpoints()).length === 0) await run.lifecycle.resolveAwaitingInput();
     run.checkpointResolvers.get(checkpoint.path)?.(approved);
     run.checkpointResolvers.delete(checkpoint.path);
     if (!silent) deliver(pi, `Workflow ${run.metadata.name} checkpoint ${name}: ${approved ? "Approved" : "Rejected"}.`);
     return true;
   };
+  const budgetDecisionDelivery = (metadata: WorkflowMetadata, request: BudgetApprovalRequest) => `Workflow ${metadata.name} budget adjustment ${request.proposalId} for run ${request.runId} requires approval. Consumed usage: ${JSON.stringify(request.consumed)}. Previous limits: ${JSON.stringify(request.previous)}. Proposed limits: ${JSON.stringify(request.proposed)}. Respond with workflow_respond using proposalId ${request.proposalId}.`;
+  const appendBudgetDecisionEvent = async (run: NonNullable<ReturnType<typeof runs.get>>, request: BudgetApprovalRequest, type: "adjustment_requested" | "adjustment_approved" | "adjustment_rejected") => {
+    run.budget.recordEvent({ type, budgetVersion: request.budgetVersion, dimensions: [], usage: structuredClone(request.consumed), limits: structuredClone(request.proposed), at: Date.now(), proposalId: request.proposalId, previous: structuredClone(request.previous), proposed: structuredClone(request.proposed) });
+    await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot() }));
+  };
+  const answerBudgetDecision = async (runId: string, proposalId: string, approved: boolean, silent = false): Promise<BudgetDecisionResult | undefined> => {
+    const run = runs.get(runId);
+    if (!run) return undefined;
+    const request = await run.store.answerWorkflowDecision(proposalId, approved);
+    if (!request) return undefined;
+    await appendBudgetDecisionEvent(run, request, approved ? "adjustment_approved" : "adjustment_rejected");
+    const result = await applyBudgetDecision(request, approved);
+    run.budgetResolvers.get(proposalId)?.(result);
+    run.budgetResolvers.delete(proposalId);
+    if (!silent) deliver(pi, `Workflow ${run.metadata.name} budget adjustment ${proposalId}: ${approved ? "Approved" : "Rejected"}.`);
+    return result;
+  };
   const checkpointBridge = (runId: string, store: RunStore, metadata: WorkflowMetadata, foreground: boolean, ui?: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }) => {
     const checkpointCounters = new Map<string, number>();
     return async (raw: Readonly<Record<string, JsonValue>>, signal: AbortSignal): Promise<boolean> => {
-    const input = validateCheckpoint(raw);
-    const label = nextNamedOccurrence(checkpointCounters, input.name);
-    const path = operationPath("checkpoint", label);
-    if (foreground && !ui?.select) fail("RESUME_INCOMPATIBLE", "Foreground checkpoints require UI");
-    const alreadyAwaiting = (await store.awaitingCheckpoints()).some((checkpoint) => checkpoint.path === path);
-    const replayed = await store.awaitCheckpoint({ ...input, name: label, path });
-    if (replayed !== undefined) return replayed;
-    const run = runs.get(runId);
-    await run?.lifecycle.enterAwaitingInput();
-    if (!alreadyAwaiting && !ui?.select) deliver(pi, `Workflow ${metadata.name} checkpoint ${label}: ${input.prompt}\nContext: ${JSON.stringify(input.context)}\nRespond with workflow_respond.`);
-    const decision = new Promise<boolean>((resolve, reject) => {
-      run?.checkpointResolvers.set(path, resolve);
-      if (signal.aborted) reject(new WorkflowError("CANCELLED", "Workflow cancelled"));
-      else signal.addEventListener("abort", () => { run?.checkpointResolvers.delete(path); reject(new WorkflowError("CANCELLED", "Workflow cancelled")); }, { once: true });
-    });
-    const answered = await store.awaitCheckpoint({ ...input, name: label, path });
-    if (answered !== undefined) {
-      if ((await store.awaitingCheckpoints()).length === 0) await run?.lifecycle.resolveAwaitingInput();
-      run?.checkpointResolvers.get(path)?.(answered);
-      run?.checkpointResolvers.delete(path);
-    }
-    if (ui?.select) void (async () => {
-      while (!signal.aborted && run?.checkpointResolvers.has(path)) {
-        const choice = await ui.select?.(input.prompt, ["Approve", "Reject"]);
-        if (!choice) {
-          if (foreground) continue; // foreground: retry until answered
-          // Background resume: user dismissed UI, fall back to LLM
-          deliver(pi, `Workflow ${metadata.name} checkpoint ${label}: ${input.prompt}\nContext: ${JSON.stringify(input.context)}\nRespond with workflow_respond.`);
-          return;
-        }
-        if (await answerCheckpoint(runId, label, choice === "Approve", true)) return;
+      const input = validateCheckpoint(raw);
+      const label = nextNamedOccurrence(checkpointCounters, input.name);
+      const path = operationPath("checkpoint", label);
+      if (foreground && !ui?.select) fail("RESUME_INCOMPATIBLE", "Foreground checkpoints require UI");
+      const alreadyAwaiting = (await store.awaitingCheckpoints()).some((checkpoint) => checkpoint.path === path);
+      const replayed = await store.awaitCheckpoint({ ...input, name: label, path });
+      if (replayed !== undefined) return replayed;
+      if (!alreadyAwaiting) await eventPublisher.checkpoint(store, metadata, label, "awaiting");
+      const run = runs.get(runId);
+      await run?.lifecycle.enterAwaitingInput();
+      if (!alreadyAwaiting && !ui?.select) deliver(pi, `Workflow ${metadata.name} checkpoint ${label}: ${input.prompt}\nContext: ${JSON.stringify(input.context)}\nRespond with workflow_respond.`);
+      const decision = new Promise<boolean>((resolve, reject) => {
+        run?.checkpointResolvers.set(path, resolve);
+        if (signal.aborted) reject(new WorkflowError("CANCELLED", "Workflow cancelled"));
+        else signal.addEventListener("abort", () => { run?.checkpointResolvers.delete(path); reject(new WorkflowError("CANCELLED", "Workflow cancelled")); }, { once: true });
+      });
+      const answered = await store.awaitCheckpoint({ ...input, name: label, path });
+      if (answered !== undefined) {
+        if ((await store.awaitingCheckpoints()).length === 0) await run?.lifecycle.resolveAwaitingInput();
+        run?.checkpointResolvers.get(path)?.(answered);
+        run?.checkpointResolvers.delete(path);
       }
-    })().catch(() => undefined);
-    return decision;
-  };
+      if (ui?.select) void (async () => {
+        while (!signal.aborted && run?.checkpointResolvers.has(path)) {
+          const choice = await ui.select?.(input.prompt, ["Approve", "Reject"]);
+          if (!choice) {
+            if (foreground) continue; // foreground: retry until answered
+            deliver(pi, `Workflow ${metadata.name} checkpoint ${label}: ${input.prompt}\nContext: ${JSON.stringify(input.context)}\nRespond with workflow_respond.`);
+            return;
+          }
+          if (await answerCheckpoint(runId, label, choice === "Approve", true)) return;
+        }
+      })().catch(() => undefined);
+      return decision;
+    };
   };
 
   pi.registerTool({
     name: "workflow_respond",
     label: "Workflow Respond",
-    description: "Approve or reject one pending workflow checkpoint",
-    parameters: Type.Object({ runId: Type.String(), name: Type.String(), approved: Type.Boolean() }, { additionalProperties: false }),
+    description: "Approve or reject one pending workflow checkpoint or budget decision",
+    parameters: Type.Object({ runId: Type.String(), name: Type.Optional(Type.String()), proposalId: Type.Optional(Type.String()), approved: Type.Boolean() }, { additionalProperties: false }),
     async execute(_id, params) {
       try {
+        if (params.proposalId) {
+          const result = await answerBudgetDecision(params.runId, params.proposalId, params.approved);
+          if (!result) { const denied = { state: "budget_exhausted" as const, approved: false, reason: "proposal_not_pending" }; return { content: [{ type: "text" as const, text: JSON.stringify(denied) }], details: denied }; }
+          return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: { ...result, reason: params.approved ? "approved" : "rejected" } };
+        }
+        if (!params.name) throw new WorkflowError("INVALID_METADATA", "workflow_respond requires name or proposalId");
         const accepted = await answerCheckpoint(params.runId, params.name, params.approved);
-        return { content: [{ type: "text" as const, text: accepted ? "Checkpoint response accepted." : "Checkpoint is not awaiting a response." }], details: { accepted } };
+        return { content: [{ type: "text" as const, text: accepted ? "Checkpoint response accepted." : "Checkpoint is not awaiting a response." }], details: { accepted, state: accepted ? "checkpoint_answered" : "not_pending", approved: params.approved, reason: "checkpoint" } as never };
+      } catch (error) {
+        throw mainAgentError(error);
+      }
+    },
+  });
+  pi.registerTool({
+    name: "workflow_stop",
+    label: "Workflow Stop",
+    description: "Stop an active workflow run by ID",
+    parameters: Type.Object({ runId: Type.String() }, { additionalProperties: false }),
+    async execute(_id, params) {
+      try {
+        const result = await stopWorkflowRun(params.runId);
+        return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: result };
       } catch (error) {
         throw mainAgentError(error);
       }
@@ -1855,7 +2433,8 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
   const registerCatalog = () => {
     if (catalogRegistered || !pi.getActiveTools().includes("workflow")) return;
     const catalog = registry.catalog();
-    if (!catalog.functions.length && !catalog.variables.length && !catalog.workflows.length) return;
+    const hasAliases = Object.keys(catalog.modelAliases ?? {}).length > 0;
+    if (!catalog.functions.length && !catalog.variables.length && !catalog.workflows.length && !hasAliases) return;
     pi.registerTool({
       name: "workflow_catalog",
       label: "Workflow Catalog",
@@ -1865,37 +2444,92 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     });
     catalogRegistered = true;
   };
-  const coldResumeRun = async (run: NonNullable<ReturnType<typeof runs.get>>, hasUI: boolean, ui: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }, trustedProject: boolean) => {
+  const refreshPausedRunAliases = async (run: NonNullable<ReturnType<typeof runs.get>>, context?: { model: { provider: string; id: string } | undefined; modelRegistry: { getAll?: () => Array<{ provider: string; id: string }>; getAvailable?: () => Array<{ provider: string; id: string }> } | undefined }) => {
+    const loaded = await run.store.load();
+    const active = new Set(pi.getActiveTools().filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_stop" && tool !== "workflow_catalog"));
+    const missing = loaded.snapshot.tools.filter((tool) => tool !== "workflow_catalog").find((tool) => !active.has(tool));
+    if (missing) throw new WorkflowError("RESUME_INCOMPATIBLE", `Required tool is unavailable: ${missing}`);
+    const settingsPath = workflowSettingsPath();
+    const currentSettings = loadSettings(settingsPath);
+    resolveAgentResourcePolicy(run.store.cwd, run.projectTrusted(), settingsPath);
+    const currentAliases = currentSettings.modelAliases ?? {};
+    const previousAliases = loaded.snapshot.modelAliases ?? loaded.snapshot.settings.modelAliases ?? {};
+    const modelRegistry = context?.modelRegistry;
+    const knownModels = new Set((modelRegistry?.getAll?.() ?? modelRegistry?.getAvailable?.() ?? []).map((model) => `${model.provider}/${model.id}`));
+    if (context?.model) knownModels.add(`${context.model.provider}/${context.model.id}`);
+    const resumeModels = modelRegistry ? knownModels : new Set([...loaded.snapshot.models, ...knownModels]);
+    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)));
+    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.setRunContext(workflowRunContext(run.store.cwd, run.store.sessionId, run.store.runId, loaded.snapshot.metadata, loaded.snapshot.args, run.abortController.signal));
+    const drift = aliasDrift(previousAliases, currentAliases);
+    if (drift.length) await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
+  };
+  const coldResumeRun = async (run: NonNullable<ReturnType<typeof runs.get>>, hasUI: boolean, ui: { select?: (prompt: string, options: string[]) => Promise<string | undefined> }, trustedProject: boolean, context?: { model: { provider: string; id: string } | undefined; modelRegistry: { getAll?: () => Array<{ provider: string; id: string }>; getAvailable?: () => Array<{ provider: string; id: string }> } | undefined }) => {
     const loaded = await run.store.load();
     if (loaded.snapshot.identityVersion !== LAUNCH_SNAPSHOT_IDENTITY_VERSION) throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow launch snapshot identity version is incompatible");
     if (loaded.snapshot.roles === undefined) throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow role definitions are missing from the launch snapshot");
     if ((loaded.snapshot.projectRoles?.length ?? 0) > 0 && !trustedProject) throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot restore project roles in an untrusted project");
     const missingRole = loaded.snapshot.agentTypes.find((role) => !loaded.snapshot.roles?.[role]);
     if (missingRole) throw new WorkflowError("RESUME_INCOMPATIBLE", `Role definition is missing from the launch snapshot: ${missingRole}`);
-    const active = new Set(pi.getActiveTools().filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_catalog"));
+    const active = new Set(pi.getActiveTools().filter((tool) => tool !== "workflow" && tool !== "workflow_respond" && tool !== "workflow_stop" && tool !== "workflow_catalog"));
     const missing = loaded.snapshot.tools.filter((tool) => tool !== "workflow_catalog").find((tool) => !active.has(tool));
     if (missing) throw new WorkflowError("RESUME_INCOMPATIBLE", `Required tool is unavailable: ${missing}`);
-    preflight(loaded.snapshot.script, { models: new Set(loaded.snapshot.models), tools: active, agentTypes: new Set(loaded.snapshot.agentTypes) }, loaded.snapshot.schemas, loaded.snapshot.metadata);
+    const settingsPath = workflowSettingsPath();
+    const currentSettings = loadSettings(settingsPath);
+    resolveAgentResourcePolicy(run.store.cwd, trustedProject, settingsPath);
+    const currentAliases = currentSettings.modelAliases ?? {};
+    const previousAliases = loaded.snapshot.modelAliases ?? loaded.snapshot.settings.modelAliases ?? {};
+    const modelRegistry = context?.modelRegistry;
+    const knownModels = new Set((modelRegistry?.getAll?.() ?? modelRegistry?.getAvailable?.() ?? []).map((model) => `${model.provider}/${model.id}`));
+    if (context?.model) knownModels.add(`${context.model.provider}/${context.model.id}`);
+    const resumeModels = modelRegistry ? knownModels : new Set([...loaded.snapshot.models, ...knownModels]);
+    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 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);
+    const drift = aliasDrift(previousAliases, currentAliases);
+    if (drift.length) await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
     const controller = new AbortController();
     run.abortController = controller;
     const runContext = workflowRunContext(run.store.cwd, run.store.sessionId, run.store.runId, loaded.snapshot.metadata, loaded.snapshot.args, controller.signal);
+    run.executor.setRunContext(runContext);
     let variables: Readonly<Record<string, JsonValue>>;
     try { variables = await resolveWorkflowVariables(runContext, controller, registry); }
     catch (error) {
       const typed = asWorkflowError(error);
-      if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.lifecycle.terminal("failed").catch(() => undefined); await run.store.updateState((current) => ({ ...current, error: { code: typed.code, message: typed.message } })); }
+      if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.lifecycle.terminal("failed", typed.code).catch(() => undefined); const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, error: { code: typed.code, message: typed.message } })); await eventPublisher.runFailed(run.store, run.metadata, typed, true, run.lifecycle.state === "interrupted" ? "interrupted" : "failed"); run.update?.(workflowToolUpdate(persisted)); }
       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) => {
       await run.lifecycle.enter();
+      const conversationId = identity.conversation ? conversationIdentityPath(identity) : undefined;
+      const conversationLock = conversationId ? `${run.store.runId}:${conversationId}` : "";
       try {
-        const path = agentIdentityPath(identity);
+        const path = conversationId ? conversationTurnPath(identity) : agentIdentityPath(identity);
         const replayed = await run.store.replay(path);
-        if (replayed) return replayed.value;
+        if (replayed) {
+          if (conversationId) {
+            const conversation = await run.store.conversation(conversationId);
+            if (!conversation || conversation.head.turn < (identity.conversation?.turn ?? 0)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Completed conversation turn has no persisted head");
+          }
+          return replayed.value;
+        }
+        if (conversationId) {
+          if (conversationLocks.has(conversationLock)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation turns cannot overlap");
+          const conversation = await run.store.conversation(conversationId);
+          if (conversation ? conversation.head.turn + 1 !== identity.conversation?.turn : identity.conversation?.turn !== 1) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation turn does not continue its persisted head");
+          conversationLocks.add(conversationLock);
+        }
         const worktree = agentWorktree(identity);
-        const cwd = worktree.worktreeOwner ? (await run.store.worktree(worktree.worktreeOwner)).cwd : run.store.cwd;
+        const cwd = worktree.worktreeOwner ? (await persistWorktree(run.store, run.metadata, worktree.worktreeOwner)).cwd : run.store.cwd;
         const role = typeof options.role === "string" ? options.role : undefined;
         const model = typeof options.model === "string" ? options.model : undefined;
         const thinking = parseThinking(options.thinking);
@@ -1904,21 +2538,86 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         const label = displayAgentName(requestedLabel, role, resolved.model);
         const tools = resolved.tools;
         const schema = object(options.outputSchema) ? options.outputSchema : undefined;
-        const spawned = scheduler.spawn(run.store.runId, prompt, { label, ...(requestedLabel ? { requestedLabel } : {}), ...(identity.parentBreadcrumb ? { parentBreadcrumb: identity.parentBreadcrumb } : {}), cwd, tools, ...worktree, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(schema ? { schema } : {}), ...(typeof options.retries === "number" ? { retries: options.retries } : {}), ...(positiveInteger(options.timeoutMs) || options.timeoutMs === null ? { timeoutMs: options.timeoutMs } : {}) });
+        const spawned = scheduler.spawn(run.store.runId, prompt, { label, ...(requestedLabel ? { requestedLabel } : {}), ...(identity.parentBreadcrumb ? { parentBreadcrumb: identity.parentBreadcrumb } : {}), cwd, tools, ...worktree, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(schema ? { schema } : {}), ...(typeof options.retries === "number" ? { retries: options.retries } : {}), ...(positiveInteger(options.timeoutMs) || options.timeoutMs === null ? { timeoutMs: options.timeoutMs } : {}), ...(conversationId ? { conversation: { id: conversationId, turn: identity.conversation?.turn ?? 0 } } : {}), agentOptions: options, agentIdentity: identity });
         const cancel = () => { scheduler.cancel(spawned.id); };
         signal.addEventListener("abort", cancel, { once: true });
         const outcome = await spawned.result.finally(() => { signal.removeEventListener("abort", cancel); });
         if (!outcome.ok) throw new WorkflowError(outcome.error.code as WorkflowErrorCode, outcome.error.message);
         await run.store.complete(path, outcome.value);
         return outcome.value;
-      } finally { 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 { await run.store.updateState((current) => ({ ...current, phase })); } finally { await run.lifecycle.leave(); } }, log: logBridge(run.lifecycle, run.metadata.name) }, run.store, runContext, variables, registry), controller.signal);
+      } finally { if (conversationLock) conversationLocks.delete(conversationLock); await run.lifecycle.leave(); }
+    }, checkpoint: checkpointBridge(run.store.runId, run.store, run.metadata, false, hasUI ? ui : undefined), phase: async (phase) => { await run.lifecycle.enter(); try { let previousPhase: string | undefined; const persisted = await persistRunState(run.store, run.metadata, (current) => { previousPhase = current.phase; return { ...current, phase }; }); await eventPublisher.phase(run.store, run.metadata, previousPhase, phase); runs.get(run.store.runId)?.update?.(workflowToolUpdate(persisted)); } finally { await run.lifecycle.leave(); } }, log: logBridge(run.lifecycle, run.metadata.name) }, run.store, runContext, variables, registry), controller.signal);
     run.execution = execution;
-    emitAsyncStarted(run.store, run.metadata);
-    const completion = execution.result.then(async (value) => { await scheduler.flush(); const resultPath = await run.store.saveResult(value); await run.lifecycle.terminal("completed"); emitAsyncComplete(run.store, "complete"); return { value, resultPath }; }, async (error: unknown) => { await scheduler.flush(); if (run.lifecycle.state !== "stopped" && run.lifecycle.state !== "interrupted") await run.lifecycle.terminal("failed"); const typed = error instanceof WorkflowError ? error : new WorkflowError(errorCode(error) ?? "INTERNAL_ERROR", errorText(error)); await run.store.updateState((current) => ({ ...current, error: { code: typed.code, message: typed.message } })); emitAsyncComplete(run.store, run.lifecycle.state === "stopped" ? "stopped" : "failed", typed); if (run.lifecycle.state !== "stopped" && run.lifecycle.state !== "interrupted") deliverFailure(pi, run.metadata.name, error); });
-    run.completion = completion;
+    const completion = execution.result.then(async (value) => {
+      await scheduler.flush();
+      if (run.budget.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
+      const resultPath = await run.store.saveResult(value);
+      await run.lifecycle.terminal("completed", "completed");
+      await eventPublisher.runCompleted(run.store, run.metadata, resultPath, true);
+      return { value, resultPath };
+    }).catch(async (error: unknown) => {
+      await scheduler.flush();
+      const typed = error instanceof WorkflowError ? error : new WorkflowError(errorCode(error) ?? "INTERNAL_ERROR", errorText(error));
+      if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) await run.lifecycle.terminal(typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
+      const persisted = await persistRunState(run.store, run.metadata, (current) => ({ ...current, ...run.budget.snapshot(), error: { code: typed.code, message: typed.message } }));
+      const state = run.lifecycle.state === "stopped" || run.lifecycle.state === "interrupted" || run.lifecycle.state === "budget_exhausted" ? run.lifecycle.state : "failed";
+      await eventPublisher.runFailed(run.store, run.metadata, typed, true, state);
+      run.update?.(workflowToolUpdate(persisted));
+      if (!["stopped", "interrupted", "budget_exhausted"].includes(run.lifecycle.state)) deliverFailure(pi, run.metadata.name, error);
+    });
     void completion;
   };
+  const applyBudgetDecision = async (request: BudgetApprovalRequest, approved: boolean): Promise<BudgetDecisionResult> => {
+    const run = runs.get(request.runId);
+    if (!run) throw new WorkflowError("RESUME_INCOMPATIBLE", `Unknown workflow run: ${request.runId}`);
+    if (!approved) return { state: "budget_exhausted", approved: false };
+    const nextBudget = validateBudget(request.proposed);
+    const nextVersion = request.budgetVersion + 1;
+    const runtime = new WorkflowBudgetRuntime(nextBudget, nextVersion, request.consumed, run.budget.events, { active: false });
+    run.budget = runtime;
+    await persistRunState(run.store, run.metadata, (current) => { const next = { ...current, ...runtime.snapshot(), budgetVersion: nextVersion }; if (nextBudget) next.budget = nextBudget; else delete next.budget; return next; });
+    await coldResumeRun(run, false, {}, true);
+    return { state: "running", approved: true };
+  };
+  const resumeWorkflowRun = async (runId: string, rawPatch?: unknown): Promise<Record<string, JsonValue>> => {
+    const run = runs.get(runId);
+    if (!run) throw new WorkflowError("RESUME_INCOMPATIBLE", `Unknown workflow run: ${runId}`);
+    const loaded = await run.store.load();
+    if (loaded.run.state !== "budget_exhausted") throw new WorkflowError("RESUME_INCOMPATIBLE", "Only budget-exhausted runs can be resumed with workflow_resume");
+    const currentBudget = validateBudget(loaded.run.budget ?? loaded.snapshot.budget);
+    const patch = rawPatch === undefined ? {} : validateBudgetPatch(rawPatch);
+    const nextBudget = mergeBudget(currentBudget, patch);
+    const usage = budgetUsage(loaded.run.usage);
+    if (!resumeBudgetAllowed(nextBudget, usage)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Every exhausted hard budget must be raised above retained usage or removed");
+    if (budgetRelaxed(currentBudget, nextBudget)) {
+      const proposalId = randomUUID();
+      const request: BudgetApprovalRequest = { kind: "budget", proposalId, runId, consumed: usage, previous: currentBudget ?? {}, proposed: nextBudget ?? {}, budgetVersion: loaded.run.budgetVersion ?? 1 };
+      const decision = new Promise<BudgetDecisionResult>((resolve) => { run.budgetResolvers.set(proposalId, resolve); });
+      try { await run.store.requestWorkflowDecision(request); await appendBudgetDecisionEvent(run, request, "adjustment_requested"); } catch (error) { run.budgetResolvers.delete(proposalId); throw error; }
+      deliver(pi, budgetDecisionDelivery(run.metadata, request));
+      const decisionResult = await decision;
+      return { state: decisionResult.state };
+    }
+    const changed = JSON.stringify(currentBudget ?? {}) !== JSON.stringify(nextBudget ?? {});
+    if (changed) {
+      const nextVersion = (loaded.run.budgetVersion ?? 1) + 1;
+      const runtime = new WorkflowBudgetRuntime(nextBudget, nextVersion, usage, loaded.run.budgetEvents, { active: false });
+      run.budget = runtime;
+      await persistRunState(run.store, run.metadata, (current) => { const next = { ...current, ...runtime.snapshot(), budgetVersion: nextVersion }; if (nextBudget) next.budget = nextBudget; else delete next.budget; return next; });
+    }
+    await coldResumeRun(run, false, {}, true);
+    return { state: "running" };
+  };
+  pi.registerTool({
+    name: "workflow_resume",
+    label: "Workflow Resume",
+    description: "Resume an exhausted workflow with unchanged or patched aggregate budgets",
+    parameters: Type.Object({ runId: Type.String(), budget: Type.Optional(Type.Unknown()) }, { additionalProperties: false }),
+    async execute(_id, params) {
+      try { const result = await resumeWorkflowRun(params.runId, params.budget); return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: result }; }
+      catch (error) { throw mainAgentError(error); }
+    },
+  });
   pi.on("session_start", async (_event, ctx) => {
     if (sessionStarted) return;
     sessionStarted = true;
@@ -1931,18 +2630,25 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       const store = new RunStore(ctx.cwd, ctx.sessionManager.getSessionId(), runId, home);
       let loaded: { run: PersistedRun; snapshot: Readonly<LaunchSnapshot> };
       try { loaded = await store.load(); } catch { if (!await store.isComplete()) await store.delete(true).catch(() => undefined); continue; }
-      if (["completed", "failed", "stopped"].includes(loaded.run.state)) continue;
-      if (loaded.run.state !== "interrupted") {
-        await store.updateState((current) => ["completed", "failed", "stopped", "interrupted"].includes(current.state) ? current : { ...current, state: "interrupted" });
+      if (loaded.run.state === "completed" || loaded.run.state === "failed" || loaded.run.state === "stopped") { terminalRunStates.set(runId, loaded.run.state); continue; }
+      if (loaded.run.state !== "interrupted" && loaded.run.state !== "budget_exhausted") {
+        const previousState = loaded.run.state;
+        await store.updateState((current) => ["completed", "failed", "stopped", "interrupted", "budget_exhausted"].includes(current.state) ? current : { ...current, state: "interrupted" });
+        loaded = { ...loaded, run: (await store.load()).run };
+        await eventPublisher.runState(store, loaded.snapshot.metadata, previousState, "interrupted", "session_shutdown");
         loaded = { ...loaded, run: (await store.load()).run };
       }
       const model = modelSpec(loaded.snapshot.models[0] ?? "", { provider: ctx.model?.provider ?? "", model: ctx.model?.id ?? "", thinking: pi.getThinkingLevel() });
-      const lifecycle = lifecycleFor(store, loaded.run.state);
+      const budget = validateBudget(loaded.run.budget ?? loaded.snapshot.budget);
+      eventPublisher.seedBudget(runId, loaded.run.budgetEvents);
+      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, 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), agentDefinitions: roleDefinitions, runStore: store, providerPause }, createSession), store, metadata: loaded.snapshot.metadata, model, lifecycle, abortController: new AbortController(), checkpointResolvers: new Map() });
+      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() });
       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.`);
-      scheduler.restoreRun(runId, loaded.snapshot.settings.concurrency, loaded.snapshot.settings.maxAgentLaunches, loaded.snapshot.identityVersion === LAUNCH_SNAPSHOT_IDENTITY_VERSION ? await store.loadOwnership() : []);
+      for (const decision of await store.pendingWorkflowDecisions()) deliver(pi, budgetDecisionDelivery(loaded.snapshot.metadata, decision));
+      scheduler.restoreRun(runId, loaded.snapshot.settings.concurrency, loaded.snapshot.identityVersion === LAUNCH_SNAPSHOT_IDENTITY_VERSION ? await store.loadOwnership() : [], () => runs.get(runId)?.budget.checkAgentLaunch());
     }
     const resumeSelect = (ctx.ui as unknown as { select?: (prompt: string, options: string[]) => Promise<string | undefined> } | undefined)?.select;
     if (ctx.hasUI && resumeSelect) {
@@ -1954,7 +2660,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         if (choice && choice !== "Skip") {
           const toResume = choice === "Resume all" ? interrupted : interrupted.filter((_, i) => labels[i] === choice);
           for (const run of toResume) {
-            try { await coldResumeRun(run, true, ctx.ui, projectTrusted(ctx)); ctx.ui.notify(`Resumed workflow ${run.metadata.name}.`, "info"); }
+            try { await coldResumeRun(run, true, ctx.ui, projectTrusted(ctx), ctx); ctx.ui.notify(`Resumed workflow ${run.metadata.name}.`, "info"); }
             catch (err) { ctx.ui.notify(`Cannot resume ${run.metadata.name}: ${err instanceof Error ? err.message : String(err)}`, "warning"); }
           }
         }
@@ -1977,17 +2683,21 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
     parameters: WORKFLOW_TOOL_PARAMETERS,
     async execute(_id, params, signal, onUpdate, ctx) {
       try {
+      const settingsPath = workflowSettingsPath();
+      const defaults = loadSettings(settingsPath);
       if (!ctx.model) throw new WorkflowError("UNKNOWN_MODEL", "A launching model is required");
-      const defaults = loadSettings();
-      const settings = Object.freeze({ concurrency: params.concurrency ?? defaults.concurrency, maxAgentLaunches: params.maxAgentLaunches ?? defaults.maxAgentLaunches });
+      const settings = Object.freeze({ concurrency: params.concurrency ?? defaults.concurrency, ...(defaults.modelAliases ? { modelAliases: defaults.modelAliases } : {}) });
+      const budget = validateBudget(params.budget);
       const rootModel: ModelSpec = { provider: ctx.model.provider, model: ctx.model.id, thinking: pi.getThinkingLevel() };
       const rootModelName = `${rootModel.provider}/${rootModel.model}`;
-      const modelRegistry = (ctx as unknown as { modelRegistry?: { getAvailable(): Array<{ provider: string; id: string }> } }).modelRegistry;
-      const availableModels = new Set((modelRegistry?.getAvailable() ?? [ctx.model]).map((model) => `${model.provider}/${model.id}`));
-      availableModels.add(rootModelName);
-      const rootTools = pi.getActiveTools().filter((name) => name !== "workflow" && name !== "workflow_respond" && name !== "workflow_catalog");
+      const modelRegistry = (ctx as unknown as { modelRegistry?: { getAll?: () => Array<{ provider: string; id: string }>; getAvailable?: () => Array<{ provider: string; id: string }> } }).modelRegistry;
+      const knownModels = new Set((modelRegistry?.getAll?.() ?? modelRegistry?.getAvailable?.() ?? [ctx.model]).map((model) => `${model.provider}/${model.id}`));
+      knownModels.add(rootModelName);
+      const availableModels = knownModels;
+      const rootTools = pi.getActiveTools().filter((name) => name !== "workflow" && name !== "workflow_respond" && name !== "workflow_stop" && name !== "workflow_catalog");
       const trustedProject = projectTrusted(ctx);
-      const validated = validateWorkflowLaunchWithRegistry(params, { cwd: ctx.cwd, projectTrusted: trustedProject, availableModels, rootTools: new Set(rootTools) }, registry);
+      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;
       await ensureSessionLease(ctx.cwd, ctx.sessionManager.getSessionId());
       const runId = randomUUID();
@@ -2000,25 +2710,41 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
       const store = new RunStore(ctx.cwd, ctx.sessionManager.getSessionId(), runId, home);
       const roles = Object.fromEntries(roleNames.map((role) => [role, agentDefinitions[role]])) as Record<string, AgentDefinition>;
       const projectRoles = roleNames.filter((role) => projectAgentDefinitions[role] !== undefined);
-      const roleModels = roleNames.flatMap((role) => { const model = agentDefinitions[role]?.model; return model ? [modelCapability(model)] : []; });
+      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, models: snapshotModels, tools: rootTools, agentTypes: checked.referenced.agentTypes, roles, projectRoles, schemas: checked.schemas });
-      await store.create({ id: runId, workflowName: checked.metadata.name, cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId(), state: "running", agents: [], nativeSessions: [] }, snapshot);
-      const lifecycle = lifecycleFor(store, "running");
+      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 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);
+      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, agentDefinitions, runStore: store, providerPause }, createSession);
-      runs.set(runId, { executor, store, metadata: checked.metadata, model: rootModel, lifecycle, abortController: runController, checkpointResolvers: new Map(), ...(params.foreground && onUpdate ? { update: onUpdate } : {}) });
+      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 } : {}) });
       if (params.foreground && onUpdate) onUpdate(workflowToolUpdate((await store.load()).run));
-      scheduler.addRun(runId, settings.concurrency, settings.maxAgentLaunches);
+      scheduler.addRun(runId, settings.concurrency, () => runs.get(runId)?.budget.checkAgentLaunch());
       const execution = runWorkflow(script, args, withWorkflowFunctions({ agent: async (prompt, options, agentSignal, identity) => {
         await lifecycle.enter();
+        const conversationId = identity.conversation ? conversationIdentityPath(identity) : undefined;
+        const conversationLock = conversationId ? `${runId}:${conversationId}` : "";
         try {
-          const path = agentIdentityPath(identity);
+          const path = conversationId ? conversationTurnPath(identity) : agentIdentityPath(identity);
           const replayed = await store.replay(path);
-          if (replayed) return replayed.value;
+          if (replayed) {
+            if (conversationId) {
+              const conversation = await store.conversation(conversationId);
+              if (!conversation || conversation.head.turn < (identity.conversation?.turn ?? 0)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Completed conversation turn has no persisted head");
+            }
+            return replayed.value;
+          }
+          if (conversationId) {
+            if (conversationLocks.has(conversationLock)) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation turns cannot overlap");
+            const conversation = await store.conversation(conversationId);
+            if (conversation ? conversation.head.turn + 1 !== identity.conversation?.turn : identity.conversation?.turn !== 1) throw new WorkflowError("RESUME_INCOMPATIBLE", "Conversation turn does not continue its persisted head");
+            conversationLocks.add(conversationLock);
+          }
           const worktree = agentWorktree(identity);
-          const cwd = worktree.worktreeOwner ? (await store.worktree(worktree.worktreeOwner)).cwd : ctx.cwd;
+          const cwd = worktree.worktreeOwner ? (await persistWorktree(store, checked.metadata, worktree.worktreeOwner)).cwd : ctx.cwd;
           const role = typeof options.role === "string" ? options.role : undefined;
           const model = typeof options.model === "string" ? options.model : undefined;
           const thinking = parseThinking(options.thinking);
@@ -2027,30 +2753,46 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           const label = displayAgentName(requestedLabel, role, resolved.model);
           const tools = resolved.tools;
           const schema = object(options.outputSchema) ? options.outputSchema : undefined;
-          const spawned = scheduler.spawn(runId, prompt, { label, ...(requestedLabel ? { requestedLabel } : {}), ...(identity.parentBreadcrumb ? { parentBreadcrumb: identity.parentBreadcrumb } : {}), cwd, tools, ...worktree, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(schema ? { schema } : {}), ...(typeof options.retries === "number" && Number.isInteger(options.retries) && options.retries >= 0 ? { retries: options.retries } : {}), ...(positiveInteger(options.timeoutMs) || options.timeoutMs === null ? { timeoutMs: options.timeoutMs } : {}) });
+          const spawned = scheduler.spawn(runId, prompt, { label, ...(requestedLabel ? { requestedLabel } : {}), ...(identity.parentBreadcrumb ? { parentBreadcrumb: identity.parentBreadcrumb } : {}), cwd, tools, ...worktree, ...(model ? { model } : {}), ...(thinking ? { thinking } : {}), ...(role ? { role } : {}), ...(schema ? { schema } : {}), ...(typeof options.retries === "number" ? { retries: options.retries } : {}), ...(positiveInteger(options.timeoutMs) || options.timeoutMs === null ? { timeoutMs: options.timeoutMs } : {}), ...(conversationId ? { conversation: { id: conversationId, turn: identity.conversation?.turn ?? 0 } } : {}), agentOptions: options, agentIdentity: identity });
           const cancel = () => { scheduler.cancel(spawned.id); };
           if (agentSignal.aborted) cancel(); else agentSignal.addEventListener("abort", cancel, { once: true });
           const outcome = await spawned.result.finally(() => { agentSignal.removeEventListener("abort", cancel); });
           if (!outcome.ok) throw new WorkflowError(outcome.error.code as WorkflowErrorCode, outcome.error.message);
           await store.complete(path, outcome.value);
           return outcome.value;
-        } finally { await lifecycle.leave(); }
+        } finally { if (conversationLock) conversationLocks.delete(conversationLock); await lifecycle.leave(); }
       }, checkpoint: checkpointBridge(runId, store, checked.metadata, Boolean(params.foreground), params.foreground && ctx.hasUI ? ctx.ui : undefined), phase: async (phase) => {
         await lifecycle.enter();
         try {
-          const run = await store.updateState((current) => ({ ...current, phase }));
-          runs.get(runId)?.update?.(workflowToolUpdate(run));
+          let previousPhase: string | undefined;
+          const persisted = await persistRunState(store, checked.metadata, (current) => { previousPhase = current.phase; return { ...current, phase }; });
+          await eventPublisher.phase(store, checked.metadata, previousPhase, phase);
+          runs.get(runId)?.update?.(workflowToolUpdate(persisted));
         } finally { await lifecycle.leave(); }
       }, log: logBridge(lifecycle, checked.metadata.name) }, store, runContext, variables, registry), runController.signal);
       (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).execution = execution;
-      if (background) emitAsyncStarted(store, checked.metadata);
-      const finish = execution.result.then(async (value) => { await scheduler.flush(); const resultPath = await store.saveResult(value); await lifecycle.terminal("completed"); return { value, resultPath }; }, async (error: unknown) => { await scheduler.flush(); const typed = error instanceof WorkflowError ? error : new WorkflowError("INTERNAL_ERROR", String(error)); if (lifecycle.state !== "stopped" && lifecycle.state !== "interrupted") await lifecycle.terminal(typed.code === "CANCELLED" ? "stopped" : "failed"); await store.updateState((current) => ({ ...current, error: { code: typed.code, message: typed.message } })); throw typed; });
+      await eventPublisher.runStarted(store, checked.metadata, background);
+      const finish = execution.result.then(async (value) => {
+        await scheduler.flush();
+        if (budgetRuntime.hardExhausted) throw new WorkflowError("BUDGET_EXHAUSTED", "Budgeted work was attempted after hard exhaustion");
+        const resultPath = await store.saveResult(value);
+        await lifecycle.terminal("completed", "completed");
+        await eventPublisher.runCompleted(store, checked.metadata, resultPath, background);
+        return { value, resultPath };
+      }).catch(async (error: unknown) => {
+        await scheduler.flush();
+        const typed = error instanceof WorkflowError ? error : new WorkflowError("INTERNAL_ERROR", String(error));
+        if (!["stopped", "interrupted", "budget_exhausted"].includes(lifecycle.state)) await lifecycle.terminal(typed.code === "CANCELLED" ? "stopped" : typed.code === "BUDGET_EXHAUSTED" ? "budget_exhausted" : "failed", typed.code);
+        await persistRunState(store, checked.metadata, (current) => ({ ...current, ...budgetRuntime.snapshot(), error: { code: typed.code, message: typed.message } }));
+        const state = lifecycle.state === "stopped" || lifecycle.state === "interrupted" || lifecycle.state === "budget_exhausted" ? lifecycle.state : "failed";
+        await eventPublisher.runFailed(store, checked.metadata, typed, background, state);
+        throw typed;
+      });
       (runs.get(runId) as NonNullable<ReturnType<typeof runs.get>>).completion = finish;
       if (background) {
         void finish.then(async ({ value, resultPath }) => {
-          emitAsyncComplete(store, "complete");
           deliver(pi, completionDelivery(checked.metadata.name, value, resultPath, await store.changedWorktrees()));
-        }, (error: unknown) => { emitAsyncComplete(store, lifecycle.state === "stopped" ? "stopped" : "failed", error instanceof Error ? error : new Error(errorText(error))); deliverFailure(pi, checked.metadata.name, error); });
+        }, (error: unknown) => { deliverFailure(pi, checked.metadata.name, error); });
         return { content: [{ type: "text" as const, text: JSON.stringify({ runId, state: "running" }) }], details: { runId, preview: `Started workflow ${runId}.` } };
       }
       const { value } = await finish;
@@ -2098,7 +2840,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
         return entries.filter((entry): entry is { store: RunStore; loaded: { run: PersistedRun; snapshot: Readonly<LaunchSnapshot> } } => entry !== undefined);
       };
       let stores = await loadStores();
-      const usage = "Usage: /workflow [doctor], or /workflow pause|resume|stop|approve|reject|delete <run-id> [checkpoint]";
+      const usage = "Usage: /workflow [doctor|model-aliases], or /workflow pause|resume|stop|approve|reject|delete <run-id> [checkpoint or proposal-id]. Use workflow_resume for budget patches."
       const setWorkflowStatus = (text: string | undefined) => {
         const setStatus = (ctx.ui as unknown as { setStatus?: (key: string, text?: string) => void }).setStatus;
         setStatus?.call(ctx.ui, "workflow-stop", text);
@@ -2114,22 +2856,44 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             ctx.ui.notify(accepted ? `${action === "approve" ? "Approved" : "Rejected"} checkpoint ${rest.join(" ")}.` : "Checkpoint is not awaiting a response.", accepted ? "info" : "warning");
             return keepContext ? "dashboard" : "done";
           }
+          if ((action === "budget-approve" || action === "budget-reject") && runId && rest[0]) {
+            const result = await answerBudgetDecision(runId, rest[0], action === "budget-approve", true);
+            ctx.ui.notify(result ? `Budget adjustment ${rest[0]} ${result.approved ? "approved" : "rejected"}.` : "Budget proposal is not pending.", result ? "info" : "warning");
+            return keepContext ? "dashboard" : "done";
+          }
           if (action === "delete" && stored) {
             if (!["completed", "failed", "stopped"].includes(stored.loaded.run.state)) { ctx.ui.notify("Stop the workflow before deleting it.", "warning"); return keepContext ? "dashboard" : "done"; }
             if (!await ctx.ui.confirm("Delete workflow?", `Delete ${stored.loaded.run.workflowName} (${stored.store.runId}) and all owned artifacts? This cannot be undone.`)) return keepContext ? "dashboard" : "done";
-            await stored.store.delete(true); runs.delete(stored.store.runId); ctx.ui.notify(`Deleted workflow ${stored.store.runId}.`, "info"); return keepContext ? "picker" : "done";
+            await stored.store.delete(true); runs.delete(stored.store.runId); terminalRunStates.delete(stored.store.runId); ctx.ui.notify(`Deleted workflow ${stored.store.runId}.`, "info"); return keepContext ? "picker" : "done";
           }
           if (action === "pause" && run) { await run.lifecycle.pause(); ctx.ui.notify(`Paused workflow ${run.store.runId}.`, "info"); return keepContext ? "dashboard" : "done"; }
           if (action === "resume" && run) {
-            if (run.lifecycle.state === "interrupted") await coldResumeRun(run, ctx.hasUI, ctx.ui, projectTrusted(ctx));
-            else await run.lifecycle.resume();
-            ctx.ui.notify(`Resumed workflow ${run.store.runId}.`, "info"); return keepContext ? "dashboard" : "done";
+            if (run.lifecycle.state === "budget_exhausted") {
+              const patch: unknown = rest.length ? JSON.parse(rest.join(" ")) as unknown : undefined;
+              const result = await resumeWorkflowRun(run.store.runId, patch);
+              ctx.ui.notify(result.state === "running" ? `Resumed workflow ${run.store.runId}.` : `Budget adjustment for ${run.store.runId} is awaiting approval.`, result.state === "running" ? "info" : "warning");
+            } else {
+              if (run.lifecycle.state === "interrupted") await coldResumeRun(run, ctx.hasUI, ctx.ui, projectTrusted(ctx), ctx);
+              else {
+                if (run.lifecycle.state === "paused") await refreshPausedRunAliases(run, ctx);
+                await run.lifecycle.resume();
+              }
+              ctx.ui.notify(`Resumed workflow ${run.store.runId}.`, "info");
+            }
+            return keepContext ? "dashboard" : "done";
+          }
+          if (action === "adjust" && run?.lifecycle.state === "budget_exhausted") {
+            const input = await (ctx.ui as unknown as { input?: (title: string, placeholder?: string) => Promise<string | undefined> }).input?.("Budget patch (JSON)", "{\"tokens\":{\"hard\":null}}" );
+            if (input === undefined) return keepContext ? "dashboard" : "done";
+            const result = await resumeWorkflowRun(run.store.runId, JSON.parse(input));
+            ctx.ui.notify(result.state === "running" ? `Resumed workflow ${run.store.runId}.` : `Budget adjustment for ${run.store.runId} is awaiting approval.`, result.state === "running" ? "info" : "warning");
+            return keepContext ? "dashboard" : "done";
           }
           if (action === "stop" && run) {
             const workflowName = stored?.loaded.run.workflowName ?? run.metadata.name;
             if (keepContext && !await ctx.ui.confirm("Stop workflow?", `Stop workflow ${workflowName} (${run.store.runId})? This cannot be undone.`)) return "dashboard";
             if (keepContext) status(`Stopping workflow ${workflowName}...`);
-            await run.lifecycle.terminal("stopped"); run.abortController.abort(); run.execution?.cancel(); await scheduler.cancelRun(run.store.runId); await scheduler.flush();
+            await stopWorkflowRun(run.store.runId);
             if (keepContext) status(`Workflow ${run.store.runId} stopped.`);
             ctx.ui.notify(`Stopped workflow ${run.store.runId}.`, "info"); return keepContext ? "dashboard" : "done";
           }
@@ -2144,10 +2908,76 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           return "dashboard";
         }
       };
+      const manageAliases = async (): Promise<void> => {
+        const settingsPath = workflowSettingsPath();
+        const modelRegistry = (ctx as unknown as { modelRegistry?: { getAvailable?: () => Array<{ provider: string; id: string }> } }).modelRegistry;
+        const available = () => [...new Set((modelRegistry?.getAvailable?.() ?? []).map((model) => `${model.provider}/${model.id}`))].sort();
+        const selectTarget = async (): Promise<string | undefined> => {
+          const models = available();
+          const choice = await ctx.ui.select("Model alias target", [...models, "Manual model ID", "Back"]);
+          if (!choice || choice === "Back") return undefined;
+          if (choice !== "Manual model ID") return choice;
+          return (await ctx.ui.input("Manual model ID", "provider/model[:thinking]"))?.trim() || undefined;
+        };
+        const save = (aliases: Readonly<Record<string, string>>): boolean => {
+          try { saveModelAliases(settingsPath, aliases); ctx.ui.notify(`Saved model aliases to ${settingsPath}.`, "info"); return true; }
+          catch (error) { ctx.ui.notify(`${settingsPath}: ${error instanceof Error ? error.message : String(error)}`, "error"); return false; }
+        };
+        for (;;) {
+          let aliases: Readonly<Record<string, string>>;
+          try { aliases = loadSettings(settingsPath).modelAliases ?? {}; }
+          catch (error) { ctx.ui.notify(`${settingsPath}: ${error instanceof Error ? error.message : String(error)}`, "error"); return; }
+          const names = Object.keys(aliases).sort();
+          const listing = names.length ? names.map((name) => `${name} = ${aliases[name] ?? ""}`).join("\n") : "(none)";
+          const options = ["Add alias", ...names.map((name) => `Edit ${name}`), ...names.map((name) => `Delete ${name}`), "Back"];
+          const choice = await ctx.ui.select(`Model aliases\n${listing}`, options);
+          if (!choice || choice === "Back") return;
+          if (choice === "Add alias") {
+            const name = (await ctx.ui.input("Alias name", "reviewer-model"))?.trim();
+            if (!name) continue;
+            if (Object.prototype.hasOwnProperty.call(aliases, name)) { ctx.ui.notify(`Alias ${name} already exists; choose Edit ${name}.`, "warning"); continue; }
+            const target = await selectTarget();
+            if (!target) continue;
+            const next = { ...aliases, [name]: target };
+            try { validateModelAliases(next, settingsPath); } catch (error) { ctx.ui.notify(`${settingsPath}: ${error instanceof Error ? error.message : String(error)}`, "error"); continue; }
+            const parsed = parseModelReference(target);
+            if (!available().includes(`${parsed.provider}/${parsed.model}`)) {
+              ctx.ui.notify(`Warning: ${target} is not currently available in Pi.`, "warning");
+              if (!await ctx.ui.confirm("Save unknown model?", "Save this target for cross-machine portability?")) continue;
+            }
+            save(next);
+            continue;
+          }
+          const edit = /^Edit (.+)$/.exec(choice);
+          if (edit?.[1]) {
+            const target = await selectTarget();
+            if (!target) continue;
+            const next = { ...aliases, [edit[1]]: target };
+            try { validateModelAliases(next, settingsPath); } catch (error) { ctx.ui.notify(`${settingsPath}: ${error instanceof Error ? error.message : String(error)}`, "error"); continue; }
+            const parsed = parseModelReference(target);
+            if (!available().includes(`${parsed.provider}/${parsed.model}`)) {
+              ctx.ui.notify(`Warning: ${target} is not currently available in Pi.`, "warning");
+              if (!await ctx.ui.confirm("Save unknown model?", "Save this target for cross-machine portability?")) continue;
+            }
+            save(next);
+            continue;
+          }
+          const deletion = /^Delete (.+)$/.exec(choice);
+          if (deletion?.[1] && await ctx.ui.confirm("Delete model alias?", `Delete ${deletion[1]}? Future workflow resumes using this alias may fail.`)) {
+            const next = Object.fromEntries(Object.entries(aliases).filter(([name]) => name !== deletion[1]));
+            save(next);
+          }
+        }
+      };
+      if (command === "model-aliases") {
+        if (!ctx.hasUI) { ctx.ui.notify("Model alias management requires UI.", "warning"); return; }
+        await manageAliases();
+        return;
+      }
       if (!command) {
         for (;;) {
-          if (!stores.length) { ctx.ui.notify("No workflow runs in this session.", "info"); return; }
           if (!ctx.hasUI) {
+            if (!stores.length) { ctx.ui.notify("No workflow runs in this session.", "info"); return; }
             const details = await Promise.all(stores.map(async ({ store, loaded }) => formatNavigatorRun(loaded, await store.awaitingCheckpoints(), await store.worktrees())));
             ctx.ui.notify(details.join("\n\n"), "info"); return;
           }
@@ -2155,13 +2985,14 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
           const labels = navigatorRunLabels(sorted);
           const terminalStates = new Set(["completed", "failed", "stopped"]);
           const hasCompleted = sorted.some(({ loaded: { run } }) => run.state === "completed");
-          const pickerOptions = [...labels, ...(hasCompleted ? ["Delete all completed"] : []), "Close"];
+          const pickerOptions = [...labels, "Model aliases", "Close", ...(hasCompleted ? ["Delete all completed"] : [])];
           const runChoice = await ctx.ui.select("Workflows\n", pickerOptions);
           if (!runChoice || runChoice === "Close") return;
+          if (runChoice === "Model aliases") { await manageAliases(); stores = await loadStores(); continue; }
           if (runChoice === "Delete all completed") {
             if (!await ctx.ui.confirm("Delete completed runs?", "Delete all completed workflow runs and their artifacts? This cannot be undone.")) continue;
             for (const entry of sorted) {
-              if (entry.loaded.run.state === "completed") { await entry.store.delete(true); runs.delete(entry.store.runId); }
+              if (entry.loaded.run.state === "completed") { await entry.store.delete(true); runs.delete(entry.store.runId); terminalRunStates.delete(entry.store.runId); }
             }
             ctx.ui.notify("Deleted all completed workflow runs.", "info"); stores = await loadStores(); continue;
           }
@@ -2178,6 +3009,38 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
               ctx.ui.notify(`Failed to copy ${artifact}: ${error instanceof Error ? error.message : String(error)}`, "error");
             }
           };
+          const openTranscript = async (transcript: string): Promise<void> => {
+            try {
+              const entries = SessionManager.open(transcript).buildContextEntries();
+              if (ctx.mode !== "tui") { ctx.ui.notify(`Transcript: ${transcript}`, "info"); return; }
+              await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
+                let offset = 0;
+                let renderedLines: string[] = [];
+                const viewport = () => Math.max(1, (((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24) - 3);
+                const move = (delta: number) => { offset = Math.max(0, Math.min(Math.max(0, renderedLines.length - viewport()), offset + delta)); };
+                return {
+                  render(width: number) {
+                    renderedLines = transcriptLines(entries).flatMap((line) => line ? truncateToVisualLines(line, Number.MAX_SAFE_INTEGER, width, 0).visualLines : [""]);
+                    offset = Math.min(offset, Math.max(0, renderedLines.length - viewport()));
+                    return [theme.fg("accent", "Native Pi transcript"), ...renderedLines.slice(offset, offset + viewport()), "", theme.fg("dim", "↑↓/pgup/pgdn scroll · esc close")];
+                  },
+                  invalidate() {},
+                  handleInput(data: string) {
+                    if (keybindings.matches(data, "tui.select.up")) move(-1);
+                    else if (keybindings.matches(data, "tui.select.down")) move(1);
+                    else if (keybindings.matches(data, "tui.select.pageUp")) move(-viewport());
+                    else if (keybindings.matches(data, "tui.select.pageDown")) move(viewport());
+                    else if (keybindings.matches(data, "tui.editor.cursorLineStart")) offset = 0;
+                    else if (keybindings.matches(data, "tui.editor.cursorLineEnd")) offset = Math.max(0, renderedLines.length - viewport());
+                    else if (keybindings.matches(data, "tui.select.cancel")) done(undefined);
+                    tui.requestRender();
+                  },
+                };
+              }, { overlay: true });
+            } catch (error) {
+              ctx.ui.notify(`Cannot open transcript: ${error instanceof Error ? error.message : String(error)}`, "warning");
+            }
+          };
           const loadDashboard = async () => {
             const loaded = await store.load();
             const checkpoints = await store.awaitingCheckpoints();
@@ -2189,6 +3052,12 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             const addCopy = (label: string, value: string, artifact: string) => { actions.set(label, "copy"); copies.set(label, { value, artifact }); };
             if (loaded.run.state === "running") add("Pause", "pause");
             if (["paused", "interrupted"].includes(loaded.run.state)) add("Resume", "resume");
+            if (loaded.run.state === "budget_exhausted") { actions.set("Resume unchanged", `resume ${store.runId}`); actions.set("Adjust budget", `adjust ${store.runId}`); }
+            for (const decision of await store.pendingWorkflowDecisions()) {
+              const id = decision.proposalId.slice(0, 8);
+              actions.set(`Approve budget ${id}`, `budget-approve ${store.runId} ${decision.proposalId}`);
+              actions.set(`Reject budget ${id}`, `budget-reject ${store.runId} ${decision.proposalId}`);
+            }
             if (!terminalStates.has(loaded.run.state)) add("Stop", "stop");
             for (const cp of checkpoints) {
               if (ctx.mode === "tui") {
@@ -2203,18 +3072,59 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             if (ctx.mode !== "tui") actions.set("Refresh", "refresh");
             else actions.set("View script", "view-script");
             const transcripts = [...new Set([...loaded.run.agents.flatMap((agent) => (agent.attemptDetails ?? []).map((attempt) => attempt.sessionFile)), ...loaded.run.nativeSessions.map(({ sessionFile }) => sessionFile)])];
-            if (ctx.mode === "tui" && transcripts.length) actions.set("View transcript", "view-transcript");
-            if (transcripts.length) actions.set("Transcript paths", "transcripts");
+            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");
-              for (const worktree of worktrees) {
-                addCopy(`Copy branch (${worktree.owner})`, worktree.branch, "branch");
-                addCopy(`Copy worktree path (${worktree.owner})`, worktree.path, "worktree path");
+            }
+            return { dashboard: formatNavigatorDashboard(loaded.run, checkpoints, worktrees), actions, copies, reviews, transcripts, script: loaded.snapshot.script, agents: loaded.run.agents, worktrees };
+          };
+          const selectAgent = async (dashboard: Awaited<ReturnType<typeof loadDashboard>>): Promise<void> => {
+            const byId = new Map(dashboard.agents.map((agent) => [agent.id, agent]));
+            const title = (agent: AgentRecord): string => {
+              const parents: string[] = [];
+              for (let parentId = agent.parentId; parentId; parentId = byId.get(parentId)?.parentId) {
+                const parent = byId.get(parentId);
+                if (!parent) break;
+                parents.unshift(parent.label ?? parent.name);
+              }
+              return [...((agent.structuralPath ?? []).length ? [(agent.structuralPath ?? []).join(" > ")] : []), ...(agent.parentBreadcrumb ? [agent.parentBreadcrumb] : []), ...parents, agent.label ?? agent.name].join(" > ");
+            };
+            const labels = dashboard.agents.map((agent, index) => `#${String(index + 1)} ${title(agent)} [${agent.state}]`);
+            const selectedLabel = await ctx.ui.select("Agents", [...labels, "Back"]);
+            const selectedIndex = selectedLabel ? labels.indexOf(selectedLabel) : -1;
+            const selected = selectedIndex >= 0 ? dashboard.agents[selectedIndex] : undefined;
+            if (!selected) return;
+            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"] : []),
+              ...(worktree ? ["Copy branch", "Copy worktree path"] : []),
+              "Copy agent ID",
+              "Back",
+            ];
+            const chooseAttempt = async (): Promise<AgentAttemptSummary | undefined> => {
+              const choices = attempts.map((attempt) => `Attempt ${String(attempt.attempt)}`);
+              const choice = choices.length === 1 ? choices[0] : await ctx.ui.select("Transcript attempts", [...choices, "Back"]);
+              const index = choice ? choices.indexOf(choice) : -1;
+              return index >= 0 ? attempts[index] : undefined;
+            };
+            for (;;) {
+              const action = await ctx.ui.select(title(selected), actions);
+              if (!action || action === "Back") return;
+              if (action === "Copy agent ID") { await copyArtifact(selected.id, "agent ID"); continue; }
+              if (action === "Copy branch" && worktree) { await copyArtifact(worktree.branch, "branch"); continue; }
+              if (action === "Copy worktree path" && worktree) { await copyArtifact(worktree.path, "worktree path"); continue; }
+              if (action === "View transcript" || action === "Copy transcript path") {
+                const attempt = await chooseAttempt();
+                if (!attempt) continue;
+                if (action === "Copy transcript path") await copyArtifact(attempt.sessionFile, "transcript path");
+                else await openTranscript(attempt.sessionFile);
               }
             }
-            return { dashboard: formatNavigatorDashboard(loaded.run, checkpoints, worktrees), actions, copies, reviews, transcripts, script: loaded.snapshot.script };
           };
           for (;;) {
             let view = await loadDashboard();
@@ -2318,6 +3228,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
                 }, { overlay: true })
               : await ctx.ui.select(view.dashboard, [...view.actions.keys(), "Close"]);
             if (!actionChoice || actionChoice === "Close") return;
+            if (actionChoice === "Agents...") { await selectAgent(view); continue; }
             if (actionChoice === "Refresh") continue;
             if (actionChoice === "View script") {
               await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
@@ -2356,47 +3267,7 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
             }
             if (actionChoice === "View transcript") {
               const transcript = await ctx.ui.select("Native Pi transcripts", [...view.transcripts, "Back"]);
-              if (transcript && transcript !== "Back") {
-                try {
-                  const entries = SessionManager.open(transcript).buildContextEntries();
-                  await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {
-                    let offset: number | undefined;
-                    let renderedLines: string[] = [];
-                    const terminalRows = () => Math.max(1, ((tui as unknown as { terminal?: { rows?: number } }).terminal?.rows) ?? 24);
-                    const viewport = () => Math.max(1, terminalRows() - 3);
-                    const move = (delta: number) => {
-                      const maxOffset = Math.max(0, renderedLines.length - viewport());
-                      offset = Math.max(0, Math.min(maxOffset, (offset ?? maxOffset) + delta));
-                    };
-                    return {
-                      render(width: number) {
-                        renderedLines = transcriptLines(entries).flatMap((line) => line ? truncateToVisualLines(line, Number.MAX_SAFE_INTEGER, width, 0).visualLines : [""]);
-                        const maxOffset = Math.max(0, renderedLines.length - viewport());
-                        offset = Math.min(offset ?? maxOffset, maxOffset);
-                        return [
-                          theme.fg("accent", "Native Pi transcript"),
-                          ...renderedLines.slice(offset, offset + viewport()),
-                          "",
-                          theme.fg("dim", "↑↓/pgup/pgdn scroll · Home/End jump · esc close"),
-                        ];
-                      },
-                      invalidate() {},
-                      handleInput(data: string) {
-                        if (keybindings.matches(data, "tui.select.up")) move(-1);
-                        else if (keybindings.matches(data, "tui.select.down")) move(1);
-                        else if (keybindings.matches(data, "tui.select.pageUp")) move(-viewport());
-                        else if (keybindings.matches(data, "tui.select.pageDown")) move(viewport());
-                        else if (keybindings.matches(data, "tui.editor.cursorLineStart")) offset = 0;
-                        else if (keybindings.matches(data, "tui.editor.cursorLineEnd")) offset = Math.max(0, renderedLines.length - viewport());
-                        else if (keybindings.matches(data, "tui.select.cancel")) done(undefined);
-                        tui.requestRender();
-                      },
-                    };
-                  }, { overlay: true });
-                } catch (error) {
-                  ctx.ui.notify(`Cannot open transcript ${transcript}: ${error instanceof Error ? error.message : String(error)}`, "warning");
-                }
-              }
+              if (transcript && transcript !== "Back") await openTranscript(transcript);
               continue;
             }
             if (actionChoice === "Transcript paths") {
@@ -2481,9 +3352,9 @@ export default function workflowExtension(pi: ExtensionAPI, home?: string, clipb
   pi.on("session_shutdown", async () => {
     try {
       await Promise.all([...runs.entries()].map(async ([runId, run]) => {
-        if (["completed", "failed", "stopped"].includes(run.lifecycle.state)) { await run.completion?.catch(() => undefined); return; }
-        if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) {
-          try { await run.lifecycle.terminal("interrupted"); } catch (error) { if (!["completed", "failed", "stopped"].includes(run.lifecycle.state)) throw error; }
+        if (["completed", "failed", "stopped", "budget_exhausted"].includes(run.lifecycle.state)) { await run.completion?.catch(() => undefined); return; }
+        if (!["completed", "failed", "stopped", "budget_exhausted"].includes(run.lifecycle.state)) {
+          try { await run.lifecycle.terminal("interrupted"); } catch (error) { if (!["completed", "failed", "stopped", "budget_exhausted"].includes(run.lifecycle.state)) throw error; }
           run.abortController.abort();
           run.execution?.cancel();
           await scheduler.cancelRun(runId);
@@ -2512,8 +3383,8 @@ function modelSpec(value: string, fallback: ModelSpec): ModelSpec {
 }
 
 export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
-export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
+export type { AwaitingCheckpoint, CompletedOperation, ConversationHead, NativeSessionReference, PendingWorkflowDecision, PersistedConversation, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
-export type { AgentAccounting, AgentAttempt, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentToolCallProgress } from "./agent-execution.js";
+export type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentSetup, AgentSetupContext, AgentSetupHook, AgentToolCallProgress, RegisteredAgentSetupHook, SessionInput } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 export type { DoctorDiagnostic, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust, DoctorWorkflow } from "./doctor.js";