fix(onboard): preserve shared-state commit authority

[ericksoa]

Summary

Recover the exact historical shared-state manifest without weakening identity-bound bootstrap, and fence Docker rollback with durable commit authority copied from the owning container. This prevents a restarted or failed managed bootstrap from rolling back state that already committed while preserving the legacy null-identity path.

Related Issue

Part of #7744.

Stack Position

• Base: fix(onboard): claim bootstrap terminal outcomes #8077 at 83e7fe53a05619bfc5c1401701ec844bbde818d9
• This exact head: 9d4dc59c331aca42f4ead7bc8831db61d1deee0e
• Stable parent-relative patch ID: cfaa19326c2bec368ac0ecc4870f20164d48c37d
• Exact patch size: 5 files, 423 insertions, 28 deletions
• Next slice: durable journal-record compatibility and canonical receipt equality

Changes

• Accept only the exact canonical schema-v1 manifest written before bootstrapIdentity, and map it to null identity solely for the legacy unbound path.
• Continue rejecting extra or missing fields, noncanonical state, caller identity mismatch, and attempts to adopt legacy null authority into an identity-bound bootstrap.
• Quiesce the failed replacement, probe its exact durable commit receipt through a protected host copy, and refuse rollback when that receipt proves commit.
• Copy verified pending authority before starting the immutable rollback helper; do not pretend --volumes-from exposes the replacement writable-layer /var/lib receipt.
• Preserve the existing provider-neutral shared-state contract; Docker owns only the engine-specific receipt extraction and helper invocation.
• Restore filesystem spies on every test exit and cover exact legacy compatibility, malformed near-misses, durable commit fencing, pending rollback, and provider-boundary behavior.
• Cover the supervisorReady: true commit-failure path: preserve exactly one available pending receipt, reuse that host copy for rollback, and reject rollback or container removal when the quiesced replacement re-probes as committed.
• Document the compatibility and writable-layer authority boundary next to the durable shared-state contract.

The compatibility path is required because pre-bootstrapIdentity schema-v1 manifests can remain on disk during upgrade. A direct current-schema-only parse would strand valid legacy rollback state, while treating every missing identity as current authority would be unsafe. managed-startup-shared-state-transaction.test.ts protects the exact historical shape and rejection boundary; docker-shared-state.test.ts protects the host-copy commit fence.

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 exact-head review found no production correctness or security issue and identified the now-covered commit-failure regression; fresh exact-head CI, advisors, CodeRabbit, CodeQL, and protected E2E remain required before merge.
• 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: src/lib/onboard/managed-bootstrap/README.md documents exact legacy null-identity schema-v1 acceptance, rejection of extra/missing/identity-bound adoption, and the Docker protected host-copy boundary required because --volumes-from cannot expose the replacement writable layer. Independent review found the wording complete and architecturally consistent with the exact implementation diff.
• Agent: Codex Desktop

DGX Station Hardware Evidence

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

Verification

• Append-only ancestry refresh: exact head 9d4dc59c331aca42f4ead7bc8831db61d1deee0e is signed-DCO and GitHub Verified on exact fix(onboard): claim bootstrap terminal outcomes #8077 base 83e7fe53a05619bfc5c1401701ec844bbde818d9; the stable parent-relative slice patch remains cfaa19326c2bec368ac0ecc4870f20164d48c37d at 5 files, +423/-28. Fresh exact-head CI, advisors, CodeRabbit, managed-image builds, and protected E2E are running.
• 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 — 43 focused/regression CLI tests and 2 provider-boundary integration tests passed for the implementation slice; the linear guardrail fixture introduced zero new if statements. The earlier advisor remediation adds the missing no-authority cleanup regression. The current implementation adds preserved-receipt reuse and committed-on-reprobe rollback-fence coverage; the focused Docker shared-state suite passes (5/5), together with Biome, CLI type-checking, repository checks, the exact test-conditional scan, commit hooks, and pre-push gates. The refreshed exact head additionally passes both affected suites, 30/30 tests, CLI typecheck, git diff --check, and the normal pre-push TypeScript/version gates.
• Applicable broad gate passed — public exact-head CI and protected E2E are starting.
• 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

Summary by CodeRabbit

• Reliability
  • Improved managed startup recovery by preventing rollback after a transaction has been durably committed.
  • Added safeguards for interrupted Docker-based updates, including transaction-status verification and preserved recovery information.
• Compatibility
  • Added support for legacy schema-v1 manifests without bootstrap identity information.
  • Added validation to reject incomplete, unexpected, or incompatible manifest fields.
• Documentation
  • Documented manifest compatibility rules and Docker rollback protections.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds canonical parsing for identity-free schema-v1 manifests and strengthens Docker shared-state rollback handling. Rollback now checks transaction status, protects commit receipts, and avoids reverting durable commits. Tests cover both behaviors.

Changes

Shared-state transactions

Layer / File(s)	Summary
Legacy manifest parsing and canonicalization src/lib/onboard/managed-startup/shared-state-transaction.ts, src/lib/onboard/managed-startup-shared-state-transaction.test.ts	Manifest parsing accepts identity-free schema-v1 records, validates exact fields, normalizes missing identities to null, and preserves identity-bound validation. Tests cover commit, rollback, and rejection cases.
Docker rollback authority and receipt handling src/lib/onboard/managed-bootstrap/docker-shared-state.ts, src/lib/onboard/managed-bootstrap/docker-shared-state.test.ts, src/lib/onboard/managed-bootstrap/README.md	Rollback checks transaction status before restoring state, rejects committed transactions, reuses or copies receipts, and returns whether rollback occurred. Tests and documentation cover receipt handling and Docker writable-layer limitations.

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

