@zachwill/pi-orchestrate 0.10.0 → 0.12.0

package/README.md

@@ -1,125 +1,53 @@
 # Pi Orchestrate
 
-[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) lets a Pi agent delegate work to separate child sessions, run independent tasks concurrently, and synthesize their results.
+[`@zachwill/pi-orchestrate`](https://www.npmjs.com/package/@zachwill/pi-orchestrate) lets a Pi session delegate work to direct child sessions.
 
-## Install
+- Each worker gets a focused brief and a separate conversation.
+- Workers run independently and return their results to the parent.
+- Only the parent can delegate; workers cannot create more workers.
 
-```bash
-pi install npm:@zachwill/pi-orchestrate
-```
+## The model
 
-The package includes `scout`, `investigator`, `web`, and `worker` definitions. Pi packages and workers run with your system permissions, so review every package and worker definition you trust.
+Each `orchestrate` dispatch creates a fresh worker session with its own transcript. The worker receives a complete brief from the parent but not the parent's conversation.
 
-## How it works
+A worker definition is reusable configuration: it selects the worker's prompt, tools, lifecycle, and optional model settings. It is not a running or retained session.
 
-The current Pi session remains the parent and owns the task. Each `orchestrate` call starts a fresh worker session with its own transcript and a complete brief from the parent.
+Independent workers dispatched together run concurrently. Their results return only to the parent session that started them, and the parent synthesizes the group after every worker finishes. A rejected or failed worker does not cancel its peers. Orchestration dispatched alongside unrelated tool calls runs inline instead of in the background.
 
 Workers have one of two lifecycles:
 
-- `one-shot` workers return one result and stop automatically.
-- `interactive` workers return a result and remain `ready` for follow-up work.
-
-A **worker ID** identifies a worker session. A **run ID** identifies one generation within that session. Each interactive follow-up creates a new run while keeping the same worker ID.
-
-## Tools
+- A `one-shot` worker returns one result and stops.
+- An `interactive` worker returns a result and remains available for follow-up work.
 
-Pi Orchestrate adds exactly five tools.
+A **worker ID** identifies a worker session. A **run ID** identifies one generation within it. An interactive follow-up creates a new run while preserving the worker ID and prior session context.
 
-### `orchestrate`
-
-```text
-orchestrate({ worker, title, instructions })
-```
+Interactive workers remain available across session switches and extension reloads within the same Pi process. Closing one releases its retained session; process shutdown releases any that remain.
 
-Starts one worker. `title` is a short label; `instructions` is the complete, self-contained brief, including scope, constraints, success criteria, and expected output.
-
-A sole call runs asynchronously. To run independent work concurrently, send the complete wave as sibling calls in one assistant response:
-
-```text
-orchestrate({
-  worker: "investigator",
-  title: "Trace configuration loading",
-  instructions: "Trace configuration loading from entry point to runtime. Read only. Return the relevant symbols, file paths, and a concise data-flow summary."
-})
-
-orchestrate({
-  worker: "investigator",
-  title: "Trace shutdown cleanup",
-  instructions: "Trace shutdown and cleanup behavior. Read only. Return the relevant symbols, lifecycle invariants, and uncovered edge cases."
-})
-```
+## Agent interface
 
-A wave must contain all N intended `orchestrate` calls and no other tool calls. Form the whole wave before sending it; a successfully admitted asynchronous call ends the parent turn. When Pi provides a parallel tool dispatcher such as `multi_tool_use.parallel`, put all N `functions.orchestrate` entries in one dispatcher call. Otherwise, emit N native sibling calls.
+Pi Orchestrate gives the parent five model-facing tools:
 
-Pure orchestration groups run asynchronously, and their siblings execute concurrently. Mixing another tool into the group makes orchestration inline and blocking. Inline work follows cancellation of the parent turn; accepted asynchronous work continues independently.
+| Tool | Purpose |
+| --- | --- |
+| `orchestrate` | Start a fresh worker with a title and complete brief |
+| `interactive_send` | Continue an owned interactive worker that is ready |
+| `interactive_close` | Release an owned interactive worker that is ready |
+| `worker_abort` | Stop active workers owned by the parent |
+| `worker_status` | Inspect the trusted catalog and diagnose the parent's worker state |
 
-Each call validates its input, worker definition, and model before starting. Sibling calls are admitted independently, so one rejection or worker failure does not roll back its peers. There is no extension-level sibling-group limit or hidden throttle.
+The extension supplies the parent with the exact dispatch and lifecycle rules for these tools. The README describes their behavior rather than duplicating those model instructions.
 
-Asynchronous results return to the exact parent session automatically. A sibling wave produces one final parent synthesis turn after every admitted worker settles. If that parent is busy or inactive, results wait for it; they are never delivered to another session.
-
-### `worker_abort`
-
-```text
-worker_abort({ worker_ids: ["worker-…"] })
-worker_abort({ all: true })
-```
-
-Stops active workers owned by the current parent session. Explicit IDs are validated together. `{ all: true }` is a no-op when no owned workers are active and does not close interactive workers that are already `ready`.
-
-Completed one-shot workers need no cleanup. Abort active interactive work before closing its retained session.
-
-### `worker_status`
-
-```text
-worker_status({})
-```
+## Worker definitions
 
-Returns the trusted worker catalog, catalog diagnostics, and the current parent session's worker and run state. It omits worker prompts and full task instructions.
+The package includes four fallback definitions in [`examples/workers/`](examples/workers/): `scout` for small factual probes, `investigator` for read-only cross-file research, `worker` for bounded implementation, and `web` for public web research. The first three inherit the parent's active model. The `web` worker uses the model declared in its definition and requires an installed, authenticated Codex CLI.
 
-Use it for diagnostics and recovery, not completion polling. Normal asynchronous results arrive automatically. The TUI widget separately shows active work, and the footer reports interactive workers that are ready.
+Definitions are loaded by name in this precedence order:
 
-### `interactive_close`
-
-```text
-interactive_close({ worker_id: "worker-…" })
-```
-
-Closes an owned interactive worker whose status is `ready`. It releases the retained session; it cannot close active work or a one-shot worker.
-
-### `interactive_send`
-
-```text
-interactive_send({
-  worker_id: "worker-…",
-  instructions: "Verify the first risk against the tests and cite the relevant cases."
-})
-```
-
-Starts a follow-up run on an owned interactive worker whose status is `ready`. The worker keeps its ID and prior session context. Send `interactive_send` as the only tool call in the assistant message to run it asynchronously; sibling tool calls make it inline and blocking.
-
-Interactive workers remain available across extension reloads and session switches within the same Pi process. Close them when their continuity is no longer useful. Runtime shutdown releases retained sessions automatically.
-
-## Parent responsibilities
-
-The parent agent still owns the result:
-
-- Delegate bounded, independent scopes and materially distinct validation perspectives. Keep trivial or tightly coupled work in the parent.
-- Use as many workers as the task supports instead of a small fixed count. User-named roles and counts are a floor unless the user sets an exact cap.
-- Give each worker a complete brief and non-overlapping write scope. Intentional overlap should serve a distinct review perspective.
-- Dispatch each full wave together. As findings expose new independent work, dispatch another full wave.
-- Review the evidence and changes, resolve conflicts, verify the integrated result, and answer from the parent session.
-
-## Configure workers
-
-Worker definitions are loaded by name in this precedence order:
-
-1. Package fallbacks in [`examples/workers/`](examples/workers/)
+1. Package fallbacks in `examples/workers/`
 2. User definitions in `~/.pi/agent/pi-orchestrate/workers/*.md`
 3. Project definitions in `<project>/.pi/pi-orchestrate/workers/*.md`, when Pi trusts the project
 
-A later definition replaces an earlier definition with the same name. Untrusted projects contribute no project definitions.
-
-The bundled `scout`, `investigator`, and `worker` inherit the parent's active model. The bundled `web` worker requires an installed, authenticated Codex CLI and uses `openai-codex/gpt-5.6-sol`. Copy a fallback into a user or project directory to customize it.
+A later definition replaces an earlier definition with the same name. Untrusted projects contribute no project definitions. Copy a fallback into a user or project directory to replace it.
 
 A definition is a Markdown file whose basename matches its `name`:
 
@@ -134,20 +62,31 @@ lifecycle: interactive
 Inspect only the assigned scope. Do not modify files. Return concise findings with file paths.
 ```
 
-Required fields are `name`, `description`, and a nonempty `tools` list. The Markdown body is the worker's nonempty system prompt.
+The frontmatter is strict:
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Required definition name; must match the filename |
+| `description` | Required catalog description used when choosing a worker |
+| `tools` | Required nonempty tool list |
+| `lifecycle` | `one-shot` or `interactive`; defaults to `one-shot` |
+| `model` | Optional `provider/model` coordinate; omission inherits the parent's model |
+| `thinking` | Optional thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+| `skills` | Optional exact skill allowlist; `[]` disables skills and omission uses normal discovery |
+| `compaction` | Optional Pi compaction settings: `enabled`, `reserveTokens`, and `keepRecentTokens` |
 
-`lifecycle` is optional, accepts `one-shot` or `interactive`, and defaults to `one-shot`. Other optional fields are `model`, `thinking`, `skills`, and `compaction`. An omitted `model` inherits the parent's model. For `skills`, omission uses normal discovery, a list is an exact allowlist, and `[]` disables skills.
+The Markdown body is the worker's nonempty system prompt. `tools` and `skills` accept either YAML arrays or comma-separated strings. Supported Pi tools are `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`. Unknown fields and malformed definitions are rejected and appear in catalog diagnostics.
 
-Definitions are strict, regular non-symlink `.md` files up to 64 KiB. Supported Pi tools are `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls`. Grant the smallest useful set: a read-only prompt does not prevent writes when the worker has tools with write authority.
+Each `orchestrate` call starts a new worker session from the selected definition. Only `interactive_send` continues an existing session.
 
-A definition is reusable dispatch configuration, not a retained session. Each `orchestrate` call starts a new worker session; only `interactive_send` continues an existing one.
+## Trust boundary
 
-## Trust and isolation
+Workers run in the parent process and are not security sandboxes. They share its filesystem and environment permissions.
 
-Workers receive fresh durable Pi child-session lineage without the parent's conversation. They run in the parent process and are not security sandboxes: they share its filesystem and environment permissions.
+Workers can use global Pi settings, authentication, packages, extensions, skills, and context. Trusted projects may add project-scoped resources. Untrusted projects do not contribute project workers, settings, extensions, skills, or context; global resources remain available.
 
-Workers use global Pi settings, authentication, packages, extensions, skills, and context. Trusted projects may add project-scoped resources. Untrusted projects do not contribute project workers, settings, extensions, skills, or context; global resources remain available.
+A definition's `tools` field controls Pi's tool allowlist, not operating-system authority. A worker with `bash` can start external processes, including other agent CLIs. A read-only prompt also does not prevent writes when the worker has a write-capable tool.
 
-A definition's `tools` field controls Pi's tool allowlist, not operating-system authority. A worker with `bash` can start external processes, including agent CLIs. Give concurrent workers separate write scopes and inspect their changes in the parent.
+Concurrent workers share the same working tree, so overlapping write scopes can collide. The parent owns reviewing their output and integrating the result.
 
-Pi Orchestrate excludes itself from child sessions and instructs workers not to create descendant Pi worker sessions. Workers remain direct Pi children.
+Pi Orchestrate excludes itself from child sessions and keeps workers as direct Pi children.

package/extension/catalog/discovery.ts

@@ -11,13 +11,13 @@ import type {
   WorkerCatalog,
   WorkerDefinition,
   WorkerSourceKind,
-} from "./definition.js";
+} from "./definition.ts";
 import {
   createWorkerCatalog,
   isSupportedToolName,
   SUPPORTED_TOOL_NAMES,
-} from "./definition.js";
-import { PACKAGE_ROOT } from "../package-root.js";
+} from "./definition.ts";
+import { PACKAGE_ROOT } from "../package-root.ts";
 
 const MAX_WORKER_BYTES = 64 * 1024;
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;

package/extension/index.ts

@@ -6,9 +6,9 @@ import type {
 import {
   discoverWorkerCatalog,
   type DiscoverWorkerCatalogOptions,
-} from "./catalog/discovery.js";
-import type { WorkerCatalog } from "./catalog/definition.js";
-import { applyOrchestratorContract } from "./parent/contract.js";
+} from "./catalog/discovery.ts";
+import type { WorkerCatalog } from "./catalog/definition.ts";
+import { applyOrchestratorContract } from "./parent/contract.ts";
 import {
   attachProcessHost,
   createProcessHost,
@@ -16,18 +16,18 @@ import {
   detachProcessHost,
   type ProcessHost,
   type ProcessHostAttachment,
-} from "./parent/process-host.js";
+} from "./parent/process-host.ts";
 import {
   createStatusController,
   registerOrchestrationPresentation,
   type StatusController,
   type WorkerStateSource,
-} from "./pi/presentation.js";
+} from "./pi/presentation.ts";
 import {
   classifyParentDispatches,
   type DispatchDecision,
-} from "./parent/dispatch-policy.js";
-import { registerOrchestrationTools } from "./pi/tools.js";
+} from "./parent/dispatch-policy.ts";
+import { registerOrchestrationTools } from "./pi/tools.ts";
 
 interface StoredDispatchDecision extends DispatchDecision {
   readonly ownerSessionId: string;
@@ -129,6 +129,8 @@ export function createOrchestrationExtension(
       const decision = dispatchDecisions.get(event.toolCallId);
       dispatchDecisions.delete(event.toolCallId);
       if (!event.isError || !decision?.synthesisGroup) return;
+      // Group size is counted before admission, so a failed member must still be
+      // accounted for as skipped or the final synthesis turn will never trigger.
       host?.delivery.skipSynthesisGroupMember(
         decision.ownerSessionId,
         decision.synthesisGroup.id,

package/extension/orchestration/admission.ts

@@ -5,7 +5,7 @@ import {
   findWorkerByName,
   type WorkerCatalog,
   type WorkerDefinition,
-} from "../catalog/definition.js";
+} from "../catalog/definition.ts";
 import {
   MAX_WORKER_INSTRUCTIONS_LENGTH,
   MAX_WORKER_TITLE_LENGTH,
@@ -13,7 +13,7 @@ import {
   WorkerId,
   type RunMode,
   type SynthesisGroup,
-} from "./model.js";
+} from "./model.ts";
 
 /** Everything one orchestration request needs from its owning parent session. */
 export interface OrchestrationContext {

package/extension/orchestration/model.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import type { WorkerLifecycle } from "../catalog/definition.js";
+import type { WorkerLifecycle } from "../catalog/definition.ts";
 
 export const MAX_WORKER_TITLE_LENGTH = 200;
 export const MAX_WORKER_INSTRUCTIONS_LENGTH = 100_000;

package/extension/orchestration/service.ts

@@ -10,7 +10,7 @@ import {
   FiberSet,
   Layer,
 } from "effect";
-import type { WorkerDefinition } from "../catalog/definition.js";
+import type { WorkerDefinition } from "../catalog/definition.ts";
 import {
   CANCELLATION_GRACE_MS,
   EMPTY_WORKER_USAGE,
@@ -30,7 +30,7 @@ import {
   type WorkerOutcome,
   type WorkerRecord,
   type WorkerUsage,
-} from "./model.js";
+} from "./model.ts";
 import {
   OrchestrationActionRejected,
   accepted,
@@ -46,21 +46,21 @@ import {
   type OrchestrationContext,
   type OrchestrationOperation,
   type ValidatedAbortTarget,
-} from "./admission.js";
+} from "./admission.ts";
 import {
   createWorkerSettlement,
   type SettlementFailureStage,
   type WorkerSettlement,
-} from "./settlement.js";
+} from "./settlement.ts";
 import {
   ChildSessions,
   type ChildSessionsService,
-} from "../worker/child-sessions.js";
+} from "../worker/child-sessions.ts";
 import type {
   WorkerSessionAbortError,
   WorkerSessionHandle,
   WorkerSessionObservation,
-} from "../worker/session.js";
+} from "../worker/session.ts";
 
 export const MAX_TERMINAL_WORKER_HISTORY = 100;
 export const MAX_COMPLETED_RUN_HISTORY = 100;
@@ -1479,8 +1479,8 @@ function makeSettlement(
   }
   const sequence = draft.settlementSequence + 1;
   draft.settlementSequence = sequence;
-  // Persisted generation records this authority epoch for reconstruction and
-  // diagnostics.
+  // Persisted generation stores workerEpoch, distinguishes follow-up settlements
+  // for one stable worker ID, and makes event IDs generation-specific.
   const settlement = createWorkerSettlement({
     sequence,
     generation: worker.workerEpoch,
@@ -1514,12 +1514,7 @@ function pruneHistory(draft: OrchestrationState): Set<string> {
     draft.runs.delete(runId);
   }
   while (draft.terminalWorkerOrder.length > MAX_TERMINAL_WORKER_HISTORY) {
-    const index = draft.terminalWorkerOrder.findIndex((workerId) => {
-      const worker = draft.workers.get(workerId);
-      return !worker || isTerminalWorkerStatus(worker.record.status);
-    });
-    if (index < 0) break;
-    const removed = draft.terminalWorkerOrder.splice(index, 1)[0];
+    const removed = draft.terminalWorkerOrder.shift();
     if (!removed) break;
     const worker = draft.workers.get(removed);
     if (worker) owners.add(worker.record.ownerSessionId);

package/extension/orchestration/settlement.ts

@@ -10,7 +10,7 @@ import {
   WorkerUsage,
   type RunRecord,
   type SettledWorkerRecord,
-} from "./model.js";
+} from "./model.ts";
 
 const NonnegativeInteger = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 const PositiveInteger = Schema.Int.check(Schema.isGreaterThan(0));

package/extension/parent/contract.ts

@@ -1,4 +1,4 @@
-import type { WorkerCatalog } from "../catalog/definition.js";
+import type { WorkerCatalog } from "../catalog/definition.ts";
 
 const CONTRACT_START = "<!-- pi-orchestrate:contract:start -->";
 const CONTRACT_END = "<!-- pi-orchestrate:contract:end -->";
@@ -98,27 +98,31 @@ 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. For broad work, proactively identify every useful bounded independent scope and every materially distinct evidence, hypothesis, or validation perspective. Spin up as many workers as needed to cover them; never use a small fixed default.
-- Treat worker roles and counts named by the user as minimum requirements, not ceilings. Exceed them when additional useful independent scopes or materially distinct perspectives exist, unless the user explicitly sets an exact cap. The same worker definition can be dispatched in multiple independent calls when it fits separate scopes or perspectives; each call creates an independent worker session. This is distinct from interactive session continuity, which keeps one worker ID for explicit follow-up work.
-- Before dispatching, enumerate the full first parallel wave from the work itself.
-- **Mandatory asynchronous-wave cardinality:** If an intended asynchronous wave has N workers, your next assistant response must contain exactly N separate, fully briefed \`orchestrate\` invocations. A single invocation is valid only when N=1. Form all N invocations before emitting or finalizing the response: a successfully admitted sole async invocation returns \`terminate: true\` and ends the parent turn, so omitted siblings cannot be added afterward. Do not emit one invocation and wait for its result before forming the rest of the wave.
-- **Parallel-dispatch mechanism:** When a parallel tool dispatcher is available, use it to submit the entire wave as one tool-call group. For example, with \`multi_tool_use.parallel\`, make one dispatcher call whose \`tool_uses\` contains exactly N \`functions.orchestrate\` entries and no other tools. If no parallel dispatcher is available, emit N native sibling \`orchestrate\` calls in the same assistant response. Never represent an N-worker wave as N sequential assistant responses.
-- **Asynchronous response shape:** To run that wave asynchronously, the resulting expanded tool-call group must contain exactly those N \`orchestrate\` invocations and no other tool calls. Harmless response text does not affect runtime classification. Pi executes sibling tool calls concurrently. For N=3, submit together three calls: \`orchestrate({ worker, title, instructions })\`, \`orchestrate({ worker, title, instructions })\`, and \`orchestrate({ worker, title, instructions })\`.
-- Delegate each independent scope or distinct perspective with its own fully briefed \`orchestrate\` call. Do not wait for one sibling's acceptance or completion before dispatching the rest.
-- Deliberate overlap is allowed only when calls pursue materially distinct evidence sources, competing hypotheses, or validation perspectives. Encode that distinction in each brief; accidental duplicate assignments are forbidden.
-- Give every worker a thorough, self-contained brief with the objective, paths and scope, context, success criteria, and expected output. State forbidden actions explicitly.
-- 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.
-- Pi Orchestrate treats a successfully admitted sole \`orchestrate\` call or pure sibling group as async. Pi executes native sibling tools concurrently. A pure group 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. \`interactive_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 the full current wave has been dispatched, yield the parent turn once its admissions have resolved; a rejected sibling does not block yielding. Worker responses arrive individually as each worker settles, and the final response starts parent synthesis. Do not poll \`worker_status\` or use it as a normal completion mechanism.
-- As results expose more useful independent scopes or materially distinct perspectives, enumerate and dispatch another full parallel wave before yielding. Continue adaptive full waves until the whole task is complete.
-- 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 \`interactive_send\` only for follow-up work on an owned lifecycle interactive worker whose status is ready, and \`interactive_close\` only when that ready interactive worker is finished. Never use either tool for one-shot or completed workers because one-shot sessions terminate automatically. Use \`worker_abort\` only when active work must stop.
-- The public tools are \`orchestrate\`, \`worker_status\`, \`interactive_send\`, \`worker_abort\`, and \`interactive_close\`.
+### Delegation
 
-### Trusted worker catalog
+- Keep trivial or tightly coupled work in the parent. Delegate work that can proceed independently or benefit from independent judgment.
+- Choose worker scopes and counts from the task. Treat workers or counts named by the user as a floor unless the user sets an exact cap.
+- Each \`orchestrate\` call creates a fresh worker session. Multiple calls may use the same worker definition and identical instructions when independent judgments are useful. Do not vary briefs merely to make them appear different. Interactive follow-up instead continues one worker ID with its existing context.
+- Give each worker a self-contained brief with its objective, context, paths and scope, forbidden actions, success criteria, and expected output. Workers do not receive the parent conversation.
+
+### Parallel dispatch
+
+- Form the complete wave before emitting any tool call.
+- For one worker, make one fully briefed \`orchestrate\` call.
+- For N workers where N > 1, make exactly one \`multi_tool_use.parallel\` call. Its \`tool_uses\` must contain exactly N \`functions.orchestrate\` entries and no other tools.
+- If \`multi_tool_use.parallel\` is not present, emit all N \`orchestrate\` calls as native siblings in one assistant response.
+- Never dispatch a multi-worker wave as separate assistant responses. An admitted sole asynchronous \`orchestrate\` call ends the parent turn, so omitted workers cannot be added afterward.
+- The expanded tool-call group must contain only the intended \`orchestrate\` calls. Mixing another tool into the group makes orchestration inline and blocking.
 
-Source labels show where each trusted definition came from; later catalog sources have already overridden earlier definitions with the same name.
+### Completion and lifecycle
+
+- Calls are admitted independently; a rejected call does not stop its siblings.
+- After dispatching, wait for automatic result delivery instead of polling \`worker_status\`. When results expose more independent work, dispatch another complete wave.
+- Automatic delivery requires no keepalive activity. While awaiting it, do not call \`sleep\`, poll with any tool, inspect files or processes to infer worker progress, or issue no-op tool calls. Perform only genuinely independent work that would be useful even if no worker were active; otherwise end the turn.
+- The parent reviews and synthesizes worker results, resolves conflicts, integrates changes, and runs the relevant verification.
+- Prefer one-shot workers. Use interactive workers only when retained context is useful, and follow the ownership and status requirements in the lifecycle tool descriptions.
+
+### Trusted worker catalog
 
 ${formatCatalog(catalog)}
 ${CONTRACT_END}`;

package/extension/parent/delivery.ts

@@ -1,6 +1,6 @@
 import { Context, Effect, Layer } from "effect";
-import { Orchestration } from "../orchestration/service.js";
-import type { WorkerSettlement } from "../orchestration/settlement.js";
+import { Orchestration } from "../orchestration/service.ts";
+import type { WorkerSettlement } from "../orchestration/settlement.ts";
 
 export const MAX_DELIVERY_MARKDOWN_BYTES = 50 * 1024;
 export const MAX_WORKER_DELIVERY_MARKDOWN_BYTES = 16 * 1024;

package/extension/parent/dispatch-policy.ts

@@ -1,4 +1,4 @@
-import type { SynthesisGroup } from "../orchestration/model.js";
+import type { SynthesisGroup } from "../orchestration/model.ts";
 
 export interface ParentToolCall {
   readonly id: string;

package/extension/parent/process-host.ts

@@ -3,7 +3,7 @@ import {
   Delivery,
   deliveryLayer,
   type DeliveryService,
-} from "./delivery.js";
+} from "./delivery.ts";
 import {
   Orchestration,
   orchestrationLayer,
@@ -14,14 +14,16 @@ import {
   type OwnerSnapshot,
   type SettlementListener,
   type UnsubscribeSettlement,
-} from "../orchestration/service.js";
+} from "../orchestration/service.ts";
 import type {
   AbortTarget,
   OrchestrationContext,
-} from "../orchestration/admission.js";
-import { createChildSessionsLayer } from "../worker/child-sessions.js";
-import type { OrchestrateTaskInput, RunMode } from "../orchestration/model.js";
+} from "../orchestration/admission.ts";
+import { createChildSessionsLayer } from "../worker/child-sessions.ts";
+import type { OrchestrateTaskInput, RunMode } from "../orchestration/model.ts";
 
