fix(runtime): close prior review debt

[ericksoa]

Summary

Closes the five still-valid unresolved CodeRabbit findings from the lower buildless stack and the same-surface advisor findings found during exact-head qualification without rewriting its green heads. Managed messaging selection now honors disabled channels through one normalized shared contract, the image-runtime entry guard is safe under ESM test imports, and dashboard-port tests are hermetic against ambient host values.

Related Issue

Part of #7744

Changes

• Normalize channel identifiers once in the shared enabled-plan helper, including disabled-channel and entry comparisons, while preserving declared channel order.
• Make post-agent-install render and build-file selection consume that shared helper and normalize both sides of render, step, channel, and hook comparisons; keep the direct image-build module self-contained and regression-test Node’s TypeScript ESM import path.
• Guard the CommonJS direct-entry check when the managed image runtime is imported through Vitest's ESM runner.
• Strip ambient NEMOCLAW_DASHBOARD_PORT and CHAT_UI_URL from wrapper scenarios before applying explicit test inputs.
• Reject persisted channel IDs that collide after canonical normalization and exclude build files whose hook owner is ambiguous or unresolved.
• Require the canonical lowercase, unpadded identity at the persisted-plan boundary across channels, disabled lists, credentials, policy, render, build, runtime-setup, state, health, and nested channel-owned references.
• Add focused regressions for mixed-case and whitespace channel IDs, disabled channels, canonical ordering, hook phases, ambiguous or missing hook references, and inherited dashboard environment values.
• Keep the slice inert: no runtime registration, buildless activation, Podman selector, workflow, or support claim 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 user-facing behavior changes
• Docs not applicable — justification: This corrects internal selection and test-import behavior in dormant buildless scaffolding; it adds no command, configuration, default, runtime selector, workflow, or support claim.
• 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: Exact-slice audit verified disabled channels and ambiguous or unresolved hook references fail closed, normalization is symmetric, declared ordering is stable, the entry guard preserves CommonJS execution, and port tests restore the parent environment.
• 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: no-docs-needed
• Evidence: The exact seven-file diff changes internal TypeScript selection/runtime guards and focused tests only; no documentation path or user-visible supported behavior changes.
• 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 — command/result or justification: 97 exact-head focused parser, messaging-selection, direct TypeScript ESM import, managed image-runtime, and entrypoint-wrapper tests passed; the branchless-test scan, build:cli, typecheck:cli, and exact-head validate:pr passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Exact-head required GitHub CI and protected E2E are the broad gate for this small dormant follow-up; they are running for locally validated head 771f48c47c0aaa1d51511d172fffc691e6c9ac76.
• 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: PR3.5a fix(onboard): harden managed startup contracts #7973 branch feat/buildless-managed-contract-hardening at 7d51947c870b8f1de2caa1d33e6e9d6e98d11346.
• This slice: PR3.5b branch feat/buildless-coderabbit-debt at 771f48c47c0aaa1d51511d172fffc691e6c9ac76.
• Next: PR3.5c introduces the inert runtime-parameterized protected-E2E foundation; it is not part of this review diff.
• Production buildless and Podman support remain disabled until their complete all-agent qualification and activation gates pass.

---

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

Summary by CodeRabbit

• Bug Fixes
  • Improved messaging-plan validation by detecting duplicate, noncanonical, and mismatched channel references.
  • Ensured disabled channels are consistently excluded from messaging, rendering, and post-install build selections.
  • Prevented ambiguous post-install hook references from being selected.
  • Improved CLI startup compatibility across supported runtime environments.
• Reliability
  • Standardized channel handling and validation across nested messaging configurations for more predictable setup behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change centralizes messaging channel selection, normalizes channel IDs, and expands plan validation across nested references. It also hardens the runtime entrypoint guard and isolates environment variables in entrypoint tests.

Changes

Messaging plan flow

