@zachwill/pi-orchestrate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# 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 → dispatch → deliver**: delegate bounded work, dispatch independent tasks as one wave, then deliver one aggregate result to the parent.
+
+## Install
+
+```bash
+pi install npm:@zachwill/pi-orchestrate
+```
+
+Pi packages execute with your system permissions. Review the package and worker definitions before trusting them.
+
+## Public 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.
+
+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.
+
+All tasks in a wave execute concurrently, including a full 12-task wave. Pi Orchestrate applies no hidden concurrency throttle. The aggregate result preserves task order.
+
+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.
+
+A successful async call yields the parent turn until aggregate results arrive. Do not poll `orchestration_status` 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.
+
+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.
+
+## Parent orchestration contract
+
+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:
+
+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.
+
+Workers provide evidence or bounded changes. They do not replace parent judgment.
+
+## Trusted worker catalog
+
+Definitions are loaded by name with this precedence:
+
+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.
+
+An untrusted project contributes no worker definitions. Review project definitions as part of Pi's normal project-trust flow before enabling them.
+
+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.
+
+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.
+
+## Worker definitions
+
+A worker is a strict Markdown system prompt. Its basename must equal its `name`:
+
+```md
+---
+name: reviewer
+description: Reviews a bounded change and returns evidence.
+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.
+```
+
+Frontmatter supports these fields:
+
+- `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.
+- `lifecycle` must be exactly `one-shot` or `reusable`.
+- The Markdown body must be nonempty.
+
+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.
+
+## Lifecycle and process limits
+
+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.
+
+## Isolation, trust, and writes
+
+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.
+
+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.

package/examples/workers/investigator.md

@@ -0,0 +1,41 @@
+---
+name: investigator
+description: Read-only worker for cross-file investigation, comparison, and evidence-based synthesis.
+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.
+
+Do not modify files. Use bash only for read-only commands. Do not run builds, tests, or commands that mutate state.
+
+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.
+
+## 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.

package/examples/workers/scout.md

@@ -0,0 +1,36 @@
+---
+name: scout
+description: Fast read-only worker for tiny factual probes and bounded repository reconnaissance.
+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.
+
+Do not modify files. Use bash only for read-only commands. Do not run builds, tests, or commands that mutate state.
+
+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.
+
+## 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.

package/examples/workers/worker.md

@@ -0,0 +1,44 @@
+---
+name: worker
+description: Implementation worker for bounded code changes with 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.
+
+## Working rules
+
+- 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.

package/extension/catalog.ts

@@ -0,0 +1,372 @@
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  parseFrontmatter,
+} from "@earendil-works/pi-coding-agent";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  CatalogDiagnostic,
+  SupportedToolName,
+  WorkerCatalog,
+  WorkerDefinition,
+  WorkerLifecycle,
+  WorkerSourceKind,
+} from "./domain.js";
+import { isSupportedToolName } from "./domain.js";
+
+const MAX_WORKER_BYTES = 64 * 1024;
+const KNOWN_FIELDS = new Set([
+  "name",
+  "description",
+  "model",
+  "thinking",
+  "tools",
+  "skills",
+  "compaction",
+  "lifecycle",
+]);
+const THINKING_LEVELS: ReadonlySet<string> = new Set([
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]);
+
+function isThinkingLevel(value: string): value is NonNullable<WorkerDefinition["thinking"]> {
+  return THINKING_LEVELS.has(value);
+}
+
+export interface CatalogFileStat {
+  readonly size: number;
+  isFile(): boolean;
+  isSymbolicLink(): boolean;
+}
+
+export interface CatalogFileSystem {
+  readDirectory(directory: string): readonly string[];
+  inspect(path: string): CatalogFileStat;
+  readText(path: string): string;
+}
+
+export interface DiscoverWorkerCatalogOptions {
+  readonly cwd: string;
+  readonly projectTrusted: boolean;
+  readonly packageRoot?: string;
+  readonly agentDir?: string;
+}
+
+interface CatalogSource {
+  readonly kind: WorkerSourceKind;
+  readonly directory: string;
+}
+
+interface WorkerFrontmatter {
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly model?: unknown;
+  readonly thinking?: unknown;
+  readonly tools?: unknown;
+  readonly skills?: unknown;
+  readonly compaction?: unknown;
+  readonly lifecycle?: unknown;
+  readonly [field: string]: unknown;
+}
+
+const productionFileSystem: CatalogFileSystem = {
+  readDirectory: (directory) => readdirSync(directory),
+  inspect: (path) => lstatSync(path),
+  readText: (path) => readFileSync(path, "utf8"),
+};
+
+function diagnostic(
+  source: WorkerSourceKind,
+  filePath: string,
+  message: string,
+): CatalogDiagnostic {
+  return { severity: "error", source, filePath, message };
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function isMissingPath(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`frontmatter field '${field}' must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined;
+  return requiredString(value, field);
+}
+
+function stringList(value: unknown, field: string, required: boolean): string[] | undefined {
+  if (value === undefined) {
+    if (required) throw new Error(`frontmatter field '${field}' is required`);
+    return undefined;
+  }
+
+  const values = typeof value === "string" ? value.split(",").map((item) => item.trim()) : value;
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`frontmatter field '${field}' must be a non-empty comma string or string array`);
+  }
+
+  const strings: string[] = [];
+  for (const item of values) {
+    if (typeof item !== "string" || item === "") {
+      throw new Error(`frontmatter field '${field}' must be a non-empty comma string or string array`);
+    }
+    strings.push(item);
+  }
+  return strings;
+}
+
+function parseTools(value: unknown): SupportedToolName[] {
+  const tools: SupportedToolName[] = [];
+  for (const tool of stringList(value, "tools", true) ?? []) {
+    if (!isSupportedToolName(tool)) throw new Error(`unsupported tool '${tool}'`);
+    tools.push(tool);
+  }
+  return tools;
+}
+
+function parseOptionalBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") {
+    throw new Error(`frontmatter field '${field}' must be a boolean`);
+  }
+  return value;
+}
+
+function parseLifecycle(value: unknown): WorkerLifecycle {
+  if (value !== "one-shot" && value !== "reusable") {
+    throw new Error("frontmatter field 'lifecycle' must be 'one-shot' or 'reusable'");
+  }
+  return value;
+}
+
+function parseCompaction(value: unknown): WorkerDefinition["compaction"] {
+  if (value === undefined) return undefined;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("frontmatter field 'compaction' must be a mapping");
+  }
+
+  const fields = Object.keys(value).sort(compareText);
+  const unknownFields = fields.filter(
+    (field) => field !== "enabled" && field !== "reserveTokens" && field !== "keepRecentTokens",
+  );
+  if (unknownFields.length > 0) {
+    throw new Error(
+      `unknown compaction field${unknownFields.length === 1 ? "" : "s"}: ${unknownFields.join(", ")}`,
+    );
+  }
+
+  const enabledValue = "enabled" in value ? value.enabled : undefined;
+  const reserveTokens = "reserveTokens" in value ? value.reserveTokens : undefined;
+  const keepRecentTokens = "keepRecentTokens" in value ? value.keepRecentTokens : undefined;
+  const enabled = parseOptionalBoolean(enabledValue, "compaction.enabled");
+
+  if (
+    reserveTokens !== undefined &&
+    (typeof reserveTokens !== "number" || !Number.isSafeInteger(reserveTokens) || reserveTokens < 0)
+  ) {
+    throw new Error("frontmatter field 'compaction.reserveTokens' must be a non-negative integer");
+  }
+  if (
+    keepRecentTokens !== undefined &&
+    (typeof keepRecentTokens !== "number" || !Number.isSafeInteger(keepRecentTokens) || keepRecentTokens < 0)
+  ) {
+    throw new Error("frontmatter field 'compaction.keepRecentTokens' must be a non-negative integer");
+  }
+
+  return { enabled, reserveTokens, keepRecentTokens };
+}
+
+function parseWorker(
+  filePath: string,
+  source: WorkerSourceKind,
+  content: string,
+): WorkerDefinition {
+  let parsed: ReturnType<typeof parseFrontmatter<WorkerFrontmatter>>;
+  try {
+    parsed = parseFrontmatter<WorkerFrontmatter>(content);
+  } catch {
+    throw new Error("frontmatter is not valid YAML");
+  }
+
+  const { frontmatter, body } = parsed;
+  if (typeof frontmatter !== "object" || frontmatter === null || Array.isArray(frontmatter)) {
+    throw new Error("frontmatter must be a mapping");
+  }
+
+  const unknownFields = Object.keys(frontmatter)
+    .filter((field) => !KNOWN_FIELDS.has(field))
+    .sort(compareText);
+  if (unknownFields.length > 0) {
+    throw new Error(
+      `unknown frontmatter field${unknownFields.length === 1 ? "" : "s"}: ${unknownFields.join(", ")}`,
+    );
+  }
+
+  const name = requiredString(frontmatter.name, "name");
+  const expectedName = basename(filePath, extname(filePath));
+  if (name !== expectedName) {
+    throw new Error(`frontmatter name '${name}' must match basename '${expectedName}'`);
+  }
+
+  const description = requiredString(frontmatter.description, "description");
+  const model = optionalString(frontmatter.model, "model");
+  if (model !== undefined && !/^[^/\s]+\/\S+$/.test(model)) {
+    throw new Error("frontmatter field 'model' must use provider/model format");
+  }
+
+  const thinking = optionalString(frontmatter.thinking, "thinking");
+  if (thinking !== undefined && !isThinkingLevel(thinking)) {
+    throw new Error(`unsupported thinking level '${thinking}'`);
+  }
+
+  const tools = parseTools(frontmatter.tools);
+  const skills = stringList(frontmatter.skills, "skills", false);
+  const compaction = parseCompaction(frontmatter.compaction);
+  const lifecycle = parseLifecycle(frontmatter.lifecycle);
+  if (body.trim() === "") throw new Error("worker prompt body must not be empty");
+
+  return {
+    name,
+    description,
+    model:
+      model === undefined
+        ? undefined
+        : {
+            provider: model.slice(0, model.indexOf("/")),
+            modelId: model.slice(model.indexOf("/") + 1),
+          },
+    thinking,
+    tools,
+    skills: skills ?? [],
+    compaction,
+    lifecycle,
+    systemPrompt: body,
+    source: { kind: source, filePath },
+  };
+}
+
+function sourceDirectories(options: DiscoverWorkerCatalogOptions): CatalogSource[] {
+  const packageRoot = options.packageRoot ?? fileURLToPath(new URL("..", import.meta.url));
+  const agentDir = options.agentDir ?? getAgentDir();
+  const sources: CatalogSource[] = [
+    { kind: "package", directory: join(packageRoot, "examples", "workers") },
+    { kind: "user", directory: join(agentDir, "pi-orchestrate", "workers") },
+  ];
+
+  if (options.projectTrusted) {
+    sources.push({
+      kind: "project",
+      directory: join(options.cwd, CONFIG_DIR_NAME, "pi-orchestrate", "workers"),
+    });
+  }
+  return sources;
+}
+
+function discoverSource(
+  fileSystem: CatalogFileSystem,
+  source: CatalogSource,
+): { workers: WorkerDefinition[]; diagnostics: CatalogDiagnostic[] } {
+  let entries: readonly string[];
+  try {
+    entries = fileSystem.readDirectory(source.directory);
+  } catch (error) {
+    if (isMissingPath(error)) return { workers: [], diagnostics: [] };
+    return {
+      workers: [],
+      diagnostics: [diagnostic(source.kind, source.directory, "could not read worker directory")],
+    };
+  }
+
+  const workers: WorkerDefinition[] = [];
+  const diagnostics: CatalogDiagnostic[] = [];
+  const markdownEntries = entries
+    .filter((entry) => extname(entry) === ".md" && basename(entry) === entry)
+    .sort(compareText);
+
+  for (const entry of markdownEntries) {
+    const filePath = join(source.directory, entry);
+    let stat: CatalogFileStat;
+    try {
+      stat = fileSystem.inspect(filePath);
+    } catch {
+      diagnostics.push(diagnostic(source.kind, filePath, "could not inspect worker file"));
+      continue;
+    }
+
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      diagnostics.push(
+        diagnostic(source.kind, filePath, "worker file must be a regular non-symlink file"),
+      );
+      continue;
+    }
+    if (stat.size > MAX_WORKER_BYTES) {
+      diagnostics.push(
+        diagnostic(source.kind, filePath, `worker file exceeds ${MAX_WORKER_BYTES} bytes`),
+      );
+      continue;
+    }
+
+    let content: string;
+    try {
+      content = fileSystem.readText(filePath);
+    } catch {
+      diagnostics.push(diagnostic(source.kind, filePath, "could not read worker file"));
+      continue;
+    }
+
+    if (Buffer.byteLength(content, "utf8") > MAX_WORKER_BYTES) {
+      diagnostics.push(
+        diagnostic(source.kind, filePath, `worker file exceeds ${MAX_WORKER_BYTES} bytes`),
+      );
+      continue;
+    }
+
+    try {
+      workers.push(parseWorker(filePath, source.kind, content));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "invalid worker definition";
+      diagnostics.push(diagnostic(source.kind, filePath, message));
+    }
+  }
+
+  return { workers, diagnostics };
+}
+
+export function createWorkerCatalogDiscovery(fileSystem: CatalogFileSystem) {
+  return (options: DiscoverWorkerCatalogOptions): WorkerCatalog => {
+    const workersByName = new Map<string, WorkerDefinition>();
+    const diagnostics: CatalogDiagnostic[] = [];
+
+    for (const source of sourceDirectories(options)) {
+      const discovered = discoverSource(fileSystem, source);
+      for (const worker of discovered.workers) workersByName.set(worker.name, worker);
+      diagnostics.push(...discovered.diagnostics);
+    }
+
+    const workers = [...workersByName.values()].sort((left, right) =>
+      compareText(left.name, right.name),
+    );
+    return { workers, diagnostics };
+  };
+}
+
+export const discoverWorkerCatalog = createWorkerCatalogDiscovery(productionFileSystem);

