pi-extensible-workflows 2.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -64,6 +64,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "acorn": "^8.17.0"
+    "acorn": "^8.17.0",
+    "minimatch": "^10.2.5"
   }
 }

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

@@ -4,50 +4,78 @@ description: Use when the task is complex enough to require multiple subagents o
 ---
 
 # pi-extensible-workflows
+
 Use `workflow` only for genuinely multi-agent orchestration; one agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
 
-## Pattern
+## Example
+
 ```js
-const reportSchema = { type: "object", properties: { summary: { type: "string" }, findings: { type: "array", items: { type: "string" } } }, required: ["summary", "findings"], additionalProperties: false };
+const reportSchema = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    findings: { type: "array", items: { type: "string" } },
+  },
+  required: ["summary", "findings"],
+  additionalProperties: false,
+};
 
 const reports = await parallel("research", {
-  first: () => agent("Research the first target.", { role: "scout", outputSchema: reportSchema }),
-  second: () => agent("Research the second target.", { role: "scout", outputSchema: reportSchema }),
+  first: () =>
+    agent("Research the first target.", {
+      role: "scout",
+      outputSchema: reportSchema,
+    }),
+  second: () =>
+    agent("Research the second target.", {
+      role: "scout",
+      outputSchema: reportSchema,
+    }),
 });
 
-return agent(
-  prompt("Review these reports:\n\n{reports}", { reports }),
-  { role: "reviewer", outputSchema: reportSchema },
-);
+return agent(prompt("Review these reports:\n\n{reports}", { reports }), {
+  role: "reviewer",
+  outputSchema: reportSchema,
+});
 ```
 
-Pass structured input from the main agent with `args`:
+Inline launches require a non-empty `name`. Registered function launches must omit `name`; they use `workflow` as the run name:
+
 ```json
 { "workflow": "workflowName", "args": { "issue": 42 } }
 ```
-Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. A terminal `parentRunId` reuses matching named `withWorktree` scopes; unnamed or missing names create new worktrees.
-If `workflow_catalog` is available, call it once before creating the first workflow for a task. The name-less result is a compact index with launch-ready input schemas, descriptions, variables, and configured model aliases. Use those inputs to launch registered functions directly with `{ "workflow": "name", "args": { ... } }`; their input and output schemas are enforced. Request full detail with `{ "name": "name" }` only when composing a function programmatically or inspecting its output contract and extension metadata; do not load full definitions unconditionally. Alias targets are catalog metadata, not an availability probe. Do not try to reinvent already exposed functions.
+
+Inside the workflow, read `args.issue` (`args` is `null` when omitted). `workflow_stop` requires the exact run ID; foreground results retain their value and completed `runId`, while background launches return `runId` immediately. A terminal `parentRunId` reuses matching named `withWorktree` scopes but does not replay journal results. For an explicitly failed run, use the exact `runId` from failure diagnostics with `workflow_retry({ runId })`: diagnostics list replayable and incomplete paths, artifacts, and valid named worktrees; the tool creates a linked child, replays completed agent, shell, function, and checkpoint operations, and executes incomplete work. Retry versus per-agent `retries` and `workflow_resume` is always explicit; external side effects before failure are not guaranteed exactly once.
+Inspect tool `workflow_catalog` result at least once before creating the first workflow for a task.
 
 Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.
 
-Use a bounded verification loop when command output controls the gate:
+Example use of `shell`:
+
 ```js
-return withWorktree("fix-tests", async ({ path, branch }) => {
-  for (let attempt = 1; attempt <= 5; attempt += 1) {
-    const tests = await shell("yarn test", { env: { CI: "1" } });
-    if (tests.exitCode === 0) return { path, branch, tests };
-    await agent(prompt("Fix these failures:\n\n{output}", { output: tests.stderr || tests.stdout }));
-  }
-  return { path, branch, tests: await shell("yarn test", { env: { CI: "1" } }) };
-});
+// ... other code
+const testRes = await shell("yarn test", { env: { CI: "1" } });
+if (testRes.exitCode === 0) {
+  // success path
+  return { ok: true };
+}
 ```
-Shell results are journaled only after process exit and RPC validation. A host crash after side effects but before journaling can rerun the command on resume; use `shell()` mainly for verification and bounded gates, not exactly-once mutations.
+
+Most of the times using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
 
 ## `agent()` options
+
 ```typescript
-interface AgentOptions {
-  label?: string; model?: string; role?: string; tools?: string[];
-  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; outputSchema?: JsonSchema; retries?: number; timeoutMs?: number | null;
+export interface AgentOptions {
+  label?: string;
+  model?: string;
+  role?: string;
+  tools?: string[];
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+  outputSchema?: JsonSchema;
+  retries?: number;
+  timeoutMs?: number | null;
+  [key: string]: JsonValue;
 }
 ```
 
@@ -55,29 +83,35 @@ Extensions may add JSON-compatible agent options such as `advisor: true`; core k
 
 Agent calls are unnamed. Direct calls receive hidden source call-site identity; aliases are unsupported, and calls from one source site must not race outside `parallel` or `pipeline`, whose structural keys make replay deterministic.
 
