Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix: raise the pane's open-files limit before an engine starts

Kelvin1e89ceea526d
diff --git a/cli/src/lib/engineLaunch.spec.ts b/cli/src/lib/engineLaunch.spec.ts
index 2d49fd6eb..9020e9f1c 100644
--- a/cli/src/lib/engineLaunch.spec.ts
+++ b/cli/src/lib/engineLaunch.spec.ts
@@ -12,17 +12,18 @@ import {
import { ENGINES } from '../engines/types.js'
import { engineBin } from './engineBin.js'
import type { EngineInstallRecipe } from './engineInstall.js'
+import { MIN_OPEN_FILES, RAISE_OPEN_FILES_SH } from './openFiles.js'
describe('buildEngineLaunchArgv', () => {
it('wraps zsh in its interactive login form and execs the resolved binary', () => {
expect(buildEngineLaunchArgv('claude', {}, '/bin/zsh')).toEqual([
- '/bin/zsh', '-lic', 'exec "$@"', 'harness-engine', engineBin('claude'),
+ '/bin/zsh', '-lic', `${RAISE_OPEN_FILES_SH}exec "$@"`, 'harness-engine', engineBin('claude'),
])
})
it('uses Ubuntu bash interactive startup files without making it a login shell', () => {
expect(buildEngineLaunchArgv('claude', {}, '/bin/bash')).toEqual([
- '/bin/bash', '-ic', 'exec "$@"', 'harness-engine', engineBin('claude'),
+ '/bin/bash', '-ic', `${RAISE_OPEN_FILES_SH}exec "$@"`, 'harness-engine', engineBin('claude'),
])
})
@@ -30,11 +31,28 @@ describe('buildEngineLaunchArgv', () => {
const argv = buildEngineLaunchArgv('claude', { cwd: '/work/project' }, '/bin/zsh')
expect(argv).toEqual([
'/bin/zsh', '-lic',
- 'if ! cd -- "$1"; then printf \'%s\\n\' \'harness: the selected working directory is unavailable.\' >&2; exit 1; fi\nshift\nexec "$@"',
+ `${RAISE_OPEN_FILES_SH}if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; exit 1; fi\nshift\nexec "$@"`,
'harness-engine', '/work/project', engineBin('claude'),
])
})
+ it('hands the engine a soft open-files limit fit for it, however low the pane started', async () => {
+ // A tmux server started by the desktop app passes launchd's 256 to every pane; Claude Code will
+ // not start under that. The pane's own shell lifts it before exec, so the server never has to.
+ const [shell, flag, paneScript] = buildEngineLaunchArgv('claude', {}, '/bin/sh')
+ const { execFile } = await import('node:child_process')
+ const seenByEngine = await new Promise<string>((resolve, reject) => {
+ execFile(
+ '/bin/sh',
+ ['-c', 'ulimit -S -n 256 || exit 99; exec "$@"', 'pane', shell, flag, paneScript, 'harness-engine', '/bin/sh', '-c', 'ulimit -S -n'],
+ { timeout: 10_000 },
+ (error, stdout, stderr) => (error ? reject(new Error(`${error.message}\n${stderr}`)) : resolve(stdout.trim())),
+ )
+ })
+ expect(seenByEngine).not.toBe('256')
+ expect(seenByEngine === 'unlimited' || Number(seenByEngine) >= Math.min(MIN_OPEN_FILES, 4096)).toBe(true)
+ })
+
it('falls back to direct execution when no absolute shell is available', () => {
expect(buildEngineLaunchArgv('claude', {}, '')).toEqual([engineBin('claude')])
expect(buildEngineLaunchArgv('claude', {}, 'zsh')).toEqual([engineBin('claude')])
@@ -165,7 +183,7 @@ describe('buildEngineLaunchArgv with installFirst', () => {
buildEngineLaunchArgv('opencode', { installFirst: install }, '/bin/zsh')[2]
it('leaves the plain launch alone when nothing has to be installed', () => {
- expect(buildEngineLaunchArgv('opencode', {}, '/bin/zsh')[2]).toBe('exec "$@"')
+ expect(buildEngineLaunchArgv('opencode', {}, '/bin/zsh')[2]).toBe(`${RAISE_OPEN_FILES_SH}exec "$@"`)
})
it('keeps the engine argv positional, so the shell never re-parses a path or a flag', () => {
diff --git a/cli/src/lib/engineLaunch.ts b/cli/src/lib/engineLaunch.ts
index ae61b62a3..d74e074e2 100644
--- a/cli/src/lib/engineLaunch.ts
+++ b/cli/src/lib/engineLaunch.ts
@@ -6,6 +6,7 @@ import { binaryOnPath } from './binaryOnPath.js'
import { engineBin } from './engineBin.js'
import type { EngineInstallRecipe } from './engineInstall.js'
import { managedNodePath } from './nodeRuntime.js'
+import { RAISE_OPEN_FILES_SH } from './openFiles.js'
/**
* Best-effort "skip permission prompts" flag per engine, confirmed against each vendor's own docs.
@@ -200,7 +201,11 @@ export function buildEngineLaunchArgv(
: opts.installFirst
? installThenExecScript(opts.installFirst)
: 'exec "$@"'
- return [interactive.path, ...interactive.args, prelude + cwdPrelude + body, 'harness-engine', ...(opts.cwd ? [opts.cwd] : []), ...command]
+ // The open-files raise goes ahead of everything, the installer included: a pane inherits the tmux
+ // SERVER's soft limit, which is launchd's 256 whenever the desktop app started the daemon that
+ // started the server, and an engine (Claude Code refuses outright) or an npm install under 256 is
+ // the failure the person then reads in the pane. See openFiles.ts.
+ return [interactive.path, ...interactive.args, RAISE_OPEN_FILES_SH + prelude + cwdPrelude + body, 'harness-engine', ...(opts.cwd ? [opts.cwd] : []), ...command]
}
/**
diff --git a/cli/src/lib/openFiles.spec.ts b/cli/src/lib/openFiles.spec.ts
new file mode 100644
index 000000000..dd5151922
--- /dev/null
+++ b/cli/src/lib/openFiles.spec.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { MIN_OPEN_FILES, RAISE_OPEN_FILES_SH } from './openFiles.js'
+
+const LOW_LIMIT = 256 // what launchd hands every process on macOS
+
+/** Run `command args` under /bin/sh with the soft open-files limit first forced to `soft`. */
+function runUnderSoftLimit(soft: number, command: string, args: string[]): Promise<string> {
+ return new Promise((resolve, reject) => {
+ execFile(
+ '/bin/sh',
+ ['-c', `ulimit -S -n ${soft} || exit 99; exec "$@"`, 'limit-wrapper', command, ...args],
+ { timeout: 10_000 },
+ (error, stdout, stderr) => (error ? reject(new Error(`${error.message}\n${stderr}`)) : resolve(stdout.trim())),
+ )
+ })
+}
+
+/** The hard limit of this test process's shell, or Infinity for `unlimited`. */
+async function hardLimit(): Promise<number> {
+ const raw = await runUnderSoftLimit(LOW_LIMIT, '/bin/sh', ['-c', 'ulimit -H -n'])
+ return raw === 'unlimited' ? Infinity : Number(raw)
+}
+
+describe('RAISE_OPEN_FILES_SH', () => {
+ it('raises a low soft limit to MIN_OPEN_FILES, or to the hard limit when that is lower', async () => {
+ const hard = await hardLimit()
+ const after = Number(await runUnderSoftLimit(LOW_LIMIT, '/bin/sh', ['-c', `${RAISE_OPEN_FILES_SH}ulimit -S -n`]))
+ expect(after).toBe(Math.min(MIN_OPEN_FILES, hard))
+ })
+
+ it('never lowers a soft limit that is already higher', async () => {
+ const hard = await hardLimit()
+ const generous = Math.min(MIN_OPEN_FILES * 2, hard)
+ if (generous <= MIN_OPEN_FILES) return // hard limit too low on this box to exercise the branch
+ const after = Number(await runUnderSoftLimit(generous, '/bin/sh', ['-c', `${RAISE_OPEN_FILES_SH}ulimit -S -n`]))
+ expect(after).toBe(generous)
+ })
+
+ it('leaves the hard limit alone', async () => {
+ const before = await runUnderSoftLimit(LOW_LIMIT, '/bin/sh', ['-c', 'ulimit -H -n'])
+ const after = await runUnderSoftLimit(LOW_LIMIT, '/bin/sh', ['-c', `${RAISE_OPEN_FILES_SH}ulimit -H -n`])
+ expect(after).toBe(before)
+ })
+
+ // The pane script runs under the user's own shell, so the prelude is exercised under the two it
+ // meets in practice as well as /bin/sh. A box without one of them skips rather than fails.
+ for (const shell of ['/bin/zsh', '/bin/bash']) {
+ it.skipIf(!existsSync(shell))(`runs under ${shell}`, async () => {
+ const hard = await hardLimit()
+ const after = Number(await runUnderSoftLimit(LOW_LIMIT, shell, ['-c', `${RAISE_OPEN_FILES_SH}ulimit -S -n`]))
+ expect(after).toBe(Math.min(MIN_OPEN_FILES, hard))
+ })
+ }
+
+ it('does not end a script running under set -e, even when the raise itself fails', async () => {
+ // ulimit shadowed to always fail; the engine (`echo`) must still run.
+ const out = await runUnderSoftLimit(LOW_LIMIT, '/bin/bash', ['-c', `set -e; ulimit() { return 1; }; ${RAISE_OPEN_FILES_SH}echo ENGINE_RAN`])
+ expect(out).toBe('ENGINE_RAN')
+ })
+})
diff --git a/cli/src/lib/openFiles.ts b/cli/src/lib/openFiles.ts
new file mode 100644
index 000000000..1468f1862
--- /dev/null
+++ b/cli/src/lib/openFiles.ts
@@ -0,0 +1,40 @@
+/**
+ * Soft open-files limit a process Harness starts should have at minimum.
+ *
+ * macOS starts everything launchd launches — the desktop app, and through it the daemon, the tmux
+ * server and every pane that server opens — at a soft limit of 256 descriptors (`launchctl limit
+ * maxfiles` → `256 unlimited`). Claude Code refuses to start under that: "An unknown error occurred,
+ * possibly due to low max file descriptors · Current limit: 256". An engine with a dozen MCP servers
+ * (three pipes each) and a transcript watcher needs hundreds before its first turn. 65,536 is well
+ * under macOS's per-process ceiling (`kern.maxfilesperproc`, 122,880 by default) and Linux's usual
+ * hard limit of 1,048,576.
+ *
+ * The daemon needs none of this: Node raises its own soft limit to the hard one at startup (measured:
+ * a `sh -c 'ulimit -S -n 256; exec node …'` reports 1,048,575 from inside). A tmux server does not,
+ * and neither does an engine shipped as a native binary — which is why a pane inherits the 256 and
+ * the engine, not the daemon, is what fails.
+ */
+export const MIN_OPEN_FILES = 65_536
+
+/**
+ * POSIX shell prelude that raises the soft open-files limit to MIN_OPEN_FILES when it is lower.
+ *
+ * A process may lift its own soft limit anywhere up to the hard one without privileges, and the hard
+ * limit is `unlimited` on macOS — so the raise costs nothing and needs no `sudo launchctl`. It never
+ * lowers: a shell that already has more keeps it. Where the hard limit is below the target (some
+ * Linux distributions cap it at 4,096), the soft limit becomes the hard one instead. `-S` is spelled
+ * out because zsh's bare `ulimit -n N` sets the HARD limit as well, and a hard limit of 65,536 is a
+ * ceiling the engine could no longer raise past. Any failure is silent, so the process starts with
+ * what it has — as it always did.
+ *
+ * Runs under /bin/sh, bash and zsh alike (`[ ]`, `$( )`, `2>/dev/null`); the pane script is already
+ * POSIX-only for the same reason.
+ */
+export const RAISE_OPEN_FILES_SH =
+ // Every statement ends in a branch that succeeds: the pane's shell has already run the user's rc
+ // files, and one that turned on `set -e` would otherwise end the script here — before the engine —
+ // the day a query or a raise fails. (A failed query reads as `unlimited`, which is "leave it".)
+ `harness_nofile=$(ulimit -S -n 2>/dev/null) || harness_nofile=unlimited; ` +
+ `if [ "$harness_nofile" != unlimited ] && [ "$harness_nofile" -lt ${MIN_OPEN_FILES} ] 2>/dev/null; ` +
+ `then ulimit -S -n ${MIN_OPEN_FILES} 2>/dev/null || ulimit -S -n "$(ulimit -H -n)" 2>/dev/null || true; fi; ` +
+ `unset harness_nofile\n`