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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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()?.pathreturn path ? basename(path) : nulldiff --git a/cli/src/lib/agentCreateDiagnosis.spec.ts b/cli/src/lib/agentCreateDiagnosis.spec.tsindex 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.tsindex 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 } = factsconst 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.tsindex 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,