-## Persistent conversations
-Use `conversation(name, options)` when several agent turns should share a persisted transcript and build on one another. Unlike independent `agent(prompt, options)` calls, the returned handle continues from the last successful turn:
+## Passing agent results
+
+Use independent `agent(prompt, options)` calls and pass each completed result explicitly to the next prompt. This keeps workflow execution deterministic and makes replay state local to each call:
 
 ```js
-const handle = conversation("developer", { role: "developer" });
-const findings = await handle.run("Inspect the implementation.");
-const fix = await handle.run("Now propose the smallest fix.");
+const findings = await agent("Inspect the implementation.");
+const fix = await agent(
+  prompt("Propose the smallest fix from these findings:\n\n{findings}", {
+    findings,
+  }),
+);
 return { findings, fix };
 ```
 
-Await each `handle.run(prompt, turnOptions)` call before starting the next one; conversation turns must be sequential and cannot overlap. Conversation creation accepts the same execution-policy options as `agent()`. `timeoutMs` and `retries` passed to `run()` are turn-local, so a failed turn does not advance the persisted conversation head.
-
 ## Worktrees
-Use `withWorktree(callback)` or `withWorktree(name, callback)` for top-level agents that collaborate in one worktree:
+
+Use `withWorktree(name, callback)` for top-level agents that collaborate in one explicitly named worktree scope:
+
 ```js
 const result = await withWorktree("issue", async ({ path, branch }) => {
   const report = await agent("Implement the issue");
   return { path, branch, report };
 });
 ```
+
 Entering the scope materializes its worktree before the callback. The callback receives a frozen reference containing only the real string `path` and `branch`; callbacks may ignore the argument, and their bare return value is preserved. Concurrent agents share mutable files, so assign non-conflicting work or coordinate explicitly.
 
 Branches may call any workflow function, not only `agent()`. Use separate named scopes when parallel branches need isolated worktrees:
