@zachwill/pi-orchestrate 0.5.0 → 0.6.0

package/README.md

@@ -18,9 +18,9 @@ Pi Orchestrate adds exactly five tools:
 | --- | --- | --- |
 | `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 |
+| `interactive_send` | `interactive_send({ worker_id, instructions })` | Send a follow-up to a ready interactive 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 |
+| `interactive_close` | `interactive_close({ worker_id })` | Close a ready interactive worker |
 
 `title` is a label. `instructions` is the complete worker brief. Collapsed tool calls preview those instructions; expanded calls show them in full.
 
@@ -28,14 +28,16 @@ Pi Orchestrate adds exactly five tools:
 
 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`.
 
-Pi executes native sibling tool calls concurrently. There is no extension-level sibling-group cap or hidden throttle. Before dispatching, enumerate the full wave. If an intended asynchronous wave has N workers, the next assistant response must contain exactly N separate, fully briefed `orchestrate` calls; one call is valid only when N=1. Form all N calls before emitting or finalizing the response because a successfully admitted sole async call returns `terminate: true` and ends the parent turn, so omitted siblings cannot be added afterward. To run the wave asynchronously, its tool-call group must contain exactly those N orchestration calls and no other tool calls. Harmless response text does not affect runtime classification. For example, a three-worker wave is one assistant response containing three native sibling `orchestrate({ worker, title, instructions })` calls.
+Pi executes sibling tool calls concurrently. There is no extension-level sibling-group cap or hidden throttle. Before dispatching, enumerate the full wave. If an intended asynchronous wave has N workers, the next assistant response must contain exactly N separate, fully briefed `orchestrate` calls; one call is valid only when N=1. Form all N calls before emitting or finalizing the response because a successfully admitted sole async call returns `terminate: true` and ends the parent turn, so omitted siblings cannot be added afterward. Never emit one call and wait for its result before forming the rest of the wave.
+
+When the host provides a parallel tool dispatcher, use it to submit the complete 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. Without a dispatcher, emit N native sibling `orchestrate` calls in one assistant response. In either form, the resulting expanded tool-call group must contain exactly those N orchestration calls and no other tool calls. Harmless response text does not affect runtime classification. A three-worker wave is one assistant response that submits all three `orchestrate({ worker, title, instructions })` calls together.
 
 Execution mode depends on the complete tool-call group:
 
 - Pi Orchestrate treats a successfully admitted sole `orchestrate` call as async.
 - Pi Orchestrate treats a successfully admitted pure group of sibling `orchestrate` calls as async; Pi executes the siblings concurrently.
 - 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.
+- `interactive_send` is asynchronous only when it is the sole tool call in the message.
 
 Inline work follows the parent turn's cancellation signal. Accepted asynchronous work detaches from that signal and continues independently.
 
