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, 13:30 UTC
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