The best way to control Claude Code, Codex and more from any computer or phone
fix(server): background subagents stop running when their Claude session is released (#36569)
Julius Marminge committed
Nov 14, 2026 at 01:36 UTC
4b99420d8e13d9cbbdfd60374583202ecff2dc0f
4 files changed
+197
-5
apps/server/src/orchestration-v2/EventSink.ts
+38
@@ -3,6 +3,7 @@ import {
3
type OrchestrationV2Run,
4
OrchestrationV2DomainEvent,
5
type OrchestrationV2ProviderThread,
6
+ type OrchestrationV2Subagent,
7
type OrchestrationV2TurnItem,
8
OrchestrationV2StoredEvent,
9
ProviderThreadId,
@@ -180,6 +181,17 @@ export interface EventSinkV2Shape {
181
},
182
EventSinkV2Error
183
>;
184
+ /** Commits only if the stored subagent still equals expected. */
185
+ readonly writeIfSubagentUnchanged: (input: {
186
+ readonly expected: OrchestrationV2Subagent;
187
+ readonly events: ReadonlyArray<OrchestrationV2DomainEvent>;
188
+ }) => Effect.Effect<
189
+ {
190
+ readonly committed: boolean;
191
+ readonly storedEvents: ReadonlyArray<OrchestrationV2StoredEvent>;
192
+ },
193
+ EventSinkV2Error
194
+ >;
195
readonly commitCommand: (input: {
196
readonly commandId: CommandId;
197
readonly threadId: ThreadId;
@@ -712,6 +724,26 @@ const layerBase: Layer.Layer<
724
);
725
});
726
727
+ const writeIfSubagentUnchangedEffect = Effect.fn(
728
+ "orchestrationV2.EventSink.writeIfSubagentUnchanged",
729
+ )(function* (input: Parameters<EventSinkV2Shape["writeIfSubagentUnchanged"]>[0]) {
730
+ yield* Effect.annotateCurrentSpan({
731
+ "orchestration_v2.event_count": input.events.length,
732
+ "orchestration_v2.subagent_id": input.expected.id,
733
+ });
734
+ const expectedJson = yield* ProjectionStore.encodeSubagentPayload(input.expected);
735
+ return yield* writeIfStoredPayloadMatches(
736
+ sql<{ readonly payload_json: string }>`
737
+ SELECT payload_json
738
+ FROM orchestration_v2_projection_subagents
739
+ WHERE subagent_id = ${input.expected.id}
740
+ LIMIT 1
741
+ `,
742
+ expectedJson,
743
+ input.events,
744
+ );
745
+ });
746
+
747
const existingCommandResult =
748
/* This helper runs for individual orchestration events; the enclosing operation owns the span. */
749
Effect.fnUntraced(function* (commandId: CommandId) {
@@ -1118,6 +1150,12 @@ const layerBase: Layer.Layer<
1150
(cause) => new EventSinkWriteError({ eventCount: input.events.length, cause }),
1151
),
1152
),
1153
+ writeIfSubagentUnchanged: (input) =>
1154
+ writeIfSubagentUnchangedEffect(input).pipe(
1155
+ Effect.mapError(
1156
+ (cause) => new EventSinkWriteError({ eventCount: input.events.length, cause }),
1157
+ ),
1158
+ ),
1159
commitCommand: (input) =>
1160
commitCommandEffect(input).pipe(
1161
Effect.mapError(
apps/server/src/orchestration-v2/ProjectionStore.ts
+1
-1
@@ -1205,7 +1205,7 @@ const encodeRunAttemptPayload = Schema.encodeEffect(
1205
const encodeNodePayload = Schema.encodeEffect(
1206
Schema.fromJsonString(OrchestrationV2ExecutionNodeJsonSchema),
1207
);
1208
-const encodeSubagentPayload = Schema.encodeEffect(
1208
+export const encodeSubagentPayload = Schema.encodeEffect(
1209
Schema.fromJsonString(OrchestrationV2SubagentJsonSchema),
1210
);
1211
const encodeProviderSessionPayload = Schema.encodeEffect(
apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
+58
-2
@@ -3309,7 +3309,53 @@ const openSessionWithBackgroundCommand = (fixtureName: string) =>
3309
});
3310
});
3311
yield* Effect.forEach(Object.values(seededToolCalls), writeToolCall);
3312
+ // A background native subagent that outlived its completed run; Claude records no provider thread on it.
3313
+ const nativeSubagentRunId = idAllocator.derive.run({ threadId, ordinal: 1 });
3314
+ const nativeSubagentId = idAllocator.derive.nodeFromProviderItem({
3315
+ driver: CODEX_DRIVER,
3316
+ nativeItemId: "background-agent",
3317
+ });
3318
+ yield* eventSink.write({
3319
+ events: [
3320
+ {
3321
+ id: yield* idAllocator.allocate.event({ threadId }),
3322
+ type: "subagent.updated",
3323
+ threadId,
3324
+ occurredAt: now,
3325
+ payload: {
3326
+ id: nativeSubagentId,
3327
+ threadId,
3328
+ runId: nativeSubagentRunId,
3329
+ parentNodeId: idAllocator.derive.rootNode({ runId: nativeSubagentRunId }),
3330
+ origin: "provider_native",
3331
+ createdBy: "agent",
3332
+ driver: CODEX_DRIVER,
3333
+ providerInstanceId: modelSelection.instanceId,
3334
+ providerThreadId: null,
3335
+ childThreadId: null,
3336
+ nativeTaskRef: {
3337
+ driver: CODEX_DRIVER,
3338
+ nativeId: "background-agent",
3339
+ strength: "strong",
3340
+ },
3341
+ prompt: "sleep 150; echo done",
3342
+ title: "Background agent",
3343
+ model: null,
3344
+ status: "running",
3345
+ result: null,
3346
+ startedAt: now,
3347
+ completedAt: null,
3348
+ updatedAt: now,
3349
+ },
3350
+ },
3351
+ ],
3352
+ });
3353
yield* manager.open({ threadId, providerSessionId, modelSelection, runtimePolicy });
3354
+ const nativeSubagentStatus = Effect.gen(function* () {
3355
+ const projectionStore = yield* ProjectionStore.ProjectionStoreV2;
3356
+ const projection = yield* projectionStore.getThreadProjection(threadId);
3357
+ return projection.subagents.find((subagent) => subagent.id === nativeSubagentId)?.status;
3358
+ });
3359
const toolCallStatus = (id: OrchestrationV2TurnItem["id"]) =>
3360
Effect.gen(function* () {
3361
const projectionStore = yield* ProjectionStore.ProjectionStoreV2;
@@ -3345,6 +3391,7 @@ const openSessionWithBackgroundCommand = (fixtureName: string) =>
3391
writeToolCall,
3392
toolCalls,
3393
toolCallStatus,
3394
+ nativeSubagentStatus,
3395
};
3396
});
3397
@@ -3356,8 +3403,15 @@ it.effect.each(["detach", "stream failure", "provider stop", "early close"] as c
3403
const state = yield* Ref.make(emptyState);
3404
const effect = Effect.gen(function* () {
3405
const manager = yield* ProviderSessionManager.ProviderSessionManagerV2;
3359
- const { threadId, providerSessionId, rosters, toolCalls, seededToolCalls, writeToolCall } =
3360
- yield* openSessionWithBackgroundCommand("provider-session-manager-detach-roster");
3406
+ const {
3407
+ threadId,
3408
+ providerSessionId,
3409
+ rosters,
3410
+ toolCalls,
3411
+ seededToolCalls,
3412
+ writeToolCall,
3413
+ nativeSubagentStatus,
3414
+ } = yield* openSessionWithBackgroundCommand("provider-session-manager-detach-roster");
3415
const runtime = Option.getOrThrow(yield* manager.get(providerSessionId));
3416
const subscription = yield* runtime.subscribeEvents!;
3417
const consuming = yield* Deferred.make<void>();
@@ -3433,6 +3487,8 @@ it.effect.each(["detach", "stream failure", "provider stop", "early close"] as c
3487
otherSession: "running",
3488
replacement: "running",
3489
});
3490
+ // regression: #36548 a native subagent the dead process ran stayed running after its run completed
3491
+ assert.notInclude(["pending", "running", "waiting"], yield* nativeSubagentStatus);
3492
});
3493
3494
yield* effect.pipe(
apps/server/src/orchestration-v2/ProviderSessionManager.ts
+100
-2
@@ -59,6 +59,10 @@ import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
59
import * as ProviderEventIngestor from "./ProviderEventIngestor.ts";
60
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
61
import { makeProviderFailure } from "@t3tools/provider-core/server/failure";
62
+import {
63
+ endOrphanedNativeSubagent,
64
+ endRunlessRootTurns,
65
+} from "@t3tools/provider-core/server/subagentProjection";
66
import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts";
67
import * as ProjectionStore from "./ProjectionStore.ts";
68
@@ -995,7 +999,7 @@ export const layerWithOptions = (
999
1000
// Tool calls the dead process started never report an end either, and run finalization
1001
// keeps them open for a late result. Items started after the release belong to a
998
- // replacement session. Subagent rows are left out: run finalization ends run-owned ones.
1002
+ // replacement session.
1003
const writeReleasedToolCallEvents = Effect.fn(
1004
"ProviderSessionManager.writeReleasedToolCallEvents",
1005
)(function* (released: ReleasedProviderThread, releasedAt: DateTime.Utc) {
@@ -1047,6 +1051,96 @@ export const layerWithOptions = (
1051
});
1052
});
1053
1054
+ // Background native subagents die with the process too, often after their run completed,
1055
+ // so run finalization does not end them. One started or resumed after the release belongs
1056
+ // to a replacement session.
1057
+ const writeReleasedSubagentEvents = Effect.fn(
1058
+ "ProviderSessionManager.writeReleasedSubagentEvents",
1059
+ )(function* (released: ReleasedProviderThread, releasedAt: DateTime.Utc) {
1060
+ const { threadId, providerSessionId, providerThreadId, driver } = released;
1061
+ const readCutOff = Effect.gen(function* () {
1062
+ const { subagents, turnItems } = yield* projectionStore.getThreadRecords(
1063
+ threadId,
1064
+ ["subagents", "turnItems"],
1065
+ {
1066
+ omitSettledSubagents: true,
1067
+ turnItemTypes: ["subagent"],
1068
+ turnItemStatuses: activeTurnItemStatuses,
1069
+ },
1070
+ );
1071
+ const cutOff = subagents.filter((subagent) => {
1072
+ if (
1073
+ subagent.origin !== "provider_native" ||
1074
+ subagent.driver !== driver ||
1075
+ !isOrchestrationV2WorkActive(subagent.status) ||
1076
+ DateTime.isGreaterThan(subagent.startedAt ?? subagent.updatedAt, releasedAt)
1077
+ ) {
1078
+ return false;
1079
+ }
1080
+ // Record and item are written together; a record without a live item lost its end.
1081
+ const item = turnItems.find(
1082
+ (candidate) => candidate.type === "subagent" && candidate.subagentId === subagent.id,
1083
+ );
1084
+ return item === undefined || item.providerThreadId === providerThreadId;
1085
+ });
1086
+ return { subagents: cutOff, turnItems };
1087
+ });
1088
+ let pending = yield* readCutOff;
1089
+ for (let pass = 0; pass < 3 && pending.subagents.length > 0; pass++) {
1090
+ const { nodes } = yield* projectionStore.getThreadRecords(threadId, ["nodes"], {
1091
+ nodeIds: pending.subagents.map((subagent) => subagent.id),
1092
+ });
1093
+ const projection = { ...pending, nodes };
1094
+ for (const subagent of pending.subagents) {
1095
+ const now = yield* DateTime.now;
1096
+ const allocateEventId = () =>
1097
+ idAllocator.allocate.event({ threadId, providerSessionId });
1098
+ const events = yield* endOrphanedNativeSubagent({
1099
+ projection,
1100
+ subagentId: subagent.id,
1101
+ status: "interrupted",
1102
+ now,
1103
+ emitted: [],
1104
+ allocateEventId,
1105
+ });
1106
+ if (subagent.childThreadId !== null) {
1107
+ const child = yield* projectionStore
1108
+ .getThreadRecords(subagent.childThreadId, ["nodes", "providerTurns", "turnItems"], {
1109
+ turnItemRunIds: [null],
1110
+ turnItemStatuses: activeTurnItemStatuses,
1111
+ })
1112
+ .pipe(
1113
+ Effect.catchTags({
1114
+ ProjectionStoreThreadNotFoundError: () => Effect.succeed(null),
1115
+ }),
1116
+ );
1117
+ if (child !== null) {
1118
+ events.push(
1119
+ ...(yield* endRunlessRootTurns({
1120
+ threadId: subagent.childThreadId,
1121
+ providerInstanceId: subagent.providerInstanceId,
1122
+ projection: child,
1123
+ status: "interrupted",
1124
+ now,
1125
+ emitted: events,
1126
+ allocateEventId,
1127
+ })),
1128
+ );
1129
+ }
1130
+ }
1131
+ // A late update from the dead session's queued events or a resume rejects only this write.
1132
+ yield* eventSink.writeIfSubagentUnchanged({ expected: subagent, events });
1133
+ }
1134
+ pending = yield* readCutOff;
1135
+ }
1136
+ if (pending.subagents.length === 0) return;
1137
+ yield* Effect.logWarning("orchestration-v2.provider-session-release-subagent-conflict", {
1138
+ providerSessionId,
1139
+ providerThreadId,
1140
+ openSubagents: pending.subagents.length,
1141
+ });
1142
+ });
1143
+
1144
const writeReleasedBackgroundWorkEvents = (
1145
released: ReadonlyArray<ReleasedProviderThread>,
1146
releasedAt: DateTime.Utc,
@@ -1056,6 +1150,7 @@ export const layerWithOptions = (
1150
(providerThread) =>
1151
writeReleasedRosterEvents(providerThread).pipe(
1152
Effect.andThen(writeReleasedToolCallEvents(providerThread, releasedAt)),
1153
+ Effect.andThen(writeReleasedSubagentEvents(providerThread, releasedAt)),
1154
),
1155
{ discard: true },
1156
);
@@ -1269,7 +1364,10 @@ export const layerWithOptions = (
1364
// Queued events can persist tool calls after the release-time scan.
1365
const afterDrain = Effect.forEach(
1366
releasedProviderThreads,
1272
- (thread) => writeReleasedToolCallEvents(thread, releasedAt),
1367
+ (thread) =>
1368
+ writeReleasedToolCallEvents(thread, releasedAt).pipe(
1369
+ Effect.andThen(writeReleasedSubagentEvents(thread, releasedAt)),
1370
+ ),
1371
{ discard: true },
1372
).pipe(logReleaseFailure(input.providerSessionId));
1373
if (input.gracefulSubscribers === true) {