fix(portable): route receipt failures to valid recovery

[prekshivyas]

Summary

Portable readiness failures without a recorded socket path no longer send users to repair a nonexistent endpoint. Invalid and legacy receipts now route to portable onboarding, current-user authority mismatches route to the recorded user or current-user onboarding, and socket service diagnostics appear only when a validated socket path is available.

Related Issue

Follow-up to #9186 for #9070.

Changes

• Record the required no-socket recovery in the portable readiness result so doctor and gateway consumers do not infer endpoint repair from error text.
• Route invalid and legacy receipts to nemoclaw onboard --experimental-profile portable.
• Route a current-user authority mismatch to the recorded user or onboarding as the current user.
• Keep socket service and API diagnostics conditional on a reported socket path.
• Add doctor and gateway regression tests for invalid and legacy receipt recovery.
• Update troubleshooting guidance to match the runtime recovery contract.

Type of Change

• 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)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Independent Codex Desktop review passed all nine security categories for commit under review 5c6a000f5e6d036845cfbebee2a7fd4d0000c36d. Invalid, legacy, and current-user mismatch paths fail closed without fabricated endpoint repair. The doctor and gateway tests cover each recovery branch.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/reference/troubleshooting.mdx routes unsafe, invalid, and legacy receipts to portable onboarding; routes current-user mismatches to the recorded user or current-user onboarding; and limits socket service and API inspection to failures that report a socket path. Doctor and gateway guidance match these paths. The merge preserves the reviewed patch and adds current-base Google Gemini documentation and provider-model tests outside the nine PR-owned files. Focused recovery tests passed 59/59. npm run docs completed with 0 errors and 2 existing warnings. git diff --check passed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project cli --project integration src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts src/lib/onboard/experimental/portable-runtime-readiness.test.ts test/gateway-failure-classifier.test.ts: 59 passed
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Prekshi Vyas prekshiv@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved Portable Podman troubleshooting for missing sockets, legacy receipts, and user-authority mismatches.
  • Recovery guidance now directs users to portable onboarding or the appropriate recorded/current user path.
  • Added clearer instructions for inspecting Podman units and validating the reported socket.
  • Prevented inappropriate endpoint-repair guidance and credential exposure in affected scenarios.

• Tests

  • Expanded coverage for portable onboarding failures, legacy receipts, socket handling, and authority mismatches.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4ee34acd-7d81-48d2-8460-5cfe40784b31

📥 Commits

Reviewing files that changed from the base of the PR and between f58a07f and fd19514.

📒 Files selected for processing (9)

• docs/reference/troubleshooting.mdx
• src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts
• src/lib/actions/sandbox/doctor-lifecycle-registration.ts
• src/lib/actions/sandbox/gateway-failure-classifier.ts
• src/lib/onboard/experimental/portable-demo-lifecycle.ts
• src/lib/onboard/experimental/portable-runtime-readiness.test.ts
• src/lib/onboard/experimental/portable-runtime-readiness.ts
• src/lib/onboard/experimental/portable-runtime-receipt-readiness.ts
• test/gateway-failure-classifier.test.ts

---

📝 Walkthrough

Walkthrough

Portable Podman readiness failures now report recovery classifications. Doctor and gateway diagnostics use these classifications to distinguish onboarding, current-user authority, and recorded-socket recovery guidance. Tests and troubleshooting documentation cover the updated behavior.

Changes

Portable Podman recovery

Layer / File(s)	Summary
Readiness recovery classification src/lib/onboard/experimental/portable-runtime-readiness.ts, src/lib/onboard/experimental/portable-runtime-receipt-readiness.ts, src/lib/onboard/experimental/portable-demo-lifecycle.ts, src/lib/onboard/experimental/portable-runtime-readiness.test.ts	Readiness failures now classify portable onboarding and current-user authority recovery modes. Invalid, legacy, and authority-mismatch states return the corresponding classification.
Recovery guidance routing src/lib/actions/sandbox/doctor-lifecycle-registration.ts, src/lib/actions/sandbox/gateway-failure-classifier.ts	Doctor and gateway diagnostics use recovery classifications to select onboarding or current-user authority guidance. Recorded-socket diagnostics remain separate.
Recovery guidance validation src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts, test/gateway-failure-classifier.test.ts, docs/reference/troubleshooting.mdx	Tests verify onboarding guidance, authority guidance, omitted endpoint-repair instructions, and credential protection. Troubleshooting guidance distinguishes failures with and without recorded socket paths.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to fd195

The change routes portable receipt failures to valid recovery paths and limits diagnostics to validated socket endpoints; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• NVIDIA/NemoClaw#9176: Both changes cover portable Podman lifecycle readiness and authority handling.
• NVIDIA/NemoClaw#9186: Both changes modify portable Podman readiness classification and recovery guidance.

Suggested labels: area: onboarding, area: sandbox, platform: container, bug-fix

Suggested reviewers: cv, apurvvkumaria

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: routing portable receipt failures to valid recovery actions.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-portable-recovery-contract

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 5c6a000 in the codex/fix-portable-r... branch remains at 96%, unchanged from commit a8ceeb1 in the main branch.

---

_{Updated August 15, 2026 04:23 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-9194.docs.buildwithfern.com/nemoclaw

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

4 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• recovery at src/lib/onboard/experimental/portable-runtime-readiness.ts:69: selected only by the second-opinion lane as justified.
• socket authority at src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts:49: selected only by the second-opinion lane as established.
• current-user-authority at src/lib/onboard/experimental/portable-runtime-readiness.ts:69: selected only by the second-opinion lane as define.
• portable-onboarding at src/lib/onboard/experimental/portable-runtime-readiness.ts:69: selected only by the second-opinion lane as justified.

1 additional E2E selection from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• security-posture: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — portable onboarding at src/lib/onboard/experimental/portable-runtime-readiness.ts:69: Use portable onboarding when the portable profile is required.
• justified — current-user authority at src/lib/onboard/experimental/portable-runtime-readiness.ts:69: Keep the modifier because it identifies the user-ownership condition that selects recovery.
• justified — recorded socket path at docs/reference/troubleshooting.mdx:3356: Keep the modifier because diagnostics must use only the reported receipt-owned path.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: onboard-repair, onboard-resume, cloud-onboard
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

1 optional E2E recommendation

• managed-image-protected-runtime

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[prekshivyas]

Reviewed exact head 5c6a000. No findings. Socketless invalid/legacy receipts route to portable onboarding, current-user authority mismatches route to the owning/current user, and endpoint repair is only suggested when a receipt-owned socket path exists. The only post-review delta is current main. Local exact-head validation: policy-boundary build passed, focused recovery suites passed 59/59, and diff check passed. GitHub does not permit me to approve my own PR.

[cv]

Replacement wording for the prior review receipt; this wording supersedes it.

Reviewed commit 5c6a000f5e6d036845cfbebee2a7fd4d0000c36d. No findings. Socketless invalid or legacy receipts route to portable onboarding, current-user authority mismatches route to the owning or current user, and endpoint repair is suggested only when a receipt-owned socket path exists. The only later delta is the merge from current main. Local validation for the reviewed commit: the policy-boundary build passed, the focused recovery suites passed 59/59, and the diff check passed. GitHub does not permit the author to approve their own PR.

[cv]

Approved at commit 5c6a000. Independent review passed, all feedback is resolved, and the repeated shard timeout is isolated to unchanged repository code already known to need extra time under load. Merge remains gated on the active retry and final image check.