The best way to control Claude Code, Codex and more from any computer or phone
fix(server): stop jobs a Claude CLI moved out of its process group when the session closes (#34505)
Julius Marminge committed
Nov 11, 2026 at 16:00 UTC
fdd54b942d1f15495d1ee0337b7a873c0fd246e1
2 files changed
+178
-4
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+115
-4
@@ -146,6 +146,7 @@ import * as Effect from "effect/Effect";
146
import * as Equal from "effect/Equal";
147
import * as Exit from "effect/Exit";
148
import * as Fiber from "effect/Fiber";
149
+import * as Schedule from "effect/Schedule";
150
import * as FileSystem from "effect/FileSystem";
151
import * as Layer from "effect/Layer";
152
import * as Option from "effect/Option";
@@ -178,6 +179,7 @@ import {
179
} from "../../claudeModelOptions.ts";
180
import * as ServerConfig from "../../config.ts";
181
import * as PortScanner from "../../preview/PortScanner.ts";
182
+import * as ProcessRunner from "../../processRunner.ts";
183
import * as ServerSettings from "../../serverSettings.ts";
184
import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
185
import { spawnAndCollect } from "@t3tools/provider-core/server/snapshotProbe";
@@ -360,6 +362,8 @@ const CLAUDE_STOP_CONFIRM_TIMEOUT_MS = 10_000;
362
const CLAUDE_STDERR_TAIL_LENGTH = 2_048;
363
// The process group is killed on exit, so its stderr closes promptly.
364
const CLAUDE_STDERR_DRAIN_TIMEOUT = Duration.seconds(1);
365
+// How often the CLI's process tree is recorded when no agent scope will stop what it leaves.
366
+const CLAUDE_DESCENDANT_POLL = "1 second";
367
// Claude Code's refusal of bypassPermissions as root, which it explains only on stderr.
368
const CLAUDE_ROOT_REFUSAL =
369
"--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons";
@@ -379,7 +383,7 @@ export function spawnClaudeProcessGroup(
383
onExit?: () => void,
384
onStderr: (text: string) => void = () => {},
385
onStderrClose: () => void = () => {},
382
-): ClaudeSpawnedProcess {
386
+): ClaudeSpawnedProcess & Pick<NodeChildProcess.ChildProcess, "pid"> {
387
const child = NodeChildProcess.spawn(
388
"/bin/sh",
389
["-c", CLAUDE_GROUP_WATCH_SCRIPT, "t3-claude", options.command, ...options.args],
@@ -400,7 +404,60 @@ export function spawnClaudeProcessGroup(
404
onExit?.();
405
});
406
// Node's typings make stdin and stdout nullable once stdio has a fourth entry; both are pipes.
403
- return child as ClaudeSpawnedProcess;
407
+ return child as ClaudeSpawnedProcess & Pick<NodeChildProcess.ChildProcess, "pid">;
408
+}
409
+
410
+interface ClaudeProcessRow {
411
+ readonly pid: number;
412
+ readonly ppid: number;
413
+ readonly pgid: number;
414
+ readonly started: string;
415
+}
416
+
417
+/** Parses `ps -A -o pid=,ppid=,pgid=,lstart=`; pid plus start time tells a process from a reused pid. */
418
+function parseClaudeProcessTable(table: string): ReadonlyArray<ClaudeProcessRow> {
419
+ return table.split("\n").flatMap((line) => {
420
+ const [pid, ppid, pgid, ...started] = line.trim().split(/\s+/);
421
+ const row = {
422
+ pid: Number(pid),
423
+ ppid: Number(ppid),
424
+ pgid: Number(pgid),
425
+ started: started.join(" "),
426
+ };
427
+ return Number.isSafeInteger(row.pid) &&
428
+ Number.isSafeInteger(row.ppid) &&
429
+ Number.isSafeInteger(row.pgid) &&
430
+ row.started
431
+ ? [row]
432
+ : [];
433
+ });
434
+}
435
+
436
+// A job leading its own group takes the processes it started since with it.
437
+function killClaudeDescendant(row: ClaudeProcessRow) {
438
+ try {
439
+ if (row.pgid === row.pid) signalProcessGroup(row.pid, "SIGKILL");
440
+ else process.kill(row.pid, "SIGKILL");
441
+ } catch {}
442
+}
443
+
444
+function claudeDescendants(
445
+ rows: ReadonlyArray<ClaudeProcessRow>,
446
+ rootPids: ReadonlyArray<number>,
447
+): ReadonlyArray<ClaudeProcessRow> {
448
+ const children = Map.groupBy(rows, (row) => row.ppid);
449
+ const found: Array<ClaudeProcessRow> = [];
450
+ const seen = new Set<number>(rootPids);
451
+ const pending = [...rootPids];
452
+ for (let parent = pending.pop(); parent !== undefined; parent = pending.pop()) {
453
+ for (const child of children.get(parent) ?? []) {
454
+ if (seen.has(child.pid)) continue;
455
+ seen.add(child.pid);
456
+ found.push(child);
457
+ pending.push(child.pid);
458
+ }
459
+ }
460
+ return found;
461
}
462
463
export const ClaudeProviderCapabilitiesV2 = {
@@ -1195,6 +1252,41 @@ export const layerQueryRunner: Layer.Layer<
1252
const runFork = Effect.runForkWith(yield* Effect.context<never>());
1253
const hostEnvironment = yield* HostProcess.Environment;
1254
const portDiscovery = yield* PortScanner.PortDiscovery;
1255
+ const processRunner = yield* ProcessRunner.make();
1256
+ const readProcessTable = processRunner
1257
+ .run({ command: "ps", args: ["-A", "-o", "pid=,ppid=,pgid=,lstart="], timeout: "5 seconds" })
1258
+ .pipe(
1259
+ Effect.map((result) => (result.code === 0 ? parseClaudeProcessTable(result.stdout) : [])),
1260
+ Effect.orElseSucceed(() => []),
1261
+ );
1262
+ // Without an agent scope, a job that left the CLI's group escapes the group kill and is
1263
+ // re-parented once the CLI exits. So the CLI's tree is recorded while it runs, and what is
1264
+ // still the same process (pid and start time) is stopped after it exits.
1265
+ const trackDescendants = (cliPid: number) => {
1266
+ const tracked = new Map<string, ClaudeProcessRow>();
1267
+ const identity = (row: ClaudeProcessRow) => `${row.pid} ${row.started}`;
1268
+ // After exit the CLI's pid may belong to an unrelated process, so only tracked jobs are roots.
1269
+ const refresh = Effect.fn("ClaudeAgentSdkQueryRunner.trackDescendants")(function* (
1270
+ cliRunning: boolean,
1271
+ ) {
1272
+ const rows = yield* readProcessTable;
1273
+ const running = new Set(rows.map(identity));
1274
+ const roots = [
1275
+ ...(cliRunning ? [cliPid] : []),
1276
+ ...[...tracked.values()].flatMap((row) => (running.has(identity(row)) ? [row.pid] : [])),
1277
+ ];
1278
+ for (const row of claudeDescendants(rows, roots)) tracked.set(identity(row), row);
1279
+ return running;
1280
+ });
1281
+ const stop = refresh(false).pipe(
1282
+ Effect.map((running) => {
1283
+ for (const row of tracked.values()) {
1284
+ if (running.has(identity(row))) killClaudeDescendant(row);
1285
+ }
1286
+ }),
1287
+ );
1288
+ return { refresh: refresh(true).pipe(Effect.asVoid), stop };
1289
+ };
1290
1291
return ClaudeAgentSdkQueryRunner.of({
1292
allocateSessionId: random.uuidV4(),
@@ -1259,6 +1351,7 @@ export const layerQueryRunner: Layer.Layer<
1351
if (answered) return;
1352
stderrTail = (stderrTail + text).slice(-CLAUDE_STDERR_TAIL_LENGTH);
1353
};
1354
+ let refreshDescendants: Effect.Effect<void> = Effect.void;
1355
const spawnProcess =
1356
options.spawnClaudeCodeProcess ??
1357
((spawnOptions: ClaudeSpawnOptions) => {
@@ -1266,7 +1359,23 @@ export const layerQueryRunner: Layer.Layer<
1359
// Node can report "exit" before it has read the stderr the CLI wrote.
1360
let stderrDone = () => {};
1361
stderrClosed = new Promise((resolve) => (stderrDone = resolve));
1269
- return spawnClaudeProcessGroup(spawnOptions, stopScope, appendStderr, stderrDone);
1362
+ const child = spawnClaudeProcessGroup(
1363
+ spawnOptions,
1364
+ stopScope,
1365
+ appendStderr,
1366
+ stderrDone,
1367
+ );
1368
+ if (unit === undefined && child.pid !== undefined) {
1369
+ const tracker = trackDescendants(child.pid);
1370
+ const polling = runFork(
1371
+ tracker.refresh.pipe(Effect.repeat(Schedule.spaced(CLAUDE_DESCENDANT_POLL))),
1372
+ );
1373
+ child.once("exit", () =>
1374
+ runFork(Fiber.interrupt(polling).pipe(Effect.andThen(tracker.stop))),
1375
+ );
1376
+ refreshDescendants = tracker.refresh;
1377
+ }
1378
+ return child;
1379
}
1380
const child = NodeChildProcess.spawn(spawnOptions.command, spawnOptions.args, {
1381
cwd: spawnOptions.cwd,
@@ -1573,7 +1682,9 @@ export const layerQueryRunner: Layer.Layer<
1682
}),
1683
),
1684
),
1576
- close: Queue.shutdown(promptQueue).pipe(
1685
+ // A job started since the last poll is recorded before the CLI is told to exit.
1686
+ close: Effect.suspend(() => (processExited ? Effect.void : refreshDescendants)).pipe(
1687
+ Effect.andThen(Queue.shutdown(promptQueue)),
1688
Effect.andThen(closeClaudeQuery(queryRuntime)),
1689
Effect.tap(() =>
1690
logProtocolEvent({
apps/server/src/orchestration-v2/Adapters/ClaudeAgentSdkQueryRunner.test.ts
+63
@@ -633,6 +633,69 @@ describe.skipIf(HostProcess.Platform.defaultValue() === "win32")("Claude CLI pro
633
}),
634
);
635
636
+ // The default AgentScope is what macOS gets: no systemd scope to catch a job outside the CLI's group.
637
+ it.effect("stops a job the CLI started in its own process group when the session closes", () =>
638
+ Effect.gen(function* () {
639
+ const cli = fakeClaudeCli(
640
+ [
641
+ 'dir=$(dirname "$0")',
642
+ `perl -e 'setpgrp(0, 0); exec @ARGV' sleep 600 > "$dir/alive" &`,
643
+ 'echo $! > "$dir/leftover.pid"',
644
+ "cat > /dev/null",
645
+ ].join("\n"),
646
+ );
647
+ const dir = NodePath.dirname(cli);
648
+ NodeChildProcess.execFileSync("mkfifo", [NodePath.join(dir, "alive")]);
649
+ yield* Effect.addFinalizer(() =>
650
+ Effect.sync(() => {
651
+ try {
652
+ process.kill(Number(NodeFS.readFileSync(NodePath.join(dir, "leftover.pid"), "utf8")));
653
+ } catch {}
654
+ NodeFS.rmSync(dir, { recursive: true, force: true });
655
+ }),
656
+ );
657
+ const alive = NodeFS.createReadStream(NodePath.join(dir, "alive"));
658
+ const leftoverStarted = new Promise<void>((resolve) => alive.once("open", () => resolve()));
659
+ const leftoverStopped = new Promise<void>((resolve) => alive.once("close", () => resolve()));
660
+ alive.resume();
661
+
662
+ const session = yield* openFakeCli(cli).pipe(Effect.provide(realQueryRunner));
663
+ yield* Effect.promise(() => leftoverStarted);
664
+ yield* session.close;
665
+ yield* Effect.promise(() => leftoverStopped);
666
+ }),
667
+ );
668
+
669
+ // Live clock: the job is found by polling while the CLI runs, and the CLI exits on its own.
670
+ it.live("stops a job the CLI started in its own process group when the CLI exits", () =>
671
+ Effect.gen(function* () {
672
+ const cli = fakeClaudeCli(
673
+ [
674
+ 'dir=$(dirname "$0")',
675
+ `perl -e 'setpgrp(0, 0); exec @ARGV' sleep 600 > "$dir/alive" &`,
676
+ 'echo $! > "$dir/leftover.pid"',
677
+ "sleep 3",
678
+ ].join("\n"),
679
+ );
680
+ const dir = NodePath.dirname(cli);
681
+ NodeChildProcess.execFileSync("mkfifo", [NodePath.join(dir, "alive")]);
682
+ yield* Effect.addFinalizer(() =>
683
+ Effect.sync(() => {
684
+ try {
685
+ process.kill(Number(NodeFS.readFileSync(NodePath.join(dir, "leftover.pid"), "utf8")));
686
+ } catch {}
687
+ NodeFS.rmSync(dir, { recursive: true, force: true });
688
+ }),
689
+ );
690
+ const alive = NodeFS.createReadStream(NodePath.join(dir, "alive"));
691
+ const leftoverStopped = new Promise<void>((resolve) => alive.once("close", () => resolve()));
692
+ alive.resume();
693
+
694
+ yield* openFakeCli(cli).pipe(Effect.provide(realQueryRunner));
695
+ yield* Effect.promise(() => leftoverStopped);
696
+ }),
697
+ );
698
+
699
const rootRefusal =
700
"--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons";
701