[orchestrator-v2] fix(orchestrator): Prevent Claude session release from hanging on idle CLI reads

apps/server/src/orchestration-v2/ProviderAdapter.ts

@@ -474,6 +474,12 @@ export interface ProviderAdapterV2SessionRuntime {
    * Adapter runtimes may omit this and expose only their single-consumer event stream.
    */
   readonly subscribeEvents?: Effect.Effect<ProviderAdapterV2EventSubscription>;
+  /**
+   * Adapters whose native runtime can hold pending work outside an active
+   * turn (for example Claude background tasks and their wake turns) report it
+   * here so the session manager defers idle release while it is pending.
+   */
+  readonly hasPendingBackgroundWork?: Effect.Effect<boolean>;
   readonly ensureThread: (
     input: ProviderAdapterV2EnsureThreadInput,
   ) => Effect.Effect<OrchestrationV2ProviderThread, ProviderAdapterV2Error>;

apps/server/src/orchestration-v2/ProviderContinuationRequests.ts

@@ -0,0 +1,39 @@
+import { ProviderDriverKind, ProviderThreadId, ThreadId } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+
+export interface ProviderContinuationRequest {
+  readonly threadId: ThreadId;
+  readonly providerThreadId: ProviderThreadId;
+  readonly driver: ProviderDriverKind;
+  readonly detail: string | null;
+}
+
+/**
+ * Adapters offer a continuation request when provider-native work completes
+ * outside an active turn (for example a Claude background task wake turn) so
+ * the orchestrator can start a run that ingests it. The default reference
+ * drops requests, keeping adapter construction dependency-free in tests; the
+ * live layer must be shared with the ProviderContinuationService worker that
+ * drains it.
+ */
+export class ProviderContinuationRequests extends Context.Reference<{
+  readonly offer: (request: ProviderContinuationRequest) => Effect.Effect<void>;
+  readonly take: Effect.Effect<ProviderContinuationRequest>;
+}>("t3/orchestration-v2/ProviderContinuationRequests", {
+  defaultValue: () => ({ offer: () => Effect.void, take: Effect.never }),
+}) {}
+
+export const layer = Layer.effect(
+  ProviderContinuationRequests,
+  Effect.gen(function* () {
+    const queue = yield* Queue.unbounded<ProviderContinuationRequest>();
+    return {
+      offer: (request: ProviderContinuationRequest) =>
+        Queue.offer(queue, request).pipe(Effect.asVoid),
+      take: Queue.take(queue),
+    };
+  }),
+);

apps/server/src/orchestration-v2/ProviderContinuationService.ts

@@ -0,0 +1,72 @@
+import { CommandId } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import { IdAllocatorV2 } from "./IdAllocator.ts";
+import {
+  type ProviderContinuationRequest,
+  ProviderContinuationRequests,
+} from "./ProviderContinuationRequests.ts";
+import { ThreadManagementService } from "./ThreadManagementService.ts";
+
+const CONTINUATION_MESSAGE_TEXT = "Background task completed.";
+
+/**
+ * Drains ProviderContinuationRequests and dispatches an internal
+ * message.dispatch per request so the wake turn buffered by the adapter is
+ * ingested as a normal run. Dispatches queue_after_active, so a continuation
+ * racing a user run simply queues behind it and drains the wake buffer once
+ * that run finishes.
+ */
+export const workerLive = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const ids = yield* IdAllocatorV2;
+    const requests = yield* ProviderContinuationRequests;
+    const threads = yield* ThreadManagementService;
+
+    const dispatchContinuation = Effect.fn("ProviderContinuationService.dispatchContinuation")(
+      function* (request: ProviderContinuationRequest) {
+        const projection = yield* threads.getThreadProjection(request.threadId);
+        if (projection.thread.archivedAt !== null) {
+          yield* Effect.logInfo("orchestration-v2.provider-continuation.thread-archived", {
+            threadId: request.threadId,
+            providerThreadId: request.providerThreadId,
+          });
+          return;
+        }
+        const messageId = yield* ids.allocate.message({
+          threadId: request.threadId,
+          ordinal: projection.messages.length + 1,
+        });
+        const commandId = CommandId.make(`provider-continuation:${messageId}`);
+        yield* threads.dispatch({
+          type: "message.dispatch",
+          commandId,
+          threadId: request.threadId,
+          messageId,
+          text: request.detail ?? CONTINUATION_MESSAGE_TEXT,
+          attachments: [],
+          dispatchMode: { type: "queue_after_active" },
+          createdBy: "agent",
+          creationSource: "provider",
+        });
+      },
+    );
+
+    yield* requests.take.pipe(
+      Effect.flatMap((request) =>
+        dispatchContinuation(request).pipe(
+          Effect.catchCause((cause) =>
+            Effect.logWarning("orchestration-v2.provider-continuation.dispatch-failed", {
+              threadId: request.threadId,
+              providerThreadId: request.providerThreadId,
+              cause,
+            }),
+          ),
+        ),
+      ),
+      Effect.forever,
+      Effect.forkScoped,
+    );
+  }),
+);