feat(onboard): add managed bootstrap image runtime

[ericksoa]

Summary

Add the dormant image-owned managed-bootstrap runtime for OpenClaw, Hermes, and
LangChain Deep Agents Code. It authenticates the canonical envelope, atomically
moves that exact inode into a root-private retry claim, applies the root request,
publishes identity-bound completion, and consumes only the authenticated claim.
A newer canonical request is preserved. This slice does not package, advertise,
or activate buildless support.

Related Issue

Part of #7744.

Changes

• Add the composed bootstrap image runtime and its recovery, apply, and
  verification CLI modes without importing managed-bootstrap from the neutral
  managed-startup layer.
• Require bounded root:root mode-0400 single-link envelopes, protected
  root-owned claim parents, and a root-private mode-0700 adjacent claim.
• Bind the authenticated descriptor through same-device atomic rename, preserve
  a newly staged canonical request, and fail closed before application if the
  claim cannot be made.
• Restore a protected displaced request after interruption immediately following
  rename, and reconcile the exact two-link state left by interruption during
  exclusive restoration without overwriting a later canonical request.
• Keep the private claim as sole retry authority across application,
  completion-publication, and cleanup interruption; resume it idempotently.
• Publish bootstrap completion only after the shared managed-startup application
  succeeds, then delegate shared completion and runtime-environment verification.
• Sequence recovery, conditional apply, and exact completion verification from
  the native trampoline for every supported agent before supervisor resume.
• Preserve provider neutrality and inert activation: production providers remain
  bootstrap-unsupported and current images do not package this entrypoint.
• Split handoff and descriptor-integrity tests into a focused 521-line suite;
  keep branch-heavy fake-FS setup in a 429-line non-test helper so no legacy
  size or conditional-growth
  allowance is required.
• Address all CodeRabbit feedback and record the independent race, recovery,
  documentation, and advisor dispositions.

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: two independent exact-tree audits cover
  atomic claim ownership, descriptor identity, replacement preservation,
  protected-parent validation, crash recovery, completion ordering, all-agent
  trampoline behavior, provider neutrality, and inert activation.
• Non-success, skipped, or missing CI check accepted by maintainer — check
  name, approval link, and follow-up issue: the maintainer explicitly waived the
  known npm advisory and its consequential same-repository E2E blockage for this
  stack because that advisory is handled on a separate security stream. No other
  check is waived.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: src/lib/onboard/managed-bootstrap/README.md was checked against the
  exact claim runtime, trampoline, tests, provider registry, production image
  packaging, and source-shape contract. It documents atomic private-claim retry
  authority, preservation of a newer canonical request, post-rename crash
  restoration, fail-closed rename,
  one-way managed-bootstrap-to-managed-startup composition, delegated shared
  completion verification, Node-owned state transitions, and inert activation.
  No published docs/ change is needed while the capability remains unpackaged
  and provider-unsupported.
• Agent: Codex Desktop documentation writer and independent exact-tree auditor

DGX Station Hardware Evidence

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

Verification

• Exact public head: 9c67a9a2a0f98c34508305360671a8a9c7a4bec5.

• Exact head tree: c615ee677c9a8bab4eebcbda57f97224da69eb09.

• Exact PR base used by the current workflow dispatch:
  878430aebebcc5e584be3bef6685997d039c213a.

• Direct base-to-head scope: 11 files, +2675/-575.

• Stable patch ID: 2ca3949b0dd55275a70bd86fd3a8d9b2118b2bc5.

• Binary diff SHA-256:
  68d73166b4ac0dd62e7d12c7bab09a1b3be775082c544c211d3ed929f010ed78.

• Focused five-file runtime/source-shape verification: 94 passed; 9 Linux-only
  tests skipped on the macOS host. The exact runtime suite passes 46 of 46.

• The largest changed test file is 1,291 lines; branch-heavy fake-FS setup is in
  a 429-line non-test helper. The trusted base-to-head evaluators report zero size
  violations and 0 -> 0 conditional growth for all five changed test files.

• CLI build and typecheck, repository architecture checks, source-shape and
  test-size guards, Biome, Markdown lint, ShellCheck, diff checks, commit hooks,
  and pre-push hooks pass locally.

