feat(runtime): start exact Podman image bootstrap by ericksoa · Pull Request #8056 · NVIDIA/NemoClaw

ericksoa · 2026-08-01T11:47:36Z

Summary

Adds a dormant Podman image-bootstrap transaction that accepts only the exact prepared replacement authority from the preceding stack slice. It stages one protected request for the selected agent, starts the exact replacement without exec or a user override, and authenticates the image-owned completion while the stopped watcher and durable journal remain authoritative. This PR does not activate Podman as a user-visible runtime.

Related Issue

Part of #7744.

Changes

Bind startup to PodmanBootstrapPreparedReplacement and the exact durable original-stopped journal.
Re-prove engine, watcher lease, runtime, image, staging name, state volume, mountpoint, and specification authority before staging, starting, polling, and accepting completion.
Stage one protected root-apply envelope and authenticate protected completion receipts for OpenClaw, Hermes, and LangChain Deep Agents Code.
Keep the transaction internal and dormant so central orchestration gains no Podman-specific activation switch.
Add drift, lost-journal, retry, timeout, file-mode, all-agent, and source-shape tests.
Document the exact image-transaction authority and its unresolved post-failure state.

The internal transaction is required by #7744 to connect the prepared replacement to the image-owned root-application boundary. A direct central-orchestration change would bypass the pluggable runtime boundary. podman-image-transaction.test.ts protects this 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: Maintainer-directed incremental runtime design in [Epic] Support native Podman with buildless managed onboarding #7744; exact authority, drift, protected-file, and unresolved-failure behavior have focused tests and lifecycle documentation.
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/lifecycle-contracts.md documents exact prerequisites, revalidation, the selected-agent request, protected completion, and the unresolved post-failure state. The review also corrected the engine-authority test title and PR terminology. The append-only parent refresh to 5250328ca preserves the exact reviewed slice diff and changes no reviewed documentation.
Agent: Codex Desktop
Qualification carry-forward: Exact head 03f5a3d on base e724196 preserves the byte-identical previously reviewed slice diff (stable patch ID 3c5a755831318334c0870a037f138765d986ae3f; binary diff SHA-256 0196f405c488cd2a352863938fd6da21cdbdc04098fe019863834e84009d8f66), and its source and documentation tree is unchanged from reviewed head 0f125e0.

DGX Station Hardware Evidence

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

Verification

Qualification-only exact head/base: 03f5a3d / e724196; signed-DCO append-only cascade, stable-patch proof, byte-identical slice diff, final-tree equality, and normal pre-push hooks passed.
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 — command/result or justification: npx vitest run --project cli src/lib/onboard/managed-bootstrap/podman-image-transaction.test.ts src/lib/onboard/managed-bootstrap/podman-bootstrap-replacement.test.ts src/lib/onboard/managed-bootstrap/podman-bootstrap-journal.test.ts src/lib/onboard/managed-bootstrap/podman-watcher-lease.test.ts src/lib/onboard/managed-bootstrap/podman-held-workload.test.ts passed 73/73; npx vitest run --project integration test/runtime-provider-source-shape.test.ts passed 2/2; CLI typecheck and pre-push checks 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: Aaron Erickson aerickson@nvidia.com

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

coderabbitai · 2026-08-01T11:47:48Z

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: ba06a482-ca93-4788-b4d3-8f3305f808c0

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 · 2026-08-01T11:48:20Z

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit acb25d6 in the feat/podman-image-bo... branch remains at 96%, unchanged from commit a7237ea in the feat/podman-bootstra... branch.

Show a code coverage summary of the most impacted files.

File	`feat/podman-bootstra...` a7237ea	`feat/podman-image-bo...` acb25d6	+/-
`nemoclaw/src/se...ntial-filter.ts`	100%	0%	-100%
`nemoclaw/src/sh...er-boundary.cts`	96%	0%	-96%
`nemoclaw/src/se...ot-sanitizer.ts`	95%	0%	-95%
`nemoclaw/src/co...test-fixture.ts`	81%	0%	-81%
`nemoclaw/src/co...ration-state.ts`	93%	94%	+1%

