[medium] perf(custom-command): run custom commands concurrently in-process before the render - #630

BLUF

• Priority: medium. This removes one helper runtime per custom-command widget from every render.
• What: all custom commands now run concurrently in a prefetch phase, using async spawn in the main process. This replaces running them one after another during the render, where each run did spawnSync(process.execPath, ['-e', capture]) and then sh -c command.
• Protection kept: in-process and fallback runs share one capture function, so both keep the same deadline, process-group SIGKILL, 1 MiB cap, and pipe destroy on delivery. A background child that keeps stdout open still cannot hang the render or keep the process alive.
• Measured (node, 20 interleaved passes, host heavily loaded): CPU -11% / -27% / -34% and wall -14% / -33% / -40% for 1 / 3 / 5 commands. With 3 commands, execve calls go from 10 to 7.
• Output unchanged on the benchmarked configs. The default TTL is not changed (see the suggestion below).

Details

• custom-command-capture.ts: captureCustomCommand now takes a deliver(result) callback and no longer calls process.stdout.write and process.exit itself. The -e helper passes a callback that does exactly that, so the synchronous path behaves as before. The function is still self-contained for the release bundle.
• custom-command.ts:
  • New runCustomCommandAsync, which uses the same memory and persistent cache logic, now factored into readCachedResult/storeResult. It never rejects, and a timeoutMs + 1000 backstop mirrors the old spawnSync timeout.
  • New prefetchCustomCommandsIfNeeded(lines, context), which runs every custom-command widget's request at once. Identical requests (same command, timeout, TTL and payload) run once per render and share the result.
  • runCustomCommand(request, prefetched?) returns the prefetched result when there is one. Otherwise it falls back to the existing synchronous helper path.
• ccstatusline.ts: getTerminalWidth moves above the Promise.all, because the piped payload and the cache key depend on it. The prefetch is added next to the transcript, usage and service-status prefetches, and its results go on RenderContext.customCommandResults.
• CustomCommand.tsx: a one-line change that passes context.customCommandResults to runCustomCommand. The request-building and maxWidth code is untouched.
• Semantics:
  • A command that exits while a background child still holds stdout still returns its output at the deadline. This is the drain behaviour pinned by the existing background test.
  • One side effect under load: the helper's startup counted against the timeoutMs + 1000 backstop. On a loaded host the old path therefore sometimes rendered [Timeout] for a sleep 0.05 command, and the new path does not.

Suggestion (not in this PR)

customCommandCacheTtlSeconds still defaults to 0, so every repaint runs every command. A small default, like the 5 s used for gitCacheTtlSeconds, would remove most of the remaining cost. That is a UX decision, so it is left to you.

Measurements

Setup: bench2 round-robin fork/exec with CPU = user+sys including reaped children, node 24, all arms interleaved in one run. Config: model + N × sleep 0.05; echo xN custom commands at TTL 0, with a payload that has no transcript. ccbg = one normal command + (sleep 2 & ) ; echo early with timeout: 300. 20 passes. load1 during the run: min 51.2 / median 60.3 / max 69.8 on 6 cores. The host was heavily loaded, so absolute times are inflated; compare the ratios.

• For 3 and 5 commands, the patched p90 is below the base median.
• execve counts (strace): with 3 commands, 10 before (4 node, 3 sh, 3 sleep) and 7 after (1 node). With 5 commands, 11 after.
• Output: stdout of the base and patched dist was hashed over repeated runs of each config. The patched output was the same on every run and matched base's majority output. Base sometimes showed [Timeout] under load, as noted above.

Checks

• bun run lint (tsc + eslint): clean.
• bun run build: OK.
• bun test:
  • New tests:
    • The out-of-process capture suite now runs every mode through both the sync and async APIs under bun and node.
    • New prefetch cases: concurrency (3 × sleep 0.5 in under 1.4 s), dedupe of identical requests, and a background job holding stdout. For that last case the result comes at the deadline, the probe process does not stay alive afterwards (checked via a lingered exit metric), and the background job survives.
    • Widget tests check that a prefetched result is used without spawning, and that a miss falls back to the synchronous path.
  • Custom-command and widget unit tests: 50/50 pass.
  • Flakes, stated honestly: load1 was about 55-65 on 6 cores during these runs.
    • The timing-sensitive process tests (200-1000 ms deadlines that include a runtime cold start) fail often here, on both paths. Unmodified main failed 10 of its 24 existing process tests in the same conditions. On this branch the unchanged sync path failed 15/24, the new async path 11/24, and prefetch 2/6. Every failure was a [Timeout] instead of the expected result, or a timing bound missed.
    • A run with every deadline and sleep scaled up ×5-10 behaved the same on both paths. A manual check with 3-4 s deadlines showed the process tree killed on timeout, the background output returned, and no lingering process, on both paths under node and bun.
    • Also failing on this host, in areas this PR does not touch: the known fetchUsageData error handling 5 s timeouts and several TUI menu tests.
• Overlap with our other PRs:
  • [low] fix(custom-command): truncate maxWidth output by display width, not string length #626 (CustomCommand.tsx maxWidth) merges cleanly with this branch; checked with git merge-tree. This PR changes only the runCustomCommand(...) call line in that file.
  • feat: total session tokens including sub-agents #441 also touches ccstatusline.ts and RenderContext.ts, and also merges cleanly.

🤖 Generated with Claude Code