+
 ```js
 const results = await parallel("implementation", {
   api: () => withWorktree("api", () => agent("Implement the API")),
@@ -88,14 +122,15 @@ const results = await parallel("implementation", {
 Registered extension functions receive `withWorktree` in context and can compose other registered functions with `context.invoke("reviewRepository", { focus: "security" })`. Their public inputs and outputs remain JSON; callbacks cannot cross the extension boundary.
 
 ## Rules
+
 - Use `log(messageString)` for brief operator status.
 - A role owns execution policy: with `role`, do not set `model`, `thinking`, or `tools`; only task options such as `outputSchema`, retries, timeout, or a `withWorktree` scope may accompany it.
 - Use `parallel()` for independent tasks with different flows and `pipeline()` when every keyed item follows the same ordered stages; do not duplicate identical chains in `parallel()`. Signatures are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; keys are stable task, item, and stage names.
 - Preserve item metadata in workflow code between pipeline stages instead of making agents echo it through `outputSchema`.
 - Use a JavaScript loop for repeated work; each direct `agent(...)` call gets deterministic call-site and occurrence identity.
 - Runs default to background; set tool-call `foreground: true` when asked to wait.
-- Add `budget` only for aggregate limits. Valid dimensions are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches`; each is `{ soft?: number, hard?: number }` with `soft < hard`.
-- `budget_exhausted` runs resume through `workflow_resume`: omitted patch values stay unchanged, `null` removes a limit, and tightening resumes directly. Relaxation stores the exact proposal and returns `{ state: "awaiting_approval", proposalId }`; `workflow_respond` must answer that ID. Rejection leaves the run exhausted; approval applies the budget and cold-resumes it.
+- Add `budget` only for aggregate limits. Do not invent limits, omit if user do not ask explicitly. Valid dimensions are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches`; each is `{ soft?: number, hard?: number }` with `soft < hard`.
+- `budget_exhausted` runs resume through `workflow_resume`: omitted patch values stay unchanged, `null` removes a limit, and tightening resumes directly. Relaxation stores the exact proposal and returns `{ state: "awaiting_approval", proposalId }`; `workflow_respond` must answer that ID. Rejection leaves the run exhausted; approval applies the budget and cold-resumes it. `workflow_retry` is only for persisted `failed` runs and inherits cumulative usage; replay itself consumes no budget.
 - `parallel()` and `pipeline()` return keyed bare values; await them before use. Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings remain literal.
 - Use `outputSchema` only when another phase compares, aggregates, or validates a result, never for final prose. Keep only consumer-needed fields and avoid repeated evidence. Agents with it must call `workflow_result`; one repair prompt is built in. Omit `retries` unless an extra retry is justified and work is idempotent.
 - Do not add persona specifications to agent prompts; define the task directly.

package/src/agent-execution.ts

@@ -1,15 +1,15 @@
-import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { Type } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
-import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, type AgentSessionEvent, type InlineExtension, type SessionStats, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 type AgentMessage = { role: string; content?: unknown; stopReason?: string; errorMessage?: string; usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { total: number } } };
-import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, WorkflowRunContext } from "./index.js";
-import { mergeAgentResourceExclusions, resolveModelReference, WorkflowError } from "./index.js";
-import type { ConversationHead, PersistedConversation, RunStore } from "./persistence.js";
-
+import type { AgentIdentity, AgentResourceExclusions, AgentResourcePolicy, AgentSetup, AgentSetupSummary, JsonSchema, JsonValue, ModelSpec, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput, WorkflowRunContext } from "./types.js";
+import { jsonObject, disabledResources, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference, unmatchedResourcePatterns } from "./utils.js";
+import { WorkflowError } from "./types.js";
+import type { RunStore } from "./persistence.js";
+export type { AgentSetup, AgentSetupContext, AgentSetupHook, NativeSession, RegisteredAgentSetupHook, SessionFactory, SessionInput } from "./types.js";
 export interface AgentBudgetHooks {
   beforeAttempt(): void;
   beforeTurn(): void;
@@ -42,7 +42,6 @@ export interface AgentExecutionOptions {
   budget?: AgentBudgetHooks;
   agentOptions?: Readonly<Record<string, JsonValue>>;
   agentIdentity?: AgentIdentity;
-  conversation?: { id: string; turn: number };
 }
 export interface AgentExecutionRoot {
   cwd: string;
@@ -68,36 +67,12 @@ export interface AgentActivity { kind: "reasoning" | "tool" | "text"; text: stri
 export interface AgentProgress { accounting: AgentAccounting; toolCalls: readonly AgentToolCallProgress[]; activity?: AgentActivity; persist: boolean }
 export interface AgentAttempt { attempt: number; sessionId: string; sessionFile: string; result?: JsonValue; error?: { code: string; message: string }; accounting: AgentAccounting; setup?: AgentSetupSummary }
 export interface AgentExecutionResult { value: JsonValue; attempts: readonly AgentAttempt[]; cwd: string }
-export interface AgentSetup { prompt: string; options: Record<string, JsonValue>; sessionInput: SessionInput; createSession: SessionFactory }
-export interface AgentSetupContext { readonly run: Readonly<WorkflowRunContext>; readonly identity: Readonly<AgentIdentity>; readonly attempt: number; readonly signal: AbortSignal }
-export interface AgentSetupHook { priority?: number; setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void> }
-export interface RegisteredAgentSetupHook { name: string; priority: number; setup: AgentSetupHook["setup"] }
-type NativeSessionStats = Pick<SessionStats, "tokens" | "cost">;
-export interface NativeSession {
-  readonly sessionId: string;
-  readonly sessionFile: string | undefined;
-  readonly messages: readonly AgentMessage[];
-  getSessionStats(): NativeSessionStats;
-  readonly systemPrompt?: string;
-  readonly model?: { provider: string; model?: string; id?: string };
-  readonly agent?: { state: { tools: readonly { name: string }[] } };
-  getLeafId?: () => string | null;
-  getToolDefinitions?: () => unknown;
-  subscribe?(listener: (event: AgentSessionEvent) => void): () => void;
-  prompt(text: string): Promise<void>;
-  steer?(text: string): Promise<void>;
-  abort?(): Promise<void>;
-  dispose(): void;
-}
-export interface SessionInput { cwd: string; model: ModelSpec; tools: string[]; sessionLabel: string; agentDir?: string; customTools?: ToolDefinition[]; resultTool?: ToolDefinition; systemPromptAppend?: string; extensionFactories?: InlineExtension[]; resourcePolicy?: AgentResourcePolicy; options?: Record<string, JsonValue>; continuation?: { sessionId: string; sessionFile: string; leafId: string }; allowModelChange?: boolean }
-export type SessionFactory = (input: SessionInput) => Promise<NativeSession>;
 
 function parseModel(value: string | undefined, fallback: ModelSpec, thinking?: ThinkingLevel, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec {
   if (!value) return { ...fallback, ...(thinking ? { thinking } : {}) };
   const parsed = resolveModelReference(value, aliases, knownModels, settingsPath);
   return { ...parsed, ...(thinking ? { thinking } : !parsed.thinking && fallback.thinking ? { thinking: fallback.thinking } : {}) };
 }
-function modelCapability(model: ModelSpec): string { return `${model.provider}/${model.model}`; }
 
 function text(messages: readonly AgentMessage[]): string {
   const message = [...messages].reverse().find((item) => item.role === "assistant");
@@ -132,34 +107,15 @@ function terminalProviderError(error: WorkflowError): TerminalProviderError | un
   return typeof candidate.provider === "string" && typeof candidate.model === "string" && typeof candidate.error === "string" ? { provider: candidate.provider, model: candidate.model, error: candidate.error } : undefined;
 }
 
-function accounting(stats: NativeSessionStats): AgentAccounting {
+function accounting(stats: ReturnType<NativeSession["getSessionStats"]>): AgentAccounting {
   return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
 }
 function canonicalSourcePath(path: string): string { try { return realpathSync(path); } catch { return resolve(path); } }
 
 export async function createNativeAgentSession(input: SessionInput): Promise<NativeSession> {
   const agentDir = input.agentDir ?? getAgentDir();
-  let manager: SessionManager;
-  if (input.continuation) {
-    try {
-      manager = SessionManager.open(input.continuation.sessionFile, input.agentDir ? join(agentDir, "sessions") : undefined, input.cwd);
-      const header = manager.getHeader();
-      if (!header || canonicalSourcePath(header.cwd) !== canonicalSourcePath(input.cwd) || manager.getSessionId() !== input.continuation.sessionId || !manager.getEntry(input.continuation.leafId)) throw new Error("Persisted transcript identity does not match the conversation head");
-      manager.branch(input.continuation.leafId);
-      const context = manager.buildSessionContext();
-      if (context.model && (context.model.provider !== input.model.provider || context.model.modelId !== input.model.model)) {
-        if (!input.allowModelChange) throw new Error("Persisted transcript model does not match the conversation execution policy");
-        manager.appendModelChange(input.model.provider, input.model.model);
-      }
-      if (input.model.thinking && context.thinkingLevel !== input.model.thinking) throw new Error("Persisted transcript thinking level does not match the conversation execution policy");
-    } catch (error) {
-      if (error instanceof WorkflowError && error.code === "RESUME_INCOMPATIBLE") throw error;
-      throw new WorkflowError("RESUME_INCOMPATIBLE", `Cannot reopen conversation transcript: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  } else {
-    manager = input.agentDir ? SessionManager.create(input.cwd, join(agentDir, "sessions")) : SessionManager.create(input.cwd);
-    manager.appendSessionInfo(input.sessionLabel);
-  }
+  const manager = input.agentDir ? SessionManager.create(input.cwd, join(agentDir, "sessions")) : SessionManager.create(input.cwd);
+  manager.appendSessionInfo(input.sessionLabel);
   const modelRuntime = await ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json") });
   const model = modelRuntime.getModel(input.model.provider, input.model.model);
   if (!model) throw new WorkflowError("UNKNOWN_MODEL", `Unknown model: ${input.model.provider}/${input.model.model}`);
