fix(ci): provision pinned Pi search tools

[ericksoa]

Summary

Makes the CLI coverage shards provision Pi's required filesystem search tools before any untrusted test code runs. This removes the intermittent shard failure where Pi could neither find nor acquire fd or rg on a GitHub-hosted runner.

The change is limited to CI execution and does not alter NemoClaw runtime behavior or support claims.

Related Issue

Relates #7744

Changes

• Pin the affected PR and main CLI shard jobs to Ubuntu 24.04 so the package contract is stable.
• Install exact Noble packages fd-find=9.0.0-1 and ripgrep=14.1.0-1 before Pi runs.
• Verify both installed package versions and executable-reported versions, failing closed on drift.
• Add a capability-detected PR bootstrap because pull-request jobs execute the composite action from the base-trusted checkout.
• Suppress the bootstrap once the trusted composite action owns the same exact contract.
• Add an executable workflow contract covering runner selection, ordering, version pins, and bootstrap/action parity.

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 internal CI provisioning only and does not change user-facing NemoClaw behavior.
• 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-head review covers the base-trusted action boundary, pre-untrusted-code ordering, immutable runner selection, exact package pins, and fail-closed version verification through an executable contract test.
• 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: Exact-head review found only internal CI provisioning and regression-test changes; no user-facing documentation surface changed.
• 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 — npx vitest run test/ci-cli-coverage-pi-tools-workflow.test.ts test/pr-workflow-contract.test.ts passed 22/22 on the exact head.
• Applicable broad gate passed — npm run check:diff, repository/config validation, source-shape, test-size, project-membership, and test-title checks passed on the exact head.
• 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)

Risk Plan

• Primary risk: package or runner-image drift could break a CI shard before tests execute.
• Containment: the job is pinned to Ubuntu 24.04 and verifies both exact package and binary versions before invoking Pi.
• Trust boundary: the PR bootstrap runs before the base-trusted composite action only when that action lacks the reviewed capability marker; both paths share byte-identical installation logic.
• Rollback: this five-file CI-only patch is independently revertible.

Stack

• Base: current main at b76a70d420fc1b316a2313fca0f7d71b5a00f5c8.
• Exact head: 9752e3a76b698b65f21efe06bb9f03278738bb37.
• Original reviewed head e3a2e8685296d82abcea51632cb7f2b4d2aaa724 is retained as append-only ancestry; the first-parent PR patch remains five files, +215/-2, with stable patch ID 0e8d44a205201d5e45e2644ebc9b7c50c6454764.
• This CI reliability fix is independent of runtime activation and does not enable buildless or Podman support.

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

Summary by CodeRabbit

• Reliability

  • CLI coverage workflows now run on a consistent Ubuntu 24.04 environment.
  • Required search tools are installed at verified, pinned versions when unavailable in the CI environment, improving consistency and reducing unexpected test failures.

• Testing

  • Added automated validation for tool availability, version checks, workflow configuration, installation behavior, and execution order.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 36441c6d-f4b4-4973-9746-03e717dfe825

📥 Commits

Reviewing files that changed from the base of the PR and between 0af50cb and 9752e3a.

📒 Files selected for processing (1)

• test/ci-cli-coverage-pi-tools-workflow.test.ts

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

• test/ci-cli-coverage-pi-tools-workflow.test.ts

---

📝 Walkthrough

Walkthrough

CLI coverage workflows now use Ubuntu 24.04. They provision pinned fd-find and ripgrep tools when required and validate package and binary versions. Contract tests cover workflow wiring and isolated installation behavior.

Changes

CLI coverage tool provisioning

Layer / File(s)	Summary
Runner and conditional tool provisioning .github/workflows/main.yaml, .github/workflows/pr.yaml	CLI shard jobs use Ubuntu 24.04. Pull-request shards detect trusted tool provisioning and install pinned packages when required.
Composite action tool validation .github/actions/ci-cli-coverage-shard/action.yaml	The composite action validates installed package versions, executable availability, and reported binary versions.
Workflow and installation contract coverage test/ci-cli-coverage-pi-tools-workflow.test.ts, ci/source-shape-test-budget.json	Tests validate workflow configuration and isolated installation behavior. The source-shape budget records the security exception.

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

Suggested labels: area: ci, bug-fix

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main CI change: provisioning pinned Pi search tools.
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.

✨ 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/ci-cli-shard-ripgrep-20260802

---

_{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 9752e3a in the fix/ci-cli-shard-rip... branch remains at 96%, unchanged from commit b76a70d in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 9752e3a in the fix/ci-cli-shard-rip... branch remains at 81%, unchanged from commit b76a70d in the main branch.

Show a code coverage summary of the most impacted files.

File	main b76a70d	fix/ci-cli-shard-rip... 9752e3a	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/onboard...shboard-port.ts	96%	90%	-6%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/state/g...way-registry.ts	94%	94%	0%
src/lib/state/m...-acquisition.ts	75%	75%	0%
src/lib/tunnel/services.ts	76%	76%	0%

---

_{Updated August 03, 2026 02:16 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 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.

• Pi at .github/actions/ci-cli-coverage-shard/action.yaml:60: selected only by the second-opinion lane as established.
• provision at .github/workflows/pr.yaml:422: selected only by the second-opinion lane as established.

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 — Pi search tools at .github/actions/ci-cli-coverage-shard/action.yaml:60: Keep this term in workflow labels and literals. If it appears in user-facing explanatory text, define it as fd-find and ripgrep at first use.
• established — bootstrap at .github/workflows/pr.yaml:424: Retain the established term with its capability condition.

E2E guidance

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

Recommended E2E: cloud-inference, cloud-onboard, security-posture

Workflow run details

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

[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 `@test/ci-cli-coverage-pi-tools-workflow.test.ts`:
- Around line 23-27: Replace the explicit conditional in requiredStep with an
assertion-based check, or reuse an existing shared required-step helper if
available. Preserve the current behavior of returning the named WorkflowStep and
reporting missing steps while removing the literal if statement from the test
file.

🪄 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: e426875a-8541-4b52-ad4d-5130f473cc0d

📥 Commits

Reviewing files that changed from the base of the PR and between b76a70d and 0af50cb.

📒 Files selected for processing (5)

• .github/actions/ci-cli-coverage-shard/action.yaml
• .github/workflows/main.yaml
• .github/workflows/pr.yaml
• ci/source-shape-test-budget.json
• test/ci-cli-coverage-pi-tools-workflow.test.ts