@zachwill/pi-orchestrate 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Pi Orchestrate
 
-[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) adds concurrent worker orchestration to [Pi](https://pi.dev). It helps a parent agent delegate bounded work, message independent workers concurrently, and synthesize each response as it arrives.
+[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) adds concurrent worker orchestration to [Pi](https://pi.dev). A parent agent can delegate bounded work to isolated child sessions, run independent tasks concurrently, and synthesize the results.
 
 ## Install
 
@@ -8,60 +8,86 @@
 pi install npm:@zachwill/pi-orchestrate
 ```
 
-Pi packages execute with your system permissions. Review the package and worker definitions before trusting them.
+Pi packages run with your system permissions. Review this package and every worker definition you trust.
 
-## Public tools
+## Tools
 
 Pi Orchestrate adds exactly five tools:
 
-- `orchestrate` dispatches 1–12 tasks with `orchestrate({ tasks: [{ worker, title, instructions }] })`.
-- `orchestration_status` inspects the trusted catalog, catalog diagnostics, waves, and worker states without exposing full task instructions.
-- `worker_send` sends follow-up instructions to an owned reusable worker in the `ready` state.
-- `worker_abort` stops owned active work that is no longer needed.
-- `worker_close` closes an owned reusable worker in the `ready` state.
+| Tool | Call | Purpose |
+| --- | --- | --- |
+| `orchestrate` | `orchestrate({ worker, title, instructions })` | Start one worker task |
+| `orchestration_status` | `orchestration_status({})` | Inspect the trusted catalog, diagnostics, runs, and worker states |
+| `worker_send` | `worker_send({ worker_id, instructions })` | Send a follow-up to a ready reusable worker |
+| `worker_abort` | `worker_abort({ worker_ids })` or `worker_abort({ all: true })` | Stop active owned work |
+| `worker_close` | `worker_close({ worker_id })` | Close a ready reusable worker |
 
-An `orchestrate` wave first performs atomic input, catalog, and model preflight. No worker starts if any task fails that preflight. After acceptance, worker resources start independently: a resource startup failure becomes that worker's `failed` result and does not roll back or stop its peers.
+`title` is a label. `instructions` is the complete worker brief. Collapsed tool calls preview those instructions; expanded calls show them in full.
 
-All tasks in a wave execute concurrently, including a full 12-task wave. Pi Orchestrate applies no hidden concurrency throttle. Exact unchanged worker instructions remain visible in each tool call: collapsed calls preview every message, and expanded calls show every full brief. Titles are labels, never replacements for instructions.
+## Dispatch
 
-For asynchronous behavior, `orchestrate` or `worker_send` must be the sole tool call in its assistant message. Mixing either with any sibling tool call makes its wave inline and blocking. Inline work receives the parent turn's cancellation signal. Accepted async work does not retain that signal and continues independently.
+Each `orchestrate` call validates its input, worker definition, and model before allocating IDs or starting a session. Calls are admitted independently: a rejected sibling does not block valid siblings. After admission, a startup or prompt failure settles only that worker as `failed`.
 
-A successful async call yields the parent turn. Responses enter the transcript individually as workers settle, and the final response starts the parent's synthesis turn. The bottom widget is ephemeral and shows active work only; completed, failed, aborted, and reusable ready workers disappear immediately. Inline responses accumulate in the live tool output while the call blocks.
+Pi executes sibling tool calls concurrently, with no extension-level group limit or hidden throttle. Send every known independent task as sibling `orchestrate` calls in one assistant message.
 
-`orchestration_status` is for diagnostics and recovery, never a normal completion mechanism. Do not poll it for completion. If the owning session becomes inactive, its workers continue and completed results remain queued. Those results become available only when that exact owning session resumes; they are never delivered to another session.
+Execution mode depends on the complete tool-call group:
 
-Worker IDs identify live worker sessions. A reusable worker keeps the same worker ID across `worker_send` follow-ups, with each follow-up result belonging to a new wave. One-shot workers finish as `completed`. Reusable workers deliver as `ready` and wait for `worker_send` or `worker_close`. Use `worker_abort` only for active work, not to close a ready worker.
+- One `orchestrate` call is asynchronous.
+- A pure group of sibling `orchestrate` calls is asynchronous and concurrent.
+- Mixing `orchestrate` with any other tool makes the orchestration calls inline and blocking.
+- `worker_send` is asynchronous only when it is the sole tool call in the message.
 
-## Parent orchestration contract
+Inline work follows the parent turn's cancellation signal. Accepted asynchronous work detaches from that signal and continues independently.
 
-Pi Orchestrate automatically injects the authoritative orchestration contract and trusted worker catalog into the parent system prompt. In summary, the parent owns the task end to end:
+## Results and ownership
 
-1. Keep trivial or tightly coupled work in the parent session.
-2. Give every delegated task a full brief: objective, paths and scope, forbidden actions, context, constraints, observable success, checks, and expected output.
-3. Dispatch every known independent task in one `orchestrate` wave, up to 12 tasks.
-4. Make an async `orchestrate` or `worker_send` call the sole tool call in its assistant message, then yield after acceptance.
-5. Review delivered evidence and changes, resolve conflicts, integrate deliberately, and run the relevant verification.
-6. Deliver the final answer from the parent session.
+Asynchronous worker results enter the transcript individually. An ungrouped result starts a parent synthesis turn. Results from a sibling orchestration group share one final synthesis turn after every admitted member settles.
+
+All state and delivery are owner-scoped. If an owning session is busy or inactive, completed results queue until that exact session is active and idle again. They are never delivered to another session.
+
+`orchestration_status` is for diagnostics and recovery, not completion polling. It exposes bounded owner-scoped state without full task instructions or worker prompts.
+
+The bottom widget shows active work only. Completed, failed, aborted, and reusable ready workers disappear immediately. Inline work shows its current response in the live tool output while it blocks.
+
+## Lifecycle
+
+A run represents one worker generation. A worker ID identifies the live worker session.
 
-Workers provide evidence or bounded changes. They do not replace parent judgment.
+- A **one-shot** worker succeeds as `completed` and terminates.
+- A **reusable** worker succeeds as `ready` and keeps the same worker ID.
+- `worker_send` starts a new run on that ready reusable worker.
+- `worker_close` closes a ready reusable worker.
+- `worker_abort` stops active work only; `{ all: true }` does not close ready workers.
+
+Workers, runs, and queued delivery survive extension reloads and session switches within the same Pi process. Reusable workers do not survive process exit, so close them when continuity is no longer needed.
+
+## Parent contract
+
+Pi Orchestrate injects the authoritative orchestration contract and trusted catalog into the parent system prompt. The parent remains responsible for the task end to end:
+
+1. Keep trivial or tightly coupled work in the parent session.
+2. Give every worker a complete brief: objective, scope and paths, forbidden actions, context, constraints, success criteria, checks, and expected output.
+3. Dispatch independent scopes together, then yield after asynchronous acceptance.
+4. Review evidence and changes, resolve conflicts, integrate deliberately, and verify the result.
+5. Produce the final answer from the parent session.
 
-## Trusted worker catalog
+Workers provide bounded evidence or changes. They do not replace parent judgment.
 
-Definitions are loaded by name with this precedence:
+## Worker catalog
 
-1. Package workers in [`examples/workers/`](examples/workers/) are active fallbacks automatically.
-2. User definitions in `~/.pi/agent/pi-orchestrate/workers/*.md` override package fallbacks by name.
-3. Project definitions in `<project>/.pi/pi-orchestrate/workers/*.md` override user and package definitions by name, but only after Pi trusts the project.
+Definitions are loaded by name in this precedence order, from lowest to highest:
 
-An untrusted project contributes no worker definitions. Review project definitions as part of Pi's normal project-trust flow before enabling them.
+1. Package fallbacks in [`examples/workers/`](examples/workers/)
+2. User definitions in `~/.pi/agent/pi-orchestrate/workers/*.md`
+3. Project definitions in `<project>/.pi/pi-orchestrate/workers/*.md`, only after Pi trusts the project
 
-All three package fallbacks intentionally omit `model`, so they portably inherit the parent model active at dispatch. User and trusted project overrides are the model-specialization points: add `model` to an override only when that worker needs a specific provider/model.
+A higher-precedence definition replaces a lower one with the same `name`. Pi performs no project-worker discovery for an untrusted project.
 
-To customize a fallback, create a Markdown definition manually at the user or project path with the same filename and `name`. The linked package fallbacks are templates. This instruction does not assume your shell is inside a source checkout or that an npm-installed package has a particular current working directory.
+The package includes `scout`, `investigator`, `web`, and `worker` fallbacks. `scout`, `investigator`, and `worker` omit `model`, so they inherit the parent's active model at dispatch. `web` uses an installed, authenticated Codex CLI for public-web research and pins its Pi session and searches to `gpt-5.6-sol`. To customize one, copy its definition to the user or project directory and keep the same filename and `name`. Add an explicit model only when that worker needs one.
 
 ## Worker definitions
 
-A worker is a strict Markdown system prompt. Its basename must equal its `name`:
+A worker is a regular Markdown file whose basename matches its `name`:
 
 ```md
 ---
@@ -71,29 +97,32 @@ tools: read, grep, find, ls, bash
 lifecycle: reusable
 ---
 
-You are a review worker. Inspect only the assigned scope and return concise findings with file paths.
+Inspect the assigned scope and return concise findings with file paths.
 ```
 
-Frontmatter supports these fields:
+| Field | Rule |
+| --- | --- |
+| `name` | Required; must match the filename |
+| `description` | Required; used by the parent to choose a worker |
+| `tools` | Required, nonempty list using `read`, `bash`, `edit`, `write`, `grep`, `find`, or `ls` |
+| `lifecycle` | Required; exactly `one-shot` or `reusable` |
+| `model` | Optional `provider/model`; omitted inherits the parent model |
+| `thinking` | Optional Pi thinking level |
+| `skills` | Optional; omitted uses normal discovery, a list is an exact allowlist, and `[]` disables skills |
+| `compaction` | Optional worker compaction settings |
 
-- `name` and `description` are required.
-- `tools` and `lifecycle` are required. Grant the smallest useful tool set.
-- `model` is optional. When omitted, the worker inherits the parent model active when dispatched.
-- `thinking`, `skills`, and `compaction` are optional.
-- Omitted `skills` uses Pi's normal discovered skills. A nonempty `skills` list is an exact name allowlist, and `skills: []` disables skills.
-- `lifecycle` must be exactly `one-shot` or `reusable`.
-- The Markdown body must be nonempty.
+The Markdown body is the worker system prompt and must be nonempty. Unknown fields, invalid values, symlinks, and filename/name mismatches invalidate a definition.
 
-Unknown fields, invalid values, filename/name mismatches, and empty bodies invalidate a definition. A read-only prompt is not enforcement when its tools can write.
+Grant the smallest useful tool set. A read-only prompt is not enforcement when the worker has tools that can write.
 
-## Lifecycle and process limits
+## Trust and isolation
 
-Use one-shot workers for bounded investigation, review, and implementation. Use reusable workers only when follow-up continuity matters. Reusable workers remain live in memory while the Pi process is running; they do not survive process exit. Close ready reusable workers when the conversation is complete.
+Workers receive fresh durable Pi session lineage without the parent's conversation. They still run in the parent process and are not security sandboxes: they share your filesystem and environment permissions.
 
-## Isolation, trust, and writes
+Workers use normal global Pi settings, authentication, packages, extensions, skills, and context. A trusted project may also contribute project-scoped definitions, settings, extensions, skills, and context. An untrusted project contributes none of those project-scoped resources; global resources remain available.
 
-Worker sessions are isolated from the parent's conversational context, but they run in-process and are not sandboxes. They share the parent process's filesystem and environment permissions. Treat worker prompts, optional skills, models, and tool grants as trusted code.
+Other configured extensions, including provider integrations such as `@benvargas/pi-claude-code-use`, load normally in worker sessions. Pi Orchestrate excludes itself, so workers remain direct Pi children. The injected boundary forbids recursive Pi Orchestrate delegation and descendant Pi worker sessions.
 
-Workers use regular persisted Pi global settings, authentication, packages, extensions, skills, and context. Trusted projects also contribute their project settings and resources; untrusted projects do not. Extensions are active in print mode for the complete worker lifecycle, including resource discovery and provider request hooks. Pi Orchestrate excludes its own package before child extension factories execute, so workers remain direct children while other configured extensions—including provider integrations such as `@benvargas/pi-claude-code-use`—load normally. Worker definitions still provide the exact bounded tool allowlist.
+The worker definition controls the Pi tool allowlist, not operating-system authority. A trusted worker with `bash` can launch explicitly required external processes, including agent CLIs.
 
-Pi Orchestrate performs no automatic filesystem writes. A worker writes only when its instructions and granted tools cause it to do so. Parallel workers must have non-overlapping write scopes, and the parent must inspect and verify their changes.
+Pi Orchestrate performs no automatic filesystem writes. Workers write only through their granted tools and instructions. Give concurrent workers non-overlapping write scopes, then inspect and verify their changes in the parent.

package/examples/workers/investigator.md

@@ -1,41 +1,15 @@
 ---
 name: investigator
-description: Read-only worker for cross-file investigation, comparison, and evidence-based synthesis.
+description: Investigates cross-file questions and synthesizes grounded evidence.
 thinking: medium
 tools: read, grep, find, ls, bash
 lifecycle: one-shot
 ---
 
-You are an investigator worker. Trace a bounded question across the relevant files and return a synthesis the parent orchestrator can use without repeating your exploration. Deliver your output in the same language as the assignment.
+Investigate the assigned cross-file question through read-only inspection, comparison, and evidence synthesis.
 
-Do not modify files. Use bash only for read-only commands. Do not run builds, tests, or commands that mutate state.
+Do not modify files or run builds, tests, or commands that mutate state. Use bash only for read-only commands.
 
-Read enough to distinguish confirmed behavior from inference, then stop. Focus on relationships, ownership, data flow, trade-offs, and risks that directly affect the assigned question.
+Ground each finding in file paths, line ranges, or symbols. Distinguish confirmed behavior from inference, connect evidence across files, and explain the resulting system shape or conclusion. Provide grounded recommendations when the assignment requests them.
 
-## Output
-
-### Scope
-
-- What you investigated
-- What remained outside scope
-
-### Findings
-
-For each finding:
-
-- `path/to/file#L10-L20` or `symbolName` in `path/to/file`
-  - Finding: what exists or happens
-  - Evidence: why it is confirmed
-  - Relevance: why it matters
-
-### Synthesis
-
-Explain the system shape or conclusion supported by the findings.
-
-### Gaps
-
-Include only unresolved questions that materially affect implementation or review.
-
-### Start Here
-
-Name the first files or symbols the parent should inspect next.
+Return concise **Findings** and **Synthesis** sections. Add **Gaps** only for material unresolved questions and **Start Here** only when useful.

package/examples/workers/scout.md

@@ -1,36 +1,15 @@
 ---
 name: scout
-description: Fast read-only worker for tiny factual probes and bounded repository reconnaissance.
+description: Answers one small factual repository question with read-only evidence.
 thinking: medium
 tools: read, grep, find, ls, bash
 lifecycle: one-shot
 ---
 
-You are a scout worker. Investigate one narrow question quickly and return evidence the parent orchestrator can use without repeating your search. Deliver your output in the same language as the assignment.
+Answer one small factual probe through fast, shallow, read-only repository inspection.
 
-Do not modify files. Use bash only for read-only commands. Do not run builds, tests, or commands that mutate state.
+Do not modify files or run builds, tests, or commands that mutate state. Use bash only for read-only commands.
 
-Accept only bounded discovery: one path range, symbol, command output, inventory, comparison, or existence check. If the assignment requires broad synthesis, architecture judgment, planning, or implementation, stop and recommend the investigator or implementation worker.
+Accept one path, symbol, command output, short inventory, direct comparison, or existence check. If the assignment requires broader investigation, synthesis, architecture judgment, planning, or implementation, stop concisely and recommend the investigator.
 
-## Output
-
-### Scope
-
-- What you inspected
-- What you did not inspect
-
-### Findings
-
-For each finding:
-
-- `path/to/file#L10-L20` or `symbolName` in `path/to/file`
-  - Finding: concrete fact
-  - Relevance: why it matters
-
-### Gaps
-
-Include only unresolved questions that materially affect the parent task.
-
-### Start Here
-
-Name the first file or symbol the parent should inspect next.
+Return a short **Answer** and **Evidence** grounded in paths, line ranges, symbols, or command output. Add **Gaps** only when material.

package/examples/workers/web.md

@@ -0,0 +1,84 @@
+---
+name: web
+description: Researches the public web with one or more Codex searches and returns a source-grounded synthesis.
+model: openai-codex/gpt-5.6-sol
+thinking: medium
+tools: bash
+skills: []
+lifecycle: one-shot
+---
+
+You are a web research worker. Understand the assigned research objective, choose an efficient search strategy, and return a useful source-grounded synthesis in the assignment's language.
+
+Use the installed, authenticated `codex` CLI as your web-search backend. This external search process is explicitly part of your task; do not invoke Pi or other Pi workers. Do not modify project files or install anything. Use fresh temporary directories and clean them up.
+
+## Strategy
+
+Use your judgment:
+
+- For a narrow lookup, run one focused Codex search.
+- For independent entities, claims, or source families, run separate focused searches in parallel by issuing sibling bash calls in the same turn.
+- For dependent questions, search serially so later work can use earlier evidence.
+- Use a follow-up search only for a material gap, conflict, or verification need.
+- Stop when the objective is adequately answered. Do not multiply searches for cosmetic coverage.
+
+Tell each Codex process to use at most four actual web searches unless the assignment justifies a different bound. Use cached search for stable documentation or background and live search for current or time-sensitive questions.
+
+## Codex Search
+
+Use this command shape for each focused search, selecting `cached` or `live` and writing a complete prompt for that angle:
+
+```bash
+work_dir="$(mktemp -d "${TMPDIR:-/tmp}/web-search.XXXXXX")" || exit 1
+trap 'rm -rf "$work_dir"' EXIT HUP INT TERM
+last_message="$work_dir/last-message.txt"
+stdout_log="$work_dir/stdout.log"
+stderr_log="$work_dir/stderr.log"
+
+codex exec - \
+  --ignore-user-config \
+  --model gpt-5.6-sol \
+  -c 'model_reasoning_effort="medium"' \
+  -c 'web_search="cached"' \
+  --ephemeral \
+  --skip-git-repo-check \
+  --cd "$work_dir" \
+  --sandbox read-only \
+  --color never \
+  --output-last-message "$last_message" \
+  >"$stdout_log" 2>"$stderr_log" <<'CODEX_PROMPT'
+[Research this focused angle. Include the assignment's relevant scope, exclusions, known facts, URLs, source priorities, freshness needs, and search bound. Require concise findings, exact source URLs, conflicts, gaps, and cautions. Stop when the angle is answered and return partial evidence if the bound is reached.]
+CODEX_PROMPT
+status=$?
+
+if [ -s "$last_message" ]; then
+  command cat "$last_message"
+fi
+if [ "$status" -ne 0 ] || [ ! -s "$last_message" ]; then
+  printf '%s\n' '--- failure diagnostics ---'
+  command tail -n 80 "$stderr_log"
+  command tail -n 80 "$stdout_log"
+fi
+exit "$status"
+```
+
+Never use `--dangerously-bypass-approvals-and-sandbox`. Retry only when diagnostics show a clear, mechanically correctable invocation failure.
+
+## Research Standards
+
+- Preserve quoted phrases, `site:` and `filetype:` constraints, known URLs, supplied facts, and assignment exclusions.
+- Prefer official and primary sources. Verify important claims on source pages rather than relying on snippets or aggregators.
+- Treat legal, discipline, injury, health, and rumor claims cautiously. Distinguish allegations, reporting, official records, and confirmed facts.
+- Compare results across angles. Expose source conflicts, uncertainty, freshness limits, and weak coverage instead of guessing.
+- Never invent sources or claims.
+
+## Response
+
+Return a concise synthesis that directly serves the assignment. Include:
+
+- the answer or strongest supported conclusion;
+- material findings and conflicts;
+- source titles with exact URLs and relevance;
+- unresolved gaps or cautions when they matter.
+
+Do not dump search transcripts or raw temporary paths. If research fails, say what failed and return any useful partial evidence.

package/examples/workers/worker.md

@@ -1,44 +1,18 @@
 ---
 name: worker
-description: Implementation worker for bounded code changes with explicit scope and acceptance criteria.
+description: Implements a bounded change within explicit scope and acceptance criteria.
 thinking: medium
 tools: read, bash, edit, write, grep, find, ls
 lifecycle: one-shot
 ---
 
-You are an implementation worker. Complete the assigned change within its stated scope and report the result to the parent orchestrator in the same language as the assignment.
+Implement the assigned change within its stated scope.
 
-## Working rules
+- Follow loaded project conventions. Inspect nearby code and reuse existing helpers and patterns before writing new code.
+- Change only what the assignment requires. Do not fix, refactor, or investigate unrelated work.
+- Do not commit, push, or perform destructive actions unless assigned.
+- Stop and report a blocker rather than guessing when a required decision is unclear.
+- Remove unused imports, dead code, debug output, and other leftovers from your changes.
+- Run only the narrowest relevant verification permitted by the assignment and project conventions. Report pre-existing failures separately; fix only failures caused by your changes.
 
-- Read project convention files and nearby code before editing.
-- Reuse existing helpers and patterns instead of duplicating them.
-- Change only files required by the assignment.
-- Keep the implementation direct and remove unused code introduced by your work.
-- Do not commit, push, or perform destructive operations unless explicitly assigned.
-- Stop and report a blocker when a required decision is unclear.
-
-## Verification
-
-Run the narrowest relevant lint, type-check, test, or build commands. Fix only failures caused by your changes and distinguish pre-existing failures with concrete evidence.
-
-## Output
-
-### Completed
-
-Concise description of the result.
-
-### Files Changed
-
-- `path/to/file` — what changed
-
-### Verification
-
-Commands run and their results.
-
-### Blockers
-
-Include only when work could not be completed.
-
-### Observations
-
-Include only relevant out-of-scope issues that were not changed.
+Return concise sections for **Completed**, **Files Changed**, and **Verification**. Add **Blockers** only when blocked and **Observations** only for directly relevant out-of-scope findings.

package/extension/catalog.ts

@@ -13,7 +13,11 @@ import type {
   WorkerDefinition,
   WorkerSourceKind,
 } from "./domain.js";
-import { isSupportedToolName, SUPPORTED_TOOL_NAMES } from "./domain.js";
+import {
+  createWorkerCatalog,
+  isSupportedToolName,
+  SUPPORTED_TOOL_NAMES,
+} from "./domain.js";
 
 const MAX_WORKER_BYTES = 64 * 1024;
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -127,27 +131,34 @@ function isMissingPath(error: unknown): boolean {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 
-interface UnexpectedPath {
+interface IssuePath {
   readonly path: readonly PropertyKey[];
+  readonly issue: SchemaIssue.Issue;
 }
 
-function collectUnexpectedPaths(
+function collectIssuePaths(
   issue: SchemaIssue.Issue,
   parentPath: readonly PropertyKey[] = [],
-): UnexpectedPath[] {
+): IssuePath[] {
   switch (issue._tag) {
     case "Pointer":
-      return collectUnexpectedPaths(issue.issue, [...parentPath, ...issue.path]);
+      return collectIssuePaths(issue.issue, [...parentPath, ...issue.path]);
     case "Composite":
+      return issue.issues.flatMap((child) => collectIssuePaths(child, parentPath));
     case "AnyOf":
-      return issue.issues.flatMap((child) => collectUnexpectedPaths(child, parentPath));
+      return issue.issues.length === 0
+        ? [{ path: parentPath, issue }]
+        : issue.issues.flatMap((child) => collectIssuePaths(child, parentPath));
     case "Encoding":
     case "Filter":
-      return collectUnexpectedPaths(issue.issue, parentPath);
+      return collectIssuePaths(issue.issue, parentPath);
+    case "InvalidType":
+    case "InvalidValue":
+    case "MissingKey":
     case "UnexpectedKey":
-      return [{ path: parentPath }];
-    default:
-      return [];
+    case "Forbidden":
+    case "OneOf":
+      return [{ path: parentPath, issue }];
   }
 }
 
@@ -165,8 +176,9 @@ function listItems(value: unknown): readonly unknown[] {
   return Array.isArray(value) ? value : [];
 }
 
-function schemaDiagnostic(error: Schema.SchemaError, frontmatter: unknown): string {
-  const unexpected = collectUnexpectedPaths(error.issue);
+function schemaDiagnostic(issue: SchemaIssue.Issue, frontmatter: unknown): string {
+  const issuePaths = collectIssuePaths(issue);
+  const unexpected = issuePaths.filter(({ issue }) => issue._tag === "UnexpectedKey");
   const frontmatterFields = unexpected
     .filter(({ path }) => path.length === 1 && typeof path[0] === "string")
     .map(({ path }) => String(path[0]))
@@ -196,8 +208,9 @@ function schemaDiagnostic(error: Schema.SchemaError, frontmatter: unknown): stri
     "compaction",
     "lifecycle",
   ];
-  const message = error.message;
-  const field = orderedFields.find((candidate) => message.includes(`["${candidate}"]`));
+  const field = orderedFields.find((candidate) =>
+    issuePaths.some(({ path }) => path[0] === candidate)
+  );
   const value = field === undefined ? undefined : fieldValue(frontmatter, field);
 
   if (field === "name" || field === "description") {
@@ -234,13 +247,21 @@ function schemaDiagnostic(error: Schema.SchemaError, frontmatter: unknown): stri
     if (compactionFields.length > 0) {
       return `unknown compaction field${compactionFields.length === 1 ? "" : "s"}: ${compactionFields.join(", ")}`;
     }
-    if (message.includes('["enabled"]')) {
+    if (issuePaths.some(({ path }) => path[0] === "compaction" && path[1] === "enabled")) {
       return "frontmatter field 'compaction.enabled' must be a boolean";
     }
-    if (message.includes('["reserveTokens"]')) {
+    if (
+      issuePaths.some(({ path }) =>
+        path[0] === "compaction" && path[1] === "reserveTokens"
+      )
+    ) {
       return "frontmatter field 'compaction.reserveTokens' must be a non-negative integer";
     }
-    if (message.includes('["keepRecentTokens"]')) {
+    if (
+      issuePaths.some(({ path }) =>
+        path[0] === "compaction" && path[1] === "keepRecentTokens"
+      )
+    ) {
       return "frontmatter field 'compaction.keepRecentTokens' must be a non-negative integer";
     }
     return "frontmatter field 'compaction' must be a mapping";
@@ -266,7 +287,7 @@ function parseWorker(
   const { frontmatter, body } = parsed;
   const decoded = decodeWorkerFrontmatter(frontmatter);
   if (Result.isFailure(decoded)) {
-    throw new Error(schemaDiagnostic(decoded.failure, frontmatter));
+    throw new Error(schemaDiagnostic(decoded.failure.issue, frontmatter));
   }
 
   const worker = decoded.success;
@@ -381,10 +402,7 @@ export function createWorkerCatalogDiscovery(fileSystem: CatalogFileSystem) {
       diagnostics.push(...discovered.diagnostics);
     }
 
-    const workers = [...workersByName.values()].sort((left, right) =>
-      compareText(left.name, right.name),
-    );
-    return { workers, diagnostics };
+    return createWorkerCatalog([...workersByName.values()], diagnostics);
   };
 }
 

package/extension/contract.ts

@@ -30,12 +30,12 @@ function buildContract(catalog: WorkerCatalog): string {
 You are the parent orchestrator and own the task end to end.
 
 - Keep trivial or tightly coupled work in the parent. Use as many useful workers as independent scopes justify.
-- Delegate every known independent scope in one concurrent \`orchestrate\` wave with \`{ tasks: [{ worker, title, instructions }] }\`. A wave accepts at most 12 tasks, and all tasks execute concurrently with no hidden throttle.
+- Delegate each independent scope with its own \`orchestrate\` call using \`{ worker, title, instructions }\`. Emit sibling \`orchestrate\` calls in one assistant message so Pi executes them concurrently.
 - Give every worker a full brief: objective; paths/scope; forbidden actions; context; constraints; observable success; checks; expected output.
-- Input, catalog, and model preflight is atomic before any worker starts. Resource startup failures become per-worker failed results and do not roll back peers.
-- For asynchronous behavior, \`orchestrate\` or \`worker_send\` must be the sole tool call in its assistant message. Mixing either with any sibling tool call makes its wave inline and blocking.
+- Input, catalog, and model preflight is atomic per call before that worker starts. Sibling calls are admitted independently, so one rejected call does not prevent valid siblings from starting.
+- A sole \`orchestrate\` call or a pure group of sibling \`orchestrate\` calls runs asynchronously. Pi accepts a pure group concurrently, yields the parent turn, delivers each result as it settles, and starts synthesis only after the whole group settles. Mixing \`orchestrate\` with another tool makes it inline and blocking. \`worker_send\` is asynchronous only as the sole tool call in its assistant message.
 - Exact worker instructions remain visible in the tool call and can be expanded; titles are labels, not substitutes for complete messages.
-- After an accepted async wave, yield the parent turn. Worker responses arrive individually as each worker settles, and the final response starts parent synthesis. Do not duplicate delegated work, poll \`orchestration_status\`, or use it as a normal completion mechanism.
+- After an accepted async run, yield the parent turn. Worker responses arrive individually as each worker settles, and the final response starts parent synthesis. Do not duplicate delegated work, poll \`orchestration_status\`, or use it as a normal completion mechanism.
 - The active-work widget shows only workers currently starting, running, or stopping. Inline worker responses appear progressively in live tool output.
 - The parent synthesizes worker results, reviews their evidence and changes, resolves conflicts, integrates the final result, and runs the relevant verification before declaring completion.
 - Prefer one-shot workers. Use \`worker_send\` for follow-up work on a ready reusable worker, \`worker_close\` when that ready worker is finished, and \`worker_abort\` only when active work must stop.