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: include redacted process tree in agent creation failure reports to improve diagnostic visibility

0xken1560632dc86662
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 361f2f3c6..aade56807 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, tmuxPaneState } from './lib/tmux.js'
+import { captureTmuxPane, clearPaneRemainOnExit, tmuxPaneProcessTree, tmuxPaneState } from './lib/tmux.js'
import { describeAgentCreateFailure, summarizePaneOutput } from './lib/agentCreateDiagnosis.js'
import { HerdrBackend } from './lib/herdrBackend.js'
import {
@@ -2697,6 +2697,10 @@ async function runForeground(session: AuthSession): Promise<void> {
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.
+ processes: paneState && !paneState.dead
+ ? await tmuxPaneProcessTree(spawned.runtime.paneId)
+ : [],
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 70321f184..a1d763789 100644
--- a/cli/src/lib/agentCreateDiagnosis.spec.ts
+++ b/cli/src/lib/agentCreateDiagnosis.spec.ts
@@ -1,7 +1,9 @@
import { describe, expect, it } from 'vitest'
import {
describeAgentCreateFailure,
+ redactArgv,
summarizePaneOutput,
+ summarizeProcessTree,
type AgentCreatePaneFacts,
} from './agentCreateDiagnosis.js'
@@ -10,6 +12,7 @@ const base: AgentCreatePaneFacts = {
output: '',
engineBin: 'codex',
shellName: 'zsh',
+ processes: [],
elapsedMs: 1400,
}
@@ -62,7 +65,7 @@ describe('describeAgentCreateFailure', () => {
state: { dead: false, exitStatus: null, command: 'node' },
})
expect(detail).toContain('was running "node"')
- expect(detail).toContain('not recognised as a codex agent')
+ expect(detail).toContain('no codex process was found under it')
})
it('says so when tmux did not keep the pane, since the output is then unrecoverable', () => {
@@ -81,6 +84,55 @@ describe('describeAgentCreateFailure', () => {
state: { dead: true, exitStatus: 1, command: 'codex' },
output: 'e'.repeat(400),
})
- expect(detail.length).toBeLessThanOrEqual(340)
+ expect(detail.length).toBeLessThanOrEqual(520)
+ })
+})
+
+describe('redactArgv', () => {
+ it('blanks credential-shaped flag values', () => {
+ expect(redactArgv('codex --api-key sk-live-1 --token=abc --model gpt-5.5'))
+ .toBe('codex --api-key <redacted> --token=<redacted> --model gpt-5.5')
+ })
+
+ it('blanks a long opaque run no launch argv needs to show', () => {
+ expect(redactArgv('node /bin/x AKIAIOSFODNN7EXAMPLEKEYVALUE12345'))
+ .toBe('node /bin/x <redacted>')
+ })
+
+ it('leaves an ordinary launch untouched', () => {
+ const argv = '/bin/zsh -lic exec "$@" harness-engine codex'
+ expect(redactArgv(argv)).toBe(argv)
+ })
+})
+
+describe('summarizeProcessTree', () => {
+ it('names what discovery walked past, which the foreground command alone does not', () => {
+ expect(summarizeProcessTree([
+ { executable: 'node', args: 'node /usr/local/bin/codex-update-notifier' },
+ { executable: 'sh', args: 'sh -c true' },
+ ])).toBe('node "node /usr/local/bin/codex-update-notifier" \u00b7 sh "sh -c true"')
+ })
+
+ it('bounds each argv so one long command cannot eat the message', () => {
+ const long = summarizeProcessTree([{ executable: 'node', args: 'node ' + 'a'.repeat(300) }])
+ expect(long.length).toBeLessThan(120)
+ })
+
+ it('is empty when no process could be read', () => {
+ expect(summarizeProcessTree([])).toBe('')
+ })
+})
+
+describe('describeAgentCreateFailure with a process tree', () => {
+ it('reports the tree so a remote reader can identify an uncovered install layout', () => {
+ const detail = describeAgentCreateFailure({
+ ...base,
+ state: { dead: false, exitStatus: null, command: 'node' },
+ processes: [{ executable: 'node', args: 'node /opt/x/update-notifier.js' }],
+ output: '2. Skip \u00b7 Press enter to continue',
+ })
+ expect(detail).toContain('no codex process was found under it')
+ expect(detail).toContain('saw: node "node /opt/x/update-notifier.js"')
+ expect(detail).toContain('Press enter to continue')
})
})
diff --git a/cli/src/lib/agentCreateDiagnosis.ts b/cli/src/lib/agentCreateDiagnosis.ts
index eaaca4760..3c907de67 100644
--- a/cli/src/lib/agentCreateDiagnosis.ts
+++ b/cli/src/lib/agentCreateDiagnosis.ts
@@ -28,11 +28,14 @@ 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: ReadonlyArray<{ executable: string; args: string }>
elapsedMs: number
}
const MAX_OUTPUT_CHARS = 180
-const MAX_DETAIL_CHARS = 340
+const MAX_DETAIL_CHARS = 520
+const MAX_ARGV_CHARS = 90
/** tmux paints this into a pane it is keeping alive under `remain-on-exit`; it is our own artifact. */
const DEAD_PANE_NOTICE = /^Pane is dead \(.*\)$/
@@ -61,6 +64,32 @@ export function summarizePaneOutput(raw: string): string {
return tail.length > MAX_OUTPUT_CHARS ? `${tail.slice(0, MAX_OUTPUT_CHARS - 1)}…` : tail
}
+/**
+ * Blank anything in an argv that looks like a credential before it travels into a dialog.
+ *
+ * The processes reported here are the ones under a pane this daemon just created, so their argv is
+ * normally the engine launch we built ourselves. "Normally" is not a guarantee once the engine starts
+ * spawning its own children, and an error string is the wrong place to find out.
+ */
+export function redactArgv(args: string): string {
+ return args
+ .replace(/(--?[\w-]*(?:key|token|secret|password|passwd|auth|credential)[\w-]*[= ])\S+/gi, '$1<redacted>')
+ // A long opaque run of credential-shaped characters is not something a launch argv needs to show.
+ .replace(/\b[A-Za-z0-9_-]{32,}\b/g, '<redacted>')
+}
+
+/** `node "/usr/local/bin/codex" · sh "..."` — what the pane was actually made of. */
+export function summarizeProcessTree(
+ processes: ReadonlyArray<{ executable: string; args: string }>,
+): string {
+ const rendered = processes.slice(0, 4).map(({ executable, args }) => {
+ const argv = redactArgv(args).trim()
+ const shown = argv.length > MAX_ARGV_CHARS ? `${argv.slice(0, MAX_ARGV_CHARS - 1)}\u2026` : argv
+ return shown ? `${executable} "${shown}"` : executable
+ })
+ return rendered.join(' \u00b7 ')
+}
+
function seconds(elapsedMs: number): string {
return `${(elapsedMs / 1000).toFixed(1)}s`
}
@@ -77,7 +106,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, elapsedMs } = facts
+ const { state, output, engineBin, shellName, processes, elapsedMs } = facts
const waited = seconds(elapsedMs)
// tmux forgot the pane entirely. `create` asks tmux to keep dead panes, so reaching this means the
@@ -106,8 +135,12 @@ export function describeAgentCreateFailure(facts: AgentCreatePaneFacts): string
)
}
+ // 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 it was not recognised as a ${engineBin} agent`,
+ `after ${waited} the pane was running "${state.command}" but no ${engineBin} process was found under it`
+ + (tree ? ` · saw: ${tree}` : ''),
output,
)
}
diff --git a/cli/src/lib/tmux.ts b/cli/src/lib/tmux.ts
index 37316b22f..23ae8c257 100644
--- a/cli/src/lib/tmux.ts
+++ b/cli/src/lib/tmux.ts
@@ -497,6 +497,42 @@ async function lookupPaneEngineProcess(
}
}
+/**
+ * Every process under a pane, shallowest first — the answer to "then WHAT was running?".
+ *
+ * `selectEngineProcess` returning null says only that nothing matched the engine, which is the least
+ * useful half of the finding. The processes it walked past are what identify an install layout the
+ * matcher does not cover, or a launcher that has not exec'd the engine yet, and reading them off the
+ * failing machine is exactly what a person diagnosing a remote New Agent failure cannot do.
+ */
+export async function tmuxPaneProcessTree(
+ pane: string,
+ limit = 4,
+): Promise<Array<{ executable: string; args: string }>> {
+ const rootPid = await panePid(pane)
+ if (!rootPid) return []
+ const rows = await processRows()
+ if (!rows) return []
+ const children = new Map<number, ProcessRow[]>()
+ for (const row of rows) {
+ const list = children.get(row.parentPid) ?? []
+ list.push(row)
+ children.set(row.parentPid, list)
+ }
+ const byPid = new Map(rows.map((row) => [row.pid, row]))
+ const found: Array<{ executable: string; args: string }> = []
+ const queue = [rootPid]
+ // Breadth-first for the same reason `selectEngineProcess` is: the shallowest processes are the
+ // launch chain, and a deep child is the least likely to explain the failure.
+ while (queue.length && found.length < limit) {
+ const pid = queue.shift()!
+ const row = byPid.get(pid)
+ if (row) found.push({ executable: row.executable, args: row.args })
+ for (const child of children.get(pid) ?? []) queue.push(child.pid)
+ }
+ return found
+}
+
/** Boolean form for callers that only need "is it there". */
export async function resolvePaneEngineProcess(
pane: string,