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.

feat: introduce binaryOnPath utility to improve engine installation diagnostics and refactor sqlite detection

0xken15fb10ad67a2b8
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 5f73f24d0..4fb3dd6e8 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -25,6 +25,7 @@ import { env } from './config/env.js'
import { VERSION } from './version.js'
import { sqlitePreflightMessage } from './lib/sqliteAvailability.js'
import { ensureUtf8Locale } from './lib/childLocale.js'
+import { binaryOnPath } from './lib/binaryOnPath.js'
import { registry, projectDisplayName, type RegisteredSession } from './lib/registry.js'
import { installAmpPlugin, installCodexHooks, installCommandCodeHooks, installCursorHooks, installDevinHooks, installGrokHooks, installAgyHooks, installCopilotHooks, installHermesHooks, installKiloPlugin, installOpencodePlugin, installPiExtension, installSessionHooks } from './lib/hooks.js'
import { PID_FILE, TOKEN_FILE, daemonPort, isAlive, readPid } from './lib/daemonState.js'
@@ -2417,18 +2418,34 @@ async function runForeground(token: string): Promise<void> {
return { ok: false, error: 'CWD_NOT_FOUND' }
}
const label = `${engine}-${Date.now()}`.replace(/[^A-Za-z0-9_-]/g, '-')
- const spawned = await tmuxBackend.create({
- cwd,
- label,
- command: buildEngineLaunchArgv(engine, { bypassPermission }),
- })
- if (spawned.state !== 'succeeded') return { ok: false, error: 'SPAWN_FAILED' }
+ const argv = buildEngineLaunchArgv(engine, { bypassPermission })
+ const spawned = await tmuxBackend.create({ cwd, label, command: argv })
+ if (spawned.state !== 'succeeded') {
+ console.warn(`[agent] create ${engine} failed · tmux could not open a pane · ${spawned.reason ?? ''}`)
+ return { ok: false, error: 'SPAWN_FAILED' }
+ }
for (const delayMs of [150, 400, 800]) {
await new Promise((resolve) => setTimeout(resolve, delayMs))
await agentReconciler.triggerHint(spawned.runtime, engine)
const session = registry.byRuntimeEngine(spawned.runtime, engine)
if (session) return { ok: true, session }
}
+ // `tmux new-session` reports success for a command that does not exist — it opens the pane, the
+ // shell says "<engine>: command not found", and the session is gone a moment later. Discovery then
+ // finds nothing and the user is told ENGINE_DID_NOT_START, which on a fresh machine is almost
+ // always "that CLI is not installed" and reads like a Harness bug instead. Measured on a container
+ // with only claude present: `tmux new-session -d "codex …"` exits 0 and leaves no session.
+ //
+ // The check is done HERE rather than before spawning on purpose: the tmux server may carry a
+ // different PATH than this daemon (it inherits from whoever started it), so a binary we cannot see
+ // might still launch. Refusing up front would turn that into a false negative; explaining a failure
+ // that already happened cannot.
+ const bin = argv[0]
+ if (!binaryOnPath(bin)) {
+ console.warn(`[agent] create ${engine} failed · "${bin}" is not installed or not on PATH`)
+ return { ok: false, error: 'ENGINE_NOT_INSTALLED' }
+ }
+ console.warn(`[agent] create ${engine} failed · "${bin}" started but no engine process appeared in the pane`)
return { ok: false, error: 'ENGINE_DID_NOT_START' }
}
diff --git a/cli/src/lib/binaryOnPath.spec.ts b/cli/src/lib/binaryOnPath.spec.ts
new file mode 100644
index 000000000..a38300f49
--- /dev/null
+++ b/cli/src/lib/binaryOnPath.spec.ts
@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { binaryOnPath } from './binaryOnPath.js'
+
+const dirs: string[] = []
+afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+
+function dirWith(name: string | null, mode = 0o755): string {
+ const dir = mkdtempSync(join(tmpdir(), 'bin-on-path-'))
+ dirs.push(dir)
+ if (name) {
+ writeFileSync(join(dir, name), '#!/bin/sh\nexit 0\n')
+ chmodSync(join(dir, name), mode)
+ }
+ return dir
+}
+
+describe('binaryOnPath', () => {
+ it('finds an executable by name on PATH', () => {
+ expect(binaryOnPath('codex', { PATH: dirWith('codex') })).toBe(true)
+ })
+
+ // The case behind the report: the machine has claude but not codex, so "New agent → Codex" can only
+ // fail. Saying WHICH is the whole point — tmux reports success for a command that does not exist.
+ it('reports a name that is on no PATH entry', () => {
+ expect(binaryOnPath('codex', { PATH: `${dirWith('claude')}${delimiter}${dirWith(null)}` })).toBe(false)
+ })
+
+ it('requires the executable bit, not just the file', () => {
+ expect(binaryOnPath('codex', { PATH: dirWith('codex', 0o644) })).toBe(false)
+ })
+
+ it('checks an explicit path directly instead of searching PATH', () => {
+ const dir = dirWith('codex')
+ expect(binaryOnPath(join(dir, 'codex'), { PATH: '' })).toBe(true)
+ expect(binaryOnPath(join(dir, 'nope'), { PATH: dir })).toBe(false)
+ })
+
+ it('handles an empty or absent PATH and an empty name', () => {
+ expect(binaryOnPath('codex', {})).toBe(false)
+ expect(binaryOnPath('', { PATH: dirWith('codex') })).toBe(false)
+ })
+})
diff --git a/cli/src/lib/binaryOnPath.ts b/cli/src/lib/binaryOnPath.ts
new file mode 100644
index 000000000..75999ab0a
--- /dev/null
+++ b/cli/src/lib/binaryOnPath.ts
@@ -0,0 +1,22 @@
+/**
+ * Is `command` runnable — an executable at that path, or a name resolvable on PATH?
+ *
+ * Resolved by reading PATH rather than by spawning: callers use it on the startup path and in error
+ * reporting, where launching a process to ask would be both slower and noisier.
+ *
+ * The same shape already lives in `herdrBinaryAvailable` (lib/herdrSessions.ts), which keeps its own
+ * copy because it is exported API with its own tests.
+ */
+import { accessSync, constants } from 'node:fs'
+import { delimiter, join } from 'node:path'
+
+export function binaryOnPath(command: string, env: NodeJS.ProcessEnv = process.env): boolean {
+ if (!command) return false
+ const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : ['']
+ const candidates = command.includes('/') || command.includes('\\')
+ ? [command]
+ : (env.PATH ?? '').split(delimiter).filter(Boolean).map((dir) => join(dir, command))
+ return candidates.some((candidate) => extensions.some((extension) => {
+ try { accessSync(candidate + extension, constants.X_OK); return true } catch { return false }
+ }))
+}
diff --git a/cli/src/lib/sqliteAvailability.ts b/cli/src/lib/sqliteAvailability.ts
index 0e955f90f..616d4e4be 100644
--- a/cli/src/lib/sqliteAvailability.ts
+++ b/cli/src/lib/sqliteAvailability.ts
@@ -10,8 +10,7 @@
* Resolved from PATH directly rather than by spawning: this runs on the startup path and the answer is
* only used for one advisory log line.
*/
-import { accessSync, constants } from 'node:fs'
-import { delimiter, join } from 'node:path'
+import { binaryOnPath } from './binaryOnPath.js'
/** Engines that cannot be mirrored without the CLI. Keep in sync with the readers listed above. */
export const SQLITE_BACKED_ENGINES = ['opencode', 'kilo', 'hermes', 'devin'] as const
@@ -20,13 +19,7 @@ let cached: boolean | null = null
export function hasSqliteCli(): boolean {
if (cached !== null) return cached
- const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : ['']
- cached = (process.env.PATH ?? '').split(delimiter).some((dir) => {
- if (!dir) return false
- return exts.some((ext) => {
- try { accessSync(join(dir, `sqlite3${ext}`), constants.X_OK); return true } catch { return false }
- })
- })
+ cached = binaryOnPath('sqlite3')
return cached
}