…3456) (NVIDIA#3520)

> **Draft for visibility.** Issue-autopilot Stages 4-5 of NVIDIA#3456. Will
mark ready once batch self-review + CI complete.

## Summary

Closes the two remaining output threads in NVIDIA#3456 after the core
dead-loop fix already landed on `main` (via NVIDIA#3459, NVIDIA#3434, NVIDIA#3483). Full
sub-bug mapping in the [NVIDIA#3456 status
comment](NVIDIA#3456 (comment)).

- **Sub-bug #3** — `nemoclaw <name> destroy --yes` recovery hint
replaced with a registry-aware helper.
- **Sub-bug NVIDIA#4** — `Destroyed gateway 'nemoclaw' skipped`
self-contradictory wording replaced with `Gateway 'nemoclaw' already
removed or unreachable`.

## Acceptance criteria mapping

| Sub-bug | Resolution | Evidence |
|---|---|---|
| #1 dead loop | Already fixed on main (NVIDIA#3459) | out of scope |
| #2 firewall diagnostic | Already fixed on main (NVIDIA#3459) | out of scope
|
| **#3** literal `<name>` placeholder | **This PR** |
`src/lib/onboard/gpu-recovery.ts` + `onboard.ts:10387-10405` |
| **NVIDIA#4** misleading "skipped" wording | **This PR** |
`src/lib/actions/uninstall/run-plan.ts:210-228, 407-414` |
| NVIDIA#5 uninstall residuals | Already fixed on main (NVIDIA#3483) | out of scope
|

## Behavior matrix

`gpuPassthroughRecoveryLines(names)`:

| Input | Suggestion |
|---|---|
| `null` / `[]` | `nemoclaw uninstall && nemoclaw onboard --gpu` |
| one sandbox | `nemoclaw <name> destroy --yes --cleanup-gateway &&
nemoclaw onboard --gpu` |
| many sandboxes | each `destroy --yes`, only the last gets
`--cleanup-gateway` |

## Test plan

```
npm run typecheck:cli
npx vitest run src/lib/onboard/gpu-recovery.test.ts src/lib/actions/uninstall/run-plan.test.ts
```

22 tests pass (6 new + 16 existing).

## Notes for reviewers

- This is the work [NVIDIA#3464
attempted](NVIDIA#3464); that PR was
closed without merging after CodeRabbit asked for the `<name>`
placeholder to be forbidden in tests via negative assertion. This PR
adopts that refinement.
- `runOptional` extension is backwards-compatible — existing callers
without `onSkip` get the original wording.

Closes NVIDIA#3456 once merged.

---------

Signed-off-by: Charan Jagwani <charjags100@gmail.com>
Co-authored-by: Charan Jagwani <charjags100@gmail.com>
Co-authored-by: Carlos Villela <cvillela@nvidia.com>

…#3271) (NVIDIA#4020)

## Summary
Adds `classifyGatewayFailure` and wires it into `showSandboxStatus`'s
final fallback branch so `nemoclaw <name> status` prints a clearly-named
failure layer header before the existing actionable hints. Closes the UX
gap split out of NVIDIA#2666 / NVIDIA#3270.

## Related Issue
Fixes NVIDIA#3271. Supersedes NVIDIA#3309 (kagura-agent), which implemented the same
feature but missed the `docker ps -a` existence check that AC #2
explicitly requires (CodeRabbit major finding on that PR).

## Changes
- `src/lib/actions/sandbox/gateway-failure-classifier.ts`: new module
exposing `classifyGatewayFailure(sandboxName, { runners? })` with
injectable runners (`dockerInfo`, `dockerIsRunning`, `dockerExists`,
`portProbe`) plus `getLayerHeader(layer)`.
- Layers: `docker_unreachable`, `container_missing` (new, distinct from
`container_exited` per AC #2), `container_exited_port_conflict`,
`container_exited`, `gateway_unreachable`.
- Default runners go through `src/lib/adapters/docker` (`dockerInfo`,
`dockerCapture`) to satisfy the docker-abstraction guard.
- `src/lib/actions/sandbox/status.ts`: calls the classifier and prints
the layer header before `printGatewayLifecycleHint` in the final
fallback branch.

## Type of Change
- [x] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Verification
- [x] Unit tests in isolation: `npx vitest run
test/gateway-failure-classifier.test.ts` → 8/8 pass (per-layer,
including `container_missing` and short-circuit behavior).
- [x] Subprocess test in isolation: `npx vitest run
test/repro-2666-silent-list-status.test.ts` → 7/7 pass, including the
new "`nemoclaw <name> status` prints the
`container_exited_port_conflict` layer header (NVIDIA#3271)" test which spawns
the real CLI against a fake docker stack + a real TCP listener holding
the gateway port.
- [x] `test/docker-abstraction-guard.test.ts` passes — no direct
`execSync("docker …")` outside `src/lib/adapters/docker`.
- [x] Tests added or updated for new or changed behavior
- [x] No secrets, API keys, or credentials committed
- [ ] Docs updated for user-facing behavior changes (status output is a
UX polish, not a contract change)
- [ ] `make docs` builds without warnings (no doc changes)

⚠️ Committed with `--no-verify` (user-authorized): the pre-commit `Test
(CLI)` hook (full vitest with v8 coverage) hits unrelated timeout flakes
on this macOS workstation (Defender + Spotlight + iMessage indexer
contention). The new tests in this PR pass cleanly in isolation. CI on
Linux runners is the authoritative gate.

## Definition of Done (from NVIDIA#3271)
- [x] `status` prints a clearly-named layer header in each classified
state (5 layers, expanded from the original 4 to split
`container_missing` from `container_exited`).
- [x] Classifier has unit tests per layer.
- [x] Repro subprocess test extended to assert the named layer for the
container-stopped + foreign-port-holder scenario.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added smarter gateway failure diagnostics that identify unreachable
Docker, missing or exited gateway containers, and port conflicts;
includes clear failure headers.

* **Bug Fixes**
* Status command now shows the appropriate failure header before
guidance and exits with a non-zero status when verification fails.

* **Tests**
* Added unit and end-to-end tests covering diagnostics, header ordering,
and port-conflict scenarios.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/4020?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Charan Jagwani <cjagwani@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Aaron Erickson <aerickson@nvidia.com>