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: say why a workspace the pane can enter but not read stops the agent

Kelvin7aee30ef80bb
diff --git a/cli/src/lib/engineLaunch.spec.ts b/cli/src/lib/engineLaunch.spec.ts
index 9020e9f1c..edc4053d4 100644
--- a/cli/src/lib/engineLaunch.spec.ts
+++ b/cli/src/lib/engineLaunch.spec.ts
@@ -8,6 +8,7 @@ import {
buildEngineCommandArgv,
buildEngineLaunchArgv,
commandAvailableInInteractiveShell,
+ unreadableCwdGuard,
} from './engineLaunch.js'
import { ENGINES } from '../engines/types.js'
import { engineBin } from './engineBin.js'
@@ -31,7 +32,7 @@ describe('buildEngineLaunchArgv', () => {
const argv = buildEngineLaunchArgv('claude', { cwd: '/work/project' }, '/bin/zsh')
expect(argv).toEqual([
'/bin/zsh', '-lic',
- `${RAISE_OPEN_FILES_SH}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\n${unreadableCwdGuard(process.platform)}shift\nexec "$@"`,
'harness-engine', '/work/project', engineBin('claude'),
])
})
@@ -53,6 +54,98 @@ describe('buildEngineLaunchArgv', () => {
expect(seenByEngine === 'unlimited' || Number(seenByEngine) >= Math.min(MIN_OPEN_FILES, 4096)).toBe(true)
})
+ describe('an unreadable workspace', () => {
+ // Under /bin/sh, with the engine replaced by printf so its run leaves a marker.
+ async function launchInto(dir: string): Promise<{ code: number; stdout: string; stderr: string }> {
+ const [, , paneScript] = buildEngineLaunchArgv('claude', { cwd: dir }, '/bin/sh')
+ const { execFile } = await import('node:child_process')
+ return await new Promise((resolve) => {
+ execFile(
+ '/bin/sh',
+ ['-c', paneScript, 'harness-engine', dir, '/usr/bin/printf', 'ENGINE_RAN\n'],
+ { timeout: 10_000 },
+ (error, stdout, stderr) => {
+ const code = error && typeof (error as { code?: unknown }).code === 'number'
+ ? (error as unknown as { code: number }).code
+ : 0
+ resolve({ code, stdout, stderr })
+ },
+ )
+ })
+ }
+
+ // root reads everything, so the guard has nothing to catch there.
+ const notRoot = process.getuid?.() !== 0
+
+ it.skipIf(!notRoot)('says why and stops instead of letting the engine fail on its first read', async () => {
+ // Enterable but not readable: what macOS privacy settings (TCC) produce for a folder the
+ // responsible app was not granted — `cd` works, the first readdir does not.
+ const dir = mkdtempSync(join(tmpdir(), 'harness-unreadable-'))
+ try {
+ chmodSync(dir, 0o300)
+ const result = await launchInto(dir)
+ expect(result.code).toBe(1)
+ expect(result.stdout).not.toContain('ENGINE_RAN')
+ expect(result.stderr).toContain(`harness: cannot read ${dir}`)
+ } finally {
+ chmodSync(dir, 0o700)
+ rmSync(dir, { recursive: true, force: true })
+ }
+ })
+
+ it('launches the engine when the workspace is readable', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'harness-readable-'))
+ try {
+ const result = await launchInto(dir)
+ expect(result.code).toBe(0)
+ expect(result.stdout).toContain('ENGINE_RAN')
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+ })
+
+ // Both hints are pushed through a real /bin/sh, whatever platform runs the suite: the quoting
+ // of the macOS text (a backtick-free command, `›`, `—`) is what a Linux runner would otherwise
+ // never exercise.
+ async function guardOutput(platform: NodeJS.Platform, dir: string): Promise<string> {
+ const { execFile } = await import('node:child_process')
+ return await new Promise((resolve) => {
+ execFile(
+ '/bin/sh',
+ ['-c', `cd -- "$1" || exit 9\n${unreadableCwdGuard(platform)}echo ENGINE_RAN`, 'guard', dir],
+ { timeout: 10_000 },
+ (_error, stdout, stderr) => resolve(stdout + stderr),
+ )
+ })
+ }
+
+ it.skipIf(!notRoot)('points at the privacy settings on macOS and at permissions elsewhere', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'harness-unreadable-hint-'))
+ try {
+ chmodSync(dir, 0o300)
+ const darwin = await guardOutput('darwin', dir)
+ expect(darwin).toContain('Full Disk Access')
+ expect(darwin).toContain('tmux kill-server')
+ expect(darwin).toContain('Privacy & Security')
+ expect(darwin).not.toContain('ENGINE_RAN')
+ const linux = await guardOutput('linux', dir)
+ expect(linux).toContain('permissions')
+ expect(linux).not.toContain('Privacy & Security')
+ expect(linux).not.toContain('ENGINE_RAN')
+ } finally {
+ chmodSync(dir, 0o700)
+ rmSync(dir, { recursive: true, force: true })
+ }
+ })
+
+ it('keeps the action inside what a relayed pane summary can show', () => {
+ // First hint line: what to do. It has to survive next to a folder path in a ~180-char summary.
+ const firstHint = unreadableCwdGuard('darwin').match(/'(harness: on macOS[^']*)'/)?.[1] ?? ''
+ expect(firstHint.length).toBeGreaterThan(0)
+ expect(firstHint.length).toBeLessThanOrEqual(120)
+ })
+ })
+
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')])
diff --git a/cli/src/lib/engineLaunch.ts b/cli/src/lib/engineLaunch.ts
index d74e074e2..28ae17906 100644
--- a/cli/src/lib/engineLaunch.ts
+++ b/cli/src/lib/engineLaunch.ts
@@ -194,7 +194,9 @@ export function buildEngineLaunchArgv(
// directory and enter the selected workspace only after those files have loaded: an IDE can replace
// a workspace inode between the desktop picker resolving it and tmux spawning the pane.
const cwdPrelude = opts.cwd
- ? `if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; exit 1; fi\nshift\n`
+ ? `if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; exit 1; fi\n`
+ + unreadableCwdGuard()
+ + 'shift\n'
: ''
const body = opts.installIfMissing
? installIfMissingThenExecScript(opts.installIfMissing, runtimeNode)
@@ -208,6 +210,34 @@ export function buildEngineLaunchArgv(
return [interactive.path, ...interactive.args, RAISE_OPEN_FILES_SH + prelude + cwdPrelude + body, 'harness-engine', ...(opts.cwd ? [opts.cwd] : []), ...command]
}
+/**
+ * Refuse a workspace the shell could enter but cannot read, and say why — before the engine finds
+ * out on its own terms.
+ *
+ * `cd` succeeding proves only the search bit. macOS privacy protection (TCC) leaves exactly that:
+ * a process whose responsible app was never granted Documents, Desktop or Downloads may enter the
+ * folder and is refused its first readdir with EPERM. The engine then dies with nothing to go on —
+ * Claude Code printed "An unknown error occurred (Unexpected)" on a machine whose tmux server had
+ * been started by a terminal app without Documents access, and every pane the daemon opened on
+ * that server inherited the refusal — so the check is made here, where the reason can be given.
+ * `[ -r . ]` is `access(2)`, which TCC answers the same way as the readdir would.
+ *
+ * The hint names the fix for the platform this daemon generates the script on, which is the one
+ * the pane runs on. `$PWD` is left to the shell so the message names the folder as entered. Short
+ * lines, the action first: a dialog that relays the pane's last lines keeps about 180 characters
+ * (agentCreateDiagnosis.ts), and the folder path alone can take half of that.
+ */
+export function unreadableCwdGuard(platform: NodeJS.Platform = process.platform): string {
+ const hints = platform === 'darwin'
+ ? [
+ 'harness: on macOS, grant Full Disk Access to the app that started tmux (and to Harness), then run: tmux kill-server',
+ 'harness: or pick a folder outside Documents, Desktop and Downloads (System Settings › Privacy & Security).',
+ ]
+ : ['harness: check the folder\'s permissions for this user.']
+ return `if ! [ -r . ]; then printf '%s\\n' "harness: cannot read $PWD — the agent was not started." `
+ + `${hints.map(shellSingleQuote).join(' ')} >&2; exit 1; fi\n`
+}
+
/**
* `unset` for the variables a grid launch must not let through, or nothing at all.
*