feat(onboard): add transactional Docker bootstrap adapter

[ericksoa]

Summary

Adds the second narrowed PR3.10B review unit: the dormant transactional Docker managed-bootstrap adapter and shared-state cutover. It builds on #8037's journal/spec primitives and remains unregistered and unsupported by every production provider.

Preparation captures immutable original and replacement authority before destructive activation. Cleanup requires an exact validated Ready receipt; mutable-name reuse is retained and reported instead of deleted unsafely. Every immutable Node helper receives a scrubbed environment, and rollback is delegated to the immutable image's canonical receipt parser with only the three capabilities required to restore ownership, access owner-restricted state, and restore modes.

Related Issue

Part of #7744

Changes

• Prepare and inspect a stopped Docker replacement before cutover.
• Persist exact sandbox, container, image, launch-spec, bootstrap, and shared-state authority.
• Separate prepare, activate, await, commit, rollback, and incomplete-create cleanup phases.
• Preserve Docker GPU device/runtime/CDI evidence and snapshot compatibility.
• Bind cleanup to a Ready receipt whose sandbox name, durable sandbox ID, and driver match current inspection.
• Reject the complete root-process injection denylist before replacement creation.
• Run immutable Node helpers through /usr/bin/env -i; clear loader variables before the scrubber and clear NODE_OPTIONS/NODE_PATH at the pre-entrypoint boundary as defense in depth.
• Keep rollback receipts opaque on the host and validate them canonically inside the immutable image from a read-only mount.
• Drop all rollback-helper capabilities, then add only CHOWN, DAC_OVERRIDE, and FOWNER for exact restoration.
• Add regressions for hostile launch environments, planted temp targets, malformed rollback receipts, same-name identity reuse, and unsafe cleanup refusal.
• Keep production Docker bootstrap explicitly unsupported and prove no provider registration or activation import changes.

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 internal architecture and dormancy claims
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed — two independent exact-diff reviews found no privilege widening, parser divergence, or activation leak
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer reviewed the completed changes
• Result: docs-updated
• Evidence: Candidate 875eab3f25f97134ed3347c51f8d7cc3ccc231a8 and graft eb8ee81cc157ea7c12e311ab4b53e87930e3ae17 share exact tree 7ef10c62ab2f10773f8f0372dd78d41329d9f1ac. Final qualification child 00154381829ea31e214bc41955384755a39fe280 changes only tests, so the reviewed documentation blobs are unchanged. Review confirmed accurate pre-/post-cutover rollback wording, npm-package versus runtime-image scope, activation/provider import scope, and dormant user-visible lifecycle claims. markdownlint-cli2, the 8/8 source-shape contract, and git diff --check pass.
• Agent: Codex Desktop

DGX Station Hardware Evidence

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

Verification

• Exact base/head: 8c542b214f15561f71b262523d80a61ed4a5e9c7 / 00154381829ea31e214bc41955384755a39fe280 (22 files, +4,868/-36).
• Review budget: 21 paths, +4,867/-35.
• Stable patch ID: 07b3d062e2a26a8c9993f70e87ef1f5c7c0ca9db.
• Binary diff SHA-256: ac4098a115e0bb14824ee7c49e211da15d268babc305a72be21b2c869b416f1d.
• Clean reconstruction: signed+DCO commit 875eab3f25f97134ed3347c51f8d7cc3ccc231a8, direct child of live main 8c542b214f15561f71b262523d80a61ed4a5e9c7.
• Append-only graft: signed+DCO commit eb8ee81cc157ea7c12e311ab4b53e87930e3ae17, first parent prior live head 206228343ae124563be7d13b4dd620e9628f9db0, second parent the clean reconstruction, exact tree 7ef10c62ab2f10773f8f0372dd78d41329d9f1ac. Signed+DCO qualification child 00154381829ea31e214bc41955384755a39fe280 is a normal fast-forward with exact tree 7c3d307d40156375bf26d8b977a93d6149013650. No remote history was rewritten.
• Durable refs: backup/podman-stack/pr8128-advisor-b23404994, backup/podman-stack/pr8128-final-eb8ee81cc, backup/podman-stack/pr8128-final-001543818, and hold/podman-stack/pr8040-base-001543818.
• Exact current-main changed-file tests passed 134/134. The complete managed-bootstrap source reconstruction passed 149/149; security-focused follow-up passed 20/20; source-shape dormancy passed 8/8. Final qualification follow-up passed package-contract 8/8, temp-file 6/6, both builds, Biome, diff checks, and hooks.
• CLI build, root/CLI/plugin typechecks, Biome, markdownlint, diff check, test-size budget, test-conditional scan, normal commit hooks, and normal pre-push hooks passed.
• Two independent security reviews found no blocker in the exact advisor-fix diff. The capability set is unchanged, /usr/bin/env -i remains the trusted Node boundary, immutable receipt validation remains image-owned, and the new tests fail closed before restoration or symlink following.
• Prior exact head 206228343ae124563be7d13b4dd620e9628f9db0 passed ordinary CI, both advisors, CodeRabbit with zero unresolved threads, CodeQL, and protected E2E child 30829525494 for rebuild-openclaw, onboard-repair, onboard-resume, and state-backup-restore. Final exact head 00154381829ea31e214bc41955384755a39fe280 must independently pass its automatically approved current-head gates, including cloud-onboard.
• Every new commit is SSH-signed and carries Aaron's DCO trailer.
• Production provider construction still returns unsupported bootstrap/recovery surfaces; no selectable runtime or activation is added.

