Summary

On Linux ARM64 (aarch64), OpenShell's sandbox create --from <Dockerfile> path can fail while streaming the built image tar into the gateway container with a misleading Docker 404 (failed to upload image tar into container / the container does not exist for openshell-cluster-nemoclaw). The gateway is actually healthy — a same-size archive PUT succeeds directly — so the 404 is a symptom of the large-tar upload path, not a missing gateway. NemoClaw previously classified this as unknown and printed the generic onboard --resume hint, which just re-runs the same deterministically failing path. This PR classifies the failure and emits a precise, leak-safe local-registry / image-ref workaround that preserves the built image tag so the operator can recreate the sandbox without rebuilding.

Related Issue

Relates to #3266 (mitigation, not a closing fix). The root cause is OpenShell's image-tar upload path on ARM64; NemoClaw cannot make that upload succeed from its side. This change turns the misleading, unactionable failure into a classified error with an accurate workaround (the gateway is healthy; push the built image to a local registry and recreate from the image ref). Onboarding still does not complete automatically on the affected ARM64 path, so no closing keyword is used.

Changes

• classifySandboxCreateFailure: new image_upload_container_missing kind detecting the upload-tar phrase, or the combined status code 404 + container-missing + openshell-cluster-nemoclaw shape.
• New pure planSandboxCreateRecovery(failure, {platform, arch}) that decides the Linux-ARM64-targeted workaround — unit-testable without console spying. Other platforms get the generic note.
• printSandboxCreateRecoveryHints now emits the workaround: start a local registry, push the built image with the matching builder (docker push or buildah push — the ARM64 build path uses buildah, where a docker-only push fails with No such image), then recreate from the registry ref.
• The recreate step reconstructs NemoClaw's own create command (via the existing createArgs) with only --from swapped to the registry ref, so the configured provider/GPU/resource flags are preserved and the recreated sandbox is not misconfigured. The temporary --policy path and the -- env … nemoclaw-start runtime wrapper are shown as placeholders rather than dumped verbatim (the temp policy is cleaned up; the env wrapper carries host-specific values).
• onboard.ts: net-zero single-line edit passing the existing createArgs to the hint.
• Unit tests for the classifier, the recovery decision, the builder-agnostic hints, the built-image-ref extraction, and the create-command reconstruction. Manual aarch64 E2E note added alongside the tests.

Normal x86_64 happy paths are untouched: this path runs only after the OpenShell upload failure is classified.

Type of Change

• Code change (feature, bug fix, or refactor)

Verification

• Targeted tests pass: vitest run --project cli src/lib/validation.test.ts src/lib/build-context.test.ts (76 passed)
• npm run typecheck:cli passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• codex review --uncommitted clean (no actionable findings)

Reproduction: this host is x86_64 (uname -m → x86_64), so the ARM64 hardware bug cannot be reproduced directly. The classifier/decision path was reproduced through the built CLI (dist/) with a controlled OpenShell output fixture: before the fix it classified as unknown and printed only onboard --resume; after the fix it classifies as image_upload_container_missing and prints the workaround. npm test was run; the 39 failing tests are pre-existing environment-only subprocess-spawn timeouts (confirmed identical on a stashed baseline) and are unrelated to this change.

Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Enhanced error recovery guidance when sandbox creation fails due to image upload issues.
  • Added platform-specific recovery recommendations for ARM64 Linux systems.
  • Improved recovery instructions with detailed step-by-step guidance and alternative deployment methods.