@devries-cameron20 / t3code-1 / commits / b60abf32e0
Fork 0

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

perf(server): Windows process launches no longer block the RPC thread (#32260)

Co-authored-by: Lakshmi Tanmay <lakshmi@voltcrash.com> Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>

Dara Adedeji committed Nov 14, 2026 at 16:11 UTC b60abf32e0b8247b2a425f8065be77352a3b86e4
9 files changed +833 -16
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+2 -2
@@ -83,6 +83,7 @@ import {
83 } from "@t3tools/shared/mcpApp";
84 import { AgentScope } from "@t3tools/shared/AgentScope";
85 import * as ProviderProcesses from "../../process/providerProcesses.ts";
86 +import * as SpawnWorker from "../../process/SpawnWorker.ts";
87 import * as HostProcess from "@t3tools/shared/HostProcess";
88 import { applyClaudePromptEffortPrefix } from "@t3tools/shared/model";
89 import { compareSemverVersions } from "@t3tools/shared/semver";
@@ -1524,12 +1525,11 @@ export const layerQueryRunner: Layer.Layer<
1525 }
1526 return child;
1527 }
1527 - const child = NodeChildProcess.spawn(spawnOptions.command, spawnOptions.args, {
1528 + const child = SpawnWorker.spawnPiped(spawnOptions.command, spawnOptions.args, {
1529 cwd: spawnOptions.cwd,
1530 env: spawnOptions.env,
1531 signal: spawnOptions.signal,
1532 windowsHide: true,
1532 - stdio: ["pipe", "pipe", "pipe"],
1533 });
1534 child.stderr
1535 .setEncoding("utf8")
apps/server/src/process/SpawnWorker.test.ts new
+163
@@ -0,0 +1,163 @@
1 +// @effect-diagnostics nodeBuiltinImport:off processEnvInEffect:off - fixtures need real paths, the process resource list and the live environment.
2 +import * as NodeOS from "node:os";
3 +import * as NodePath from "node:path";
4 +import * as NodeServices from "@effect/platform-node/NodeServices";
5 +import { describe, expect, it } from "@effect/vitest";
6 +import * as Deferred from "effect/Deferred";
7 +import * as Effect from "effect/Effect";
8 +import * as Fiber from "effect/Fiber";
9 +import * as Layer from "effect/Layer";
10 +import * as Result from "effect/Result";
11 +import * as Stream from "effect/Stream";
12 +import * as ChildProcess from "effect/process/ChildProcess";
13 +import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
14 +import * as HostProcess from "@t3tools/shared/HostProcess";
15 +
16 +import * as SpawnWorker from "./SpawnWorker.ts";
17 +
18 +const layer = SpawnWorker.layer.pipe(Layer.provide(NodeServices.layer));
19 +const text = <E>(stream: Stream.Stream<Uint8Array, E>) =>
20 + stream.pipe(Stream.decodeText(), Stream.mkString);
21 +const node = (script: string, args: ReadonlyArray<string> = [], options = {}) =>
22 + ChildProcess.make(process.execPath, ["-e", script, ...args], options);
23 +
24 +describe("SpawnWorker", () => {
25 + it.live("runs the server's Windows children on a launcher thread, not the server thread", () =>
26 + Effect.gen(function* () {
27 + for (const [platform, onServerThread] of [
28 + ["win32", false],
29 + ["linux", true],
30 + ] as const) {
31 + const launched = Effect.gen(function* () {
32 + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
33 + const child = yield* spawner.spawn(
34 + node("process.stdout.write('ready');process.stdin.resume()"),
35 + );
36 + expect(yield* child.stdout.pipe(Stream.take(1), text)).toBe("ready");
37 + // The thread that called spawn owns the native process handle.
38 + expect(process.getActiveResourcesInfo().includes("ProcessWrap")).toBe(onServerThread);
39 + expect(yield* child.isRunning).toBe(true);
40 + });
41 + yield* launched.pipe(
42 + Effect.scoped,
43 + Effect.provide(SpawnWorker.layerServer.pipe(Layer.provide(NodeServices.layer))),
44 + Effect.provideService(HostProcess.Platform, platform),
45 + );
46 + }
47 + }),
48 + );
49 +
50 + it.live("preserves stdin, large output, env, cwd, literal args and additional descriptors", () =>
51 + Effect.gen(function* () {
52 + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
53 + const literal = "quote' \" $HOME; * & %PATH%";
54 + const cwd = NodeOS.tmpdir();
55 + const script = `
56 + const fs = require('node:fs');
57 + const input = fs.readFileSync(0, 'utf8');
58 + fs.writeSync(1, JSON.stringify([input, process.cwd(), process.env.SPAWN_WORKER_TEST, process.argv[1]]) + '\\n');
59 + fs.writeSync(1, 'a'.repeat(1024 * 1024));
60 + fs.writeSync(2, 'b'.repeat(1024 * 1024));
61 + `;
62 + for (let i = 0; i < 3; i++) {
63 + const child = yield* spawner.spawn(
64 + node(script, [literal], {
65 + cwd,
66 + env: { SPAWN_WORKER_TEST: "inherited value" },
67 + extendEnv: true,
68 + stdin: Stream.encodeText(Stream.make("stdin value")),
69 + }),
70 + );
71 + const [stdout, stderr, code] = yield* Effect.all(
72 + [text(child.stdout), text(child.stderr), child.exitCode],
73 + { concurrency: "unbounded" },
74 + );
75 + expect(stdout).toBe(
76 + JSON.stringify(["stdin value", NodePath.resolve(cwd), "inherited value", literal]) +
77 + "\n" +
78 + "a".repeat(1024 * 1024),
79 + );
80 + expect(stderr).toBe("b".repeat(1024 * 1024));
81 + expect(code).toBe(0);
82 + }
83 + // The launcher threads already exist, so this needs the server's environment at launch time.
84 + process.env.SPAWN_WORKER_LATE = "set after start";
85 + const late = yield* spawner.spawn(
86 + node("process.stdout.write(process.env.SPAWN_WORKER_LATE)"),
87 + );
88 + expect(yield* text(late.stdout)).toBe("set after start");
89 + delete process.env.SPAWN_WORKER_LATE;
90 + const extra = yield* spawner.spawn(
91 + node("require('node:fs').writeSync(3, 'fd3 value')", [], {
92 + additionalFds: { fd3: { type: "output" } },
93 + }),
94 + );
95 + const [fd3, extraCode] = yield* Effect.all([text(extra.getOutputFd(3)), extra.exitCode], {
96 + concurrency: "unbounded",
97 + });
98 + expect(fd3).toBe("fd3 value");
99 + expect(extraCode).toBe(0);
100 + const reader = yield* spawner.spawn(
101 + node("process.stdin.on('end', () => process.stdout.write('eof')).resume()"),
102 + );
103 + yield* Stream.fail("abandoned input").pipe(Stream.run(reader.stdin), Effect.ignore);
104 + expect(yield* text(reader.stdout)).toBe("eof");
105 + const pipeline = node("process.stdout.write('piped')").pipe(
106 + ChildProcess.pipeTo(
107 + node("process.stdin.on('data', (d) => process.stdout.write(String(d).toUpperCase()))"),
108 + ),
109 + );
110 + const piped = yield* spawner.spawn(pipeline);
111 + expect(yield* text(piped.stdout)).toBe("PIPED");
112 + expect(yield* piped.exitCode).toBe(0);
113 + }).pipe(Effect.scoped, Effect.provide(layer)),
114 + );
115 +
116 + it.live("reports launch errors and exit codes, and keeps launching after either", () =>
117 + Effect.gen(function* () {
118 + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
119 + const missing = yield* spawner
120 + .spawn(ChildProcess.make("t3-missing-command-25245"))
121 + .pipe(Effect.result);
122 + expect(Result.isFailure(missing)).toBe(true);
123 + if (Result.isFailure(missing)) expect(missing.failure.reason._tag).toBe("NotFound");
124 + const failed = yield* spawner.spawn(node("process.exit(23)"));
125 + expect(yield* failed.exitCode).toBe(23);
126 + const healthy = yield* spawner.spawn(node("process.stdout.write('ok')"));
127 + expect(yield* text(healthy.stdout)).toBe("ok");
128 + expect(yield* healthy.exitCode).toBe(0);
129 + }).pipe(Effect.scoped, Effect.provide(layer)),
130 + );
131 +
132 + it.live("kills running commands, detached or not, and on scope interruption", () =>
133 + Effect.gen(function* () {
134 + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
135 + for (const detached of [true, false]) {
136 + const child = yield* spawner.spawn(
137 + node("process.stdout.write(String(process.pid));process.stdin.resume()", [], {
138 + detached,
139 + }),
140 + );
141 + const pid = yield* child.stdout.pipe(Stream.take(1), text);
142 + expect(Number(pid)).toBe(child.pid);
143 + yield* child.kill();
144 + expect(yield* child.isRunning).toBe(false);
145 + }
146 + const started = yield* Deferred.make<ChildProcessSpawner.ChildProcessHandle>();
147 + const running = yield* Effect.gen(function* () {
148 + const scoped = yield* spawner.spawn(node("process.stdin.resume()"));
149 + yield* Deferred.succeed(started, scoped);
150 + return yield* Effect.never;
151 + }).pipe(Effect.scoped, Effect.forkChild);
152 + const scoped = yield* Deferred.await(started);
153 + yield* Fiber.interrupt(running);
154 + expect(yield* scoped.isRunning).toBe(false);
155 + // Direct callers such as the Claude adapter pass an AbortSignal, which cannot cross to a worker.
156 + const direct = SpawnWorker.spawnPiped(process.execPath, ["-e", "process.stdin.resume()"], {
157 + signal: AbortSignal.abort(),
158 + });
159 + const exited = new Promise((resolve) => direct.once("exit", () => resolve(direct.killed)));
160 + expect(yield* Effect.promise(() => exited)).toBe(true);
161 + }).pipe(Effect.scoped, Effect.provide(layer)),
162 + );
163 +});
apps/server/src/process/SpawnWorker.ts new
+536
@@ -0,0 +1,536 @@
1 +// @effect-diagnostics nodeBuiltinImport:off - worker threads and Node streams implement the platform spawner boundary.
2 +import * as NodeEvents from "node:events";
3 +import type * as NodeChildProcess from "node:child_process";
4 +import * as NodeStream from "node:stream";
5 +import * as NodeWorkerThreads from "node:worker_threads";
6 +import * as NodeChildProcessSpawner from "@effect/platform-node-shared/NodeChildProcessSpawner";
7 +import * as Effect from "effect/Effect";
8 +import * as Layer from "effect/Layer";
9 +import * as HostProcess from "@t3tools/shared/HostProcess";
10 +
11 +// Windows runs CreateProcess synchronously on the calling thread, and antivirus or a busy disk can
12 +// hold it for seconds. Workers own the children, so only the worker waits.
13 +const MAX_WORKERS = 4;
14 +const MAX_IDLE_WORKERS = 1;
15 +
16 +type ToWorker =
17 + | {
18 + readonly type: "spawn";
19 + readonly id: number;
20 + readonly command: string;
21 + readonly args: ReadonlyArray<string>;
22 + readonly options: NodeChildProcess.SpawnOptions;
23 + }
24 + | { readonly type: "write"; readonly id: number; readonly fd: number; readonly data: Uint8Array }
25 + | { readonly type: "end"; readonly id: number; readonly fd: number }
26 + | { readonly type: "flow"; readonly id: number; readonly fd: number; readonly paused: boolean }
27 + | { readonly type: "destroy"; readonly id: number; readonly fd: number }
28 + | { readonly type: "kill"; readonly id: number; readonly signal: NodeJS.Signals | number };
29 +
30 +interface SerializedError {
31 + readonly message: string;
32 + readonly [key: string]: unknown;
33 +}
34 +
35 +type FromWorker =
36 + | { readonly type: "spawn"; readonly id: number; readonly pid: number | undefined }
37 + | { readonly type: "error"; readonly id: number; readonly error: SerializedError }
38 + | { readonly type: "data"; readonly id: number; readonly fd: number; readonly data: Uint8Array }
39 + | {
40 + readonly type: "written";
41 + readonly id: number;
42 + readonly fd: number;
43 + readonly error?: SerializedError;
44 + }
45 + | { readonly type: "eof"; readonly id: number; readonly fd: number }
46 + | { readonly type: "finished"; readonly id: number; readonly fd: number }
47 + | {
48 + readonly type: "stream-error";
49 + readonly id: number;
50 + readonly fd: number;
51 + readonly error: SerializedError;
52 + }
53 + | {
54 + readonly type: "exit";
55 + readonly id: number;
56 + readonly code: number | null;
57 + readonly signal: NodeJS.Signals | null;
58 + }
59 + | { readonly type: "close"; readonly id: number };
60 +
61 +// Inline source runs from bundles, asar archives and single-executable builds without module files.
62 +const workerSource = `
63 +const { parentPort } = require("node:worker_threads");
64 +const { spawn } = require("node:child_process");
65 +const children = new Map();
66 +const post = (message, transfer) => parentPort.postMessage(message, transfer);
67 +const serialize = (error) => {
68 + const out = { message: String(error && error.message) };
69 + for (const key of ["code", "errno", "syscall", "path", "spawnargs"]) {
70 + if (error && error[key] !== undefined) out[key] = error[key];
71 + }
72 + return out;
73 +};
74 +parentPort.on("message", (request) => {
75 + const { id } = request;
76 + if (request.type === "spawn") {
77 + let child;
78 + try {
79 + child = spawn(request.command, request.args, request.options);
80 + } catch (error) {
81 + post({ type: "error", id, error: serialize(error) });
82 + return;
83 + }
84 + children.set(id, child);
85 + child.on("spawn", () => post({ type: "spawn", id, pid: child.pid }));
86 + child.on("error", (error) => post({ type: "error", id, error: serialize(error) }));
87 + child.on("exit", (code, signal) => post({ type: "exit", id, code, signal }));
88 + // Output can still arrive after exit; close follows the last of it.
89 + child.on("close", () => {
90 + children.delete(id);
91 + post({ type: "close", id });
92 + });
93 + child.stdio?.forEach((stream, fd) => {
94 + if (!stream) return;
95 + stream.on("error", (error) => post({ type: "stream-error", id, fd, error: serialize(error) }));
96 + if (fd === 0) return;
97 + // Cloning a Buffer copies its whole backing store; copy the bytes once and transfer them.
98 + stream.on("data", (chunk) => {
99 + const data = new Uint8Array(chunk);
100 + post({ type: "data", id, fd, data }, [data.buffer]);
101 + });
102 + stream.on("end", () => post({ type: "eof", id, fd }));
103 + });
104 + return;
105 + }
106 + const child = children.get(id);
107 + if (child === undefined) {
108 + if (request.type === "write") post({ type: "written", id, fd: request.fd, error: { message: "write after exit", code: "EPIPE" } });
109 + if (request.type === "end") post({ type: "finished", id, fd: request.fd });
110 + return;
111 + }
112 + const stream = child.stdio?.[request.fd];
113 + switch (request.type) {
114 + case "write":
115 + if (!stream || stream.destroyed) {
116 + post({ type: "written", id, fd: request.fd, error: { message: "write after end", code: "EPIPE" } });
117 + return;
118 + }
119 + try {
120 + stream.write(request.data, (error) => post({ type: "written", id, fd: request.fd, error: error ? serialize(error) : undefined }));
121 + } catch (error) {
122 + post({ type: "written", id, fd: request.fd, error: serialize(error) });
123 + }
124 + return;
125 + case "end":
126 + if (!stream || stream.destroyed || stream.writableFinished) post({ type: "finished", id, fd: request.fd });
127 + else stream.end(() => post({ type: "finished", id, fd: request.fd }));
128 + return;
129 + case "flow":
130 + if (request.paused) stream?.pause();
131 + else stream?.resume();
132 + return;
133 + case "destroy":
134 + stream?.destroy();
135 + return;
136 + case "kill":
137 + try {
138 + child.kill(request.signal);
139 + } catch {}
140 + return;
141 + }
142 +});
143 +`;
144 +
145 +const toError = (serialized: SerializedError) =>
146 + Object.assign(new Error(serialized.message), serialized);
147 +
148 +const toBuffer = (data: Uint8Array) => Buffer.from(data.buffer, data.byteOffset, data.byteLength);
149 +
150 +class WorkerChild
151 + extends NodeEvents.EventEmitter
152 + implements NodeChildProcessSpawner.SpawnedChildProcess
153 +{
154 + pid: number | undefined;
155 + exitCode: number | null = null;
156 + signalCode: NodeJS.Signals | null = null;
157 + stdin: NodeStream.Writable | null = null;
158 + stdout: NodeStream.Readable | null = null;
159 + stderr: NodeStream.Readable | null = null;
160 + readonly stdio: Array<NodeStream.Readable | NodeStream.Writable | null | undefined> = [];
161 + referenced = true;
162 + killed = false;
163 + spawned = false;
164 + exited = false;
165 + readonly #writes = new Map<number, Array<(error?: Error | null) => void>>();
166 + readonly #finals = new Map<number, (error?: Error | null) => void>();
167 + readonly #paused = new Set<number>();
168 +
169 + readonly worker: SpawnWorker;
170 + readonly id: number;
171 +
172 + constructor(worker: SpawnWorker, id: number, stdio: ReadonlyArray<unknown>) {
173 + super();
174 + this.worker = worker;
175 + this.id = id;
176 + stdio.forEach((option, fd) => {
177 + if (option !== "pipe" && option !== "overlapped") return;
178 + const stream = this.#relay(fd);
179 + this.stdio[fd] = stream;
180 + if (fd === 0) this.stdin = stream as NodeStream.Writable;
181 + else if (fd === 1) this.stdout = stream as NodeStream.Readable;
182 + else if (fd === 2) this.stderr = stream as NodeStream.Readable;
183 + });
184 + }
185 +
186 + #relay(fd: number): NodeStream.Readable | NodeStream.Writable {
187 + const read = () => {
188 + if (this.#paused.delete(fd))
189 + this.worker.post({ type: "flow", id: this.id, fd, paused: false });
190 + };
191 + const write = (
192 + chunk: Buffer,
193 + _encoding: BufferEncoding,
194 + callback: (error?: Error | null) => void,
195 + ) => {
196 + if (this.worker.closed) {
197 + callback(Object.assign(new Error("write EPIPE"), { code: "EPIPE" }));
198 + return;
199 + }
200 + const pending = this.#writes.get(fd) ?? [];
201 + pending.push(callback);
202 + this.#writes.set(fd, pending);
203 + const data = new Uint8Array(chunk);
204 + this.worker.post({ type: "write", id: this.id, fd, data }, [data.buffer]);
205 + };
206 + const final = (callback: (error?: Error | null) => void) => {
207 + this.#finals.set(fd, callback);
208 + this.worker.post({ type: "end", id: this.id, fd });
209 + };
210 + // A caller that destroys its end closes the child pipe, as it would with a real pipe.
211 + const destroy = (error: Error | null, callback: (error?: Error | null) => void) => {
212 + if (!this.exited) this.worker.post({ type: "destroy", id: this.id, fd });
213 + callback(error);
214 + };
215 + if (fd === 0) return new NodeStream.Writable({ write, final, destroy });
216 + if (fd <= 2) return new NodeStream.Readable({ read, destroy });
217 + return new NodeStream.Duplex({ read, write, final, destroy, allowHalfOpen: true });
218 + }
219 +
220 + onData(fd: number, data: Uint8Array): void {
221 + const stream = this.stdio[fd];
222 + if (!stream || !("push" in stream)) return;
223 + if (!stream.push(toBuffer(data)) && !this.#paused.has(fd)) {
224 + this.#paused.add(fd);
225 + this.worker.post({ type: "flow", id: this.id, fd, paused: true });
226 + }
227 + }
228 +
229 + onEof(fd: number): void {
230 + const stream = this.stdio[fd];
231 + if (stream && "push" in stream) stream.push(null);
232 + }
233 +
234 + onFinished(fd: number): void {
235 + const callback = this.#finals.get(fd);
236 + this.#finals.delete(fd);
237 + callback?.();
238 + }
239 +
240 + onWritten(fd: number, error: SerializedError | undefined): void {
241 + const callback = this.#writes.get(fd)?.shift();
242 + callback?.(error === undefined ? null : toError(error));
243 + }
244 +
245 + onStreamError(fd: number, error: SerializedError): void {
246 + this.stdio[fd]?.destroy(toError(error));
247 + }
248 +
249 + kill(signal: NodeJS.Signals | number = "SIGTERM"): boolean {
250 + if (this.exited) return false;
251 + this.killed = true;
252 + this.worker.post({ type: "kill", id: this.id, signal });
253 + return true;
254 + }
255 +
256 + ref(): void {
257 + this.referenced = true;
258 + this.worker.syncRef();
259 + }
260 +
261 + unref(): void {
262 + this.referenced = false;
263 + this.worker.syncRef();
264 + }
265 +
266 + exit(code: number | null, signal: NodeJS.Signals | null): void {
267 + if (this.exited) return;
268 + this.exited = true;
269 + this.exitCode = code;
270 + this.signalCode = signal;
271 + // Node destroys stdin on exit; the Effect sink may already have removed its error listener.
272 + this.stdin?.on("error", () => {});
273 + this.stdin?.destroy();
274 + this.emit("exit", code, signal);
275 + }
276 +
277 + /** The worker is gone: end output so readers finish, and let the exit report the kill. */
278 + abandon(): void {
279 + // Not destroy(error): Effect leaves an unread stderr's pipe without an error listener.
280 + for (const stream of this.stdio) {
281 + if (stream && "push" in stream && !stream.readableEnded) stream.push(null);
282 + else if (stream && !("push" in stream)) stream.destroy();
283 + }
284 + }
285 +}
286 +
287 +class SpawnWorker {
288 + readonly worker: NodeWorkerThreads.Worker;
289 + readonly children = new Map<number, WorkerChild>();
290 + readonly pool: SpawnWorkerPool;
291 + /** Launches sent but not yet answered; the worker is inside CreateProcess for one of them. */
292 + launching = 0;
293 + closed = false;
294 +
295 + constructor(pool: SpawnWorkerPool) {
296 + this.pool = pool;
297 + this.worker = new NodeWorkerThreads.Worker(workerSource, { eval: true });
298 + this.worker.on("message", (message: FromWorker) => this.onMessage(message));
299 + this.worker.on("error", (error) => this.fail(error));
300 + this.worker.on("exit", () => this.fail(new Error("The process launcher thread exited.")));
301 + this.worker.unref();
302 + }
303 +
304 + post(message: ToWorker, transfer?: ReadonlyArray<ArrayBuffer>): void {
305 + if (!this.closed) this.worker.postMessage(message, transfer);
306 + }
307 +
308 + spawn(
309 + id: number,
310 + command: string,
311 + args: ReadonlyArray<string>,
312 + options: NodeChildProcess.SpawnOptions,
313 + ): WorkerChild {
314 + const io = options.stdio;
315 + const stdio =
316 + typeof io === "string" || io === undefined ? [io ?? "pipe", io ?? "pipe", io ?? "pipe"] : io;
317 + const child = new WorkerChild(this, id, stdio);
318 + // An AbortSignal cannot cross to the worker, so this thread kills on abort as Node would.
319 + const { signal, ...rest } = options;
320 + if (signal !== undefined) {
321 + const abort = () => child.kill();
322 + if (signal.aborted) queueMicrotask(abort);
323 + else {
324 + signal.addEventListener("abort", abort, { once: true });
325 + child.once("exit", () => signal.removeEventListener("abort", abort));
326 + }
327 + }
328 + this.children.set(id, child);
329 + this.launching++;
330 + this.syncRef();
331 + this.post({
332 + type: "spawn",
333 + id,
334 + command,
335 + args: [...args],
336 + // A worker's process.env is a copy from when it started; children get the server's current one.
337 + options: { ...rest, stdio, env: rest.env ?? { ...process.env } },
338 + });
339 + return child;
340 + }
341 +
342 + syncRef(): void {
343 + if (this.closed) return;
344 + const referenced =
345 + this.launching > 0 || [...this.children.values()].some((child) => child.referenced);
346 + if (referenced) this.worker.ref();
347 + else this.worker.unref();
348 + }
349 +
350 + onMessage(message: FromWorker): void {
351 + const child = this.children.get(message.id);
352 + if (child === undefined) return;
353 + switch (message.type) {
354 + case "spawn":
355 + this.launching--;
356 + child.spawned = true;
357 + child.pid = message.pid;
358 + child.emit("spawn");
359 + break;
360 + case "error":
361 + if (!child.spawned) {
362 + this.launching--;
363 + child.exited = true;
364 + this.release(child);
365 + }
366 + child.emit("error", toError(message.error));
367 + break;
368 + case "data":
369 + child.onData(message.fd, message.data);
370 + break;
371 + case "written":
372 + child.onWritten(message.fd, message.error);
373 + break;
374 + case "eof":
375 + child.onEof(message.fd);
376 + break;
377 + case "finished":
378 + child.onFinished(message.fd);
379 + break;
380 + case "stream-error":
381 + child.onStreamError(message.fd, message.error);
382 + break;
383 + case "exit":
384 + child.exit(message.code, message.signal);
385 + break;
386 + case "close":
387 + child.emit("close", child.exitCode, child.signalCode);
388 + this.release(child);
389 + break;
390 + }
391 + }
392 +
393 + release(child: WorkerChild): void {
394 + this.children.delete(child.id);
395 + this.syncRef();
396 + this.pool.release(this);
397 + }
398 +
399 + fail(error: Error): void {
400 + if (this.closed) return;
401 + this.close();
402 + for (const child of this.children.values()) {
403 + if (child.exited) {
404 + child.abandon();
405 + continue;
406 + }
407 + if (!child.spawned) {
408 + child.exited = true;
409 + child.emit("error", error);
410 + continue;
411 + }
412 + // The worker owned the only handle, so try to end the whole tree before reporting the exit.
413 + const finish = () => {
414 + child.exit(null, "SIGKILL");
415 + child.abandon();
416 + };
417 + if (child.pid === undefined) finish();
418 + else this.pool.killTree(child.pid, finish);
419 + }
420 + this.children.clear();
421 + }
422 +
423 + close(): void {
424 + if (this.closed) return;
425 + this.closed = true;
426 + this.pool.workers.delete(this);
427 + void this.worker.terminate();
428 + }
429 +}
430 +
431 +class SpawnWorkerPool {
432 + readonly workers = new Set<SpawnWorker>();
433 + readonly platform: NodeJS.Platform;
434 + #nextId = 0;
435 +
436 + constructor(platform: NodeJS.Platform) {
437 + this.platform = platform;
438 + }
439 +
440 + readonly spawn = (
441 + command: string,
442 + args: ReadonlyArray<string>,
443 + options: NodeChildProcess.SpawnOptions,
444 + ) => {
445 + const workers = [...this.workers];
446 + // A worker inside CreateProcess cannot start another launch until it returns.
447 + const worker =
448 + workers.find((candidate) => candidate.launching === 0) ??
449 + (workers.length < MAX_WORKERS
450 + ? this.#add()
451 + : workers.reduce((best, candidate) =>
452 + candidate.launching < best.launching ? candidate : best,
453 + ));
454 + return worker.spawn(++this.#nextId, command, args, options);
455 + };
456 +
457 + killTree(pid: number, done: () => void): void {
458 + const killPid = () => {
459 + try {
460 + process.kill(pid, "SIGKILL");
461 + } catch {}
462 + };
463 + if (this.platform !== "win32") {
464 + killPid();
465 + done();
466 + return;
467 + }
468 + let settled = false;
469 + const finish = (killed: boolean) => {
470 + if (settled) return;
471 + settled = true;
472 + // As Effect's own kill does when taskkill fails, end at least the direct child.
473 + if (!killed) killPid();
474 + done();
475 + };
476 + this.spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
477 + stdio: "ignore",
478 + windowsHide: true,
479 + })
480 + .on("error", () => finish(false))
481 + .on("exit", (code) => finish(code === 0));
482 + }
483 +
484 + #add(): SpawnWorker {
485 + const worker = new SpawnWorker(this);
486 + this.workers.add(worker);
487 + return worker;
488 + }
489 +
490 + release(worker: SpawnWorker): void {
491 + if (worker.children.size > 0 || worker.launching > 0) return;
492 + const idle = [...this.workers].filter(
493 + (candidate) => candidate.children.size === 0 && candidate.launching === 0,
494 + );
495 + if (idle.length > MAX_IDLE_WORKERS) worker.close();
496 + }
497 +
498 + close(): void {
499 + for (const worker of this.workers) worker.close();
500 + }
501 +}
502 +
503 +let sharedPool: SpawnWorkerPool | undefined;
504 +
505 +/** A piped `child_process.spawn` for Windows launches outside Effect's spawner. */
506 +export const spawnPiped = (
507 + command: string,
508 + args: ReadonlyArray<string>,
509 + options: Omit<NodeChildProcess.SpawnOptions, "stdio">,
510 +) =>
511 + (sharedPool ??= new SpawnWorkerPool("win32")).spawn(command, args, {
512 + ...options,
513 + stdio: ["pipe", "pipe", "pipe"],
514 + }) as WorkerChild & {
515 + readonly stdin: NodeStream.Writable;
516 + readonly stdout: NodeStream.Readable;
517 + readonly stderr: NodeStream.Readable;
518 + };
519 +
520 +export const layer = Layer.unwrap(
521 + Effect.gen(function* () {
522 + const platform = yield* HostProcess.Platform;
523 + const pool = yield* Effect.acquireRelease(
524 + Effect.sync(() => new SpawnWorkerPool(platform)),
525 + (pool) => Effect.sync(() => pool.close()),
526 + );
527 + return NodeChildProcessSpawner.layerWithSpawn(pool.spawn);
528 + }),
529 +);
530 +
531 +/** Only Windows creates processes slowly enough on the calling thread to need workers. */
532 +export const layerServer = Layer.unwrap(
533 + Effect.map(HostProcess.Platform, (platform) =>
534 + platform === "win32" ? layer : NodeChildProcessSpawner.layer,
535 + ),
536 +);
apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts
+1 -1
@@ -30,7 +30,7 @@ it("drops strict MCP mode, and only that, next to an administrator's managed-mcp
30 environment: { HOME: "/home/user" },
31 cwd: undefined,
32 managedMcpConfig: true,
33 - spawnThroughEnv: false,
33 + spawnVia: undefined,
34 });
35
36 // Claude exits before initializing when handed --strict-mcp-config here.
apps/server/src/provider/ClaudeProvider.ts
+22 -5
@@ -23,6 +23,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process";
23 import { createModelCapabilities } from "@t3tools/shared/model";
24 import { envTrampoline, supportsEnvChdir } from "@t3tools/shared/envTrampoline";
25 import * as HostProcess from "@t3tools/shared/HostProcess";
26 +import * as SpawnWorker from "../process/SpawnWorker.ts";
27 import { resolveSpawnCommand } from "@t3tools/shared/shell";
28 import {
29 query as claudeQuery,
@@ -259,16 +260,27 @@ export function spawnClaudeProbeThroughEnv({
260 });
261 }
262
263 +/** Windows runs CreateProcess on the calling thread, so the probe launches from a launcher thread. */
264 +function spawnClaudeProbeOffThread({ command, args, cwd, env, signal }: ClaudeSpawnOptions) {
265 + const child = SpawnWorker.spawnPiped(command, args, { cwd, env, signal, windowsHide: true });
266 + // The probe ignores stderr; drain it so a full pipe cannot stall the CLI.
267 + child.stderr.resume();
268 + return child;
269 +}
270 +
271 export function buildClaudeCapabilitiesProbeQueryOptions(input: {
272 readonly executablePath: string;
273 readonly abortController: AbortController;
274 readonly environment: NodeJS.ProcessEnv;
275 readonly cwd: string | undefined;
276 readonly managedMcpConfig: boolean;
268 - readonly spawnThroughEnv: boolean;
277 + readonly spawnVia: "env" | "launcher-thread" | undefined;
278 }): ClaudeQueryOptions {
279 return {
271 - ...(input.spawnThroughEnv ? { spawnClaudeCodeProcess: spawnClaudeProbeThroughEnv } : {}),
280 + ...(input.spawnVia === "env" ? { spawnClaudeCodeProcess: spawnClaudeProbeThroughEnv } : {}),
281 + ...(input.spawnVia === "launcher-thread"
282 + ? { spawnClaudeCodeProcess: spawnClaudeProbeOffThread }
283 + : {}),
284 persistSession: false,
285 pathToClaudeCodeExecutable: input.executablePath,
286 abortController: input.abortController,
@@ -498,8 +510,13 @@ const probeClaudeCapabilities = (
510 ...(yield* readClaudeSettingsEnv(claudeSettings, cwd, claudeEnvironment)),
511 })
512 : 0;
501 - const spawnThroughEnv =
502 - (yield* HostProcess.Platform) === "linux" && (yield* Effect.promise(supportsEnvChdir));
513 + const platform = yield* HostProcess.Platform;
514 + const spawnVia =
515 + platform === "win32"
516 + ? "launcher-thread"
517 + : platform === "linux" && (yield* Effect.promise(supportsEnvChdir))
518 + ? "env"
519 + : undefined;
520 return yield* Effect.tryPromise({
521 try: async () => {
522 const q = claudeQuery({
@@ -513,7 +530,7 @@ const probeClaudeCapabilities = (
530 environment: claudeEnvironment,
531 cwd,
532 managedMcpConfig,
516 - spawnThroughEnv,
533 + spawnVia,
534 }),
535 });
536 const init = await q.initializationResult();
apps/server/src/server.ts
+8 -4
@@ -44,6 +44,7 @@ import { fixPath } from "./os-jank.ts";
44 import * as Ws from "./ws.ts";
45 import * as AgentScopeLive from "./process/agentScope.ts";
46 import * as ExternalLauncher from "./process/externalLauncher.ts";
47 +import * as SpawnWorker from "./process/SpawnWorker.ts";
48 import * as NodePtyAdapter from "./terminal/NodePtyAdapter.ts";
49 import * as PullRequestHttp from "./pullRequest/http.ts";
50 import * as SpeechModelStore from "./speech/SpeechModelStore.ts";
@@ -348,6 +349,9 @@ const layerRelayClient = Layer.unwrap(
349 }),
350 ).pipe(Layer.provide(ManagedPolicy.layer));
351
352 +// NodeServices and NodeHttpServer each output Node's own spawner, so each is followed by this one.
353 +const layerSpawner = SpawnWorker.layerServer.pipe(Layer.provide(NodeServices.layer));
354 +
355 const layerHttpServer = Layer.unwrap(
356 Effect.gen(function* () {
357 const config = yield* ServerConfig.ServerConfig;
@@ -384,7 +388,7 @@ const layerHttpServer = Layer.unwrap(
388 // `threshold` when context takeover is disabled).
389 websocket: { perMessageDeflate: true },
390 },
387 - );
391 + ).pipe(Layer.merge(layerSpawner));
392 }),
393 ).pipe(
394 Layer.provide(ManagedPolicy.layer),
@@ -394,7 +398,7 @@ const layerHttpServer = Layer.unwrap(
398
399 const layerPlatformServices = DocumentText.layer.pipe(
400 Layer.provideMerge(NonBlockingSpawner.layer),
397 - Layer.provideMerge(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer)),
401 + Layer.provideMerge(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer, layerSpawner)),
402 );
403
404 const layerPersistence = Layer.empty.pipe(Layer.provideMerge(SqlitePersistence.layerConfig));
@@ -1356,6 +1360,6 @@ const layerMakeServer = Layer.unwrap(
1360 ).pipe(Layer.provide(ProcessRunner.layer));
1361
1362 export const runServer = Layer.launch(
1359 - // For the layers above whose spawner requirement is met by the caller's runtime.
1360 - layerMakeServer.pipe(Layer.provide(NonBlockingSpawner.layer)),
1363 + // For the layers above whose spawner requirement is not met by one of them.
1364 + layerMakeServer.pipe(Layer.provide(NonBlockingSpawner.layer.pipe(Layer.provide(layerSpawner)))),
1365 );
patches/@effect__platform-node-shared@4.1.2.patch new
+93
@@ -0,0 +1,93 @@
1 +diff --git a/dist/NodeChildProcessSpawner.d.ts b/dist/NodeChildProcessSpawner.d.ts
2 +index 213be4fa2647d800b320fa483c9ede801366fd73..bb7a2bb97e976f85af4760a7299db39506318155 100644
3 +--- a/dist/NodeChildProcessSpawner.d.ts
4 ++++ b/dist/NodeChildProcessSpawner.d.ts
5 +@@ -31,6 +31,8 @@
6 + * @stability unstable
7 + * @since 4.0.0
8 + */
9 ++import type * as NodeChildProcess from "node:child_process";
10 ++import type { Readable, Writable } from "node:stream";
11 + import type * as Arr from "effect/Array";
12 + import * as FileSystem from "effect/FileSystem";
13 + import * as Layer from "effect/Layer";
14 +@@ -45,6 +47,19 @@ import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
15 + * @since 4.0.0
16 + */
17 + export declare const layer: Layer.Layer<ChildProcessSpawner, never, FileSystem.FileSystem | Path.Path>;
18 ++export interface SpawnedChildProcess extends NodeJS.EventEmitter {
19 ++ readonly pid?: number | undefined;
20 ++ readonly exitCode: number | null;
21 ++ readonly signalCode: NodeJS.Signals | null;
22 ++ readonly stdin: Writable | null;
23 ++ readonly stdout: Readable | null;
24 ++ readonly stderr: Readable | null;
25 ++ readonly stdio: ReadonlyArray<Readable | Writable | null | undefined>;
26 ++ kill(signal?: NodeJS.Signals | number): boolean;
27 ++ ref(): void;
28 ++ unref(): void;
29 ++}
30 ++export declare const layerWithSpawn: (spawnProcess: (command: string, args: ReadonlyArray<string>, options: NodeChildProcess.SpawnOptions) => SpawnedChildProcess) => Layer.Layer<ChildProcessSpawner, never, FileSystem.FileSystem | Path.Path>;
31 + /**
32 + * Result of flattening a pipeline of commands.
33 + *
34 +diff --git a/dist/NodeChildProcessSpawner.js b/dist/NodeChildProcessSpawner.js
35 +index 08d50b16dfe564551f1bffc7cae2d3b53805e172..fbecacc8b39a9eab7725a799aa5019c36bcc32ab 100644
36 +--- a/dist/NodeChildProcessSpawner.js
37 ++++ b/dist/NodeChildProcessSpawner.js
38 +@@ -81,16 +81,26 @@ const isProcessAlive = (command, childProcess) => {
39 + return isUnsignallableProcessGroup(error);
40 + }
41 + };
42 +-const taskkill = (childProcess, onExit = () => {}) => {
43 +- if (hasExited(childProcess)) {
44 +- onExit(null);
45 +- return;
46 +- }
47 +- NodeChildProcess.execFile("taskkill", ["/pid", String(childProcess.pid), "/T", "/F"], {
48 +- windowsHide: true
49 +- }, onExit);
50 +-};
51 +-const make = /*#__PURE__*/Effect.gen(function* () {
52 ++const makeWithSpawn = spawnProcess => Effect.gen(function* () {
53 ++ // Starts taskkill through the injected spawner so it gets the same off-thread launch as commands.
54 ++ const taskkill = (childProcess, onExit = () => {}) => {
55 ++ if (hasExited(childProcess)) {
56 ++ onExit(null);
57 ++ return;
58 ++ }
59 ++ let done = false;
60 ++ const finish = error => {
61 ++ if (done) return;
62 ++ done = true;
63 ++ onExit(error);
64 ++ };
65 ++ const killer = spawnProcess("taskkill", ["/pid", String(childProcess.pid), "/T", "/F"], {
66 ++ stdio: "ignore",
67 ++ windowsHide: true
68 ++ });
69 ++ killer.on("error", finish);
70 ++ killer.on("exit", code => finish(code === 0 ? null : new Error(`taskkill exited with code ${code}`)));
71 ++ };
72 + const fs = yield* FileSystem.FileSystem;
73 + const path = yield* Path.Path;
74 + const resolveWorkingDirectory = Effect.fnUntraced(function* (options) {
75 +@@ -335,7 +345,7 @@ const make = /*#__PURE__*/Effect.gen(function* () {
76 + };
77 + const spawn = (command, spawnOptions) => Effect.callback(resume => {
78 + const deferred = Deferred.makeUnsafe();
79 +- const handle = NodeChildProcess.spawn(command.command, command.args.map(unwrap), spawnOptions);
80 ++ const handle = spawnProcess(command.command, command.args.map(unwrap), spawnOptions);
81 + handle.on("error", error => {
82 + // Node copies the arguments into `spawnargs`.
83 + if (command.args.some(Redacted.isRedacted)) {
84 +@@ -665,7 +675,8 @@ const make = /*#__PURE__*/Effect.gen(function* () {
85 + * @category layers
86 + * @since 4.0.0
87 + */
88 +-export const layer = /*#__PURE__*/Layer.effect(ChildProcessSpawner, make);
89 ++export const layer = /*#__PURE__*/Layer.effect(ChildProcessSpawner, /*#__PURE__*/makeWithSpawn(NodeChildProcess.spawn));
90 ++export const layerWithSpawn = spawnProcess => Layer.effect(ChildProcessSpawner, makeWithSpawn(spawnProcess));
91 + /**
92 + * Flattens a `Command` into an array of `StandardCommand`s along with pipe
93 + * options for each connection.
pnpm-lock.yaml
+5 -4
@@ -363,6 +363,7 @@ patchedDependencies:
363 '@alchemy.run/test@2.0.0-beta.85': 29c0539ea71d9cc372f0b16558640599beb9bc609605feb2a493da268d72713e
364 '@clerk/expo-native-components@0.4.4': 7a808b92da8460750b85818552e13be3fb73d111691c7db76965970351e124e4
365 '@cursor/sdk@1.2.0': 57f502128bf6accd976963b126e227c86a45d815a53a8dc450461beae3bed4a4
366 + '@effect/platform-node-shared@4.1.2': 06952843c6f431ca83c78762fd18d23cda76883801049ee311feced2438ecf14
367 '@effect/vitest@4.1.2': 299510b71c36537a832a67e9d160a5f112a5f326a29e95c41cb45fc8234e47c7
368 '@expo/ui@58.0.27': 9f2547678939f4ec78fe45163b6455aad63d3c80353d7e0cc783f6a61a7ccc2f
369 '@ff-labs/fff-node@0.11.0': 3be7107340e5f388114da259637828cd47f2b32eb8ae572440715c4e38cffe6e
@@ -855,7 +856,7 @@ importers:
856 version: 4.1.2(bufferutil@4.1.0)(effect@4.1.3)(redis@6.2.1)(utf-8-validate@6.0.6)
857 '@effect/platform-node-shared':
858 specifier: 4.1.2
858 - version: 4.1.2(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)
859 + version: 4.1.2(patch_hash=06952843c6f431ca83c78762fd18d23cda76883801049ee311feced2438ecf14)(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)
860 '@ff-labs/fff-node':
861 specifier: 0.11.0
862 version: 0.11.0(patch_hash=3be7107340e5f388114da259637828cd47f2b32eb8ae572440715c4e38cffe6e)
@@ -14311,13 +14312,13 @@ snapshots:
14312
14313 '@effect/platform-bun@4.1.2(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)':
14314 dependencies:
14314 - '@effect/platform-node-shared': 4.1.2(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)
14315 + '@effect/platform-node-shared': 4.1.2(patch_hash=06952843c6f431ca83c78762fd18d23cda76883801049ee311feced2438ecf14)(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)
14316 effect: 4.1.3
14317 transitivePeerDependencies:
14318 - bufferutil
14319 - utf-8-validate
14320
14320 - '@effect/platform-node-shared@4.1.2(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)':
14321 + '@effect/platform-node-shared@4.1.2(patch_hash=06952843c6f431ca83c78762fd18d23cda76883801049ee311feced2438ecf14)(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)':
14322 dependencies:
14323 '@types/ws': 8.18.2
14324 effect: 4.1.3
@@ -14328,7 +14329,7 @@ snapshots:
14329
14330 '@effect/platform-node@4.1.2(bufferutil@4.1.0)(effect@4.1.3)(redis@6.2.1)(utf-8-validate@6.0.6)':
14331 dependencies:
14331 - '@effect/platform-node-shared': 4.1.2(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)
14332 + '@effect/platform-node-shared': 4.1.2(patch_hash=06952843c6f431ca83c78762fd18d23cda76883801049ee311feced2438ecf14)(bufferutil@4.1.0)(effect@4.1.3)(utf-8-validate@6.0.6)
14333 effect: 4.1.3
14334 redis: 6.2.1
14335 undici: 8.12.4
pnpm-workspace.yaml
+3
@@ -268,6 +268,9 @@ patchedDependencies:
268 # Observe the owned host exit independently of descendants retaining its stdio.
269 "@muse-code/sdk@1.4.6": patches/@muse-code__sdk@1.4.6.patch
270 app-builder-lib@26.16.1: patches/app-builder-lib@26.16.1.patch
271 + # The spawner takes an injected spawn function (and uses it for taskkill) so Windows launches
272 + # can run on worker threads: apps/server/src/process/SpawnWorker.ts.
273 + "@effect/platform-node-shared@4.1.2": patches/@effect__platform-node-shared@4.1.2.patch
274 # Electron net requests never emit "socket", so upstream's idle timeout never fires and a
275 # stalled update download hangs forever.
276 electron-updater@6.8.9: patches/electron-updater@6.8.9.patch