TypeScript / code-coverage/cli

The overall coverage in commit acb25d6 in the feat/podman-image-bo... branch remains at 81%, unchanged from commit a7237ea in the feat/podman-bootstra... branch.

Show a code coverage summary of the most impacted files.

File	`feat/podman-bootstra...` a7237ea	`feat/podman-image-bo...` acb25d6	+/-
`src/lib/state/sandbox.ts`	85%	78%	-7%
`src/lib/onboard...strap/docker.ts`	69%	64%	-5%
`src/lib/onboard...atcher-lease.ts`	0%	75%	+75%
`src/lib/onboard...an-lifecycle.ts`	0%	84%	+84%
`src/lib/onboard...trap-journal.ts`	0%	86%	+86%
`src/lib/onboard...-replacement.ts`	0%	87%	+87%
`src/lib/onboard...-transaction.ts`	0%	88%	+88%
`src/lib/onboard...eld-workload.ts`	0%	88%	+88%
`src/lib/onboard...ne-authority.ts`	0%	89%	+89%
`src/lib/onboard...an-preflight.ts`	0%	95%	+95%

_{Updated August 04, 2026 00:03 UTC}

github-actions · 2026-08-01T11:53:47Z

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: Review the warnings below.
Findings: 0 blockers · 2 warnings · 0 suggestions
Status: Partial review preserved 2 canonical finding(s) and 2 terminology decision(s) before the advisor stopped.

Model lanes

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

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

2 semantic terminology decisions

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

define — image-owned bootstrap transaction at src/lib/onboard/lifecycle-contracts.md:190: Keep the term and its boundary definition in the lifecycle contract.
define — persisted-engine-authority at src/lib/onboard/managed-bootstrap/README.md:90: Keep the term and its definition in the managed-bootstrap README.

E2E guidance

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

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

2 warnings · 0 suggestions

Warnings

Warnings do not block.

`PRA-1` Warning — Reject persisted-authority ownership checks without a process UID

Location: src/lib/onboard/runtime-provider/persisted-engine-authority.ts:185
Category: correctness
Problem: currentUid uses the candidate file or directory UID when process.getuid is unavailable. The subsequent equality check then accepts any owner, so this private-state boundary does not verify current-user ownership on that runtime.
Impact: A runtime without process.getuid can accept an authority record or directory owned by another account, weakening the record's ownership boundary before a future lifecycle consumer relies on it.
Recommendation: Make currentUid return no identity when process.getuid is unavailable, and reject private-record operations in that case.
Verification: Inspect the ownership predicates with process.getuid unavailable and confirm they reject rather than compare metadata.uid to itself.
Test coverage: Add a test that simulates an unavailable process.getuid and verifies directory and file authority operations fail before accepting a record.
Evidence: src/lib/onboard/runtime-provider/persisted-engine-authority.ts:185-201 src/lib/onboard/runtime-provider/persisted-engine-authority.ts:217-227 src/lib/inference/vllm-station-ssh-binding.ts:155-158 rejects an unavailable POSIX user identity.

`PRA-2` Warning — Remove the unconsumed persisted-engine-authority layer until a lifecycle consumer exists

Location: src/lib/onboard/runtime-provider/persisted-engine-authority.ts:27
Category: architecture
Problem: This PR adds a durable authority store and matcher, but no production lifecycle code records or requires it. The changed README explicitly says no production lifecycle calls the matcher.
Impact: The repository gains a security-sensitive durable-state contract with no active behavior to validate, increasing maintenance and future integration risk.
Recommendation: Remove this dormant persisted-engine-authority layer from this PR, or add its named current lifecycle consumer and an end-to-end consumer contract test in the same change.
Verification: Search production lifecycle call paths for createFilePersistedEngineAuthorityStore, record, and requirePersistedEngineAuthority; confirm no current consumer exists.
Test coverage: If retained with a current consumer, add a contract test that records authority before that consumer's mutation and rejects a mismatched freshly qualified engine.
Simplification (yagni): Remove The unconsumed persisted-engine-authority store, parser, matcher, tests, README paragraph, and source-shape inventory.; use Keep authority persistence in the future lifecycle slice that first consumes it.. Net: -540 lines.
Keep: Do not remove the existing prepared-replacement journal, watcher lease, or exact Podman transaction authority checks.
Evidence: src/lib/onboard/managed-bootstrap/README.md:90-96 states that no production lifecycle calls the matcher yet. src/lib/onboard/runtime-provider/persisted-engine-authority.ts:27-330 adds the standalone persistence layer. test/runtime-provider-source-shape.test.ts:86-171 inventories the file without exercising a lifecycle consumer.