• The append-only history preserves every former public head. 9c67a9a2a has
  sole parent 30b61ca5c; that GitHub update commit retains 856a021b3 as its
  first parent and the exact workflow base as its second. No remote history was
  rewritten.

• GitHub verifies the exact head signature and DCO. Exact-head CI, advisors,
  CodeRabbit, and protected E2E are running.

• All seven findings in CodeRabbit review 4850036066 are addressed. The prior
  Nemotron size warning and Terra post-rename replacement race are fixed;
  dependency direction, delegated verification, Node-owned state transitions,
  and fail-closed recovery behavior are explicit in the README and independently
  audited.

• 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

• Applicable broad gate passed — exact-head CI is running

• 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)

Stack

• Base: merged PR3.12B fix(onboard): reconcile managed bootstrap after restart #8043 plus the PR workflow base above.
• This slice: PR3.13 feat(onboard): add managed bootstrap image runtime #8045 at exact public head 9c67a9a2a, targeting main.
• Later dormant/additive slices are being consolidated into internally complete
  review batches to pay one qualification cycle per batch. Buildless and Podman
  support remain disabled until the complete 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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

src/lib/onboard/managed-startup-image-runtime.test.ts (3)

704-732: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Split the CLI leg into its own test.

The title claims two behaviors: completion is published only after application, and attempt identity is preserved. Lines 704-731 add a third behavior, which is CLI logging for --apply-bootstrap-file and --verify-bootstrap-completion. Line 704 also calls the mocked fs.unlinkSync directly to reset state between the two legs.

Move lines 704-731 into a separate it that seeds its own filesystem. The reset at line 704 then disappears, and a CLI regression names the CLI behavior instead of the publish-ordering behavior.

🤖 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-startup-image-runtime.test.ts` around lines 704 -
732, Split the CLI logging assertions around mainManagedBootstrapImageRuntime
into a separate it test that initializes its own filesystem state and validates
both --apply-bootstrap-file and --verify-bootstrap-completion logs. Remove the
direct fs.unlinkSync reset from the existing publish-ordering/attempt-identity
test, leaving that test focused only on its claimed behavior.

---

734-776: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Add coverage for envelope metadata rejection.

This test covers one failure mode, which is a rejecting coordinator. consumeManagedBootstrapEnvelope in src/lib/onboard/managed-bootstrap/image-runtime.ts lines 89-96 also rejects an envelope that is not root:root mode 0400 with one link. That check is the trust boundary for the request file, and the seeded map already carries a mode, so the case is cheap to express.

Add a case that seeds the request file with mode 0o444 and asserts that the call rejects and that the request file is not consumed. Also add a case with a mismatched bootstrapIdentity to cover the identity check at lines 98-104.

🤖 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-startup-image-runtime.test.ts` around lines 734 -
776, Add test coverage for envelope metadata validation alongside the existing
rejecting-coordinator test: seed the request file with mode 0o444 and assert
applyManagedBootstrapEnvelope rejects without consuming the request, then add a
separate case with a mismatched bootstrapIdentity and the same non-consumption
assertion. Reuse the existing managed profile, filesystem setup, and request
envelope helpers while targeting the metadata checks in
consumeManagedBootstrapEnvelope.

Source: Path instructions

---

634-635: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the exported bootstrap path constants in both test setups. Import MANAGED_BOOTSTRAP_REQUEST_FILE and MANAGED_BOOTSTRAP_COMPLETION_FILE, then use them instead of the repeated literals at lines 634-635 and 739-740. The CLI entry point defaults to these constants, so one source prevents fixture paths from drifting.

🤖 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-startup-image-runtime.test.ts` around lines 634 -
635, Update both test setups in managed-startup-image-runtime.test.ts to import
and use the exported MANAGED_BOOTSTRAP_REQUEST_FILE and
MANAGED_BOOTSTRAP_COMPLETION_FILE constants instead of hardcoded path literals.
Apply this at both fixture definitions around lines 634-635 and 739-740,
preserving the existing test behavior.

🤖 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/image-runtime.ts`:
- Around line 179-185: Update the --verify-bootstrap-completion branch to retain
the completion record returned by verifyManagedBootstrapImageCompletion and
include its transactionPending value in the verification log, matching the apply
log’s pending-state reporting. Update the corresponding assertion in
managed-startup-image-runtime.test.ts to expect the expanded message.
- Around line 105-118: Update applyManagedBootstrapEnvelope and the
consumeManagedBootstrapEnvelope flow so the bootstrap request remains available
until applyManagedStartupRootRequest completes successfully. Preserve or
re-stage the consumed envelope when application throws, allowing a subsequent
invocation to retry; retain the existing cleanup behavior after success. Add
coverage for an interrupted application followed by a successful retry.