Risk Plan

• Primary risk: destructive cutover or cleanup against stale/reused identity, unsafe inherited process state, or loss of GPU/spec/shared-state authority across replacement.
• Containment: exact immutable handles, validated Ready receipts, process-injection rejection, clean helper environments, immutable image-owned receipt validation, validated clone overrides, provider-owned journal receipts, and preparation-before-activation. Ambiguous cleanup fails closed and retains the workload.
• Regression risk: dormant adapter dependencies could alter existing snapshot or GPU clone behavior. Focused compatibility tests and explicit unsupported-provider/source-shape assertions remain green.
• Rollback: the adapter remains unregistered and independently revertible.

Stack

• Base: merged PR3.10B1 feat(onboard): add dormant Docker bootstrap primitives #8037 at main commit b30781c399d3456e6e071bae098c28c6000d80f9.
• This slice: PR3.10B2 feat(onboard): add transactional Docker bootstrap adapter #8128, exact head 00154381829ea31e214bc41955384755a39fe280.
• Next: PR3.11 feat(onboard): bind managed create to runtime providers #8040 integrates provider/create and GPU-create flows without activating buildless support.
• feat(onboard): bind managed create to runtime providers #8040's next exact handoff is protected at hold/podman-stack/pr8040-base-001543818 before its append-only recascade.
• Buildless and Podman support remain disabled until all-agent, multiarch, GPU/local-inference, recovery, installer, and protected-E2E gates in [Epic] Support native Podman with buildless managed onboarding #7744 pass.

Signed-off-by: Aaron Erickson aerickson@nvidia.com

Summary by CodeRabbit

• New Features

  • Added Docker-based managed startup for workload creation, replacement, activation, rollback, recovery, and cleanup.
  • Added durable coordination for safe replacement commits and interrupted operations.
  • Added reliable sandbox identity detection from formatted command output.
  • Added support for preserving container names, entrypoints, and commands during replacements.

• Bug Fixes

  • Improved validation, cleanup, state recovery, and process-environment safety during failed or interrupted replacements.

