Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
b16afc0
feat(cli): persistent control process with pre-warmed workers for sho…
EvanBacon Nov 10, 2026
7a71816
feat(cli): report warming workers in serve-sim control status
EvanBacon Nov 10, 2026
90948a1
docs: document the control process, its fallbacks, and before/after l…
EvanBacon Nov 10, 2026
6ca270e
fix(control): hand off only after go, verify socket ownership, harden…
EvanBacon Nov 11, 2026
418d0f4
test(bundle): check dist/serve-sim-cli.js for baked-in build paths
EvanBacon Nov 11, 2026
0c2a0c2
docs(control): document the go handshake, ownership checks and fallbacks
EvanBacon Nov 11, 2026
31df89e
fix(control): free a held worker that dies before go
EvanBacon Nov 11, 2026
51b9fff
fix(control): only report stopped once the daemon has exited
EvanBacon Nov 11, 2026
a1583e2
fix(control): adopt the caller's umask; keep sandboxed callers in-pro…
EvanBacon Nov 11, 2026
e515b9a
fix(control): show a recent worker load failure in control status
EvanBacon Nov 11, 2026
110381f
docs(control): document umask, sandbox bypass, held-worker fallback a…
EvanBacon Nov 11, 2026
268f22c
fix(control): refuse control start inside a sandbox; resolve --file b…
EvanBacon Nov 11, 2026
fd9614b
docs(control): note sandboxed start refusal, direct-run pipe truncati…
EvanBacon Nov 11, 2026
67fd553
fix(control): treat Linux /proc/<pid>/fd paths as fd aliases in the -…
EvanBacon Nov 11, 2026
8bf77f9
fix(control): apply output backpressure, validate run requests, bound…
EvanBacon Nov 11, 2026
11a00d3
docs(control): note output backpressure and the control stop deadline
EvanBacon Nov 11, 2026
49e5499
ci: retrigger checks after camera-connections e2e flake
EvanBacon Nov 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions knip.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
],
"entry": [
"src/index.ts",
"src/bin.ts",
"src/middleware.ts",
"src/state.ts",
"src/client/client.tsx",
Expand Down
48 changes: 48 additions & 0 deletions packages/serve-sim/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,8 @@ serve-sim ax --refs [--all] [--text] Compact snapshot with element refs (@e1…
serve-sim tap @e2 [--settle] [--timeout <ms>]
Tap an element ref; --settle prints the diff
serve-sim settle [--timeout <ms>] 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 <bundle-id> [-d udid] [source-options]
Inject a synthetic camera feed and (re)launch the app
Expand Down Expand Up @@ -357,6 +359,52 @@ 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 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. 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.
- **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; 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)
# (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-<uid>/control-<id>.sock` (or under `SERVE_SIM_CONTROL_DIR`), with a pid file next to it. `<id>` 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.

| 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.
Expand Down
42 changes: 34 additions & 8 deletions packages/serve-sim/build.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions packages/serve-sim/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
},
"files": [
"dist/serve-sim.js",
"dist/serve-sim-cli.js",
"dist/middleware.js",
"dist/middleware.cjs",
"dist/simcam/libSimCameraInjector.dylib",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading