fix(inference): restore qualification loopback publish

[apurvvkumaria]

Summary

The llama.cpp qualification runner launches Docker directly and cannot rely on the normal lifecycle provider to publish its guarded port. This change completes the qualification-only loopback adapter by placing exactly one declarative mapping immediately before the image reference and failing closed when the materialized argument boundary conflicts, while the shared materializer and product lifecycle remain unchanged.

Related Issue

Fixes #8667

Changes

• Replace the qualification runner's --entrypoint position heuristic with an adapter that requires exactly one image-reference boundary, validates the host and container ports, and rejects long, short, attached, and publish-all Docker publication options before the image.
• Emit 127.0.0.1::<container-port> for ephemeral qualification and 127.0.0.1:<host-port>:<container-port> for fixed-port agent qualification, with the container port derived from the validated recipe.
• Keep the shared host-local materializer non-publishing and leave the normal Docker lifecycle provider unchanged; ordinary launches use that provider, while this protected runner calls docker run, docker port, and the live probe directly.
• Expand behavior coverage for mapping count, loopback-only binding, declarative port authority, Docker option ordering, image-boundary failures, request-guard arguments, and existing runtime hardening.

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 changes only the protected qualification adapter; the documented product lifecycle and fixed authenticated loopback listener remain unchanged.
• 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: Codex Desktop completed the final nine-category review; no blocker, public binding, authentication bypass, port-authority drift, or normal-launch change was found. The protected live-run gap is recorded below.
• 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: No documentation files changed. docs/inference/set-up-llama-cpp.mdx remains accurate for the normal managed runtime.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable
• Station profile/scenario: Not applicable
• Result: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• Supporting evidence: Not applicable

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 — npx vitest run --project integration test/llama-cpp-dgx-spark-qualification-runner.test.ts test/llama-cpp-dgx-spark-qualification-contract.test.ts (31 passed); npx vitest run --project cli src/lib/inference/llama-cpp/host-local-runtime.test.ts src/lib/onboard/runtime-provider/docker-llama-cpp-managed-lifecycle.test.ts (57 passed); npm run typecheck:cli and npx prek run --from-ref main --to-ref HEAD 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)

Full PR CI reached a terminal state with 38 passed, 14 skipped, and one unrelated root failure plus two downstream aggregators. CLI shard 5 reproduced the deterministic current-main regression tracked in #8674 on both its initial run and one retry: the stale-recovery fixture upgrades OpenShell 0.0.99 to 0.0.101, then stops on its live-route mismatch before reaching the expected assertion. No maintainer acceptance is recorded, so the non-success checkbox remains unchecked.

Protected DGX Spark qualification was not run pre-merge. The local host is Darwin/ARM64 without the required GB10 GPU or model, and the protected PR workflow deliberately executes this runner script from trusted main rather than the candidate checkout. A trusted-main protected run after merge remains the live validation step for docker port resolution and the health probe.

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

[coderabbitai]

📝 Walkthrough

Walkthrough

The qualification runner adds validated loopback-only Docker port publishing. Server argument construction uses the new helper. Tests cover ephemeral and fixed host ports, alternate plan ports, image validation, duplicate publish rejection, GPU flags, and security options.

Changes

Qualification loopback publishing

Layer / File(s)	Summary
Loopback publish argument helper scripts/checks/run-llama-cpp-dgx-spark-qualification.mts, test/llama-cpp-dgx-spark-qualification-runner.test.ts	Adds insertQualificationLoopbackPublishArgv with image, publish-flag, and port validation. Tests cover valid insertion and invalid argument combinations.
Server argument integration scripts/checks/run-llama-cpp-dgx-spark-qualification.mts, test/llama-cpp-dgx-spark-qualification-runner.test.ts	buildServerContainerArgv uses the helper. Tests verify YAML-bound ports, fixed host mappings, GPU flags, and security options.

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

Possibly related PRs

• NVIDIA/NemoClaw#8512: Both changes modify qualification-container port-publishing logic.
• NVIDIA/NemoClaw#8532: Both changes modify the qualification runner and Docker port-publishing paths.
• NVIDIA/NemoClaw#8565: Both changes cover llama.cpp loopback and fixed host/container port mappings.

Suggested labels: area: inference, platform: dgx-spark, bug-fix

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy #8667 by adding validated ephemeral and fixed loopback mappings while preserving the shared materializer architecture.
Out of Scope Changes check	✅ Passed	The implementation and tests remain within the linked issue scope and do not modify the shared materializer or lifecycle provider.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: restoring loopback publishing for the inference qualification runner.

✨ 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 codex/fix-8667-qualification-loopback-publish

---

_{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 a32183b in the codex/fix-8667-quali... branch remains at 96%, unchanged from commit 5003bce in the main branch.

---

_{Updated August 10, 2026 03:28 UTC}

[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 `@scripts/checks/run-llama-cpp-dgx-spark-qualification.mts`:
- Around line 329-331: Update the publish-argument validation around the
--publish check to reject every Docker port-publication spelling: -p,
--publish=<mapping>, attached -p<mapping>, -P, and --publish-all, while
retaining rejection of --publish. Add tests covering each spelling before the
qualification materializer inserts its loopback mapping.

🪄 Autofix

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: d54da0d2-8e9b-4e1e-a485-0ce50f5f145a

📥 Commits

Reviewing files that changed from the base of the PR and between 352680c and 3b2aae5.

📒 Files selected for processing (2)

• scripts/checks/run-llama-cpp-dgx-spark-qualification.mts
• test/llama-cpp-dgx-spark-qualification-runner.test.ts

[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 terminology decisions differ; normalized E2E selections match; severity counts match.

2 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• materialized argument vector at scripts/checks/run-llama-cpp-dgx-spark-qualification.mts:332: selected only by the second-opinion lane as define.
• insertQualificationLoopbackPublishArgv at scripts/checks/run-llama-cpp-dgx-spark-qualification.mts:321: selected only by the second-opinion lane as established.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

2 semantic terminology decisions

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

• established — image boundary at test/llama-cpp-dgx-spark-qualification-runner.test.ts:446: Keep "image boundary" for this Docker argument boundary.
• justified — loopback mapping at test/llama-cpp-dgx-spark-qualification-runner.test.ts:446: Keep "loopback mapping" because it identifies the loopback-bound Docker publication asserted by this test.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: managed-image-multiarch-startup

1 optional E2E recommendation

• llama-cpp-dgx-spark-qualification

Workflow run details

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

[senthilr-nv]

Post-merge follow-ups:

• test(rebuild): keep stale-recovery fixture compatible with OpenShell 0.0.101 #8674 is the unrelated pre-existing CI fixture failure observed in the required check; test(rebuild): align stale recovery fixture with OpenShell 0.0.101 #8678 is the targeted fix and currently needs review.
• fix(inference): restore loopback port publishing in the llama.cpp qualification runner #8676 addresses the same accepted issue and is now conflicting/redundant; close it after confirming it contains no unique work worth retaining.

No follow-up code change is needed for the merged #8672 head. The protected DGX Spark live qualification remains optional evidence, not a merge-gate blocker.