@tranhoangnguyen0310/pi-flow-external 5.1.0-external.0 → 5.2.0-external.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [5.2.0-external.0] - 2026-10-20
+
+### Changed
+- Requires Pi 1.3: peer dependencies on `@earendil-works/pi-agent-core`, `pi-ai`, `pi-coding-agent` and `pi-tui` move from `~0.99.2` to `~1.3.0`.
+- Node 26 is supported and tested in CI. `npm run e2e` no longer passes `--experimental-transform-types`, which Node 26 removed; the sources now use erasable TypeScript syntax only and load through Node's built-in type stripping.
+
+### Fixed
+- `external_delegate` and `external_workflow` no longer disappear from a session saved before the #85 rename. Pi restores a resumed or tree-navigated session's tool loadout from its transcript, and the legacy names `Agent` and `workflow` no longer register. Each legacy name the restored loadout declares now activates its replacement. A launcher stays off when the loadout also declares its current name, or when `--tools -<name>` or `--no-tools` excludes it.
+
+## [5.1.1-external.0] - 2026-10-20
+
+### Changed
+- Simplified `external_runs` action-specific argument guidance (#87):
+  - Consolidated `externalRunsParameters`, `EXTERNAL_RUNS_PARAMETER_KEYS`, `EXTERNAL_RUNS_EXAMPLES`, `EXTERNAL_RUNS_ACTION_SPECS`, and `formatExternalRunsActionGuidance()` in `src/contract/runs.ts` so schema descriptions, on-demand `external_help` (`usage` and `workflow`), and documentation share one authoritative per-action argument matrix (`required`, `optional`, and dynamically derived `inapplicable` fields).
+  - Clarified single-target `inspect` (`1` ID, views `summary|output|diagnostics|final|launch`) vs. batch `inspect` (`2-20` IDs, `summary` view only), and `cursor` (`runs` stream) vs. `workflowCursor` (`workflows` stream, inapplicable when `workflowRunId` filters to one workflow's children).
+  - Updated `request_invalid` and `cursor_invalid` error messages across `list`, `inspect`, `wait`, and `cancel` to identify the applicable action and include a minimal valid JSON call example while preserving #62 forced-placeholder normalization and supervision invariants.
+
 ## [5.1.0-external.0] - 2026-10-19
 
 ### Added

package/docs/supervision-and-runtime.md

@@ -108,27 +108,37 @@ return { run, view, encoding, text, checklist };
 
 ## The `external_runs` Tool
 
-Use `external_runs` to supervise, inspect, and manage runs programmatically:
+Use `external_runs` to supervise, inspect, and manage runs programmatically. Only `action` is top-level required in the JSON Schema; omit parameters that do not apply to the chosen action:
+
+| Action | Required | Optional | Inapplicable (omit) |
+| --- | --- | --- | --- |
+| `list` | `action` | `workflowRunId`, `cursor`, `workflowCursor`, `limit` | `runIds`, `view`, `limitBytes`, `mode`, `reason` |
+| `list` (with `workflowRunId`) | `action`, `workflowRunId` | `cursor`, `limit` | `workflowCursor`, `runIds`, `view`, `limitBytes`, `mode`, `reason` |
+| `inspect` (single run: 1 ID) | `action`, `runIds` (`[id]`) | `view` (`summary` \| `output` \| `diagnostics` \| `final` \| `launch`), `cursor`, `limitBytes` | `workflowRunId`, `workflowCursor`, `limit`, `mode`, `reason` |
+| `inspect` (batch: 2-20 IDs) | `action`, `runIds` (`2-20` IDs) | `view` (`"summary"` only), `cursor`, `limitBytes` | `workflowRunId`, `workflowCursor`, `limit`, `mode`, `reason` |
+| `wait` | `action`, `runIds` (`1-100` IDs) | `mode` (`"any"` \| `"all"`), `limitBytes` | `workflowRunId`, `view`, `cursor`, `workflowCursor`, `limit`, `reason` |
+| `cancel` | `action`, `runIds` (`[id]`, `1` ID) | `reason` | `workflowRunId`, `view`, `cursor`, `workflowCursor`, `limit`, `limitBytes`, `mode` |
 
 ### 1. `list`
-Page session-owned runs and workflow roots:
+Page session-owned agent runs and workflow roots:
 ```ts
 await external_runs({
   action: "list",
   limit: 10,
-  cursor: undefined, // pass nextCursor for pagination
 });
 ```
-Each entry returns timing projections (`queueDelayMs`, `elapsedMs`, `activityAgeMs`, `processDurationMs`).
+- **`cursor` vs. `workflowCursor`:** `list` returns two independent paged streams: `runs` (paged with `cursor` from `nextCursor`) and `workflows` (paged with `workflowCursor` from `nextWorkflowCursor`).
+- **`workflowRunId` filtering:** Passing `workflowRunId: "wf_..."` filters `runs` to that workflow's child agent runs and returns `workflows: []`, so only `cursor` applies (`workflowCursor` is inapplicable).
+- Each entry returns timing projections (`queueDelayMs`, `elapsedMs`, `activityAgeMs`, `processDurationMs`).
 
 ### 2. `inspect`
 Inspect a specific run's state and streams:
 ```ts
-// Single-run inspection supports any view:
+// Single-run inspection (1 ID) supports any view:
 await external_runs({
   action: "inspect",
   runIds: [runId],
-  view: "summary", // "summary" | "output" | "diagnostics" | "final" | "launch"
+  view: "final", // "summary" | "output" | "diagnostics" | "final" | "launch"
   limitBytes: 32768,
 });
 ```
@@ -138,17 +148,16 @@ await external_runs({
 - `final`: **Verified canonical result only**. Returns empty with `finalAvailable: false` until the child reaches verified terminal success.
 - `launch`: Detailed initial launch prompt, configuration, and shared context snapshot.
 
-**Batch Inspection (Summary-only):** Pass up to 20 IDs to check multiple background children in a single cheap call:
+**Batch Inspection (`2-20` IDs, `summary` view only):** Pass 2 to 20 IDs in `runIds` to check multiple background runs in a single bounded call (non-`summary` views require a single target):
 ```ts
 await external_runs({
   action: "inspect",
   runIds: [runId1, runId2],
-  view: "summary", // Batch inspect is summary-only
 });
 ```
 
 ### 3. `wait`
-Block until one or more targets reach terminal state:
+Block until one or more targets (`1-100` IDs in `runIds`) reach terminal state:
 ```ts
 const waitResult = await external_runs({
   action: "wait",
@@ -162,7 +171,7 @@ const waitResult = await external_runs({
 - **Shared Budget:** The `limitBytes` cap is spent across settled results in requested order. If a result exceeds remaining space, it returns `resultTruncated: true` with references to inspect the rest.
 
 ### 4. `cancel`
-Cancel an active run:
+Cancel a single active run (`1` ID via `runIds: [runId]` or `runId`):
 ```ts
 await external_runs({
   action: "cancel",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "5.1.0-external.0",
+  "version": "5.2.0-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",
@@ -41,22 +41,22 @@
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit && vitest run",
-    "e2e": "node --experimental-transform-types scripts/e2e/external.mjs",
+    "e2e": "node scripts/e2e/external.mjs",
     "field-report": "node scripts/field-report.mjs",
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "~0.99.2",
-    "@earendil-works/pi-ai": "~0.99.2",
-    "@earendil-works/pi-coding-agent": "~0.99.2",
-    "@earendil-works/pi-tui": "~0.99.2",
+    "@earendil-works/pi-agent-core": "~1.3.0",
+    "@earendil-works/pi-ai": "~1.3.0",
+    "@earendil-works/pi-coding-agent": "~1.3.0",
+    "@earendil-works/pi-tui": "~1.3.0",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.99.2",
-    "@earendil-works/pi-ai": "0.99.2",
-    "@earendil-works/pi-coding-agent": "0.99.2",
-    "@earendil-works/pi-tui": "0.99.2",
+    "@earendil-works/pi-agent-core": "1.3.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
     "@types/node": "^24.12.4",
     "typebox": "1.1.38",
     "typescript": "^5.9.3",

package/src/config-modal.ts

@@ -23,7 +23,13 @@ export class ConfigModal implements Component {
   private remember = false;
   private cancelBusy?: () => void;
   focused = true;
-  constructor(private tui: TUI, private theme: Theme, private cancelled: (data:string)=>boolean = data=>matchesKey(data,Key.escape), private externalEditorKey:(data:string)=>boolean = ()=>false) {}
+  private tui: TUI;
+  private theme: Theme;
+  private cancelled: (data:string)=>boolean;
+  private externalEditorKey: (data:string)=>boolean;
+  constructor(tui: TUI, theme: Theme, cancelled: (data:string)=>boolean = data=>matchesKey(data,Key.escape), externalEditorKey:(data:string)=>boolean = ()=>false) {
+    this.tui = tui; this.theme = theme; this.cancelled = cancelled; this.externalEditorKey = externalEditorKey;
+  }
   private listTheme() {
     return { selectedPrefix: (s:string)=>this.theme.fg('accent',s), selectedText: (s:string)=>this.theme.fg('accent',s), description:(s:string)=>this.theme.fg('muted',s),scrollInfo:(s:string)=>this.theme.fg('dim',s),noMatch:(s:string)=>this.theme.fg('warning',s) };
   }

package/src/contract/runs.ts

@@ -1,3 +1,4 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { failureVariant, strings, successVariant } from "./envelope.ts";
 import { supervisedRunSchema } from "./run.ts";
@@ -6,7 +7,177 @@ const TOOL = "external_runs";
 const runs = Type.Array(supervisedRunSchema);
 const cursor = Type.Optional(Type.String());
 
+export const EXTERNAL_RUNS_ACTIONS = ["list", "inspect", "wait", "cancel"] as const;
 export const SINGLE_INSPECT_VIEWS = ["summary", "output", "diagnostics", "final", "launch"] as const;
+export const WAIT_MODES = ["any", "all"] as const;
+export const MAX_WAIT_TARGETS = 100;
+/**
+ * Cap for `inspect`'s batch `runIds` mode. Intentionally lower than `wait`'s
+ * MAX_WAIT_TARGETS (100): batch inspection returns full projections and may
+ * touch live evidence reads per target, so it stays cheap by staying small.
+ */
+export const MAX_BATCH_INSPECT_TARGETS = 20;
+
+export const externalRunsParameters = Type.Object({
+  action: StringEnum(EXTERNAL_RUNS_ACTIONS, {
+    description:
+      "Required action. list: page session runs and workflow roots (optional: workflowRunId, limit, cursor, workflowCursor; omit runIds, view, mode, limitBytes, reason). inspect: read 1 run with any view or 2-20 runs for batch summary (required: runIds; optional: view, cursor, limitBytes; omit mode, workflowRunId, workflowCursor, limit, reason). wait: block until terminal outcomes for 1-100 runs (required: runIds; optional: mode, limitBytes; omit view, cursor, workflowCursor, limit, workflowRunId, reason). cancel: stop 1 run (required: runIds with 1 ID; optional: reason; omit view, mode, cursor, workflowCursor, limit, limitBytes, workflowRunId).",
+  }),
+  runIds: Type.Optional(Type.Array(Type.String(), {
+    maxItems: MAX_WAIT_TARGETS,
+    description:
+      "Target run IDs (run_... agent, wf_... workflow). Required for inspect (1 ID for any view: summary, output, diagnostics, final, launch; 2-20 IDs for summary-only batch), wait (1-100 IDs), and cancel (1 ID). Inapplicable to list (omit).",
+  })),
+  view: Type.Optional(StringEnum(SINGLE_INSPECT_VIEWS, {
+    description:
+      "Optional for inspect only (default \"summary\"); inapplicable to list, wait, and cancel (omit). Single-target inspect (1 ID) accepts \"summary\" (state/timing/freshness/refs, default), \"output\" (assistant text plus canonical result, partial or final), \"diagnostics\" (tool activity/errors), \"final\" (only the verified canonical terminal answer, empty until a successful terminal boundary exists), or \"launch\" (recorded prompt, context and execution configuration; sensitive, explicit inspection only). Batch inspect (2-20 runIds) only supports \"summary\".",
+  })),
+  mode: Type.Optional(StringEnum(WAIT_MODES, {
+    description:
+      "Optional for wait only (\"any\" | \"all\", default \"all\"); inapplicable to list, inspect, and cancel (omit). any returns on the first terminal outcome; all waits for every target. Neither cancels pending work; an unsuccessful selected workflow returns early even in all mode.",
+  })),
+  cursor: Type.Optional(Type.String({
+    description:
+      "Optional continuation cursor for list and inspect; inapplicable to wait and cancel (omit). For list: pass back nextCursor verbatim to page the runs stream (all agent runs, or that workflow's children when workflowRunId is set). For single inspect: pass back page.nextCursor with the same runId and view. For batch inspect: pass back nextCursor with the identical runIds array. Stale/reused cursors fail with an actionable error.",
+  })),
+  workflowCursor: Type.Optional(Type.String({
+    description:
+      "Optional continuation cursor for unfiltered list only; inapplicable when workflowRunId filters to one workflow's children and for inspect, wait, and cancel (omit). Pass back nextWorkflowCursor verbatim to page the workflow-roots listing (workflows); passing workflowCursor without cursor pages workflows only.",
+  })),
+  limit: Type.Optional(Type.Integer({
+    minimum: 1,
+    maximum: 100,
+    description: "Optional for list only (1-100); inapplicable to inspect, wait, and cancel (omit). Max entries per list/children page.",
+  })),
+  limitBytes: Type.Optional(Type.Integer({
+    minimum: 4,
+    maximum: 65536,
+    description:
+      "Optional for inspect and wait (4-65536); inapplicable to list and cancel (omit). For inspect: max UTF-8 bytes per page, including the summary view; follow nextCursor for the remainder. For wait: total result budget shared across every settled outcome in the response in request order (default 32768); a result that fits is returned complete, one that does not is truncated with resultTruncated:true and outputRef/diagnosticsRef for the rest.",
+  })),
+  workflowRunId: Type.Optional(Type.String({
+    description:
+      "Optional for list only (wf_... ID); inapplicable to inspect, wait, and cancel (omit). Filters list.runs to children of this wf_... workflow only, leaves list.workflows empty, and pages via cursor (nextCursor) rather than workflowCursor.",
+  })),
+  reason: Type.Optional(Type.String({
+    maxLength: 512,
+    description: "Optional for cancel only (max 512 chars); inapplicable to list, inspect, and wait (omit). Cancellation reason recorded with the run evidence.",
+  })),
+});
+
+export type ExternalRunsParameterKey = keyof typeof externalRunsParameters.properties;
+
+export const EXTERNAL_RUNS_PARAMETER_KEYS = Object.keys(
+  externalRunsParameters.properties,
+) as readonly ExternalRunsParameterKey[];
+
+export const EXTERNAL_RUNS_EXAMPLES = {
+  list: { action: "list" as const },
+  listWorkflowChildren: { action: "list" as const, workflowRunId: "wf_example" },
+  listRunsNextPage: { action: "list" as const, cursor: "cursor_from_nextCursor" },
+  listWorkflowsNextPage: { action: "list" as const, workflowCursor: "cursor_from_nextWorkflowCursor" },
+  inspectSingle: { action: "inspect" as const, runIds: ["run_example"], view: "final" as const },
+  inspectBatch: { action: "inspect" as const, runIds: ["run_example_1", "run_example_2"] },
+  wait: { action: "wait" as const, runIds: ["run_example"], mode: "all" as const },
+  cancel: { action: "cancel" as const, runIds: ["run_example"] },
+  cancelWithReason: { action: "cancel" as const, runIds: ["run_example"], reason: "No longer needed" },
+};
+
+export type ExternalRunsExample = (typeof EXTERNAL_RUNS_EXAMPLES)[keyof typeof EXTERNAL_RUNS_EXAMPLES];
+
+export interface ExternalRunsActionSpec {
+  id: "list" | "list_children" | "inspect_single" | "inspect_batch" | "wait" | "cancel";
+  label: string;
+  action: (typeof EXTERNAL_RUNS_ACTIONS)[number];
+  required: readonly ExternalRunsParameterKey[];
+  optional: readonly ExternalRunsParameterKey[];
+  inapplicable: readonly ExternalRunsParameterKey[];
+  rule: string;
+  example: ExternalRunsExample;
+}
+
+function defineActionSpec(spec: Omit<ExternalRunsActionSpec, "inapplicable">): ExternalRunsActionSpec {
+  const allowed = new Set<ExternalRunsParameterKey>([...spec.required, ...spec.optional]);
+  return {
+    ...spec,
+    inapplicable: EXTERNAL_RUNS_PARAMETER_KEYS.filter((key) => !allowed.has(key)),
+  };
+}
+
+export const EXTERNAL_RUNS_ACTION_SPECS: readonly ExternalRunsActionSpec[] = [
+  defineActionSpec({
+    id: "list",
+    label: "list (session runs + workflow roots)",
+    action: "list",
+    required: ["action"],
+    optional: ["limit", "cursor", "workflowCursor", "workflowRunId"],
+    rule: "Two independent cursor streams: cursor (from nextCursor) pages runs; workflowCursor (from nextWorkflowCursor) pages workflows. Passing workflowCursor without cursor pages workflows alone.",
+    example: EXTERNAL_RUNS_EXAMPLES.list,
+  }),
+  defineActionSpec({
+    id: "list_children",
+    label: "list (workflow children via workflowRunId)",
+    action: "list",
+    required: ["action", "workflowRunId"],
+    optional: ["limit", "cursor"],
+    rule: "workflowRunId (wf_...) filters runs to that workflow's children and returns workflows: []; page with cursor (nextCursor) only, never workflowCursor.",
+    example: EXTERNAL_RUNS_EXAMPLES.listWorkflowChildren,
+  }),
+  defineActionSpec({
+    id: "inspect_single",
+    label: "inspect (single run, any view)",
+    action: "inspect",
+    required: ["action", "runIds"],
+    optional: ["view", "cursor", "limitBytes"],
+    rule: `1 ID in runIds (legacy runId also accepted); view is ${SINGLE_INSPECT_VIEWS.join("|")} (default summary); cursor continues from page.nextCursor with the same runId and view.`,
+    example: EXTERNAL_RUNS_EXAMPLES.inspectSingle,
+  }),
+  defineActionSpec({
+    id: "inspect_batch",
+    label: `inspect (batch summary, 2-${MAX_BATCH_INSPECT_TARGETS} runs)`,
+    action: "inspect",
+    required: ["action", "runIds"],
+    optional: ["view", "cursor", "limitBytes"],
+    rule: `2-${MAX_BATCH_INSPECT_TARGETS} IDs in runIds (1 ID with default/summary view also uses batch shape); view must be omitted or "summary" (output, diagnostics, final, and launch are rejected); cursor continues from nextCursor with the identical runIds array.`,
+    example: EXTERNAL_RUNS_EXAMPLES.inspectBatch,
+  }),
+  defineActionSpec({
+    id: "wait",
+    label: `wait (1-${MAX_WAIT_TARGETS} runs)`,
+    action: "wait",
+    required: ["action", "runIds"],
+    optional: ["mode", "limitBytes"],
+    rule: `1-${MAX_WAIT_TARGETS} IDs in runIds; mode is ${WAIT_MODES.join("|")} (default all); limitBytes is the shared result budget spent in request order.`,
+    example: EXTERNAL_RUNS_EXAMPLES.wait,
+  }),
+  defineActionSpec({
+    id: "cancel",
+    label: "cancel (1 run)",
+    action: "cancel",
+    required: ["action", "runIds"],
+    optional: ["reason"],
+    rule: "1 ID in runIds (legacy runId also accepted); reason is optional (<=512 chars).",
+    example: EXTERNAL_RUNS_EXAMPLES.cancelWithReason,
+  }),
+];
+
+/**
+ * Compact per-action argument matrix and minimal valid examples generated from
+ * `externalRunsParameters` and `EXTERNAL_RUNS_ACTION_SPECS` so on-demand help
+ * cannot drift from the executable tool contract.
+ */
+export function formatExternalRunsActionGuidance(): string {
+  const rows = EXTERNAL_RUNS_ACTION_SPECS.map((spec) => [
+    `- ${spec.label}: required: ${spec.required.join(", ")} | optional: ${spec.optional.join(", ") || "none"} | omit: ${spec.inapplicable.join(", ") || "none"}`,
+    `  Rule: ${spec.rule}`,
+    `  Minimal call: ${JSON.stringify(spec.example)}`,
+  ].join("\n"));
+  return [
+    "external_runs action-specific arguments (supply only the relevant fields; omit inapplicable ones):",
+    ...rows,
+    `List pagination examples: runs stream -> ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listRunsNextPage)}; workflow roots stream -> ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowsNextPage)}.`,
+  ].join("\n");
+}
 
 /** One success variant per action (inspect has batch and single shapes); every expected failure has `data: null`. */
 export const externalRunsOutputSchema = Type.Union([
@@ -28,7 +199,8 @@ export const externalRunsOutputSchema = Type.Union([
       outputStatus: Type.Optional(strings("preliminary", "final", "interrupted")),
     }),
   ])),
-  successVariant(TOOL, Type.Literal("wait"), Type.Object({ mode: strings("any", "all"), completed: runs, pending: Type.Array(Type.String()) })),
+  successVariant(TOOL, Type.Literal("wait"), Type.Object({ mode: strings(...WAIT_MODES), completed: runs, pending: Type.Array(Type.String()) })),
   successVariant(TOOL, Type.Literal("cancel"), Type.Object({ runId: Type.String(), status: strings("requested", "terminal") })),
-  failureVariant(TOOL, strings("list", "inspect", "wait", "cancel"), Type.Null()),
+  failureVariant(TOOL, strings(...EXTERNAL_RUNS_ACTIONS), Type.Null()),
 ]);
+

package/src/core/concurrency.ts

@@ -42,10 +42,13 @@ export class ConcurrencyLimiter {
   private active = 0;
   private readonly waiters: Waiter[] = [];
 
-  constructor(readonly max: number) {
+  readonly max: number;
+
+  constructor(max: number) {
     if (!Number.isInteger(max) || max < 1) {
       throw new Error("ConcurrencyLimiter max must be a positive integer");
     }
+    this.max = max;
   }
 
   get activeCount(): number {

package/src/core/errors.ts

@@ -8,8 +8,11 @@ export type FlowErrorCode = (typeof FLOW_ERROR_CODES)[number];
 
 /** Expected caller/configuration failure, distinct from a programming error. */
 export class ExpectedFlowError extends Error {
-  constructor(readonly code: FlowErrorCode, message: string) {
+  readonly code: FlowErrorCode;
+
+  constructor(code: FlowErrorCode, message: string) {
     super(message);
+    this.code = code;
     this.name = "ExpectedFlowError";
   }
 }

package/src/core/run-inspection.ts

@@ -839,7 +839,7 @@ function encodeCursor(cursor: InspectionCursor | ListCursor): string {
 }
 
 function decodeCursor(value: string): InspectionCursor | ListCursor {
-  if (!value || value.length > MAX_CURSOR_CHARS) throw cursorInvalid();
+  if (typeof value !== "string" || !value || value.length > MAX_CURSOR_CHARS) throw cursorInvalid();
   let parsed: Record<string, unknown> | undefined;
   try {
     parsed = asRecord(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));

package/src/core/run-registry.ts

@@ -80,11 +80,16 @@ export class RunRegistry {
   private readonly closedSessions = new Set<string>();
   private readonly backgroundListeners = new Set<(event: BackgroundRunEvent) => void>();
 
-  constructor(private readonly completedLimit = DEFAULT_COMPLETED_LIMIT, private readonly shutdownGraceMs = 4_000) {
+  private readonly completedLimit: number;
+  private readonly shutdownGraceMs: number;
+
+  constructor(completedLimit = DEFAULT_COMPLETED_LIMIT, shutdownGraceMs = 4_000) {
     if (!Number.isInteger(completedLimit) || completedLimit < 0) {
       throw new Error("completed run limit must be a non-negative integer");
     }
     if (!Number.isInteger(shutdownGraceMs) || shutdownGraceMs < 0) throw new Error("shutdown grace must be a non-negative integer");
+    this.completedLimit = completedLimit;
+    this.shutdownGraceMs = shutdownGraceMs;
   }
 
   sessionVersion(sessionId: string): number {

package/src/external-command.ts

@@ -1090,8 +1090,11 @@ type ExternalRunsResult = { content: Array<{ type: string; text?: string }>; det
 
 /** A returned external_runs failure, raised with its code so callers recover by code, never by message. */
 class RunsActionError extends Error {
-  constructor(readonly code: string, message: string) {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
     super(message);
+    this.code = code;
   }
 }
 

package/src/external-help.ts

@@ -7,6 +7,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { filterProfilesForModelRegistry } from "./core/model.ts";
+import { formatExternalRunsActionGuidance } from "./contract/runs.ts";
 import { disabledHarnessMessage, loadExternalCatalog } from "./profiles.ts";
 import { loadHarnessConfigs } from "./harnesses.ts";
 import {
@@ -103,6 +104,8 @@ Execution mode: foreground is blocking by default when you need the result next,
 
 Supervision: external_runs selects targets with runIds. list takes optional workflowRunId, cursor, workflowCursor, and limit. inspect with one id reads summary/output/diagnostics/final/launch and pages with cursor and limitBytes; several ids (up to 20) batch summary only. wait takes up to 100 runIds in mode any or all; check ok for the operation, then each completed run's outcome and pending IDs. It never cancels pending work and can return early on a failed workflow even in all mode. If settlement is already known, skip wait. Use inline successful output when available; otherwise inspect final and follow nextCursor. Failures need diagnostics/output, not final. Follow nextWorkflowCursor for workflow listings too. Foreground-call interruption cancels that call; interrupting wait only stops waiting. Use cancel with one id and an optional reason to stop background work. Cancelling a workflow stops active children; cancelling one child is a catchable workflow error. There is no live steering.
 
+${formatExternalRunsActionGuidance()}
+
 Replay: resumeFromRunId works only with persisted scriptPath and starts an explicit new attempt. It reuses the longest unchanged prefix of successful child calls; the first changed/failed/cancelled/timed-out call and its suffix run again. Script recomposition is cheap, but child reruns can cost money or repeat side effects. There is no automatic repaired-script replay.
 
 Background is an external_workflow tool call parameter ({ script, background: true }), never a meta field — meta.background is silently ignored and does not run the workflow in the background.

package/src/external-runs.ts

@@ -1,7 +1,6 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionContext, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Container, Text } from "@earendil-works/pi-tui";
-import { Type, type Static } from "typebox";
+import { type Static } from "typebox";
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import { getRunRecord, inspectRun, listRunRecords, type RunInspectionView, type RunRecordListItem } from "./core/run-inspection.ts";
@@ -13,7 +12,16 @@ import { SPINNER_INTERVAL_MS } from "./core/spinner.ts";
 import { EXTERNAL_RUNS_PROMPT_SNIPPET } from "./prompts.ts";
 import { envelope, INLINE_RESULT_BYTES, redactedText, withContract } from "./contract/envelope.ts";
 import { durableAgentRun, journalWorkflowRun, liveAgentRun, liveWorkflowRun, unreadableWorkflowRun, type EvidenceIntegrity, type PublicRun } from "./contract/run.ts";
-import { externalRunsOutputSchema } from "./contract/runs.ts";
+import {
+  EXTERNAL_RUNS_ACTIONS,
+  EXTERNAL_RUNS_EXAMPLES,
+  externalRunsOutputSchema,
+  externalRunsParameters,
+  MAX_BATCH_INSPECT_TARGETS,
+  MAX_WAIT_TARGETS,
+  SINGLE_INSPECT_VIEWS,
+  WAIT_MODES,
+} from "./contract/runs.ts";
 import { ExpectedFlowError } from "./core/errors.ts";
 import { redactSecrets } from "./core/run-record.ts";
 import type { WorkflowToolDetails } from "./types.ts";
@@ -21,52 +29,6 @@ import { getSessionWorkflowDir, listWorkflowJournals, loadWorkflowJournal, Workf
 
 const RUN_ID = /^(?:run|wf)_[A-Za-z0-9_-]{1,128}$/;
 const WORKFLOW_ID = /^wf_[A-Za-z0-9_-]{1,128}$/;
-const MAX_TARGETS = 100;
-/**
- * Cap for `inspect`'s batch `runIds` mode. Intentionally lower than `wait`'s
- * MAX_TARGETS (100): batch inspection returns full projections and may touch
- * live evidence reads per target, so it stays cheap by staying small.
- */
-const MAX_BATCH_INSPECT_TARGETS = 20;
-
-const externalRunsParameters = Type.Object({
-  action: StringEnum(["list", "inspect", "wait", "cancel"] as const, {
-    description: "list: page runs/workflows; inspect: read one run; wait: block until selected terminal outcomes; cancel: stop one run.",
-  }),
-  runIds: Type.Optional(Type.Array(Type.String(), {
-    maxItems: MAX_TARGETS,
-    description: "Target run IDs (run_... agent, wf_... workflow). For inspect: a single-entry list [\"run_...\"] inspects that run with any view (summary, output, diagnostics, final); multiple entries (1-20 targets) batch summary inspect. For cancel: a single-entry list [\"run_...\"]. For wait: any|all of up to 100 targets.",
-  })),
-  view: Type.Optional(StringEnum(["summary", "output", "diagnostics", "final", "launch"] as const, {
-    description: "inspect view: launch (recorded prompt, context and execution configuration; sensitive, explicit inspection only), summary (state/timing/freshness/refs, default), output (assistant text plus canonical result, partial or final), diagnostics (tool activity/errors), final (only the verified canonical terminal answer, empty until a successful terminal boundary exists). Batch inspect (runIds) only supports summary.",
-  })),
-  mode: Type.Optional(StringEnum(["any", "all"] as const, {
-    description: "wait mode: any returns on the first terminal outcome; all waits for every target. Neither cancels pending work; an unsuccessful selected workflow returns early even in all mode.",
-  })),
-  cursor: Type.Optional(Type.String({
-    description: "Opaque continuation cursor from a prior response; pass back verbatim to page. Stale/reused cursors fail with an actionable error.",
-  })),
-  workflowCursor: Type.Optional(Type.String({
-    description: "Opaque cursor paging the workflow-roots listing (list action); pass back verbatim. Not used when workflowRunId filters to one workflow's children.",
-  })),
-  limit: Type.Optional(Type.Integer({
-    minimum: 1,
-    maximum: 100,
-    description: "Max entries per list/children page.",
-  })),
-  limitBytes: Type.Optional(Type.Integer({
-    minimum: 4,
-    maximum: 65536,
-    description: "Max bytes per inspect page, including the summary view; follow nextCursor for the remainder. For wait, this is the total result budget shared across every settled outcome in the response (default 32768): a result that fits is returned complete, one that does not is truncated with resultTruncated:true and outputRef/diagnosticsRef for the rest.",
-  })),
-  workflowRunId: Type.Optional(Type.String({
-    description: "list filter: children of this wf_... workflow only.",
-  })),
-  reason: Type.Optional(Type.String({
-    maxLength: 512,
-    description: "Optional cancellation reason recorded with the run evidence.",
-  })),
-});
 
 export type ExternalRunsParams = Static<typeof externalRunsParameters> & {
   /** Legacy single-target selector; preserved for backwards-compatible programmatic/test callers. */
@@ -112,8 +74,16 @@ function notLive(message: string): ExpectedFlowError {
   return new ExpectedFlowError("run_not_live", message);
 }
 
-function assertRunId(runId: unknown): asserts runId is string {
-  if (typeof runId !== "string" || !RUN_ID.test(runId)) throw invalid("Invalid run ID");
+function assertRunId(runId: unknown, action: "inspect" | "wait" | "cancel" = "inspect"): asserts runId is string {
+  if (typeof runId === "string" && RUN_ID.test(runId)) return;
+  const example = action === "cancel"
+    ? EXTERNAL_RUNS_EXAMPLES.cancel
+    : action === "wait"
+      ? EXTERNAL_RUNS_EXAMPLES.wait
+      : EXTERNAL_RUNS_EXAMPLES.inspectSingle;
+  throw invalid(
+    `Invalid run ID for ${action}; pass a run_... or wf_... ID in runIds, e.g. ${JSON.stringify(example)}.`,
+  );
 }
 
 function assertOwned(entry: Pick<RegisteredRunEntry, "sessionId" | "project">, sessionId: string, project: string): void {
@@ -293,8 +263,16 @@ function decodeUnpersistedCursor(value: string, scope: string): UnpersistedBookm
   if (parsed?.kind !== "unpersisted-list") return undefined;
   const keys = Object.keys(parsed).sort().join(",");
   const valid = parsed.v === 1 && ((keys === "after,kind,scope,v" && typeof parsed.after === "string" && RUN_ID.test(parsed.after)) || (keys === "kind,persisted,scope,v" && parsed.persisted === true));
-  if (!valid) throw cursorInvalid("Invalid list cursor");
-  if (parsed.scope !== scope) throw cursorInvalid("Cursor belongs to a different list scope");
+  if (!valid) {
+    throw cursorInvalid(
+      `Invalid list cursor; pass nextCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listRunsNextPage)}) or nextWorkflowCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowsNextPage)}), or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+    );
+  }
+  if (parsed.scope !== scope) {
+    throw cursorInvalid(
+      `Cursor belongs to a different list scope for list; use cursor for runs (or workflowRunId children) and workflowCursor for unfiltered workflows, or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+    );
+  }
   return typeof parsed.after === "string" ? { after: parsed.after } : { persisted: true };
 }
 
@@ -317,7 +295,18 @@ async function pageUnpersistedFirst<L extends { runId: string }, D>(
   persisted: (limit: number, cursor: string | undefined) => Promise<{ items: D[]; nextCursor?: string }>,
 ): Promise<{ live: L[]; items: D[]; nextCursor?: string }> {
   const bookmark = cursor === undefined ? undefined : decodeUnpersistedCursor(cursor, scope);
-  if (cursor !== undefined && bookmark === undefined) return { live: [], ...await persisted(pageSize, cursor) };
+  if (cursor !== undefined && bookmark === undefined) {
+    try {
+      return { live: [], ...await persisted(pageSize, cursor) };
+    } catch (error) {
+      if (error instanceof ExpectedFlowError && error.code === "cursor_invalid") {
+        throw cursorInvalid(
+          `${error.message} for list; pass nextCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listRunsNextPage)}) or nextWorkflowCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowsNextPage)}), or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+        );
+      }
+      throw error;
+    }
+  }
   if (bookmark && "persisted" in bookmark) return { live: [], ...await persisted(pageSize, undefined) };
   let start = 0;
   if (bookmark) {
@@ -465,12 +454,15 @@ function encodeBatchCursor(scope: string, runIds: string[], nextIndex: number):
  * invalidate the cursor.
  */
 function decodeBatchCursor(value: string, scope: string, runIds: string[]): number {
-  if (!value || value.length > 8192) throw cursorInvalid();
+  const invalidBatch = () => cursorInvalid(
+    `Invalid inspect batch cursor; pass nextCursor with the identical runIds array, or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectBatch)}.`,
+  );
+  if (typeof value !== "string" || !value || value.length > 8192) throw invalidBatch();
   let parsed: Record<string, unknown>;
   try {
     parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as Record<string, unknown>;
   } catch {
-    throw cursorInvalid();
+    throw invalidBatch();
   }
   if (
     !parsed ||
@@ -480,14 +472,20 @@ function decodeBatchCursor(value: string, scope: string, runIds: string[]): numb
     !Array.isArray(parsed.runIds) ||
     !Number.isSafeInteger(parsed.nextIndex)
   ) {
-    throw cursorInvalid();
+    throw invalidBatch();
+  }
+  if (parsed.scope !== scope) {
+    throw cursorInvalid(
+      `Cursor belongs to a different session or project for inspect; restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectBatch)}.`,
+    );
   }
-  if (parsed.scope !== scope) throw cursorInvalid("Cursor belongs to a different session or project");
   if (JSON.stringify(parsed.runIds) !== JSON.stringify(runIds)) {
-    throw cursorInvalid("Batch cursor does not match the requested run IDs; repeat the identical runIds array to continue paging");
+    throw cursorInvalid(
+      `Batch cursor does not match the requested run IDs for inspect; repeat the identical runIds array to continue paging, or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectBatch)}.`,
+    );
   }
   const nextIndex = parsed.nextIndex as number;
-  if (nextIndex < 0 || nextIndex > runIds.length) throw cursorInvalid();
+  if (nextIndex < 0 || nextIndex > runIds.length) throw invalidBatch();
   return nextIndex;
 }
 
@@ -504,15 +502,18 @@ function encodeProjectionCursor(runId: string, view: RunInspectionView, offset:
 }
 
 function decodeProjectionCursor(value: string, runId: string, view: RunInspectionView, text: string): number {
-  if (!value || value.length > 4096) throw cursorInvalid();
+  const invalidInspect = () => cursorInvalid(
+    `Invalid inspect cursor; pass page.nextCursor with the same runId and view, or restart with ${JSON.stringify({ action: "inspect", runIds: [runId], view })}.`,
+  );
+  if (typeof value !== "string" || !value || value.length > 4096) throw invalidInspect();
   let parsed: Record<string, unknown>;
   try {
     parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as Record<string, unknown>;
   } catch {
-    throw cursorInvalid();
+    throw invalidInspect();
   }
   const keys = parsed && typeof parsed === "object" ? Object.keys(parsed).sort().join(",") : "";
-  if (keys !== "kind,offset,revision,runId,v,view" || parsed.v !== 1 || parsed.kind !== "projection-inspect" || parsed.runId !== runId || parsed.view !== view || !Number.isSafeInteger(parsed.offset) || (parsed.offset as number) < 0 || typeof parsed.revision !== "string") throw cursorInvalid();
+  if (keys !== "kind,offset,revision,runId,v,view" || parsed.v !== 1 || parsed.kind !== "projection-inspect" || parsed.runId !== runId || parsed.view !== view || !Number.isSafeInteger(parsed.offset) || (parsed.offset as number) < 0 || typeof parsed.revision !== "string") throw invalidInspect();
   if (parsed.revision !== projectionRevision(text)) throw cursorStale();
   return parsed.offset as number;
 }
@@ -700,7 +701,7 @@ function renderExternalRunsCall(args: Record<string, unknown>, theme: Theme): Te
       : String(args.runId ?? "");
     detail = `inspect ${target} · ${typeof args.view === "string" ? args.view : "summary"}`;
   } else {
-    detail = `list${typeof args.workflowRunId === "string" ? ` · workflow ${args.workflowRunId}` : ""}`;
+    detail = `list${typeof args.workflowRunId === "string" && args.workflowRunId.trim() !== "" ? ` · workflow ${args.workflowRunId.trim()}` : ""}`;
   }
   return new Text(`${theme.bold("External Runs")} ${theme.fg("dim", detail)}`, 0, 0);
 }
@@ -824,7 +825,9 @@ function normalizeInspectSelectors(params: ExternalRunsParams): ExternalRunsPara
     ? undefined
     : params.runIds;
   if (runId !== undefined && runIds !== undefined && runIds.length > 0) {
-    throw invalid("inspect accepts either runId or runIds, not both");
+    throw invalid(
+      `inspect accepts either runId or runIds, not both; e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectSingle)}.`,
+    );
   }
   if (runId === params.runId && runIds === params.runIds) return params;
   return { ...params, runId, runIds };
@@ -850,9 +853,17 @@ export function createExternalRunsTool(
     parameters: externalRunsParameters,
     outputSchema: externalRunsOutputSchema,
     async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx: ExtensionContext) {
-      const action = params.action ?? "list";
+      const action = (params.action && (EXTERNAL_RUNS_ACTIONS as readonly string[]).includes(params.action)) ? params.action : "list";
       return await withContract({ tool: "external_runs", action, failureData: null }, async () => {
       if (params.action === "inspect") {
+        if (
+          params.limitBytes !== undefined &&
+          (typeof params.limitBytes !== "number" || !Number.isSafeInteger(params.limitBytes) || params.limitBytes < 4 || params.limitBytes > 65536)
+        ) {
+          throw invalid(
+            `Invalid limitBytes for inspect (must be an integer from 4 to 65536); e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectSingle)}.`,
+          );
+        }
         params = normalizeInspectSelectors(params);
         if (params.runId === undefined && params.runIds !== undefined && params.runIds.length === 1 && params.view !== undefined && params.view !== "summary") {
           params = { ...params, runId: params.runIds[0], runIds: undefined };
@@ -862,30 +873,76 @@ export function createExternalRunsTool(
       const runsDirectory = options.runsDirectory();
 
       if (params.action === "list") {
-        if (params.workflowRunId !== undefined && !WORKFLOW_ID.test(params.workflowRunId)) throw invalid("Invalid workflow run ID");
+        if (
+          params.limit !== undefined &&
+          (typeof params.limit !== "number" || !Number.isSafeInteger(params.limit) || params.limit < 1 || params.limit > 100)
+        ) {
+          throw invalid(
+            `Invalid limit for list (must be an integer from 1 to 100); e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+          );
+        }
+        if (
+          params.workflowRunId !== undefined &&
+          (typeof params.workflowRunId !== "string" || (params.workflowRunId.trim() !== "" && !WORKFLOW_ID.test(params.workflowRunId.trim())))
+        ) {
+          throw invalid(
+            `Invalid workflow run ID for list; pass a wf_... ID (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowChildren)}) or omit workflowRunId (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}).`,
+          );
+        }
+        const workflowRunId = typeof params.workflowRunId === "string" && params.workflowRunId.trim() !== ""
+          ? params.workflowRunId.trim()
+          : undefined;
+        if (
+          workflowRunId !== undefined &&
+          params.workflowCursor !== undefined &&
+          (typeof params.workflowCursor !== "string" || params.workflowCursor.trim() !== "")
+        ) {
+          throw invalid(
+            `workflowCursor is inapplicable when filtering list by workflowRunId; page child runs with cursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listRunsNextPage)}) or omit workflowRunId to page workflow roots (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowsNextPage)}).`,
+          );
+        }
+        if (
+          workflowRunId === undefined &&
+          params.workflowCursor !== undefined &&
+          typeof params.workflowCursor !== "string"
+        ) {
+          throw cursorInvalid(
+            `Invalid workflow list cursor for list; pass nextWorkflowCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowsNextPage)}), or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+          );
+        }
+        if (
+          params.cursor !== undefined &&
+          typeof params.cursor !== "string"
+        ) {
+          throw cursorInvalid(
+            `Invalid cursor for list; pass nextCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listRunsNextPage)}) or nextWorkflowCursor (${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.listWorkflowsNextPage)}), or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+          );
+        }
+        const workflowCursor = typeof params.workflowCursor === "string" ? params.workflowCursor.trim() || undefined : undefined;
+        const cursor = typeof params.cursor === "string" ? params.cursor.trim() || undefined : undefined;
         const workflowDir = getSessionWorkflowDir(ctx);
         // Live state overlays its persisted row on whichever page that row
         // falls, so a live run is never shown as interrupted or listed twice.
         // Live runs with no persisted row yet are paged first, inside the same
         // limit, before the persisted rows begin.
         const registered = new Map(options.registry.list(sessionId, project).map((entry) => [entry.runId, entry]));
-        const runScope = listScope("runs", sessionId, project, params.workflowRunId);
-        const page = params.workflowCursor && !params.cursor
+        const runScope = listScope("runs", sessionId, project, workflowRunId);
+        const page = workflowCursor && !cursor
           ? { live: [], items: [] }
-          : await pageUnpersistedFirst(runScope, params.cursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 50))),
-            [...registered.values()].filter((entry) => entry.kind === "agent" && (params.workflowRunId === undefined || entry.workflowRunId === params.workflowRunId)),
+          : await pageUnpersistedFirst(runScope, cursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 50))),
+            [...registered.values()].filter((entry) => entry.kind === "agent" && (workflowRunId === undefined || entry.workflowRunId === workflowRunId)),
             async (entry) => {
               const persisted = await getRunRecord(runsDirectory, entry.runId);
               return !persisted || persisted.parentSessionId !== sessionId || persisted.project !== project
-                || (params.workflowRunId !== undefined && persisted.workflowRunId !== params.workflowRunId);
+                || (workflowRunId !== undefined && persisted.workflowRunId !== workflowRunId);
             },
-            (limit, cursor) => listRunRecords({ runsDirectory, sessionId, project, workflowRunId: params.workflowRunId, limit, cursor }));
-        const historical = params.workflowRunId
+            (limit, c) => listRunRecords({ runsDirectory, sessionId, project, workflowRunId, limit, cursor: c }));
+        const historical = workflowRunId
           ? { live: [], items: [] }
