Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
test(tmux): give every vitest run a private TMUX_TMPDIR
enes979b875c55e3
diff --git a/CLAUDE.md b/CLAUDE.mdindex 588ebeaec..28cd704d6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2846,6 +2846,43 @@ also hold an exclusive candidate lock until the rename and cleanup finish. Neverthose back to `<target>.tmp` / `<target>.part` or a read-only "does the destination exist?" check —the overlap tests exercise the resulting race.+## The test suite never touches a live tmux server++This repo is developed from inside nodeterm, so `tmux -L node-terminal` and `-L nodeterm-rmt` are+not fixture names on a contributor's machine — they are the servers holding every terminal they have+open. A test that binds one shares a process with the user's whole canvas, and the failure mode is+not a red test: it is every pane printing `[server exited unexpectedly]` (issue #629).++**Every vitest run gets a private `TMUX_TMPDIR`.** tmux resolves `-L <socket>` to+`$TMUX_TMPDIR/tmux-<uid>/<socket>` and falls back to `/tmp` when the variable is unset, so+re-pointing the variable re-points every socket name at once — including the real ones, including+in a suite nobody thought about. `test/setup/tmux-sandbox.ts` (`globalSetup`) creates the directory,+kills whatever is still bound inside it and removes it; `test/setup/tmux-worker-env.ts`+(`setupFiles`) re-asserts it inside each worker and **refuses to run** if it is missing, because+vitest's env inheritance into workers is an implementation detail and a silent fallback would put+every test back on the live server. `enterSandbox` also strips `TMUX`/`TMUX_PANE` — a suite run from+inside a nodeterm terminal inherits a live client's, and production strips both for the same reason.++Two suites deliberately name a real socket, and both are allowlisted with their reason in+`src/core/tmux-socket-isolation.guard.test.ts`: `agents/pane-owner.test.ts` (the production bytes+hardcode `-L nodeterm-rmt`; re-spelling it would judge different bytes) and+`main/remote/host-destroy-tmux.test.ts` (`PtyManager` binds `TMUX_SOCKET` itself). The latter was+the one file that reached the live server by construction — measured, not inferred — and it now+refuses to start unless the sandbox is in effect.++The guard has three legs on purpose, and the weakest one is the scan: a test can still escape by+handing a real tmux an `env` object it built from scratch with no `TMUX_TMPDIR` in it, which no+regex sees. So the structural leg is the sandbox, the behavioural leg actually **starts a server on+the real socket name and proves the socket file landed inside the sandbox** (asserting the env var+would only prove we set a variable — the resolution rule is a property of tmux), and the scan exists+to make a third allowlist entry a decision somebody signs for. Same shape as the `fs.rename` guard,+for the same reason: nobody reading one file can see this.++**What this does not claim.** #629's server death was not traced to a test — the reporter's evidence+points at tmux's `server_accept()` calling `fatal()` under the suite's process/fd burst on a+memory-starved machine, and two identical runs finished clean. Sharing a server with the user's live+sessions is a hazard whatever kills it; this removes the hazard, not a proven cause.+## Conventions- **Two docs, two audiences — keep both.** This file holds the deep invariants with theirdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 64971acfc..2028901f8 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -310,6 +310,16 @@ Where a behaviour can only be verified on hardware we do not have in CI (a Mac,GPU), say so explicitly rather than implying coverage. Several docs carry numbered devicechecklists for exactly this.+**A test never touches a live tmux server.** You will most likely run `npm test` from inside a+nodeterm terminal, where `-L node-terminal` and `-L nodeterm-rmt` are the servers holding every+node you have open — one stray `kill-server` there ends your whole canvas, not your test. Every run+therefore gets a private `TMUX_TMPDIR` (`test/setup/tmux-sandbox.ts`), which re-points every socket+name at once. Write real-tmux suites the normal way — pick your own socket name, and use+`makeTmuxTmpdir` if you also want your own directory — and do not build an `env` object for a real+tmux without carrying `TMUX_TMPDIR` into it, which is the one way left to escape the sandbox.+`src/core/tmux-socket-isolation.guard.test.ts` holds the short allowlist of suites that name a+production socket on purpose; adding a third is a review conversation, not a checkbox.+## Pull requests- Branch from `main`. CI runs `quality`, `CodeQL` and `Dependency review`; all three are required.diff --git a/src/core/tmux-socket-isolation.guard.test.ts b/src/core/tmux-socket-isolation.guard.test.tsnew file mode 100644index 000000000..a8ab0e08c--- /dev/null+++ b/src/core/tmux-socket-isolation.guard.test.ts@@ -0,0 +1,168 @@+// Issue #629 — the invariant: **a test never touches the machine's live nodeterm tmux server.**+//+// This repo is developed from inside nodeterm, so `tmux -L node-terminal` and `-L nodeterm-rmt` are+// not names in a fixture — on a contributor's machine they are the servers holding every terminal+// they have open. A test that binds one shares a process with the user's entire canvas, and the+// failure mode is not a red test: it is every pane printing `[server exited unexpectedly]`.+//+// It is enforced three ways, deliberately, because each covers what the others cannot:+//+// 1. STRUCTURAL — `test/setup/tmux-sandbox.ts` gives the run a private `TMUX_TMPDIR`, which+// re-points every socket name, the real ones included. This is the only leg that covers a test+// nobody thought about.+// 2. BEHAVIOURAL — the third test below actually starts a server on the real socket NAME and+// proves the socket file landed inside the sandbox. Asserting the environment variable would+// only prove we set a variable; the resolution rule is a property of tmux.+// 3. BY REVIEW — the scan at the bottom lists the files that hand a real socket name to a real+// tmux binary. It cannot stop a new one being written; it makes writing one a decision+// somebody signs for, the way `fs-atomic.guard.test.ts` does for a bare rename.+//+// The scan is the weakest of the three ON PURPOSE. A test can still escape the sandbox by handing a+// real tmux an `env` object it built from scratch (with no `TMUX_TMPDIR` in it), and no regex sees+// that reliably; the allowlist is what keeps such a file rare and reviewed.+import { describe, expect, it } from 'vitest'+import { execFileSync } from 'child_process'+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'+import { join, relative } from 'path'+import { TMUX_SOCKET } from './tmux-naming'+import { RMT_TMUX_SOCKET } from './remote-ssh/control-master'+import { SANDBOX_ENV, tmuxSocketPath } from './tmux-test-socket'++const REPO_ROOT = join(__dirname, '..', '..')+const TEST_ROOTS = [join(REPO_ROOT, 'src'), join(REPO_ROOT, 'test')]+const UID = process.getuid?.() ?? 0+const HAS_TMUX = (() => {+ try {+ execFileSync('tmux', ['-V'], { stdio: 'ignore' })+ return true+ } catch {+ return false+ }+})()++describe('the run cannot reach a live nodeterm tmux server', () => {+ it('runs inside a private TMUX_TMPDIR', () => {+ const sandbox = process.env[SANDBOX_ENV]+ expect(sandbox, 'globalSetup did not create the tmux sandbox').toBeTruthy()+ expect(process.env.TMUX_TMPDIR).toBe(sandbox)+ expect(existsSync(sandbox!)).toBe(true)+ // `/tmp` is what an unset `TMUX_TMPDIR` resolves to, and it is where the live servers are.+ expect(tmuxSocketPath(sandbox!, UID, TMUX_SOCKET)).not.toBe(+ tmuxSocketPath('/tmp', UID, TMUX_SOCKET)+ )+ })++ it('inherits no ambient tmux client', () => {+ // Both are set for every process inside a nodeterm terminal — i.e. for the suite as it is+ // normally run in this repo.+ expect(process.env.TMUX).toBeUndefined()+ expect(process.env.TMUX_PANE).toBeUndefined()+ })++ it.skipIf(!HAS_TMUX || process.platform === 'win32')(+ 'binds the REAL socket name inside the sandbox — measured, not inferred from the env',+ () => {+ const sandbox = process.env[SANDBOX_ENV]!+ const tmux = (args: string[]): void => {+ execFileSync('tmux', ['-L', TMUX_SOCKET, ...args], { stdio: 'ignore' })+ }+ try {+ tmux(['new-session', '-d', '-s', 'nt-isolation-guard', 'sleep', '30'])+ expect(existsSync(tmuxSocketPath(sandbox, UID, TMUX_SOCKET))).toBe(true)+ } finally {+ try {+ tmux(['kill-server'])+ } catch {+ /* never started */+ }+ }+ }+ )+})++/**+ * Files allowed to name a real nodeterm socket to a real tmux, each with the reason.+ *+ * Both are here because the NAME is part of what they measure, not because nobody got round to+ * changing them. Each must also carry `TMUX_TMPDIR` in its own text — the sandbox is the floor, and+ * a file that deliberately names a live socket owes an explicit statement of where it binds.+ */+const REAL_SOCKET_ALLOWED = new Map<string, string>([+ [+ 'src/core/agents/pane-owner.test.ts',+ 'the production bytes hardcode `-L nodeterm-rmt`; re-spelling it would judge different bytes'+ ],+ [+ 'src/main/remote/host-destroy-tmux.test.ts',+ 'PtyManager binds TMUX_SOCKET itself, so the verb can only be measured on that name'+ ]+])++/**+ * An exec of a real tmux whose argv begins `-L <a real nodeterm socket>`.+ *+ * Deliberately narrow: `['-L', 'node-terminal', …]` appears all over the suite as an EXPECTATION+ * against a faked `execFile`, and a scan that flagged those would be switched off within a week.+ * What it matches is the program-plus-argv adjacency, which only a real spawn has.+ */+const REAL_SOCKET_EXEC =+ /(?:execFile|execFileSync|spawn|spawnSync|run|runAsync)\s*\(\s*[^,()]*,\s*\[\s*'-L',\s*(?:TMUX_SOCKET|RMT_TMUX_SOCKET|'node-terminal'|'nodeterm-rmt')/++function testFiles(dir: string, out: string[] = []): string[] {+ for (const entry of readdirSync(dir)) {+ const p = join(dir, entry)+ if (statSync(p).isDirectory()) {+ if (entry !== 'node_modules') testFiles(p, out)+ } else if (/\.test\.tsx?$/.test(entry)) {+ out.push(p)+ }+ }+ return out+}++describe('no unreviewed test hands a real socket name to a real tmux', () => {+ const files = TEST_ROOTS.filter((r) => existsSync(r)).flatMap((r) => testFiles(r))++ it('finds the test tree (a zero-file scan would pass silently)', () => {+ expect(files.length).toBeGreaterThan(100)+ })++ it('matches the construction it is meant to catch, and not the expectations beside it', () => {+ // The lesson from fs-atomic.guard.test.ts: a scan nobody proved can match anything reads+ // exactly like a scan with nothing to find.+ expect(REAL_SOCKET_EXEC.test("await run(TMUX!, ['-L', TMUX_SOCKET, 'has-session'])")).toBe(true)+ expect(REAL_SOCKET_EXEC.test("execFileSync(bin, ['-L', 'nodeterm-rmt', 'ls'])")).toBe(true)+ expect(+ REAL_SOCKET_EXEC.test("expect(kills).toEqual([['-L', 'node-terminal', 'kill-session']])")+ ).toBe(false)+ })++ it('flags every offender that is not allowlisted', () => {+ // This file is skipped rather than allowlisted: it matches only because it spells the pattern+ // out in the positive control above, and an allowlist entry would read as permission to run a+ // real tmux from here.+ const self = relative(REPO_ROOT, __filename).replace(/\\/g, '/')+ const offenders = files+ .filter((f) => REAL_SOCKET_EXEC.test(readFileSync(f, 'utf8')))+ .map((f) => relative(REPO_ROOT, f).replace(/\\/g, '/'))+ .filter((rel) => rel !== self && !REAL_SOCKET_ALLOWED.has(rel))+ expect(offenders).toEqual([])+ })++ it('every allowlisted file still exists and says where it binds', () => {+ for (const [rel] of REAL_SOCKET_ALLOWED) {+ const p = join(REPO_ROOT, rel)+ expect(existsSync(p), `${rel} is allowlisted but gone — drop the entry`).toBe(true)+ expect(readFileSync(p, 'utf8'), `${rel} must say which TMUX_TMPDIR it binds in`).toContain(+ 'TMUX_TMPDIR'+ )+ }+ })++ it('the socket names the scan spells are still the production ones', () => {+ // The regex carries the two names as literals so it can read a test that hardcodes them. If a+ // constant is ever renamed, this is what says the scan went blind.+ expect(TMUX_SOCKET).toBe('node-terminal')+ expect(RMT_TMUX_SOCKET).toBe('nodeterm-rmt')+ })+})diff --git a/src/core/tmux-test-socket.ts b/src/core/tmux-test-socket.tsindex 67305eaab..1376c2286 100644--- a/src/core/tmux-test-socket.ts+++ b/src/core/tmux-test-socket.ts@@ -89,3 +89,36 @@ function realpathOrSelf(p: string): string {return p}}++// ── The run-wide sandbox (issue #629) ───────────────────────────────────────────────────────────+//+// The two helpers above serve a suite that ASKS for a private socket. Everything below serves the+// suites that do not: `test/setup/tmux-sandbox.ts` gives the whole vitest run one private+// `TMUX_TMPDIR`, so a test naming `node-terminal` binds inside the sandbox instead of on the server+// carrying the developer's live nodeterm canvas. They live here rather than beside the setup file+// because `src/core` is what the guard test can import — `test/` is outside every tsconfig project.++/** How the sandbox path reaches the workers, separately from `TMUX_TMPDIR` itself: a worker must be+ * able to tell "this run set it up" from "the developer already had TMUX_TMPDIR exported". */+export const SANDBOX_ENV = 'NODETERM_TEST_TMUX_TMPDIR'++/**+ * Longest socket NAME the sandbox reserves room for.+ *+ * The sandbox is a PREFIX of every socket bound inside it, so it owes the same `SUN_PATH_MAX`+ * arithmetic as a per-suite directory. The real names are short (`node-terminal` is 13) but a suite+ * that binds `nt-accttest-<pid>` inside the sandbox needs the slack, and a budget discovered at+ * bind time reads like a broken test rather than a path-length limit.+ */+export const SANDBOX_SOCKET_BUDGET = 40++/** Point this process — and therefore every child and worker it spawns — at the sandbox. */+export function enterSandbox(sandbox: string): void {+ process.env[SANDBOX_ENV] = sandbox+ process.env.TMUX_TMPDIR = sandbox+ // A suite run from inside a nodeterm terminal inherits a live client's `TMUX`/`TMUX_PANE`.+ // Production strips both from every child it spawns for the same reason (nesting refusal); a test+ // that reads them would be measuring the developer's canvas.+ delete process.env.TMUX+ delete process.env.TMUX_PANE+}diff --git a/src/main/remote/host-destroy-tmux.test.ts b/src/main/remote/host-destroy-tmux.test.tsindex 0cab7849a..1a38f4d0c 100644--- a/src/main/remote/host-destroy-tmux.test.ts+++ b/src/main/remote/host-destroy-tmux.test.ts@@ -7,12 +7,20 @@// nothing to show over a session that kept running. `handleDestroy` therefore verifies the// OUTCOME (`sessionExists` after the destroy must say gone) before answering.//-// This suite runs the verb against tmux for real, on the real `node-terminal` socket with a-// unique throwaway session name — the same discipline as the canvas-control shim and-// remote-usage suites (generated side-effects are proven on the real interpreter, not a fake).+// This suite runs the verb against tmux for real — the same discipline as the canvas-control shim+// and remote-usage suites (generated side-effects are proven on the real interpreter, not a fake).// node-pty stays mocked (suite convention: it is built for Electron's ABI); the pty spawn is// irrelevant here — the tmux side-calls and the kill are real subprocesses.-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'+//+// WHERE IT BINDS (issue #629). It must use the socket NAME `PtyManager` binds, `TMUX_SOCKET` — that+// is not a choice, the manager hardcodes it and this suite exists to watch the manager's own kill+// land. Until the run-wide sandbox existed, that name resolved to `/tmp/tmux-<uid>/node-terminal`:+// the server holding every terminal on the developer's machine, since this repo is developed from+// inside nodeterm. So the suite created sessions on the user's live server and drove a real+// `PtyManager` at it. `test/setup/tmux-sandbox.ts` now re-points `TMUX_TMPDIR` for the whole run,+// and `beforeAll` REFUSES to run at all if that sandbox is not in effect — a suite that quietly+// falls back to the shared server is exactly the failure this check exists to make loud.+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest'import { execFile } from 'child_process'import { promisify } from 'util'import { existsSync, promises as fs } from 'fs'@@ -22,6 +30,7 @@ import { initPlatform, resetPlatformForTests } from '../../core/platform'import { fakePlatform } from '../../core/platform-fake'import { DEFAULT_SETTINGS } from '../../shared/types'import { TMUX_SOCKET, sessionName } from '../../core/tmux-naming'+import { SANDBOX_ENV, tmuxSocketPath } from '../../core/tmux-test-socket'import { createHostHandlers, type HostFsOps, type HostRelaySocket } from './host-service'const run = promisify(execFile)@@ -65,10 +74,23 @@ describe.skipIf(!TMUX || process.platform === 'win32')(}}+ // The socket name is the live one; only `TMUX_TMPDIR` keeps it off the live SERVER. Prove that+ // before anything is created, and name the sandbox in the failure — a suite that silently used+ // the developer's own tmux server is what issue #629 is about.+ beforeAll(() => {+ const sandbox = process.env[SANDBOX_ENV]+ expect(sandbox, 'tmux sandbox not in effect — see test/setup/tmux-sandbox.ts').toBeTruthy()+ expect(process.env.TMUX_TMPDIR).toBe(sandbox)+ expect(tmuxSocketPath(sandbox!, process.getuid?.() ?? 0, TMUX_SOCKET)).not.toBe(+ tmuxSocketPath('/tmp', process.getuid?.() ?? 0, TMUX_SOCKET)+ )+ })+beforeEach(async () => {userData = await fs.mkdtemp(path.join(os.tmpdir(), 'nt-destroy-'))initPlatform(fakePlatform({ userDataDir: userData }))- // Unique per run: this socket is the REAL one, shared with whatever else the machine runs.+ // Unique per run: the socket NAME is the production one, so a collision inside the sandbox+ // between two concurrent runs would be a real one.nodeId = `e581-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`await run(TMUX!, ['-L', TMUX_SOCKET, 'new-session', '-d', '-s', sessionName(nodeId), 'sleep', '600'])expect(await hasSession()).toBe(true)diff --git a/test/setup/tmux-sandbox.ts b/test/setup/tmux-sandbox.tsnew file mode 100644index 000000000..dd1a8eaa1--- /dev/null+++ b/test/setup/tmux-sandbox.ts@@ -0,0 +1,72 @@+// TEST-ONLY — issue #629: the whole vitest run gets a private `TMUX_TMPDIR`, so no test can reach+// the tmux servers this machine is actually running nodeterm on.+//+// tmux resolves `-L <socket>` to `$TMUX_TMPDIR/tmux-<uid>/<socket>`, falling back to `/tmp` when+// the variable is unset. A test that names `node-terminal` or `nodeterm-rmt` therefore lands on the+// SHARED server carrying every live node on the machine — the developer's own canvas when the suite+// is run from inside a nodeterm terminal, which is how this repo is normally developed.+// `src/main/remote/host-destroy-tmux.test.ts` did exactly that by design (measured: it binds+// `node-terminal`, creates sessions on it and drives a real `PtyManager` against it), and+// `src/core/agents/pane-owner.test.ts` runs a real `tmux -L nodeterm-rmt` because the bytes it+// judges hardcode that name.+//+// Neither was proven to be the killer in #629 — the reporter's evidence points at the tmux server+// hitting a `fatal()` under the suite's process/fd burst, not at a `kill-server` from a test. But+// "the suite shares a server with the user's live sessions" is a hazard whatever kills it, and it+// is one this file removes by construction rather than by everybody remembering the rule.+//+// The sandbox is per RUN, not per file: `setup` creates it in the main process (so the workers+// inherit the variable), `teardown` kills whatever is still bound inside it and removes it. Suites+// that make their OWN private `TMUX_TMPDIR` are unaffected — this is the floor, not an override.+import { execFileSync } from 'child_process'+import fs from 'fs'+import path from 'path'+import {+ SANDBOX_SOCKET_BUDGET,+ enterSandbox,+ makeTmuxTmpdir,+ tmuxSocketPath+} from '../../src/core/tmux-test-socket'++let dir: string | null = null++export async function setup(): Promise<void> {+ dir = makeTmuxTmpdir('ntvitest-', 'x'.repeat(SANDBOX_SOCKET_BUDGET))+ enterSandbox(dir)+}++export async function teardown(): Promise<void> {+ if (!dir) return+ killSandboxServers(dir)+ fs.rmSync(dir, { recursive: true, force: true })+ dir = null+}++/**+ * Kill every tmux server still bound inside the sandbox.+ *+ * `rm -rf` alone would unlink the socket and leave the server process running forever — which is+ * the shape of #629's leftovers (`nt-pr3-*` servers whose `afterAll` never ran, each still holding+ * its fake agents). Everything under this directory was started by this run, so there is nothing+ * else here to hit.+ */+function killSandboxServers(sandbox: string): void {+ const uid = process.getuid?.() ?? 0+ const socketDir = path.dirname(tmuxSocketPath(sandbox, uid, 'x'))+ let sockets: string[] = []+ try {+ sockets = fs.readdirSync(socketDir)+ } catch {+ return // nothing ever bound here+ }+ for (const socket of sockets) {+ try {+ execFileSync('tmux', ['-L', socket, 'kill-server'], {+ env: { ...process.env, TMUX_TMPDIR: sandbox },+ stdio: 'ignore'+ })+ } catch {+ /* no server on that socket, or no tmux at all — both fine */+ }+ }+}diff --git a/test/setup/tmux-worker-env.ts b/test/setup/tmux-worker-env.tsnew file mode 100644index 000000000..1ffb70398--- /dev/null+++ b/test/setup/tmux-worker-env.ts@@ -0,0 +1,22 @@+// TEST-ONLY — issue #629. The worker half of the tmux sandbox; see `tmux-sandbox.ts` for why.+//+// `globalSetup` runs in vitest's main process and the workers inherit its environment, so this file+// is usually re-stating what is already true. It exists because that inheritance is vitest's+// implementation detail, not its contract: a pool that snapshotted the environment before+// `globalSetup` ran would silently hand every worker the DEFAULT tmux directory — i.e. the+// machine's live `node-terminal` server — and nothing in a green suite would say so.+//+// It refuses rather than inventing a directory of its own. A per-worker fallback would be a sandbox+// nobody ever removes, and "the isolation is not wired" is exactly the thing that must be loud.+import fs from 'fs'+import { SANDBOX_ENV, enterSandbox } from '../../src/core/tmux-test-socket'++const sandbox = process.env[SANDBOX_ENV]+if (!sandbox || !fs.existsSync(sandbox)) {+ throw new Error(+ `tmux sandbox missing (${SANDBOX_ENV}=${sandbox ?? 'unset'}). vitest.config.ts must keep ` ++ 'test/setup/tmux-sandbox.ts in `globalSetup` — without it a test naming `node-terminal` ' ++ "binds this machine's live nodeterm tmux server. See issue #629."+ )+}+enterSandbox(sandbox)diff --git a/vitest.config.ts b/vitest.config.tsindex 022a37f02..47436de3e 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -23,6 +23,11 @@ export default defineConfig({'test/ssh-docker/**/*.test.ts'],environment: 'node',+ // Issue #629: every run gets a private `TMUX_TMPDIR`, so no test can reach the tmux servers+ // this machine runs nodeterm on. `globalSetup` creates and removes it, the setup file re-asserts+ // it inside each worker (and refuses if it is missing). See test/setup/tmux-sandbox.ts.+ globalSetup: ['test/setup/tmux-sandbox.ts'],+ setupFiles: ['test/setup/tmux-worker-env.ts'],// Issue #160: with the default (one worker per core), a 10-core Mac runs ~10 fs-heavy suites// at once and transient fd exhaustion (EMFILE) turns into silent test flakiness — probes like// `fs.existsSync` swallow the error and answer false, so whole files fail in ways that never