@devries-cameron20 / t3code Mirror · read-only / commits / fdd54b942d
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 21:00 UTC

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