pi-extensible-workflows 3.0.0 → 3.2.0

package/dist/src/workflow-artifacts.js

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function workflowScriptArtifact(script) { return { extension: ".js", content: script }; }
+export function workflowResultArtifact(value) { return typeof value === "string" ? { extension: ".md", content: value } : { extension: ".json", content: `${JSON.stringify(value, null, 2)}\n` }; }
+async function spawnWorkflowEditor(command, path) {
+    const [editor, ...editorArgs] = command.split(" ");
+    if (!editor)
+        return null;
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(editor, [...editorArgs, path], { stdio: "inherit", shell: process.platform === "win32" });
+            child.once("error", () => { resolve(null); });
+            child.once("close", (code) => { resolve(code); });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+export async function openWorkflowArtifact(tui, command, artifact) {
+    const directory = await mkdtemp(join(tmpdir(), "pi-workflow-editor-"));
+    const path = join(directory, `artifact${artifact.extension}`);
+    try {
+        await writeFile(path, artifact.content, { encoding: "utf8", mode: 0o600 });
+        tui.stop();
+        try {
+            return await spawnWorkflowEditor(command, path);
+        }
+        finally {
+            tui.start();
+            tui.requestRender(true);
+        }
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}

package/examples/workflow-extension-template/README.md

@@ -0,0 +1,37 @@
+# Workflow extension template
+
+This is a small, copyable extension rather than a generator. It shows the usual
+registration shape with one function and one packaged role. Copy the directory
+into a project, rename the metadata and function, then edit the role body.
+
+
+## Run it
+
+From the repository root after installing dependencies and building the package:
+
+```sh
+node --test examples/workflow-extension-template/extension.test.mjs
+```
+
+For a published package, run the same test from this directory after installing
+`pi-extensible-workflows` in the surrounding project. Copy the directory into a
+trusted Pi extension location; Pi auto-discovers its `index.js` entry point.
+
+
+## Files
+
+- `index.js` registers `greet` and resolves `roles/` from `import.meta.url`.
+  Relative role-directory strings are not accepted by the extension API.
+- `roles/reviewer.md` is a portable packaged role with no provider or tool
+  assumptions.
+- `extension.test.mjs` checks registration, function behavior, role packaging,
+  and the advanced examples.
+
+
+## Optional advanced pieces
+
+The dynamic `template-model` alias and `templateAdvisor` setup hook are
+optional examples. The hook only changes an agent after the call includes
+`{ templateAdvisor: true }`; remove either section if the extension does not
+need it. Both features are trusted host code and should be kept under explicit
+project policy.

package/examples/workflow-extension-template/extension.test.mjs

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { cp, mkdir, mkdtemp, rm, symlink } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { discoverAndLoadExtensions } from "@earendil-works/pi-coding-agent";
+import { beginWorkflowExtensionLoading, loadingRegistry, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, resetWorkflowRegistry, workflowCatalog } from "pi-extensible-workflows";
+
+test("discovers the copied directory as a trusted Pi extension", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workflow-extension-template-"));
+  try {
+    const destination = join(root, ".pi", "extensions", "workflow-extension-template");
+    await mkdir(join(root, "node_modules"), { recursive: true });
+    const packageEntry = fileURLToPath(import.meta.resolve("pi-extensible-workflows"));
+    const packageRoot = join(dirname(packageEntry), "..", "..");
+    await symlink(packageRoot, join(root, "node_modules", "pi-extensible-workflows"), "dir");
+    await cp(dirname(fileURLToPath(import.meta.url)), destination, { recursive: true });
+    const result = await discoverAndLoadExtensions([], root, join(root, ".pi", "agent"));
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.extensions.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+
+  resetWorkflowRegistry();
+  const { default: extension } = await import("./index.js");
+  beginWorkflowExtensionLoading();
+  extension();
+
+  const catalog = workflowCatalog();
+  assert.deepEqual(catalog.functions.map(({ name }) => name), ["greet"]);
+  assert.deepEqual(catalog.modelAliasEntries?.filter(({ name }) => name === "template-model").map(({ name, kind }) => ({ name, kind })), [{ name: "template-model", kind: "dynamic" }]);
+  assert.equal(await registeredWorkflowFunctions().greet.run({ name: "Ada" }, {}), "Hello, Ada!");
+
+  const registration = registeredWorkflowRoleDirectoryRegistrations()[0];
+  assert.ok(registration);
+  assert.match(readFileSync(join(registration.path, "reviewer.md"), "utf8"), /Packaged reviewer role/);
+
+  const resolved = await loadingRegistry().resolveModelAliases({
+    cwd: process.cwd(),
+    projectTrusted: true,
+    rootModel: { provider: "example", model: "root" },
+    knownModels: new Set(["example/root", "example/available"]),
+    availableModels: new Set(["example/available"]),
+    signal: new AbortController().signal,
+  });
+  assert.deepEqual(resolved, { "template-model": "example/available" });
+
+  const hook = loadingRegistry().agentSetupHooks().find(({ name }) => name === "templateAdvisor");
+  assert.ok(hook);
+  const agent = { prompt: "Review this", options: {}, sessionInput: {} };
+  await hook.setup(agent, { signal: new AbortController().signal });
+  assert.equal(agent.sessionInput.systemPromptAppend, undefined);
+  agent.options.templateAdvisor = true;
+  await hook.setup(agent, { signal: new AbortController().signal });
+  assert.match(agent.sessionInput.systemPromptAppend, /one concrete risk/);
+});

package/examples/workflow-extension-template/index.js

@@ -0,0 +1,51 @@
+import { registerWorkflowExtension } from "pi-extensible-workflows";
+
+const templateExtension = {
+  version: "1.0.0",
+  headline: "Workflow extension template",
+  description: "A copyable registered function with a packaged role.",
+  functions: {
+    greet: {
+      description: "Return a greeting for one person.",
+      input: {
+        type: "object",
+        properties: { name: { type: "string" } },
+        required: ["name"],
+        additionalProperties: false,
+      },
+      output: { type: "string" },
+      run(input) {
+        return `Hello, ${String(input.name)}!`;
+      },
+    },
+  },
+  // Packaged resources must be absolute paths or file URLs. This URL stays
+  // correct when the extension is copied or installed elsewhere.
+  roleDirectories: [new URL("./roles/", import.meta.url)],
+  // Optional advanced example: select an available model without naming a
+  // provider-specific model in the extension.
+  modelAliases: {
+    "template-model": {
+      resolve({ availableModels, rootModel }) {
+        const root = `${rootModel.provider}/${rootModel.model}`;
+        return availableModels.has(root) ? root : availableModels.values().next().value ?? root;
+      },
+    },
+  },
+  // Optional advanced example: mutate setup only for explicitly opted-in
+  // agents. Setup hooks are trusted code and should stay narrowly scoped.
+  agentSetupHooks: {
+    templateAdvisor: {
+      setup(agent, context) {
+        if (context.signal.aborted || agent.options.templateAdvisor !== true) return;
+        const suffix = "\n\nAdvisor: call out one concrete risk and one next check.";
+        const existing = agent.sessionInput.systemPromptAppend;
+        agent.sessionInput.systemPromptAppend = existing ? existing + suffix : suffix;
+      },
+    },
+  },
+};
+
+export default function extension() {
+  registerWorkflowExtension(templateExtension);
+}

package/examples/workflow-extension-template/roles/reviewer.md

@@ -0,0 +1,4 @@
+---
+description: Packaged reviewer role
+---
+Review the requested change carefully. Return concrete findings with file names and a next check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensible-workflows",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Deterministic multi-agent workflow orchestration for Pi",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -25,6 +25,7 @@
     "src",
     "skills",
     "evals",
+    "examples",
     "test/fixtures"
   ],
   "scripts": {
@@ -32,7 +33,7 @@
     "inspect": "node dist/src/cli.js inspect",
     "lint": "eslint .",
     "test": "npm run build && TEST_FILES='dist/test/*.test.js' npm run test:run",
-    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test $TEST_FILES",
+    "test:run": "tmp=$(mktemp -d); trap 'rm -rf \"$tmp\"' EXIT; TMPDIR=\"$tmp\" node --test --test-concurrency=1 $TEST_FILES",
     "acceptance": "npm run build && TEST_FILES='dist/test/runtime-acceptance.test.js' npm run test:run",
     "docs:check": "node scripts/check-docs.mjs",
     "check": "npm run lint && npm test && npm run docs:check",
@@ -64,6 +65,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "acorn": "^8.17.0"
+    "acorn": "^8.17.0",
+    "minimatch": "^10.2.5"
   }
 }

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

