From b16afc0411245c9aafd8eaf951e8974a85863a6c Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 11:25:47 -0800 Subject: [PATCH 01/17] feat(cli): persistent control process with pre-warmed workers for short commands Most of a `serve-sim tap` is Node compiling and evaluating the ~1 MB CLI bundle before any real work. The bin (dist/serve-sim.js) is now a 14 KB entry that only uses node builtins; the CLI moves to dist/serve-sim-cli.js. For short one-shot commands (tap, gesture, settle, button, type, paste, rotate, fold, ca-debug, memory-warning, event-log, ax, buffer, and --help/--version) the bin hands argv, cwd, env and TTY shape to a control daemon over a Unix socket. The daemon keeps two single-use workers that have already evaluated the CLI bundle; one adopts the caller's context, runs the command exactly as the bin would, and exits. stdout/stderr are relayed, exit codes and signals propagate, Ctrl+C is forwarded, and a caller that dies takes its worker with it. - Auto-starts in the background on first use (that call runs in-process), exits after 5 minutes idle (SERVE_SIM_CONTROL_IDLE_MS). Under CI it only reuses a running daemon; SERVE_SIM_CONTROL=0 turns it off. - `serve-sim control status|start|stop [--json]`, all idempotent; stop clears stale socket/pid files. - Stale sockets are replaced, concurrent starters converge on one daemon (losers notice their socket inode was replaced and exit), a rebuilt dist or a caller with different HOME/TMPDIR/DEBUG runs in-process. - Anything else (servers, record, camera, exec, --stdin, ...) and any failure before the daemon accepts a command runs in-process as before. --- knip.json | 1 + packages/serve-sim/build.ts | 42 +- packages/serve-sim/package.json | 1 + .../src/__tests__/control-process.test.ts | 481 ++++++++++++++++++ .../__tests__/fixtures/control-fake-cli.ts | 49 ++ packages/serve-sim/src/bin.ts | 64 +++ packages/serve-sim/src/control-client.ts | 333 ++++++++++++ packages/serve-sim/src/control-daemon.ts | 416 +++++++++++++++ packages/serve-sim/src/control-protocol.ts | 283 +++++++++++ packages/serve-sim/src/control-worker.ts | 74 +++ packages/serve-sim/src/index.ts | 16 +- 11 files changed, 1751 insertions(+), 9 deletions(-) create mode 100644 packages/serve-sim/src/__tests__/control-process.test.ts create mode 100644 packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts create mode 100644 packages/serve-sim/src/bin.ts create mode 100644 packages/serve-sim/src/control-client.ts create mode 100644 packages/serve-sim/src/control-daemon.ts create mode 100644 packages/serve-sim/src/control-protocol.ts create mode 100644 packages/serve-sim/src/control-worker.ts diff --git a/knip.json b/knip.json index 2a2465581..db5e8d6b7 100644 --- a/knip.json +++ b/knip.json @@ -16,6 +16,7 @@ ], "entry": [ "src/index.ts", + "src/bin.ts", "src/middleware.ts", "src/state.ts", "src/client/client.tsx", diff --git a/packages/serve-sim/build.ts b/packages/serve-sim/build.ts index 7d84e5536..a918d1ec9 100644 --- a/packages/serve-sim/build.ts +++ b/packages/serve-sim/build.ts @@ -3,7 +3,9 @@ * Unified serve-sim build. * * Produces, all minified and with no runtime deps on workspace packages: - * dist/serve-sim.js ESM bin (node target) referenced by package.json#bin + * dist/serve-sim.js Tiny ESM bin (node target) referenced by package.json#bin; + * dispatches to the control process or loads: + * dist/serve-sim-cli.js The full CLI bundle (node target) * dist/serve-sim Compiled single-file executable (bun --compile) * dist/middleware.js Public subpath export "serve-sim/middleware" (ESM) * dist/middleware.cjs Thin CJS wrapper for the same @@ -150,27 +152,51 @@ writeFileSync( ); console.log("dist/middleware.cjs (wrapper)"); -// ─── 4. Bin JS bundle ──────────────────────────────────────────────────── +// ─── 4. Bin JS bundles ─────────────────────────────────────────────────── +// dist/serve-sim-cli.js is the whole CLI. dist/serve-sim.js is the bin: only +// node builtins, so a short command handed to the persistent control process +// skips compiling the ~1 MB CLI bundle (see src/bin.ts). -const binJsResult = await Bun.build({ +const NODE_EXTERNALS = ["fs", "path", "os", "child_process", "url", "net", "tls", "crypto", "stream", "events", "http", "https", "zlib", "buffer", "module", "ws"]; + +const cliJsResult = await Bun.build({ entrypoints: [resolve(root, "src/index.ts")], target: "node", format: "esm", minify: true, outdir: distDir, - naming: "serve-sim.js", - external: ["fs", "path", "os", "child_process", "url", "net", "tls", "crypto", "stream", "events", "http", "https", "zlib", "buffer", "module", "ws"], + naming: "serve-sim-cli.js", + external: NODE_EXTERNALS, define: PREVIEW_DEFINE, sourcemap: "linked", }); +if (!cliJsResult.success) { + console.error("CLI JS build failed:"); + for (const log of cliJsResult.logs) console.error(log); + process.exit(1); +} +console.log(`dist/serve-sim-cli.js ${kb((await cliJsResult.outputs[0]!.text()).length)}`); + +const binJsResult = await Bun.build({ + entrypoints: [resolve(root, "src/bin.ts")], + target: "node", + format: "esm", + minify: true, + outdir: distDir, + naming: "serve-sim.js", + external: NODE_EXTERNALS, +}); if (!binJsResult.success) { console.error("Bin JS build failed:"); for (const log of binJsResult.logs) console.error(log); process.exit(1); } - -const binJsSize = (await binJsResult.outputs[0]!.text()).length; -console.log(`dist/serve-sim.js ${kb(binJsSize)}`); +const binJs = await binJsResult.outputs[0]!.text(); +if (/\bws\b["']|from"ws"|commander/.test(binJs)) { + console.error("dist/serve-sim.js must only import node builtins"); + process.exit(1); +} +console.log(`dist/serve-sim.js ${kb(binJs.length)}`); // ─── 5. Compiled single-file executable ────────────────────────────────── // Bun.build doesn't expose --compile yet, so shell out. The define arg carries diff --git a/packages/serve-sim/package.json b/packages/serve-sim/package.json index 13eb618f2..e3e727168 100644 --- a/packages/serve-sim/package.json +++ b/packages/serve-sim/package.json @@ -25,6 +25,7 @@ }, "files": [ "dist/serve-sim.js", + "dist/serve-sim-cli.js", "dist/middleware.js", "dist/middleware.cjs", "dist/simcam/libSimCameraInjector.dylib", diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts new file mode 100644 index 000000000..76fd89915 --- /dev/null +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -0,0 +1,481 @@ +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test"; +import { spawn, spawnSync, type ChildProcess } from "child_process"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, utimesSync, writeFileSync } from "fs"; +import { join } from "path"; +import { + CONTROL_DIR_ENV, + FRAME_JSON, + FRAME_STDOUT, + FrameDecoder, + controlFingerprint, + controlMode, + controlPaths, + encodeFrame, + encodeJson, + fingerprintMismatch, + isDispatchable, + isStaleBuild, + parseIdleMs, + parseJsonFrame, + type ControlMessage, +} from "../control-protocol"; +import { adoptCaller } from "../control-worker"; + +// ─── Pure pieces ───────────────────────────────────────────────────────── + +describe("isDispatchable", () => { + test("short commands and root info flags dispatch", () => { + expect(isDispatchable(["tap", "0.5", "0.5"])).toBe(true); + expect(isDispatchable(["button", "home", "-d", "X"])).toBe(true); + expect(isDispatchable(["buffer", "status"])).toBe(true); + expect(isDispatchable(["--help"])).toBe(true); + expect(isDispatchable(["-v"])).toBe(true); + expect(isDispatchable(["help", "tap"])).toBe(true); + }); + + test("servers, long-running, stdin and unknown commands stay in-process", () => { + expect(isDispatchable([])).toBe(false); + expect(isDispatchable(["--port", "3412"])).toBe(false); + expect(isDispatchable(["--detach"])).toBe(false); + expect(isDispatchable(["record"])).toBe(false); + expect(isDispatchable(["camera", "status"])).toBe(false); + expect(isDispatchable(["exec", "ls"])).toBe(false); + expect(isDispatchable(["control", "status"])).toBe(false); + expect(isDispatchable(["type", "--stdin"])).toBe(false); + expect(isDispatchable(["paste", "--stdin", "-d", "X"])).toBe(false); + expect(isDispatchable(["iPhone 16"])).toBe(false); + expect(isDispatchable(["--help", "tap"])).toBe(false); + }); +}); + +describe("controlMode", () => { + test("defaults to auto, off/on overrides, CI only reuses", () => { + expect(controlMode({})).toBe("auto"); + expect(controlMode({ SERVE_SIM_CONTROL: "0" })).toBe("off"); + expect(controlMode({ SERVE_SIM_CONTROL: "off" })).toBe("off"); + expect(controlMode({ CI: "true" })).toBe("use"); + expect(controlMode({ CI: "false" })).toBe("auto"); + expect(controlMode({ CI: "1", SERVE_SIM_CONTROL: "1" })).toBe("auto"); + }); + + test("parseIdleMs falls back on junk", () => { + expect(parseIdleMs(undefined)).toBe(300_000); + expect(parseIdleMs("2000")).toBe(2000); + expect(parseIdleMs("nope")).toBe(300_000); + expect(parseIdleMs("5")).toBe(300_000); + }); +}); + +describe("framing", () => { + test("decodes frames split across arbitrary chunks", () => { + const wire = Buffer.concat([ + encodeJson({ t: "accepted" }), + encodeFrame(FRAME_STDOUT, "hello\n"), + encodeJson({ t: "exit", code: 3, signal: null }), + ]); + const decoder = new FrameDecoder(); + const frames = []; + for (let i = 0; i < wire.length; i += 3) frames.push(...decoder.push(wire.subarray(i, i + 3))); + expect(frames.map((f) => f.type)).toEqual([FRAME_JSON, FRAME_STDOUT, FRAME_JSON]); + expect(frames[1]!.payload.toString()).toBe("hello\n"); + expect(parseJsonFrame(frames[2]!)).toEqual({ t: "exit", code: 3, signal: null }); + }); + + test("rejects oversized frames and ignores non-JSON", () => { + const header = Buffer.alloc(5); + header.writeUInt8(FRAME_JSON, 0); + header.writeUInt32BE(0xffffffff, 1); + expect(() => new FrameDecoder().push(header)).toThrow(/too large/); + expect(parseJsonFrame({ type: FRAME_JSON, payload: Buffer.from("{nope") })).toBeNull(); + }); +}); + +describe("fingerprint", () => { + const base = { + protocol: 1, + execPath: "/n", + home: "/h", + tmpdir: "/t", + debug: "", + binMtimeMs: 1, + mainMtimeMs: 2, + }; + test("reports the first differing field; rebuilds are stale", () => { + expect(fingerprintMismatch(base, { ...base })).toBeNull(); + expect(fingerprintMismatch(base, { ...base, debug: "serve-sim*" })).toBe("debug"); + expect(isStaleBuild(fingerprintMismatch(base, { ...base, mainMtimeMs: 3 }))).toBe(true); + expect(isStaleBuild("home")).toBe(false); + }); + + test("socket paths are per install and node binary", () => { + const env = { HOME: "/h", [CONTROL_DIR_ENV]: "/tmp/x" }; + const a = controlPaths({ binFile: "/a/serve-sim.js", execPath: "/n", env }); + const b = controlPaths({ binFile: "/b/serve-sim.js", execPath: "/n", env }); + const c = controlPaths({ binFile: "/a/serve-sim.js", execPath: "/n2", env }); + expect(a.socket.startsWith("/tmp/x/control-")).toBe(true); + expect(new Set([a.socket, b.socket, c.socket]).size).toBe(3); + expect(controlFingerprint({ binFile: "/missing", mainFile: "/missing", execPath: "/n", env }).mainMtimeMs).toBe(-1); + }); +}); + +describe("adoptCaller", () => { + test("takes over argv, env, cwd and TTY shape", () => { + const dir = mkdtempSync("/tmp/ssctl-adopt-"); + const chdirs: string[] = []; + const stdout = {} as NodeJS.WriteStream; + const proc = { + argv: ["/node", "/bin.js"], + env: { KEEP: "old", DROP: "x" } as NodeJS.ProcessEnv, + chdir: (d: string) => chdirs.push(d), + stdout, + stderr: {} as NodeJS.WriteStream, + } as unknown as NodeJS.Process; + adoptCaller( + { + t: "run", + fingerprint: {} as never, + argv: ["tap", "1", "2"], + cwd: dir, + env: { KEEP: "new", ADD: "y" }, + tty: { stdout: { isTTY: true, columns: 120 }, stderr: { isTTY: false } }, + }, + proc, + ); + expect(proc.argv).toEqual(["/node", "/bin.js", "tap", "1", "2"]); + expect(proc.env).toEqual({ KEEP: "new", ADD: "y" }); + expect(chdirs).toEqual([dir]); + expect(stdout.isTTY).toBe(true); + expect(stdout.columns).toBe(120); + expect(proc.stderr.isTTY).toBeUndefined(); + rmSync(dir, { recursive: true, force: true }); + }); +}); + +// ─── Real processes ────────────────────────────────────────────────────── +// Build the real bin next to a fake CLI bundle and drive it with node, the +// runtime the published bin targets. + +const NODE = spawnSync("node", ["-e", "process.stdout.write(process.execPath)"], { encoding: "utf8" }); +const nodePath = NODE.status === 0 ? NODE.stdout : null; +const describeWithNode = nodePath ? describe : describe.skip; + +describeWithNode("control process", () => { + let root: string; + let dist: string; + let binFile: string; + let mainFile: string; + let ctlDir: string; + let work: string; + const stray: ChildProcess[] = []; + + beforeAll(async () => { + // realpath: macOS /tmp is a symlink, and the bin keys its socket on its own real path. + root = realpathSync(mkdtempSync("/tmp/ssctl-")); + dist = join(root, "dist"); + for (const [entry, naming] of [ + [join(import.meta.dir, "../bin.ts"), "serve-sim.js"], + [join(import.meta.dir, "fixtures/control-fake-cli.ts"), "serve-sim-cli.js"], + ] as const) { + const result = await Bun.build({ entrypoints: [entry], target: "node", format: "esm", outdir: dist, naming }); + if (!result.success) throw new Error(result.logs.map(String).join("\n")); + } + binFile = join(dist, "serve-sim.js"); + mainFile = join(dist, "serve-sim-cli.js"); + }); + + beforeEach(() => { + ctlDir = mkdtempSync(join(root, "c")); + work = mkdtempSync(join(root, "w")); + }); + + afterEach(async () => { + await cli(["control", "stop"]); + for (const c of stray.splice(0)) c.kill("SIGKILL"); + }); + + afterAll(() => { + rmSync(root, { recursive: true, force: true }); + }); + + function env(extra: Record = {}): NodeJS.ProcessEnv { + const e: NodeJS.ProcessEnv = { ...process.env, [CONTROL_DIR_ENV]: ctlDir, SERVE_SIM_CONTROL_IDLE_MS: "60000" }; + delete e.CI; + delete e.SERVE_SIM_CONTROL; + delete e.EXIT_CODE; + for (const [k, v] of Object.entries(extra)) { + if (v === undefined) delete e[k]; + else e[k] = v; + } + return e; + } + + function cli( + args: string[], + opts: { env?: Record; cwd?: string } = {}, + ): Promise<{ code: number | null; signal: string | null; stdout: string; stderr: string }> { + return new Promise((resolve) => { + const child = spawn(nodePath!, [binFile, ...args], { cwd: opts.cwd ?? work, env: env(opts.env) }); + let stdout = ""; + let stderr = ""; + child.stdout.on("data", (d) => (stdout += d)); + child.stderr.on("data", (d) => (stderr += d)); + child.on("close", (code, signal) => resolve({ code, signal, stdout, stderr })); + }); + } + + async function status(): Promise<{ running: boolean; pid?: number; served?: number; warm?: number; busy?: number }> { + const r = await cli(["control", "status", "--json"]); + return JSON.parse(r.stdout); + } + + async function until(probe: () => Promise, ms = 5000): Promise { + const deadline = Date.now() + ms; + for (;;) { + const v = await probe(); + if (v) return v; + if (Date.now() > deadline) throw new Error("timed out waiting"); + await Bun.sleep(25); + } + } + + const warm = () => until(async () => ((await status()).warm ?? 0) >= 1); + + async function startDaemon() { + const r = await cli(["control", "start", "--json"]); + expect(r.code).toBe(0); + await warm(); + return JSON.parse(r.stdout) as { pid: number; alreadyRunning: boolean }; + } + + test("start is idempotent and status/stop report it", async () => { + expect((await cli(["control", "status"])).code).toBe(1); + const first = await startDaemon(); + expect(first.alreadyRunning).toBe(false); + const again = JSON.parse((await cli(["control", "start", "--json"])).stdout); + expect(again).toMatchObject({ alreadyRunning: true, pid: first.pid }); + const stop = JSON.parse((await cli(["control", "stop", "--json"])).stdout); + expect(stop).toMatchObject({ wasRunning: true, pid: first.pid }); + expect((await status()).running).toBe(false); + expect(JSON.parse((await cli(["control", "stop", "--json"])).stdout)).toMatchObject({ wasRunning: false }); + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + expect(existsSync(paths.socket)).toBe(false); + expect(existsSync(paths.pidFile)).toBe(false); + }); + + test("dispatches a command with the caller's argv, cwd, env, output and exit code", async () => { + const daemon = await startDaemon(); + const sub = join(work, "sub dir"); + mkdirSync(sub); + const r = await cli(["tap", "0.25", "0.75"], { cwd: sub, env: { FOO: "bar", EXIT_CODE: "3" } }); + expect(r.code).toBe(3); + expect(r.stderr).toBe("to stderr\n"); + const seen = JSON.parse(r.stdout); + expect(seen).toMatchObject({ + argv: ["tap", "0.25", "0.75"], + argv1: binFile, + cwd: sub, + foo: "bar", + role: null, + stdoutIsTTY: false, + }); + // It ran in one of the daemon's workers, not in the client. + expect(seen.ppid).toBe(daemon.pid); + expect((await status()).served).toBe(1); + }); + + test("process.exit codes, thrown errors and help/version come back intact", async () => { + await startDaemon(); + expect(await cli(["button", "9"])).toMatchObject({ code: 9, stdout: "exiting hard\n" }); + const thrown = await cli(["ax"]); + expect(thrown.code).toBe(1); + expect(thrown.stderr).toContain("boom from ax"); + expect(await cli(["--version"])).toMatchObject({ code: 0, stdout: "fake 1.0.0\n", stderr: "" }); + expect((await status()).served).toBe(3); + }); + + test("reuses the daemon with a fresh worker per call", async () => { + const daemon = await startDaemon(); + const a = JSON.parse((await cli(["tap", "1", "1"])).stdout); + const b = JSON.parse((await cli(["tap", "2", "2"])).stdout); + expect(a.ppid).toBe(daemon.pid); + expect(b.ppid).toBe(daemon.pid); + expect(a.pid).not.toBe(b.pid); + expect((await status()).pid).toBe(daemon.pid); + }); + + test("auto-starts on first use; that call runs in-process", async () => { + const first = await cli(["tap", "1", "1"]); + expect(first.code).toBe(0); + const firstSeen = JSON.parse(first.stdout); + const s = await until(async () => { + const v = await status(); + return v.running && (v.warm ?? 0) >= 1 ? v : null; + }); + expect(firstSeen.ppid).not.toBe(s.pid); + const second = JSON.parse((await cli(["tap", "1", "1"])).stdout); + expect(second.ppid).toBe(s.pid); + }); + + test("never starts with SERVE_SIM_CONTROL=0 or under CI, and stays in-process for other commands", async () => { + expect((await cli(["tap", "1", "1"], { env: { SERVE_SIM_CONTROL: "0" } })).code).toBe(0); + expect((await cli(["tap", "1", "1"], { env: { CI: "true" } })).code).toBe(0); + expect(await cli(["record"])).toMatchObject({ code: 0, stdout: "direct-only:record\n" }); + await Bun.sleep(300); + expect((await status()).running).toBe(false); + + // CI reuses one that is already running. + const daemon = await startDaemon(); + expect(JSON.parse((await cli(["tap", "1", "1"], { env: { CI: "true" } })).stdout).ppid).toBe(daemon.pid); + expect(JSON.parse((await cli(["tap", "1", "1"], { env: { SERVE_SIM_CONTROL: "0" } })).stdout).ppid).not.toBe(daemon.pid); + }); + + test("recovers from a stale socket and pid file left by a killed daemon", async () => { + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + // A listener that dies without cleanup leaves the socket file behind. + const dead = spawn(nodePath!, [ + "-e", + `require("net").createServer().listen(${JSON.stringify(paths.socket)}, () => process.kill(process.pid, "SIGKILL"))`, + ]); + await new Promise((r) => dead.on("close", r)); + expect(existsSync(paths.socket)).toBe(true); + writeFileSync(paths.pidFile, JSON.stringify({ pid: dead.pid })); + + // The caller still gets its answer (in-process) and a new daemon takes over. + const r = await cli(["tap", "1", "1"]); + expect(r.code).toBe(0); + const s = await until(async () => { + const v = await status(); + return v.running && (v.warm ?? 0) >= 1 ? v : null; + }); + expect(JSON.parse((await cli(["tap", "1", "1"])).stdout).ppid).toBe(s.pid); + }); + + test("stop clears stale files when nothing is listening", async () => { + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + mkdirSync(paths.dir, { recursive: true }); + writeFileSync(paths.socket, ""); + writeFileSync(paths.pidFile, JSON.stringify({ pid: 999_999 })); + expect(JSON.parse((await cli(["control", "stop", "--json"])).stdout)).toMatchObject({ + wasRunning: false, + clearedStale: true, + }); + expect(existsSync(paths.socket)).toBe(false); + expect(existsSync(paths.pidFile)).toBe(false); + }); + + test("exits on its own after the idle period and cleans up", async () => { + const r = await cli(["control", "start", "--json"], { env: { SERVE_SIM_CONTROL_IDLE_MS: "400" } }); + const { pid } = JSON.parse(r.stdout); + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + await until(async () => { + try { + process.kill(pid, 0); + return false; + } catch { + return true; + } + }, 5000); + expect(existsSync(paths.socket)).toBe(false); + expect(existsSync(paths.pidFile)).toBe(false); + // No orphaned workers: none of them is still a child of the dead daemon. + const ps = spawnSync("ps", ["-A", "-o", "ppid="], { encoding: "utf8" }).stdout; + expect(ps.split("\n").map((l) => Number(l.trim()))).not.toContain(pid); + }); + + test("a rebuilt dist makes the daemon step aside", async () => { + const daemon = await startDaemon(); + const later = new Date(Date.now() + 5000); + utimesSync(mainFile, later, later); + const r = JSON.parse((await cli(["tap", "1", "1"])).stdout); + expect(r.ppid).not.toBe(daemon.pid); + await until(async () => { + try { + process.kill(daemon.pid, 0); + return false; + } catch { + return true; + } + }); + }); + + test("callers with a different HOME/DEBUG run in-process", async () => { + const daemon = await startDaemon(); + const r = JSON.parse((await cli(["tap", "1", "1"], { env: { DEBUG: "serve-sim*" } })).stdout); + expect(r.ppid).not.toBe(daemon.pid); + expect((await status()).pid).toBe(daemon.pid); + }); + + test("forwards Ctrl+C to the worker", async () => { + await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + let stdout = ""; + await new Promise((resolve) => + child.stdout.on("data", (d) => { + stdout += d; + if (stdout.includes("waiting")) resolve(); + }), + ); + child.kill("SIGINT"); + const code = await new Promise((r) => child.on("close", (c) => r(c))); + expect(code).toBe(130); + expect(stdout).toBe("waiting\ngot SIGINT\n"); + }); + + test("a caller that dies mid-command takes its worker with it", async () => { + await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + await new Promise((resolve) => child.stdout.on("data", () => resolve())); + expect((await status()).busy).toBe(1); + child.kill("SIGKILL"); + // The fake settle would otherwise run for 10s. + await until(async () => (await status()).busy === 0, 3000); + }); + + test("concurrent starters share one daemon and concurrent calls all complete", async () => { + const starts = await Promise.all(Array.from({ length: 4 }, () => cli(["control", "start", "--json"]))); + const pids = new Set(starts.map((s) => JSON.parse(s.stdout).pid)); + expect(pids.size).toBe(1); + const [pid] = [...pids]; + + const results = await Promise.all( + Array.from({ length: 8 }, (_, i) => cli(["tap", String(i), "0"], { env: { EXIT_CODE: String(i % 3) } })), + ); + results.forEach((r, i) => { + expect(r.code).toBe(i % 3); + const seen = JSON.parse(r.stdout); + expect(seen.argv).toEqual(["tap", String(i), "0"]); + expect(seen.ppid).toBe(pid); + }); + expect(new Set(results.map((r) => JSON.parse(r.stdout).pid)).size).toBe(8); + expect((await status()).served).toBe(8); + }); + + test("concurrent auto-starts converge on one daemon", async () => { + const results = await Promise.all(Array.from({ length: 6 }, () => cli(["tap", "1", "1"]))); + for (const r of results) expect(r.code).toBe(0); + const s = await until(async () => { + const v = await status(); + return v.running ? v : null; + }); + await Bun.sleep(500); + const daemons = spawnSync("pgrep", ["-f", `${binFile} __control-daemon`], { encoding: "utf8" }) + .stdout.split("\n") + .filter(Boolean); + expect(daemons).toEqual([String(s.pid)]); + }); + + test("rejects malformed and unknown first messages without wedging", async () => { + await startDaemon(); + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + const { createConnection } = await import("net"); + await new Promise((resolve) => { + const c = createConnection(paths.socket); + c.on("connect", () => c.write(encodeJson({ t: "accepted" } as ControlMessage))); + c.on("close", () => resolve()); + c.on("error", () => resolve()); + c.resume(); + }); + expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); + }); +}); diff --git a/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts new file mode 100644 index 000000000..5494f60ff --- /dev/null +++ b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts @@ -0,0 +1,49 @@ +// Stand-in for dist/serve-sim-cli.js in control-process tests: built next to +// a real bin build, it reports what the process it ran in looked like. +import { runCliMain } from "../../control-protocol"; + +async function main() { + const [command, ...rest] = process.argv.slice(2); + if (command === "--version") { + console.log("fake 1.0.0"); + return; + } + if (command === "tap") { + console.log( + JSON.stringify({ + argv: process.argv.slice(2), + argv1: process.argv[1], + cwd: process.cwd(), + foo: process.env.FOO ?? null, + role: process.env.SERVE_SIM_CONTROL_ROLE ?? null, + stdoutIsTTY: process.stdout.isTTY === true, + columns: process.stdout.columns ?? null, + pid: process.pid, + ppid: process.ppid, + }), + ); + process.stderr.write("to stderr\n"); + process.exitCode = Number(process.env.EXIT_CODE ?? 0); + return; + } + if (command === "button") { + console.log("exiting hard"); + process.exit(Number(rest[0] ?? 7)); + } + if (command === "settle") { + process.on("SIGINT", () => { + console.log("got SIGINT"); + process.exit(130); + }); + console.log("waiting"); + await new Promise((r) => setTimeout(r, 10_000)); + console.log("timed out"); + return; + } + if (command === "ax") { + throw new Error("boom from ax"); + } + console.log(`direct-only:${command ?? ""}`); +} + +await runCliMain(main); diff --git a/packages/serve-sim/src/bin.ts b/packages/serve-sim/src/bin.ts new file mode 100644 index 000000000..da6f17599 --- /dev/null +++ b/packages/serve-sim/src/bin.ts @@ -0,0 +1,64 @@ +#!/usr/bin/env node +/** + * The `serve-sim` bin. Deliberately tiny: short commands are handed to the + * persistent control process (see control-daemon.ts) so they skip loading + * the ~1 MB CLI bundle; everything else, and every case where the control + * process is unavailable, imports the bundle and runs in-process as before. + */ +import { fileURLToPath } from "url"; +import { controlCli, dispatchViaControl, type ControlContext } from "./control-client"; +import { runControlDaemonProcess } from "./control-daemon"; +import { + CONTROL_DAEMON_ARG, + CONTROL_IDLE_ENV, + CONTROL_ROLE_ENV, + DEFAULT_POOL_SIZE, + controlFingerprint, + controlPaths, + parseIdleMs, +} from "./control-protocol"; +import { runControlWorker } from "./control-worker"; + +// A sibling file at runtime; kept out of this bundle on purpose. +const mainUrl = new URL("./serve-sim-cli.js", import.meta.url); +const binFile = fileURLToPath(import.meta.url); +const args = process.argv.slice(2); + +function context(): ControlContext { + return { + binFile, + mainFile: fileURLToPath(mainUrl), + execPath: process.execPath, + env: process.env, + cwd: process.cwd(), + stdout: process.stdout, + stderr: process.stderr, + }; +} + +if (process.env[CONTROL_ROLE_ENV] === "worker") { + await runControlWorker(mainUrl.href); +} else if (args[0] === CONTROL_DAEMON_ARG) { + const ctx = context(); + const paths = controlPaths(ctx); + await runControlDaemonProcess({ + binFile, + socket: paths.socket, + pidFile: paths.pidFile, + fingerprint: controlFingerprint(ctx), + idleMs: parseIdleMs(process.env[CONTROL_IDLE_ENV]), + poolSize: DEFAULT_POOL_SIZE, + roleEnv: CONTROL_ROLE_ENV, + }); +} else if (args[0] === "control") { + process.exitCode = await controlCli(args.slice(1), context()); +} else { + const result = await dispatchViaControl(args, context()); + if (result.kind === "bypass") { + await import(mainUrl.href); + } else if (result.signal) { + process.kill(process.pid, result.signal); + } else { + process.exitCode = result.code ?? 1; + } +} diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts new file mode 100644 index 000000000..1f779dee4 --- /dev/null +++ b/packages/serve-sim/src/control-client.ts @@ -0,0 +1,333 @@ +/** + * Thin client for the persistent control process, plus `serve-sim control + * start|stop|status`. Runs inside the tiny bin entry, so node builtins only. + * + * Every failure before the daemon has accepted a command means "run it + * in-process instead", so a missing, stale or wedged daemon only costs a + * failed connect. + */ +import { execFileSync, spawn } from "child_process"; +import { existsSync, readFileSync, unlinkSync } from "fs"; +import { createConnection } from "net"; +import { + CONTROL_DAEMON_ARG, + FORWARDED_SIGNALS, + FRAME_STDERR, + FRAME_STDOUT, + FrameDecoder, + controlFingerprint, + controlMode, + controlPaths, + encodeJson, + isDispatchable, + parseJsonFrame, + type ControlPaths, + type ControlStatus, + type ForwardedSignal, +} from "./control-protocol"; +import { pingSocket } from "./control-daemon"; + +export interface ControlContext { + binFile: string; + mainFile: string; + execPath: string; + env: NodeJS.ProcessEnv; + cwd: string; + stdout: NodeJS.WriteStream; + stderr: NodeJS.WriteStream; + /** How long to wait for the daemon to accept before running in-process. */ + acceptTimeoutMs?: number; +} + +export type DispatchResult = + | { kind: "bypass"; reason: string } + | { kind: "done"; code: number | null; signal: NodeJS.Signals | null }; + +function pathsFor(ctx: ControlContext): ControlPaths { + return controlPaths({ binFile: ctx.binFile, execPath: ctx.execPath, env: ctx.env }); +} + +function stringEnv(env: NodeJS.ProcessEnv): Record { + const out: Record = {}; + for (const [k, v] of Object.entries(env)) if (typeof v === "string") out[k] = v; + return out; +} + +/** Start a detached daemon and return immediately. */ +function spawnDaemon(ctx: ControlContext): void { + try { + const child = spawn(ctx.execPath, [ctx.binFile, CONTROL_DAEMON_ARG], { + cwd: "/", + detached: true, + stdio: "ignore", + env: ctx.env, + }); + child.on("error", () => {}); + child.unref(); + } catch {} +} + +/** + * Run `args` through the control process when possible. Resolves "bypass" + * whenever the caller should run the command in-process. + */ +export function dispatchViaControl(args: string[], ctx: ControlContext): Promise { + const mode = controlMode(ctx.env); + if (mode === "off") return Promise.resolve({ kind: "bypass", reason: "disabled" }); + if (!isDispatchable(args)) return Promise.resolve({ kind: "bypass", reason: "not dispatchable" }); + const { socket } = pathsFor(ctx); + // sun_path is 104 bytes on macOS; a deep TMPDIR can't host the socket. + if (Buffer.byteLength(socket) > 103) return Promise.resolve({ kind: "bypass", reason: "socket path too long" }); + + return new Promise((resolve) => { + const conn = createConnection(socket); + const decoder = new FrameDecoder(); + let accepted = false; + let settled = false; + const signalHandlers = new Map void>(); + + const finish = (result: DispatchResult) => { + if (settled) return; + settled = true; + clearTimeout(acceptTimer); + for (const [sig, handler] of signalHandlers) process.off(sig, handler); + conn.destroy(); + resolve(result); + }; + const acceptTimer = setTimeout( + () => finish({ kind: "bypass", reason: "accept timeout" }), + ctx.acceptTimeoutMs ?? 1000, + ); + + conn.on("error", (error: NodeJS.ErrnoException) => { + if (accepted) { + ctx.stderr.write(`serve-sim: lost the control process mid-command (${error.code ?? error.message})\n`); + finish({ kind: "done", code: 1, signal: null }); + return; + } + if (mode === "auto" && (error.code === "ENOENT" || error.code === "ECONNREFUSED")) spawnDaemon(ctx); + finish({ kind: "bypass", reason: error.code ?? "connect failed" }); + }); + conn.on("close", () => { + if (settled) return; + if (!accepted) finish({ kind: "bypass", reason: "closed before accept" }); + else { + ctx.stderr.write("serve-sim: control process exited mid-command\n"); + finish({ kind: "done", code: 1, signal: null }); + } + }); + conn.on("connect", () => { + conn.write( + encodeJson({ + t: "run", + fingerprint: controlFingerprint(ctx), + argv: args, + cwd: ctx.cwd, + env: stringEnv(ctx.env), + tty: { + stdout: { isTTY: ctx.stdout.isTTY === true, columns: ctx.stdout.columns }, + stderr: { isTTY: ctx.stderr.isTTY === true, columns: ctx.stderr.columns }, + }, + }), + ); + }); + conn.on("data", (chunk) => { + let frames; + try { + frames = decoder.push(chunk); + } catch { + conn.destroy(); + return; + } + for (const frame of frames) { + if (frame.type === FRAME_STDOUT) { + ctx.stdout.write(frame.payload); + continue; + } + if (frame.type === FRAME_STDERR) { + ctx.stderr.write(frame.payload); + continue; + } + const msg = parseJsonFrame(frame); + if (!msg) continue; + if (msg.t === "bypass") finish({ kind: "bypass", reason: msg.reason }); + else if (msg.t === "accepted") { + accepted = true; + clearTimeout(acceptTimer); + // From here the worker owns the command: forward signals to it. + for (const sig of FORWARDED_SIGNALS) { + const handler = () => conn.write(encodeJson({ t: "signal", signal: sig })); + signalHandlers.set(sig, handler); + process.on(sig, handler); + } + } else if (msg.t === "exit") { + finish({ kind: "done", code: msg.code, signal: (msg.signal as NodeJS.Signals | null) ?? null }); + } + } + }); + }); +} + +// ─── serve-sim control start|stop|status ───────────────────────────────── + +const CONTROL_USAGE = `Usage: serve-sim control [status|start|stop] [--json] + +Persistent control process: keeps pre-warmed workers so short commands +(tap, type, button, ax, buffer, --help, ...) skip Node startup. Started +automatically on first use and exits after SERVE_SIM_CONTROL_IDLE_MS +(default 5 minutes) of quiet. SERVE_SIM_CONTROL=0 disables it; under CI it +is only used when already running unless SERVE_SIM_CONTROL=1. + + status Show whether it is running (exit 1 if not) + start Start it if needed and wait until it answers (idempotent) + stop Stop it and clear stale socket/pid files (idempotent)`; + +interface PidRecord { + pid: number; +} + +function readPidRecord(file: string): PidRecord | null { + try { + const v = JSON.parse(readFileSync(file, "utf8")) as PidRecord; + return typeof v.pid === "number" ? v : null; + } catch { + return null; + } +} + +function isAlive(pid: number): boolean { + try { + process.kill(pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === "EPERM"; + } +} + +function looksLikeDaemon(pid: number): boolean { + try { + const args = execFileSync("ps", ["-p", String(pid), "-o", "args="], { encoding: "utf8", timeout: 1000 }); + return args.includes(CONTROL_DAEMON_ARG); + } catch { + return false; + } +} + +/** Remove socket/pid files no live daemon is behind. */ +async function clearStaleControlFiles(paths: ControlPaths): Promise { + if (await pingSocket(paths.socket)) return false; + let cleared = false; + if (existsSync(paths.socket)) { + try { + unlinkSync(paths.socket); + cleared = true; + } catch {} + } + const rec = readPidRecord(paths.pidFile); + if (existsSync(paths.pidFile) && (!rec || !isAlive(rec.pid))) { + try { + unlinkSync(paths.pidFile); + cleared = true; + } catch {} + } + return cleared; +} + +function sleep(ms: number) { + return new Promise((r) => setTimeout(r, ms)); +} + +async function waitFor(probe: () => Promise, timeoutMs: number): Promise { + const deadline = Date.now() + timeoutMs; + for (;;) { + const v = await probe(); + if (v) return v; + if (Date.now() >= deadline) return null; + await sleep(25); + } +} + +function formatStatus(s: ControlStatus): string { + const idleLeft = Math.max(0, s.idleMs - (Date.now() - s.lastActiveAt)); + return ( + `control process running (pid ${s.pid}): ${s.warm} warm, ${s.busy} busy, ` + + `${s.served} served; idle exit in ${Math.ceil(idleLeft / 1000)}s\n socket ${s.socket}` + ); +} + +export async function controlCli(args: string[], ctx: ControlContext): Promise { + const json = args.includes("--json"); + const rest = args.filter((a) => a !== "--json"); + const verb = rest[0] ?? "status"; + const out = (line: string) => ctx.stdout.write(`${line}\n`); + const paths = pathsFor(ctx); + + if (verb === "--help" || verb === "-h" || verb === "help" || rest.length > 1) { + (rest.length > 1 ? ctx.stderr : ctx.stdout).write(`${CONTROL_USAGE}\n`); + return rest.length > 1 ? 1 : 0; + } + if (verb === "status") { + const status = await pingSocket(paths.socket); + if (json) out(JSON.stringify(status ? { running: true, ...status } : { running: false, socket: paths.socket })); + else out(status ? formatStatus(status) : "control process not running"); + return status ? 0 : 1; + } + if (verb === "start") { + let status = await pingSocket(paths.socket); + const already = status != null; + if (!status) { + spawnDaemon(ctx); + status = await waitFor(() => pingSocket(paths.socket), 5000); + } + if (!status) { + ctx.stderr.write("serve-sim: control process did not start\n"); + return 1; + } + if (json) out(JSON.stringify({ running: true, alreadyRunning: already, ...status })); + else out(already ? `already running (pid ${status.pid})` : `started (pid ${status.pid})`); + if (controlMode(ctx.env) === "off") { + ctx.stderr.write("serve-sim: note: SERVE_SIM_CONTROL=0 is set, so commands won't use it\n"); + } + return 0; + } + if (verb === "stop") { + const status = await pingSocket(paths.socket); + let stopped = false; + let stoppedPid: number | null = status?.pid ?? null; + if (status) { + await new Promise((resolve) => { + const conn = createConnection(paths.socket); + conn.on("connect", () => conn.write(encodeJson({ t: "stop" }))); + // Consume the reply, or the socket never reaches end/close. + conn.resume(); + conn.on("close", () => resolve()); + conn.on("error", () => resolve()); + }); + stopped = (await waitFor(async () => (isAlive(status.pid) ? null : true), 5000)) === true; + if (!stopped) { + try { + process.kill(status.pid, "SIGTERM"); + } catch {} + } + } + if (!status) { + // Alive but not answering (wedged or stopped): terminate it if the + // pid really is our daemon, not a recycled pid. + const rec = readPidRecord(paths.pidFile); + if (rec && rec.pid !== process.pid && isAlive(rec.pid) && looksLikeDaemon(rec.pid)) { + try { + process.kill(rec.pid, "SIGTERM"); + stoppedPid = rec.pid; + stopped = (await waitFor(async () => (isAlive(rec.pid) ? null : true), 3000)) === true; + } catch {} + } + } + const cleared = await clearStaleControlFiles(paths); + const wasRunning = stoppedPid != null; + if (json) out(JSON.stringify({ wasRunning, pid: stoppedPid, stopped: wasRunning && (stopped || status != null), clearedStale: cleared })); + else out(wasRunning ? `stopped (pid ${stoppedPid})` : cleared ? "not running (cleared stale files)" : "not running"); + return 0; + } + ctx.stderr.write(`serve-sim: unknown control verb '${verb}'\n${CONTROL_USAGE}\n`); + return 1; +} diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts new file mode 100644 index 000000000..51a832f12 --- /dev/null +++ b/packages/serve-sim/src/control-daemon.ts @@ -0,0 +1,416 @@ +/** + * The persistent control process: a Unix-socket server that keeps a small + * pool of pre-warmed workers (see control-worker.ts) and hands each incoming + * command to one of them, relaying its stdout/stderr and exit status back to + * the thin client. It exits after a quiet period, when stopped, when its + * socket is taken over by another daemon, or when the dist it was started + * from is rebuilt. + */ +import { spawn, type ChildProcess } from "child_process"; +import { chmodSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "fs"; +import { createConnection, createServer, type Server, type Socket } from "net"; +import { dirname } from "path"; +import { + FORWARDED_SIGNALS, + FRAME_STDERR, + FRAME_STDOUT, + FrameDecoder, + encodeFrame, + encodeJson, + fingerprintMismatch, + isStaleBuild, + parseJsonFrame, + type ControlFingerprint, + type ControlMessage, + type ControlStatus, +} from "./control-protocol"; + +interface ControlDaemonOptions { + socket: string; + pidFile: string; + /** Spawns one warm worker (stdio must include an IPC channel). */ + spawnWorker: () => ChildProcess; + fingerprint: ControlFingerprint; + idleMs: number; + poolSize: number; + /** Ownership/idle check period; defaults to min(1s, idleMs / 4). */ + checkIntervalMs?: number; +} + +interface ControlDaemon { + /** Resolves once the daemon has fully shut down. */ + closed: Promise; + stop: (reason: string) => void; +} + +interface Worker { + child: ChildProcess; + ready: boolean; +} + +const MAX_SPAWN_FAILURES = 3; + +/** Probe a socket path: true only if a control daemon answers a ping. */ +export function pingSocket(socket: string, timeoutMs = 500): Promise { + return new Promise((resolve) => { + const conn = createConnection(socket); + const decoder = new FrameDecoder(); + const done = (status: ControlStatus | null) => { + clearTimeout(timer); + conn.destroy(); + resolve(status); + }; + const timer = setTimeout(() => done(null), timeoutMs); + conn.on("connect", () => conn.write(encodeJson({ t: "ping" }))); + conn.on("data", (chunk) => { + try { + for (const frame of decoder.push(chunk)) { + const msg = parseJsonFrame(frame); + if (msg?.t === "pong") return done(msg.status); + } + } catch { + done(null); + } + }); + conn.on("error", () => done(null)); + conn.on("close", () => done(null)); + }); +} + +function listen(server: Server, socket: string): Promise { + return new Promise((resolve, reject) => { + const onError = (error: Error) => { + server.off("listening", onListening); + reject(error); + }; + const onListening = () => { + server.off("error", onError); + resolve(); + }; + server.once("error", onError); + server.once("listening", onListening); + server.listen(socket); + }); +} + +/** + * Bind the socket, clearing a stale one left by a dead daemon. Returns false + * when a live daemon already owns it (the caller should just exit). + */ +async function bindExclusive(server: Server, socket: string): Promise { + for (let attempt = 0; attempt < 3; attempt++) { + try { + await listen(server, socket); + return true; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error; + if (await pingSocket(socket)) return false; + try { + unlinkSync(socket); + } catch {} + } + } + return false; +} + +function inodeOf(path: string): number | null { + try { + return statSync(path).ino; + } catch { + return null; + } +} + +async function startControlDaemon(opts: ControlDaemonOptions): Promise { + mkdirSync(dirname(opts.socket), { recursive: true, mode: 0o700 }); + const server = createServer(); + if (!(await bindExclusive(server, opts.socket))) { + server.close(); + return null; + } + try { + chmodSync(opts.socket, 0o600); + } catch {} + const socketInode = inodeOf(opts.socket); + const startedAt = Date.now(); + let lastActiveAt = startedAt; + let busy = 0; + let served = 0; + let spawnFailures = 0; + let stopping = false; + const pool: Worker[] = []; + const waiting: Array<(worker: Worker | null) => void> = []; + const busyChildren = new Set(); + let resolveClosed!: () => void; + const closed = new Promise((resolve) => (resolveClosed = resolve)); + + const status = (): ControlStatus => ({ + pid: process.pid, + startedAt, + lastActiveAt, + idleMs: opts.idleMs, + warm: pool.filter((w) => w.ready).length, + busy, + served, + socket: opts.socket, + }); + + const writePidFile = () => { + const tmp = `${opts.pidFile}.${process.pid}.tmp`; + try { + writeFileSync(tmp, JSON.stringify({ pid: process.pid, socket: opts.socket, startedAt }), { mode: 0o600 }); + renameSync(tmp, opts.pidFile); + } catch {} + }; + writePidFile(); + + const ownsSocket = () => socketInode != null && inodeOf(opts.socket) === socketInode; + + function spawnWorker(): void { + if (stopping) return; + let child: ChildProcess; + try { + child = opts.spawnWorker(); + } catch { + onSpawnFailure(); + return; + } + const worker: Worker = { child, ready: false }; + pool.push(worker); + // Anything a worker prints before it is assigned is load noise. + child.stdout?.on("data", () => {}); + child.stderr?.on("data", () => {}); + child.on("message", (msg: { t?: string }) => { + if (msg?.t !== "ready" || worker.ready) return; + worker.ready = true; + spawnFailures = 0; + const waiter = waiting.shift(); + if (waiter) { + removeFromPool(worker); + waiter(worker); + refill(); + } + }); + child.on("exit", () => { + if (!pool.includes(worker)) return; + removeFromPool(worker); + if (!worker.ready) onSpawnFailure(); + else refill(); + }); + child.on("error", () => {}); + } + + function onSpawnFailure(): void { + spawnFailures++; + if (spawnFailures >= MAX_SPAWN_FAILURES) { + // Workers can't load (broken dist?). Send everyone in-process. + for (const waiter of waiting.splice(0)) waiter(null); + shutdown("workers failing to start"); + return; + } + if (waiting.length > 0) refill(); + } + + function removeFromPool(worker: Worker): void { + const i = pool.indexOf(worker); + if (i >= 0) pool.splice(i, 1); + } + + function refill(): void { + if (stopping) return; + const want = opts.poolSize + Math.max(0, waiting.length - pool.filter((w) => w.ready).length); + while (pool.length < want) spawnWorker(); + } + + function acquire(): Promise { + const ready = pool.find((w) => w.ready); + if (ready) { + removeFromPool(ready); + refill(); + return Promise.resolve(ready); + } + return new Promise((resolve) => { + waiting.push(resolve); + refill(); + }); + } + + function release(worker: Worker): void { + // A pristine worker whose caller went away goes back to the pool. + if (stopping || pool.length >= opts.poolSize) worker.child.kill("SIGTERM"); + else pool.unshift(worker); + } + + async function runJob(conn: Socket, msg: Extract): Promise { + const mismatch = fingerprintMismatch(opts.fingerprint, msg.fingerprint); + if (mismatch) { + conn.end(encodeJson({ t: "bypass", reason: `fingerprint:${mismatch}` })); + if (isStaleBuild(mismatch)) shutdown("dist rebuilt"); + return; + } + if (stopping) { + conn.end(encodeJson({ t: "bypass", reason: "stopping" })); + return; + } + busy++; + lastActiveAt = Date.now(); + conn.write(encodeJson({ t: "accepted" })); + let clientGone = false; + let child: ChildProcess | null = null; + const pendingSignals: string[] = []; + conn.on("close", () => { + clientGone = true; + // The caller died mid-command (e.g. SIGKILL): don't leave it running. + child?.kill("SIGTERM"); + }); + conn.on("error", () => {}); + const onClientMessage = (m: ControlMessage) => { + if (m.t !== "signal" || !FORWARDED_SIGNALS.includes(m.signal)) return; + if (child) child.kill(m.signal); + else pendingSignals.push(m.signal); + }; + jobListeners.set(conn, onClientMessage); + + const worker = await acquire(); + if (!worker) { + busy--; + if (!clientGone) conn.end(encodeJson({ t: "exit", code: 1, signal: null })); + return; + } + if (clientGone) { + busy--; + release(worker); + maybeFinishStop(); + return; + } + child = worker.child; + busyChildren.add(child); + served++; + child.stdout?.removeAllListeners("data"); + child.stderr?.removeAllListeners("data"); + child.stdout?.on("data", (chunk: Buffer) => { + if (!clientGone) conn.write(encodeFrame(FRAME_STDOUT, chunk)); + }); + child.stderr?.on("data", (chunk: Buffer) => { + if (!clientGone) conn.write(encodeFrame(FRAME_STDERR, chunk)); + }); + child.removeAllListeners("exit"); + child.once("close", (code, signal) => { + busyChildren.delete(child!); + busy--; + lastActiveAt = Date.now(); + if (!clientGone) conn.end(encodeJson({ t: "exit", code, signal })); + maybeFinishStop(); + }); + const { t: _t, fingerprint: _fp, ...payload } = msg; + child.send({ t: "run", ...payload }); + for (const sig of pendingSignals) child.kill(sig as NodeJS.Signals); + } + + const jobListeners = new WeakMap void>(); + + server.on("connection", (conn) => { + const decoder = new FrameDecoder(); + let first = true; + conn.on("error", () => {}); + conn.on("data", (chunk) => { + let frames; + try { + frames = decoder.push(chunk); + } catch { + conn.destroy(); + return; + } + for (const frame of frames) { + const msg = parseJsonFrame(frame); + if (!msg) continue; + if (!first) { + jobListeners.get(conn)?.(msg); + continue; + } + first = false; + if (msg.t === "ping") conn.end(encodeJson({ t: "pong", status: status() })); + else if (msg.t === "stop") { + conn.end(encodeJson({ t: "stopping" })); + shutdown("stop requested"); + } else if (msg.t === "run") void runJob(conn, msg); + else conn.destroy(); + } + }); + }); + + const checkMs = opts.checkIntervalMs ?? Math.max(50, Math.min(1000, Math.floor(opts.idleMs / 4))); + const timer = setInterval(() => { + if (!ownsSocket()) { + // Another daemon replaced our socket (or it was deleted): nobody can + // reach us any more. + shutdown("socket taken over", { unlink: false }); + return; + } + if (busy === 0 && waiting.length === 0 && Date.now() - lastActiveAt >= opts.idleMs) shutdown("idle"); + }, checkMs); + + let unlinkOnExit = true; + function shutdown(_reason: string, o: { unlink?: boolean } = {}): void { + if (o.unlink === false) unlinkOnExit = false; + if (stopping) return; + stopping = true; + clearInterval(timer); + server.close(); + if (unlinkOnExit && ownsSocket()) { + try { + unlinkSync(opts.socket); + } catch {} + } + if (unlinkOnExit) { + try { + unlinkSync(opts.pidFile); + } catch {} + } + for (const waiter of waiting.splice(0)) waiter(null); + for (const w of pool.splice(0)) w.child.kill("SIGTERM"); + maybeFinishStop(); + } + + function maybeFinishStop(): void { + if (stopping && busy === 0 && busyChildren.size === 0) resolveClosed(); + } + + refill(); + return { closed, stop: (reason) => shutdown(reason) }; +} + +/** Entry for `node serve-sim.js __control-daemon`. */ +export async function runControlDaemonProcess(opts: { + binFile: string; + socket: string; + pidFile: string; + fingerprint: ControlFingerprint; + idleMs: number; + poolSize: number; + roleEnv: string; +}): Promise { + // Don't pin whatever directory the first caller happened to be in. + try { + process.chdir("/"); + } catch {} + const daemon = await startControlDaemon({ + socket: opts.socket, + pidFile: opts.pidFile, + fingerprint: opts.fingerprint, + idleMs: opts.idleMs, + poolSize: opts.poolSize, + spawnWorker: () => + spawn(process.execPath, [opts.binFile], { + cwd: "/", + env: { ...process.env, [opts.roleEnv]: "worker" }, + stdio: ["ignore", "pipe", "pipe", "ipc"], + }), + }); + if (!daemon) return; // another daemon already owns the socket + process.on("SIGTERM", () => daemon.stop("SIGTERM")); + process.on("SIGINT", () => daemon.stop("SIGINT")); + process.on("SIGHUP", () => {}); + await daemon.closed; + process.exit(0); +} diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts new file mode 100644 index 000000000..7f7810de7 --- /dev/null +++ b/packages/serve-sim/src/control-protocol.ts @@ -0,0 +1,283 @@ +/** + * Shared pieces of the persistent control process: which commands it may + * run, where its socket lives, the wire framing, and the fingerprint that + * decides whether a warm worker matches the caller. + * + * This file is imported by the tiny bin entry (src/bin.ts), so it must only + * pull in node builtins — anything heavier defeats the point. + */ +import { createHash } from "crypto"; +import { statSync } from "fs"; +import { homedir, tmpdir } from "os"; +import { join } from "path"; + +const CONTROL_PROTOCOL = 1; +/** argv[2] marker for the daemon process (visible in `ps`). */ +export const CONTROL_DAEMON_ARG = "__control-daemon"; +/** Set on pre-warmed worker processes; stripped before the command runs. */ +export const CONTROL_ROLE_ENV = "SERVE_SIM_CONTROL_ROLE"; +/** `0`/`off` disables the control process; `1`/`on` auto-starts even in CI. */ +const CONTROL_ENV = "SERVE_SIM_CONTROL"; +/** Quiet period before the daemon exits on its own (ms). */ +export const CONTROL_IDLE_ENV = "SERVE_SIM_CONTROL_IDLE_MS"; +/** Override the socket/pid directory (tests, unusual TMPDIRs). */ +export const CONTROL_DIR_ENV = "SERVE_SIM_CONTROL_DIR"; +const DEFAULT_IDLE_MS = 5 * 60_000; +/** Warm workers kept ready; each is single-use, then replaced. */ +export const DEFAULT_POOL_SIZE = 2; + +/** + * Short, one-shot commands that only talk to a running preview server and + * print a result. Anything that starts servers, injects into apps, records, + * reads stdin or runs an interactive shell keeps running in-process. + */ +const DISPATCHABLE_COMMANDS: ReadonlySet = new Set([ + "tap", + "gesture", + "settle", + "button", + "type", + "paste", + "rotate", + "fold", + "ca-debug", + "memory-warning", + "event-log", + "ax", + "buffer", +]); + +const ROOT_INFO_FLAGS = new Set(["--help", "-h", "--version", "-v"]); + +/** Whether `args` (argv after the script) may run in a warm worker. */ +export function isDispatchable(args: readonly string[]): boolean { + const [first] = args; + if (first == null) return false; // bare `serve-sim` starts the preview server + if (args.length === 1 && ROOT_INFO_FLAGS.has(first)) return true; + if (first === "help") return args.length <= 2; + if (!DISPATCHABLE_COMMANDS.has(first)) return false; + // stdin is not forwarded to workers. + if (args.includes("--stdin")) return false; + return true; +} + +export type ControlMode = "off" | "use" | "auto"; + +/** + * off: never touch the control process. use: dispatch to one that is already + * running but never start one (the default under CI, so jobs don't leave a + * daemon behind). auto: dispatch, and start one in the background if absent. + */ +export function controlMode(env: NodeJS.ProcessEnv): ControlMode { + const raw = env[CONTROL_ENV]?.trim().toLowerCase(); + if (raw === "0" || raw === "false" || raw === "off" || raw === "no") return "off"; + if (raw === "1" || raw === "true" || raw === "on" || raw === "yes") return "auto"; + const ci = env.CI?.trim().toLowerCase(); + if (ci && ci !== "0" && ci !== "false") return "use"; + return "auto"; +} + +export function parseIdleMs(raw: string | undefined): number { + if (raw == null || raw.trim() === "") return DEFAULT_IDLE_MS; + const n = Number(raw); + return Number.isFinite(n) && n >= 100 ? Math.floor(n) : DEFAULT_IDLE_MS; +} + +export interface ControlPaths { + dir: string; + socket: string; + pidFile: string; +} + +/** + * One daemon per (bin file, node binary, HOME): different installs or node + * versions never share warm workers. + */ +export function controlPaths(opts: { + binFile: string; + execPath: string; + env: NodeJS.ProcessEnv; +}): ControlPaths { + const dir = opts.env[CONTROL_DIR_ENV] || join(tmpdir(), "serve-sim"); + const id = createHash("sha256") + .update(`${opts.binFile}\0${opts.execPath}\0${opts.env.HOME ?? homedir()}`) + .digest("hex") + .slice(0, 12); + return { + dir, + socket: join(dir, `control-${id}.sock`), + pidFile: join(dir, `control-${id}.json`), + }; +} + +/** + * What a warm worker baked in at load time. The main bundle reads HOME and + * TMPDIR into module constants and `debug` reads DEBUG on import, so a caller + * whose values differ must run in-process. The mtimes catch a rebuilt dist + * under a still-running daemon. + */ +export interface ControlFingerprint { + protocol: number; + execPath: string; + home: string; + tmpdir: string; + debug: string; + binMtimeMs: number; + mainMtimeMs: number; +} + +function mtimeMs(file: string): number { + try { + return statSync(file).mtimeMs; + } catch { + return -1; + } +} + +export function controlFingerprint(opts: { + binFile: string; + mainFile: string; + execPath: string; + env: NodeJS.ProcessEnv; +}): ControlFingerprint { + return { + protocol: CONTROL_PROTOCOL, + execPath: opts.execPath, + home: opts.env.HOME ?? "", + tmpdir: opts.env.TMPDIR ?? "", + debug: opts.env.DEBUG ?? "", + binMtimeMs: mtimeMs(opts.binFile), + mainMtimeMs: mtimeMs(opts.mainFile), + }; +} + +/** First differing field, or null when the worker matches the caller. */ +export function fingerprintMismatch( + daemon: ControlFingerprint, + caller: ControlFingerprint, +): keyof ControlFingerprint | null { + for (const key of Object.keys(daemon) as (keyof ControlFingerprint)[]) { + if (daemon[key] !== caller[key]) return key; + } + return null; +} + +/** A rebuilt dist means the daemon itself is stale and should go away. */ +export function isStaleBuild(field: keyof ControlFingerprint | null): boolean { + return field === "binMtimeMs" || field === "mainMtimeMs" || field === "protocol"; +} + +// ─── Wire framing ──────────────────────────────────────────────────────── +// [type u8][length u32 BE][payload]. JSON frames carry control messages; +// stdout/stderr frames carry raw command output bytes. + +export const FRAME_JSON = 0x4a; // J +export const FRAME_STDOUT = 0x4f; // O +export const FRAME_STDERR = 0x45; // E +const MAX_FRAME_BYTES = 64 * 1024 * 1024; + +export function encodeFrame(type: number, payload: Buffer | string): Buffer { + const body = typeof payload === "string" ? Buffer.from(payload) : payload; + const header = Buffer.allocUnsafe(5); + header.writeUInt8(type, 0); + header.writeUInt32BE(body.length, 1); + return Buffer.concat([header, body]); +} + +export function encodeJson(message: ControlMessage): Buffer { + return encodeFrame(FRAME_JSON, JSON.stringify(message)); +} + +export interface Frame { + type: number; + payload: Buffer; +} + +export class FrameDecoder { + private buffer: Buffer = Buffer.alloc(0); + + push(chunk: Buffer | string): Frame[] { + const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk; + this.buffer = this.buffer.length === 0 ? bytes : Buffer.concat([this.buffer, bytes]); + const frames: Frame[] = []; + while (this.buffer.length >= 5) { + const length = this.buffer.readUInt32BE(1); + if (length > MAX_FRAME_BYTES) throw new Error(`control frame too large (${length} bytes)`); + if (this.buffer.length < 5 + length) break; + frames.push({ + type: this.buffer.readUInt8(0), + payload: this.buffer.subarray(5, 5 + length), + }); + this.buffer = this.buffer.subarray(5 + length); + } + return frames; + } +} + +export interface StreamTty { + isTTY: boolean; + columns?: number; +} + +export const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const; +export type ForwardedSignal = (typeof FORWARDED_SIGNALS)[number]; + +export type ControlMessage = + | { + t: "run"; + fingerprint: ControlFingerprint; + argv: string[]; + cwd: string; + env: Record; + tty: { stdout: StreamTty; stderr: StreamTty }; + } + | { t: "signal"; signal: ForwardedSignal } + | { t: "ping" } + | { t: "stop" } + | { t: "accepted" } + | { t: "bypass"; reason: string } + | { t: "exit"; code: number | null; signal: string | null } + | { t: "pong"; status: ControlStatus } + | { t: "stopping" }; + +export interface ControlStatus { + pid: number; + startedAt: number; + lastActiveAt: number; + idleMs: number; + warm: number; + busy: number; + served: number; + socket: string; +} + +export function parseJsonFrame(frame: Frame): ControlMessage | null { + if (frame.type !== FRAME_JSON) return null; + try { + const value = JSON.parse(frame.payload.toString("utf8")) as ControlMessage; + return value && typeof value === "object" && typeof value.t === "string" ? value : null; + } catch { + return null; + } +} + +// ─── Deferred main ─────────────────────────────────────────────────────── +// A warm worker imports the full CLI bundle ahead of time; the bundle hands +// its entry point back instead of parsing argv right away. + +const DEFER_KEY = Symbol.for("serve-sim.control.defer-main"); +type DeferredMain = () => Promise; + +/** Called by the CLI bundle in place of `await main()`. */ +export async function runCliMain(main: DeferredMain): Promise { + const hook = (globalThis as Record)[DEFER_KEY]; + if (typeof hook === "function") { + (hook as (main: DeferredMain) => void)(main); + return; + } + await main(); +} + +export function deferCliMain(capture: (main: DeferredMain) => void): void { + (globalThis as Record)[DEFER_KEY] = capture; +} diff --git a/packages/serve-sim/src/control-worker.ts b/packages/serve-sim/src/control-worker.ts new file mode 100644 index 000000000..aac7f9088 --- /dev/null +++ b/packages/serve-sim/src/control-worker.ts @@ -0,0 +1,74 @@ +/** + * A pre-warmed, single-use worker. It loads the full CLI bundle ahead of time + * (that load is most of a cold `serve-sim` call), tells the daemon it is + * ready, then waits for one command: it adopts the caller's argv, cwd, env + * and TTY shape, runs the CLI exactly as the normal bin would, and exits. + * + * Because every command still gets its own process, `process.exit`, exit + * codes, signal handlers and module state behave as in a direct run. + */ +import { CONTROL_ROLE_ENV, deferCliMain, type ControlMessage, type StreamTty } from "./control-protocol"; + +type RunMessage = Extract; + +function adoptTty(stream: NodeJS.WriteStream, tty: StreamTty | undefined): void { + if (!tty?.isTTY) return; + // Help wrapping and a couple of commands key off these; the stream itself + // is a pipe to the daemon, so don't fake any TTY methods. + Object.defineProperty(stream, "isTTY", { value: true, configurable: true }); + if (tty.columns) Object.defineProperty(stream, "columns", { value: tty.columns, configurable: true }); +} + +export function adoptCaller(message: RunMessage, proc: NodeJS.Process = process): void { + proc.chdir(message.cwd); + for (const key of Object.keys(proc.env)) { + if (!(key in message.env)) delete proc.env[key]; + } + Object.assign(proc.env, message.env); + proc.argv.splice(2, proc.argv.length - 2, ...message.argv); + adoptTty(proc.stdout, message.tty.stdout); + adoptTty(proc.stderr, message.tty.stderr); +} + +export async function runControlWorker(mainUrl: string): Promise { + delete process.env[CONTROL_ROLE_ENV]; + const send = process.send?.bind(process); + if (!send) { + console.error("serve-sim: control worker needs an IPC channel"); + process.exit(70); + } + // While idle, follow the daemon down. + const onDisconnect = () => process.exit(0); + process.on("disconnect", onDisconnect); + + let main: (() => Promise) | null = null; + deferCliMain((m) => { + main = m; + }); + await import(mainUrl); + const run = main as (() => Promise) | null; + if (!run) { + console.error("serve-sim: CLI bundle did not hand back its entry point"); + process.exit(70); + } + + process.once("message", (message: ControlMessage) => { + if (message?.t !== "run") process.exit(70); + try { + adoptCaller(message); + } catch (error) { + console.error(`serve-sim: ${(error as Error).message}`); + process.exit(1); + } + // Drop the IPC channel so the event loop drains like a normal run. + process.off("disconnect", onDisconnect); + process.disconnect?.(); + run().catch((error) => { + // Same as an uncaught top-level await rejection: stack on stderr, exit 1. + setImmediate(() => { + throw error; + }); + }); + }); + send({ t: "ready" }); +} diff --git a/packages/serve-sim/src/index.ts b/packages/serve-sim/src/index.ts index 6ce5013a1..655efc9c2 100755 --- a/packages/serve-sim/src/index.ts +++ b/packages/serve-sim/src/index.ts @@ -107,6 +107,7 @@ import { import { redactHome } from "./diagnostics-redact"; import { BUFFER_VERBS, runBufferCommand, startBufferOnReusedServer, type BufferCliOptions, type BufferVerb } from "./buffer-cli"; import { ROLLING_BUFFER_ENV, parseRollingBufferEnv } from "./rolling-buffer"; +import { runCliMain } from "./control-protocol"; // `import.meta.dir` is Bun-only; resolve once via fileURLToPath so the bundled // CLI works under plain `node` too. @@ -2974,6 +2975,19 @@ program .argument("[args...]") .action((args: string[]) => uiSettings(args)); +// Handled by the node bin (src/bin.ts) before this bundle loads; registered +// here so it shows in --help and explains itself in other builds. +program + .command("control") + .description("Persistent control process that keeps short commands fast (status|start|stop)") + .allowUnknownOption(true) + .helpOption(false) + .argument("[args...]") + .action(() => { + console.error("serve-sim: the control process is only available from the node bin (dist/serve-sim.js)."); + process.exit(1); + }); + // Settle the device set before any command runs. Commander matches the root // --device-set after a subcommand's name too. program.hook("preAction", () => { @@ -2984,4 +2998,4 @@ program.hook("preAction", () => { process.exit(1); } }); -await program.parseAsync(process.argv); +await runCliMain(() => program.parseAsync(process.argv)); From 7a7181684a15bb48cf47acb1cacd715d79be7fa0 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 11:34:25 -0800 Subject: [PATCH 02/17] feat(cli): report warming workers in serve-sim control status --- packages/serve-sim/src/control-client.ts | 2 +- packages/serve-sim/src/control-daemon.ts | 1 + packages/serve-sim/src/control-protocol.ts | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index 1f779dee4..7687f6976 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -250,7 +250,7 @@ async function waitFor(probe: () => Promise, timeoutMs: number): Pr function formatStatus(s: ControlStatus): string { const idleLeft = Math.max(0, s.idleMs - (Date.now() - s.lastActiveAt)); return ( - `control process running (pid ${s.pid}): ${s.warm} warm, ${s.busy} busy, ` + + `control process running (pid ${s.pid}): ${s.warm} warm, ${s.warming} warming, ${s.busy} busy, ` + `${s.served} served; idle exit in ${Math.ceil(idleLeft / 1000)}s\n socket ${s.socket}` ); } diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts index 51a832f12..67869e6c2 100644 --- a/packages/serve-sim/src/control-daemon.ts +++ b/packages/serve-sim/src/control-daemon.ts @@ -150,6 +150,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise w.ready).length, + warming: pool.filter((w) => !w.ready).length, busy, served, socket: opts.socket, diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts index 7f7810de7..2bc851458 100644 --- a/packages/serve-sim/src/control-protocol.ts +++ b/packages/serve-sim/src/control-protocol.ts @@ -246,6 +246,7 @@ export interface ControlStatus { lastActiveAt: number; idleMs: number; warm: number; + warming: number; busy: number; served: number; socket: string; From 90948a10f0a606d3b0d53459e5bdb5633bf3c81a Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 11:34:25 -0800 Subject: [PATCH 03/17] docs: document the control process, its fallbacks, and before/after latency --- packages/serve-sim/README.md | 44 ++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/packages/serve-sim/README.md b/packages/serve-sim/README.md index f6c543660..7aa36df18 100644 --- a/packages/serve-sim/README.md +++ b/packages/serve-sim/README.md @@ -135,6 +135,8 @@ serve-sim ax --refs [--all] [--text] Compact snapshot with element refs (@e1… serve-sim tap @e2 [--settle] [--timeout ] Tap an element ref; --settle prints the diff serve-sim settle [--timeout ] Wait for the screen to settle; print the diff +serve-sim control [status|start|stop] Persistent control process that keeps short + commands fast (automatic; see below) serve-sim camera [-d udid] [source-options] Inject a synthetic camera feed and (re)launch the app @@ -357,6 +359,48 @@ HTTP, under the same device helper routes and auth as `/recording` (`--auth-toke Limits: sampling at 4 fps can miss a state shown for less than a tick (record for frame-exact history). Frames are the raw framebuffer orientation, like the stream before rotation. When serve-sim is embedded as middleware, `SERVE_SIM_BUFFER` in the dev server's environment starts the buffer when a device's session opens (its first viewer or command), not at startup. +### Control process (faster repeated commands) + +Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now a 14 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. + +- **Which commands**: `tap`, `gesture`, `settle`, `button`, `type`, `paste`, `rotate`, `fold`, `ca-debug`, `memory-warning`, `event-log`, `ax`, `buffer`, and bare `--help`/`--version`. Everything else runs in-process as before: the preview server, `--detach`, `record`, `camera`, `exec`, `doctor`, `permissions`, `ui`, and anything with `--stdin` (stdin is not forwarded). +- **What carries over**: argv, cwd, the full environment, stdout/stderr (as separate streams), the exit code or signal, and whether stdout/stderr are TTYs plus their column width. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker. If the caller dies, its worker is stopped. +- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, or that use a different node binary or install, always run in-process. +- **Fallback**: if the control process is missing, stale, or doesn't accept a command within 1 s, the command runs in-process. Once it has accepted a command, a lost connection fails that call (exit 1) instead of running the command twice. +- **Off switch**: `SERVE_SIM_CONTROL=0` never uses or starts it. Under `CI` it is only used if already running; `SERVE_SIM_CONTROL=1` auto-starts it there too. + +```sh +serve-sim control status [--json] # exit 1 when not running +serve-sim control start # idempotent; waits until it answers +serve-sim control stop # idempotent; also clears stale socket/pid files +``` + +It listens on a Unix socket (mode 0600) at `$TMPDIR/serve-sim/control-.sock`, with a pid file next to it. `` is derived from the bin path, the node binary, and `HOME`. A daemon that finds a dead socket replaces it. When several start at once, the extra ones see their socket was taken over and exit. + +Measured on an Apple Silicon Mac with Node 24.13: each case was spawned with `spawnSync` from a node script, after 3 warm-up runs. Back-to-back means calls ran one after another. "Before" runs the full CLI bundle directly, which is what the bin was before this change. `tap` ran against a live preview on its own simulator. + +| case | p50 ms | p95 ms | +|---|---|---| +| `node -e 0` (floor) | 23.1 | 27.1 | +| `--help`, before | 66.2 | 82.7 | +| `--help`, warm control process | 31.9 | 32.8 | +| `--help`, first call with no daemon (starts it) | 76.0 | 81.7 | +| `--help`, the call right after that | 51.1 | 54.2 | +| `tap`, before | 113.3 | 119.4 | +| `tap`, warm control process | 84.8 | 86.6 | +| `tap`, first call with no daemon (starts it) | 114.0 | 121.2 | +| `tap`, the call right after that | 86.6 | 89.6 | + +With calls spaced 400 ms apart, a more agent-like pace, everything is slower, including bare Node (p50 38 ms). The saving stays about the same: `--help` drops from 72.5 to 44.5 ms and `tap` from 132.1 to 105.9 ms. + +Where the warm time goes: + +- About 23 ms is Node's own startup, which can't be avoided. +- About 9 ms is the bin, the socket round trip, the worker running the command, and the worker's exit. +- For `tap`, about 40 ms more is spent waiting on the preview server for the touch-config fetch, the WebSocket connect, and the HID ack. + +The first call with no daemon running costs about 10 ms extra. That is the daemon spawn, plus its workers competing with the command for CPU. + ### Accessibility refs for agents `serve-sim ax --refs` prints a compact snapshot of the visible screen: each interesting element gets a short ref (`@e1`, `@e2`, …, in tree order), its role, label, value (when set), `enabled: false` (only when disabled), and its frame and center in device points. `--all` includes offscreen elements; `--text` prints one line per element. From 6ca270ea3c5b19bb0fbfbd1c88c34acd5189b652 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 16:32:27 -0800 Subject: [PATCH 04/17] fix(control): hand off only after go, verify socket ownership, harden workers Review fixes for the persistent control process. - Two-phase start: the daemon reserves a warm worker, replies `accepted`, and only gives the worker the command after the client's `go`. The client's accept timer can only fire before `go`, so a timed-out call runs in-process without the worker also running it. After `go` the client never falls back. A held worker whose caller leaves goes back to the pool. - Ownership: the default dir is now $TMPDIR/serve-sim-control-. Client and daemon lstat the dir (ours, no group/other bits, not a symlink) and the client lstats the socket (a socket we own, not a symlink) before sending anything; otherwise it runs in-process and the daemon refuses to start. The socket is bound under umask 077. - No worker after a call arrives is a bypass, not a silent exit 1. Workers that can't load write a .failed marker with their output; callers then don't respawn a daemon for 10 minutes or until the dist changes. `control start` waits for a warm worker and prints the load error otherwise. Early load failures refill with a short backoff. Queued replies are flushed before the daemon exits, after running commands finish. - Workers write stdout/stderr synchronously, so write + process.exit no longer truncates at 64 KB. When the caller's fd 1 and 2 are the same file the worker sends stderr down the stdout pipe to keep `2>&1` order. - NODE_OPTIONS, NODE_EXTRA_CA_CERTS and NODE_USE_ENV_PROXY are stripped from the daemon and worker env; callers that set them or pass node flags run in-process. - bin.ts reads cwd lazily, so a deleted cwd no longer crashes every command; the dispatch path bypasses instead. - The daemon re-checks isDispatchable, keeps a 0-column TTY width, and `control start` says why it can't start (long socket path, unsafe dir). - SERVE_SIM_CONTROL_ACCEPT_MS overrides the 1 s accept window; tests use it so slow CI doesn't turn dispatches into in-process runs, and the converge test polls for one daemon instead of sleeping. --- .../src/__tests__/control-process.test.ts | 364 +++++++++++++++++- .../__tests__/fixtures/control-fake-cli.ts | 30 ++ .../__tests__/fixtures/control-race-driver.ts | 31 ++ packages/serve-sim/src/bin.ts | 10 +- packages/serve-sim/src/control-client.ts | 199 ++++++++-- packages/serve-sim/src/control-daemon.ts | 280 +++++++++----- packages/serve-sim/src/control-protocol.ts | 89 ++++- packages/serve-sim/src/control-worker.ts | 25 +- 8 files changed, 879 insertions(+), 149 deletions(-) create mode 100644 packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index 76fd89915..0ddaf6b05 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -1,6 +1,18 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test"; import { spawn, spawnSync, type ChildProcess } from "child_process"; -import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, utimesSync, writeFileSync } from "fs"; +import { + chmodSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + realpathSync, + rmSync, + statSync, + symlinkSync, + utimesSync, + writeFileSync, +} from "fs"; import { join } from "path"; import { CONTROL_DIR_ENV, @@ -15,8 +27,13 @@ import { fingerprintMismatch, isDispatchable, isStaleBuild, + nodeRuntimeOverride, + parseAcceptMs, parseIdleMs, parseJsonFrame, + unsafeControlDir, + unsafeControlSocket, + withoutNodeRuntimeEnv, type ControlMessage, } from "../control-protocol"; import { adoptCaller } from "../control-worker"; @@ -63,6 +80,62 @@ describe("controlMode", () => { expect(parseIdleMs("2000")).toBe(2000); expect(parseIdleMs("nope")).toBe(300_000); expect(parseIdleMs("5")).toBe(300_000); + expect(parseAcceptMs(undefined)).toBe(1000); + expect(parseAcceptMs("30000")).toBe(30000); + expect(parseAcceptMs("-1")).toBe(1000); + }); + + test("node runtime settings are stripped from workers and force in-process", () => { + expect(withoutNodeRuntimeEnv({ NODE_OPTIONS: "--require x", NODE_EXTRA_CA_CERTS: "/ca", KEEP: "1" })).toEqual({ + KEEP: "1", + }); + expect(nodeRuntimeOverride({}, [])).toBeNull(); + expect(nodeRuntimeOverride({ NODE_OPTIONS: "" }, [])).toBeNull(); + expect(nodeRuntimeOverride({ NODE_USE_ENV_PROXY: "1" }, [])).toBe("NODE_USE_ENV_PROXY"); + expect(nodeRuntimeOverride({}, ["--inspect"])).toBe("execArgv"); + }); +}); + +describe("control dir and socket ownership", () => { + test("default dir is per uid", () => { + const p = controlPaths({ binFile: "/a", execPath: "/n", env: { HOME: "/h" } }); + expect(p.dir.endsWith(`serve-sim-control-${process.getuid!()}`)).toBe(true); + }); + + test("rejects missing, group/other-writable, symlinked and foreign-owned dirs", () => { + const base = realpathSync(mkdtempSync("/tmp/ssctl-own-")); + try { + const ok = join(base, "ok"); + mkdirSync(ok, { mode: 0o700 }); + expect(unsafeControlDir(ok)).toBeNull(); + expect(unsafeControlDir(join(base, "nope"))).toBe("missing"); + const open = join(base, "open"); + mkdirSync(open); + chmodSync(open, 0o777); + expect(unsafeControlDir(open)).toMatch(/group\/other/); + chmodSync(open, 0o750); + expect(unsafeControlDir(open)).toMatch(/group\/other/); + const link = join(base, "link"); + symlinkSync(ok, link); + expect(unsafeControlDir(link)).toBe("symlink"); + const file = join(base, "file"); + writeFileSync(file, ""); + expect(unsafeControlDir(file)).toBe("not a directory"); + // Root-owned: stands in for a directory another user pre-created. + if (process.getuid!() !== 0) expect(unsafeControlDir("/")).toBe("owned by uid 0"); + expect(unsafeControlSocket(join(ok, "x.sock"))).toBe("missing"); + expect(unsafeControlSocket(file)).toBe("not a socket"); + const sockLink = join(base, "s.sock"); + symlinkSync(file, sockLink); + expect(unsafeControlSocket(sockLink)).toBe("symlink"); + // A root-owned socket, where the OS has one. + const rootSock = "/var/run/mDNSResponder"; + if (process.getuid!() !== 0 && existsSync(rootSock) && statSync(rootSock).isSocket()) { + expect(unsafeControlSocket(rootSock)).toBe("owned by uid 0"); + } + } finally { + rmSync(base, { recursive: true, force: true }); + } }); }); @@ -149,6 +222,29 @@ describe("adoptCaller", () => { expect(proc.stderr.isTTY).toBeUndefined(); rmSync(dir, { recursive: true, force: true }); }); + + test("keeps a 0-column TTY width and merges stderr into stdout for 2>&1", () => { + const writes: string[] = []; + const stdout = { write: (c: string) => writes.push(`out:${c}`) } as unknown as NodeJS.WriteStream; + const stderr = { write: (c: string) => writes.push(`err:${c}`) } as unknown as NodeJS.WriteStream; + const proc = { argv: [], env: {}, chdir: () => {}, stdout, stderr } as unknown as NodeJS.Process; + adoptCaller( + { + t: "run", + fingerprint: {} as never, + argv: [], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: true, columns: 0 }, stderr: { isTTY: true, columns: 0 } }, + sharedOutput: true, + }, + proc, + ); + expect(stdout.columns).toBe(0); + proc.stderr.write("a"); + proc.stdout.write("b"); + expect(writes).toEqual(["out:a", "out:b"]); + }); }); // ─── Real processes ────────────────────────────────────────────────────── @@ -164,6 +260,7 @@ describeWithNode("control process", () => { let dist: string; let binFile: string; let mainFile: string; + let driverFile: string; let ctlDir: string; let work: string; const stray: ChildProcess[] = []; @@ -175,12 +272,14 @@ describeWithNode("control process", () => { for (const [entry, naming] of [ [join(import.meta.dir, "../bin.ts"), "serve-sim.js"], [join(import.meta.dir, "fixtures/control-fake-cli.ts"), "serve-sim-cli.js"], + [join(import.meta.dir, "fixtures/control-race-driver.ts"), "race-driver.js"], ] as const) { const result = await Bun.build({ entrypoints: [entry], target: "node", format: "esm", outdir: dist, naming }); if (!result.success) throw new Error(result.logs.map(String).join("\n")); } binFile = join(dist, "serve-sim.js"); mainFile = join(dist, "serve-sim-cli.js"); + driverFile = join(dist, "race-driver.js"); }); beforeEach(() => { @@ -198,8 +297,15 @@ describeWithNode("control process", () => { }); function env(extra: Record = {}): NodeJS.ProcessEnv { - const e: NodeJS.ProcessEnv = { ...process.env, [CONTROL_DIR_ENV]: ctlDir, SERVE_SIM_CONTROL_IDLE_MS: "60000" }; + const e: NodeJS.ProcessEnv = { + ...process.env, + [CONTROL_DIR_ENV]: ctlDir, + SERVE_SIM_CONTROL_IDLE_MS: "60000", + // Slow CI must not turn dispatches into in-process runs. + SERVE_SIM_CONTROL_ACCEPT_MS: "30000", + }; delete e.CI; + for (const k of ["NODE_OPTIONS", "NODE_EXTRA_CA_CERTS", "NODE_USE_ENV_PROXY", "MARKER", "FAKE_WORKER_LOAD_FAIL"]) delete e[k]; delete e.SERVE_SIM_CONTROL; delete e.EXIT_CODE; for (const [k, v] of Object.entries(extra)) { @@ -209,12 +315,11 @@ describeWithNode("control process", () => { return e; } - function cli( - args: string[], - opts: { env?: Record; cwd?: string } = {}, - ): Promise<{ code: number | null; signal: string | null; stdout: string; stderr: string }> { + type Run = { code: number | null; signal: string | null; stdout: string; stderr: string }; + + function run(cmd: string, argv: string[], opts: { env?: Record; cwd?: string } = {}): Promise { return new Promise((resolve) => { - const child = spawn(nodePath!, [binFile, ...args], { cwd: opts.cwd ?? work, env: env(opts.env) }); + const child = spawn(cmd, argv, { cwd: opts.cwd ?? work, env: env(opts.env) }); let stdout = ""; let stderr = ""; child.stdout.on("data", (d) => (stdout += d)); @@ -223,6 +328,19 @@ describeWithNode("control process", () => { }); } + function cli( + args: string[], + opts: { env?: Record; cwd?: string; nodeArgs?: string[] } = {}, + ): Promise { + return run(nodePath!, [...(opts.nodeArgs ?? []), binFile, ...args], opts); + } + + const paths = () => controlPaths({ binFile, execPath: nodePath!, env: env() }); + const daemonPids = () => + spawnSync("pgrep", ["-f", `${binFile} __control-daemon`], { encoding: "utf8" }) + .stdout.split("\n") + .filter(Boolean); + async function status(): Promise<{ running: boolean; pid?: number; served?: number; warm?: number; busy?: number }> { const r = await cli(["control", "status", "--json"]); return JSON.parse(r.stdout); @@ -458,11 +576,9 @@ describeWithNode("control process", () => { const v = await status(); return v.running ? v : null; }); - await Bun.sleep(500); - const daemons = spawnSync("pgrep", ["-f", `${binFile} __control-daemon`], { encoding: "utf8" }) - .stdout.split("\n") - .filter(Boolean); - expect(daemons).toEqual([String(s.pid)]); + // Losers notice the takeover on their next ownership check. + await until(async () => daemonPids().length === 1); + expect(daemonPids()).toEqual([String(s.pid)]); }); test("rejects malformed and unknown first messages without wedging", async () => { @@ -478,4 +594,228 @@ describeWithNode("control process", () => { }); expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); }); + // ─── Review regressions ────────────────────────────────────────────── + + function race(o: { stallAfter: string; stallMs: number; acceptTimeoutMs: number; marker: string }) { + return run(nodePath!, [driverFile], { + env: { + MARKER: o.marker, + RACE_OPTS: JSON.stringify({ binFile, mainFile, argv: ["tap", "1", "1"], ...o }), + }, + }).then((r) => { + const line = r.stderr.split("\n").find((l) => l.startsWith("RESULT ")); + return { ...r, result: JSON.parse(line!.slice(7)) as { kind: string; reason?: string; code?: number; signal?: string | null } }; + }); + } + + const ranCount = (marker: string) => (existsSync(marker) ? readFileSync(marker, "utf8").split("\n").filter(Boolean).length : 0); + + test("an accept timeout that fires before go never also runs the command in a worker", async () => { + await startDaemon(); + const marker = join(work, "ran.txt"); + // The client stalls right after `run`, so by the time it looks again its + // timer has expired even though `accepted` is waiting in the buffer. + const r = await race({ stallAfter: "run", stallMs: 400, acceptTimeoutMs: 50, marker }); + expect(r.result).toEqual({ kind: "bypass", reason: "accept timeout" }); + // The held worker went back to the pool untouched. + await until(async () => { + const s = await status(); + return s.busy === 0 && (s.warm ?? 0) >= 1; + }); + expect((await status()).served).toBe(0); + expect(ranCount(marker)).toBe(0); + }); + + test("once go is sent, a stall past the timeout never falls back", async () => { + await startDaemon(); + const marker = join(work, "ran.txt"); + const r = await race({ stallAfter: "go", stallMs: 1500, acceptTimeoutMs: 1000, marker }); + expect(r.result).toEqual({ kind: "done", code: 0, signal: null }); + expect(ranCount(marker)).toBe(1); + expect((await status()).served).toBe(1); + }); + + test("refuses a group/other-writable or symlinked control dir", async () => { + chmodSync(ctlDir, 0o777); + const r = await cli(["tap", "1", "1"]); + expect(r.code).toBe(0); + expect(JSON.parse(r.stdout).argv).toEqual(["tap", "1", "1"]); + const start = await cli(["control", "start"]); + expect(start.code).toBe(1); + expect(start.stderr).toMatch(/can't start: .* group\/other accessible/); + // The daemon itself refuses too. + const direct = await cli(["__control-daemon"]); + expect(direct.code).toBe(1); + expect(direct.stderr).toMatch(/refused to start/); + await Bun.sleep(200); + expect(daemonPids()).toEqual([]); + chmodSync(ctlDir, 0o700); + + const real = mkdtempSync(join(root, "real")); + const link = join(root, `link-${Date.now()}`); + symlinkSync(real, link); + const viaLink = { env: { [CONTROL_DIR_ENV]: link } }; + expect((await cli(["control", "start"], viaLink)).stderr).toMatch(/symlink/); + expect((await cli(["tap", "1", "1"], viaLink)).code).toBe(0); + await Bun.sleep(200); + expect(daemonPids()).toEqual([]); + }); + + test("never sends a command to a planted (symlinked) socket", async () => { + const elsewhere = mkdtempSync(join(root, "e")); + const planted = join(elsewhere, "p.sock"); + const log = join(elsewhere, "received"); + const listener = spawn(nodePath!, [ + "-e", + `const fs=require("fs");require("net").createServer(c=>c.on("data",d=>fs.appendFileSync(${JSON.stringify(log)},d))).listen(${JSON.stringify(planted)},()=>console.log("up"))`, + ]); + stray.push(listener); + await new Promise((resolve) => listener.stdout.on("data", () => resolve())); + symlinkSync(planted, paths().socket); + const r = await cli(["tap", "1", "1"], { env: { SECRET_TOKEN: "hunter2" } }); + expect(r.code).toBe(0); + expect(JSON.parse(r.stdout).argv).toEqual(["tap", "1", "1"]); + await Bun.sleep(100); + expect(existsSync(log)).toBe(false); + }); + + test("binds its socket owner-only", async () => { + await startDaemon(); + expect(statSync(paths().socket).mode & 0o777).toBe(0o600); + expect(statSync(ctlDir).mode & 0o077).toBe(0); + }); + + test("workers that can't load: start fails loudly, callers run in-process, no respawn loop", async () => { + const broken = { env: { FAKE_WORKER_LOAD_FAIL: "1" } }; + const start = await cli(["control", "start"], broken); + expect(start.code).toBe(1); + expect(start.stderr).toContain("workers failed to load the CLI"); + expect(start.stderr).toContain("cannot load ws"); + expect(existsSync(paths().failFile)).toBe(true); + await until(async () => daemonPids().length === 0); + + // In-process still works, and the fail marker stops auto-start. + for (let i = 0; i < 3; i++) expect(await cli(["--version"], broken)).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); + await Bun.sleep(300); + expect(daemonPids()).toEqual([]); + + // A caller queued on such a daemon is told to bypass, not exit 1. + rmSync(paths().failFile); + const daemon = spawn(nodePath!, [binFile, "__control-daemon"], { env: env(broken.env), stdio: "ignore" }); + stray.push(daemon); + const r = await cli(["tap", "1", "1"], broken); + expect(r.code).toBe(0); + expect(JSON.parse(r.stdout).argv).toEqual(["tap", "1", "1"]); + await new Promise((res) => (daemon.exitCode != null ? res(null) : daemon.on("close", res))); + }); + + test("a write over 64 KB followed by process.exit arrives intact", async () => { + await startDaemon(); + const r = await cli(["event-log", "500000"]); + expect(r.code).toBe(0); + expect(r.stdout.length).toBe(500_000); + expect((await status()).served).toBe(1); + }); + + test("keeps stdout/stderr order under 2>&1", async () => { + const daemon = await startDaemon(); + const expected = Array.from({ length: 40 }, (_, i) => `out${i}\nerr${i}\n`).join("") + `ppid ${daemon.pid}\n`; + for (let i = 0; i < 3; i++) { + const r = await run("/bin/sh", ["-c", `exec "$0" "$1" gesture 2>&1`, nodePath!, binFile]); + expect(r.stdout).toBe(expected); + } + // Separate streams stay separate. + const split = await cli(["gesture"]); + expect(split.stderr).toBe(Array.from({ length: 40 }, (_, i) => `err${i}\n`).join("")); + }); + + test("the first caller's NODE_OPTIONS doesn't leak; callers with node flags run in-process", async () => { + const pre = join(work, "pre.cjs"); + writeFileSync(pre, `globalThis.__pre = "preloaded-by-first-caller";`); + const withPre = { env: { NODE_OPTIONS: `--require ${pre}` } }; + const start = await cli(["control", "start", "--json"], withPre); + expect(start.code).toBe(0); + const { pid } = JSON.parse(start.stdout); + await warm(); + const plain = JSON.parse((await cli(["buffer"])).stdout); + expect(plain).toMatchObject({ pre: null, nodeOptions: null, ppid: pid }); + const own = JSON.parse((await cli(["buffer"], withPre)).stdout); + expect(own.pre).toBe("preloaded-by-first-caller"); + expect(own.ppid).not.toBe(pid); + const flagged = JSON.parse((await cli(["buffer"], { nodeArgs: ["--no-warnings"] })).stdout); + expect(flagged.execArgv).toEqual(["--no-warnings"]); + expect(flagged.ppid).not.toBe(pid); + }); + + test("works from a deleted cwd, with and without the control process", async () => { + const gone = join(work, "gone"); + const script = `mkdir "$2" && cd "$2" && rmdir "$2" && exec "$0" "$1" --version`; + for (const extra of [{ SERVE_SIM_CONTROL: "0" }, {}]) { + const r = await run("/bin/sh", ["-c", script, nodePath!, binFile, gone], { env: extra }); + expect(r).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); + } + await startDaemon(); + const r = await run("/bin/sh", ["-c", script, nodePath!, binFile, gone]); + expect(r).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); + }); + + test("the daemon re-checks that a command may run in a worker", async () => { + await startDaemon(); + const { createConnection } = await import("net"); + const fp = controlFingerprint({ binFile, mainFile, execPath: nodePath!, env: env() }); + const reply = await new Promise((resolve) => { + const c = createConnection(paths().socket); + let data = Buffer.alloc(0); + c.on("connect", () => + c.write( + encodeJson({ + t: "run", + fingerprint: fp, + argv: ["--port", "3412"], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: false }, stderr: { isTTY: false } }, + }), + ), + ); + c.on("data", (d) => (data = Buffer.concat([data, Buffer.from(d)]))); + c.on("close", () => resolve(new FrameDecoder().push(data).map((f) => f.payload.toString()).join(""))); + }); + expect(JSON.parse(reply)).toEqual({ t: "bypass", reason: "not dispatchable" }); + expect((await status()).busy).toBe(0); + }); + test("a stop request lets a running command finish", async () => { + const daemon = await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + let stdout = ""; + await new Promise((resolve) => + child.stdout.on("data", (d) => { + stdout += d; + if (stdout.includes("waiting")) resolve(); + }), + ); + const { createConnection } = await import("net"); + await new Promise((resolve) => { + const c = createConnection(paths().socket); + c.on("connect", () => c.write(encodeJson({ t: "stop" }))); + c.resume(); + c.on("close", () => resolve()); + }); + // Longer than the daemon's reply-drain window. + await Bun.sleep(1500); + expect(child.exitCode).toBeNull(); + child.kill("SIGINT"); + const code = await new Promise((r) => child.on("close", (c) => r(c))); + expect(code).toBe(130); + expect(stdout).toBe("waiting\ngot SIGINT\n"); + await until(async () => { + try { + process.kill(daemon.pid, 0); + return false; + } catch { + return true; + } + }); + }); }); diff --git a/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts index 5494f60ff..977a8723f 100644 --- a/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts +++ b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts @@ -1,7 +1,12 @@ // Stand-in for dist/serve-sim-cli.js in control-process tests: built next to // a real bin build, it reports what the process it ran in looked like. +import { appendFileSync } from "fs"; import { runCliMain } from "../../control-protocol"; +// Simulates an install whose bundle can't load in a worker (only workers +// have an IPC channel), while direct runs still work. +if (process.env.FAKE_WORKER_LOAD_FAIL === "1" && process.send) throw new Error("cannot load ws"); + async function main() { const [command, ...rest] = process.argv.slice(2); if (command === "--version") { @@ -9,6 +14,7 @@ async function main() { return; } if (command === "tap") { + if (process.env.MARKER) appendFileSync(process.env.MARKER, `ran ${process.pid}\n`); console.log( JSON.stringify({ argv: process.argv.slice(2), @@ -40,6 +46,30 @@ async function main() { console.log("timed out"); return; } + if (command === "event-log") { + // A big write followed by a hard exit must not lose output. + process.stdout.write("x".repeat(Number(rest[0]))); + process.exit(0); + } + if (command === "gesture") { + for (let i = 0; i < 40; i++) { + process.stdout.write(`out${i}\n`); + process.stderr.write(`err${i}\n`); + } + console.log(`ppid ${process.ppid}`); + return; + } + if (command === "buffer") { + console.log( + JSON.stringify({ + pre: (globalThis as { __pre?: string }).__pre ?? null, + execArgv: process.execArgv, + nodeOptions: process.env.NODE_OPTIONS ?? null, + ppid: process.ppid, + }), + ); + return; + } if (command === "ax") { throw new Error("boom from ax"); } diff --git a/packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts b/packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts new file mode 100644 index 000000000..10fe2e257 --- /dev/null +++ b/packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts @@ -0,0 +1,31 @@ +// Drives dispatchViaControl under node with a synchronous stall injected +// right after a chosen client frame, to pin down what happens when the +// accept timer and the daemon's reply race. +import { dispatchViaControl } from "../../control-client"; + +const opts = JSON.parse(process.env.RACE_OPTS!) as { + binFile: string; + mainFile: string; + argv: string[]; + stallAfter: string; + stallMs: number; + acceptTimeoutMs: number; +}; + +const result = await dispatchViaControl(opts.argv, { + binFile: opts.binFile, + mainFile: opts.mainFile, + execPath: process.execPath, + execArgv: [], + env: process.env, + cwd: () => process.cwd(), + stdout: process.stdout, + stderr: process.stderr, + acceptTimeoutMs: opts.acceptTimeoutMs, + afterWrite: (t) => { + if (t !== opts.stallAfter) return; + const end = Date.now() + opts.stallMs; + while (Date.now() < end) {} + }, +}); +process.stderr.write(`RESULT ${JSON.stringify(result)}\n`); diff --git a/packages/serve-sim/src/bin.ts b/packages/serve-sim/src/bin.ts index da6f17599..28d3977ad 100644 --- a/packages/serve-sim/src/bin.ts +++ b/packages/serve-sim/src/bin.ts @@ -9,12 +9,14 @@ import { fileURLToPath } from "url"; import { controlCli, dispatchViaControl, type ControlContext } from "./control-client"; import { runControlDaemonProcess } from "./control-daemon"; import { + CONTROL_ACCEPT_ENV, CONTROL_DAEMON_ARG, CONTROL_IDLE_ENV, CONTROL_ROLE_ENV, DEFAULT_POOL_SIZE, controlFingerprint, controlPaths, + parseAcceptMs, parseIdleMs, } from "./control-protocol"; import { runControlWorker } from "./control-worker"; @@ -29,10 +31,13 @@ function context(): ControlContext { binFile, mainFile: fileURLToPath(mainUrl), execPath: process.execPath, + execArgv: process.execArgv, env: process.env, - cwd: process.cwd(), + // Lazy: a deleted cwd must not break commands that never dispatch. + cwd: () => process.cwd(), stdout: process.stdout, stderr: process.stderr, + acceptTimeoutMs: parseAcceptMs(process.env[CONTROL_ACCEPT_ENV]), }; } @@ -43,8 +48,7 @@ if (process.env[CONTROL_ROLE_ENV] === "worker") { const paths = controlPaths(ctx); await runControlDaemonProcess({ binFile, - socket: paths.socket, - pidFile: paths.pidFile, + paths, fingerprint: controlFingerprint(ctx), idleMs: parseIdleMs(process.env[CONTROL_IDLE_ENV]), poolSize: DEFAULT_POOL_SIZE, diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index 7687f6976..5385c0824 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -2,12 +2,14 @@ * Thin client for the persistent control process, plus `serve-sim control * start|stop|status`. Runs inside the tiny bin entry, so node builtins only. * - * Every failure before the daemon has accepted a command means "run it - * in-process instead", so a missing, stale or wedged daemon only costs a - * failed connect. + * The daemon replies `accepted` once it holds a warm worker for the call, + * and only hands the worker the command after the client answers `go`. + * Every failure before `go` therefore means "run it in-process instead": + * nothing has run yet, so a missing, stale or wedged daemon only costs a + * failed connect. After `go` the client never falls back. */ import { execFileSync, spawn } from "child_process"; -import { existsSync, readFileSync, unlinkSync } from "fs"; +import { existsSync, fstatSync, readFileSync, unlinkSync } from "fs"; import { createConnection } from "net"; import { CONTROL_DAEMON_ARG, @@ -15,12 +17,18 @@ import { FRAME_STDERR, FRAME_STDOUT, FrameDecoder, + MAX_SOCKET_PATH_BYTES, controlFingerprint, controlMode, controlPaths, encodeJson, isDispatchable, + nodeRuntimeOverride, parseJsonFrame, + unsafeControlDir, + unsafeControlSocket, + withoutNodeRuntimeEnv, + type ControlFingerprint, type ControlPaths, type ControlStatus, type ForwardedSignal, @@ -31,12 +39,17 @@ export interface ControlContext { binFile: string; mainFile: string; execPath: string; + /** The caller's node flags; workers can't adopt them. */ + execArgv: readonly string[]; env: NodeJS.ProcessEnv; - cwd: string; + /** Read lazily: the caller's cwd may have been deleted. */ + cwd: () => string; stdout: NodeJS.WriteStream; stderr: NodeJS.WriteStream; /** How long to wait for the daemon to accept before running in-process. */ acceptTimeoutMs?: number; + /** Test hook: called right after each client frame is written. */ + afterWrite?: (t: string) => void; } export type DispatchResult = @@ -53,6 +66,46 @@ function stringEnv(env: NodeJS.ProcessEnv): Record { return out; } +/** Whether fds 1 and 2 are the same open file (`2>&1`, one pty). */ +function sameOutputFile(): boolean { + try { + const out = fstatSync(1); + const err = fstatSync(2); + return out.dev === err.dev && out.ino === err.ino; + } catch { + return false; + } +} + +/** Don't retry a daemon whose workers couldn't load this build for a while. */ +const FAILED_BACKOFF_MS = 10 * 60_000; + +interface FailRecord { + at: number; + binMtimeMs: number; + mainMtimeMs: number; + reason?: string; +} + +function readFailRecord(file: string): FailRecord | null { + try { + const v = JSON.parse(readFileSync(file, "utf8")) as FailRecord; + return typeof v.at === "number" ? v : null; + } catch { + return null; + } +} + +function recentlyFailed(paths: ControlPaths, fp: ControlFingerprint): boolean { + const rec = readFailRecord(paths.failFile); + return ( + rec != null && + Date.now() - rec.at < FAILED_BACKOFF_MS && + rec.binMtimeMs === fp.binMtimeMs && + rec.mainMtimeMs === fp.mainMtimeMs + ); +} + /** Start a detached daemon and return immediately. */ function spawnDaemon(ctx: ControlContext): void { try { @@ -60,31 +113,60 @@ function spawnDaemon(ctx: ControlContext): void { cwd: "/", detached: true, stdio: "ignore", - env: ctx.env, + env: withoutNodeRuntimeEnv(ctx.env), }); child.on("error", () => {}); child.unref(); } catch {} } +/** Why the control socket can't be used, or null. "missing" means start one. */ +function unusableSocket(paths: ControlPaths): string | null { + if (Buffer.byteLength(paths.socket) > MAX_SOCKET_PATH_BYTES) return "socket path too long"; + const dir = unsafeControlDir(paths.dir); + if (dir) return dir === "missing" ? "missing" : `control dir ${dir}`; + const sock = unsafeControlSocket(paths.socket); + if (sock) return sock === "missing" ? "missing" : `control socket ${sock}`; + return null; +} + /** * Run `args` through the control process when possible. Resolves "bypass" * whenever the caller should run the command in-process. */ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise { + const bypass = (reason: string) => Promise.resolve({ kind: "bypass", reason }); const mode = controlMode(ctx.env); - if (mode === "off") return Promise.resolve({ kind: "bypass", reason: "disabled" }); - if (!isDispatchable(args)) return Promise.resolve({ kind: "bypass", reason: "not dispatchable" }); - const { socket } = pathsFor(ctx); - // sun_path is 104 bytes on macOS; a deep TMPDIR can't host the socket. - if (Buffer.byteLength(socket) > 103) return Promise.resolve({ kind: "bypass", reason: "socket path too long" }); + if (mode === "off") return bypass("disabled"); + if (!isDispatchable(args)) return bypass("not dispatchable"); + const runtime = nodeRuntimeOverride(ctx.env, ctx.execArgv); + if (runtime) return bypass(`caller sets ${runtime}`); + let cwd: string; + try { + cwd = ctx.cwd(); + } catch { + return bypass("no cwd"); + } + const paths = pathsFor(ctx); + const fingerprint = controlFingerprint(ctx); + const unusable = unusableSocket(paths); + if (unusable === "missing") { + if (mode === "auto" && !recentlyFailed(paths, fingerprint)) spawnDaemon(ctx); + return bypass("not running"); + } + if (unusable) return bypass(unusable); return new Promise((resolve) => { - const conn = createConnection(socket); + const conn = createConnection(paths.socket); const decoder = new FrameDecoder(); - let accepted = false; + // Once `go` is written the worker may be running: never fall back after. + let committed = false; let settled = false; const signalHandlers = new Map void>(); + const send = (msg: Parameters[0]) => { + conn.write(encodeJson(msg)); + ctx.afterWrite?.(msg.t); + }; const finish = (result: DispatchResult) => { if (settled) return; @@ -94,44 +176,43 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise conn.destroy(); resolve(result); }; + const lost = (detail: string) => { + ctx.stderr.write(`serve-sim: lost the control process mid-command (${detail})\n`); + finish({ kind: "done", code: 1, signal: null }); + }; + // Covers connect + waiting for a worker. It can only fire before `go`: + // the `accepted` handler clears it and sends `go` in the same tick. const acceptTimer = setTimeout( () => finish({ kind: "bypass", reason: "accept timeout" }), ctx.acceptTimeoutMs ?? 1000, ); conn.on("error", (error: NodeJS.ErrnoException) => { - if (accepted) { - ctx.stderr.write(`serve-sim: lost the control process mid-command (${error.code ?? error.message})\n`); - finish({ kind: "done", code: 1, signal: null }); - return; - } - if (mode === "auto" && (error.code === "ENOENT" || error.code === "ECONNREFUSED")) spawnDaemon(ctx); + if (committed) return lost(error.code ?? error.message); + if (mode === "auto" && (error.code === "ENOENT" || error.code === "ECONNREFUSED") && !recentlyFailed(paths, fingerprint)) spawnDaemon(ctx); finish({ kind: "bypass", reason: error.code ?? "connect failed" }); }); conn.on("close", () => { if (settled) return; - if (!accepted) finish({ kind: "bypass", reason: "closed before accept" }); - else { - ctx.stderr.write("serve-sim: control process exited mid-command\n"); - finish({ kind: "done", code: 1, signal: null }); - } + if (committed) lost("closed"); + else finish({ kind: "bypass", reason: "closed before accept" }); }); conn.on("connect", () => { - conn.write( - encodeJson({ - t: "run", - fingerprint: controlFingerprint(ctx), - argv: args, - cwd: ctx.cwd, - env: stringEnv(ctx.env), - tty: { - stdout: { isTTY: ctx.stdout.isTTY === true, columns: ctx.stdout.columns }, - stderr: { isTTY: ctx.stderr.isTTY === true, columns: ctx.stderr.columns }, - }, - }), - ); + send({ + t: "run", + fingerprint, + argv: args, + cwd, + env: stringEnv(ctx.env), + tty: { + stdout: { isTTY: ctx.stdout.isTTY === true, columns: ctx.stdout.columns }, + stderr: { isTTY: ctx.stderr.isTTY === true, columns: ctx.stderr.columns }, + }, + sharedOutput: sameOutputFile(), + }); }); conn.on("data", (chunk) => { + if (settled) return; let frames; try { frames = decoder.push(chunk); @@ -140,6 +221,7 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise return; } for (const frame of frames) { + if (settled) return; if (frame.type === FRAME_STDOUT) { ctx.stdout.write(frame.payload); continue; @@ -150,13 +232,15 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise } const msg = parseJsonFrame(frame); if (!msg) continue; + // The daemon only says bypass before it handed the job to a worker. if (msg.t === "bypass") finish({ kind: "bypass", reason: msg.reason }); - else if (msg.t === "accepted") { - accepted = true; + else if (msg.t === "accepted" && !committed) { clearTimeout(acceptTimer); + committed = true; + send({ t: "go" }); // From here the worker owns the command: forward signals to it. for (const sig of FORWARDED_SIGNALS) { - const handler = () => conn.write(encodeJson({ t: "signal", signal: sig })); + const handler = () => send({ t: "signal", signal: sig }); signalHandlers.set(sig, handler); process.on(sig, handler); } @@ -266,21 +350,52 @@ export async function controlCli(args: string[], ctx: ControlContext): Promise 1 ? ctx.stderr : ctx.stdout).write(`${CONTROL_USAGE}\n`); return rest.length > 1 ? 1 : 0; } + const unsafeDir = unsafeControlDir(paths.dir); + if (unsafeDir && unsafeDir !== "missing" && verb !== "start") { + ctx.stderr.write(`serve-sim: ignoring control dir ${paths.dir}: ${unsafeDir}\n`); + return 1; + } if (verb === "status") { - const status = await pingSocket(paths.socket); + const status = unusableSocket(paths) ? null : await pingSocket(paths.socket); if (json) out(JSON.stringify(status ? { running: true, ...status } : { running: false, socket: paths.socket })); else out(status ? formatStatus(status) : "control process not running"); return status ? 0 : 1; } if (verb === "start") { + // Socket-level problems inside our own private dir are the daemon's to + // clear; refuse only what it can't fix. + const tooLong = Buffer.byteLength(paths.socket) > MAX_SOCKET_PATH_BYTES; + if (tooLong || (unsafeDir && unsafeDir !== "missing")) { + const why = tooLong + ? `socket path ${paths.socket} is ${Buffer.byteLength(paths.socket)} bytes (max ${MAX_SOCKET_PATH_BYTES}); set SERVE_SIM_CONTROL_DIR to a shorter directory` + : `${paths.dir} is ${unsafeDir}; it must be a directory owned by you with mode 0700`; + ctx.stderr.write(`serve-sim: control process can't start: ${why}\n`); + return 1; + } let status = await pingSocket(paths.socket); const already = status != null; if (!status) { + // An explicit start retries even after workers failed to load. + try { + unlinkSync(paths.failFile); + } catch {} spawnDaemon(ctx); status = await waitFor(() => pingSocket(paths.socket), 5000); + // Don't report success until a worker could actually load the CLI; + // a daemon whose workers can't load writes its fail file and exits. + if (status && status.warm === 0) { + const ready = await waitFor(async () => { + const s = await pingSocket(paths.socket); + if (s) return s.warm > 0 ? s : null; + return existsSync(paths.failFile) ? "failed" : null; + }, 10_000); + status = ready && ready !== "failed" ? ready : null; + } } if (!status) { - ctx.stderr.write("serve-sim: control process did not start\n"); + const failed = readFailRecord(paths.failFile); + const detail = failed?.reason ? `: workers failed to load the CLI\n${failed.reason.trimEnd()}` : ""; + ctx.stderr.write(`serve-sim: control process did not start${detail}\n`); return 1; } if (json) out(JSON.stringify({ running: true, alreadyRunning: already, ...status })); diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts index 67869e6c2..89ebb386b 100644 --- a/packages/serve-sim/src/control-daemon.ts +++ b/packages/serve-sim/src/control-daemon.ts @@ -9,7 +9,6 @@ import { spawn, type ChildProcess } from "child_process"; import { chmodSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "fs"; import { createConnection, createServer, type Server, type Socket } from "net"; -import { dirname } from "path"; import { FORWARDED_SIGNALS, FRAME_STDERR, @@ -18,16 +17,19 @@ import { encodeFrame, encodeJson, fingerprintMismatch, + isDispatchable, isStaleBuild, parseJsonFrame, + unsafeControlDir, + withoutNodeRuntimeEnv, type ControlFingerprint, type ControlMessage, + type ControlPaths, type ControlStatus, } from "./control-protocol"; interface ControlDaemonOptions { - socket: string; - pidFile: string; + paths: ControlPaths; /** Spawns one warm worker (stdio must include an IPC channel). */ spawnWorker: () => ChildProcess; fingerprint: ControlFingerprint; @@ -46,9 +48,15 @@ interface ControlDaemon { interface Worker { child: ChildProcess; ready: boolean; + /** Last bytes a worker printed while loading, for the fail file. */ + loadOutput: string; } const MAX_SPAWN_FAILURES = 3; +/** How long an accepted caller has to answer `go` before its worker is freed. */ +const GO_TIMEOUT_MS = 10_000; +/** Cap on waiting for replies to flush before the daemon exits. */ +const DRAIN_TIMEOUT_MS = 1000; /** Probe a socket path: true only if a control daemon answers a ping. */ export function pingSocket(socket: string, timeoutMs = 500): Promise { @@ -89,7 +97,13 @@ function listen(server: Server, socket: string): Promise { }; server.once("error", onError); server.once("listening", onListening); - server.listen(socket); + // Create the socket owner-only from the start: no window before chmod. + const previous = process.umask(0o077); + try { + server.listen(socket); + } finally { + process.umask(previous); + } }); } @@ -122,25 +136,34 @@ function inodeOf(path: string): number | null { } async function startControlDaemon(opts: ControlDaemonOptions): Promise { - mkdirSync(dirname(opts.socket), { recursive: true, mode: 0o700 }); + const { socket, pidFile, failFile, dir } = opts.paths; + mkdirSync(dir, { recursive: true, mode: 0o700 }); + // Callers send their whole environment here: refuse a directory that + // someone else owns or can write to. + const unsafe = unsafeControlDir(dir); + if (unsafe) throw new Error(`control dir ${dir} is ${unsafe}`); const server = createServer(); - if (!(await bindExclusive(server, opts.socket))) { + if (!(await bindExclusive(server, socket))) { server.close(); return null; } try { - chmodSync(opts.socket, 0o600); + chmodSync(socket, 0o600); } catch {} - const socketInode = inodeOf(opts.socket); + const socketInode = inodeOf(socket); const startedAt = Date.now(); let lastActiveAt = startedAt; let busy = 0; let served = 0; let spawnFailures = 0; + let lastLoadOutput = ""; let stopping = false; const pool: Worker[] = []; const waiting: Array<(worker: Worker | null) => void> = []; const busyChildren = new Set(); + /** Accepted callers that haven't said `go` yet, and the worker held for each. */ + const held = new Map(); + const connections = new Set(); let resolveClosed!: () => void; const closed = new Promise((resolve) => (resolveClosed = resolve)); @@ -153,37 +176,48 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise !w.ready).length, busy, served, - socket: opts.socket, + socket, }); - const writePidFile = () => { - const tmp = `${opts.pidFile}.${process.pid}.tmp`; + const writeJsonFile = (file: string, value: unknown) => { + const tmp = `${file}.${process.pid}.tmp`; try { - writeFileSync(tmp, JSON.stringify({ pid: process.pid, socket: opts.socket, startedAt }), { mode: 0o600 }); - renameSync(tmp, opts.pidFile); + writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 }); + renameSync(tmp, file); } catch {} }; - writePidFile(); + writeJsonFile(pidFile, { pid: process.pid, socket, startedAt }); - const ownsSocket = () => socketInode != null && inodeOf(opts.socket) === socketInode; + const ownsSocket = () => socketInode != null && inodeOf(socket) === socketInode; function spawnWorker(): void { if (stopping) return; let child: ChildProcess; try { child = opts.spawnWorker(); - } catch { + } catch (error) { + lastLoadOutput = (error as Error).message; onSpawnFailure(); return; } - const worker: Worker = { child, ready: false }; + const worker: Worker = { child, ready: false, loadOutput: "" }; pool.push(worker); - // Anything a worker prints before it is assigned is load noise. - child.stdout?.on("data", () => {}); - child.stderr?.on("data", () => {}); + // Anything a worker prints before it is assigned is load noise, kept + // only to explain a worker that never becomes ready. + const keep = (chunk: Buffer) => { + if (!worker.ready) worker.loadOutput = (worker.loadOutput + chunk.toString()).slice(-4096); + }; + child.stdout?.on("data", keep); + child.stderr?.on("data", keep); child.on("message", (msg: { t?: string }) => { if (msg?.t !== "ready" || worker.ready) return; worker.ready = true; + worker.loadOutput = ""; + if (spawnFailures > 0 || served === 0) { + try { + unlinkSync(failFile); + } catch {} + } spawnFailures = 0; const waiter = waiting.shift(); if (waiter) { @@ -192,24 +226,37 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { + // "close", not "exit": a failed load's output can arrive after exit. + child.on("close", () => { if (!pool.includes(worker)) return; removeFromPool(worker); - if (!worker.ready) onSpawnFailure(); - else refill(); + if (!worker.ready) { + lastLoadOutput = worker.loadOutput; + onSpawnFailure(); + } else refill(); + }); + child.on("error", (error) => { + lastLoadOutput = error.message; }); - child.on("error", () => {}); } function onSpawnFailure(): void { spawnFailures++; if (spawnFailures >= MAX_SPAWN_FAILURES) { - // Workers can't load (broken dist?). Send everyone in-process. - for (const waiter of waiting.splice(0)) waiter(null); + // Workers can't load (broken install?). Tell callers to stop starting + // daemons for this build, and send everyone in-process. + writeJsonFile(failFile, { + at: Date.now(), + binMtimeMs: opts.fingerprint.binMtimeMs, + mainMtimeMs: opts.fingerprint.mainMtimeMs, + reason: lastLoadOutput, + }); shutdown("workers failing to start"); return; } - if (waiting.length > 0) refill(); + // Back off a little, then keep the pool warm so the next caller doesn't + // pay for a cold spawn. + setTimeout(refill, 100 * spawnFailures).unref(); } function removeFromPool(worker: Worker): void { @@ -224,6 +271,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { + if (stopping) return Promise.resolve(null); const ready = pool.find((w) => w.ready); if (ready) { removeFromPool(ready); @@ -238,79 +286,112 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise= opts.poolSize) worker.child.kill("SIGTERM"); + if (stopping || worker.child.exitCode != null || pool.length >= opts.poolSize) worker.child.kill("SIGTERM"); else pool.unshift(worker); } + /** Nothing has run yet: tell the caller to run the command itself. */ + function bypass(conn: Socket, reason: string): void { + if (!conn.destroyed) conn.end(encodeJson({ t: "bypass", reason })); + } + async function runJob(conn: Socket, msg: Extract): Promise { const mismatch = fingerprintMismatch(opts.fingerprint, msg.fingerprint); if (mismatch) { - conn.end(encodeJson({ t: "bypass", reason: `fingerprint:${mismatch}` })); + bypass(conn, `fingerprint:${mismatch}`); if (isStaleBuild(mismatch)) shutdown("dist rebuilt"); return; } - if (stopping) { - conn.end(encodeJson({ t: "bypass", reason: "stopping" })); - return; - } + // Don't trust the client's filter: only short one-shot commands may + // occupy a worker (and keep the daemon alive). + if (!Array.isArray(msg.argv) || !isDispatchable(msg.argv)) return bypass(conn, "not dispatchable"); + if (stopping) return bypass(conn, "stopping"); busy++; lastActiveAt = Date.now(); - conn.write(encodeJson({ t: "accepted" })); let clientGone = false; let child: ChildProcess | null = null; - const pendingSignals: string[] = []; conn.on("close", () => { clientGone = true; + const worker = held.get(conn); + if (worker) { + // Accepted but never told to go: the worker is still pristine. + held.delete(conn); + clearTimeout(goTimer); + busy--; + release(worker); + maybeFinishStop(); + } // The caller died mid-command (e.g. SIGKILL): don't leave it running. child?.kill("SIGTERM"); }); conn.on("error", () => {}); - const onClientMessage = (m: ControlMessage) => { - if (m.t !== "signal" || !FORWARDED_SIGNALS.includes(m.signal)) return; - if (child) child.kill(m.signal); - else pendingSignals.push(m.signal); - }; - jobListeners.set(conn, onClientMessage); + // Hold a worker before accepting, so "no worker" is still a bypass. const worker = await acquire(); - if (!worker) { + if (!worker || clientGone || stopping) { busy--; - if (!clientGone) conn.end(encodeJson({ t: "exit", code: 1, signal: null })); + if (worker) release(worker); + if (!clientGone) bypass(conn, worker ? "stopping" : "no worker available"); + maybeFinishStop(); return; } - if (clientGone) { + held.set(conn, worker); + const goTimer = setTimeout(() => { + if (held.get(conn) !== worker) return; + held.delete(conn); busy--; release(worker); + conn.destroy(); maybeFinishStop(); - return; - } - child = worker.child; - busyChildren.add(child); - served++; - child.stdout?.removeAllListeners("data"); - child.stderr?.removeAllListeners("data"); - child.stdout?.on("data", (chunk: Buffer) => { - if (!clientGone) conn.write(encodeFrame(FRAME_STDOUT, chunk)); - }); - child.stderr?.on("data", (chunk: Buffer) => { - if (!clientGone) conn.write(encodeFrame(FRAME_STDERR, chunk)); + }, GO_TIMEOUT_MS); + conn.write(encodeJson({ t: "accepted" })); + + jobListeners.set(conn, (m: ControlMessage) => { + if (m.t === "go") { + if (held.get(conn) !== worker) return; + held.delete(conn); + clearTimeout(goTimer); + start(worker); + } else if (m.t === "signal" && child && FORWARDED_SIGNALS.includes(m.signal)) { + child.kill(m.signal); + } }); - child.removeAllListeners("exit"); - child.once("close", (code, signal) => { - busyChildren.delete(child!); - busy--; + + function start(w: Worker): void { + const c = w.child; + child = c; + busyChildren.add(c); + served++; lastActiveAt = Date.now(); - if (!clientGone) conn.end(encodeJson({ t: "exit", code, signal })); - maybeFinishStop(); - }); - const { t: _t, fingerprint: _fp, ...payload } = msg; - child.send({ t: "run", ...payload }); - for (const sig of pendingSignals) child.kill(sig as NodeJS.Signals); + c.stdout?.removeAllListeners("data"); + c.stderr?.removeAllListeners("data"); + c.stdout?.on("data", (chunk: Buffer) => { + if (!clientGone) conn.write(encodeFrame(FRAME_STDOUT, chunk)); + }); + c.stderr?.on("data", (chunk: Buffer) => { + if (!clientGone) conn.write(encodeFrame(FRAME_STDERR, chunk)); + }); + c.removeAllListeners("close"); + c.once("close", (code, signal) => { + busyChildren.delete(c); + busy--; + lastActiveAt = Date.now(); + if (!clientGone) conn.end(encodeJson({ t: "exit", code, signal })); + maybeFinishStop(); + }); + const { t: _t, fingerprint: _fp, ...payload } = msg; + c.send({ t: "run", ...payload }); + } } const jobListeners = new WeakMap void>(); server.on("connection", (conn) => { + connections.add(conn); + conn.on("close", () => { + connections.delete(conn); + if (stopping) maybeFinishStop(); + }); const decoder = new FrameDecoder(); let first = true; conn.on("error", () => {}); @@ -352,6 +433,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise | null = null; function shutdown(_reason: string, o: { unlink?: boolean } = {}): void { if (o.unlink === false) unlinkOnExit = false; if (stopping) return; @@ -360,21 +442,39 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise 0 || busyChildren.size > 0) return; + if (connections.size === 0) { + if (drainTimer) clearTimeout(drainTimer); + resolveClosed(); + return; + } + drainTimer ??= setTimeout(() => { + for (const conn of connections) conn.destroy(); + resolveClosed(); + }, DRAIN_TIMEOUT_MS); } refill(); @@ -384,8 +484,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise - spawn(process.execPath, [opts.binFile], { - cwd: "/", - env: { ...process.env, [opts.roleEnv]: "worker" }, - stdio: ["ignore", "pipe", "pipe", "ipc"], - }), - }); + let daemon: ControlDaemon | null; + try { + daemon = await startControlDaemon({ + paths: opts.paths, + fingerprint: opts.fingerprint, + idleMs: opts.idleMs, + poolSize: opts.poolSize, + spawnWorker: () => + spawn(process.execPath, [opts.binFile], { + cwd: "/", + // The first caller's node flags must not leak into later callers. + env: { ...withoutNodeRuntimeEnv(process.env), [opts.roleEnv]: "worker" }, + stdio: ["ignore", "pipe", "pipe", "ipc"], + }), + }); + } catch (error) { + process.stderr.write(`serve-sim: control process refused to start: ${(error as Error).message}\n`); + process.exit(1); + } if (!daemon) return; // another daemon already owns the socket - process.on("SIGTERM", () => daemon.stop("SIGTERM")); - process.on("SIGINT", () => daemon.stop("SIGINT")); + const running = daemon; + process.on("SIGTERM", () => running.stop("SIGTERM")); + process.on("SIGINT", () => running.stop("SIGINT")); process.on("SIGHUP", () => {}); - await daemon.closed; + await running.closed; process.exit(0); } diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts index 2bc851458..cba927927 100644 --- a/packages/serve-sim/src/control-protocol.ts +++ b/packages/serve-sim/src/control-protocol.ts @@ -7,11 +7,11 @@ * pull in node builtins — anything heavier defeats the point. */ import { createHash } from "crypto"; -import { statSync } from "fs"; +import { lstatSync, statSync } from "fs"; import { homedir, tmpdir } from "os"; import { join } from "path"; -const CONTROL_PROTOCOL = 1; +const CONTROL_PROTOCOL = 2; /** argv[2] marker for the daemon process (visible in `ps`). */ export const CONTROL_DAEMON_ARG = "__control-daemon"; /** Set on pre-warmed worker processes; stripped before the command runs. */ @@ -20,8 +20,11 @@ export const CONTROL_ROLE_ENV = "SERVE_SIM_CONTROL_ROLE"; const CONTROL_ENV = "SERVE_SIM_CONTROL"; /** Quiet period before the daemon exits on its own (ms). */ export const CONTROL_IDLE_ENV = "SERVE_SIM_CONTROL_IDLE_MS"; -/** Override the socket/pid directory (tests, unusual TMPDIRs). */ +/** Override the socket/pid directory (tests, unusual TMPDIRs). @lintignore Exported for tests. */ export const CONTROL_DIR_ENV = "SERVE_SIM_CONTROL_DIR"; +/** How long a caller waits for the daemon to hand it a worker (ms). */ +export const CONTROL_ACCEPT_ENV = "SERVE_SIM_CONTROL_ACCEPT_MS"; +const DEFAULT_ACCEPT_MS = 1000; const DEFAULT_IDLE_MS = 5 * 60_000; /** Warm workers kept ready; each is single-use, then replaced. */ export const DEFAULT_POOL_SIZE = 2; @@ -77,6 +80,31 @@ export function controlMode(env: NodeJS.ProcessEnv): ControlMode { return "auto"; } +export function parseAcceptMs(raw: string | undefined): number { + const n = raw == null || raw.trim() === "" ? NaN : Number(raw); + return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_ACCEPT_MS; +} + +/** + * Node runtime settings a warm worker can't adopt after it has started: + * they shape how node itself boots (preloads, inspector, CA store, proxy). + * They are stripped from the daemon and its workers, and a caller that sets + * any of them runs in-process. + */ +const NODE_RUNTIME_ENV = ["NODE_OPTIONS", "NODE_EXTRA_CA_CERTS", "NODE_USE_ENV_PROXY"] as const; + +export function withoutNodeRuntimeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const out = { ...env }; + for (const key of NODE_RUNTIME_ENV) delete out[key]; + return out; +} + +/** The first runtime setting the caller has that a worker can't honor. */ +export function nodeRuntimeOverride(env: NodeJS.ProcessEnv, execArgv: readonly string[]): string | null { + for (const key of NODE_RUNTIME_ENV) if (env[key]) return key; + return execArgv.length > 0 ? "execArgv" : null; +} + export function parseIdleMs(raw: string | undefined): number { if (raw == null || raw.trim() === "") return DEFAULT_IDLE_MS; const n = Number(raw); @@ -87,6 +115,8 @@ export interface ControlPaths { dir: string; socket: string; pidFile: string; + /** Written when workers can't load, so callers stop respawning a daemon. */ + failFile: string; } /** @@ -98,7 +128,9 @@ export function controlPaths(opts: { execPath: string; env: NodeJS.ProcessEnv; }): ControlPaths { - const dir = opts.env[CONTROL_DIR_ENV] || join(tmpdir(), "serve-sim"); + // Per-uid so another user on a shared /tmp can't pre-create the directory. + const uid = typeof process.getuid === "function" ? process.getuid() : null; + const dir = opts.env[CONTROL_DIR_ENV] || join(tmpdir(), uid == null ? "serve-sim-control" : `serve-sim-control-${uid}`); const id = createHash("sha256") .update(`${opts.binFile}\0${opts.execPath}\0${opts.env.HOME ?? homedir()}`) .digest("hex") @@ -107,9 +139,52 @@ export function controlPaths(opts: { dir, socket: join(dir, `control-${id}.sock`), pidFile: join(dir, `control-${id}.json`), + failFile: join(dir, `control-${id}.failed`), }; } +/** sun_path is 104 bytes on macOS, including the terminating NUL. */ +export const MAX_SOCKET_PATH_BYTES = 103; + +function currentUid(): number | null { + return typeof process.getuid === "function" ? process.getuid() : null; +} + +/** + * Why `dir` can't hold the control socket, or null if it is a real + * directory owned by us that nobody else can write to. The client sends its + * whole environment over the socket, so it must be ours. + */ +export function unsafeControlDir(dir: string): string | null { + let st; + try { + st = lstatSync(dir); + } catch (error) { + return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unreadable"; + } + if (st.isSymbolicLink()) return "symlink"; + if (!st.isDirectory()) return "not a directory"; + const uid = currentUid(); + if (uid != null && st.uid !== uid) return `owned by uid ${st.uid}`; + if ((st.mode & 0o077) !== 0) return `mode ${(st.mode & 0o777).toString(8)} is group/other accessible`; + return null; +} + +/** Why `socket` isn't a socket we own ("missing" when absent), or null. */ +export function unsafeControlSocket(socket: string): string | null { + let st; + try { + st = lstatSync(socket); + } catch (error) { + return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unreadable"; + } + if (st.isSymbolicLink()) return "symlink"; + if (!st.isSocket()) return "not a socket"; + const uid = currentUid(); + if (uid != null && st.uid !== uid) return `owned by uid ${st.uid}`; + return null; +} + /** * What a warm worker baked in at load time. The main bundle reads HOME and * TMPDIR into module constants and `debug` reads DEBUG on import, so a caller @@ -171,6 +246,7 @@ export function isStaleBuild(field: keyof ControlFingerprint | null): boolean { // [type u8][length u32 BE][payload]. JSON frames carry control messages; // stdout/stderr frames carry raw command output bytes. +/** @lintignore Exported for tests. */ export const FRAME_JSON = 0x4a; // J export const FRAME_STDOUT = 0x4f; // O export const FRAME_STDERR = 0x45; // E @@ -230,7 +306,12 @@ export type ControlMessage = cwd: string; env: Record; tty: { stdout: StreamTty; stderr: StreamTty }; + /** The caller's stdout and stderr are the same file (e.g. `2>&1`). */ + sharedOutput?: boolean; } + // Two-phase start: the daemon replies `accepted` once it holds a worker + // for the caller, and only hands it the command after the caller's `go`. + | { t: "go" } | { t: "signal"; signal: ForwardedSignal } | { t: "ping" } | { t: "stop" } diff --git a/packages/serve-sim/src/control-worker.ts b/packages/serve-sim/src/control-worker.ts index aac7f9088..91703d6b5 100644 --- a/packages/serve-sim/src/control-worker.ts +++ b/packages/serve-sim/src/control-worker.ts @@ -16,9 +16,22 @@ function adoptTty(stream: NodeJS.WriteStream, tty: StreamTty | undefined): void // Help wrapping and a couple of commands key off these; the stream itself // is a pipe to the daemon, so don't fake any TTY methods. Object.defineProperty(stream, "isTTY", { value: true, configurable: true }); - if (tty.columns) Object.defineProperty(stream, "columns", { value: tty.columns, configurable: true }); + if (tty.columns != null) Object.defineProperty(stream, "columns", { value: tty.columns, configurable: true }); } +interface PipeHandle { + setBlocking?: (blocking: boolean) => void; +} + +/** + * Make writes to the daemon pipe synchronous, as they are for a file or TTY + * in a direct run, so `write(big); process.exit()` doesn't lose output. + */ +function blockingWrites(stream: NodeJS.WriteStream): void { + (stream as unknown as { _handle?: PipeHandle })._handle?.setBlocking?.(true); +} + +/** @lintignore Exported for tests. */ export function adoptCaller(message: RunMessage, proc: NodeJS.Process = process): void { proc.chdir(message.cwd); for (const key of Object.keys(proc.env)) { @@ -28,6 +41,16 @@ export function adoptCaller(message: RunMessage, proc: NodeJS.Process = process) proc.argv.splice(2, proc.argv.length - 2, ...message.argv); adoptTty(proc.stdout, message.tty.stdout); adoptTty(proc.stderr, message.tty.stderr); + blockingWrites(proc.stdout); + blockingWrites(proc.stderr); + if (message.sharedOutput) { + // The caller's stdout and stderr are one file (`2>&1`): send both down + // one pipe so the daemon can't reorder them. Writes from child + // processes that inherit fd 2 still travel separately. + const stdout = proc.stdout; + proc.stderr.write = ((...args: Parameters) => + stdout.write(...args)) as NodeJS.WriteStream["write"]; + } } export async function runControlWorker(mainUrl: string): Promise { From 418d0f49dd12ee294cd3062406cde9e27d527994 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 16:32:27 -0800 Subject: [PATCH 05/17] test(bundle): check dist/serve-sim-cli.js for baked-in build paths --- packages/serve-sim/src/__tests__/bundle-portability.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/serve-sim/src/__tests__/bundle-portability.test.ts b/packages/serve-sim/src/__tests__/bundle-portability.test.ts index 34a3ee1d9..204eb8523 100644 --- a/packages/serve-sim/src/__tests__/bundle-portability.test.ts +++ b/packages/serve-sim/src/__tests__/bundle-portability.test.ts @@ -15,7 +15,7 @@ import { join } from "path"; const PKG_DIR = join(import.meta.dir, "../.."); const SRC_DIR = join(PKG_DIR, "src"); -const BUNDLES = ["dist/serve-sim.js", "dist/middleware.js"] as const; +const BUNDLES = ["dist/serve-sim.js", "dist/serve-sim-cli.js", "dist/middleware.js"] as const; // CI builds dist before running this directory; locally, run // `bun run build.ts` first or the suite skips. From 0c2a0c27ba033db3991070900d944de050e034ec Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 16:32:27 -0800 Subject: [PATCH 06/17] docs(control): document the go handshake, ownership checks and fallbacks --- packages/serve-sim/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/serve-sim/README.md b/packages/serve-sim/README.md index 7aa36df18..c81c14148 100644 --- a/packages/serve-sim/README.md +++ b/packages/serve-sim/README.md @@ -361,12 +361,13 @@ Limits: sampling at 4 fps can miss a state shown for less than a tick (record fo ### Control process (faster repeated commands) -Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now a 14 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. +Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now an 18 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. - **Which commands**: `tap`, `gesture`, `settle`, `button`, `type`, `paste`, `rotate`, `fold`, `ca-debug`, `memory-warning`, `event-log`, `ax`, `buffer`, and bare `--help`/`--version`. Everything else runs in-process as before: the preview server, `--detach`, `record`, `camera`, `exec`, `doctor`, `permissions`, `ui`, and anything with `--stdin` (stdin is not forwarded). -- **What carries over**: argv, cwd, the full environment, stdout/stderr (as separate streams), the exit code or signal, and whether stdout/stderr are TTYs plus their column width. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker. If the caller dies, its worker is stopped. -- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, or that use a different node binary or install, always run in-process. -- **Fallback**: if the control process is missing, stale, or doesn't accept a command within 1 s, the command runs in-process. Once it has accepted a command, a lost connection fails that call (exit 1) instead of running the command twice. +- **What carries over**: argv, cwd, the full environment, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. +- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. +- **Fallback**: the daemon first reserves a warm worker and replies "accepted"; the command is only handed to the worker after the caller confirms. If the control process is missing, stale, or doesn't reserve a worker within 1 s (`SERVE_SIM_CONTROL_ACCEPT_MS`), nothing has run yet and the command runs in-process. Once the caller has confirmed, it never falls back: a lost connection fails that call (exit 1) instead of running the command twice. +- **Broken installs**: if workers can't load the CLI, the daemon records why in a `.failed` file next to its socket and exits. Commands keep running in-process, and for 10 minutes (or until the dist is rebuilt) they don't start a new daemon. `serve-sim control start` retries immediately, and only reports success once a worker has loaded; otherwise it prints the worker's error and exits 1. - **Off switch**: `SERVE_SIM_CONTROL=0` never uses or starts it. Under `CI` it is only used if already running; `SERVE_SIM_CONTROL=1` auto-starts it there too. ```sh @@ -375,7 +376,7 @@ serve-sim control start # idempotent; waits until it answers serve-sim control stop # idempotent; also clears stale socket/pid files ``` -It listens on a Unix socket (mode 0600) at `$TMPDIR/serve-sim/control-.sock`, with a pid file next to it. `` is derived from the bin path, the node binary, and `HOME`. A daemon that finds a dead socket replaces it. When several start at once, the extra ones see their socket was taken over and exit. +It listens on a Unix socket at `$TMPDIR/serve-sim-control-/control-.sock` (or under `SERVE_SIM_CONTROL_DIR`), with a pid file next to it. `` is derived from the bin path, the node binary, and `HOME`. Callers send their whole environment over that socket, so both sides check ownership first: the directory must be a real directory (not a symlink) owned by you with no group/other access, and the socket must be a socket owned by you. Otherwise commands run in-process and the daemon refuses to start. The socket is created owner-only (mode 0600) with no window where it is more open. A daemon that finds a dead socket replaces it. When several start at once, the extra ones see their socket was taken over and exit. Measured on an Apple Silicon Mac with Node 24.13: each case was spawned with `spawnSync` from a node script, after 3 warm-up runs. Back-to-back means calls ran one after another. "Before" runs the full CLI bundle directly, which is what the bin was before this change. `tap` ran against a live preview on its own simulator. From 31df89e70c0b77379d724fda2fb04231ded2345d Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 16:59:35 -0800 Subject: [PATCH 07/17] fix(control): free a held worker that dies before go A reserved worker is out of the pool, so its pool close handler ignored its death. When `go` then arrived, the daemon sent the command to a dead child and waited for a close that had already happened: the caller hung forever and busy stayed at 1, so the daemon never idle-exited. Watch the held worker's close and, on death (or if it is already gone when acquired or when `go` arrives), release it and tell the caller to bypass: nothing has run yet. A send that fails because the child just died is reported as bypass too. acquire() skips pooled workers that exited but whose close hasn't been handled. The go timeout now sends bypass instead of a bare close, so a slow caller runs in-process rather than exiting 1. --- .../src/__tests__/control-process.test.ts | 34 ++++++++ packages/serve-sim/src/control-daemon.ts | 77 ++++++++++++++----- 2 files changed, 92 insertions(+), 19 deletions(-) diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index 0ddaf6b05..6d66457af 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -818,4 +818,38 @@ describeWithNode("control process", () => { } }); }); + const alive = (pid: number) => { + try { + process.kill(pid, 0); + return true; + } catch { + return false; + } + }; + const workerPids = (daemonPid: number) => + spawnSync("pgrep", ["-P", String(daemonPid)], { encoding: "utf8" }) + .stdout.split("\n") + .filter(Boolean) + .map(Number); + + test("a held worker that dies before go sends the caller in-process and frees the daemon", async () => { + const r0 = await cli(["control", "start", "--json"], { env: { SERVE_SIM_CONTROL_IDLE_MS: "1500" } }); + const daemon = JSON.parse(r0.stdout) as { pid: number }; + await warm(); + const marker = join(work, "ran.txt"); + // The client stalls after `run`, so the daemon holds a worker for it + // while we kill every worker (the held one included). + const pending = race({ stallAfter: "run", stallMs: 1500, acceptTimeoutMs: 30_000, marker }); + await until(async () => (await status()).busy === 1); + for (const pid of workerPids(daemon.pid)) process.kill(pid, "SIGKILL"); + const r = await pending; + expect(r.result).toEqual({ kind: "bypass", reason: "worker exited" }); + expect(ranCount(marker)).toBe(0); + await until(async () => (await status()).busy === 0); + // The real bin finishes such a call in-process. + expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); + // Nothing pins it: it still idle-exits. + await until(async () => !alive(daemon.pid), 8000); + }); + }); diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts index 89ebb386b..56d2a66db 100644 --- a/packages/serve-sim/src/control-daemon.ts +++ b/packages/serve-sim/src/control-daemon.ts @@ -163,6 +163,8 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise(); /** Accepted callers that haven't said `go` yet, and the worker held for each. */ const held = new Map(); + const holdTimers = new Map>(); + const holdWatchers = new Map void>(); const connections = new Set(); let resolveClosed!: () => void; const closed = new Promise((resolve) => (resolveClosed = resolve)); @@ -189,6 +191,8 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise socketInode != null && inodeOf(socket) === socketInode; + /** Exited, or its IPC channel is gone; its `close` may not have been handled yet. */ + const isGone = (w: Worker) => w.child.exitCode != null || w.child.signalCode != null || !w.child.connected; function spawnWorker(): void { if (stopping) return; @@ -272,7 +276,8 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { if (stopping) return Promise.resolve(null); - const ready = pool.find((w) => w.ready); + // A dead worker stays in the pool until its `close` handler refills. + const ready = pool.find((w) => w.ready && !isGone(w)); if (ready) { removeFromPool(ready); refill(); @@ -286,10 +291,29 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise= opts.poolSize) worker.child.kill("SIGTERM"); + if (stopping || isGone(worker) || pool.length >= opts.poolSize) worker.child.kill("SIGTERM"); else pool.unshift(worker); } + function hold(conn: Socket, worker: Worker, onExit: () => void): void { + held.set(conn, worker); + holdWatchers.set(conn, onExit); + worker.child.once("close", onExit); + } + + /** Stop holding the caller's worker; returns it if it was still held. */ + function unhold(conn: Socket): Worker | undefined { + const worker = held.get(conn); + if (!worker) return undefined; + held.delete(conn); + clearTimeout(holdTimers.get(conn)); + holdTimers.delete(conn); + const onExit = holdWatchers.get(conn); + holdWatchers.delete(conn); + if (onExit) worker.child.off("close", onExit); + return worker; + } + /** Nothing has run yet: tell the caller to run the command itself. */ function bypass(conn: Socket, reason: string): void { if (!conn.destroyed) conn.end(encodeJson({ t: "bypass", reason })); @@ -312,11 +336,9 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { clientGone = true; - const worker = held.get(conn); + const worker = unhold(conn); if (worker) { // Accepted but never told to go: the worker is still pristine. - held.delete(conn); - clearTimeout(goTimer); busy--; release(worker); maybeFinishStop(); @@ -328,29 +350,33 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { - if (held.get(conn) !== worker) return; - held.delete(conn); + // Nothing has run yet if the held worker dies before `go` (an outside + // `pkill`, a crash): send the caller in-process rather than leave it, + // and this daemon, waiting on a dead child. + const dropHeld = (reason: string) => { + if (!unhold(conn)) return; busy--; release(worker); - conn.destroy(); + bypass(conn, reason); maybeFinishStop(); - }, GO_TIMEOUT_MS); + }; + hold(conn, worker, () => dropHeld("worker exited")); + // Freed before any late `go` is honoured, so bypass is still safe. + holdTimers.set(conn, setTimeout(() => dropHeld("go timeout"), GO_TIMEOUT_MS)); conn.write(encodeJson({ t: "accepted" })); jobListeners.set(conn, (m: ControlMessage) => { if (m.t === "go") { if (held.get(conn) !== worker) return; - held.delete(conn); - clearTimeout(goTimer); + if (isGone(worker)) return dropHeld("worker exited"); + unhold(conn); start(worker); } else if (m.t === "signal" && child && FORWARDED_SIGNALS.includes(m.signal)) { child.kill(m.signal); @@ -371,16 +397,29 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { if (!clientGone) conn.write(encodeFrame(FRAME_STDERR, chunk)); }); + // The command never reached the worker (it died just now): the + // caller can still run it itself. + let undelivered = false; c.removeAllListeners("close"); c.once("close", (code, signal) => { busyChildren.delete(c); busy--; lastActiveAt = Date.now(); - if (!clientGone) conn.end(encodeJson({ t: "exit", code, signal })); + if (undelivered) { + served--; + bypass(conn, "worker exited"); + } + else if (!clientGone) conn.end(encodeJson({ t: "exit", code, signal })); maybeFinishStop(); }); const { t: _t, fingerprint: _fp, ...payload } = msg; - c.send({ t: "run", ...payload }); + try { + c.send({ t: "run", ...payload }, (error) => { + if (error) undelivered = true; + }); + } catch { + undelivered = true; + } } } @@ -452,8 +491,8 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise Date: Tue, 10 Nov 2026 16:59:51 -0800 Subject: [PATCH 08/17] fix(control): only report stopped once the daemon has exited `control stop` printed "stopped" (and `"stopped":true`) while the daemon was still finishing a running command, after a SIGTERM that did nothing because the daemon was already stopping. The daemon's `stopping` reply now carries how many commands are still running. stop reports stopped only when the pid is gone; otherwise it says "stopping; waiting for N running command(s)" (json: stopped:false, stopping:true, busy:N). It waits 1 s instead of 5 s when commands are running, and no longer sends the pointless SIGTERM. --- .../src/__tests__/control-process.test.ts | 30 ++++++++ packages/serve-sim/src/control-client.ts | 72 +++++++++++++------ packages/serve-sim/src/control-daemon.ts | 3 +- packages/serve-sim/src/control-protocol.ts | 3 +- 4 files changed, 84 insertions(+), 24 deletions(-) diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index 6d66457af..2184c3ac2 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -852,4 +852,34 @@ describeWithNode("control process", () => { await until(async () => !alive(daemon.pid), 8000); }); + test("stop with a command in flight reports stopping, not stopped", async () => { + const daemon = await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + await new Promise((resolve) => child.stdout.on("data", () => resolve())); + const stop = await cli(["control", "stop", "--json"]); + expect(JSON.parse(stop.stdout)).toEqual({ + wasRunning: true, + pid: daemon.pid, + stopped: false, + stopping: true, + busy: 1, + clearedStale: false, + }); + expect(alive(daemon.pid)).toBe(true); + child.kill("SIGINT"); + await until(async () => !alive(daemon.pid)); + expect(JSON.parse((await cli(["control", "stop", "--json"])).stdout)).toMatchObject({ wasRunning: false }); + }); + + test("stop text output says it is waiting for running commands", async () => { + await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + await new Promise((resolve) => child.stdout.on("data", () => resolve())); + const stop = await cli(["control", "stop"]); + expect(stop.stdout).toMatch(/^stopping \(pid \d+\); waiting for 1 running command\(s\) to finish\n$/); + child.kill("SIGINT"); + }); + }); diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index 5385c0824..2be13573c 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -331,6 +331,31 @@ async function waitFor(probe: () => Promise, timeoutMs: number): Pr } } +function waitForExit(pid: number, timeoutMs: number): Promise { + return waitFor(async () => (isAlive(pid) ? null : true), timeoutMs).then((v) => v === true); +} + +/** Ask the daemon to stop; resolves with how many commands it is still running. */ +function requestStop(socket: string): Promise { + return new Promise((resolve) => { + const conn = createConnection(socket); + const decoder = new FrameDecoder(); + let busy = 0; + conn.on("connect", () => conn.write(encodeJson({ t: "stop" }))); + // Read the reply, or the socket never reaches end/close. + conn.on("data", (chunk) => { + try { + for (const frame of decoder.push(chunk)) { + const msg = parseJsonFrame(frame); + if (msg?.t === "stopping" && typeof msg.busy === "number") busy = msg.busy; + } + } catch {} + }); + conn.on("close", () => resolve(busy)); + conn.on("error", () => resolve(busy)); + }); +} + function formatStatus(s: ControlStatus): string { const idleLeft = Math.max(0, s.idleMs - (Date.now() - s.lastActiveAt)); return ( @@ -407,40 +432,43 @@ export async function controlCli(args: string[], ctx: ControlContext): Promise((resolve) => { - const conn = createConnection(paths.socket); - conn.on("connect", () => conn.write(encodeJson({ t: "stop" }))); - // Consume the reply, or the socket never reaches end/close. - conn.resume(); - conn.on("close", () => resolve()); - conn.on("error", () => resolve()); - }); - stopped = (await waitFor(async () => (isAlive(status.pid) ? null : true), 5000)) === true; - if (!stopped) { - try { - process.kill(status.pid, "SIGTERM"); - } catch {} - } - } - if (!status) { + running = await requestStop(paths.socket); + stopped = await waitForExit(status.pid, running > 0 ? 1000 : 5000); + } else { // Alive but not answering (wedged or stopped): terminate it if the // pid really is our daemon, not a recycled pid. const rec = readPidRecord(paths.pidFile); if (rec && rec.pid !== process.pid && isAlive(rec.pid) && looksLikeDaemon(rec.pid)) { + pid = rec.pid; try { process.kill(rec.pid, "SIGTERM"); - stoppedPid = rec.pid; - stopped = (await waitFor(async () => (isAlive(rec.pid) ? null : true), 3000)) === true; } catch {} + stopped = await waitForExit(rec.pid, 3000); } } const cleared = await clearStaleControlFiles(paths); - const wasRunning = stoppedPid != null; - if (json) out(JSON.stringify({ wasRunning, pid: stoppedPid, stopped: wasRunning && (stopped || status != null), clearedStale: cleared })); - else out(wasRunning ? `stopped (pid ${stoppedPid})` : cleared ? "not running (cleared stale files)" : "not running"); + const wasRunning = pid != null; + // Only report stopped once the process is really gone. + const stopping = wasRunning && !stopped; + if (json) { + out( + JSON.stringify({ + wasRunning, + pid, + stopped: wasRunning && stopped, + ...(stopping ? { stopping: true, busy: running } : {}), + clearedStale: cleared, + }), + ); + } else if (!wasRunning) out(cleared ? "not running (cleared stale files)" : "not running"); + else if (stopped) out(`stopped (pid ${pid})`); + else if (running > 0) out(`stopping (pid ${pid}); waiting for ${running} running command(s) to finish`); + else out(`stopping (pid ${pid}); it has not exited yet`); return 0; } ctx.stderr.write(`serve-sim: unknown control verb '${verb}'\n${CONTROL_USAGE}\n`); diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts index 56d2a66db..556a8977a 100644 --- a/packages/serve-sim/src/control-daemon.ts +++ b/packages/serve-sim/src/control-daemon.ts @@ -452,8 +452,9 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise Date: Tue, 10 Nov 2026 17:00:02 -0800 Subject: [PATCH 09/17] fix(control): adopt the caller's umask; keep sandboxed callers in-process Workers ran with the umask of whoever started the daemon, so files that `buffer dump` or `frame -o` wrote got the wrong modes. The client now sends process.umask() with `run` and the worker applies it. A worker can't enter the caller's OS sandbox, and a daemon started inside one would confine everyone's commands for the next 5 minutes. Callers with a known sandbox marker (CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, or Claude Code's SANDBOX_RUNTIME) now run in-process and never start a daemon. Also run `--file /dev/...` (e.g. /dev/stdin, /dev/fd/0) in-process: stdin isn't forwarded, so a worker would silently read /dev/null. --- .../src/__tests__/control-process.test.ts | 75 ++++++++++++++++++- .../__tests__/fixtures/control-fake-cli.ts | 1 + packages/serve-sim/src/control-client.ts | 4 + packages/serve-sim/src/control-protocol.ts | 28 ++++++- packages/serve-sim/src/control-worker.ts | 5 +- 5 files changed, 109 insertions(+), 4 deletions(-) diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index 2184c3ac2..ddba93eca 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -31,6 +31,7 @@ import { parseAcceptMs, parseIdleMs, parseJsonFrame, + sandboxMarker, unsafeControlDir, unsafeControlSocket, withoutNodeRuntimeEnv, @@ -63,6 +64,21 @@ describe("isDispatchable", () => { expect(isDispatchable(["iPhone 16"])).toBe(false); expect(isDispatchable(["--help", "tap"])).toBe(false); }); + + test("--file pointing at a /dev alias of stdin stays in-process", () => { + expect(isDispatchable(["type", "--file", "/dev/stdin"])).toBe(false); + expect(isDispatchable(["type", "--file=/dev/fd/0"])).toBe(false); + expect(isDispatchable(["paste", "-d", "X", "--file", "/dev/fd/3"])).toBe(false); + expect(isDispatchable(["type", "--file", "/tmp/notes.txt"])).toBe(true); + }); + + test("sandboxed callers are recognised by their env markers", () => { + expect(sandboxMarker({})).toBeNull(); + expect(sandboxMarker({ CODEX_SANDBOX: "seatbelt" })).toBe("CODEX_SANDBOX"); + expect(sandboxMarker({ CODEX_SANDBOX_NETWORK_DISABLED: "1" })).toBe("CODEX_SANDBOX_NETWORK_DISABLED"); + expect(sandboxMarker({ SANDBOX_RUNTIME: "1" })).toBe("SANDBOX_RUNTIME"); + expect(sandboxMarker({ SANDBOX_RUNTIME: "" })).toBeNull(); + }); }); describe("controlMode", () => { @@ -223,6 +239,30 @@ describe("adoptCaller", () => { rmSync(dir, { recursive: true, force: true }); }); + test("adopts the caller's umask when sent", () => { + const umasks: number[] = []; + const proc = { + argv: [], + env: {}, + chdir: () => {}, + umask: (m: number) => umasks.push(m), + stdout: {} as NodeJS.WriteStream, + stderr: {} as NodeJS.WriteStream, + } as unknown as NodeJS.Process; + const msg = { + t: "run" as const, + fingerprint: {} as never, + argv: [], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: false }, stderr: { isTTY: false } }, + }; + adoptCaller(msg, proc); + expect(umasks).toEqual([]); + adoptCaller({ ...msg, umask: 0o027 }, proc); + expect(umasks).toEqual([0o027]); + }); + test("keeps a 0-column TTY width and merges stderr into stdout for 2>&1", () => { const writes: string[] = []; const stdout = { write: (c: string) => writes.push(`out:${c}`) } as unknown as NodeJS.WriteStream; @@ -305,7 +345,17 @@ describeWithNode("control process", () => { SERVE_SIM_CONTROL_ACCEPT_MS: "30000", }; delete e.CI; - for (const k of ["NODE_OPTIONS", "NODE_EXTRA_CA_CERTS", "NODE_USE_ENV_PROXY", "MARKER", "FAKE_WORKER_LOAD_FAIL"]) delete e[k]; + for (const k of [ + "NODE_OPTIONS", + "NODE_EXTRA_CA_CERTS", + "NODE_USE_ENV_PROXY", + "MARKER", + "FAKE_WORKER_LOAD_FAIL", + "CODEX_SANDBOX", + "CODEX_SANDBOX_NETWORK_DISABLED", + "SANDBOX_RUNTIME", + ]) + delete e[k]; delete e.SERVE_SIM_CONTROL; delete e.EXIT_CODE; for (const [k, v] of Object.entries(extra)) { @@ -882,4 +932,27 @@ describeWithNode("control process", () => { child.kill("SIGINT"); }); + test("workers run with the caller's umask", async () => { + const daemon = await startDaemon(); + const script = `umask $2 && exec "$0" "$1" tap 1 1`; + for (const mask of ["077", "027"]) { + const r = await run("/bin/sh", ["-c", script, nodePath!, binFile, mask]); + const seen = JSON.parse(r.stdout); + expect(seen.ppid).toBe(daemon.pid); + expect(seen.umask).toBe(parseInt(mask, 8)); + } + }); + + test("sandboxed callers run in-process and never start a daemon", async () => { + for (const marker of [{ CODEX_SANDBOX: "seatbelt" }, { SANDBOX_RUNTIME: "1" }]) { + expect((await cli(["tap", "1", "1"], { env: marker })).code).toBe(0); + } + await Bun.sleep(300); + expect((await status()).running).toBe(false); + expect(daemonPids()).toEqual([]); + const daemon = await startDaemon(); + const seen = JSON.parse((await cli(["tap", "1", "1"], { env: { CODEX_SANDBOX_NETWORK_DISABLED: "1" } })).stdout); + expect(seen.ppid).not.toBe(daemon.pid); + expect((await status()).served).toBe(0); + }); }); diff --git a/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts index 977a8723f..91436ce45 100644 --- a/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts +++ b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts @@ -26,6 +26,7 @@ async function main() { columns: process.stdout.columns ?? null, pid: process.pid, ppid: process.ppid, + umask: process.umask(), }), ); process.stderr.write("to stderr\n"); diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index 2be13573c..8332eac9e 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -25,6 +25,7 @@ import { isDispatchable, nodeRuntimeOverride, parseJsonFrame, + sandboxMarker, unsafeControlDir, unsafeControlSocket, withoutNodeRuntimeEnv, @@ -141,6 +142,8 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise if (!isDispatchable(args)) return bypass("not dispatchable"); const runtime = nodeRuntimeOverride(ctx.env, ctx.execArgv); if (runtime) return bypass(`caller sets ${runtime}`); + const sandbox = sandboxMarker(ctx.env); + if (sandbox) return bypass(`sandboxed (${sandbox})`); let cwd: string; try { cwd = ctx.cwd(); @@ -209,6 +212,7 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise stderr: { isTTY: ctx.stderr.isTTY === true, columns: ctx.stderr.columns }, }, sharedOutput: sameOutputFile(), + umask: process.umask(), }); }); conn.on("data", (chunk) => { diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts index 22b008cdd..30cfd39f9 100644 --- a/packages/serve-sim/src/control-protocol.ts +++ b/packages/serve-sim/src/control-protocol.ts @@ -59,11 +59,22 @@ export function isDispatchable(args: readonly string[]): boolean { if (args.length === 1 && ROOT_INFO_FLAGS.has(first)) return true; if (first === "help") return args.length <= 2; if (!DISPATCHABLE_COMMANDS.has(first)) return false; - // stdin is not forwarded to workers. + // stdin is not forwarded to workers (nor are its /dev aliases). if (args.includes("--stdin")) return false; + if (readsDevFile(args)) return false; return true; } +/** `--file /dev/stdin`, `--file=/dev/fd/0` and friends read the caller's fds. */ +function readsDevFile(args: readonly string[]): boolean { + for (let i = 0; i < args.length; i++) { + const a = args[i]!; + const value = a === "--file" ? args[i + 1] : a.startsWith("--file=") ? a.slice("--file=".length) : null; + if (value != null && value.startsWith("/dev/")) return true; + } + return false; +} + export type ControlMode = "off" | "use" | "auto"; /** @@ -99,6 +110,19 @@ export function withoutNodeRuntimeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv return out; } +/** + * Env markers of an OS sandbox around the caller (Codex's seatbelt, Claude + * Code's sandbox runtime). A worker can't enter the caller's sandbox, and a + * daemon started inside one would confine everyone else's commands, so + * these callers run in-process and never start a daemon. + */ +const SANDBOX_ENV = ["CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "SANDBOX_RUNTIME"] as const; + +export function sandboxMarker(env: NodeJS.ProcessEnv): string | null { + for (const key of SANDBOX_ENV) if (env[key]) return key; + return null; +} + /** The first runtime setting the caller has that a worker can't honor. */ export function nodeRuntimeOverride(env: NodeJS.ProcessEnv, execArgv: readonly string[]): string | null { for (const key of NODE_RUNTIME_ENV) if (env[key]) return key; @@ -308,6 +332,8 @@ export type ControlMessage = tty: { stdout: StreamTty; stderr: StreamTty }; /** The caller's stdout and stderr are the same file (e.g. `2>&1`). */ sharedOutput?: boolean; + /** The caller's umask, so files the command writes get its modes. */ + umask?: number; } // Two-phase start: the daemon replies `accepted` once it holds a worker // for the caller, and only hands it the command after the caller's `go`. diff --git a/packages/serve-sim/src/control-worker.ts b/packages/serve-sim/src/control-worker.ts index 91703d6b5..78ea11c4f 100644 --- a/packages/serve-sim/src/control-worker.ts +++ b/packages/serve-sim/src/control-worker.ts @@ -1,8 +1,8 @@ /** * A pre-warmed, single-use worker. It loads the full CLI bundle ahead of time * (that load is most of a cold `serve-sim` call), tells the daemon it is - * ready, then waits for one command: it adopts the caller's argv, cwd, env - * and TTY shape, runs the CLI exactly as the normal bin would, and exits. + * ready, then waits for one command: it adopts the caller's argv, cwd, env, + * umask and TTY shape, runs the CLI exactly as the normal bin would, and exits. * * Because every command still gets its own process, `process.exit`, exit * codes, signal handlers and module state behave as in a direct run. @@ -34,6 +34,7 @@ function blockingWrites(stream: NodeJS.WriteStream): void { /** @lintignore Exported for tests. */ export function adoptCaller(message: RunMessage, proc: NodeJS.Process = process): void { proc.chdir(message.cwd); + if (typeof message.umask === "number") proc.umask(message.umask); for (const key of Object.keys(proc.env)) { if (!(key in message.env)) delete proc.env[key]; } From e515b9ade3c12d2431d08ea09da2362a16b5a4fa Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Tue, 10 Nov 2026 17:00:02 -0800 Subject: [PATCH 10/17] fix(control): show a recent worker load failure in control status When workers couldn't load the CLI, status only said "not running" even though the .failed record is what stops commands from auto-starting a daemon. It now prints the failure, its age, and points to `serve-sim control start` to retry (json: `failed: {at, reason}`). --- .../src/__tests__/control-process.test.ts | 6 +++++ packages/serve-sim/src/control-client.ts | 23 +++++++++++++++++-- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index ddba93eca..cf3b8c069 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -743,6 +743,12 @@ describeWithNode("control process", () => { expect(start.stderr).toContain("cannot load ws"); expect(existsSync(paths().failFile)).toBe(true); await until(async () => daemonPids().length === 0); + // status explains why nothing is running. + const st = await cli(["control", "status"], broken); + expect(st.code).toBe(1); + expect(st.stdout).toMatch(/workers failed to load the CLI .*`serve-sim control start` to retry/s); + expect(st.stdout).toContain("cannot load ws"); + expect(JSON.parse((await cli(["control", "status", "--json"], broken)).stdout).failed.reason).toContain("cannot load ws"); // In-process still works, and the fail marker stops auto-start. for (let i = 0; i < 3; i++) expect(await cli(["--version"], broken)).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index 8332eac9e..3113d7570 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -386,8 +386,27 @@ export async function controlCli(args: string[], ctx: ControlContext): Promise Date: Tue, 10 Nov 2026 17:00:02 -0800 Subject: [PATCH 11/17] docs(control): document umask, sandbox bypass, held-worker fallback and stop Note what doesn't carry over to workers (rlimits, nice level, OS sandbox, stdin), which sandbox markers keep callers in-process, that a reserved worker dying before the hand-off falls back in-process, and that stop reports "stopping" while commands finish. --- packages/serve-sim/README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/packages/serve-sim/README.md b/packages/serve-sim/README.md index c81c14148..9b5543512 100644 --- a/packages/serve-sim/README.md +++ b/packages/serve-sim/README.md @@ -364,16 +364,17 @@ Limits: sampling at 4 fps can miss a state shown for less than a tick (record fo Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now an 18 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. - **Which commands**: `tap`, `gesture`, `settle`, `button`, `type`, `paste`, `rotate`, `fold`, `ca-debug`, `memory-warning`, `event-log`, `ax`, `buffer`, and bare `--help`/`--version`. Everything else runs in-process as before: the preview server, `--detach`, `record`, `camera`, `exec`, `doctor`, `permissions`, `ui`, and anything with `--stdin` (stdin is not forwarded). -- **What carries over**: argv, cwd, the full environment, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. -- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. -- **Fallback**: the daemon first reserves a warm worker and replies "accepted"; the command is only handed to the worker after the caller confirms. If the control process is missing, stale, or doesn't reserve a worker within 1 s (`SERVE_SIM_CONTROL_ACCEPT_MS`), nothing has run yet and the command runs in-process. Once the caller has confirmed, it never falls back: a lost connection fails that call (exit 1) instead of running the command twice. +- **What carries over**: argv, cwd, the full environment, the umask, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. What does not carry over: resource limits (`ulimit`), the nice level, and any OS sandbox around the caller; those come from whoever started the control process. stdin isn't forwarded either, so `--stdin` and `--file /dev/...` run in-process. +- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. So do callers inside a known agent sandbox (`CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, or Claude Code's `SANDBOX_RUNTIME`), and they never start one, so a daemon is never born inside a sandbox or used to step outside it. Other sandboxes aren't detected; set `SERVE_SIM_CONTROL=0` under them. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. +- **Fallback**: the daemon first reserves a warm worker and replies "accepted"; the command is only handed to the worker after the caller confirms. If the control process is missing, stale, or doesn't reserve a worker within 1 s (`SERVE_SIM_CONTROL_ACCEPT_MS`), nothing has run yet and the command runs in-process. Once the caller has confirmed, it never falls back: a lost connection fails that call (exit 1) instead of running the command twice. If the reserved worker dies before it is handed the command (for example `pkill node`), or the caller takes more than 10 s to confirm, the daemon frees it and the caller runs the command in-process. - **Broken installs**: if workers can't load the CLI, the daemon records why in a `.failed` file next to its socket and exits. Commands keep running in-process, and for 10 minutes (or until the dist is rebuilt) they don't start a new daemon. `serve-sim control start` retries immediately, and only reports success once a worker has loaded; otherwise it prints the worker's error and exits 1. - **Off switch**: `SERVE_SIM_CONTROL=0` never uses or starts it. Under `CI` it is only used if already running; `SERVE_SIM_CONTROL=1` auto-starts it there too. ```sh -serve-sim control status [--json] # exit 1 when not running +serve-sim control status [--json] # exit 1 when not running; shows a recent worker load failure serve-sim control start # idempotent; waits until it answers serve-sim control stop # idempotent; also clears stale socket/pid files + # (says "stopping" while running commands finish) ``` It listens on a Unix socket at `$TMPDIR/serve-sim-control-/control-.sock` (or under `SERVE_SIM_CONTROL_DIR`), with a pid file next to it. `` is derived from the bin path, the node binary, and `HOME`. Callers send their whole environment over that socket, so both sides check ownership first: the directory must be a real directory (not a symlink) owned by you with no group/other access, and the socket must be a socket owned by you. Otherwise commands run in-process and the daemon refuses to start. The socket is created owner-only (mode 0600) with no window where it is more open. A daemon that finds a dead socket replaces it. When several start at once, the extra ones see their socket was taken over and exit. From 268f22cec075040b8d0167991b7694f474acd1a5 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 09:18:03 -0800 Subject: [PATCH 12/17] fix(control): refuse control start inside a sandbox; resolve --file before the /dev check - `serve-sim control start` now exits 1 with "control process can't start inside a sandbox ()" when a sandbox env marker is set, so a daemon is never born inside one. - --file values are resolved against the caller's cwd and followed through symlinks before the /dev/ check, so ../../dev/stdin or a link to /dev/stdin stays in-process. The daemon re-checks with the run's cwd. - The stopping reply counts busyChildren + held rather than `busy`, which still includes queued callers that were just bypassed. - Fold `} else if` in start(). - Held-worker test stalls 5 s (under the 10 s go timeout) with a longer idle window so the daemon outlives the stall. --- .../src/__tests__/control-process.test.ts | 46 +++++++++++++++++-- packages/serve-sim/src/control-client.ts | 17 +++++-- packages/serve-sim/src/control-daemon.ts | 11 +++-- packages/serve-sim/src/control-protocol.ts | 44 ++++++++++++++---- 4 files changed, 96 insertions(+), 22 deletions(-) diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index cf3b8c069..5a8bdba0d 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -6,6 +6,7 @@ import { mkdirSync, mkdtempSync, readFileSync, + readdirSync, realpathSync, rmSync, statSync, @@ -72,6 +73,27 @@ describe("isDispatchable", () => { expect(isDispatchable(["type", "--file", "/tmp/notes.txt"])).toBe(true); }); + test("--file resolves against the caller's cwd and through symlinks before the /dev check", () => { + const dir = realpathSync(mkdtempSync("/tmp/ssctl-devfile-")); + try { + const up = "../".repeat(dir.split("/").length); + expect(isDispatchable(["type", "--file", `${up}dev/stdin`], dir)).toBe(false); + expect(isDispatchable(["type", `--file=./../${up}dev/fd/0`], dir)).toBe(false); + symlinkSync("/dev/stdin", join(dir, "in")); + expect(isDispatchable(["type", "--file", "in"], dir)).toBe(false); + symlinkSync("in", join(dir, "in2")); + expect(isDispatchable(["type", "--file", "in2"], dir)).toBe(false); + symlinkSync("/dev", join(dir, "devdir")); + expect(isDispatchable(["type", "--file", "devdir/fd/0"], dir)).toBe(false); + expect(isDispatchable(["type", "--file", join(dir, "in")])).toBe(false); + writeFileSync(join(dir, "notes.txt"), "hi"); + expect(isDispatchable(["type", "--file", "notes.txt"], dir)).toBe(true); + expect(isDispatchable(["type", "--file", "missing.txt"], dir)).toBe(true); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); + test("sandboxed callers are recognised by their env markers", () => { expect(sandboxMarker({})).toBeNull(); expect(sandboxMarker({ CODEX_SANDBOX: "seatbelt" })).toBe("CODEX_SANDBOX"); @@ -889,13 +911,17 @@ describeWithNode("control process", () => { .map(Number); test("a held worker that dies before go sends the caller in-process and frees the daemon", async () => { - const r0 = await cli(["control", "start", "--json"], { env: { SERVE_SIM_CONTROL_IDLE_MS: "1500" } }); + // Idle longer than the client's stall, so the daemon is still there to + // report busy 0 once the stall ends. + const r0 = await cli(["control", "start", "--json"], { env: { SERVE_SIM_CONTROL_IDLE_MS: "7000" } }); const daemon = JSON.parse(r0.stdout) as { pid: number }; await warm(); const marker = join(work, "ran.txt"); // The client stalls after `run`, so the daemon holds a worker for it // while we kill every worker (the held one included). - const pending = race({ stallAfter: "run", stallMs: 1500, acceptTimeoutMs: 30_000, marker }); + // stallMs only has to outlast the polling and kills below, and stay + // under the daemon's 10 s go timeout. + const pending = race({ stallAfter: "run", stallMs: 5000, acceptTimeoutMs: 30_000, marker }); await until(async () => (await status()).busy === 1); for (const pid of workerPids(daemon.pid)) process.kill(pid, "SIGKILL"); const r = await pending; @@ -905,8 +931,8 @@ describeWithNode("control process", () => { // The real bin finishes such a call in-process. expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); // Nothing pins it: it still idle-exits. - await until(async () => !alive(daemon.pid), 8000); - }); + await until(async () => !alive(daemon.pid), 12_000); + }, 30_000); test("stop with a command in flight reports stopping, not stopped", async () => { const daemon = await startDaemon(); @@ -961,4 +987,16 @@ describeWithNode("control process", () => { expect(seen.ppid).not.toBe(daemon.pid); expect((await status()).served).toBe(0); }); + + test("control start refuses inside a sandbox", async () => { + for (const [key, value] of [["CODEX_SANDBOX", "seatbelt"], ["SANDBOX_RUNTIME", "1"]] as const) { + const r = await cli(["control", "start"], { env: { [key]: value } }); + expect(r.code).toBe(1); + expect(r.stderr).toBe(`serve-sim: control process can't start inside a sandbox (${key})\n`); + } + await Bun.sleep(300); + expect((await status()).running).toBe(false); + expect(daemonPids()).toEqual([]); + expect(existsSync(ctlDir) ? readdirSync(ctlDir) : []).toEqual([]); + }); }); diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index 3113d7570..c97f42adf 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -139,17 +139,17 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise const bypass = (reason: string) => Promise.resolve({ kind: "bypass", reason }); const mode = controlMode(ctx.env); if (mode === "off") return bypass("disabled"); - if (!isDispatchable(args)) return bypass("not dispatchable"); - const runtime = nodeRuntimeOverride(ctx.env, ctx.execArgv); - if (runtime) return bypass(`caller sets ${runtime}`); - const sandbox = sandboxMarker(ctx.env); - if (sandbox) return bypass(`sandboxed (${sandbox})`); let cwd: string; try { cwd = ctx.cwd(); } catch { return bypass("no cwd"); } + if (!isDispatchable(args, cwd)) return bypass("not dispatchable"); + const runtime = nodeRuntimeOverride(ctx.env, ctx.execArgv); + if (runtime) return bypass(`caller sets ${runtime}`); + const sandbox = sandboxMarker(ctx.env); + if (sandbox) return bypass(`sandboxed (${sandbox})`); const paths = pathsFor(ctx); const fingerprint = controlFingerprint(ctx); const unusable = unusableSocket(paths); @@ -410,6 +410,13 @@ export async function controlCli(args: string[], ctx: ControlContext): Promise MAX_SOCKET_PATH_BYTES; diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts index 556a8977a..bda89df25 100644 --- a/packages/serve-sim/src/control-daemon.ts +++ b/packages/serve-sim/src/control-daemon.ts @@ -328,7 +328,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise = new Set([ const ROOT_INFO_FLAGS = new Set(["--help", "-h", "--version", "-v"]); -/** Whether `args` (argv after the script) may run in a warm worker. */ -export function isDispatchable(args: readonly string[]): boolean { +/** + * Whether `args` (argv after the script) may run in a warm worker. `cwd` is + * the caller's working directory, used to resolve relative `--file` paths. + */ +export function isDispatchable(args: readonly string[], cwd?: string): boolean { const [first] = args; if (first == null) return false; // bare `serve-sim` starts the preview server if (args.length === 1 && ROOT_INFO_FLAGS.has(first)) return true; @@ -61,16 +64,41 @@ export function isDispatchable(args: readonly string[]): boolean { if (!DISPATCHABLE_COMMANDS.has(first)) return false; // stdin is not forwarded to workers (nor are its /dev aliases). if (args.includes("--stdin")) return false; - if (readsDevFile(args)) return false; + if (readsDevFile(args, cwd)) return false; return true; } -/** `--file /dev/stdin`, `--file=/dev/fd/0` and friends read the caller's fds. */ -function readsDevFile(args: readonly string[]): boolean { +/** + * `--file /dev/stdin`, `--file=/dev/fd/0` and friends read the caller's fds. + * Relative paths (`../../dev/stdin`) and symlinks into /dev count too. + */ +export function readsDevFile(args: readonly string[], cwd?: string): boolean { for (let i = 0; i < args.length; i++) { const a = args[i]!; const value = a === "--file" ? args[i + 1] : a.startsWith("--file=") ? a.slice("--file=".length) : null; - if (value != null && value.startsWith("/dev/")) return true; + if (value == null || value === "") continue; + if (!isAbsolute(value) && cwd == null) continue; + if (intoDev(isAbsolute(value) ? resolve(value) : resolve(cwd!, value))) return true; + } + return false; +} + +/** + * Whether `path` lands in /dev/, following symlinks one hop at a time + * (realpath on /dev/stdin itself resolves fd 0, which can fail or vary). + */ +function intoDev(path: string): boolean { + let p = path; + for (let hop = 0; hop < 32; hop++) { + if (p.startsWith("/dev/")) return true; + try { + p = join(realpathSync(dirname(p)), basename(p)); + if (p.startsWith("/dev/")) return true; + if (!lstatSync(p).isSymbolicLink()) return false; + p = resolve(dirname(p), readlinkSync(p)); + } catch { + return false; + } } return false; } From fd9614b9622a3d1f11b762c7477ffd974b19f678 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 09:18:03 -0800 Subject: [PATCH 13/17] docs(control): note sandboxed start refusal, direct-run pipe truncation and --file resolution --- packages/serve-sim/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/serve-sim/README.md b/packages/serve-sim/README.md index 9b5543512..1a0ee1d63 100644 --- a/packages/serve-sim/README.md +++ b/packages/serve-sim/README.md @@ -364,8 +364,8 @@ Limits: sampling at 4 fps can miss a state shown for less than a tick (record fo Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now an 18 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. - **Which commands**: `tap`, `gesture`, `settle`, `button`, `type`, `paste`, `rotate`, `fold`, `ca-debug`, `memory-warning`, `event-log`, `ax`, `buffer`, and bare `--help`/`--version`. Everything else runs in-process as before: the preview server, `--detach`, `record`, `camera`, `exec`, `doctor`, `permissions`, `ui`, and anything with `--stdin` (stdin is not forwarded). -- **What carries over**: argv, cwd, the full environment, the umask, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. What does not carry over: resource limits (`ulimit`), the nice level, and any OS sandbox around the caller; those come from whoever started the control process. stdin isn't forwarded either, so `--stdin` and `--file /dev/...` run in-process. -- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. So do callers inside a known agent sandbox (`CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, or Claude Code's `SANDBOX_RUNTIME`), and they never start one, so a daemon is never born inside a sandbox or used to step outside it. Other sandboxes aren't detected; set `SERVE_SIM_CONTROL=0` under them. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. +- **What carries over**: argv, cwd, the full environment, the umask, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. That is better than a direct run: when stdout is a pipe on macOS, a direct run can cut that output short (to 64 KiB) because Node writes pipes asynchronously. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. What does not carry over: resource limits (`ulimit`), the nice level, and any OS sandbox around the caller; those come from whoever started the control process. stdin isn't forwarded either, so `--stdin` and `--file` paths that resolve into `/dev/` (relative or via a symlink) run in-process. +- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. So do callers inside a known agent sandbox (`CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, or Claude Code's `SANDBOX_RUNTIME`), and they never start one (`serve-sim control start` refuses there too), so a daemon is never born inside a sandbox or used to step outside it. Other sandboxes aren't detected; set `SERVE_SIM_CONTROL=0` under them. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. - **Fallback**: the daemon first reserves a warm worker and replies "accepted"; the command is only handed to the worker after the caller confirms. If the control process is missing, stale, or doesn't reserve a worker within 1 s (`SERVE_SIM_CONTROL_ACCEPT_MS`), nothing has run yet and the command runs in-process. Once the caller has confirmed, it never falls back: a lost connection fails that call (exit 1) instead of running the command twice. If the reserved worker dies before it is handed the command (for example `pkill node`), or the caller takes more than 10 s to confirm, the daemon frees it and the caller runs the command in-process. - **Broken installs**: if workers can't load the CLI, the daemon records why in a `.failed` file next to its socket and exits. Commands keep running in-process, and for 10 minutes (or until the dist is rebuilt) they don't start a new daemon. `serve-sim control start` retries immediately, and only reports success once a worker has loaded; otherwise it prints the worker's error and exits 1. - **Off switch**: `SERVE_SIM_CONTROL=0` never uses or starts it. Under `CI` it is only used if already running; `SERVE_SIM_CONTROL=1` auto-starts it there too. From 67fd553758d3ea51be292d7407d401ac0dcc0235 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 09:28:21 -0800 Subject: [PATCH 14/17] fix(control): treat Linux /proc//fd paths as fd aliases in the --file check --- packages/serve-sim/src/control-protocol.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts index 86b25d0b1..e816a53d4 100644 --- a/packages/serve-sim/src/control-protocol.ts +++ b/packages/serve-sim/src/control-protocol.ts @@ -90,10 +90,10 @@ export function readsDevFile(args: readonly string[], cwd?: string): boolean { function intoDev(path: string): boolean { let p = path; for (let hop = 0; hop < 32; hop++) { - if (p.startsWith("/dev/")) return true; + if (isFdPath(p)) return true; try { p = join(realpathSync(dirname(p)), basename(p)); - if (p.startsWith("/dev/")) return true; + if (isFdPath(p)) return true; if (!lstatSync(p).isSymbolicLink()) return false; p = resolve(dirname(p), readlinkSync(p)); } catch { @@ -103,6 +103,11 @@ function intoDev(path: string): boolean { return false; } +/** /dev/... or, on Linux where /dev/fd -> /proc/self/fd, /proc//fd/... */ +function isFdPath(p: string): boolean { + return p.startsWith("/dev/") || /^\/proc\/(?:self|thread-self|\d+)\/fd\//.test(p); +} + export type ControlMode = "off" | "use" | "auto"; /** From 8bf77f915cc6e450673d7b6091fe225357b3fa77 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 09:48:16 -0800 Subject: [PATCH 15/17] fix(control): apply output backpressure, validate run requests, bound control stop - Daemon pauses the worker's stdout/stderr while the caller's socket is full and resumes on drain (and discards once the caller is gone), so a slow reader of a big output can't grow the shared daemon's memory. The client pauses the socket while stdout/stderr are full and resumes once every full destination has drained. Status reports `buffered` bytes. - `run` requests are validated and reduced to known fields before use; a missing/mistyped fingerprint, argv, cwd, env, tty or umask is bypassed instead of throwing, and runJob rejections are always observed. - `control stop` gives the stop request a 2 s deadline; a daemon that answers ping but never acknowledges goes through the unresponsive path, which only SIGTERMs the pid-file pid after the existing checks and when it matches the pid the daemon reported. --- .../src/__tests__/control-process.test.ts | 109 +++++++++++++++++- packages/serve-sim/src/control-client.ts | 82 ++++++++++--- packages/serve-sim/src/control-daemon.ts | 54 +++++++-- packages/serve-sim/src/control-protocol.ts | 48 ++++++++ packages/serve-sim/src/control-worker.ts | 4 +- 5 files changed, 263 insertions(+), 34 deletions(-) diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts index 5a8bdba0d..dd5f00787 100644 --- a/packages/serve-sim/src/__tests__/control-process.test.ts +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -413,7 +413,7 @@ describeWithNode("control process", () => { .stdout.split("\n") .filter(Boolean); - async function status(): Promise<{ running: boolean; pid?: number; served?: number; warm?: number; busy?: number }> { + async function status(): Promise<{ running: boolean; pid?: number; served?: number; warm?: number; busy?: number; buffered?: number }> { const r = await cli(["control", "status", "--json"]); return JSON.parse(r.stdout); } @@ -665,6 +665,45 @@ describeWithNode("control process", () => { c.resume(); }); expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); + + // `run` requests missing or mistyping required fields are bypassed, + // never crash the daemon, and never stop it as a "stale build". + const fp = controlFingerprint({ binFile, mainFile, execPath: nodePath!, env: env() }); + const good = { + t: "run", + fingerprint: fp, + argv: ["tap", "1", "1"], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: false }, stderr: { isTTY: false } }, + }; + const malformed: unknown[] = [ + { t: "run" }, + { ...good, fingerprint: undefined }, + { ...good, fingerprint: null }, + { ...good, fingerprint: {} }, + { ...good, fingerprint: { ...fp, protocol: "1" } }, + { ...good, argv: "tap" }, + { ...good, argv: ["tap", 1] }, + { ...good, cwd: undefined }, + { ...good, env: { A: 1 } }, + { ...good, tty: undefined }, + { ...good, tty: { stdout: { isTTY: false } } }, + { ...good, umask: "022" }, + ]; + for (const msg of malformed) { + const reply = await new Promise((resolve) => { + const c = createConnection(paths.socket); + let data = Buffer.alloc(0); + c.on("connect", () => c.write(encodeFrame(FRAME_JSON, JSON.stringify(msg)))); + c.on("data", (d) => (data = Buffer.concat([data, Buffer.from(d)]))); + c.on("close", () => resolve(new FrameDecoder().push(data).map((f) => f.payload.toString()).join(""))); + }); + expect(JSON.parse(reply)).toEqual({ t: "bypass", reason: "malformed run request" }); + } + const after = await status(); + expect(after).toMatchObject({ running: true, busy: 0, served: 1 }); + expect(JSON.parse((await cli(["tap", "1", "1"])).stdout).ppid).toBe(after.pid); }); // ─── Review regressions ────────────────────────────────────────────── @@ -795,6 +834,40 @@ describeWithNode("control process", () => { expect((await status()).served).toBe(1); }); + test("a slow reader holds back a big output instead of buffering it in the daemon", async () => { + const daemon = await startDaemon(); + const rss = (pid: number) => Number(spawnSync("ps", ["-o", "rss=", "-p", String(pid)], { encoding: "utf8" }).stdout.trim()) * 1024; + const before = rss(daemon.pid); + const size = 64 * 1024 * 1024; + // Nobody reads the pipe for 3 s, then it is counted. Under 2>&1 and + // with separate streams. + const pending = Promise.all( + [`"$0" "$1" event-log $2 | (sleep 3; wc -c)`, `"$0" "$1" event-log $2 2>&1 | (sleep 3; wc -c)`].map((script) => + run("/bin/sh", ["-c", script, nodePath!, binFile, String(size)]), + ), + ); + await until(async () => (await status()).busy === 2); + let peakBuffered = 0; + let peakRss = 0; + const end = Date.now() + 2000; + while (Date.now() < end) { + const s = await status(); + // Still in flight: the workers are waiting on the readers. + expect(s.busy).toBe(2); + peakBuffered = Math.max(peakBuffered, s.buffered ?? 0); + peakRss = Math.max(peakRss, rss(daemon.pid)); + await Bun.sleep(100); + } + expect(peakBuffered).toBeLessThan(4 * 1024 * 1024); + expect(peakRss - before).toBeLessThan(32 * 1024 * 1024); + for (const r of await pending) { + expect(r.code).toBe(0); + expect(r.stdout.trim()).toBe(String(size)); + } + await until(async () => (await status()).busy === 0); + expect((await status()).served).toBe(2); + }, 30_000); + test("keeps stdout/stderr order under 2>&1", async () => { const daemon = await startDaemon(); const expected = Array.from({ length: 40 }, (_, i) => `out${i}\nerr${i}\n`).join("") + `ppid ${daemon.pid}\n`; @@ -934,6 +1007,40 @@ describeWithNode("control process", () => { await until(async () => !alive(daemon.pid), 12_000); }, 30_000); + test("stop gives up on a daemon that never acknowledges and terminates only the recorded one", async () => { + const p = paths(); + // Answers ping like a daemon but ignores stop; `__control-daemon` in its + // argv is what the pid check looks for. + const script = ` + const net = require("net"); + const pong = (pid) => { const b = Buffer.from(JSON.stringify({ t: "pong", status: { pid, startedAt: 0, lastActiveAt: Date.now(), idleMs: 60000, warm: 1, warming: 0, busy: 0, served: 0, socket: ${JSON.stringify(p.socket)} } })); const h = Buffer.alloc(5); h.writeUInt8(0x4a, 0); h.writeUInt32BE(b.length, 1); return Buffer.concat([h, b]); }; + net.createServer((c) => c.on("data", (d) => { if (d.includes('"ping"')) c.end(pong(process.pid)); })).listen(${JSON.stringify(p.socket)}, () => console.log("up"));`; + const startFake = async () => { + const fake = spawn(nodePath!, ["-e", script, "__control-daemon"]); + stray.push(fake); + await new Promise((resolve) => fake.stdout.on("data", () => resolve())); + return fake; + }; + + // The pid file names someone else: nothing is killed. + const fake = await startFake(); + const bystander = spawn("/bin/sleep", ["30"]); + stray.push(bystander); + writeFileSync(p.pidFile, JSON.stringify({ pid: bystander.pid })); + const t0 = Date.now(); + const r1 = JSON.parse((await cli(["control", "stop", "--json"])).stdout); + expect(Date.now() - t0).toBeLessThan(10_000); + expect(r1).toMatchObject({ wasRunning: true, pid: fake.pid, stopped: false }); + expect(alive(fake.pid!)).toBe(true); + expect(alive(bystander.pid!)).toBe(true); + + // The pid file names it: it is terminated after the deadline. + writeFileSync(p.pidFile, JSON.stringify({ pid: fake.pid })); + const r2 = JSON.parse((await cli(["control", "stop", "--json"])).stdout); + expect(r2).toMatchObject({ wasRunning: true, pid: fake.pid, stopped: true }); + expect(alive(fake.pid!)).toBe(false); + }, 30_000); + test("stop with a command in flight reports stopping, not stopped", async () => { const daemon = await startDaemon(); const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts index c97f42adf..f2686763c 100644 --- a/packages/serve-sim/src/control-client.ts +++ b/packages/serve-sim/src/control-client.ts @@ -215,6 +215,20 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise umask: process.umask(), }); }); + // Backpressure: stop reading the socket while stdout/stderr can't keep + // up, so the daemon stops reading the worker instead of anyone + // buffering a big output in memory. Resume once every full destination + // has drained. + const full = new Set(); + const relay = (dest: NodeJS.WriteStream, payload: Buffer) => { + if (dest.write(payload) || full.has(dest)) return; + full.add(dest); + conn.pause(); + dest.once("drain", () => { + full.delete(dest); + if (full.size === 0 && !settled) conn.resume(); + }); + }; conn.on("data", (chunk) => { if (settled) return; let frames; @@ -227,11 +241,11 @@ export function dispatchViaControl(args: string[], ctx: ControlContext): Promise for (const frame of frames) { if (settled) return; if (frame.type === FRAME_STDOUT) { - ctx.stdout.write(frame.payload); + relay(ctx.stdout, frame.payload); continue; } if (frame.type === FRAME_STDERR) { - ctx.stderr.write(frame.payload); + relay(ctx.stderr, frame.payload); continue; } const msg = parseJsonFrame(frame); @@ -339,27 +353,54 @@ function waitForExit(pid: number, timeoutMs: number): Promise { return waitFor(async () => (isAlive(pid) ? null : true), timeoutMs).then((v) => v === true); } -/** Ask the daemon to stop; resolves with how many commands it is still running. */ -function requestStop(socket: string): Promise { +/** How long `control stop` waits for the daemon to acknowledge a stop. */ +const STOP_REPLY_TIMEOUT_MS = 2000; + +/** + * Ask the daemon to stop; resolves with how many commands it is still + * running, or null when it never acknowledged (wedged after answering ping). + */ +function requestStop(socket: string, timeoutMs = STOP_REPLY_TIMEOUT_MS): Promise { return new Promise((resolve) => { const conn = createConnection(socket); const decoder = new FrameDecoder(); - let busy = 0; + let busy: number | null = null; + const done = () => { + clearTimeout(timer); + conn.destroy(); + resolve(busy); + }; + const timer = setTimeout(done, timeoutMs); conn.on("connect", () => conn.write(encodeJson({ t: "stop" }))); // Read the reply, or the socket never reaches end/close. conn.on("data", (chunk) => { try { for (const frame of decoder.push(chunk)) { const msg = parseJsonFrame(frame); - if (msg?.t === "stopping" && typeof msg.busy === "number") busy = msg.busy; + if (msg?.t === "stopping") busy = typeof msg.busy === "number" ? msg.busy : 0; } } catch {} }); - conn.on("close", () => resolve(busy)); - conn.on("error", () => resolve(busy)); + conn.on("close", done); + conn.on("error", done); }); } +/** + * SIGTERM an unresponsive daemon, but only if the pid file names a live + * control daemon (not us, not a recycled pid) and, when `expected` is known + * from a ping, the same one. Resolves the pid tried and whether it exited. + */ +async function terminateRecordedDaemon(paths: ControlPaths, expected?: number): Promise<{ pid: number; stopped: boolean } | null> { + const rec = readPidRecord(paths.pidFile); + if (!rec || rec.pid === process.pid || (expected != null && rec.pid !== expected)) return null; + if (!isAlive(rec.pid) || !looksLikeDaemon(rec.pid)) return null; + try { + process.kill(rec.pid, "SIGTERM"); + } catch {} + return { pid: rec.pid, stopped: await waitForExit(rec.pid, 3000) }; +} + function formatStatus(s: ControlStatus): string { const idleLeft = Math.max(0, s.idleMs - (Date.now() - s.lastActiveAt)); return ( @@ -466,19 +507,22 @@ export async function controlCli(args: string[], ctx: ControlContext): Promise 0 ? 1000 : 5000); } else { - // Alive but not answering (wedged or stopped): terminate it if the - // pid really is our daemon, not a recycled pid. - const rec = readPidRecord(paths.pidFile); - if (rec && rec.pid !== process.pid && isAlive(rec.pid) && looksLikeDaemon(rec.pid)) { - pid = rec.pid; - try { - process.kill(rec.pid, "SIGTERM"); - } catch {} - stopped = await waitForExit(rec.pid, 3000); + // Alive but not answering (wedged or stopped), or it answered ping + // but never acknowledged the stop: terminate it if the pid really is + // our daemon, not a recycled pid. + // (One that exited on its own meanwhile just counts as stopped.) + if (status && !isAlive(status.pid)) stopped = true; + else { + const killed = await terminateRecordedDaemon(paths, status?.pid); + if (killed) { + pid = killed.pid; + stopped = killed.stopped; + } } } const cleared = await clearStaleControlFiles(paths); diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts index bda89df25..db3afe69b 100644 --- a/packages/serve-sim/src/control-daemon.ts +++ b/packages/serve-sim/src/control-daemon.ts @@ -20,12 +20,14 @@ import { isDispatchable, isStaleBuild, parseJsonFrame, + parseRunMessage, unsafeControlDir, withoutNodeRuntimeEnv, type ControlFingerprint, type ControlMessage, type ControlPaths, type ControlStatus, + type RunMessage, } from "./control-protocol"; interface ControlDaemonOptions { @@ -179,6 +181,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise n + c.writableLength, 0), }); const writeJsonFile = (file: string, value: unknown) => { @@ -319,7 +322,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise): Promise { + async function runJob(conn: Socket, msg: RunMessage): Promise { const mismatch = fingerprintMismatch(opts.fingerprint, msg.fingerprint); if (mismatch) { bypass(conn, `fingerprint:${mismatch}`); @@ -328,14 +331,17 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise {}; conn.on("close", () => { clientGone = true; + releaseOutput(); const worker = unhold(conn); if (worker) { // Accepted but never told to go: the worker is still pristine. @@ -391,12 +397,31 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { - if (!clientGone) conn.write(encodeFrame(FRAME_STDOUT, chunk)); - }); - c.stderr?.on("data", (chunk: Buffer) => { - if (!clientGone) conn.write(encodeFrame(FRAME_STDERR, chunk)); - }); + // Backpressure: while the caller isn't keeping up (a slow pipe, a + // stopped pager), stop reading the worker's output rather than queue + // it here, where one big command could exhaust the shared daemon. The + // worker's writes are blocking, so it simply waits, as it would on a + // full pipe in a direct run. + const streams = [c.stdout, c.stderr].filter((x) => x != null); + let paused = false; + const resume = () => { + if (!paused) return; + paused = false; + for (const x of streams) x.resume(); + }; + // A caller that left can't drain: discard the rest so the worker + // (killed on close) can finish closing its pipes. + releaseOutput = resume; + conn.on("drain", resume); + const relay = (type: number) => (chunk: Buffer) => { + if (clientGone) return; + if (!conn.write(encodeFrame(type, chunk)) && !paused) { + paused = true; + for (const x of streams) x.pause(); + } + }; + c.stdout?.on("data", relay(FRAME_STDOUT)); + c.stderr?.on("data", relay(FRAME_STDERR)); // The command never reached the worker (it died just now): the // caller can still run it itself. let undelivered = false; @@ -411,7 +436,7 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise { if (error) undelivered = true; @@ -456,8 +481,15 @@ async function startControlDaemon(opts: ControlDaemonOptions): Promise conn.destroy()); + } else conn.destroy(); } }); }); diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts index e816a53d4..c15ab6cd5 100644 --- a/packages/serve-sim/src/control-protocol.ts +++ b/packages/serve-sim/src/control-protocol.ts @@ -391,6 +391,8 @@ export interface ControlStatus { busy: number; served: number; socket: string; + /** Command output queued for callers that aren't reading it yet. */ + buffered?: number; } export function parseJsonFrame(frame: Frame): ControlMessage | null { @@ -403,6 +405,52 @@ export function parseJsonFrame(frame: Frame): ControlMessage | null { } } +export type RunMessage = Extract; + +const isObject = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); +const isStreamTty = (v: unknown): v is StreamTty => + isObject(v) && typeof v.isTTY === "boolean" && (v.columns === undefined || typeof v.columns === "number"); + +const FINGERPRINT_TYPES: Record = { + protocol: "number", + execPath: "string", + home: "string", + tmpdir: "string", + debug: "string", + binMtimeMs: "number", + mainMtimeMs: "number", +}; +const isFingerprint = (v: unknown): v is ControlFingerprint => + isObject(v) && Object.entries(FINGERPRINT_TYPES).every(([k, type]) => typeof v[k] === type); + +/** + * A well-formed `run` request, rebuilt from only the fields the protocol + * defines; null for anything else. The daemon must not trust its callers' + * JSON: a missing field would otherwise throw deep inside the job. + */ +export function parseRunMessage(msg: ControlMessage): RunMessage | null { + const m = msg as unknown as Record; + if (m.t !== "run") return null; + const { fingerprint, argv, cwd, env, tty, sharedOutput, umask } = m; + if (!isFingerprint(fingerprint)) return null; + if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string")) return null; + if (typeof cwd !== "string") return null; + if (!isObject(env) || !Object.values(env).every((v) => typeof v === "string")) return null; + if (!isObject(tty) || !isStreamTty(tty.stdout) || !isStreamTty(tty.stderr)) return null; + if (sharedOutput !== undefined && typeof sharedOutput !== "boolean") return null; + if (umask !== undefined && (typeof umask !== "number" || !Number.isInteger(umask) || umask < 0 || umask > 0o777)) return null; + return { + t: "run", + fingerprint, + argv: argv as string[], + cwd, + env: env as Record, + tty: { stdout: tty.stdout, stderr: tty.stderr }, + ...(sharedOutput !== undefined ? { sharedOutput } : {}), + ...(umask !== undefined ? { umask } : {}), + }; +} + // ─── Deferred main ─────────────────────────────────────────────────────── // A warm worker imports the full CLI bundle ahead of time; the bundle hands // its entry point back instead of parsing argv right away. diff --git a/packages/serve-sim/src/control-worker.ts b/packages/serve-sim/src/control-worker.ts index 78ea11c4f..a54486fd9 100644 --- a/packages/serve-sim/src/control-worker.ts +++ b/packages/serve-sim/src/control-worker.ts @@ -7,9 +7,7 @@ * Because every command still gets its own process, `process.exit`, exit * codes, signal handlers and module state behave as in a direct run. */ -import { CONTROL_ROLE_ENV, deferCliMain, type ControlMessage, type StreamTty } from "./control-protocol"; - -type RunMessage = Extract; +import { CONTROL_ROLE_ENV, deferCliMain, type ControlMessage, type RunMessage, type StreamTty } from "./control-protocol"; function adoptTty(stream: NodeJS.WriteStream, tty: StreamTty | undefined): void { if (!tty?.isTTY) return; From 11a00d3fa8bb3942e65b8d9e7a7f5a138c99c9b5 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 09:48:16 -0800 Subject: [PATCH 16/17] docs(control): note output backpressure and the control stop deadline --- packages/serve-sim/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/serve-sim/README.md b/packages/serve-sim/README.md index 1a0ee1d63..d25d13183 100644 --- a/packages/serve-sim/README.md +++ b/packages/serve-sim/README.md @@ -364,7 +364,7 @@ Limits: sampling at 4 fps can miss a state shown for less than a tick (record fo Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now an 18 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. - **Which commands**: `tap`, `gesture`, `settle`, `button`, `type`, `paste`, `rotate`, `fold`, `ca-debug`, `memory-warning`, `event-log`, `ax`, `buffer`, and bare `--help`/`--version`. Everything else runs in-process as before: the preview server, `--detach`, `record`, `camera`, `exec`, `doctor`, `permissions`, `ui`, and anything with `--stdin` (stdin is not forwarded). -- **What carries over**: argv, cwd, the full environment, the umask, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. That is better than a direct run: when stdout is a pipe on macOS, a direct run can cut that output short (to 64 KiB) because Node writes pipes asynchronously. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. What does not carry over: resource limits (`ulimit`), the nice level, and any OS sandbox around the caller; those come from whoever started the control process. stdin isn't forwarded either, so `--stdin` and `--file` paths that resolve into `/dev/` (relative or via a symlink) run in-process. +- **What carries over**: argv, cwd, the full environment, the umask, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. That is better than a direct run: when stdout is a pipe on macOS, a direct run can cut that output short (to 64 KiB) because Node writes pipes asynchronously. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. A slow reader (a pager, a stalled pipe) holds the worker back as it would a direct run, instead of the output piling up in the control process. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. What does not carry over: resource limits (`ulimit`), the nice level, and any OS sandbox around the caller; those come from whoever started the control process. stdin isn't forwarded either, so `--stdin` and `--file` paths that resolve into `/dev/` (relative or via a symlink) run in-process. - **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. So do callers inside a known agent sandbox (`CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, or Claude Code's `SANDBOX_RUNTIME`), and they never start one (`serve-sim control start` refuses there too), so a daemon is never born inside a sandbox or used to step outside it. Other sandboxes aren't detected; set `SERVE_SIM_CONTROL=0` under them. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. - **Fallback**: the daemon first reserves a warm worker and replies "accepted"; the command is only handed to the worker after the caller confirms. If the control process is missing, stale, or doesn't reserve a worker within 1 s (`SERVE_SIM_CONTROL_ACCEPT_MS`), nothing has run yet and the command runs in-process. Once the caller has confirmed, it never falls back: a lost connection fails that call (exit 1) instead of running the command twice. If the reserved worker dies before it is handed the command (for example `pkill node`), or the caller takes more than 10 s to confirm, the daemon frees it and the caller runs the command in-process. - **Broken installs**: if workers can't load the CLI, the daemon records why in a `.failed` file next to its socket and exits. Commands keep running in-process, and for 10 minutes (or until the dist is rebuilt) they don't start a new daemon. `serve-sim control start` retries immediately, and only reports success once a worker has loaded; otherwise it prints the worker's error and exits 1. @@ -375,6 +375,8 @@ serve-sim control status [--json] # exit 1 when not running; shows a recent wo serve-sim control start # idempotent; waits until it answers serve-sim control stop # idempotent; also clears stale socket/pid files # (says "stopping" while running commands finish) + # (a daemon that doesn't acknowledge within 2 s gets + # SIGTERM, only if its pid file names that daemon) ``` It listens on a Unix socket at `$TMPDIR/serve-sim-control-/control-.sock` (or under `SERVE_SIM_CONTROL_DIR`), with a pid file next to it. `` is derived from the bin path, the node binary, and `HOME`. Callers send their whole environment over that socket, so both sides check ownership first: the directory must be a real directory (not a symlink) owned by you with no group/other access, and the socket must be a socket owned by you. Otherwise commands run in-process and the daemon refuses to start. The socket is created owner-only (mode 0600) with no window where it is more open. A daemon that finds a dead socket replaces it. When several start at once, the extra ones see their socket was taken over and exit. From 49e54998e7acba1bd1095aa862c84afcb6fe7ed2 Mon Sep 17 00:00:00 2001 From: Evan Bacon Date: Wed, 11 Nov 2026 15:04:12 -0800 Subject: [PATCH 17/17] ci: retrigger checks after camera-connections e2e flake