feat(onboard): declare runtime host mount support

[ericksoa]

Summary

Declare read-only host-mount support through the selected runtime-provider contract and reject unsupported providers or host platforms before onboarding mutates durable session state. Docker remains supported on Linux and WSL, while Kubernetes and OpenShell MXC fail closed with provider-specific reasons. This is a stacked follow-up to #8280.

Related Issue

Part of #8343. Depends on #8280.

Changes

• Require every runtime-provider bundle to declare read-only host-mount support or an explicit unsupported reason, including qualified host platforms for supported providers.
• Resolve and enforce that capability for CLI requests and persisted resume state before session mutation.
• Document the current Docker, Kubernetes, and MXC support matrix plus the qualification checklist for future provider implementations.
• Keep the abstraction because onboarding has multiple runtime providers and a direct Docker-only platform check cannot protect persisted mounts when runtime selection changes. Runtime-provider contract tests protect registration and the support matrix; command and session-bootstrap tests protect requested and persisted fail-closed 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:
• 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: Maintainer security-code review completed for input validation, runtime trust boundaries, filesystem and TOCTOU behavior, injection, authorization, secrets and logging, network exposure, state ordering, and dependencies; no findings.
• 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/manage-sandboxes/workspace-files.mdx; independent final review found no findings; npm run docs 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 — 137 tests passed across the runtime-provider, host-mount, command, session-bootstrap, checkpoint-resume, and Station Express session suites.
• 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: Aaron Erickson aerickson@nvidia.com

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f6972709-cf1d-44c2-91d8-3efb78d34b9f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{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 23d5c6e in the feat/runtime-host-mo... branch remains at 96%, unchanged from commit cbabb66 in the feat/read-only-host-... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 23d5c6e in the feat/runtime-host-mo... branch is 81%. The coverage in commit cbabb66 in the feat/read-only-host-... branch is 82%.

Show a code coverage summary of the most impacted files.

File	feat/read-only-host-... cbabb66	feat/runtime-host-mo... 23d5c6e	+/-
src/lib/actions...post-restore.ts	83%	50%	-33%
src/lib/inferen...pter-forward.ts	98%	92%	-6%
src/lib/sandbox/config.ts	76%	74%	-2%
src/lib/onboard.ts	31%	30%	-1%
src/lib/inference/vllm.ts	89%	89%	0%
src/lib/shields/index.ts	73%	74%	+1%
src/lib/onboard...ization-deps.ts	0%	83%	+83%
src/lib/state/r...y/host-mount.ts	0%	88%	+88%
src/lib/onboard...e-port-reuse.ts	0%	100%	+100%
src/lib/onboard...-mount/index.ts	0%	100%	+100%

---

_{Updated August 05, 2026 15:33 UTC}

[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.

2 terminology differences from the second opinion

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

• host-directory sharing contract at src/lib/onboard/runtime-provider/mxc.ts:109: primary classified it as define; the second opinion classified it as justified.
• Host Platform at docs/manage-sandboxes/workspace-files.mdx:17: selected only by the second-opinion lane as established.

2 additional E2E selections from the second opinion

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

• state-backup-restore: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• ubuntu-repo-docker-post-reboot-recovery: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

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

• established — runtime provider at docs/manage-sandboxes/workspace-files.mdx:17: Keep `runtime provider` for this provider-bundle concept.
• justified — qualified host platform at docs/manage-sandboxes/workspace-files.mdx:38: Keep `qualified host platform`; the modifier identifies the enforced capability distinction.
• define — host-directory sharing contract at src/lib/onboard/runtime-provider/mxc.ts:109: Define the term at its first explanatory user-facing use if it is exposed outside this provider-specific diagnostic.

E2E guidance

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

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

1 optional E2E recommendation

• rebuild-openclaw

Workflow run details

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