@@ -173,14 +129,17 @@ export async function createNativeAgentSession(input: SessionInput): Promise<Nat
     settingsManager.setProjectTrusted(policy.projectTrusted);
     const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
     const resolved = await packageManager.resolve();
-    const disabledExtensions = new Set(policy.effective.extensions);
-    const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)).filter((path) => !disabledExtensions.has(canonicalSourcePath(path))))];
+    const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)))];
+    const excludedExtensions = new Set(disabledResources(policy.effective.extensions, discoveredExtensions));
+    const extensionPaths = discoveredExtensions.filter((path) => !excludedExtensions.has(path));
+    Object.assign(policy, { excludedExtensions: [...excludedExtensions], unmatchedExtensions: unmatchedResourcePatterns(policy.effective.extensions, discoveredExtensions) });
     const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
-    const updateSkillMatches = (skills: readonly { name: string }[]) => {
-      const names = new Set(skills.map(({ name }) => name));
-      Object.assign(policy, { unmatchedSkills: policy.effective.skills.filter((name) => !names.has(name)) });
+    const updateSkillMatches = (skills: readonly { name: string }[]): Set<string> => {
+      const names = [...new Set(skills.map(({ name }) => name))];
+      const excludedSkills = disabledResources(policy.effective.skills, names);
+      Object.assign(policy, { excludedSkills, unmatchedSkills: unmatchedResourcePatterns(policy.effective.skills, names) });
+      return new Set(excludedSkills);
     };
-    const disabledSkills = new Set(policy.effective.skills);
     resourceLoader = new DefaultResourceLoader({
       cwd: input.cwd,
       agentDir,
@@ -191,20 +150,17 @@ export async function createNativeAgentSession(input: SessionInput): Promise<Nat
       additionalSkillPaths: skillPaths,
       ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
       skillsOverride: (base) => {
-        updateSkillMatches(base.skills);
+        const disabledSkills = updateSkillMatches(base.skills);
         return { ...base, skills: base.skills.filter(({ name }) => !disabledSkills.has(name)) };
       },
       ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}),
     });
     await resourceLoader.reload();
-    const discoveredExtensions = new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalSourcePath(path)));
-    Object.assign(policy, { unmatchedExtensions: policy.effective.extensions.filter((path) => !discoveredExtensions.has(canonicalSourcePath(path))) });
   } else if (input.systemPromptAppend || input.extensionFactories?.length) {
     resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
     await resourceLoader.reload();
   }
