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: expose detailed tmux error messages during agent creation failures

0xken15708f8b47eca7
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index bde0ef877..8976c34b9 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -294,7 +294,7 @@ export class BackendSocket {
/** Called on `agent_create` — cli.ts spawns a fresh tmux session running the requested engine in the
* requested folder and returns the registered session once discovery has picked it up. */
onCreateAgent: ((input: { engine: AgentEngine; cwd: string; bypassPermission: boolean }) =>
- Promise<{ ok: true; session: RegisteredSession } | { ok: false; error: string }>) | null = null
+ Promise<{ ok: true; session: RegisteredSession } | { ok: false; error: string; detail?: string }>) | null = null
/** Called when the web/device sends chat input to an agent terminal. */
onMessage: ((sessionId: string, content: string) => void) | null = null
/** Best-effort terminal-native title sync after a user renames an agent. */
@@ -1270,7 +1270,12 @@ export class BackendSocket {
if (!cwd || !isAbsolute(cwd)) { reply(type, requestId, { error: 'INVALID_CWD' }); return }
if (!this.onCreateAgent) { reply(type, requestId, { error: 'UNSUPPORTED_ON_REMOTE' }); return }
const result = await this.onCreateAgent({ engine, cwd, bypassPermission: payload.bypassPermission === true })
- if (!result.ok) { reply(type, requestId, { error: result.error }); return }
+ // `detail` carries the underlying cause (tmux's own message) so the person who clicked
+ // Create can read it, rather than having to open a log on the machine that failed.
+ if (!result.ok) {
+ reply(type, requestId, result.detail ? { error: result.error, detail: result.detail } : { error: result.error })
+ return
+ }
reply(type, requestId, { agent: await this.toProject(result.session) })
return
}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index aaffdb2bb..d7333f01d 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -2647,7 +2647,7 @@ async function runForeground(session: AuthSession): Promise<void> {
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' }
+ return { ok: false, error: 'SPAWN_FAILED', detail: spawned.reason }
}
for (const delayMs of [150, 400, 800]) {
await new Promise((resolve) => setTimeout(resolve, delayMs))
diff --git a/cli/src/lib/tmuxBackend.spec.ts b/cli/src/lib/tmuxBackend.spec.ts
index 8d53bad2b..448b90ccc 100644
--- a/cli/src/lib/tmuxBackend.spec.ts
+++ b/cli/src/lib/tmuxBackend.spec.ts
@@ -45,6 +45,39 @@ esac
])
})
+ it('carries tmux\'s own refusal into the failure reason', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'tmux-backend-refusal-'))
+ dirs.push(dir)
+ const tmux = join(dir, 'tmux')
+ // What a real tmux does when the session name is taken: exit 1, reason on stderr, nothing on
+ // stdout. Swallowing that turned every distinct cause into one bare SPAWN_FAILED.
+ writeFileSync(tmux, `#!/bin/sh
+printf 'duplicate session: harness-test\\n' >&2
+exit 1
+`)
+ chmodSync(tmux, 0o700)
+ process.env.PATH = `${dir}${delimiter}${originalPath ?? ''}`
+
+ const created = await new TmuxBackend().create({ cwd: '/tmp/work', label: 'harness-test' })
+
+ expect(created.state).not.toBe('succeeded')
+ if (created.state === 'succeeded') return
+ expect(created.reason).toContain('duplicate session: harness-test')
+ })
+
+ it('still reports a missing tmux as unavailable rather than a refusal', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'tmux-backend-absent-'))
+ dirs.push(dir)
+ // An empty directory as the ENTIRE path: nothing named tmux is resolvable, so execFile ENOENTs.
+ process.env.PATH = dir
+
+ const created = await new TmuxBackend().create({ cwd: '/tmp/work', label: 'harness-test' })
+
+ expect(created.state).not.toBe('succeeded')
+ if (created.state === 'succeeded') return
+ expect(created.reason).toBe('tmux is unavailable')
+ })
+
it('displays a bounded message in the addressed pane without a shell', async () => {
const dir = mkdtempSync(join(tmpdir(), 'tmux-backend-notify-'))
dirs.push(dir)
diff --git a/cli/src/lib/tmuxBackend.ts b/cli/src/lib/tmuxBackend.ts
index e2588af41..e09bd6340 100644
--- a/cli/src/lib/tmuxBackend.ts
+++ b/cli/src/lib/tmuxBackend.ts
@@ -79,16 +79,26 @@ export class TmuxBackend implements TerminalBackend<TmuxRuntimeRef> {
// Trailing args after this point become the session's shell-command. tmux execs them directly
// (no shell interposed) when given as separate argv elements, so no quoting/escaping is needed.
if (request.command?.length) args.push(...request.command)
- const result = await new Promise<{ error: NodeJS.ErrnoException | null; stdout: string }>((resolve) => {
- execFile('tmux', args, { timeout: 5_000 }, (error, stdout) => resolve({
- error: error as NodeJS.ErrnoException | null,
+ // `killed`/`signal` come from execFile's own error shape, which ErrnoException alone does not declare.
+ type ExecError = NodeJS.ErrnoException & { killed?: boolean; signal?: NodeJS.Signals | null }
+ const result = await new Promise<{ error: ExecError | null; stdout: string; stderr: string }>((resolve) => {
+ execFile('tmux', args, { timeout: 5_000 }, (error, stdout, stderr) => resolve({
+ error: error as ExecError | null,
stdout,
+ stderr,
}))
})
if (result.error) {
- return result.error.code === 'ENOENT'
- ? terminalActionNotStarted('tmux is unavailable')
- : terminalActionPossiblyExecuted('tmux session creation did not complete')
+ if (result.error.code === 'ENOENT') return terminalActionNotStarted('tmux is unavailable')
+ // tmux says exactly why it refused — "duplicate session", "protocol version mismatch",
+ // a .tmux.conf error, a directory it cannot enter. Dropping stderr here turned every one of
+ // those into the same unactionable SPAWN_FAILED, diagnosable only by reading the daemon log
+ // on the machine that failed, which does not have the reason either.
+ const detail = result.stderr.trim().split('\n')[0]?.slice(0, 200)
+ // execFile reports a timeout kill as SIGTERM with no stderr — the one failure whose cause
+ // is not in tmux's own output.
+ || (result.error.killed ? 'tmux did not answer within 5s' : result.error.message.slice(0, 200))
+ return terminalActionPossiblyExecuted(`tmux session creation did not complete: ${detail}`)
}
const paneId = result.stdout.trim()
if (!/^%\d+$/.test(paneId)) {