---

Nitpick comments:
In `@src/lib/onboard/managed-startup-image-runtime.test.ts`:
- Around line 704-732: Split the CLI logging assertions around
mainManagedBootstrapImageRuntime into a separate it test that initializes its
own filesystem state and validates both --apply-bootstrap-file and
--verify-bootstrap-completion logs. Remove the direct fs.unlinkSync reset from
the existing publish-ordering/attempt-identity test, leaving that test focused
only on its claimed behavior.
- Around line 734-776: Add test coverage for envelope metadata validation
alongside the existing rejecting-coordinator test: seed the request file with
mode 0o444 and assert applyManagedBootstrapEnvelope rejects without consuming
the request, then add a separate case with a mismatched bootstrapIdentity and
the same non-consumption assertion. Reuse the existing managed profile,
filesystem setup, and request envelope helpers while targeting the metadata
checks in consumeManagedBootstrapEnvelope.
- Around line 634-635: Update both test setups in
managed-startup-image-runtime.test.ts to import and use the exported
MANAGED_BOOTSTRAP_REQUEST_FILE and MANAGED_BOOTSTRAP_COMPLETION_FILE constants
instead of hardcoded path literals. Apply this at both fixture definitions
around lines 634-635 and 739-740, preserving the existing test 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: 81885d26-b680-449d-803e-cdac2eb6ad7e

📥 Commits

Reviewing files that changed from the base of the PR and between a0ef33f and e32b552.

📒 Files selected for processing (7)

• src/lib/onboard/managed-bootstrap/README.md
• src/lib/onboard/managed-bootstrap/image-runtime.ts
• src/lib/onboard/managed-bootstrap/index.ts
• src/lib/onboard/managed-startup-bootstrap-image-runtime.test.ts
• src/lib/onboard/managed-startup-image-runtime.test.ts
• src/lib/onboard/managed-startup/image-runtime.ts
• test/runtime-provider-source-shape.test.ts

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

• src/lib/onboard/managed-startup-bootstrap-image-runtime.test.ts
• src/lib/onboard/managed-bootstrap/README.md

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/onboard/managed-startup-image-runtime.test.ts (1)

527-529: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Model pending temporary-file cleanup in the fake filesystem. unlinkSync(temporary) runs after atomic-write failure, but the mock only deletes committed files. Remove pending entries before falling back to deleteExistingFile; the production catch preserves the primary failure, so the current mock does not mask it.

🤖 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-startup-image-runtime.test.ts` around lines 527 -
529, Update the vi.spyOn(fs, "unlinkSync") mock in the test to remove the
provided temporary path from the fake filesystem’s pending entries before
calling deleteExistingFile(String(target)). Preserve the existing committed-file
cleanup fallback and ensure atomic-write failure cleanup mirrors production
behavior without masking the primary error.

Source: Path instructions

🤖 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-startup-image-runtime.test.ts`:
- Around line 527-529: Update the vi.spyOn(fs, "unlinkSync") mock in the test to
remove the provided temporary path from the fake filesystem’s pending entries
before calling deleteExistingFile(String(target)). Preserve the existing
committed-file cleanup fallback and ensure atomic-write failure cleanup mirrors
production behavior without masking the primary error.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 280fbcd6-935e-40a0-a68c-262e9b3e35c2

📥 Commits

Reviewing files that changed from the base of the PR and between e32b552 and 483b187.

📒 Files selected for processing (2)

• src/lib/onboard/managed-bootstrap/README.md
• src/lib/onboard/managed-startup-image-runtime.test.ts

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

• src/lib/onboard/managed-bootstrap/README.md