+// Bump this key when ProcessHost/OrchestrationClient changes incompatibly.
+// Multiple package copies can coexist in one Pi process and adopt the same host.
 const PROCESS_HOST_KEY = Symbol.for("@zachwill/pi-orchestrate/process-host/v3");
 
 type DispatchResult<M extends RunMode> = M extends "async"
@@ -223,6 +225,8 @@ export class ManagedOrchestrationClient<R = never> implements OrchestrationClien
     if (signal?.aborted) throw abortSignalReason(signal);
     if (!signal) return this.effectRuntime.runPromise(effect);
 
+    // Race with a private sentinel because Effect may transform failures; after
+    // interruption settles, Pi must receive the caller's exact AbortSignal.reason.
     const signalInterruption = {};
     const exit = await this.effectRuntime.runPromiseExit(
       Effect.raceFirst(effect, abortSignalEffect(signal, signalInterruption)),

package/extension/pi/presentation.ts

@@ -19,18 +19,18 @@ import type {
   WorkerOutcome,
   WorkerRecord,
   WorkerStatus,
-} from "../orchestration/model.js";
-import type { OwnerSnapshot } from "../orchestration/service.js";
+} from "../orchestration/model.ts";
+import type { OwnerSnapshot } from "../orchestration/service.ts";
 import {
   disposeComponent,
   formatElapsed,
   resultAppearance,
   WidthBoundComponent,
-} from "./tui.js";
+} from "./tui.ts";
 import {
   decodePersistedWorkerSettlement,
   type WorkerSettlement,
-} from "../orchestration/settlement.js";
+} from "../orchestration/settlement.ts";
 
 export const ORCHESTRATION_PRESENTATION_KEY = "pi-orchestrate";
 export const MAX_RESULT_PREVIEW_LINES = 6;
