Problem

There is no shared timeout architecture for child-process execution. The codebase uses 5 different ad-hoc approaches, and the most critical execution layer — openshell.ts — has zero timeout support, making every openshell CLI call unbounded.

This was the root cause of the E2E hang introduced by PR #2398 (reverted in #2471): the dashboard recovery chain wired runOpenshell/captureOpenshell calls as deps, but those calls have no timeout. When the sandbox was in a bad state, openshell sandbox download and openshell forward list hung forever.

Current State: 5 Timeout Approaches, No Shared Pattern

Silent Bug Already Shipping

nemoclaw connect passes timeout: remainingMs() to captureOpenshell, but the wrapper in nemoclaw.ts does not forward it, and captureOpenshellCommand in openshell.ts does not accept it:

// nemoclaw.ts — timeout silently dropped
captureOpenshell(["sandbox", "list"], {
  ignoreError: true,
  timeout: remainingMs(),  // ← dead code
}).output;

// nemoclaw.ts wrapper — does not forward timeout
function captureOpenshell(args, opts = {}) {
  return captureOpenshellCommand(getOpenshellBinary(), args, {
    cwd: ROOT,
    env: opts.env,
    ignoreError: opts.ignoreError,  // timeout not here
    errorLine: console.error,
    exit: (code) => process.exit(code),
  });
}

TypeScript does not catch this because nemoclaw.ts uses untyped opts = {}.

Proposed Solution

1. Add timeout to openshell.ts interfaces — both RunOpenshellOptions and CaptureOpenshellOptions should accept timeout?: number and forward it to spawnSync.

2. Define named timeout constants — follow the pattern Aaron established in cluster-image-patch.ts:

   • OPENSHELL_SANDBOX_EXEC_TIMEOUT_MS (e.g. 15s — matches existing SSH timeout)
   • OPENSHELL_FORWARD_LIST_TIMEOUT_MS (e.g. 10s)
   • OPENSHELL_SANDBOX_DOWNLOAD_TIMEOUT_MS (e.g. 30s)
   • OPENSHELL_DEFAULT_TIMEOUT_MS (e.g. 30s fallback)

3. Forward timeout in nemoclaw.ts wrappers — runOpenshell and captureOpenshell must pass opts.timeout through.

4. Fix the silent connect bug — the timeout: remainingMs() in the connect readiness loop should actually work once the plumbing is in place.

5. Audit all runOpenshell/captureOpenshell call sites — decide appropriate timeout for each, default to OPENSHELL_DEFAULT_TIMEOUT_MS for any that do not specify one.

Context

• refactor(cli): extract dashboard delivery chain into contract/health/recover modules #2398 — dashboard refactor that hung due to unbounded openshell calls (reverted in fix(cli): restore pre-#2398 gateway recovery (fixes E2E hangs) #2471)
• refactor(arch): introduce Dashboard Delivery Contract — single source of truth for dashboard reachability #2390 — dashboard delivery chain consolidation (blocked until timeout safety exists)
• [NemoClaw][macOS][Onboard] nemoclaw onboard does not auto-restart Docker (Colima) when daemon is stopped — hangs indefinitely at gateway health #2347 — macOS onboard hangs indefinitely at gateway health (same class of bug)
• cluster-image-patch.ts (fix(onboard): auto-patch cluster image for Docker 26+ overlayfs nested mount break #2487) — best current example of disciplined timeout injection