package/extension/contract.ts

@@ -0,0 +1,70 @@
+import type { WorkerCatalog } from "./domain.js";
+
+const CONTRACT_START = "<!-- pi-orchestrate:contract:start -->";
+const CONTRACT_END = "<!-- pi-orchestrate:contract:end -->";
+
+function contractWorkers(catalog: WorkerCatalog) {
+  return [...catalog.workers].sort((left, right) => {
+    if (left.name < right.name) return -1;
+    if (left.name > right.name) return 1;
+    return 0;
+  });
+}
+
+function formatCatalog(catalog: WorkerCatalog): string {
+  const workers = contractWorkers(catalog);
+  if (workers.length === 0) return "- No trusted workers are available for this session.";
+
+  return workers
+    .map(
+      (worker) =>
+        `- \`${worker.name}\` [${worker.source.kind}] (${worker.lifecycle}): ${worker.description}`,
+    )
+    .join("\n");
+}
+
+function buildContract(catalog: WorkerCatalog): string {
+  return `${CONTRACT_START}
+## Pi Orchestrate Contract
+
+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.
+- 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.
+- After an accepted async wave, yield the parent turn until aggregate results arrive. Do not duplicate delegated work or poll \`orchestration_status\` for completion.
+- 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.
+- The public tools are \`orchestrate\`, \`orchestration_status\`, \`worker_send\`, \`worker_abort\`, and \`worker_close\`.
+
+### Trusted worker catalog
+
+Source labels show where each trusted definition came from; later catalog sources have already overridden earlier definitions with the same name.
+
+${formatCatalog(catalog)}
+${CONTRACT_END}`;
+}
+
+export function appendOrchestratorContract(
+  systemPrompt: string,
+  catalog: WorkerCatalog,
+): string {
+  const section = buildContract(catalog);
+  const start = systemPrompt.indexOf(CONTRACT_START);
+  if (start >= 0) {
+    const end = systemPrompt.indexOf(CONTRACT_END, start);
+    if (end >= 0) {
+      return `${systemPrompt.slice(0, start)}${section}${systemPrompt.slice(end + CONTRACT_END.length)}`;
+    }
+  }
+
+  const separator =
+    systemPrompt.length === 0 || systemPrompt.endsWith("\n\n")
+      ? ""
+      : systemPrompt.endsWith("\n")
+        ? "\n"
+        : "\n\n";
+  return `${systemPrompt}${separator}${section}`;
+}