@@ -52,6 +52,10 @@ const WORKER_ANIMATIONS = {
 } as const;
 const ANIMATION_CYCLE_TICKS = 40;
 const SPINNER_INTERVAL_MS = 140;
+const TURN_USAGE_MIN_WIDTH = 12;
+const CONTEXT_USAGE_MIN_WIDTH = 28;
+const WIDE_WORKER_ROW_MIN_WIDTH = 72;
+const WORKER_NAME_SLACK_COLUMNS = 10;
 const ACTIVE_STATUSES: ReadonlySet<WorkerStatus> = new Set(["starting", "running", "stopping"]);
 
 /** Owner-scoped worker state feed consumed by the parent's status presentation. */
@@ -211,12 +215,14 @@ export class WorkerStatusComponent implements Component {
     );
     const turns = formatTurnMarker(worker);
     const context = `${formatContextTokens(numberOrZero(worker.usage?.contextTokens))} ctx`;
-    const usageFields = width >= 28 ? [turns, context] : width >= 12 ? [turns] : [];
+    const usageFields = width >= CONTEXT_USAGE_MIN_WIDTH
+      ? [turns, context]
+      : width >= TURN_USAGE_MIN_WIDTH ? [turns] : [];
     const workerName = this.theme.fg("muted", this.theme.italic(worker.worker));
     const workerNameFits = visibleWidth(
       `⠋  · ${worker.worker} · ${usageFields.join(" · ")}`,
-    ) + 10 <= width;
-    const suffixFields = width >= 72 && workerNameFits
+    ) + WORKER_NAME_SLACK_COLUMNS <= width;
+    const suffixFields = width >= WIDE_WORKER_ROW_MIN_WIDTH && workerNameFits
       ? [workerName, ...usageFields]
       : usageFields;
     const prefix = `${glyph} `;