@@ -47,19 +49,19 @@ All state and delivery are owner-scoped. If an owning session is busy or inactiv
 
 `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.
+The bottom widget shows active work only. Completed, failed, aborted, and interactive 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.
+A run represents one worker generation. A worker ID identifies its worker session. Completed one-shot IDs may remain in bounded diagnostics history, but their sessions have already terminated.
 
-- 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.
+- A **one-shot** worker is the default. It automatically terminates after settling and requires no cleanup.
+- An **interactive** worker is explicitly retained after a successful response as `ready`, keeping the same worker ID for follow-up work.
+- `interactive_send` starts a new run on that ready interactive worker.
+- `interactive_close` closes a ready interactive worker.
+- `worker_abort` stops active work only; `{ all: true }` does not close ready interactive 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.
+Workers, runs, and queued delivery survive extension reloads and session switches within the same Pi process. Runtime shutdown releases retained interactive workers automatically; use `interactive_close` earlier only when their continuity is no longer needed.
 
 ## Parent contract
 
@@ -67,7 +69,7 @@ Pi Orchestrate injects the authoritative orchestration contract and trusted cata
 
 1. Keep trivial or tightly coupled work in the parent. For broad work, spin up as many workers as needed to cover every useful bounded independent scope and distinct validation perspective; never use a small default or the number of roles the user names. Named workers and counts are a floor unless the user explicitly states an exact cap; the same role can be instantiated for multiple scopes.
 2. Give every worker a thorough, self-contained brief with the objective, paths and scope, context, success criteria, and expected output. Distinct validation perspectives can intentionally overlap, but avoid accidental duplicate work. State forbidden actions explicitly.
-3. For an intended asynchronous wave of N workers, make the next assistant response's tool-call group exactly N fully briefed native sibling `orchestrate` calls and no other tool calls. Harmless response text does not affect runtime classification. A single call is valid only for N=1. Form the complete group before emitting it because a successfully admitted sole async call returns `terminate: true` and ends the turn; never wait for one sibling before dispatching the rest.
+3. For an intended asynchronous wave of N workers, submit exactly N fully briefed `orchestrate` calls together and no other tool calls. Prefer one parallel dispatcher call containing N orchestration entries when a dispatcher such as `multi_tool_use.parallel` is available; otherwise emit N native siblings in one assistant response. Harmless response text does not affect runtime classification. A single call is valid only for N=1. Form the complete group before emitting it because a successfully admitted sole async call returns `terminate: true` and ends the turn; never emit one call and wait for its result before forming the rest.
 4. As results expose new independent work, dispatch each full adaptive wave in parallel and continue until the whole task is complete.
 5. Review evidence and changes, resolve conflicts, integrate deliberately, and verify the result.
 6. Produce the final answer from the parent session.
@@ -86,6 +88,8 @@ A higher-precedence definition replaces a lower one with the same `name`. Pi per
 
 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.
 
+A catalog definition is dispatch configuration, not a retained session. The same definition can be dispatched repeatedly; each one-shot dispatch creates a fresh session that terminates automatically without cleanup.
+
 ## Worker definitions
 
 A worker is a regular Markdown file whose basename matches its `name`:
@@ -95,7 +99,7 @@ A worker is a regular Markdown file whose basename matches its `name`:
 name: reviewer
 description: Reviews a bounded change and returns evidence.
 tools: read, grep, find, ls, bash
-lifecycle: reusable
+lifecycle: interactive
 ---
 
 Inspect the assigned scope and return concise findings with file paths.
@@ -106,7 +110,7 @@ Inspect the assigned scope and return concise findings with file paths.
 | `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` |
+| `lifecycle` | Required; exactly `one-shot` or `interactive` |
 | `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 |

package/extension/catalog.ts

@@ -76,7 +76,7 @@ const WorkerFrontmatter = Schema.Struct({
   tools: commaList(Schema.Literals(SUPPORTED_TOOL_NAMES)),
   skills: Schema.optionalKey(commaList(Schema.NonEmptyString, true)),
   compaction: Schema.optionalKey(Compaction),
-  lifecycle: Schema.Literals(["one-shot", "reusable"]),
+  lifecycle: Schema.Literals(["one-shot", "interactive"]),
 });
 const decodeWorkerFrontmatter = Schema.decodeUnknownResult(WorkerFrontmatter, {
   errors: "all",
@@ -267,7 +267,7 @@ function schemaDiagnostic(issue: SchemaIssue.Issue, frontmatter: unknown): strin
     return "frontmatter field 'compaction' must be a mapping";
   }
   if (field === "lifecycle") {
-    return "frontmatter field 'lifecycle' must be 'one-shot' or 'reusable'";
+    return "frontmatter field 'lifecycle' must be 'one-shot' or 'interactive'";
   }
   return "invalid worker definition";
 }

package/extension/contract.ts

@@ -30,21 +30,22 @@ 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. A worker role is reusable: dispatch the same catalog worker in many calls when it fits separate scopes or perspectives.
+- 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.
-- **Asynchronous response shape:** To run that wave asynchronously, its 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 native sibling tool calls concurrently. For N=3, emit three native sibling calls in one response: \`orchestrate({ worker, title, instructions })\`, \`orchestrate({ worker, title, instructions })\`, and \`orchestrate({ worker, title, instructions })\`.
+- **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. \`worker_send\` is asynchronous only as the sole tool call in its assistant message.
+- 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 \`orchestration_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 \`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\`.
+- 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\`, \`orchestration_status\`, \`interactive_send\`, \`worker_abort\`, and \`interactive_close\`.
 
 ### Trusted worker catalog
 

package/extension/delivery.ts

@@ -198,10 +198,12 @@ export class DeliveryCoordinator {
     byteLimit: number,
   ): WorkerDeliveryMessage {
     const heading = `## Worker result — ${settlement.title} · ${settlement.worker}`;