@@ -4,30 +4,38 @@ 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.
 
-## Example
-```js
-const reportSchema = { type: "object", properties: { summary: { type: "string" }, findings: { type: "array", items: { type: "string" } } }, required: ["summary", "findings"], additionalProperties: false };
+## Default path
+
+Use `workflow` only for genuinely multi-agent orchestration; a single agent uses ordinary tools or `Agent` directly. Give phases distinct responsibilities and keep result flow explicit.
 
+For most multi-agent tasks, start with a named inline workflow: provide a non-empty `name` and a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns.
 
+```js
 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."),
+  second: () => agent("Research the second target."),
 });
 
-return agent(
-  prompt("Review these reports:\n\n{reports}", { reports }),
-  { role: "reviewer", outputSchema: reportSchema },
+return await agent(
+  prompt("Summarize these reports:\n\n{reports}", { reports }),
 );
 ```
 
+Await `parallel(...)` or `pipeline(...)` results before interpolation. Runs are backgrounded by default; set the tool-call `foreground: true` when the caller must wait for the final value.
+
+## Runtime and safety rules
+
+
 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 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. 
+Recovery map: `agent(..., { retries })` reruns one agent call in the same run for transient failures; `workflow_retry({ runId })` replays a failed run into a child; `workflow_resume({ runId, budget? })` continues a `budget_exhausted` run; `parentRunId` on a new launch only borrows named worktrees and never replays or resumes. Use each only for its stated case.
+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. External side effects before failure are not guaranteed exactly once.
+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. Retry versus per-agent `retries` and `workflow_resume` is always explicit.
+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`.
 
@@ -37,20 +45,28 @@ Example use of `shell`:
 // ... other code
 const testRes = await shell("yarn test", { env: { CI: "1" } });
 if (testRes.exitCode === 0) {
-   // success path
-   return {...}
+  // success path
+  return { ok: true };
 }
 ```
 
 Most of the times using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
 
+## Advanced capabilities
+
+Registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` remain available for workflows that need them. Treat these as advanced controls rather than requirements for the default inline path.
+
 ## `agent()` options
+
 ```typescript
 export interface AgentOptions {
-  label?: string; model?: string; role?: string; tools?: string[];
-  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; 
-  outputSchema?: JsonSchema; 
-  retries?: number; 
+  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;
 }
@@ -61,24 +77,34 @@ 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.
 
 ## 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 findings = await agent("Inspect the implementation.");
-const fix = await agent(prompt("Propose the smallest fix from these findings:\n\n{findings}", { findings }));
+const fix = await agent(
+  prompt("Propose the smallest fix from these findings:\n\n{findings}", {
+    findings,
+  }),
+);
 return { findings, fix };
 ```
 
 ## Worktrees
+
 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")),
@@ -89,6 +115,7 @@ 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.

package/src/agent-execution.ts

@@ -2,13 +2,14 @@ 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 "./types.js";
-import { jsonObject, mergeAgentResourceExclusions, modelAliasName, modelCapability, resolveModelReference } from "./utils.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;
@@ -66,29 +67,6 @@ 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> }
-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 } : {}) };
@@ -129,7 +107,7 @@ 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); } }
@@ -151,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,
@@ -169,14 +150,12 @@ 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();
@@ -218,7 +197,7 @@ 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] };
 }
 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;
