@zachwill/pi-orchestrate 0.9.2 → 0.11.0

package/extension/{worker-session.ts → worker/session.ts}

@@ -1,6 +1,5 @@
 import { realpathSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import {
@@ -20,26 +19,22 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import {
   Cause,
-  Context,
-  Deferred,
   Effect,
   Exit,
-  FiberSet,
-  Layer,
   Schema,
   Scope,
-  SynchronizedRef,
 } from "effect";
+import type { WorkerDefinition } from "../catalog/definition.ts";
 import type {
-  WorkerDefinition,
   WorkerMessageDirection,
   WorkerOutcome,
   WorkerUsage,
-} from "./domain.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.";
-const ORCHESTRATE_PACKAGE_ROOT = canonicalPath(fileURLToPath(new URL("..", import.meta.url)));
+const ORCHESTRATE_PACKAGE_ROOT = canonicalPath(PACKAGE_ROOT);
 
 interface WorkerAgentSession {
   readonly sessionFile: string | undefined;
@@ -131,11 +126,6 @@ export class WorkerAgentSessionAcquisitionError extends Schema.TaggedError<Worke
   { operation: WorkerAgentSessionAcquisitionOperation, message: Schema.String, cause: Schema.Defect() },
 ) {}
 
-export class WorkerSessionAcquisitionClosedError extends Schema.TaggedError<WorkerSessionAcquisitionClosedError>()(
-  "WorkerSession.AcquisitionClosedError",
-  { message: Schema.String },
-) {}
-
 const WorkerSessionAbortOperation = Schema.Literals([
   "abort-compaction",
   "abort-prompt",
@@ -155,29 +145,10 @@ export class WorkerSessionAbortError extends Schema.TaggedError<WorkerSessionAbo
   },
 ) {}
 
-export type WorkerSessionAcquisitionError =
+export type WorkerSessionCreationError =
   | WorkerModelAcquisitionError
   | WorkerResourceAcquisitionError
-  | WorkerAgentSessionAcquisitionError
-  | WorkerSessionAcquisitionClosedError;
-
-export interface ChildSessionsService {
-  /**
-   * Acquires a child session through a process-owned producer. The adopter must
-   * synchronously install ownership before returning a value. Returning undefined
-   * rejects adoption and leaves ChildSessions responsible for disposal.
-   */
-  readonly acquire: <Adopted>(
-    options: ChildSessionOptions,
-    adopt: (session: WorkerSessionHandle) => Adopted | undefined,
-  ) => Effect.Effect<Adopted | undefined, WorkerSessionAcquisitionError>;
-  /** Closes every handoff without waiting for uncancellable Pi calls. */
-  readonly shutdown: () => Effect.Effect<void>;
-}
-
-export class ChildSessions extends Context.Service<ChildSessions, ChildSessionsService>()(
-  "@zachwill/pi-orchestrate/ChildSessions",
-) {}
+  | WorkerAgentSessionAcquisitionError;
 
 const WorkerSessionCleanupOperation = Schema.Literals([
   "unsubscribe",
@@ -249,7 +220,12 @@ export interface WorkerSessionDependencies {
   onReclamationOpenObserved(): Effect.Effect<void>;
 }
 
-const defaultDependencies: WorkerSessionDependencies = {
+type WorkerSessionAcquisitionDependencies = Omit<
+  WorkerSessionDependencies,
+  "beforeAdoptionReservation" | "onReclamationOpenObserved"
+>;
+
+const defaultWorkerSessionDependencies: WorkerSessionAcquisitionDependencies = {
   createSettingsManager: ({ cwd, agentDir, projectTrusted, compaction }) => {
     const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted });
     if (compaction !== undefined) settingsManager.applyOverrides({ compaction: { ...compaction } });
@@ -279,8 +255,6 @@ const defaultDependencies: WorkerSessionDependencies = {
       detail: `Operation: ${operation}`,
     });
   },
-  beforeAdoptionReservation: () => Effect.void,
-  onReclamationOpenObserved: () => Effect.void,
 };
 
 function canonicalPath(path: string): string {
@@ -411,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)),
@@ -483,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 };
@@ -582,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 {
@@ -656,7 +634,7 @@ const refreshModelRuntime = Effect.fn("WorkerSession.refreshModelRuntime")(funct
 
 const prepareChildModelRuntime = Effect.fn("WorkerSession.prepareChildModelRuntime")(function* (
   options: ChildSessionOptions,
-  dependencies: WorkerSessionDependencies,
+  dependencies: WorkerSessionAcquisitionDependencies,
 ) {
   const selected = yield* Effect.try({
     try: () => selectedModelCoordinates(options.definition, options.parentModel),
@@ -749,7 +727,7 @@ const disposeWorkerSession = Effect.fn("WorkerSession.dispose")(function* (
 
 const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(function* (
   options: ChildSessionOptions,
-  dependencies: WorkerSessionDependencies,
+  dependencies: WorkerSessionAcquisitionDependencies,
   modelRuntime: ModelRuntime,
 ) {
   const definition = options.definition;
@@ -819,13 +797,15 @@ 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;
 }
 
 const acquireAgentSession = Effect.fn("WorkerSession.acquireAgentSession")(function* (
-  dependencies: WorkerSessionDependencies,
+  dependencies: WorkerSessionAcquisitionDependencies,
   input: AgentSessionInput,
 ) {
   return yield* Effect.acquireRelease(
@@ -844,7 +824,7 @@ const acquireAgentSession = Effect.fn("WorkerSession.acquireAgentSession")(funct
 });
 
 const acquireAgentSessionRuntime = Effect.fn("WorkerSession.acquireAgentSessionRuntime")(function* (
-  dependencies: WorkerSessionDependencies,
+  dependencies: WorkerSessionAcquisitionDependencies,
   ownership: AgentSessionOwnership,
   services: AgentSessionServices,
 ) {
@@ -857,7 +837,7 @@ const acquireAgentSessionRuntime = Effect.fn("WorkerSession.acquireAgentSessionR
 });
 
 const acquireSessionSubscription = Effect.fn("WorkerSession.acquireSubscription")(function* (
-  dependencies: WorkerSessionDependencies,
+  dependencies: WorkerSessionAcquisitionDependencies,
   runtime: OwnedWorkerRuntime,
   handle: DefaultWorkerSessionHandle,
 ) {
@@ -874,19 +854,23 @@ const acquireSessionSubscription = Effect.fn("WorkerSession.acquireSubscription"
   );
 });
 
-const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
+export const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
   options: ChildSessionOptions,
-  dependencies: WorkerSessionDependencies,
+  overrides: Partial<WorkerSessionDependencies>,
 ) {
+  const dependencies: WorkerSessionAcquisitionDependencies = {
+    ...defaultWorkerSessionDependencies,
+    ...overrides,
+  };
   const scope = yield* Scope.make("sequential");
   const acquisition = Effect.gen(function* () {
     const definition = options.definition;
     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: () => {
@@ -969,245 +953,3 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
     ),
   );
 });
-
-type AcquisitionHandoffState =
-  | { readonly _tag: "Pending" }
-  | { readonly _tag: "Offered"; readonly session: WorkerSessionHandle }
-  | { readonly _tag: "Adopting"; readonly session: WorkerSessionHandle }
-  | { readonly _tag: "Adopted" }
-  | { readonly _tag: "Abandoned"; readonly error?: WorkerSessionAcquisitionClosedError }
-  | { readonly _tag: "Failed" };
-
-interface AcquisitionHandoff {
-  readonly state: SynchronizedRef.SynchronizedRef<AcquisitionHandoffState>;
-  readonly result: Deferred.Deferred<WorkerSessionHandle, WorkerSessionAcquisitionError>;
-}
-
-type ChildSessionsState =
-  | { readonly _tag: "Open"; readonly handoffs: ReadonlySet<AcquisitionHandoff> }
-  | { readonly _tag: "Closed"; readonly error: WorkerSessionAcquisitionClosedError };
-
-type AdoptionReservation =
-  | { readonly _tag: "Reserved"; readonly session: WorkerSessionHandle }
-  | { readonly _tag: "Closed"; readonly error: WorkerSessionAcquisitionClosedError }
-  | { readonly _tag: "Abandoned" };
-
-function disposeLateSession(session: WorkerSessionHandle): Effect.Effect<void> {
-  return session.dispose().pipe(Effect.catchCause(() => Effect.void));
-}
-
-function admitReclamationOrJoinAfterClosure(
-  fibers: FiberSet.FiberSet<void, never>,
-  reclamation: Effect.Effect<void>,
-  onOpenObserved: () => Effect.Effect<void>,
-): Effect.Effect<void> {
-  return Effect.suspend(() => {
-    if (fibers.state._tag === "Closed") return reclamation;
-    return Effect.gen(function* () {
-      yield* onOpenObserved().pipe(Effect.catchCause(() => Effect.void));
-      yield* FiberSet.run(fibers, reclamation, { startImmediately: true });
-      if (fibers.state._tag === "Closed") {
-        // FiberSet.run returns an interrupted sentinel when closure wins admission.
-        // If admission won, closure interrupts the admitted fiber instead. Real
-        // session disposal is cached and uninterruptible, so this fallback safely
-        // joins that same disposal in both cases rather than starting cleanup twice.
-        yield* reclamation;
-      }
-    });
-  });
-}
-
-export function createChildSessionsLayer(
-  overrides: Partial<WorkerSessionDependencies> = {},
-): Layer.Layer<ChildSessions> {
-  return Layer.effect(
-    ChildSessions,
-    Effect.gen(function* () {
-      const dependencies: WorkerSessionDependencies = { ...defaultDependencies, ...overrides };
-      const fibers = yield* FiberSet.make<void, never>();
-      const serviceState = yield* SynchronizedRef.make<ChildSessionsState>({
-        _tag: "Open",
-        handoffs: new Set(),
-      });
-
-      const withoutHandoff = (
-        state: ChildSessionsState,
-        handoff: AcquisitionHandoff,
-      ): ChildSessionsState => {
-        if (state._tag === "Closed" || !state.handoffs.has(handoff)) return state;
-        const handoffs = new Set(state.handoffs);
-        handoffs.delete(handoff);
-        return { _tag: "Open", handoffs };
-      };
-
-      const removeHandoff = (handoff: AcquisitionHandoff): Effect.Effect<void> =>
-        SynchronizedRef.update(serviceState, (state) => withoutHandoff(state, handoff));
-
-      const runReclamation = (session: WorkerSessionHandle): Effect.Effect<void> =>
-        admitReclamationOrJoinAfterClosure(
-          fibers,
-          disposeLateSession(session).pipe(Effect.uninterruptible),
-          dependencies.onReclamationOpenObserved,
-        );
-
-      const abandonHandoff = Effect.fn("ChildSessions.abandonHandoff")(function* (
-        handoff: AcquisitionHandoff,
-      ) {
-        const session = yield* SynchronizedRef.modifyEffect(serviceState, (service) => {
-          const nextService = withoutHandoff(service, handoff);
-          return SynchronizedRef.modify(handoff.state, (state): readonly [
-            { readonly session: WorkerSessionHandle | undefined },
-            AcquisitionHandoffState,
-          ] => {
-            if (state._tag === "Pending") {
-              return [{ session: undefined }, { _tag: "Abandoned" }];
-            }
-            if (state._tag === "Offered") {
-              return [{ session: state.session }, { _tag: "Abandoned" }];
-            }
-            return [{ session: undefined }, state];
-          }).pipe(Effect.map(({ session }) => [session, nextService] as const));
-        });
-        if (session) yield* runReclamation(session);
-      });
-
-      const shutdown = Effect.fn("ChildSessions.shutdown")(() =>
-        Effect.gen(function* () {
-          const closed = yield* SynchronizedRef.modifyEffect(serviceState, (state) => {
-            if (state._tag === "Closed") return Effect.succeed([undefined, state] as const);
-            const error = new WorkerSessionAcquisitionClosedError({
-              message: "Child sessions are shutting down",
-            });
-            return Effect.gen(function* () {
-              const sessions: WorkerSessionHandle[] = [];
-              for (const handoff of state.handoffs) {
-                const session = yield* SynchronizedRef.modifyEffect(handoff.state, (handoffState) => {
-                  if (handoffState._tag === "Pending") {
-                    return Deferred.fail(handoff.result, error).pipe(
-                      Effect.as([undefined, { _tag: "Abandoned", error }] as const),
-                    );
-                  }
-                  if (handoffState._tag === "Offered") {
-                    return Effect.succeed([
-                      handoffState.session,
-                      { _tag: "Abandoned", error },
-                    ] as const);
-                  }
-                  // Failed already settled its Deferred. Adopting is an ownership
-                  // reservation whose synchronous winner must be allowed to commit.
-                  return Effect.succeed([undefined, handoffState] as const);
-                });
-                if (session) sessions.push(session);
-              }
-              return [{ sessions }, { _tag: "Closed", error }] as const;
-            });
-          });
-          if (!closed) return;
-          for (const session of closed.sessions) yield* runReclamation(session);
-        }).pipe(Effect.uninterruptible)
-      );
-
-      yield* Effect.addFinalizer(() => shutdown());
-
-      const acquire = Effect.fn("ChildSessions.acquire")(function* <Adopted>(
-        options: ChildSessionOptions,
-        adopt: (session: WorkerSessionHandle) => Adopted | undefined,
-      ) {
-        const handoff: AcquisitionHandoff = {
-          state: yield* SynchronizedRef.make<AcquisitionHandoffState>({ _tag: "Pending" }),
-          result: yield* Deferred.make<WorkerSessionHandle, WorkerSessionAcquisitionError>(),
-        };
-        return yield* Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
-          const admissionError = yield* SynchronizedRef.modify(serviceState, (state) => {
-            if (state._tag === "Closed") return [state.error, state] as const;
-            return [undefined, {
-              _tag: "Open",
-              handoffs: new Set([...state.handoffs, handoff]),
-            }] as const;
-          });
-          if (admissionError) return yield* Effect.fail(admissionError);
-
-          const producer = createWorkerSession(options, dependencies).pipe(
-            Effect.matchCauseEffect({
-              onFailure: (cause) => Effect.gen(function* () {
-                const failed = yield* SynchronizedRef.modifyEffect(handoff.state, (state) =>
-                  state._tag === "Pending"
-                    ? Deferred.failCause(handoff.result, cause).pipe(
-                        Effect.as([true, { _tag: "Failed" }] as const),
-                      )
-                    : Effect.succeed([false, state] as const));
-                if (failed) yield* removeHandoff(handoff);
-              }),
-              onSuccess: (session) => Effect.gen(function* () {
-                const offered = yield* SynchronizedRef.modifyEffect(handoff.state, (state) =>
-                  state._tag === "Pending"
-                    ? Deferred.succeed(handoff.result, session).pipe(
-                        Effect.as([true, { _tag: "Offered", session }] as const),
-                      )
-                    : Effect.succeed([false, state] as const));
-                if (!offered) {
-                  yield* removeHandoff(handoff);
-                  yield* runReclamation(session);
-                }
-              }),
-            }),
-            Effect.uninterruptible,
-          );
-          yield* FiberSet.run(fibers, producer, { startImmediately: true });
-
-          const session = yield* restore(
-            Deferred.await(handoff.result).pipe(
-              Effect.tap(() => dependencies.beforeAdoptionReservation()),
-            ),
-          ).pipe(Effect.onInterrupt(() => abandonHandoff(handoff)));
-          const reservation = yield* SynchronizedRef.modifyEffect(serviceState, (service) => {
-            if (service._tag === "Closed") {
-              return Effect.succeed([
-                { _tag: "Closed", error: service.error } satisfies AdoptionReservation,
-                service,
-              ] as const);
-            }
-            return SynchronizedRef.modify(
-              handoff.state,
-              (state): readonly [AdoptionReservation, AcquisitionHandoffState] => {
-                if (state._tag === "Abandoned") {
-                  return state.error
-                    ? [{ _tag: "Closed", error: state.error }, state]
-                    : [{ _tag: "Abandoned" }, state];
-                }
-                if (state._tag !== "Offered" || state.session !== session) {
-                  return [{ _tag: "Abandoned" }, state];
-                }
-                return [
-                  { _tag: "Reserved", session },
-                  { _tag: "Adopting", session },
-                ];
-              },
-            ).pipe(Effect.map((result) => [result, service] as const));
-          });
-          if (reservation._tag === "Closed") return yield* Effect.fail(reservation.error);
-          if (reservation._tag === "Abandoned") {
-            return yield* Effect.die(new Error("Child session acquisition handoff was abandoned"));
-          }
-
-          // The adopter is arbitrary synchronous runtime code. The reservation
-          // protects it from shutdown, but no SynchronizedRef semaphore is held.
-          const adopted = yield* Effect.exit(Effect.sync(() => adopt(reservation.session)));
-          const transferred = Exit.isSuccess(adopted) && adopted.value !== undefined;
-          yield* SynchronizedRef.update(handoff.state, (state): AcquisitionHandoffState => {
-            if (state._tag !== "Adopting" || state.session !== reservation.session) return state;
-            return transferred ? { _tag: "Adopted" } : { _tag: "Abandoned" };
-          });
-          yield* removeHandoff(handoff);
-          if (transferred) return adopted.value;
-
-          yield* runReclamation(reservation.session);
-          if (Exit.isFailure(adopted)) return yield* Effect.failCause(adopted.cause);
-          return undefined;
-        }));
-      });
-
-      return ChildSessions.of({ acquire, shutdown });
-    }),
-  );
-}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@zachwill/pi-orchestrate",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "Concurrent worker orchestration for Pi",
+  "exports": {},
   "files": ["extension/", "examples/", "README.md", "LICENSE"],
   "keywords": ["pi-package", "pi", "workers", "orchestration"],
   "license": "MIT",

package/extension/contract.ts

@@ -1,144 +0,0 @@
-import type { WorkerCatalog } from "./domain.js";
-
-const CONTRACT_START = "<!-- pi-orchestrate:contract:start -->";
-const CONTRACT_END = "<!-- pi-orchestrate:contract:end -->";
-
-function sortedWorkers(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 escapeContractMarkers(value: string): string {
-  return value
-    .replaceAll(CONTRACT_START, "&lt;!-- pi-orchestrate:contract:start --&gt;")
-    .replaceAll(CONTRACT_END, "&lt;!-- pi-orchestrate:contract:end --&gt;");
-}
-
-function formatCatalog(catalog: WorkerCatalog): string {
-  const workers = sortedWorkers(catalog);
-  if (workers.length === 0) return "- No trusted workers are available for this session.";
-
-  return workers
-    .map(
-      (worker) =>
-        `- \`${escapeContractMarkers(worker.name)}\` [${worker.source.kind}] (${worker.lifecycle}): ${escapeContractMarkers(worker.description)}`,
-    )
-    .join("\n");
-}
-
-interface ContractMarker {
-  readonly start: number;
-  readonly end: number;
-  readonly kind: "start" | "end";
-}
-
-function contractMarkers(prompt: string): ContractMarker[] {
-  const markers: ContractMarker[] = [];
-  for (const [value, kind] of [
-    [CONTRACT_START, "start"],
-    [CONTRACT_END, "end"],
-  ] as const) {
-    let offset = 0;
-    while (offset < prompt.length) {
-      const start = prompt.indexOf(value, offset);
-      if (start < 0) break;
-      markers.push({ start, end: start + value.length, kind });
-      offset = start + value.length;
-    }
-  }
-  return markers.sort((left, right) => left.start - right.start);
-}
-
-function removeContractMarkers(prompt: string): {
-  readonly prompt: string;
-  readonly insertionOffset?: number;
-} {
-  const markers = contractMarkers(prompt);
-  if (markers.length === 0) return { prompt };
-
-  const removed: Array<{ start: number; end: number }> = [];
-  const stack: ContractMarker[] = [];
-  for (const marker of markers) {
-    if (marker.kind === "start") {
-      stack.push(marker);
-      continue;
-    }
-    const start = stack.pop();
-    if (start && stack.length === 0) removed.push({ start: start.start, end: marker.end });
-  }
-
-  for (const marker of markers) {
-    if (!removed.some((range) => marker.start >= range.start && marker.end <= range.end)) {
-      removed.push({ start: marker.start, end: marker.end });
-    }
-  }
-  removed.sort((left, right) => left.start - right.start);
-
-  const insertionPoint = markers[0]!.start;
-  let insertionOffset = 0;
-  let cursor = 0;
-  let cleaned = "";
-  for (const range of removed) {
-    if (range.start < cursor) continue;
-    const retained = prompt.slice(cursor, range.start);
-    cleaned += retained;
-    if (range.start <= insertionPoint) insertionOffset = cleaned.length;
-    cursor = range.end;
-  }
-  cleaned += prompt.slice(cursor);
-  return { prompt: cleaned, insertionOffset };
-}
-
-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. 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\`.
-
-### 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 cleaned = removeContractMarkers(systemPrompt);
-  if (cleaned.insertionOffset !== undefined) {
-    return `${cleaned.prompt.slice(0, cleaned.insertionOffset)}${section}${cleaned.prompt.slice(cleaned.insertionOffset)}`;
-  }
-
-  const separator =
-    systemPrompt.length === 0 || systemPrompt.endsWith("\n\n")
-      ? ""
-      : systemPrompt.endsWith("\n")
-        ? "\n"
-        : "\n\n";
-  return `${systemPrompt}${separator}${section}`;
-}