• Documentation

  • Expanded managed startup documentation with Docker workflows, recovery behavior, and operational limitations.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/managed-bootstrap/docker-test-fixture.ts`:
- Around line 352-356: Wrap the body of the --commit-shared-state-transaction
case in braces so the result declaration is scoped within its switch clause.
Preserve the existing sharedState update, event recording, and return behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1420e8b5-79b3-431e-add3-cf9cd22036b1

📥 Commits

Reviewing files that changed from the base of the PR and between 2c64343 and 7bcc852.

📒 Files selected for processing (5)

• src/lib/onboard/managed-bootstrap/adapter.ts
• src/lib/onboard/managed-bootstrap/docker-shared-state.ts
• src/lib/onboard/managed-bootstrap/docker-test-fixture.ts
• src/lib/onboard/managed-bootstrap/docker.test.ts
• src/lib/onboard/managed-bootstrap/docker.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/lib/onboard/managed-bootstrap/adapter.ts
• src/lib/onboard/managed-bootstrap/docker.ts

[ericksoa]

Addressed all CodeRabbit feedback on exact head c874abc64a256bba1363d23c7cde34456483c970:

• aligned NODE_PATH with the root-process injection denylist and parameterized pre-create rejection coverage;
• preserved the original commit-validation failure when quiescing also fails, with an explicit no-unsafe-rollback regression;
• made every flagged event-order test prove both events exist;
• removed the superseded rollback helper/import and dead journal assignment;
• explicitly rejects empty intended argv;
• made fixture nullability honest, renamed the retention helper, and moved mutation options before first use.

The five inline threads are resolved. Local validation passed 45/45 review-fix tests plus the 16/16 exact follow-up Docker suite, both typechecks, Biome, growth/test-size checks, repository checks, and normal hooks. Public exact-head requalification is running.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/lib/onboard/managed-bootstrap/docker.test.ts (1)

328-332: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Require the --agent flag before reading its value.

args.indexOf("--agent") returns -1 when the flag is absent. The assertion then checks args[0]. It can pass without proving that --agent <agent> was emitted if the first argument equals agent. Add an explicit agentIndex >= 0 check.

Proposed fix

         const agentIndex = args.indexOf("--agent");
-        return args.includes("--shared-state-transaction-status") && args[agentIndex + 1] === agent;
+        return (
+          agentIndex >= 0 &&
+          args.includes("--shared-state-transaction-status") &&
+          args[agentIndex + 1] === agent
+        );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/managed-bootstrap/docker.test.ts` around lines 328 - 332,
Update the mock-call predicate in the docker bootstrap test to require
agentIndex >= 0 before comparing args[agentIndex + 1] with agent, while
preserving the existing shared-state flag check.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/lib/onboard/managed-bootstrap/docker.test.ts`:
- Around line 328-332: Update the mock-call predicate in the docker bootstrap
test to require agentIndex >= 0 before comparing args[agentIndex + 1] with
agent, while preserving the existing shared-state flag check.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e97cb327-1ddd-48ae-8189-ace4dd6b0808

📥 Commits

Reviewing files that changed from the base of the PR and between 7bcc852 and c874abc.

📒 Files selected for processing (1)

• src/lib/onboard/managed-bootstrap/docker.test.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/managed-bootstrap/docker-shared-state.test.ts`:
- Around line 57-68: Remove the args[0] === "run" conditional from the shared
test assertion helper. Extract the run-specific and exec-specific assertions
into separate named helpers, then update each test to call the applicable helper
directly while preserving the existing argument-slice expectations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4af4e343-f700-4880-96ec-eec67cbb2006

📥 Commits

Reviewing files that changed from the base of the PR and between 633e0dc and 503fdd8.

📒 Files selected for processing (3)

• src/lib/onboard/managed-bootstrap/adapter.test.ts
• src/lib/onboard/managed-bootstrap/docker-shared-state.test.ts
• src/lib/onboard/managed-bootstrap/docker-shared-state.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/onboard/managed-bootstrap/docker-shared-state.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/temp-files.test.ts`:
- Around line 46-48: Update the assertion around fs.writeFileSync in the
temp-file test to verify that the thrown error has the EEXIST code, rather than
accepting any exception. Preserve the existing write attempt and subsequent
content check.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 14ab4620-6c21-406c-9ad1-ade109af6fda

📥 Commits

Reviewing files that changed from the base of the PR and between 2062283 and eb8ee81.

📒 Files selected for processing (5)

• src/lib/onboard/managed-bootstrap/README.md
• src/lib/onboard/managed-bootstrap/docker-shared-state.test.ts
• src/lib/onboard/managed-bootstrap/docker-shared-state.ts
• src/lib/onboard/managed-startup-shared-state-transaction.test.ts
• src/lib/onboard/temp-files.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• src/lib/onboard/managed-bootstrap/docker-shared-state.test.ts
• src/lib/onboard/managed-bootstrap/README.md
• src/lib/onboard/managed-bootstrap/docker-shared-state.ts

[ericksoa]

Nemotron F-001 disposition on exact head eb8ee81cc157ea7c12e311ab4b53e87930e3ae17: not actionable after two exact-diff audits.

The cited fourth file, docker-gpu-patch-clone.test.ts, adds 35 lines of direct behavioral coverage and no mocks. The repeated additions are about 15 small mock-member declarations across three snapshot tests: six Docker members and nine credential-store members. Those three hoisted vi.mock factories are not identical—two bind a file-local dockerInspectMock, one does not, and their fixture lifecycles differ. A shared parameterized factory would add hoist-sensitive test plumbing, broaden this dormant adapter slice into test-infrastructure refactoring, and would not support the claimed approximately 80-line reduction.

The file-local mocks are therefore retained to preserve module isolation. No production or test correctness issue remains from this suggestion.

[github-actions]

E2E Target Results — ❌ Some tests failed

Run: 30836022706
Workflow ref: feat/docker-managed-bootstrap-adapter-lifecycle
Requested targets: (default — all supported)
Requested test IDs: (selector rejected by workflow validation)
Summary: 0 passed, 1 failed, 0 cancelled, 0 skipped, 0 unknown

Test	Result	Total wall clock time
base-image-publication	❌ failure	2s

Failed tests: base-image-publication. Check the workflow run for all logs and artifacts.