{"record":{"id":"9cd0a5fffaada1e0","repo":"affaan-m/ECC","slug":"program-args-join-failed-stderr","errorCode":null,"errorMessage":"${program} ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}","messagePattern":"(.+?) (.+?) failed(.+?)` : ''\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/lib/tmux-worktree-orchestrator.js","lineNumber":336,"sourceCode":"    for (const file of artifacts.files) {\n      fs.writeFileSync(file.path, file.content + '\\n', 'utf8');\n    }\n  }\n}\n\nfunction runCommand(program, args, options = {}) {\n  const result = spawnSync(program, args, {\n    cwd: options.cwd,\n    encoding: 'utf8',\n    stdio: ['ignore', 'pipe', 'pipe']\n  });\n\n  if (result.error) {\n    throw result.error;\n  }\n  if (result.status !== 0) {\n    const stderr = (result.stderr || '').trim();\n    throw new Error(`${program} ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}`);\n  }\n  return result;\n}\n\nfunction commandSucceeds(program, args, options = {}) {\n  const result = spawnSync(program, args, {\n    cwd: options.cwd,\n    encoding: 'utf8',\n    stdio: ['ignore', 'pipe', 'pipe']\n  });\n  return result.status === 0;\n}\n\nfunction canonicalizePath(targetPath) {\n  const resolvedPath = path.resolve(targetPath);\n\n  try {\n    return fs.realpathSync.native(resolvedPath);","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/tmux-worktree-orchestrator.js#L318-L354","documentation":"runCommand is a wrapper around spawnSync used for all git/tmux invocations. When the spawned process exits with a non-zero status, it throws an Error containing the full command line and any captured stderr, so callers (and users) see exactly which external command failed and why.","triggerScenarios":"Any runCommand call whose child process exits non-zero: e.g. 'git worktree add' on a path that already exists or a branch name that already exists, 'tmux new-session'/'split-window' when no tmux server/session exists or tmux is not installed, or 'git rev-parse' in a non-git directory.","commonSituations":"Running the orchestrator outside a git repo; a leftover worktree or branch from a previous crashed run; tmux not installed or not running; insufficient permissions on the worktree root; git version lacking worktree support.","solutions":["Read the stderr in the error message to identify the failing git/tmux command and its cause.","Clean up stale state: remove existing worktrees ('git worktree list' / 'git worktree remove') and delete leftover 'orchestrator-*' branches.","Verify tmux and git are installed and on PATH, and that you are inside a git repository.","Check permissions on the repo root and worktree root directories."],"exampleFix":"// before (stale branch blocks 'git worktree add -b orchestrator-foo-worker')\ngit worktree add -b orchestrator-foo-worker ../foo-worktree\n// after\ngit branch -D orchestrator-foo-worker\ngit worktree add -b orchestrator-foo-worker ../foo-worktree","handlingStrategy":"try-catch","validationCode":"// pre-flight checks before running the orchestrator\nspawnSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });\nspawnSync('tmux', ['-V'], { stdio: 'ignore' });\nconst wt = spawnSync('git', ['worktree', 'list'], { encoding: 'utf8' });\nif (wt.stdout.includes(sessionName)) console.warn('stale worktrees exist for this session');","typeGuard":null,"tryCatchPattern":"try {\n  const result = runCommand('git', ['worktree', 'add', '-b', branch, path, baseRef]);\n} catch (err) {\n  console.error(`Command failed: ${err.message}`);\n  if (err.message.includes('already exists')) {\n    // clean stale worktree/branch and retry once\n  }\n  throw err;\n}","preventionTips":["Run 'git worktree prune' and delete stale orchestrator-* branches after crashed runs","Verify git and tmux are installed and on PATH before invoking the orchestrator","Run the orchestrator from inside the target git repository","Check the stderr in the message first — it names the exact failing command and reason"],"tags":["shell","git","tmux","process"],"backgroundTag":"git-command-failed","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}