The best way to control Claude Code, Codex and more from any computer or phone
fix(server): a queued provider switch no longer ends background work (#30401)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 3, 2026 at 15:36 UTC
6049196c5004d95ea7ea9a1781a2b4245a2a6e93
2 files changed
+186
-48
apps/server/src/orchestration-v2/Orchestrator.ts
+72
-39
@@ -1167,6 +1167,35 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1167
return withId;
1168
});
1169
1170
+ // Detaching kills background work running inside the provider process.
1171
+ // Probe even with an empty roster: Claude's native subagents never reach
1172
+ // pendingBackgroundTasks. Sessions shared across threads probe per thread.
1173
+ const sessionHasBackgroundWork = Effect.fn("Orchestrator.sessionHasBackgroundWork")(function* (
1174
+ detaching: OrchestrationV2ThreadProjection["providerSessions"][number],
1175
+ providerThreads: OrchestrationV2ThreadProjection["providerThreads"],
1176
+ ) {
1177
+ const session = yield* providerSessions
1178
+ .get(detaching.id)
1179
+ .pipe(Effect.orElseSucceed(() => Option.none()));
1180
+ if (Option.isNone(session)) return false;
1181
+ const runtime = session.value;
1182
+ const probes =
1183
+ !detaching.capabilities.sessions.supportsMultipleProviderThreadsPerSession &&
1184
+ runtime.hasPendingBackgroundWork !== undefined
1185
+ ? [runtime.hasPendingBackgroundWork]
1186
+ : providerThreads.flatMap((providerThread) =>
1187
+ providerThread.providerSessionId === detaching.id &&
1188
+ runtime.hasPendingBackgroundWorkForThread !== undefined
1189
+ ? [runtime.hasPendingBackgroundWorkForThread(providerThread)]
1190
+ : [],
1191
+ );
1192
+ for (const probe of probes) {
1193
+ // A failed probe cannot confirm that the work ended.
1194
+ if (yield* probe.pipe(Effect.catchCause(() => Effect.succeed(true)))) return true;
1195
+ }
1196
+ return false;
1197
+ });
1198
+
1199
// Runs in every command transaction; avoid reading thousands of finished leaf nodes.
1200
const readCommandProjection = (threadId: ThreadId) =>
1201
projectionStore
@@ -1827,6 +1856,42 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
1856
),
1857
)
1858
: null;
1859
+ const releasableSessions = projection.providerSessions.filter(
1860
+ (session) =>
1861
+ switchPlan?.releaseProviderSessionIds.includes(session.id) &&
1862
+ session.status !== "stopped" &&
1863
+ session.status !== "error",
1864
+ );
1865
+ const busySessionIds = new Set<ProviderSessionId>();
1866
+ for (const session of releasableSessions) {
1867
+ if (yield* sessionHasBackgroundWork(session, projection.providerThreads)) {
1868
+ busySessionIds.add(session.id);
1869
+ }
1870
+ }
1871
+ // Nobody waits on a queued start to refuse it. A handoff runs in its own session, so a
1872
+ // busy one stays up; a restart resumes the busy session's native thread, so wait instead.
1873
+ if (busySessionIds.size > 0 && switchPlan?.transition.type === "restart_and_resume") {
1874
+ yield* Effect.logInfo(
1875
+ "Holding the queue: the replaced provider session still runs background work",
1876
+ { threadId, runId: queuedRun.id, providerSessionIds: Array.from(busySessionIds) },
1877
+ );
1878
+ yield* writeSystemEvents(
1879
+ projection.runs
1880
+ .filter((run) => run.status === "queued")
1881
+ .map((run) => ({
1882
+ type: "run.updated" as const,
1883
+ threadId,
1884
+ runId: run.id,
1885
+ providerInstanceId: run.providerInstanceId,
1886
+ occurredAt: now,
1887
+ payload: { ...run, queueHeld: true },
1888
+ })),
1889
+ );
1890
+ return;
1891
+ }
1892
+ const sessionsToDetach = releasableSessions.filter(
1893
+ (session) => !busySessionIds.has(session.id),
1894
+ );
1895
const canResumeAcrossInstances =
1896
switchPlan?.instanceChanged === true &&
1897
switchPlan.transition.type === "restart_and_resume" &&
@@ -2165,12 +2230,6 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
2230
},
2231
]
2232
: [];
2168
- const sessionsToDetach = projection.providerSessions.filter(
2169
- (session) =>
2170
- switchPlan?.releaseProviderSessionIds.includes(session.id) &&
2171
- session.status !== "stopped" &&
2172
- session.status !== "error",
2173
- );
2233
yield* writeSystemEvents(
2234
[
2235
...(selectionChanged
@@ -6284,40 +6343,14 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
6343
session.status !== "stopped" &&
6344
session.status !== "error",
6345
);
6287
- // Detaching kills background work running inside the provider process.
6288
- // Probe even with an empty roster: Claude's native subagents never reach
6289
- // pendingBackgroundTasks. Sessions shared across threads probe per thread.
6346
for (const detaching of sessionsToDetach) {
6291
- const session = yield* providerSessions
6292
- .get(detaching.id)
6293
- .pipe(Effect.orElseSucceed(() => Option.none()));
6294
- if (Option.isNone(session)) {
6295
- continue;
6296
- }
6297
- const runtime = session.value;
6298
- const probes =
6299
- !detaching.capabilities.sessions.supportsMultipleProviderThreadsPerSession &&
6300
- runtime.hasPendingBackgroundWork !== undefined
6301
- ? [runtime.hasPendingBackgroundWork]
6302
- : projection.providerThreads.flatMap((providerThread) =>
6303
- providerThread.providerSessionId === detaching.id &&
6304
- runtime.hasPendingBackgroundWorkForThread !== undefined
6305
- ? [runtime.hasPendingBackgroundWorkForThread(providerThread)]
6306
- : [],
6307
- );
6308
- for (const probe of probes) {
6309
- const stillRunning = yield* probe.pipe(
6310
- // A failed probe cannot confirm that the work ended.
6311
- Effect.catchCause(() => Effect.succeed(true)),
6312
- );
6313
- if (stillRunning) {
6314
- return yield* new OrchestratorDispatchError({
6315
- commandId: command.commandId,
6316
- commandType: command.type,
6317
- cause:
6318
- "The previous provider is still running background agents or commands, and switching would end them. Wait for them to finish, or press Stop, then send the message again.",
6319
- });
6320
- }
6347
+ if (yield* sessionHasBackgroundWork(detaching, projection.providerThreads)) {
6348
+ return yield* new OrchestratorDispatchError({
6349
+ commandId: command.commandId,
6350
+ commandType: command.type,
6351
+ cause:
6352
+ "The previous provider is still running background agents or commands, and switching would end them. Wait for them to finish, or press Stop, then send the message again.",
6353
+ });
6354
}
6355
}
6356
apps/server/src/orchestration-v2/testkit/ProviderSwitch.integration.test.ts
+114
-9
@@ -2529,21 +2529,36 @@ describe("orchestration v2 provider switching", () => {
2529
2530
// regression: #20343 sending to an instance with separate history must release the old session
2531
it.live.each([
2532
- ["detaches the previous instance's session when a send hands off to another instance", false],
2533
- ["refuses the hand-off while the previous instance still runs background work", true],
2534
- ] as const)("%s", ([, backgroundRunning]) =>
2532
+ [
2533
+ "detaches the previous instance's session when a send hands off to another instance",
2534
+ { background: false, queued: false, sharedHistory: false },
2535
+ ],
2536
+ [
2537
+ "refuses the hand-off while the previous instance still runs background work",
2538
+ { background: true, queued: false, sharedHistory: false },
2539
+ ],
2540
+ [
2541
+ "keeps a busy previous session running when a queued hand-off starts",
2542
+ { background: true, queued: true, sharedHistory: false },
2543
+ ],
2544
+ [
2545
+ "holds a queued account switch while the replaced session still runs background work",
2546
+ { background: true, queued: true, sharedHistory: true },
2547
+ ],
2548
+ ] as const)("%s", ([, { background, queued, sharedHistory }]) =>
2549
Effect.scoped(
2550
Effect.gen(function* () {
2551
const cwd = yield* checkpointWorkspace("handoff-releases-session");
2552
const capturedTurns = yield* Ref.make<ReadonlyArray<CapturedTurn>>([]);
2539
- const backgroundWork = yield* Ref.make(backgroundRunning);
2553
+ const backgroundWork = yield* Ref.make(background);
2554
const closedSessions = yield* Ref.make<ReadonlyArray<string>>([]);
2555
+ const firstStarted = yield* Deferred.make<void>();
2556
+ const releaseFirst = yield* Deferred.make<void>();
2557
const secondSelection: ModelSelection = {
2558
...CLAUDE_MODEL_SELECTION,
2559
instanceId: ProviderInstanceId.make("claude-second-account"),
2560
};
2545
- // No shared continuation key: each Claude instance owns its own native history.
2546
- const layerRegistry = ProviderAdapterRegistry.layerFromAdapters([
2561
+ const adapters = [
2562
makeTestAdapter({
2563
instanceId: CLAUDE_MODEL_SELECTION.instanceId,
2564
driver: CLAUDE_DRIVER,
@@ -2553,6 +2568,7 @@ describe("orchestration v2 provider switching", () => {
2568
capturedTurns,
2569
backgroundWork,
2570
closedSessions,
2571
+ ...(queued ? { holdFirstTurn: firstStarted, releaseFirstTurn: releaseFirst } : {}),
2572
}),
2573
makeTestAdapter({
2574
instanceId: secondSelection.instanceId,
@@ -2562,7 +2578,33 @@ describe("orchestration v2 provider switching", () => {
2578
responseByRunOrdinal: { 2: "Second account complete" },
2579
capturedTurns,
2580
}),
2565
- ]);
2581
+ ];
2582
+ // Without a shared continuation key, each Claude instance owns its own native history.
2583
+ const layerRegistry = sharedHistory
2584
+ ? Layer.succeed(
2585
+ ProviderAdapterRegistry.ProviderAdapterRegistryV2,
2586
+ ProviderAdapterRegistry.ProviderAdapterRegistryV2.of({
2587
+ get: (instanceId) => {
2588
+ const adapter = adapters.find((candidate) => candidate.instanceId === instanceId);
2589
+ return adapter === undefined
2590
+ ? Effect.fail(
2591
+ new ProviderAdapterRegistry.ProviderAdapterRegistryLookupError({
2592
+ instanceId,
2593
+ }),
2594
+ )
2595
+ : Effect.succeed(adapter);
2596
+ },
2597
+ list: () => Effect.succeed(adapters.map((adapter) => adapter.instanceId)),
2598
+ getMetadata: () =>
2599
+ Effect.succeed({
2600
+ driver: CLAUDE_DRIVER,
2601
+ continuationKey: "claude:shared-native-account-history",
2602
+ enabled: true,
2603
+ capabilities: ClaudeProviderCapabilitiesV2,
2604
+ }),
2605
+ }),
2606
+ )
2607
+ : ProviderAdapterRegistry.layerFromAdapters(adapters);
2608
const handoffThreadId = ThreadId.make("thread:handoff-releases-session");
2609
yield* Effect.gen(function* () {
2610
const orchestrator = yield* Orchestrator.OrchestratorV2;
@@ -2578,7 +2620,7 @@ describe("orchestration v2 provider switching", () => {
2620
text: `Prompt ${ordinal}`,
2621
attachments: [],
2622
modelSelection,
2581
- dispatchMode: { type: "start_immediately" },
2623
+ dispatchMode: { type: queued ? "queue_after_active" : "start_immediately" },
2624
});
2625
yield* orchestrator.dispatch({
2626
type: "thread.create",
@@ -2595,6 +2637,69 @@ describe("orchestration v2 provider switching", () => {
2637
worktreePath: cwd,
2638
});
2639
yield* send(1, CLAUDE_MODEL_SELECTION);
2640
+
2641
+ if (queued) {
2642
+ yield* Deferred.await(firstStarted);
2643
+ yield* send(2, secondSelection);
2644
+ const queuedRunId = (yield* orchestrator.getThreadProjection(handoffThreadId)).runs[1]
2645
+ ?.id;
2646
+ assert.isDefined(queuedRunId);
2647
+ yield* Deferred.succeed(releaseFirst, undefined);
2648
+ yield* orchestrator.streamStoredEvents.pipe(
2649
+ Stream.filter(
2650
+ ({ event }) =>
2651
+ event.type === "run.updated" &&
2652
+ event.runId === queuedRunId &&
2653
+ (event.payload.queueHeld === true || event.payload.status === "completed"),
2654
+ ),
2655
+ Stream.runHead,
2656
+ );
2657
+ yield* worker.drain();
2658
+ const afterQueue = yield* orchestrator.getThreadProjection(handoffThreadId);
2659
+ const firstSession = afterQueue.providerSessions.find(
2660
+ (session) => session.providerInstanceId === CLAUDE_MODEL_SELECTION.instanceId,
2661
+ );
2662
+ // Detaching would end the background agents, so the busy session must stay up.
2663
+ assert.deepEqual(yield* Ref.get(closedSessions), []);
2664
+ assert.equal(firstSession?.status, "ready");
2665
+ if (!sharedHistory) {
2666
+ assert.deepEqual(
2667
+ afterQueue.runs.map((run) => [run.providerInstanceId, run.status]),
2668
+ [
2669
+ [CLAUDE_MODEL_SELECTION.instanceId, "completed"],
2670
+ [secondSelection.instanceId, "completed"],
2671
+ ],
2672
+ );
2673
+ return;
2674
+ }
2675
+ // Resuming the native thread beside the busy session would fork its history.
2676
+ assert.deepEqual(
2677
+ afterQueue.runs.map((run) => [run.status, run.queueHeld === true]),
2678
+ [
2679
+ ["completed", false],
2680
+ ["queued", true],
2681
+ ],
2682
+ );
2683
+ assert.lengthOf(yield* Ref.get(capturedTurns), 1);
2684
+ yield* Ref.set(backgroundWork, false);
2685
+ yield* orchestrator.dispatch({
2686
+ type: "queue.resume",
2687
+ commandId: CommandId.make("command:handoff-releases-session:resume"),
2688
+ threadId: handoffThreadId,
2689
+ });
2690
+ yield* worker.drain();
2691
+ const resumed = yield* waitForIdle(handoffThreadId);
2692
+ assert.deepEqual(
2693
+ resumed.runs.map((run) => [run.providerInstanceId, run.status]),
2694
+ [
2695
+ [CLAUDE_MODEL_SELECTION.instanceId, "completed"],
2696
+ [secondSelection.instanceId, "completed"],
2697
+ ],
2698
+ );
2699
+ assert.deepEqual(yield* Ref.get(closedSessions), [firstSession!.id]);
2700
+ return;
2701
+ }
2702
+
2703
yield* worker.drain();
2704
const afterFirst = yield* waitForIdle(handoffThreadId);
2705
const firstSession = afterFirst.providerSessions.find(
@@ -2602,7 +2707,7 @@ describe("orchestration v2 provider switching", () => {
2707
);
2708
assert.equal(firstSession?.status, "ready");
2709
2605
- if (backgroundRunning) {
2710
+ if (background) {
2711
// Native subagents live only in the adapter's roster, so the projection's
2712
// pendingBackgroundTasks stays empty while the probe still reports work.
2713
assert.deepEqual(afterFirst.providerThreads[0]?.pendingBackgroundTasks ?? [], []);