@zachwill/pi-orchestrate 0.8.0 → 0.9.2

package/extension/worker-session.ts

@@ -11,7 +11,6 @@ import {
   ModelRuntime,
   type ModelRegistry,
   type PromptOptions,
-  type ResourceLoader,
   SessionManager,
   SettingsManager,
   type AgentSessionEvent,
@@ -19,7 +18,18 @@ import {
   type CreateAgentSessionResult,
   type DefaultResourceLoader,
 } from "@earendil-works/pi-coding-agent";
-import { Cause, Effect, Exit, Schema, Scope } from "effect";
+import {
+  Cause,
+  Context,
+  Deferred,
+  Effect,
+  Exit,
+  FiberSet,
+  Layer,
+  Schema,
+  Scope,
+  SynchronizedRef,
+} from "effect";
 import type {
   WorkerDefinition,
   WorkerMessageDirection,
@@ -52,7 +62,7 @@ type ResourceLoaderOptions = Omit<
   "cwd" | "agentDir" | "settingsManager"
 >;
 
-export interface WorkerSessionFactoryOptions {
+export interface ChildSessionOptions {
   cwd: string;
   agentDir: string;
   parentSessionFile: string | undefined;
@@ -63,18 +73,18 @@ export interface WorkerSessionFactoryOptions {
   modelRegistry: ModelRegistry;
 }
 
-export interface WorkerSessionHandle {
-  readonly sessionFile: string;
-  prompt(instructions: string): Promise<WorkerOutcome>;
-  abort(): Promise<void>;
-  dispose(): Promise<void>;
-  subscribeUsage(listener: (usage: WorkerUsage) => void): () => void;
-  subscribeActivity(listener: (activity: string | undefined) => void): () => void;
-  subscribeMessageDirection(listener: (direction: WorkerMessageDirection) => void): () => void;
+export interface WorkerSessionObservation {
+  readonly usage: WorkerUsage;
+  readonly activity: string | undefined;
+  readonly messageDirection: WorkerMessageDirection | undefined;
 }
 
-export interface WorkerSessionFactory {
-  create(options: WorkerSessionFactoryOptions): Promise<WorkerSessionHandle>;
+export interface WorkerSessionHandle {
+  readonly sessionFile: string;
+  prompt(instructions: string): Effect.Effect<WorkerOutcome, never>;
+  abort(): Effect.Effect<void, WorkerSessionAbortError>;
+  dispose(): Effect.Effect<void, never>;
+  subscribeObservation(listener: (observation: WorkerSessionObservation) => void): () => void;
 }
 
 const WorkerModelAcquisitionOperation = Schema.Literals([
@@ -121,6 +131,54 @@ 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",
+]);
+export type WorkerSessionAbortOperation = typeof WorkerSessionAbortOperation.Type;
+
+const WorkerSessionAbortStage = Schema.Literals(["compaction", "prompt"]);
+export type WorkerSessionAbortStage = typeof WorkerSessionAbortStage.Type;
+
+export class WorkerSessionAbortError extends Schema.TaggedError<WorkerSessionAbortError>()(
+  "WorkerSession.AbortError",
+  {
+    operation: WorkerSessionAbortOperation,
+    stage: WorkerSessionAbortStage,
+    message: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {}
+
+export type WorkerSessionAcquisitionError =
+  | 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",
+) {}
+
 const WorkerSessionCleanupOperation = Schema.Literals([
   "unsubscribe",
   "runtime",
@@ -185,6 +243,10 @@ export interface WorkerSessionDependencies {
   createAgentSession(input: AgentSessionInput): Promise<{ session: WorkerAgentSession }>;
   createRuntime(input: RuntimeInput): OwnedWorkerRuntime;
   reportCleanupFailure(failure: WorkerSessionCleanupFailure): void;
+  /** Deterministic boundary before an offered session reserves adopter ownership. */
+  beforeAdoptionReservation(): Effect.Effect<void>;
+  /** Deterministic boundary for verifying reclamation admission during root closure. */
+  onReclamationOpenObserved(): Effect.Effect<void>;
 }
 
 const defaultDependencies: WorkerSessionDependencies = {
@@ -217,30 +279,10 @@ const defaultDependencies: WorkerSessionDependencies = {
       detail: `Operation: ${operation}`,
     });
   },
+  beforeAdoptionReservation: () => Effect.void,
+  onReclamationOpenObserved: () => Effect.void,
 };
 
-export function resolveWorkerModel(
-  definition: WorkerDefinition,
-  parentModel: Model<Api> | undefined,
-  modelRegistry: ModelRegistry,
-): Model<Api> {
-  const configured = definition.model;
-  if (!configured) {
-    if (parentModel) return parentModel;
-    throw new Error(
-      `Worker "${definition.name}" has no configured model and no parent model is available`,
-    );
-  }
-
-  const model = modelRegistry.find(configured.provider, configured.modelId);
-  if (!model) {
-    throw new Error(
-      `Worker "${definition.name}" configured model "${configured.provider}/${configured.modelId}" was not found`,
-    );
-  }
-  return model;
-}
-
 function canonicalPath(path: string): string {
   try {
     return realpathSync.native(path);
@@ -276,25 +318,18 @@ function bestEffortCleanup(
   reporter: WorkerSessionCleanupReporter,
   operation: WorkerSessionCleanupOperation,
   cleanup: () => void | Promise<void>,
+  afterFailure: Effect.Effect<void> = Effect.void,
 ): Effect.Effect<void> {
   return Effect.tryPromise({
-    try: async () => cleanup(),
+    try: () => Promise.resolve(cleanup()),
     catch: (cause) => cause,
   }).pipe(
-    Effect.catch((cause) => reportCleanupFailure(reporter, operation, cause)),
+    Effect.catch((cause) =>
+      reportCleanupFailure(reporter, operation, cause).pipe(Effect.andThen(afterFailure))
+    ),
   );
 }
 
-function resourceLoaderFinalizer(
-  resourceLoader: ResourceLoader,
-  reporter: WorkerSessionCleanupReporter,
-): Effect.Effect<void> {
-  return bestEffortCleanup(reporter, "resource-loader", () => {
-    if (!("dispose" in resourceLoader) || typeof resourceLoader.dispose !== "function") return;
-    resourceLoader.dispose();
-  });
-}
-
 function describeError(error: unknown, fallback: string): string {
   if (error instanceof Error) return error.message;
   if (typeof error === "string" && error !== "") return error;
@@ -331,31 +366,67 @@ function emptyUsage(): MutableWorkerUsage {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
 
+interface ActivePrompt {
+  readonly _tag: "Active";
+  readonly previousAssistant: AssistantMessage | undefined;
+  assistant: AssistantMessage | undefined;
+  abortRequested: boolean;
+}
+
+type PromptState =
+  | { readonly _tag: "Idle" }
+  | ActivePrompt
+  | { readonly _tag: "Disposed" };
+
+interface PromptCompletion {
+  readonly failureMessage: string | undefined;
+  readonly message: AssistantMessage | undefined;
+  readonly prompt: ActivePrompt;
+}
+
 class DefaultWorkerSessionHandle implements WorkerSessionHandle {
   readonly sessionFile: string;
   private readonly usage = emptyUsage();
-  private readonly usageListeners = new Set<(usage: WorkerUsage) => void>();
-  private readonly activityListeners = new Set<(activity: string | undefined) => void>();
-  private readonly messageDirectionListeners = new Set<(direction: WorkerMessageDirection) => void>();
+  private readonly observationListeners = new Set<(observation: WorkerSessionObservation) => void>();
   private readonly activeToolCalls = new Map<string, string>();
-  private disposed = false;
-  private disposePromise: Promise<void> | undefined;
   private activity: string | undefined;
   private messageDirection: WorkerMessageDirection | undefined;
-  private prompting = false;
-  private abortRequested = false;
-  private promptAssistant: AssistantMessage | undefined;
+  private promptState: PromptState = { _tag: "Idle" };
+  private disposeOperation!: Effect.Effect<void, never>;
 
-  constructor(
+  private constructor(
     private readonly runtime: OwnedWorkerRuntime,
     private readonly interactive: boolean,
     sessionFile: string,
-    private readonly scope: Scope.Closeable,
-    private readonly cleanupReporter: WorkerSessionCleanupReporter,
   ) {
     this.sessionFile = sessionFile;
   }
 
+  static make(
+    runtime: OwnedWorkerRuntime,
+    interactive: boolean,
+    sessionFile: string,
+    scope: Scope.Closeable,
+    cleanupReporter: WorkerSessionCleanupReporter,
+  ): Effect.Effect<DefaultWorkerSessionHandle> {
+    return Effect.gen(function* () {
+      const handle = new DefaultWorkerSessionHandle(runtime, interactive, sessionFile);
+      handle.disposeOperation = yield* Effect.cached(
+        Effect.sync(() => handle.beginDispose()).pipe(
+          Effect.andThen(disposeWorkerSession(scope, cleanupReporter)),
+          Effect.uninterruptible,
+        ),
+      );
+      return handle;
+    });
+  }
+
+  private beginDispose(): void {
+    this.promptState = { _tag: "Disposed" };
+    this.activeToolCalls.clear();
+    this.observationListeners.clear();
+  }
+
   receiveSessionEvent(event: AgentSessionEvent): void {
     if (event.type === "message_start") {
       if (event.message.role === "assistant") this.setMessageDirection("from-model");
@@ -375,7 +446,7 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
       return;
     }
     if (event.type !== "turn_end" || event.message.role !== "assistant") return;
-    this.promptAssistant = event.message;
+    if (this.promptState._tag === "Active") this.promptState.assistant = event.message;
     this.usage.input += event.message.usage.input ?? 0;
     this.usage.output += event.message.usage.output ?? 0;
     this.usage.cacheRead += event.message.usage.cacheRead ?? 0;
@@ -383,96 +454,130 @@ class DefaultWorkerSessionHandle implements WorkerSessionHandle {
     this.usage.cost += event.message.usage.cost?.total ?? 0;
     this.usage.contextTokens = event.message.usage.totalTokens ?? 0;
     this.usage.turns += 1;
-    for (const listener of [...this.usageListeners]) safelyNotify(() => listener({ ...this.usage }));
+    this.emitObservation();
   }
 
   private setActivity(activity: string | undefined): void {
     if (this.activity === activity) return;
     this.activity = activity;
-    for (const listener of [...this.activityListeners]) safelyNotify(() => listener(activity));
+    this.emitObservation();
   }
 
   private setMessageDirection(direction: WorkerMessageDirection): void {
     if (this.messageDirection === direction) return;
     this.messageDirection = direction;
-    for (const listener of [...this.messageDirectionListeners]) safelyNotify(() => listener(direction));
+    this.emitObservation();
   }
 
-  async prompt(instructions: string): Promise<WorkerOutcome> {
-    if (this.disposed) throw new Error("Worker session has been disposed");
-    if (this.prompting) throw new Error("Worker session is already processing a prompt");
-    this.prompting = true;
-    this.abortRequested = false;
-    this.promptAssistant = undefined;
-    this.setMessageDirection("to-model");
-    const previousAssistant = lastAssistant(this.runtime.session.messages);
-    let failureMessage: string | undefined;
-    try {
-      await this.runtime.session.prompt(instructions, {
-        expandPromptTemplates: false,
-        source: "extension",
-      });
-    } catch (error) {
-      failureMessage = describeError(error, "Worker prompt failed");
-    } finally {
-      this.prompting = false;
-    }
-    const latestAssistant = lastAssistant(this.runtime.session.messages);
-    const message = this.promptAssistant ?? (latestAssistant !== previousAssistant ? latestAssistant : undefined);
-    const text = assistantText(message);
-    const assistantPayload = text === undefined ? {} : { assistantText: text };
-    if (this.abortRequested || message?.stopReason === "aborted") {
-      const abortMessage = message?.errorMessage ?? failureMessage;
-      return { status: "aborted", ...(abortMessage ? { message: abortMessage } : {}), ...assistantPayload };
-    }
-    if (message?.stopReason === "error") {
-      return { status: "failed", message: message.errorMessage ?? failureMessage ?? "Worker assistant reported a failure", ...assistantPayload };
+  private emitObservation(): void {
+    const observation: WorkerSessionObservation = Object.freeze({
+      usage: Object.freeze({ ...this.usage }),
+      activity: this.activity,
+      messageDirection: this.messageDirection,
+    });
+    for (const listener of [...this.observationListeners]) {
+      safelyNotify(() => listener(observation));
     }
-    if (failureMessage) return { status: "failed", message: failureMessage, ...assistantPayload };
-    return { status: this.interactive ? "ready" : "completed", assistantText: text ?? "" };
   }
 
-  async abort(): Promise<void> {
-    if (this.prompting) this.abortRequested = true;
+  prompt(instructions: string): Effect.Effect<WorkerOutcome, never> {
+    return Effect.fn("WorkerSession.prompt")(function* (this: DefaultWorkerSessionHandle) {
+      const completion = yield* Effect.sync(() => this.startPrompt(instructions));
+      const { failureMessage, message, prompt } = yield* Effect.promise(() => completion);
+      const text = assistantText(message);
+      const assistantPayload = text === undefined ? {} : { assistantText: text };
+      if (prompt.abortRequested || message?.stopReason === "aborted") {
+        const abortMessage = message?.errorMessage ?? failureMessage;
+        return { status: "aborted", ...(abortMessage ? { message: abortMessage } : {}), ...assistantPayload } satisfies WorkerOutcome;
+      }
+      if (message?.stopReason === "error") {
+        return { status: "failed", message: message.errorMessage ?? failureMessage ?? "Worker assistant reported a failure", ...assistantPayload } satisfies WorkerOutcome;
+      }
+      if (failureMessage) return { status: "failed", message: failureMessage, ...assistantPayload } satisfies WorkerOutcome;
+      return { status: this.interactive ? "ready" : "completed", assistantText: text ?? "" } satisfies WorkerOutcome;
+    }).call(this);
+  }
 
-    let firstFailure: unknown;
-    try {
-      this.runtime.session.abortCompaction();
-    } catch (error) {
-      firstFailure = error;
-    }
+  private startPrompt(instructions: string): Promise<PromptCompletion> {
+    if (this.promptState._tag === "Disposed") throw new Error("Worker session has been disposed");
+    if (this.promptState._tag === "Active") throw new Error("Worker session is already processing a prompt");
+
+    const prompt: ActivePrompt = {
+      _tag: "Active",
+      previousAssistant: lastAssistant(this.runtime.session.messages),
+      assistant: undefined,
+      abortRequested: false,
+    };
+    this.promptState = prompt;
+    this.setMessageDirection("to-model");
 
+    let physicalPrompt: Promise<void>;
     try {
-      await this.runtime.session.abort();
-    } catch (error) {
-      if (firstFailure === undefined) firstFailure = error;
+      physicalPrompt = this.runtime.session.prompt(instructions, {
+        expandPromptTemplates: false,
+        source: "extension",
+      });
+    } catch (cause) {
+      return Promise.resolve(this.completePrompt(
+        prompt,
+        describeError(cause, "Worker prompt failed"),
+      ));
     }
 
-    if (firstFailure !== undefined) throw firstFailure;
+    return physicalPrompt.then(
+      () => this.completePrompt(prompt, undefined),
+      (cause) => this.completePrompt(prompt, describeError(cause, "Worker prompt failed")),
+    );
   }
 
-  dispose(): Promise<void> {
-    if (this.disposePromise) return this.disposePromise;
-
-    this.disposed = true;
-    this.activeToolCalls.clear();
-    this.usageListeners.clear();
-    this.activityListeners.clear();
-    this.messageDirectionListeners.clear();
-    this.disposePromise = Effect.runPromise(
-      disposeWorkerSession(this.scope, this.cleanupReporter),
-    );
-    return this.disposePromise;
+  private completePrompt(
+    prompt: ActivePrompt,
+    failureMessage: string | undefined,
+  ): PromptCompletion {
+    const latestAssistant = lastAssistant(this.runtime.session.messages);
+    const message = prompt.assistant ??
+      (latestAssistant !== prompt.previousAssistant ? latestAssistant : undefined);
+    if (this.promptState === prompt) this.promptState = { _tag: "Idle" };
+    return { failureMessage, message, prompt };
   }
 
-  subscribeUsage(listener: (usage: WorkerUsage) => void): () => void {
-    return subscribe(this.usageListeners, listener);
+  abort(): Effect.Effect<void, WorkerSessionAbortError> {
+    return Effect.fn("WorkerSession.abort")(function* (this: DefaultWorkerSessionHandle) {
+      if (this.promptState._tag === "Active") this.promptState.abortRequested = true;
+
+      const compaction = yield* Effect.result(Effect.try({
+        try: () => this.runtime.session.abortCompaction(),
+        catch: (cause) => new WorkerSessionAbortError({
+          operation: "abort-compaction",
+          stage: "compaction",
+          message: describeError(cause, "Worker compaction abort failed"),
+          cause,
+        }),
+      }));
+      const prompt = yield* Effect.result(Effect.tryPromise({
+        try: () => this.runtime.session.abort(),
+        catch: (cause) => new WorkerSessionAbortError({
+          operation: "abort-prompt",
+          stage: "prompt",
+          message: describeError(cause, "Worker prompt abort failed"),
+          cause,
+        }),
+      }));
+
+      if (compaction._tag === "Failure") return yield* Effect.fail(compaction.failure);
+      if (prompt._tag === "Failure") return yield* Effect.fail(prompt.failure);
+    }).call(this);
   }
-  subscribeActivity(listener: (activity: string | undefined) => void): () => void {
-    return subscribe(this.activityListeners, listener);
+
+  dispose(): Effect.Effect<void, never> {
+    return this.disposeOperation;
   }
-  subscribeMessageDirection(listener: (direction: WorkerMessageDirection) => void): () => void {
-    return subscribe(this.messageDirectionListeners, listener);
+
+  subscribeObservation(listener: (observation: WorkerSessionObservation) => void): () => void {
+    // A disposed handle has no current event source. Late subscription is an
+    // explicit no-op rather than a listener retained forever.
+    if (this.promptState._tag === "Disposed") return () => {};
+    return subscribe(this.observationListeners, listener);
   }
 }
 
@@ -499,36 +604,30 @@ function selectedModelCoordinates(
   throw new Error(`Worker "${definition.name}" has no configured model and no parent model is available`);
 }
 
-function modelAcquisitionError(
-  operation: WorkerModelAcquisitionOperation,
-  fallback: string,
-): (cause: unknown) => WorkerModelAcquisitionError {
-  return (cause) => new WorkerModelAcquisitionError({
-    operation,
-    message: describeError(cause, fallback),
-    cause,
-  });
-}
-
-function resourceAcquisitionError(
-  operation: WorkerResourceAcquisitionOperation,
-): (cause: unknown) => WorkerResourceAcquisitionError {
-  return (cause) => new WorkerResourceAcquisitionError({
-    operation,
-    message: describeError(cause, "Worker resource acquisition failed"),
-    cause,
-  });
+function acquisitionErrorFactory<Operation, AcquisitionError>(
+  ErrorClass: new (fields: {
+    operation: Operation;
+    message: string;
+    cause: unknown;
+  }) => AcquisitionError,
+  defaultMessage: string,
+) {
+  return (operation: Operation, fallback = defaultMessage) => (cause: unknown) =>
+    new ErrorClass({ operation, message: describeError(cause, fallback), cause });
 }
 
-function agentSessionAcquisitionError(
-  operation: WorkerAgentSessionAcquisitionOperation,
-): (cause: unknown) => WorkerAgentSessionAcquisitionError {
-  return (cause) => new WorkerAgentSessionAcquisitionError({
-    operation,
-    message: describeError(cause, "Worker agent session acquisition failed"),
-    cause,
-  });
-}
+const modelAcquisitionError = acquisitionErrorFactory(
+  WorkerModelAcquisitionError,
+  "Worker model acquisition failed",
+);
+const resourceAcquisitionError = acquisitionErrorFactory(
+  WorkerResourceAcquisitionError,
+  "Worker resource acquisition failed",
+);
+const agentSessionAcquisitionError = acquisitionErrorFactory(
+  WorkerAgentSessionAcquisitionError,
+  "Worker agent session acquisition failed",
+);
 
 const refreshModelRuntime = Effect.fn("WorkerSession.refreshModelRuntime")(function* (
   modelRuntime: ModelRuntime,
@@ -556,7 +655,7 @@ const refreshModelRuntime = Effect.fn("WorkerSession.refreshModelRuntime")(funct
 });
 
 const prepareChildModelRuntime = Effect.fn("WorkerSession.prepareChildModelRuntime")(function* (
-  options: WorkerSessionFactoryOptions,
+  options: ChildSessionOptions,
   dependencies: WorkerSessionDependencies,
 ) {
   const selected = yield* Effect.try({
@@ -639,8 +738,9 @@ function contextLoaderOptions(
 const disposeWorkerSession = Effect.fn("WorkerSession.dispose")(function* (
   scope: Scope.Closeable,
   reporter: WorkerSessionCleanupReporter,
+  exit: Exit.Exit<void, unknown> = Exit.void,
 ) {
-  yield* Scope.close(scope, Exit.void).pipe(
+  yield* Scope.close(scope, exit).pipe(
     Effect.catchCause((cause) =>
       reportCleanupFailure(reporter, "scope-close", Cause.squash(cause))
     ),
@@ -648,7 +748,7 @@ const disposeWorkerSession = Effect.fn("WorkerSession.dispose")(function* (
 });
 
 const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(function* (
-  options: WorkerSessionFactoryOptions,
+  options: ChildSessionOptions,
   dependencies: WorkerSessionDependencies,
   modelRuntime: ModelRuntime,
 ) {
@@ -692,9 +792,14 @@ const acquireWorkerServices = Effect.fn("WorkerSession.acquireServices")(functio
       }),
       catch: resourceAcquisitionError("create-services"),
     }),
-    (services) => resourceLoaderFinalizer(
-      services.resourceLoader,
+    (services) => bestEffortCleanup(
       dependencies.reportCleanupFailure,
+      "resource-loader",
+      () => {
+        const loader = services.resourceLoader;
+        if (!("dispose" in loader) || typeof loader.dispose !== "function") return;
+        loader.dispose();
+      },
     ),
   );
 });
@@ -704,29 +809,19 @@ interface AgentSessionOwnership {
   runtime: OwnedWorkerRuntime | undefined;
 }
 
-function rawSessionFinalizer(
-  session: WorkerAgentSession,
-  reporter: WorkerSessionCleanupReporter,
-): Effect.Effect<void> {
-  return bestEffortCleanup(reporter, "raw-session", () => session.dispose());
-}
-
 function agentSessionFinalizer(
   ownership: AgentSessionOwnership,
   reporter: WorkerSessionCleanupReporter,
 ): Effect.Effect<void> {
-  const runtime = ownership.runtime;
-  if (!runtime) return rawSessionFinalizer(ownership.session, reporter);
-  return Effect.tryPromise({
-    try: () => runtime.dispose(),
-    catch: (cause) => cause,
-  }).pipe(
-    Effect.catch((cause) =>
-      reportCleanupFailure(reporter, "runtime", cause).pipe(
-        Effect.andThen(rawSessionFinalizer(ownership.session, reporter)),
-      )
-    ),
+  const disposeRawSession = bestEffortCleanup(
+    reporter,
+    "raw-session",
+    () => ownership.session.dispose(),
   );
+  const runtime = ownership.runtime;
+  return runtime
+    ? bestEffortCleanup(reporter, "runtime", () => runtime.dispose(), disposeRawSession)
+    : disposeRawSession;
 }
 
 const acquireAgentSession = Effect.fn("WorkerSession.acquireAgentSession")(function* (
@@ -780,7 +875,7 @@ const acquireSessionSubscription = Effect.fn("WorkerSession.acquireSubscription"
 });
 
 const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
-  options: WorkerSessionFactoryOptions,
+  options: ChildSessionOptions,
   dependencies: WorkerSessionDependencies,
 ) {
   const scope = yield* Scope.make("sequential");
@@ -850,7 +945,7 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
       catch: agentSessionAcquisitionError("verify-durability"),
     });
 
-    const handle = new DefaultWorkerSessionHandle(
+    const handle = yield* DefaultWorkerSessionHandle.make(
       runtime,
       definition.lifecycle === "interactive",
       sessionFile,
@@ -864,14 +959,10 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
   return yield* acquisition.pipe(
     Effect.catchCause((cause) =>
       Effect.gen(function* () {
-        yield* Scope.close(scope, Exit.failCause(cause)).pipe(
-          Effect.catchCause((cleanupCause) =>
-            reportCleanupFailure(
-              dependencies.reportCleanupFailure,
-              "scope-close",
-              Cause.squash(cleanupCause),
-            )
-          ),
+        yield* disposeWorkerSession(
+          scope,
+          dependencies.reportCleanupFailure,
+          Exit.failCause(cause),
         );
         return yield* Effect.failCause(cause);
       })
@@ -879,9 +970,244 @@ const createWorkerSession = Effect.fn("WorkerSession.create")(function* (
   );
 });
 
-export function createWorkerSessionFactory(
+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> = {},
-): WorkerSessionFactory {
-  const dependencies: WorkerSessionDependencies = { ...defaultDependencies, ...overrides };
-  return { create: (options) => Effect.runPromise(createWorkerSession(options, dependencies)) };
+): 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 });
+    }),
+  );
 }