package/extension/pi/tool-renderer.ts

@@ -19,12 +19,12 @@ import {
   formatElapsed,
   resultAppearance,
   WidthBoundComponent,
-} from "./tui.js";
+} from "./tui.ts";
 import {
   decodeInlineWorkerToolDetails,
   type InlineWorkerSettlementDetails,
   WorkerSettlement,
-} from "../orchestration/settlement.js";
+} from "../orchestration/settlement.ts";
 
 const MAX_INSTRUCTION_PREVIEW_LINES = 2;
 

package/extension/pi/tools.ts

@@ -13,7 +13,7 @@ import type {
   CatalogDiagnostic,
   WorkerCatalog,
   WorkerDefinition,
-} from "../catalog/definition.js";
+} from "../catalog/definition.ts";
 import {
   MAX_WORKER_INSTRUCTIONS_LENGTH,
   MAX_WORKER_TITLE_LENGTH,
@@ -21,32 +21,32 @@ import {
   type WorkerOutcome,
   type WorkerRecord,
   type WorkerUsage,
-} from "../orchestration/model.js";
+} from "../orchestration/model.ts";
 import type {
   AbortTarget,
   OrchestrationContext,
-} from "../orchestration/admission.js";
+} from "../orchestration/admission.ts";
 import type {
   AcceptedRun,
   CompletedRun,
   OwnerSnapshot,
   SettlementListener,
   WorkerRunResult,
-} from "../orchestration/service.js";
-import type { DispatchDecision } from "../parent/dispatch-policy.js";
-import type { OrchestrationClient } from "../parent/process-host.js";
+} from "../orchestration/service.ts";
+import type { DispatchDecision } from "../parent/dispatch-policy.ts";
+import type { OrchestrationClient } from "../parent/process-host.ts";
 import {
   interactiveCloseToolRenderer,
   interactiveSendToolRenderer,
   orchestrateToolRenderer,
   workerAbortToolRenderer,
   workerStatusToolRenderer,
-} from "./tool-renderer.js";
+} from "./tool-renderer.ts";
 import {
   encodeInlineWorkerToolDetails,
   type InlineWorkerSettlementDetails,
   type WorkerSettlement,
-} from "../orchestration/settlement.js";
+} from "../orchestration/settlement.ts";
 
 const STRICT_OBJECT = { additionalProperties: false } as const;
 const shortTextSchema = Type.String({

package/extension/worker/child-sessions.ts

@@ -14,7 +14,7 @@ import {
   type WorkerSessionCreationError,
   type WorkerSessionDependencies,
   type WorkerSessionHandle,
-} from "./session.js";
+} from "./session.ts";
 
 export class WorkerSessionAcquisitionClosedError extends Schema.TaggedError<WorkerSessionAcquisitionClosedError>()(
   "WorkerSession.AcquisitionClosedError",

package/extension/worker/session.ts

@@ -24,13 +24,13 @@ import {
   Schema,
   Scope,
 } from "effect";
-import type { WorkerDefinition } from "../catalog/definition.js";
+import type { WorkerDefinition } from "../catalog/definition.ts";
 import type {
   WorkerMessageDirection,
   WorkerOutcome,
   WorkerUsage,
-} from "../orchestration/model.js";
-import { PACKAGE_ROOT } from "../package-root.js";
+} from "../orchestration/model.ts";
+import { PACKAGE_ROOT } from "../package-root.ts";
 
 const DIRECT_CHILD_BOUNDARY =
   "You are a direct child worker session. Do not spawn, delegate to, or orchestrate descendant Pi worker sessions. Complete the assigned task yourself and return the result directly to the parent orchestrator.";
@@ -385,6 +385,8 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
   ): Effect.Effect<DefaultWorkerSessionHandle> {
     return Effect.gen(function* () {
       const handle = new DefaultWorkerSessionHandle(runtime, interactive, sessionFile);
+      // Cache the disposal Effect so repeated or concurrent callers join the same
+      // uninterruptible Scope.close rather than skipping an in-progress disposal.
       handle.disposeOperation = yield* Effect.cached(
         Effect.sync(() => handle.beginDispose()).pipe(
           Effect.andThen(disposeWorkerSession(scope, cleanupReporter)),
@@ -457,6 +459,8 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
   prompt(instructions: string): Effect.Effect<WorkerOutcome, never> {
     return Effect.fn("WorkerSession.prompt")(function* (this: DefaultWorkerSessionHandle) {
       const completion = yield* Effect.sync(() => this.startPrompt(instructions));
+      // Interrupting this waiter does not cancel Pi's prompt. abort() owns physical
+      // cancellation, and completePrompt releases Active state when it settles.
       const { failureMessage, message, prompt } = yield* Effect.promise(() => completion);
       const text = assistantText(message);
       const assistantPayload = text === undefined ? {} : { assistantText: text };
@@ -556,7 +560,7 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
 }
 
 function safelyNotify(callback: () => void): void {
-  try { callback(); } catch { /* One cleanup/listener cannot block another. */ }
+  try { callback(); } catch { /* One observer cannot block the others. */ }
 }
 
 function subscribe<T>(listeners: Set<(value: T) => void>, listener: (value: T) => void): () => void {
@@ -793,6 +797,8 @@ function agentSessionFinalizer(
     () => ownership.session.dispose(),
   );
   const runtime = ownership.runtime;
+  // The runtime owns normal raw-session disposal after creation. Before that
+  // handoff, or if runtime disposal fails, close the raw session directly.
   return runtime
     ? bestEffortCleanup(reporter, "runtime", () => runtime.dispose(), disposeRawSession)
     : disposeRawSession;
@@ -862,9 +868,9 @@ export const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
     const { selected, modelRuntime } = yield* prepareChildModelRuntime(options, dependencies);
     const services = yield* acquireWorkerServices(options, dependencies, modelRuntime);
 
-    // createAgentSessionServices owns extension-provider registration and refresh, but
-    // Pi 0.80.10 discards that refresh result. Keep this worker-owned probe so provider
-    // errors and aborts remain typed acquisition failures before session creation.
+    // createAgentSessionServices registers extension providers and refreshes, but
+    // discards that result in Pi 0.80.10. Keep this worker-owned probe so provider
+    // errors and aborts remain typed acquisition failures; remove it when Pi surfaces them.
     yield* refreshModelRuntime(modelRuntime, definition);
     const model = yield* Effect.try({
       try: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachwill/pi-orchestrate",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Concurrent worker orchestration for Pi",
   "exports": {},