Workflow run details

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

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

## Summary Add a dormant, provider-neutral persistence contract for future snapshot, rebuild, restore, and recovery paths. These paths must compare a freshly provider-qualified container engine with its exact authority record before mutation. This slice adds the identity record and matcher only; no production lifecycle calls it, and it does not select, reconstruct, or activate Podman or any other runtime. ## Related Issue Related to #7744. ## Changes - Add a canonical versioned authority record binding one provider, operation scope, engine identity, endpoint-authority identity, and non-secret runtime binding digest. - Add a private atomic store with write-once/idempotent semantics, stable metadata checks, bounded canonical parsing, and fail-closed symlink, ownership, permission, and conflict handling. - Verify stored-file mode and canonical bytes through one `O_NOFOLLOW` descriptor in tests, avoiding a path-based check/use race. - Add an exact matcher for a freshly provider-qualified injected engine; no production lifecycle calls the matcher in this slice. - Exercise the contract with an MXC-style engine and keep production provider selection unchanged; source-shape coverage prevents the persistence boundary from importing managed-bootstrap implementations. - Document the dormant ownership and deferred activation boundary in the internal managed-bootstrap map. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [x] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates - [x] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [ ] Tests not applicable — justification: - [ ] Docs updated for user-facing behavior changes - [x] Docs not applicable — justification: This slice is internal and dormant; its ownership and activation boundary is recorded in the internal managed-bootstrap README. - [x] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [x] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Maintainer-directed inert slice in #7744; exact identity, filesystem, canonicalization, retry, and drift boundaries have focused adversarial tests. - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Documentation Writer Review - [x] Documentation writer subagent reviewed the completed changes - Result: `docs-updated` - Evidence: Reviewed `src/lib/onboard/managed-bootstrap/README.md`, changed source comments, test titles, source-shape wording, and the PR description at exact head `269de66e5`; all prior wording findings are resolved, and `git diff --check` passed. The append-only parent refresh to `ae30b0694` preserves the exact reviewed slice diff and changes no reviewed documentation. - Agent: Codex Desktop - Qualification carry-forward: Exact head a2ae17e on base 03f5a3d preserves the byte-identical previously reviewed slice diff (stable patch ID 1eecb90d9b155b37b64b93c8d9c31feeb6b611d2; binary diff SHA-256 1c1968117fe5fae4894da9d74030aa39d6a6be8e8ae525c2ff2e7c594404efb6), and its source and documentation tree is unchanged from reviewed head 0fde3f9.   ## DGX Station Hardware Evidence - [ ] Tested on DGX Station - Tested commit: - Station profile/scenario: - Result: - Supporting evidence: ## Verification - Qualification-only exact head/base: a2ae17e / 03f5a3d; signed-DCO append-only cascade, stable-patch proof, byte-identical slice diff, final-tree equality, and normal pre-push hooks passed. - [x] PR description includes a `Signed-off-by:` line and every commit appears as `Verified` in GitHub - [x] 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 - [x] 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/runtime-provider/persisted-engine-authority.test.ts` (10 passed); `npx vitest run --project integration test/runtime-provider-source-shape.test.ts` (2 passed); CLI build and typecheck passed at exact implementation head `b403f7a68`; the exact head `269de66e5` reran the authority suite after the same-descriptor CodeQL repair; source-shape, Biome, diff-check, and normal push hooks pass. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) - [ ] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) --- Signed-off-by: Aaron Erickson <aerickson@nvidia.com> --------- Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