@@ -518,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);

package/src/cli.ts

@@ -7,7 +7,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, type LoadExtensionsResult } from "@earendil-works/pi-coding-agent";
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport, type DoctorOptions } from "./doctor.js";
-import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, type JsonSchema, type JsonValue, type WorkflowProgressStyles } from "./index.js";
+import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport, type DoctorCleanupOptions } from "./doctor-cleanup.js";
+import workflowExtension, { formatWorkflowProgress, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath, type JsonSchema, type JsonValue, type WorkflowProgressStyles } from "./index.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
 import type { PersistedRun } from "./persistence.js";
 import type { WorkflowCatalogFunction } from "./index.js";
@@ -158,6 +159,26 @@ function launcherHelpLines(): string[] {
 }
 function workflowUsage(): string { return [`Usage: pi-extensible-workflows run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
 function exportUsage(): string { return [`Usage: pi-extensible-workflows export <workflow-name> [--name <command>] [--output <path>] [--force]`, "", "Launcher options:", ...launcherHelpLines()].join("\n") + "\n"; }
+export function parseDoctorCleanupArgs(rawArgs: readonly string[]): Required<Pick<DoctorCleanupOptions, "olderThanDays" | "yes">> {
+  let olderThanDays = 90;
+  let yes = false;
+  let seenDays = false;
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const token = rawArgs[index] as string;
+    if (token === "--yes") { yes = true; continue; }
+    const inline = token.startsWith("--older-than-days=") ? token.slice("--older-than-days=".length) : undefined;
+    if (token === "--older-than-days" || inline !== undefined) {
+      if (seenDays) throw new Error("--older-than-days may only be provided once");
+      const raw = inline ?? rawArgs[++index];
+      if (raw === undefined || !/^[1-9]\d*$/.test(raw)) throw new Error("older-than-days must be a positive integer");
+      const parsed = Number(raw);
+      if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error("older-than-days must be a positive integer");
+      olderThanDays = parsed; seenDays = true; continue;
+    }
+    throw new Error(`Unknown cleanup option: ${token}`);
+  }
+  return { olderThanDays, yes };
+}
 function stripTrustOptions(rawArgs: readonly string[]): { args: string[]; trustOverride?: boolean } {
   const args: string[] = [];
   let trustOverride: boolean | undefined;
@@ -233,7 +254,7 @@ async function createWorkflowRuntime(options: WorkflowIo, shutdownHandlers: Shut
   workflowExtension(headlessPi as never, homedir(), undefined, undefined, agentDir);
   const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow") as HeadlessWorkflowTool | undefined;
   if (!workflowTool) throw new Error("The workflow runtime could not be initialized");
-  return { catalog: workflowCatalog(), services, workflowTool, shutdownHandlers };
+  return { catalog: workflowCatalog({ cwd, projectTrusted: settingsManager.isProjectTrusted(), globalSettingsPath: workflowSettingsPath(agentDir) }), services, workflowTool, shutdownHandlers };
 }
 
 function availableModelInfo(services: WorkflowRuntime["services"], available = false): { provider: string; id: string }[] {
@@ -415,6 +436,16 @@ export async function runCli(args: readonly string[], options: CliOptions = {},
     write(formatDoctorReport(report));
     return doctorExitCode(report);
   }
+  if (args[0] === "doctor" && args[1] === "cleanup") {
+    if (args.slice(2).some((arg) => arg === "--help" || arg === "-h")) { write("Usage: pi-extensible-workflows doctor cleanup [--older-than-days <days>] [--yes]\n"); return 0; }
+    try {
+      const parsed = parseDoctorCleanupArgs(args.slice(2));
+      const cleanupOptions: DoctorCleanupOptions = { ...parsed, ...(options.cwd !== undefined ? { cwd: options.cwd } : {}) };
+      const report = await doctorCleanup(cleanupOptions);
+      write(formatDoctorCleanupReport(report));
+      return doctorCleanupExitCode(report);
+    } catch (error) { stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }
+  }
   if (args[0] === "inspect" && args.length <= 2) {
     try { await (options.inspect ?? runSessionInspector)(args[1]); return 0; }
     catch (error) { write(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1; }