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: resolve Claude native installer process matching and improve diagnostic reporting for registry registration failures

0xken156974b495b47b
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 6f658cae6..b3c90cb3f 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -47,7 +47,7 @@ import { terminateDeletedAgent } from './lib/deleteAgentFallback.js'
import { findLiveSession } from './lib/sessionRepair.js'
import { TmuxBackend } from './lib/tmuxBackend.js'
import { basename } from 'node:path'
-import { captureTmuxPane, clearPaneRemainOnExit, tmuxPaneProcessTree, tmuxPaneState, type TmuxPaneState } from './lib/tmux.js'
+import { captureTmuxPane, clearPaneRemainOnExit, resolvePaneEngineProcess, tmuxPaneProcessTree, tmuxPaneState, type TmuxPaneState } from './lib/tmux.js'
import { describeAgentCreateFailure, summarizePaneOutput } from './lib/agentCreateDiagnosis.js'
import { HerdrBackend } from './lib/herdrBackend.js'
import {
@@ -2708,16 +2708,37 @@ async function runForeground(session: AuthSession): Promise<void> {
// hammering `ps` for eight seconds.
delayMs = Math.min(delayMs * 2, 750)
}
+
+ // Close the race between the last scheduled discovery snapshot and the error snapshot below.
+ // Claude's native launcher can still identify as its versioned install target during the former,
+ // then become a matchable `claude` process while painting its first-run trust prompt. A fresh,
+ // authoritative process lookup makes that a valid sessionless process-agent instead of reporting
+ // ENGINE_DID_NOT_START. It never sends input to the pane: folder trust remains the user's choice.
+ let engineProcess = paneState && !paneState.dead
+ ? await resolvePaneEngineProcess(spawned.runtime.paneId, engine)
+ : null
+ if (engineProcess) {
+ await agentReconciler.triggerHint(spawned.runtime, engine)
+ const session = registry.byRuntimeEngine(spawned.runtime, engine)
+ if (session) {
+ await clearPaneRemainOnExit(spawned.runtime.paneId)
+ return { ok: true, session }
+ }
+ // Keep the diagnosis tied to the latest pane state if registration itself failed.
+ paneState = await tmuxPaneState(spawned.runtime.paneId)
+ if (!paneState || paneState.dead) engineProcess = null
+ }
const diagnosis = describeAgentCreateFailure({
state: paneState,
output: summarizePaneOutput(
await captureTmuxPane(spawned.runtime.paneId, 40, { ansi: false }) ?? '',
),
engineBin: command[0],
- // Only useful when a process IS there and did not match; a dead or vanished pane has no tree.
+ // A dead or vanished pane has no tree; every live failure includes one for remote diagnosis.
processes: paneState && !paneState.dead
? await tmuxPaneProcessTree(spawned.runtime.paneId)
: [],
+ engineProcessFound: !!engineProcess,
shellName: (() => {
const path = interactiveEngineShell()?.path
return path ? basename(path) : null
diff --git a/cli/src/lib/agentCreateDiagnosis.spec.ts b/cli/src/lib/agentCreateDiagnosis.spec.ts
index a1d763789..afc525917 100644
--- a/cli/src/lib/agentCreateDiagnosis.spec.ts
+++ b/cli/src/lib/agentCreateDiagnosis.spec.ts
@@ -68,6 +68,31 @@ describe('describeAgentCreateFailure', () => {
expect(detail).toContain('no codex process was found under it')
})
+ it('reports a matched process whose registry adoption did not finish', () => {
+ const detail = describeAgentCreateFailure({
+ ...base,
+ state: { dead: false, exitStatus: null, command: '2.1.246' },
+ engineBin: 'claude',
+ engineProcessFound: true,
+ processes: [{ executable: 'claude', args: 'claude' }],
+ })
+ expect(detail).toContain('"claude" process was found under the pane')
+ expect(detail).toContain('agent registration did not complete')
+ expect(detail).not.toContain('no claude process')
+ })
+
+ it('names a live Claude trust prompt without treating it as a missing process', () => {
+ const detail = describeAgentCreateFailure({
+ ...base,
+ state: { dead: false, exitStatus: null, command: '2.1.246' },
+ engineBin: 'claude',
+ engineProcessFound: true,
+ output: '1. Yes, I trust this folder · 2. No, exit',
+ })
+ expect(detail).toContain('is running and waiting for folder trust')
+ expect(detail).not.toContain('no claude process')
+ })
+
it('says so when tmux did not keep the pane, since the output is then unrecoverable', () => {
const detail = describeAgentCreateFailure({ ...base, state: null })
expect(detail).toContain('tmux did not keep it')
diff --git a/cli/src/lib/agentCreateDiagnosis.ts b/cli/src/lib/agentCreateDiagnosis.ts
index 3c907de67..f9279306b 100644
--- a/cli/src/lib/agentCreateDiagnosis.ts
+++ b/cli/src/lib/agentCreateDiagnosis.ts
@@ -28,8 +28,10 @@ export interface AgentCreatePaneFacts {
engineBin: string
/** Process name of the wrapper login shell, e.g. `zsh`. Null when no interactive shell was used. */
shellName: string | null
- /** Processes found under the pane, shallowest first. Only read when nothing matched the engine. */
+ /** Processes found under the pane, shallowest first, for the remote-readable diagnosis. */
processes: ReadonlyArray<{ executable: string; args: string }>
+ /** A fresh matcher pass found the requested engine, even though registry adoption did not finish. */
+ engineProcessFound?: boolean
elapsedMs: number
}
@@ -106,7 +108,7 @@ function withOutput(summary: string, output: string): string {
* failed: it says what the pane was doing, not what the code checked.
*/
export function describeAgentCreateFailure(facts: AgentCreatePaneFacts): string {
- const { state, output, engineBin, shellName, processes, elapsedMs } = facts
+ const { state, output, engineBin, shellName, processes, engineProcessFound = false, elapsedMs } = facts
const waited = seconds(elapsedMs)
// tmux forgot the pane entirely. `create` asks tmux to keep dead panes, so reaching this means the
@@ -135,9 +137,20 @@ export function describeAgentCreateFailure(facts: AgentCreatePaneFacts): string
)
}
+ const tree = summarizeProcessTree(processes)
+ if (engineProcessFound) {
+ const waitingForTrust = /(?:yes,\s*i trust this folder|trust this folder)/i.test(output)
+ return withOutput(
+ waitingForTrust
+ ? `"${engineBin}" is running and waiting for folder trust, but agent registration did not complete after ${waited}`
+ : `"${engineBin}" process was found under the pane, but agent registration did not complete after ${waited}`
+ + (tree ? ` · saw: ${tree}` : ''),
+ output,
+ )
+ }
+
// Naming only the foreground command is what left the last report unactionable: discovery searches
// the WHOLE tree under the pane, so "it was running node" does not say what discovery rejected.
- const tree = summarizeProcessTree(processes)
return withOutput(
`after ${waited} the pane was running "${state.command}" but no ${engineBin} process was found under it`
+ (tree ? ` · saw: ${tree}` : ''),
diff --git a/cli/src/lib/tmux.spec.ts b/cli/src/lib/tmux.spec.ts
index 691746070..9e44329aa 100644
--- a/cli/src/lib/tmux.spec.ts
+++ b/cli/src/lib/tmux.spec.ts
@@ -84,6 +84,18 @@ describe('tmux process primitives', () => {
expect(engineProcessMatchScore({ executable: '/Users/demo/.grok/bin/grok', args: 'grok' }, 'grok')).toBe(3)
})
+ it('recognises Claude native installer version targets without accepting a bare semver', () => {
+ expect(engineProcessMatchScore({
+ executable: '/Users/demo/.local/share/claude/versions/2.1.246',
+ args: '/Users/demo/.local/share/claude/versions/2.1.246',
+ }, 'claude')).toBe(3)
+ expect(engineProcessMatchScore({
+ executable: '2.1.246',
+ args: '/home/demo/.local/share/claude/versions/2.1.246',
+ }, 'claude')).toBe(3)
+ expect(engineProcessMatchScore({ executable: '2.1.246', args: '2.1.246' }, 'claude')).toBe(0)
+ })
+
it('reads an engine through the ori launcher, before and after its exec', () => {
// `ori claude` computes an environment and then execve's the vendor binary away, so for all but the
// first ~100ms the pane row IS `claude` — that case must keep scoring exactly as a bare launch does.
diff --git a/cli/src/lib/tmux.ts b/cli/src/lib/tmux.ts
index 23ae8c257..392163c32 100644
--- a/cli/src/lib/tmux.ts
+++ b/cli/src/lib/tmux.ts
@@ -270,6 +270,19 @@ function commTruncatedPrefixOf(seen: string, want: string): boolean {
return Buffer.byteLength(seen) === 15 && want.length > seen.length && want.startsWith(seen)
}
+/**
+ * Claude's native installer exposes `~/.local/bin/claude` as a symlink to a binary whose basename is
+ * only its version (`~/.local/share/claude/versions/2.1.246`). During early startup both `comm` and
+ * argv[0] can still contain that target path, before Claude rewrites either one to `claude`.
+ *
+ * Match the vendor-specific install layout, never a bare semver: an unrelated process called
+ * `2.1.246` is not evidence that Claude is running.
+ */
+function claudeNativeInstallPath(value: string): boolean {
+ const normalized = value.replace(/\\/g, '/').toLowerCase()
+ return /(?:^|\/)\.local\/share\/claude\/versions\/[^/]+$/.test(normalized)
+}
+
export function engineProcessMatchScore(
row: Pick<ProcessRow, 'executable' | 'args' | 'imageFileKey' | 'entrypointFileKey'>,
engine: RegisteredSession['engine'],
@@ -372,6 +385,7 @@ export function engineProcessMatchScore(
return /@github[\/\\]copilot[\/\\](?:npm-loader\.js|.*copilot)$/.test(entrypoint) ? 2 : 0
}
if (executable === 'claude' || entrybase === 'claude') return 3
+ if (claudeNativeInstallPath(row.executable) || claudeNativeInstallPath(entrypoint)) return 3
return /@anthropic-ai[\/\\]claude-code[\/\\]cli\.js$/.test(entrypoint) ? 2 : 0
}
diff --git a/cli/src/lib/tmuxAgentDiscovery.spec.ts b/cli/src/lib/tmuxAgentDiscovery.spec.ts
index cf040d9ae..3c6184e09 100644
--- a/cli/src/lib/tmuxAgentDiscovery.spec.ts
+++ b/cli/src/lib/tmuxAgentDiscovery.spec.ts
@@ -130,6 +130,17 @@ describe('tmux process agent snapshot discovery', () => {
expect(result.agents[0].engine).toBe(engine)
})
+ it('discovers a native Claude version target before it rewrites argv to claude', () => {
+ const native = '/home/demo/.local/share/claude/versions/2.1.246'
+ const result = discoverTmuxAgentsFromSnapshot(
+ [pane],
+ [row(1, 0, 'zsh'), row(2, 1, '2.1.246', native)],
+ 900,
+ )
+ expect(result.agents).toHaveLength(1)
+ expect(result.agents[0]).toMatchObject({ engine: 'claude', tmuxPane: '%1' })
+ })
+
const installPrefixes = [
'/usr/local',
'/opt/homebrew',