cv

Reviewed commit acb25d6356 in bottom-up stack order. This PR depends on #8055, which is not approval-ready. Its image, audit, CI, and E2E checks fail, so image-bootstrap behavior cannot advance ahead of the preparation contract. Review remains blocked until the parent is reconstructed or repaired, this branch is restacked on the accepted parent commit, and current CI, security, and documentation evidence passes for the resulting commit. No approval is granted for the current branch.

ericksoa added 8 commits August 1, 2026 03:10

feat(runtime): stage Podman image bootstrap

39c89b5

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

merge(stack): refresh Podman bootstrap journal

4e56aa3

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

test(runtime): keep Podman image transaction fixture linear

289287c

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

merge(stack): refresh Podman bootstrap journal checks

ab65196

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

test(runtime): inventory Podman image transaction

4e18b65

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

fix(runtime): bind Podman image bootstrap authority

fd82f60

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

fix(runtime): accept omitted Podman shared mount mode

094cea4

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

merge(stack): refresh Podman bootstrap review fixes

6ae135a

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

docs(runtime): record Podman image transaction boundary

913c724

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

ericksoa mentioned this pull request Aug 1, 2026

[Epic] Support native Podman with buildless managed onboarding #7744

Open

ericksoa added 3 commits August 1, 2026 05:31

chore(stack): refresh Podman image transaction parent

5250328

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

chore(stack): incorporate prior-slice repairs

0f125e0

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

chore(stack): incorporate prior-slice qualification refresh

03f5a3d

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

github-actions Bot added v0.0.102 Release target and removed v0.0.101 labels Aug 3, 2026

apurvvkumaria self-assigned this Aug 3, 2026

apurvvkumaria removed their assignment Aug 4, 2026

jyaunches mentioned this pull request Aug 4, 2026

feat(runtime): define provider state-mutation contract #8186

Open

23 tasks

apurvvkumaria assigned ericksoa Aug 4, 2026

cv reviewed Aug 4, 2026

View reviewed changes

cv mentioned this pull request Aug 4, 2026

feat(runtime): persist engine lifecycle recovery #8058

Open

23 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(runtime): start exact Podman image bootstrap - #8056

feat(runtime): start exact Podman image bootstrap#8056
ericksoa wants to merge 13 commits into
feat/podman-bootstrap-journalfrom
feat/podman-image-bootstrap-transaction

ericksoa commented Aug 1, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 1, 2026 •

edited

Loading

Review skipped

Uh oh!

github-code-quality Bot commented Aug 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 1, 2026 •

edited

Loading

Warnings

`PRA-1` Warning — Reject persisted-authority ownership checks without a process UID

`PRA-2` Warning — Remove the unconsumed persisted-engine-authority layer until a lifecycle consumer exists

Uh oh!

cv left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

ericksoa commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Quality Gates

Documentation Writer Review

DGX Station Hardware Evidence

Verification

Uh oh!

coderabbitai Bot commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-code-quality Bot commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Overview

TypeScript / code-coverage/plugin

TypeScript / code-coverage/cli

Uh oh!

github-actions Bot commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor — Informational

Model lanes

E2E guidance

Warnings

PRA-1 Warning — Reject persisted-authority ownership checks without a process UID

PRA-2 Warning — Remove the unconsumed persisted-engine-authority layer until a lifecycle consumer exists

Uh oh!

cv left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ericksoa commented Aug 1, 2026 •

edited

Loading

coderabbitai Bot commented Aug 1, 2026 •

edited

Loading

github-code-quality Bot commented Aug 1, 2026 •

edited

Loading

github-actions Bot commented Aug 1, 2026 •

edited

Loading

`PRA-1` Warning — Reject persisted-authority ownership checks without a process UID

`PRA-2` Warning — Remove the unconsumed persisted-engine-authority layer until a lifecycle consumer exists