fix(sandbox): unpause a paused container during docker-driver recovery

[latenighthackathon]

Summary

Docker-driver recovery previously reported a paused labeled sandbox as recovered without resuming its container. Recovery now runs docker unpause before reporting success and reports a failed unpause instead of a false recovery.

Related Issue

Closes #7640

Changes

• Detect Up ... (Paused) in the existing running-original recovery branch.
• Use the existing Docker adapter to unpause the labeled original container and report unpaused-original.
• Return recovered: false with the Docker exit status when unpause fails.
• Cover successful and failed unpause behavior without changing the existing running and stopped paths.

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: Existing sandbox recovery documentation already describes paused containers and docker unpause; this fix adds no command, flag, configuration, or documentation contract.
• 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: Codex Desktop security specialist review at PR SHA c072a3978 passed all nine repository security categories with no findings. This is agent review, not human review.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Product scope: Approved independently at PR SHA c072a3978 and base SHA 0b722a4. This fixes the existing supported Docker-driver recovery contract described in #7640 and creates no integration, recipe, image, third-party stack, or other product surface.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: src/lib/onboard/docker-driver-sandbox-recovery.ts and its test are the only changed files. Existing docs already describe paused containers and docker unpause. Changed comments and test titles comply with WRITING.md.
• Agent: Codex Desktop documentation writer subagent

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 check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project cli src/lib/onboard/docker-driver-sandbox-recovery.test.ts src/lib/actions/sandbox/start.test.ts src/lib/actions/sandbox/gateway-state-drift.test.ts src/lib/actions/sandbox/rebuild-gateway-drift.test.ts passed 4 files and 46 tests at PR SHA c072a3978.
• 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)

Exact local review state: PR SHA c072a39788586e71070376e2c22915332bccb9a3; base SHA 0b722a4822bb450e6676786bb81fc2a5c2fc5668. Diff-aware pre-commit, commit-message, and pre-push stages passed against this exact pair.

---

Signed-off-by: latenighthackathon latenighthackathon@users.noreply.github.com

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit c072a39 in the fix/recover-unpause-... branch remains at 96%, unchanged from commit 0b722a4 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit c072a39 in the fix/recover-unpause-... branch remains at 81%, unchanged from commit 0b722a4 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 0b722a4	fix/recover-unpause-... c072a39	+/-
src/lib/onboard...der-metadata.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/onboard...box-recovery.ts	86%	89%	+3%

---

_{Updated July 27, 2026 22:49 UTC}

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Paused sandbox recovery

Layer / File(s)	Summary
Recovery contract and paused-container detection src/lib/onboard/docker-driver-sandbox-recovery.ts	Adds the unpaused-original recovery mode, optional dockerUnpause dependency, lazy adapter fallback, and paused-status classification.
Paused original unpause flow src/lib/onboard/docker-driver-sandbox-recovery.ts, src/lib/onboard/docker-driver-sandbox-recovery.test.ts	Unpauses paused original containers, reports unpause failures, preserves non-paused behavior, and tests both outcomes.

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

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

Suggested reviewers: cv, brandonpelfrey

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address the paused-container recovery bug and failure reporting described in #7640.
Out of Scope Changes check	✅ Passed	The diff stays focused on Docker-driver recovery logic and its tests, with no clear unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: recovering paused Docker containers by unpausing them.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/recover-unpause-paused-sandbox

---

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

[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 · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, the same number of warnings, 1 more suggestion.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: onboard-repair, onboard-resume, cloud-onboard

Workflow run details

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

[senthilr-nv]

Reviewed Files changed for PR SHA c072a39 against base SHA 0b722a4. The diff is limited to resuming paused Docker-driver sandbox containers and its success/failure tests. I approve this exact head.