Layer / File(s)	Summary
Shared channel selection and post-install filtering src/lib/messaging/post-agent-install-selection.ts, src/lib/messaging/applier/plan-filter.ts, src/lib/messaging/post-agent-install-selection.test.ts	Shared helpers normalize channel IDs, filter enabled channels, and select matching renders and post-install build files. The applier now re-exports these helpers.
Canonical channel validation src/lib/messaging/plan-validation.ts, src/lib/messaging/plan-validation.test.ts	Plan parsing rejects invalid, noncanonical, and duplicate channel IDs across direct and nested references.

Runtime entrypoint test isolation

Layer / File(s)	Summary
Entrypoint guard and environment isolation src/lib/onboard/managed-startup/image-runtime.ts, test/entrypoint-env-wrapper.test.ts	The entrypoint checks both require and module. Tests sanitize inherited dashboard variables, verify default-port behavior, and restore stubs.

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

Sequence Diagram(s)

sequenceDiagram
  participant Plan
  participant ChannelSelection
  participant BuildSelection
  Plan->>ChannelSelection: normalize and filter enabled channels
  ChannelSelection->>BuildSelection: provide enabled channel IDs
  BuildSelection->>Plan: return matching post-agent-install build files

Loading

Possibly related PRs

• NVIDIA/NemoClaw#6700: Related Vitest environment-stubbing and state-isolation changes.

Suggested labels: chore

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title identifies a runtime fix but does not describe the primary messaging validation and selection changes.	Mention the main change, such as canonical messaging channel validation and selection fixes, in the title.

✅ Passed checks (3 passed)

Check name	Status	Explanation
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.

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Fix failing CI checks

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/buildless-coderabbit-debt

---

_{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 771f48c in the feat/buildless-coder... branch remains at 96%, unchanged from commit 387cb08 in the feat/buildless-manag... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 771f48c in the feat/buildless-coder... branch remains at 81%, unchanged from commit 387cb08 in the feat/buildless-manag... branch.

Show a code coverage summary of the most impacted files.

File	feat/buildless-manag... 387cb08	feat/buildless-coder... 771f48c	+/-
src/lib/messagi.../plan-filter.ts	100%	0%	-100%
src/lib/onboard...mage-runtime.ts	93%	50%	-43%
src/lib/onboard.../application.ts	86%	84%	-2%
src/lib/onboard...file-builder.ts	90%	90%	0%
src/lib/onboard...-environment.ts	92%	96%	+4%
src/lib/onboard...-transaction.ts	0%	78%	+78%
src/lib/onboard...p/root-apply.ts	0%	84%	+84%
src/lib/messagi...ll-selection.ts	0%	84%	+84%
src/lib/onboard...shared-state.ts	0%	87%	+87%
src/lib/onboard...r-root-apply.ts	0%	94%	+94%

---

_{Updated July 31, 2026 08:49 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 E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

Recommended E2E: channels-add-remove, channels-stop-start, onboard-repair, onboard-resume, 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

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

✅ 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]

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/messaging/post-agent-install-selection.ts`:
- Around line 91-112: Update selectEnabledPostAgentInstallBuildFiles so an
unresolved step.hookId is excluded rather than treated as unrestricted:
distinguish a missing hook returned by find from a resolved hook, and return
true only when the matching hook exists and its phase is "post-agent-install"
(or otherwise satisfies the intended phase rule). Add a regression test covering
a hookId that does not match any hook on the matched channel.

🪄 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: 99fdd735-17c2-4887-b0c4-715e121faadc

📥 Commits

Reviewing files that changed from the base of the PR and between a0f12f1 and 76c54d4.

📒 Files selected for processing (7)

• src/lib/messaging/applier/plan-filter.ts
• src/lib/messaging/plan-validation.test.ts
• src/lib/messaging/plan-validation.ts
• src/lib/messaging/post-agent-install-selection.test.ts
• src/lib/messaging/post-agent-install-selection.ts
• src/lib/onboard/managed-startup/image-runtime.ts
• test/entrypoint-env-wrapper.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.