+    const disposition = renderDisposition(settlement);
     const metadata = [
       `Worker \`${settlement.workerId}\``,
       `run \`${settlement.runId}\``,
       `status \`${settlement.status}\``,
+      ...(disposition ? [disposition] : []),
     ].join(" · ");
     const body = renderOutcome(settlement.outcome);
     const content = body.length > 0
@@ -283,6 +285,16 @@ function truncateUtf8(content: string, byteLimit: number): string {
   return bytes.subarray(0, end).toString("utf8");
 }
 
+function renderDisposition(settlement: WorkerSettlement): string | undefined {
+  if (settlement.status === "completed" && settlement.lifecycle === "one-shot") {
+    return "one-shot session ended automatically; no close needed";
+  }
+  if (settlement.status === "ready" && settlement.lifecycle === "interactive") {
+    return "interactive session retained; use `interactive_send` or `interactive_close`";
+  }
+  return undefined;
+}
+
 function renderOutcome(outcome: WorkerSettlement["outcome"]): string {
   switch (outcome.status) {
     case "completed":

package/extension/domain.ts

@@ -36,7 +36,7 @@ export interface WorkerCompaction {
   readonly keepRecentTokens?: number;
 }
 
-export type WorkerLifecycle = "one-shot" | "reusable";
+export type WorkerLifecycle = "one-shot" | "interactive";
 
 export interface WorkerDefinition {
   readonly name: string;
@@ -278,11 +278,11 @@ export function canTransitionWorkerStatus(
     case "starting":
       return to === "running" || to === "stopping" || to === "failed" || to === "aborted";
     case "running":
-      if (to === "ready") return lifecycle === "reusable";
+      if (to === "ready") return lifecycle === "interactive";
       if (to === "completed") return lifecycle === "one-shot";
       return to === "stopping" || to === "failed" || to === "aborted";
     case "ready":
-      if (lifecycle !== "reusable") return false;
+      if (lifecycle !== "interactive") return false;
       return to === "running" || to === "stopping" || to === "closed";
     case "stopping":
       return to === "aborted" || to === "failed";

package/extension/index.ts

@@ -29,7 +29,7 @@ import {
 
 const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set([
   "orchestrate",
-  "worker_send",
+  "interactive_send",
 ]);
 
 interface StoredDispatchDecision extends DispatchDecision {

package/extension/presentation.ts

@@ -66,7 +66,7 @@ export function registerOrchestrationPresentation(pi: ExtensionAPI): void {
 
 export function formatFooterStatus(snapshot: RuntimeSnapshot): string | undefined {
   const ready = snapshot.workers.filter((worker) => worker.status === "ready").length;
-  return ready > 0 ? `${ready} available for follow-up` : undefined;
+  return ready > 0 ? `${ready} interactive ready` : undefined;
 }
 
 export class StatusController {
@@ -331,7 +331,8 @@ function resultQualifier(result: SafeSettlement): string | undefined {
     return "could not start";
   }
   if (result.status === "failed") return "failed";
-  if (result.status === "ready") return "ready for follow-up";
+  if (result.status === "ready") return "interactive ready";
+  if (result.status === "completed") return "one-shot ended";
   return undefined;
 }
 

package/extension/runtime.ts

@@ -140,7 +140,7 @@ export interface OrchestratorRuntime {
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
   ): Promise<AcceptedRun | CompletedRun>;
-  send(
+  sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -148,7 +148,7 @@ export interface OrchestratorRuntime {
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
   ): Promise<AcceptedRun>;
-  send(
+  sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -156,7 +156,7 @@ export interface OrchestratorRuntime {
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
   ): Promise<CompletedRun>;
-  send(
+  sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -165,7 +165,7 @@ export interface OrchestratorRuntime {
     onSettlement?: SettlementListener,
   ): Promise<AcceptedRun | CompletedRun>;
   abort(ownerSessionId: string, target: AbortTarget): Promise<void>;
-  close(ownerSessionId: string, workerId: WorkerId): Promise<void>;
+  closeInteractive(ownerSessionId: string, workerId: WorkerId): Promise<void>;
   snapshot(ownerSessionId: string): Promise<RuntimeSnapshot>;
   subscribeSettlement(listener: SettlementListener): UnsubscribeSettlement;
   subscribeState(listener: StateListener): () => void;
@@ -314,7 +314,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     return freezeAcceptedRun(runId, workerId);
   }
 
-  send(
+  sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -322,7 +322,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
   ): Promise<AcceptedRun>;
-  send(
+  sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -330,7 +330,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
   ): Promise<CompletedRun>;
-  send(
+  sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -338,7 +338,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     signal?: AbortSignal,
     onSettlement?: SettlementListener,
   ): Promise<AcceptedRun | CompletedRun>;
-  async send(
+  async sendInteractive(
     context: OrchestrationContext,
     workerId: WorkerId,
     instructions: string,
@@ -353,11 +353,11 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     validateText("instructions", instructions, MAX_WORKER_INSTRUCTIONS_LENGTH);
 
     const current = this.ownedWorker(context.ownerSessionId, workerId);
-    if (current.lifecycle !== "reusable" || current.status !== "ready") {
-      throw new Error("worker_send requires an owned ready reusable worker");
+    if (current.lifecycle !== "interactive" || current.status !== "ready") {
+      throw new Error("interactive_send requires an owned ready interactive worker");
     }
     const entry = this.entries.get(workerId);
-    if (!entry?.session) throw new Error("Ready reusable worker has no session handle");
+    if (!entry?.session) throw new Error("Ready interactive worker has no session handle");
 
     const runId = this.idFactories.runId();
     if (this.runs.has(runId)) throw new Error(`Duplicate run ID: ${runId}`);
@@ -403,14 +403,14 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     await this.cancelWorkers(targets);
   }
 
-  async close(ownerSessionId: string, workerId: WorkerId): Promise<void> {
+  async closeInteractive(ownerSessionId: string, workerId: WorkerId): Promise<void> {
     this.assertOpen();
     validateContextOwner(ownerSessionId);
     const current = this.ownedWorker(ownerSessionId, workerId);
-    if (current.lifecycle !== "reusable" || current.status !== "ready") {
-      throw new Error("worker_close requires an owned ready reusable worker");
+    if (current.lifecycle !== "interactive" || current.status !== "ready") {
+      throw new Error("interactive_close requires an owned ready interactive worker");
     }
-    this.closeReadyWorker(current);
+    this.closeReadyInteractiveWorker(current);
   }
 
   async snapshot(ownerSessionId: string): Promise<RuntimeSnapshot> {
@@ -458,7 +458,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
 
   private async performShutdown(): Promise<void> {
     try {
-      this.closeReadyWorkersForShutdown();
+      this.closeReadyInteractiveWorkersForShutdown();
       const active = [...this.workers.values()]
         .filter((worker) => isActiveWorkerStatus(worker.status))
         .map((worker) => worker.id);
@@ -748,7 +748,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     let status: "ready" | "completed" | "failed" | "aborted";
     if (outcome.status === "failed" || outcome.status === "aborted") {
       status = outcome.status;
-    } else if (current.lifecycle === "reusable" && outcome.status === "ready") {
+    } else if (current.lifecycle === "interactive" && outcome.status === "ready") {
       status = "ready";
     } else if (current.lifecycle === "one-shot" && outcome.status === "completed") {
       status = "completed";
@@ -928,7 +928,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
       for (const workerId of unique) {
         const worker = this.ownedWorker(ownerSessionId, workerId);
         if (worker.status === "ready") {
-          throw new Error("Ready reusable workers are not active; use worker_close");
+          throw new Error("Ready interactive workers are not active; use interactive_close");
         }
         if (!isActiveWorkerStatus(worker.status)) {
           throw new Error("worker_abort requires owned active workers");
@@ -1068,7 +1068,7 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     });
   }
 
-  private closeReadyWorker(current: WorkerRecord): void {
+  private closeReadyInteractiveWorker(current: WorkerRecord): void {
     const entry = this.entries.get(current.id);
     if (entry) this.disposeEntrySession(entry);
     this.workers.set(current.id, {
@@ -1083,9 +1083,13 @@ class DefaultOrchestratorRuntime implements OrchestratorRuntime {
     this.emitStateForOwners(affectedOwners);
   }
 
-  private closeReadyWorkersForShutdown(): void {
-    const ready = [...this.workers.values()].filter((worker) => worker.status === "ready");
-    for (const worker of ready) this.closeReadyWorker(worker);
+  private closeReadyInteractiveWorkersForShutdown(): void {
+    const readyInteractiveWorkers = [...this.workers.values()].filter(
+      (worker) => worker.lifecycle === "interactive" && worker.status === "ready",
+    );
+    for (const worker of readyInteractiveWorkers) {
+      this.closeReadyInteractiveWorker(worker);
+    }
   }
 
   private subscribeEntryObservability(

package/extension/tools.ts

@@ -59,7 +59,7 @@ const orchestrateSchema = taskSchema;
 
 const statusSchema = Type.Object({}, STRICT_OBJECT);
 
-const workerSendSchema = Type.Object(
+const interactiveSendSchema = Type.Object(
   {
     worker_id: Type.String({ minLength: 1 }),
     instructions: Type.String(),
@@ -82,7 +82,7 @@ const workerAbortSchema = Type.Union([
   ),
 ]);
 
-const workerCloseSchema = Type.Object(
+const interactiveCloseSchema = Type.Object(
   {
     worker_id: Type.String({ minLength: 1 }),
   },
@@ -116,7 +116,8 @@ export function registerOrchestrationTools(
     promptGuidelines: [
       "Spin up as many workers as needed to cover every useful parallel scope and distinct validation perspective. Treat user-named workers or counts as a floor unless explicitly capped, and reuse the same worker role across multiple calls when useful.",
       "For an intended async wave of N workers, the next assistant response must contain exactly N separate, fully briefed orchestrate calls; one call is valid only when N=1. To run it asynchronously, include no other tool calls; harmless response text does not affect runtime classification.",
-      "Form all N native sibling calls before emitting or finalizing the response. A successfully admitted sole async orchestrate call returns terminate=true and ends the turn, so omitted siblings cannot be added afterward; never wait for one sibling's acceptance or completion.",
+      "When a parallel tool dispatcher is available, use it once with exactly N orchestrate entries and no other tools; for example, put N functions.orchestrate entries in multi_tool_use.parallel. Otherwise emit N native sibling orchestrate calls in one assistant response.",
+      "Form all N calls before emitting or finalizing the response. Never emit one call and wait for its result before forming the rest of the wave: a successfully admitted sole async orchestrate call returns terminate=true and ends the turn.",
     ],
     executionMode: "parallel",
     parameters: orchestrateSchema,
@@ -212,17 +213,17 @@ export function registerOrchestrationTools(
   });
 
   pi.registerTool({
-    name: "worker_send",
-    label: "Worker Send",
+    name: "interactive_send",
+    label: "Interactive Send",
     description:
-      "Send follow-up instructions to an owned ready reusable worker. A sole tool call runs asynchronously; sibling tool calls make it inline and blocking.",
-    promptSnippet: "Send follow-up work to an owned ready reusable worker",
+      "Send follow-up instructions only to an owned lifecycle interactive worker whose status is ready. Never use for one-shot or completed workers; one-shot sessions terminate automatically. A sole tool call runs asynchronously; sibling tool calls make it inline and blocking.",
+    promptSnippet: "Use only for an owned lifecycle interactive worker with status ready; never one-shot/completed because one-shot sessions terminate automatically",
     promptGuidelines: [
-      "Use worker_send only for follow-up work on an owned ready reusable worker.",
+      "Use interactive_send only for an owned lifecycle interactive worker whose status is ready; never use it for one-shot or completed workers because one-shot sessions terminate automatically.",
     ],
-    parameters: workerSendSchema,
+    parameters: interactiveSendSchema,
     renderCall(args, theme, { expanded }) {
-      return renderWorkerMessageCall(theme, "worker_send", args.worker_id, args.instructions, expanded);
+      return renderInteractiveMessageCall(theme, "interactive_send", args.worker_id, args.instructions, expanded);
     },
     renderResult(result, { isPartial, expanded }, theme, context) {
       return renderOrchestrationResult(result, isPartial, expanded, theme, context.lastComponent);
@@ -232,7 +233,7 @@ export function registerOrchestrationTools(
       const mode = deps.getDispatchDecision(toolCallId).mode;
       const runtimeContext = await buildRuntimeContext(ctx, deps);
       if (mode === "async") {
-        const acceptedRun = await deps.runtime.send(
+        const acceptedRun = await deps.runtime.sendInteractive(
           runtimeContext,
           workerId,
           params.instructions,
@@ -252,7 +253,7 @@ export function registerOrchestrationTools(
         };
       }
 
-      const completedRun = await deps.runtime.send(
+      const completedRun = await deps.runtime.sendInteractive(
         runtimeContext,
         workerId,
         params.instructions,
@@ -280,10 +281,10 @@ export function registerOrchestrationTools(
     name: "worker_abort",
     label: "Worker Abort",
     description:
-      "Abort owned active work by worker IDs or all active owned workers. Use worker_close for ready reusable workers.",
+      "Abort owned active work by worker IDs or all active owned workers. Use interactive_close for owned lifecycle interactive workers whose status is ready.",
     promptSnippet: "Abort active owned workers by worker IDs or all",
     promptGuidelines: [
-      "Use worker_abort only for active work; use worker_close for a ready reusable worker.",
+      "Use worker_abort only for active work; use interactive_close only for an owned lifecycle interactive worker whose status is ready, never for one-shot or completed workers because one-shot sessions terminate automatically.",
     ],
     parameters: workerAbortSchema,
     renderCall(args, theme) {
@@ -316,16 +317,16 @@ export function registerOrchestrationTools(
   });
 
   pi.registerTool({
-    name: "worker_close",
-    label: "Worker Close",
-    description: "Close an owned ready reusable worker that no longer needs follow-up work.",
-    promptSnippet: "Close an owned ready reusable worker",
+    name: "interactive_close",
+    label: "Interactive Close",
+    description: "Close only an owned lifecycle interactive worker whose status is ready. Never use for one-shot or completed workers; one-shot sessions terminate automatically.",
+    promptSnippet: "Use only for an owned lifecycle interactive worker with status ready; never one-shot/completed because one-shot sessions terminate automatically",
     promptGuidelines: [
-      "Use worker_close when an owned ready reusable worker is finished.",
+      "Use interactive_close only for an owned lifecycle interactive worker whose status is ready; never use it for one-shot or completed workers because one-shot sessions terminate automatically.",
     ],
-    parameters: workerCloseSchema,
+    parameters: interactiveCloseSchema,
     renderCall(args, theme) {
-      return renderCompactCall(theme, "worker_close", args.worker_id);
+      return renderCompactCall(theme, "interactive_close", args.worker_id);
     },
     renderResult(result, { isPartial }, theme) {
       return renderSimpleResult(result, isPartial ? "Closing worker…" : "✓ Worker closed", theme);
@@ -336,7 +337,7 @@ export function registerOrchestrationTools(
         ctx.sessionManager.getSessionId(),
       );
       const workerId = asWorkerId(params.worker_id);
-      await deps.runtime.close(ownerSessionId, workerId);
+      await deps.runtime.closeInteractive(ownerSessionId, workerId);
       const readable = { worker_id: workerId };
       return {
         content: [
@@ -641,7 +642,7 @@ class InstructionPreview implements Component {
   invalidate(): void {}
 }
 
-function renderWorkerMessageCall(
+function renderInteractiveMessageCall(
   theme: Theme,
   tool: string,
   workerId: unknown,

package/extension/worker-session.ts

@@ -348,7 +348,7 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
 
   constructor(
     private readonly runtime: OwnedWorkerRuntime,
-    private readonly reusable: boolean,
+    private readonly interactive: boolean,
     sessionFile: string,
     private readonly scope: Scope.Closeable,
     private readonly cleanupReporter: WorkerSessionCleanupReporter,
@@ -429,7 +429,7 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
       return { status: "failed", message: message.errorMessage ?? failureMessage ?? "Worker assistant reported a failure", ...assistantPayload };
     }
     if (failureMessage) return { status: "failed", message: failureMessage, ...assistantPayload };
-    return { status: this.reusable ? "ready" : "completed", assistantText: text ?? "" };
+    return { status: this.interactive ? "ready" : "completed", assistantText: text ?? "" };
   }
 
   async abort(): Promise<void> {
@@ -852,7 +852,7 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
 
     const handle = new DefaultWorkerSessionHandle(
       runtime,
-      definition.lifecycle === "reusable",
+      definition.lifecycle === "interactive",
       sessionFile,
       scope,
       dependencies.reportCleanupFailure,

package/extension/worker-settlement.ts

@@ -53,7 +53,7 @@ export const WorkerSettlementDetails = Schema.Struct({
   mode: Schema.Literals(["async", "inline"]),
   worker: Schema.String,
   title: Schema.String,
-  lifecycle: Schema.Literals(["one-shot", "reusable"]),
+  lifecycle: Schema.Literals(["one-shot", "interactive"]),
   status: Schema.Literals(["completed", "ready", "failed", "aborted"]),
   outcome: WorkerOutcome,
   usage: WorkerUsage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachwill/pi-orchestrate",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Concurrent worker orchestration for Pi",
   "files": ["extension/", "examples/", "README.md", "LICENSE"],