-          : await pageUnpersistedFirst(listScope("workflows", sessionId, project), params.workflowCursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 100))),
+          : await pageUnpersistedFirst(listScope("workflows", sessionId, project), workflowCursor, Math.max(1, Math.min(100, Math.floor(params.limit ?? 100))),
             [...registered.values()].filter((entry) => entry.kind === "workflow"),
             async (entry) => !workflowDir || !await hasWorkflowJournal(workflowDir, entry.runId, project),
-            async (limit, cursor) => workflowDir ? listWorkflowJournals(workflowDir, project, limit, cursor) : { items: [] });
+            async (limit, c) => workflowDir ? listWorkflowJournals(workflowDir, project, limit, c) : { items: [] });
         const workflowRows: Array<{ legacy: Record<string, unknown>; run: PublicRun }> = [
           ...historical.live.map((entry) => ({ legacy: liveSummary(entry), run: liveWorkflowRun(entry).run })),
           ...historical.items.map((journal) => {
@@ -915,14 +972,26 @@ export function createExternalRunsTool(
 
       if (params.action === "inspect" && params.runIds !== undefined) {
         // normalizeInspectSelectors already guarantees runId is unset here.
-        if (params.view !== undefined && params.view !== "summary") throw invalid('Batch inspect (runIds) only supports view: "summary"');
+        if (params.view !== undefined && params.view !== "summary") {
+          throw invalid(
+            `Batch inspect (runIds) only supports view: "summary"; use ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectBatch)} for batch summary or ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectSingle)} for a single run.`,
+          );
+        }
         const runIds = [...new Set(params.runIds)];
         if (runIds.length === 0 || runIds.length > MAX_BATCH_INSPECT_TARGETS) {
-          throw invalid(`inspect runIds requires 1-${MAX_BATCH_INSPECT_TARGETS} run IDs`);
+          throw invalid(
+            `inspect runIds requires 1-${MAX_BATCH_INSPECT_TARGETS} run IDs; e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectSingle)} or ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectBatch)}.`,
+          );
+        }
+        for (const runId of runIds) assertRunId(runId, "inspect");
+        if (params.cursor !== undefined && typeof params.cursor !== "string") {
+          throw cursorInvalid(
+            `Invalid batch cursor; pass nextCursor verbatim with the identical runIds array, or restart with ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectBatch)}.`,
+          );
         }
-        for (const runId of runIds) assertRunId(runId);
+        const cursor = typeof params.cursor === "string" ? params.cursor.trim() || undefined : undefined;
         const scope = batchCursorScope(sessionId, project);
-        const startIndex = params.cursor ? decodeBatchCursor(params.cursor, scope, runIds) : 0;
+        const startIndex = cursor ? decodeBatchCursor(cursor, scope, runIds) : 0;
         // Resolve (and thereby validate ownership of) every requested target
         // before returning any page — an invalid or cross-session/project
         // target anywhere in the set fails the whole request, not just the
@@ -960,9 +1029,20 @@ export function createExternalRunsTool(
       }
 
       if (params.action === "inspect") {
-        assertRunId(params.runId);
+        if (params.view !== undefined && !SINGLE_INSPECT_VIEWS.includes(params.view as any)) {
+          throw invalid(
+            `Invalid view ${JSON.stringify(params.view)} for inspect; choose ${SINGLE_INSPECT_VIEWS.join(", ")}, e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.inspectSingle)}.`,
+          );
+        }
+        assertRunId(params.runId, "inspect");
         const runId = params.runId;
         const view = params.view ?? "summary";
+        if (params.cursor !== undefined && typeof params.cursor !== "string") {
+          throw cursorInvalid(
+            `Invalid inspect cursor; pass page.nextCursor with the same runId and view, or restart with ${JSON.stringify({ action: "inspect", runIds: [runId], view })}.`,
+          );
+        }
+        const cursor = typeof params.cursor === "string" ? params.cursor.trim() || undefined : undefined;
         const entry = options.registry.get(runId);
         if (entry) assertOwned(entry, sessionId, project);
         const single = (text: string, encoding: "json" | "text", details: Record<string, unknown>, extra: { finalAvailable?: boolean; outputStatus?: string } = {}, contentText = text) => {
@@ -990,11 +1070,11 @@ export function createExternalRunsTool(
             // layer's job (src/external-command.ts's showPages), not this tool's.
             if (!finalAvailable) {
               const status = entry ? (entry.state === "running" ? "running" : entry.outcome?.status) : historical!.status;
-              const page = projectionPage(runId, view, "", params.cursor, params.limitBytes);
+              const page = projectionPage(runId, view, "", cursor, params.limitBytes);
               return single(page.text, "json", { runId, view, text: page.text, finalAvailable: false, status: status ?? "running", nextCursor: page.nextCursor }, { finalAvailable: false });
             }
             const text = JSON.stringify(redactSecrets({ runId, result: workflowResult, finalAvailable: true }));
-            const page = projectionPage(runId, view, text, params.cursor, params.limitBytes);
+            const page = projectionPage(runId, view, text, cursor, params.limitBytes);
             return single(page.text, "json", { runId, view, text: page.text, finalAvailable: true, nextCursor: page.nextCursor }, { finalAvailable: true });
           }
           const source = view === "launch"
@@ -1008,7 +1088,7 @@ export function createExternalRunsTool(
               ? { runId, result: entry ? entry.outcome?.result : historical?.result }
               : { runId, status: entry?.outcome?.status ?? historical?.status ?? "running", error: entry?.outcome?.error ?? historical?.error };
           const text = JSON.stringify(redactSecrets(source));
-          const page = projectionPage(runId, view, text, params.cursor, params.limitBytes);
+          const page = projectionPage(runId, view, text, cursor, params.limitBytes);
           return single(page.text, "json", { runId, view, text: page.text, nextCursor: page.nextCursor });
         }
         // A wf_... ID that resolved to neither a live nor a historical
@@ -1020,25 +1100,35 @@ export function createExternalRunsTool(
         if (!entry) assertOwnedRecord(durable, sessionId, project);
         if (view === "summary") {
           const source = entry ? redactSecrets(projectLiveAgent(entry)) : historicalAgent(durable!);
-          const page = projectionPage(runId, view, JSON.stringify(source), params.cursor, params.limitBytes);
+          const page = projectionPage(runId, view, JSON.stringify(source), cursor, params.limitBytes);
           return single(page.text, "json", { runId, view, text: page.text, nextCursor: page.nextCursor });
         }
         // A settled successful result in the registry is the verified final
         // answer, so a final reference stays followable even when evidence
         // was never persisted.
-        if (view === "final" && entry?.kind === "agent" && entry.outcome?.status === "done" && entry.outcome.result !== undefined && (!params.cursor || isProjectionCursor(params.cursor))) {
-          const page = projectionPage(runId, view, liveAgentOutput(entry) ?? "", params.cursor, params.limitBytes);
+        if (view === "final" && entry?.kind === "agent" && entry.outcome?.status === "done" && entry.outcome.result !== undefined && (!cursor || isProjectionCursor(cursor))) {
+          const page = projectionPage(runId, view, liveAgentOutput(entry) ?? "", cursor, params.limitBytes);
           return single(page.text, "text", { runId, view, text: page.text, finalAvailable: true, outputStatus: "final", nextCursor: page.nextCursor }, { finalAvailable: true, outputStatus: "final" });
         }
-        if (view === "output" && entry?.kind === "agent" && (!params.cursor || isProjectionCursor(params.cursor))) {
+        if (view === "output" && entry?.kind === "agent" && (!cursor || isProjectionCursor(cursor))) {
           const text = liveAgentOutput(entry);
           if (text !== undefined) {
-            const page = projectionPage(runId, view, text, params.cursor, params.limitBytes);
+            const page = projectionPage(runId, view, text, cursor, params.limitBytes);
             const outputStatus = entry.state === "running" ? "preliminary" : entry.outcome?.outcome === "succeeded" ? "final" : "interrupted";
             return single(page.text, "text", { runId, view, text: page.text, outputStatus, nextCursor: page.nextCursor }, { outputStatus });
           }
         }
-        const page = await inspectRun({ runsDirectory, runId, view, limitBytes: params.limitBytes, cursor: params.cursor, live: entry?.state === "running" });
+        let page: Awaited<ReturnType<typeof inspectRun>>;
+        try {
+          page = await inspectRun({ runsDirectory, runId, view, limitBytes: params.limitBytes, cursor, live: entry?.state === "running" });
+        } catch (error) {
+          if (error instanceof ExpectedFlowError && error.code === "cursor_invalid") {
+            throw cursorInvalid(
+              `${error.message} for inspect; pass nextCursor with matching runId and view, or restart with ${JSON.stringify({ action: "inspect", runIds: [runId], view })}.`,
+            );
+          }
+          throw error;
+        }
         const text = pageItemsText(page);
         // view: "final" stays a clean, narration-free canonical-answer
         // surface — a bounded empty page (finalAvailable:false) when
@@ -1050,16 +1140,25 @@ export function createExternalRunsTool(
       }
 
       if (params.action === "cancel") {
+        if (params.reason !== undefined && (typeof params.reason !== "string" || params.reason.length > 512)) {
+          throw invalid(
+            `Invalid reason for cancel (must be a string up to 512 characters); e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.cancelWithReason)}.`,
+          );
+        }
         const rawRunIds = params.runIds;
         if (rawRunIds?.length && params.runId?.trim()) {
-          throw invalid("cancel accepts either runId or runIds, not both");
+          throw invalid(
+            `cancel accepts either runId or runIds, not both; e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.cancel)}.`,
+          );
         }
         if (rawRunIds && rawRunIds.length > 1) {
-          throw invalid("cancel targets one run at a time");
+          throw invalid(
+            `cancel targets one run at a time; e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.cancel)}.`,
+          );
         }
         const targetRunId = (rawRunIds && rawRunIds.length === 1 ? rawRunIds[0] : undefined)
           ?? (typeof params.runId === "string" && params.runId.trim() !== "" ? params.runId.trim() : undefined);
-        assertRunId(targetRunId);
+        assertRunId(targetRunId, "cancel");
         const cancelled = (status: "requested" | "terminal") => ({
           ...result(status === "requested" ? `Cancellation requested for ${targetRunId}.` : `${targetRunId} is already terminal.`, { runId: targetRunId, status }),
           data: { runId: targetRunId, status },
@@ -1067,7 +1166,8 @@ export function createExternalRunsTool(
         const entry = options.registry.get(targetRunId);
         if (entry) {
           assertOwned(entry, sessionId, project);
-          const status = options.registry.cancel(targetRunId, params.reason ?? "cancelled by external_runs");
+          const reason = params.reason?.trim() ? params.reason.trim() : "cancelled by external_runs";
+          const status = options.registry.cancel(targetRunId, reason);
           // "unknown" means the entry left the registry between get and cancel.
           if (status === "unknown") throw unavailable();
           return cancelled(status);
@@ -1086,9 +1186,36 @@ export function createExternalRunsTool(
         throw notLive("Run is no longer live in this session; cancellation cannot be confirmed");
       }
 
-      const runIds = [...new Set(params.runIds ?? (params.runId ? [params.runId] : []))];
-      if (runIds.length === 0 || runIds.length > MAX_TARGETS) throw invalid(`wait requires 1-${MAX_TARGETS} run IDs`);
-      for (const runId of runIds) assertRunId(runId);
+      if (params.action === "wait") {
+        if (
+          params.limitBytes !== undefined &&
+          (typeof params.limitBytes !== "number" || !Number.isSafeInteger(params.limitBytes) || params.limitBytes < 4 || params.limitBytes > 65536)
+        ) {
+          throw invalid(
+            `Invalid limitBytes for wait (must be an integer from 4 to 65536); e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.wait)}.`,
+          );
+        }
+        if (params.mode !== undefined && !WAIT_MODES.includes(params.mode as any)) {
+          throw invalid(
+            `Invalid mode ${JSON.stringify(params.mode)} for wait; choose ${WAIT_MODES.join(" or ")}, e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.wait)}.`,
+          );
+        }
+        const rawRunIds = params.runIds;
+        if (rawRunIds?.length && params.runId?.trim()) {
+          throw invalid(
+            `wait accepts either runId or runIds, not both; e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.wait)}.`,
+          );
+        }
+        const rawWaitRunIds = (rawRunIds && rawRunIds.length > 0)
+          ? rawRunIds
+          : (params.runId?.trim() ? [params.runId.trim()] : []);
+        const runIds = [...new Set(rawWaitRunIds)];
+        if (runIds.length === 0 || runIds.length > MAX_WAIT_TARGETS) {
+          throw invalid(
+            `wait requires 1-${MAX_WAIT_TARGETS} run IDs; e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.wait)}.`,
+          );
+        }
+        for (const runId of runIds) assertRunId(runId, "wait");
       const known: WaitTarget[] = await Promise.all(runIds.map(async (runId): Promise<WaitTarget> => {
         const entry = options.registry.get(runId);
         if (entry) {
@@ -1201,6 +1328,13 @@ export function createExternalRunsTool(
         data: { mode, completed, pending: finalPending },
         warnings: [...warnings],
       };
+      }
+
+      throw invalid(
+        params.action === undefined
+          ? `Missing required action; choose list, inspect, wait, or cancel, e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`
+          : `Invalid action ${JSON.stringify(params.action)}; choose list, inspect, wait, or cancel, e.g. ${JSON.stringify(EXTERNAL_RUNS_EXAMPLES.list)}.`,
+      );
       });
     },
     renderCall(args, theme) {

package/src/pi-subagent.ts

@@ -17,6 +17,7 @@ import { resolve, join } from "node:path";
 import { resolveExecutionProfile } from './execution-config.ts';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
 import { Type, type Static } from "typebox";
 import {
@@ -51,7 +52,7 @@ import { registerProfileCreator, startRoleInterview, startHarnessInterview } fro
 import { registerExternalCommand } from "./external-command.ts";
 import { DEFAULT_EXTERNAL_SETTINGS, loadExternalSettings, resolveCtxDefaultHarness, resolveExternalSettings, renderDefaultHarness } from "./settings.ts";
 import { EXTERNAL_HARNESSES } from "./types.ts";
-import { EXTERNAL_DELEGATE_TOOL } from "./tool-names.ts";
+import { EXTERNAL_DELEGATE_TOOL, EXTERNAL_WORKFLOW_TOOL } from "./tool-names.ts";
 import type {
   PermissionTier,
   SubagentBackend,
@@ -257,6 +258,45 @@ function isSubagentProgressNode(value: unknown): value is SubagentProgressNode {
   );
 }
 
+// Launcher names a transcript saved before the #85 rename declares, and their replacements.
+const RENAMED_LAUNCHERS: ReadonlyArray<readonly [legacy: string, current: string]> = [
+  ["Agent", EXTERNAL_DELEGATE_TOOL],
+  ["workflow", EXTERNAL_WORKFLOW_TOOL],
+];
+
+// Launchers the user kept off on the command line. Pi applies `--tools` modifiers
+// to the restored loadout but does not expose them to extensions, and a `-name`
+// modifier cannot match the legacy name it replaces. `--no-tools` turns
+// extension tools off by default. SDK `tools` options are not visible here.
+function cliExcludedLaunchers(argv: readonly string[]): Set<string> {
+  if (argv.includes("--no-tools") || argv.includes("-nt")) return new Set(RENAMED_LAUNCHERS.map(([, current]) => current));
+  let tools: string[] = [];
+  argv.forEach((arg, index) => {
+    if ((arg === "--tools" || arg === "-t") && index + 1 < argv.length) {
+      tools = argv[index + 1].split(",").map((name) => name.trim());
+    }
+  });
+  return new Set(tools.filter((name) => name.startsWith("-")).map((name) => name.slice(1)));
+}
+
+// Pi restores a resumed or tree-navigated session's tool loadout from its
+// transcript. A legacy name no longer registers, so its replacement stays off.
+// Activate the replacement for each legacy name the restored loadout declares,
+// unless the loadout also declares the replacement (it was then turned off on
+// purpose) or the command line excludes it. setActiveTools ignores a tool that
+// is not registered or not allowed.
+function restoreRenamedLaunchers(pi: ExtensionAPI, ctx: ExtensionContext, argv: readonly string[] = process.argv): void {
+  const declared = new Set(
+    (getCurrentSystemMessage(ctx.sessionManager.buildSessionProjection().messages)?.toolsAdded ?? []).map((tool) => tool.name),
+  );
+  const active = pi.getActiveTools();
+  const excluded = cliExcludedLaunchers(argv);
+  const restored = RENAMED_LAUNCHERS
+    .filter(([legacy, current]) => declared.has(legacy) && !declared.has(current) && !active.includes(current) && !excluded.has(current))
+    .map(([, current]) => current);
+  if (restored.length > 0) pi.setActiveTools([...active, ...restored]);
+}
+
 function createUsageStatusState(): SubagentUsageStatusState {
   return {
     calls: new Map(),
@@ -1019,7 +1059,9 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
       if (activeSessionId) scheduleWakeFlush(activeSessionId);
     });
 
+    pi.on("session_tree", (_event, ctx) => restoreRenamedLaunchers(pi, ctx));
     pi.on("session_start", (_event, ctx) => {
+      restoreRenamedLaunchers(pi, ctx);
       const sessionId = ctx.sessionManager.getSessionId();
       rememberSessionContext(ctx, sessionId);
       inAgentTurn = false;

package/src/prompts.ts

@@ -1,3 +1,4 @@
+import { EXTERNAL_RUNS_EXAMPLES, formatExternalRunsActionGuidance } from "./contract/runs.ts";
 import type { SavedWorkflow } from "./workflow/registry.ts";
 import { EXTERNAL_HARNESSES, type PermissionTier, type SubagentProfile } from "./types.ts";
 import { externalProfileRole, externalRoleAvailability } from "./profiles.ts";
@@ -12,7 +13,7 @@ export const EXTERNAL_HELP_PROMPT_SNIPPET =
   "Show the delegation playbook, role details, permission behavior, or workflow guidance on demand.";
 
 export const EXTERNAL_RUNS_PROMPT_SNIPPET =
-  "List, inspect (single or batch summary via runIds, up to 20), wait for, or cancel session-owned external runs; follow cursors for complete output. view: final returns only a verified terminal answer, empty until one exists.";
+  "Supervise session-owned external runs (supply only fields for the chosen action): list (optional workflowRunId, limit, cursor, workflowCursor), inspect (runIds: 1 ID with any view, or 2-20 IDs for summary batch), wait (runIds 1-100, optional mode/limitBytes), or cancel (runIds: 1 ID, optional reason). view: final returns only a verified terminal answer, empty until one exists.";
 
 // Only elide the "(harness only)" suffix when every configured harness
 // carries the role; a role available on all configured CLIs but no pi harness
@@ -143,12 +144,8 @@ export const USAGE_BACKGROUND_AGENT: UsageAgentExample = {
   background: true,
 };
 
-/** Single-id batch inspect. The executor accepts runIds with view final for one id. */
-export const USAGE_RUNS_FINAL = {
-  action: "inspect" as const,
-  runIds: ["run_example"],
-  view: "final" as const,
-};
+/** Single-id inspect with final view, shared with the authoritative external_runs contract examples. */
+export const USAGE_RUNS_FINAL = EXTERNAL_RUNS_EXAMPLES.inspectSingle;
 
 /** Continues a CLI child that stored a session id. Named pi-* harnesses cannot resume. */
 export const USAGE_RESUME_AGENT: UsageAgentExample = {
@@ -219,6 +216,8 @@ Choose foreground by default when you need the result next, even for a long or p
 
 Unless the user deferred collection, after independent work use external_runs wait if settlement is not already known. When the user later asks about a deferred run, inspect its runId first and wait only if it is still running. Check ok for the operation, then each completed run's state.outcome and pending IDs; a failed workflow can return wait early even in mode all. Use successful output when delivery is inline (null/false/0 are valid); otherwise inspect view final, following cursor pages. For failures inspect diagnostics or output; final is empty without verified success. A successful workflow may still have children.failed when its script caught child errors; read the reports. Interrupting the original foreground call cancels its work. Interrupting wait only stops waiting; cancel explicitly to stop background work. Cancelling a workflow stops active children; cancelling one child throws a catchable child error. Both modes share permissions, budget enforcement, and concurrency limits. A failed or aborted run stays failed. Retry it, or switch model or harness, only when the user authorized that step. agy may make one disclosed infrastructure retry; that exception is not yours to extend.
 
+${formatExternalRunsActionGuidance()}
+
 One external_delegate call. Permission stays omitted; the prompt carries the no-edit intent:
 ${jsonBlock(USAGE_ONE_AGENT)}
 

package/src/workflow/journal.ts

@@ -48,8 +48,13 @@ export interface LoadedWorkflowJournal {
 
 /** A journal that exists but cannot be loaded; `project` is set when its own run_start line names one. */
 export class WorkflowJournalReadError extends ExpectedFlowError {
-  constructor(message: string, readonly project: string | undefined, readonly integrity: "damaged" | "unknown") {
+  readonly project: string | undefined;
+  readonly integrity: "damaged" | "unknown";
+
+  constructor(message: string, project: string | undefined, integrity: "damaged" | "unknown") {
     super("run_unavailable", message);
+    this.project = project;
+    this.integrity = integrity;
     this.name = "WorkflowJournalReadError";
   }
 }
@@ -243,7 +248,7 @@ function workflowListCursor(name: string): string {
 
 function workflowListStart(names: string[], cursor?: string): number {
   if (!cursor) return 0;
-  if (cursor.length > 4_096) throw new ExpectedFlowError("cursor_invalid", "Invalid workflow list cursor");
+  if (typeof cursor !== "string" || cursor.length > 4_096) throw new ExpectedFlowError("cursor_invalid", "Invalid workflow list cursor");
   try {
     const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as Record<string, unknown>;
     if (Object.keys(parsed).sort().join(",") !== "kind,name,v" || parsed.v !== 1 || parsed.kind !== "workflow-list" || typeof parsed.name !== "string") throw new Error();
@@ -260,8 +265,8 @@ export async function listWorkflowJournals(dir: string, project: string, limit =
   try {
     names = (await readdir(dir)).filter((name) => /^run-wf_[A-Za-z0-9_-]{1,128}\.jsonl$/.test(name)).sort().reverse();
   } catch (error) {
-    if (isNotFound(error)) return { items: [] };
-    throw error;
+    if (!isNotFound(error)) throw error;
+    names = [];
   }
   const start = workflowListStart(names, cursor);
   const pageLimit = Math.max(1, Math.min(100, limit));