[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/image-runtime.ts (1)

108-130: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Bind request cleanup to the validated file.

readManagedBootstrapEnvelope validates one file, but applyManagedBootstrapEnvelope closes it before the await and then unlinks requestFile by pathname. A replacement can therefore be deleted. Serialize access or revalidate the same file identity before cleanup. Add tests for default and injected requestFile paths.

🤖 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/image-runtime.ts` around lines 108 - 130,
Update applyManagedBootstrapEnvelope so cleanup remains bound to the request
file validated by readManagedBootstrapEnvelope across the await, preventing a
replacement at requestFile from being deleted; serialize access or revalidate
the file identity before fs.unlinkSync. Add coverage for both the default
requestFile and an injected requestFile path.

Source: Path instructions

🤖 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/image-runtime.ts`:
- Around line 108-130: Update applyManagedBootstrapEnvelope so cleanup remains
bound to the request file validated by readManagedBootstrapEnvelope across the
await, preventing a replacement at requestFile from being deleted; serialize
access or revalidate the file identity before fs.unlinkSync. Add coverage for
both the default requestFile and an injected requestFile path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: de0b2078-bc1c-4525-8414-a2a3dc9fe3f6

📥 Commits

Reviewing files that changed from the base of the PR and between 483b187 and 42520a6.

📒 Files selected for processing (5)

• src/lib/onboard/managed-bootstrap/README.md
• src/lib/onboard/managed-bootstrap/image-runtime.ts
• src/lib/onboard/managed-bootstrap/index.ts
• src/lib/onboard/managed-startup-bootstrap-image-runtime.test.ts
• src/lib/onboard/managed-startup-image-runtime.test.ts

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

• src/lib/onboard/managed-bootstrap/index.ts
• src/lib/onboard/managed-startup-bootstrap-image-runtime.test.ts
• src/lib/onboard/managed-startup-image-runtime.test.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.

[coderabbitai]

🧹 Nitpick comments (7)

src/lib/onboard/managed-startup-image-runtime.test.ts (2)

1197-1206: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert one failure mode for the pre-claim replacement.

The regular expression accepts two different rejection reasons. The test passes whether the runtime detects the identity mismatch or the pre-claim change. That hides a change in which check fires first. The rename observer replaces the request exactly at the claim rename, so the expected failure is deterministic. Assert that single message, and keep the recoverManagedBootstrapEnvelopeClaim assertion on Line 1204 as the identity check.

As per path instructions: "Flag copied production algorithms, broad mocks that bypass the behavior under test, and conditionals that make a test pass without exercising its claim."

🤖 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-startup-image-runtime.test.ts` around lines 1197 -
1206, The applyManagedBootstrapEnvelope assertion in the pre-claim replacement
test must require the deterministic “changed before its atomic claim” rejection
instead of accepting either message; keep the separate
recoverManagedBootstrapEnvelopeClaim assertion for “identity does not match”
unchanged.

Source: Path instructions

---

550-568: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Make openSync reject reads of missing files.

The mock only raises ENOENT for MANAGED_STARTUP_RUNTIME_ENV_FILE and MANAGED_STARTUP_COMPLETION_FILE. For any other absent path, allocateDescriptor returns a descriptor, and the failure surfaces later in fstatSync. Production readStableFile wraps only the openSync call and reports could not safely open <target>; it does not wrap fstatSync. A test that exercises a missing request or claim file therefore observes a raw ENOENT instead of the production error text.

Gate the behavior on the create flag so writes still work.

♻️ Proposed mock fidelity fix

-    vi.spyOn(fs, "openSync").mockImplementation(((target: fs.PathLike, _flags, mode) => {
+    vi.spyOn(fs, "openSync").mockImplementation(((target: fs.PathLike, flags, mode) => {
       const resolved = String(target);
+      const creating =
+        typeof flags === "number" && (flags & fs.constants.O_CREAT) === fs.constants.O_CREAT;
       const descriptor =
-        (resolved === MANAGED_STARTUP_RUNTIME_ENV_FILE ||
-          resolved === MANAGED_STARTUP_COMPLETION_FILE) &&
-        !files.has(resolved)
+        !creating && !files.has(resolved) && !directories.has(resolved)
           ? missing()
           : allocateDescriptor(resolved, typeof mode === "number" ? mode : 0o600);

🤖 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-startup-image-runtime.test.ts` around lines 550 -
568, Update the openSync mock in the managed startup runtime tests to throw the
missing-file error for every absent path when the requested flags do not permit
creation, while preserving descriptor allocation for create-mode writes. Keep
existing special handling and descriptor snapshots unchanged for present files,
and ensure missing request or claim reads fail at openSync so readStableFile
produces its expected error.

src/lib/onboard/managed-bootstrap/README.md (1)

193-199: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove the redundant qualifier.

Line 194 says "the same exact attempt". Use "the same attempt". The rest of the paragraph matches the implemented claim protocol.

✏️ Proposed change

-completion publication so the same exact attempt can retry after interruption;
+completion publication so the same attempt can retry after interruption;

🤖 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/README.md` around lines 193 - 199, In the
managed-bootstrap README paragraph, update the phrase “the same exact attempt”
to “the same attempt” while leaving the rest of the claim protocol description
unchanged.

Source: Linters/SAST tools

src/lib/onboard/managed-bootstrap/image-runtime.ts (2)

99-132: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Reuse isProtectedManagedBootstrapFile for the snapshot metadata check.

Lines 108-115 repeat the ownership, link-count, and mode rules that isProtectedManagedBootstrapFile already encodes at lines 181-189. One helper keeps both paths in agreement if the protected-file rule changes.

♻️ Proposed refactor

-  if (
-    stat.nlink !== 1n ||
-    stat.uid !== 0n ||
-    stat.gid !== 0n ||
-    Number(stat.mode & 0o777n) !== 0o400
-  ) {
+  if (!isProtectedManagedBootstrapFile(stat)) {
     fail("managed bootstrap envelope must be root:root mode 0400 with one link");
   }

readStableRegularFileSnapshot already proves the target is a regular file, so the added isFile() check does not change behavior.

🤖 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/image-runtime.ts` around lines 99 - 132,
Update readManagedBootstrapEnvelopeSnapshot to reuse
isProtectedManagedBootstrapFile for validating the snapshot stat metadata
instead of duplicating the nlink, uid, gid, and mode checks. Preserve the
existing failure message and identity validation behavior.

---

154-179: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Compose the two stat-comparison helpers.

sameClaimedManagedBootstrapFile repeats every field of sameStableManagedBootstrapFile except ctimeNs. Express the stable check as the claimed check plus ctimeNs equality. This removes the risk that a future field is added to only one helper.

♻️ Proposed refactor

 function sameStableManagedBootstrapFile(left: fs.BigIntStats, right: fs.BigIntStats): boolean {
-  return (
-    left.dev === right.dev &&
-    left.ino === right.ino &&
-    left.mode === right.mode &&
-    left.nlink === right.nlink &&
-    left.uid === right.uid &&
-    left.gid === right.gid &&
-    left.size === right.size &&
-    left.mtimeNs === right.mtimeNs &&
-    left.ctimeNs === right.ctimeNs
-  );
+  return sameClaimedManagedBootstrapFile(left, right) && left.ctimeNs === right.ctimeNs;
 }

🤖 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/image-runtime.ts` around lines 154 - 179,
Refactor sameStableManagedBootstrapFile to reuse sameClaimedManagedBootstrapFile
for all shared stat comparisons, then additionally require matching ctimeNs.
Remove the duplicated field checks while preserving both helpers’ existing
comparison behavior.

test/managed-bootstrap-trampoline.test.ts (1)

766-777: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert that the restart invoked claim recovery.

The mock node command at lines 652-653 removes both the request and the claim on every invocation. So the assertions at lines 770-772 pass even if the trampoline never runs --recover-bootstrap-claim on the restart. Add a count assertion on the recovery trace line. This makes the recovered-claim claim in the test title observable.

💚 Proposed change

       lines = fs.readFileSync(trace, "utf8").trim().split("\n");
+      expect(lines.filter((line) => line.includes("--recover-bootstrap-claim"))).toHaveLength(2);
       expect(lines.filter((line) => line.includes("--apply-bootstrap-file"))).toHaveLength(2);

As per path instructions: "Flag copied production algorithms, broad mocks that bypass the behavior under test, and conditionals that make a test pass without exercising its claim."

🤖 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 `@test/managed-bootstrap-trampoline.test.ts` around lines 766 - 777, Extend the
assertions in the restart scenario to verify the recovery path was invoked,
using the existing trace lines collected in lines. Add a count assertion for the
--recover-bootstrap-claim invocation alongside the existing
--apply-bootstrap-file, supervisor, and startup assertions, so the test observes
claim recovery rather than relying only on filesystem cleanup.

Source: Path instructions

ci/test-file-size-budget.json (1)

7-7: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Split the bootstrap cases before adding more lines.

The checker treats legacyMaxLines as both a maximum and a ratchet. Since the file is exactly 1874 lines, any line-count change fails CI unless the budget changes with it.

🤖 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 `@ci/test-file-size-budget.json` at line 7, Split the bootstrap test cases in
managed-startup-image-runtime.test.ts into a separate test file before adding
further lines, then update ci/test-file-size-budget.json so each resulting file
has an appropriate legacyMaxLines budget and no file remains ratcheted at the
exact 1874-line limit.

🤖 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 `@ci/test-file-size-budget.json`:
- Line 7: Split the bootstrap test cases in
managed-startup-image-runtime.test.ts into a separate test file before adding
further lines, then update ci/test-file-size-budget.json so each resulting file
has an appropriate legacyMaxLines budget and no file remains ratcheted at the
exact 1874-line limit.

In `@src/lib/onboard/managed-bootstrap/image-runtime.ts`:
- Around line 99-132: Update readManagedBootstrapEnvelopeSnapshot to reuse
isProtectedManagedBootstrapFile for validating the snapshot stat metadata
instead of duplicating the nlink, uid, gid, and mode checks. Preserve the
existing failure message and identity validation behavior.
- Around line 154-179: Refactor sameStableManagedBootstrapFile to reuse
sameClaimedManagedBootstrapFile for all shared stat comparisons, then
additionally require matching ctimeNs. Remove the duplicated field checks while
preserving both helpers’ existing comparison behavior.

In `@src/lib/onboard/managed-bootstrap/README.md`:
- Around line 193-199: In the managed-bootstrap README paragraph, update the
phrase “the same exact attempt” to “the same attempt” while leaving the rest of
the claim protocol description unchanged.

In `@src/lib/onboard/managed-startup-image-runtime.test.ts`:
- Around line 1197-1206: The applyManagedBootstrapEnvelope assertion in the
pre-claim replacement test must require the deterministic “changed before its
atomic claim” rejection instead of accepting either message; keep the separate
recoverManagedBootstrapEnvelopeClaim assertion for “identity does not match”
unchanged.
- Around line 550-568: Update the openSync mock in the managed startup runtime
tests to throw the missing-file error for every absent path when the requested
flags do not permit creation, while preserving descriptor allocation for
create-mode writes. Keep existing special handling and descriptor snapshots
unchanged for present files, and ensure missing request or claim reads fail at
openSync so readStableFile produces its expected error.

In `@test/managed-bootstrap-trampoline.test.ts`:
- Around line 766-777: Extend the assertions in the restart scenario to verify
the recovery path was invoked, using the existing trace lines collected in
lines. Add a count assertion for the --recover-bootstrap-claim invocation
alongside the existing --apply-bootstrap-file, supervisor, and startup
assertions, so the test observes claim recovery rather than relying only on
filesystem cleanup.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: cefbf62d-7fc1-4cb1-9fd0-990690a1d067

📥 Commits

Reviewing files that changed from the base of the PR and between 483b187 and a4e49f9.

📒 Files selected for processing (8)

• ci/test-file-size-budget.json
• scripts/managed-bootstrap-trampoline.sh
• src/lib/onboard/managed-bootstrap/README.md
• src/lib/onboard/managed-bootstrap/image-runtime.ts
• src/lib/onboard/managed-bootstrap/index.ts
• src/lib/onboard/managed-startup-bootstrap-image-runtime.test.ts
• src/lib/onboard/managed-startup-image-runtime.test.ts
• test/managed-bootstrap-trampoline.test.ts

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

• src/lib/onboard/managed-bootstrap/index.ts
• src/lib/onboard/managed-startup-bootstrap-image-runtime.test.ts