-  const { session, modelFallbackMessage } = await createAgentSession({ ...(input.options ?? {}), cwd: input.cwd, agentDir, modelRuntime, model, ...(settingsManager ? { settingsManager } : {}), ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(resourceLoader ? { resourceLoader } : {}), sessionManager: manager });
-  if (input.continuation && modelFallbackMessage) throw new WorkflowError("RESUME_INCOMPATIBLE", modelFallbackMessage);
+  const { session } = await createAgentSession({ ...(input.options ?? {}), cwd: input.cwd, agentDir, modelRuntime, model, ...(settingsManager ? { settingsManager } : {}), ...(input.model.thinking ? { thinkingLevel: input.model.thinking } : {}), tools, ...(customTools.length ? { customTools } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(resourceLoader ? { resourceLoader } : {}), sessionManager: manager });
   return Object.assign(session, {
     getLeafId: () => manager.getLeafId(),
     getToolDefinitions: () => session.getAllTools().map(({ name, description, parameters, promptGuidelines }) => ({ name, description, parameters, ...(promptGuidelines ? { promptGuidelines } : {}) })),
@@ -212,19 +168,6 @@ export async function createNativeAgentSession(input: SessionInput): Promise<Nat
 }
 function changedOption(options: Readonly<Record<string, JsonValue>>, baseline: Readonly<Record<string, JsonValue>>, key: string): boolean { return JSON.stringify(options[key]) !== JSON.stringify(baseline[key]); }
 function validThinking(value: unknown): value is ThinkingLevel { return typeof value === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value); }
-function jsonValue(value: unknown, seen = new Set<object>()): value is JsonValue {
-  if (value === null || typeof value === "boolean" || typeof value === "string") return true;
-  if (typeof value === "number") return Number.isFinite(value);
-  if (typeof value !== "object" || seen.has(value)) return false;
-  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return false;
-  const keys = Reflect.ownKeys(value);
-  if (keys.some((key) => typeof key !== "string")) return false;
-  seen.add(value);
-  const valid = (Array.isArray(value) ? Array.from(value) : keys.map((key) => (value as Record<string, unknown>)[key as string])).every((item) => jsonValue(item, seen));
-  seen.delete(value);
-  return valid;
-}
-function jsonObject(value: unknown): value is Record<string, JsonValue> { return jsonValue(value) && typeof value === "object" && value !== null && !Array.isArray(value); }
 interface ChildAgentToolParams {
   prompt: string;
   label: string;
@@ -254,51 +197,9 @@ function fallbackSetupContext(root: AgentExecutionRoot, options: AgentExecutionO
   return { run, identity: Object.freeze({ ...identity, structuralPath: Object.freeze([...identity.structuralPath]) }) };
 }
 function resourcePolicySummary(policy: AgentResourcePolicy): NonNullable<AgentSetupSummary["disabledAgentResources"]> {
-  return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
+  return { skills: [...policy.effective.skills], extensions: [...policy.effective.extensions], excludedSkills: [...(policy.excludedSkills ?? [])], excludedExtensions: [...(policy.excludedExtensions ?? [])], unmatchedSkills: [...policy.unmatchedSkills], unmatchedExtensions: [...policy.unmatchedExtensions] };
 }
-function canonicalJson(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map((item) => canonicalJson(item));
-  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, canonicalJson(item)]));
-  return value;
-}
-function fingerprint(value: unknown): string { return createHash("sha256").update(JSON.stringify(canonicalJson(value))).digest("hex"); }
-function promptFingerprint(value: string): string { return createHash("sha256").update(value).digest("hex"); }
-function fixedConversationOptions(options: Readonly<Record<string, JsonValue>>): JsonValue {
-  const fixedOptions = structuredClone(options) as Record<string, JsonValue>;
-  delete fixedOptions.timeoutMs;
-  delete fixedOptions.retries;
-  return fixedOptions;
-}
-function conversationExecutionPolicy(options: AgentExecutionOptions, setup: AgentSetup): JsonValue {
-  return structuredClone({
-    model: setup.sessionInput.model,
-    tools: [...setup.sessionInput.tools],
-    cwd: setup.sessionInput.cwd,
-    role: options.role ?? null,
-    worktreeOwner: options.worktreeOwner ?? null,
-    parent: options.parent ?? null,
-    systemPromptAppend: setup.sessionInput.systemPromptAppend ?? "",
-    options: fixedConversationOptions(setup.options),
-    resourcePolicy: setup.sessionInput.resourcePolicy ? resourcePolicySummary(setup.sessionInput.resourcePolicy) : null,
-  }) as unknown as JsonValue;
-}
-function conversationPolicyMatches(expected: JsonValue, current: JsonValue, allowModelChange: boolean): boolean {
-  if (fingerprint(expected) === fingerprint(current)) return true;
-  if (!allowModelChange || !expected || typeof expected !== "object" || Array.isArray(expected) || !current || typeof current !== "object" || Array.isArray(current)) return false;
-  const expectedModel = conversationPolicyModel(expected);
-  const currentModel = conversationPolicyModel(current);
-  if (!expectedModel || !currentModel) return false;
-  return fingerprint(expected) === fingerprint({ ...current, model: { ...currentModel, provider: expectedModel.provider, model: expectedModel.model } });
-}
-function conversationPolicyModel(policy: JsonValue): ModelSpec | undefined {
-  if (!policy || typeof policy !== "object" || Array.isArray(policy)) return undefined;
-  const model = policy.model;
-  if (!model || typeof model !== "object" || Array.isArray(model) || typeof model.provider !== "string" || typeof model.model !== "string") return undefined;
-  const thinking = typeof model.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(model.thinking) ? model.thinking as ModelSpec["thinking"] : undefined;
-  return thinking === undefined ? { provider: model.provider, model: model.model } : { provider: model.provider, model: model.model, thinking };
-}
-function conversationFailure(message: string): WorkflowError { return new WorkflowError("RESUME_INCOMPATIBLE", message); }
-async function prepareAgentSetup(root: AgentExecutionRoot, createSession: SessionFactory, task: string, options: AgentExecutionOptions, resolved: { model: ModelSpec; tools: readonly string[]; systemPromptAppend: string }, cwd: string, attempt: number, signal: AbortSignal | undefined, customTools: readonly ToolDefinition[], resultTool: ToolDefinition | undefined, continuation?: ConversationHead): Promise<{ setup: AgentSetup; summary: AgentSetupSummary }> {
+async function prepareAgentSetup(root: AgentExecutionRoot, createSession: SessionFactory, task: string, options: AgentExecutionOptions, resolved: { model: ModelSpec; tools: readonly string[]; systemPromptAppend: string }, cwd: string, attempt: number, signal: AbortSignal | undefined, customTools: readonly ToolDefinition[], resultTool: ToolDefinition | undefined): Promise<{ setup: AgentSetup; summary: AgentSetupSummary }> {
   const setupSignal = signal ?? root.runContext?.signal ?? new AbortController().signal;
   const baselineOptions = structuredClone(options.agentOptions ?? {});
   const baseResourcePolicy = await root.agentResourcePolicy?.();
@@ -320,7 +221,6 @@ async function prepareAgentSetup(root: AgentExecutionRoot, createSession: Sessio
   if (changedOption(setup.options, baselineOptions, "thinking") && validThinking(setup.options.thinking)) setup.sessionInput.model = { ...setup.sessionInput.model, thinking: setup.options.thinking };
   if (changedOption(setup.options, baselineOptions, "tools") && Array.isArray(setup.options.tools) && setup.options.tools.every((tool) => typeof tool === "string")) setup.sessionInput.tools = [...setup.options.tools];
   if (changedOption(setup.options, baselineOptions, "cwd") && typeof setup.options.cwd === "string") setup.sessionInput.cwd = setup.options.cwd;
-  if (continuation) setup.sessionInput.continuation = { sessionId: continuation.sessionId, sessionFile: continuation.sessionFile, leafId: continuation.leafId };
   const model = setup.sessionInput.model;
   const summary: AgentSetupSummary = { hookNames: [...hookNames], model: { provider: model.provider, model: model.model, ...(model.thinking ? { thinking: model.thinking } : {}) }, tools: [...setup.sessionInput.tools], cwd: setup.sessionInput.cwd, ...(setup.sessionInput.resourcePolicy ? { disabledAgentResources: resourcePolicySummary(setup.sessionInput.resourcePolicy) } : {}) };
   return { setup, summary };
@@ -339,13 +239,14 @@ export class WorkflowAgentExecutor {
     const forbidden = requested.find((tool) => !this.root.tools.has(tool));
     if (forbidden) throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${forbidden}`);
     const requestedModel = options.model ?? definition?.model;
-    const hasAlias = requestedModel !== undefined && Object.prototype.hasOwnProperty.call(this.root.modelAliases ?? {}, requestedModel);
-    if (requestedModel !== undefined && this.root.blockedAliases?.has(requestedModel) && !hasAlias) { const target = this.root.blockedAliasTargets?.[requestedModel]; throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`); }
-    const aliasThinking = requestedModel !== undefined && hasAlias ? resolveModelReference(requestedModel, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath).thinking : undefined;
+    const alias = requestedModel === undefined ? undefined : modelAliasName(requestedModel, this.root.modelAliases ?? {});
+    const blockedAlias = requestedModel?.split(":", 1)[0];
+    if (requestedModel !== undefined && blockedAlias && this.root.blockedAliases?.has(blockedAlias) && !alias) { const target = this.root.blockedAliasTargets?.[blockedAlias]; throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`); }
+    const aliasThinking = requestedModel !== undefined && alias ? resolveModelReference(requestedModel, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath).thinking : undefined;
     const model = options.modelOverride ?? parseModel(requestedModel, this.root.model, options.thinking ?? (aliasThinking === undefined ? definition?.thinking : undefined), this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
     const availableModels = this.root.knownModels ?? this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
     if (!availableModels.has(modelCapability(model))) throw new WorkflowError("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
-    return { model, ...(hasAlias ? { requestedModel } : {}), tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
+    return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: [...requested], systemPromptAppend: definition?.prompt ?? "" };
   }
 
   async execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, customTools: readonly ToolDefinition[] = [], setSteer?: (handler: (message: string) => void | Promise<void>) => void, beforeRetry?: () => void): Promise<AgentExecutionResult> {
@@ -373,20 +274,7 @@ export class WorkflowAgentExecutor {
       if (options.cwd) throw new WorkflowError("INVALID_METADATA", "Only child agents or worktree scopes may provide a cwd");
       cwd = this.root.cwd;
     }
-    let conversationRecord: PersistedConversation | undefined;
-    if (options.conversation) {
-      const store = this.root.runStore;
-      if (!store) throw conversationFailure("Conversation persistence is unavailable");
-      try { conversationRecord = await store.conversation(options.conversation.id); } catch (error) { throw conversationFailure(`Cannot load conversation state: ${error instanceof Error ? error.message : String(error)}`); }
-      if (conversationRecord) {
-        const model = conversationPolicyModel(conversationRecord.policy);
-        if (model) resolved = this.resolve({ ...options, modelOverride: model });
-      }
-      if (!Number.isInteger(options.conversation.turn) || options.conversation.turn < 1) throw conversationFailure("Conversation turn must be a positive integer");
-      if (conversationRecord ? conversationRecord.head.turn + 1 !== options.conversation.turn : options.conversation.turn !== 1) throw conversationFailure(`Conversation turn ${String(options.conversation.turn)} does not continue its persisted head`);
-    }
     const attempts: AgentAttempt[] = [];
-    let conversationBaseline: { executionPolicy: JsonValue; toolDefinitionsSha256: string; systemPrompt?: string; systemPromptSha256?: string } | undefined;
     let maxAttempts = (options.retries ?? 0) + 1;
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
       if (recoveryModel) resolved = this.resolve({ ...options, modelOverride: recoveryModel });
@@ -398,10 +286,6 @@ export class WorkflowAgentExecutor {
       let setupFailed = false;
       let budgetError: WorkflowError | undefined;
       let turnStarted = false;
-      let conversationSystemPrompt = "";
-      let conversationToolDefinitionsSha256 = "";
-      let conversationMismatch: WorkflowError | undefined;
-      const conversationMismatchError = () => conversationMismatch ? new WorkflowError("RESUME_INCOMPATIBLE", conversationMismatch.message) : undefined;
       const hasSchemaResult = () => schemaResult !== undefined;
       const resultTool = options.schema ? {
         name: "workflow_result", label: "Workflow Result", description: "Submit the terminal structured workflow result", parameters: Type.Unsafe(options.schema),
@@ -431,51 +315,19 @@ export class WorkflowAgentExecutor {
       };
       try {
         setupFailed = true;
-        const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool, conversationRecord?.head);
+        const prepared = await prepareAgentSetup(this.root, this.createSession, task, options, resolved, cwd, attempt, executionSignal, customTools, resultTool);
         setup = prepared.setup;
         setupSummary = prepared.summary;
         setupFailed = false;
         if (executionSignal?.aborted) throw new WorkflowError("CANCELLED", "Agent cancelled");
-        if (recoveryModel && conversationRecord) setup.sessionInput.allowModelChange = true;
         const started = Date.now();
         session = await setup.createSession(setup.sessionInput);
         if (setup.sessionInput.resourcePolicy) setupSummary = { ...setupSummary, disabledAgentResources: resourcePolicySummary(setup.sessionInput.resourcePolicy) };
-        if (options.conversation) {
-          conversationSystemPrompt = session.systemPrompt ?? "";
-          conversationToolDefinitionsSha256 = fingerprint(session.getToolDefinitions?.() ?? session.agent?.state.tools ?? []);
-          const currentExecutionPolicy = conversationExecutionPolicy(options, setup);
-          if (conversationRecord) {
-            if (session.sessionId !== conversationRecord.head.sessionId || requiredFile(session.sessionFile) !== conversationRecord.head.sessionFile) throw conversationFailure("Conversation transcript identity changed");
-            if (!session.getLeafId || (!recoveryModel && session.getLeafId() !== conversationRecord.head.leafId)) throw conversationFailure("Conversation transcript leaf identity changed");
-            if (!conversationPolicyMatches(conversationRecord.policy, currentExecutionPolicy, Boolean(recoveryModel))) throw conversationFailure("Conversation execution policy changed");
-            if (!session.subscribe && (promptFingerprint(conversationSystemPrompt) !== conversationRecord.head.systemPromptSha256 || conversationSystemPrompt !== conversationRecord.head.systemPrompt)) throw conversationFailure("Conversation system prompt changed");
-            if (conversationToolDefinitionsSha256 !== conversationRecord.head.toolDefinitionsSha256) throw conversationFailure("Conversation tool definitions changed");
-          } else if (conversationBaseline) {
-            if (!conversationPolicyMatches(conversationBaseline.executionPolicy, currentExecutionPolicy, Boolean(recoveryModel))) throw conversationFailure("Conversation execution policy changed");
-            if (conversationToolDefinitionsSha256 !== conversationBaseline.toolDefinitionsSha256) throw conversationFailure("Conversation tool definitions changed");
-          } else {
-            conversationBaseline = { executionPolicy: currentExecutionPolicy, toolDefinitionsSha256: conversationToolDefinitionsSha256 };
-          }
-          if (!session.subscribe) {
-            const expectedPrompt = conversationRecord?.head.systemPrompt ?? conversationBaseline?.systemPrompt;
-            const expectedDigest = conversationRecord?.head.systemPromptSha256 ?? conversationBaseline?.systemPromptSha256;
-            if (expectedPrompt !== undefined && expectedDigest !== undefined && (promptFingerprint(conversationSystemPrompt) !== expectedDigest || expectedPrompt !== conversationSystemPrompt)) throw conversationFailure("Conversation system prompt changed");
-            if (!conversationRecord && conversationBaseline && conversationBaseline.systemPrompt === undefined) conversationBaseline = { ...conversationBaseline, systemPrompt: conversationSystemPrompt, systemPromptSha256: promptFingerprint(conversationSystemPrompt) };
-          }
-          if (conversationRecord && (!session.model || session.model.provider !== setup.sessionInput.model.provider || (session.model.model ?? session.model.id) !== setup.sessionInput.model.model)) throw conversationFailure("Conversation model changed");
-        }
         const includeAttemptSetup = Boolean(this.root.agentSetupHooks?.length || setup.sessionInput.resourcePolicy);
         await options.onAttempt?.({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), ...(includeAttemptSetup ? { setup: setupSummary } : {}) });
         const activeSession = session;
         unsubscribe = activeSession.subscribe?.((event) => {
           if (event.type === "agent_start" && session?.systemPrompt !== undefined) {
-            if (options.conversation) {
-              conversationSystemPrompt = session.systemPrompt;
-              const expectedPrompt = conversationRecord?.head.systemPrompt ?? conversationBaseline?.systemPrompt;
-              const expectedDigest = conversationRecord?.head.systemPromptSha256 ?? conversationBaseline?.systemPromptSha256;
-              if (expectedPrompt !== undefined && expectedDigest !== undefined && (promptFingerprint(conversationSystemPrompt) !== expectedDigest || expectedPrompt !== conversationSystemPrompt)) { conversationMismatch = conversationFailure("Conversation system prompt changed"); void session.abort?.(); }
-              if (!conversationRecord && conversationBaseline && conversationBaseline.systemPrompt === undefined) conversationBaseline = { ...conversationBaseline, systemPrompt: conversationSystemPrompt, systemPromptSha256: promptFingerprint(conversationSystemPrompt) };
-            }
             if (this.root.runStore) {
               systemPromptTurn += 1;
               const entry = { sessionId: session.sessionId, attempt, turn: systemPromptTurn, prompt: session.systemPrompt };
@@ -497,7 +349,7 @@ export class WorkflowAgentExecutor {
             }
           }
           if (event.type === "tool_execution_start") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: "running" }); activity = { kind: "tool", text: event.toolName }; report(false); }
-          if (event.type === "tool_execution_end") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" }); if (activity?.kind === "tool" && activity.text === event.toolName) activity = undefined; report(false); }
+          if (event.type === "tool_execution_end") { toolCalls.set(event.toolCallId, { id: event.toolCallId, name: event.toolName, state: event.isError ? "failed" : "completed" }); if (activity?.kind === "tool" && activity.text === event.toolName) activity = undefined; report(false); toolCalls.delete(event.toolCallId); }
         });
         report(false);
         if (setSteer) {
@@ -510,7 +362,6 @@ export class WorkflowAgentExecutor {
         options.budget?.beforeTurn();
         turnStarted = true;
         try { await promptWithProviderPause(session, promptText, remaining(options.timeoutMs, started), executionSignal, this.root.providerPause); } catch (error) { if (!hasSchemaResult()) throw error; }
-        if (conversationMismatch) throw conversationMismatch;
         throwIfTerminalAssistantError(session, setup.sessionInput.model);
         { const completedAccounting = accounting(session.getSessionStats()); options.budget?.afterTurn(completedAccounting, options.schema !== undefined ? hasSchemaResult() : !latestAssistantHasToolCall(session.messages)); turnStarted = false; }
         if (budgetError) throw budgetError;
@@ -525,8 +376,6 @@ export class WorkflowAgentExecutor {
           }
           if (schemaResult === undefined) throw new WorkflowError("RESULT_INVALID", "Agent did not submit a valid workflow_result after one repair");
         }
-        const mismatch = conversationMismatchError();
-        if (mismatch) throw mismatch;
         const value = options.schema ? schemaResult as JsonValue : text(session.messages);
         if (options.worktreeOwner) await this.root.runStore?.snapshotWorktree(options.worktreeOwner);
         report(true);
@@ -534,19 +383,12 @@ export class WorkflowAgentExecutor {
         await flushSystemPrompts();
         unsubscribe?.();
         const attemptAccounting = accounting(session.getSessionStats());
-        const leafId = session.getLeafId?.() ?? undefined;
-        if (options.conversation) {
-          if (!leafId) throw conversationFailure("Conversation transcript has no persisted leaf");
-          const store = this.root.runStore;
-          if (!store) throw conversationFailure("Conversation persistence is unavailable");
-          await store.saveConversation({ id: options.conversation.id, policy: conversationExecutionPolicy(options, setup), head: { turn: options.conversation.turn, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), leafId, systemPrompt: conversationSystemPrompt, systemPromptSha256: promptFingerprint(conversationSystemPrompt), toolDefinitionsSha256: conversationToolDefinitionsSha256 } });
-        }
         const includeCompletedSetup = Boolean(this.root.agentSetupHooks?.length || setup.sessionInput.resourcePolicy);
         attempts.push({ attempt, sessionId: session.sessionId, sessionFile: requiredFile(session.sessionFile), result: value, accounting: attemptAccounting, ...(includeCompletedSetup ? { setup: setupSummary } : {}) });
         session.dispose();
         return { value, attempts, cwd: setupSummary.cwd };
       } catch (error) {
-        const typed = budgetError ?? conversationMismatch ?? (error instanceof WorkflowError ? error : new WorkflowError(executionSignal?.aborted && setupFailed ? "CANCELLED" : "AGENT_FAILED", error instanceof Error ? error.message : String(error)));
+        const typed = budgetError ?? (error instanceof WorkflowError ? error : new WorkflowError(executionSignal?.aborted && setupFailed ? "CANCELLED" : "AGENT_FAILED", error instanceof Error ? error.message : String(error)));
         if (session) {
           report(true);
           await progress;
@@ -598,7 +440,6 @@ export interface ScheduledAgentOptions {
   timeoutMs?: number | null;
   agentOptions?: Readonly<Record<string, JsonValue>>;
   agentIdentity?: AgentIdentity;
-  conversation?: { id: string; turn: number };
 }
 
 export type ScheduledAgentResult =
@@ -656,6 +497,13 @@ export class FairAgentScheduler {
     this.#runs.set(runId, { limit, ...(beforeLaunch ? { beforeLaunch } : {}), logical: 0, active: 0, queue: [] });
     this.#runOrder.push(runId);
   }
+  updateRunLimit(runId: string, limit: number): void {
+    const run = this.#runs.get(runId);
+    if (!run) throw new WorkflowError("INTERNAL_ERROR", `Unknown scheduler run: ${runId}`);
+    if (!Number.isInteger(limit) || limit < 1 || limit > this.sessionLimit) throw new WorkflowError("INVALID_SETTINGS", "Invalid run concurrency");
+    run.limit = limit;
+    this.#dispatch();
+  }
 
   spawn(runId: string, prompt: string, options: ScheduledAgentOptions, parentId?: string): { id: string; result: Promise<ScheduledAgentResult> } {
     const run = this.#runs.get(runId);