Sequence Diagram(s)

sequenceDiagram
  participant ReplacementContainer
  participant ProtectedHostReceipt
  participant SharedStateTransaction
  ReplacementContainer->>ProtectedHostReceipt: Copy writable-layer commit receipt
  ReplacementContainer->>SharedStateTransaction: Probe transaction status
  alt committed transaction
    SharedStateTransaction-->>ReplacementContainer: Report durable commit
    ReplacementContainer-->>ReplacementContainer: Reject rollback
  else pending transaction
    ReplacementContainer->>SharedStateTransaction: Invoke rollback with receipt
    SharedStateTransaction-->>ReplacementContainer: Restore shared state
  end

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 and concisely describes preserving shared-state commit authority, which is the main change in the pull request.

✨ 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/managed-bootstrap-shared-state-commit-authority

---

_{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 9d4dc59 in the fix/managed-bootstra... branch remains at 96%, unchanged from commit c63e7eb in the hold/podman-stack/pr... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 9d4dc59 in the fix/managed-bootstra... branch remains at 81%, unchanged from commit c63e7eb in the hold/podman-stack/pr... branch.

Show a code coverage summary of the most impacted files.

File	hold/podman-stack/pr... c63e7eb	fix/managed-bootstra... 9d4dc59	+/-
src/lib/onboard...trap/adapter.ts	84%	63%	-21%
src/lib/onboard...ndbox-create.ts	91%	82%	-9%
src/lib/state/sandbox.ts	85%	81%	-4%
src/lib/onboard...eway-service.ts	86%	82%	-4%
src/lib/onboard...cker-journal.ts	86%	83%	-3%
src/lib/onboard...-transaction.ts	78%	80%	+2%
src/lib/onboard...strap/docker.ts	60%	64%	+4%
src/lib/onboard...shared-state.ts	73%	78%	+5%
src/lib/onboard...cker-runtime.ts	0%	52%	+52%
src/lib/onboard...ntime-create.ts	0%	100%	+100%

---

_{Updated August 03, 2026 19:22 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: Partial review preserved 0 canonical finding(s) and 3 terminology decision(s) before the advisor stopped.

Model lanes

• GPT-5.6 Terra (primary): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

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.

• define — legacy null-identity path at src/lib/onboard/managed-bootstrap/README.md:62: Keep the adjacent definition and rejection boundary; they identify when this compatibility path applies.
• justified — identity-bound authority at src/lib/onboard/managed-bootstrap/README.md:64: Keep this modifier because it distinguishes the authority that can authorize rollback.
• define — writable-layer commit receipt at src/lib/onboard/managed-bootstrap/README.md:65: Keep the adjacent host-copy explanation; it states the verification boundary for this receipt.

E2E guidance

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

Recommended E2E: device-auth-health, issue-4462-scope-upgrade-approval, onboard-repair, onboard-resume, openclaw-inference-switch, cloud-onboard

Workflow run details

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

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

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

109-166: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Add coverage for the commit-failure rollback path that reuses a preserved receipt.

This suite covers supervisorReady: false with a committed state and with a pending state. It does not cover supervisorReady: true followed by a commit failure. That path calls rollbackManagedStartupSharedState with a non-undefined preservedReceiptPath (docker-shared-state.ts Line 620). This is the specific mechanism this PR introduces to avoid re-copying the receipt and to still recheck the durable-commit status before restoring.

Add a test that drives finalizeDockerManagedStartupSharedState with supervisorReady: true, makes the logical commit validation fail after the receipt is copied, and asserts that:

• rollback proceeds using the already-copied receipt (no second cp from the pending-transaction path), and
• rollback still throws if the container reports "committed" on the re-probe, instead of silently restoring stale state.

🤖 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-shared-state.test.ts` around lines
109 - 166, Extend the Docker shared-state rollback tests with a supervisorReady:
true scenario where logical commit validation fails after the receipt is copied.
Configure the fixture to report committed during the rollback re-probe, then
assert finalizeDockerManagedStartupSharedState throws the durable-commit error,
rollback uses the preserved receipt without a second pending-transaction copy,
and the expected rollback/status commands and events are recorded.

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

Nitpick comments:
In `@src/lib/onboard/managed-bootstrap/docker-shared-state.test.ts`:
- Around line 109-166: Extend the Docker shared-state rollback tests with a
supervisorReady: true scenario where logical commit validation fails after the
receipt is copied. Configure the fixture to report committed during the rollback
re-probe, then assert finalizeDockerManagedStartupSharedState throws the
durable-commit error, rollback uses the preserved receipt without a second
pending-transaction copy, and the expected rollback/status commands and events
are recorded.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 440e9c95-f650-4310-96a1-706708b1ba72

📥 Commits

Reviewing files that changed from the base of the PR and between 6e1a80f and 1fef6bd.

📒 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/managed-startup/shared-state-transaction.ts

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[apurvvkumaria]

Approve — reviewed exact head 9d4dc59. Shared-state publication retains single-writer commit authority and rejects stale or mismatched transactions, with focused transaction and Docker shared-state coverage. I found no blocking security or correctness regression. The inherited npm dependency failure and pending coordination signal are not evidence of a defect in this delta.

[ericksoa]

Superseded by clean consolidated replacement #8225, now merged. The donor head remains preserved under backup/podman-stack/pr8078-source-9d4dc59c.