perf(images): short-circuit reachable tag scan

[apurvvkumaria]

Summary

This replacement rebuilds #7554 from current main while retaining Ho Lim as Author for the production optimization.
It reduces fallback reachability probes without changing tag selection, trust, or local fallback behavior.

Related Issue

Closes #7249.
Supersedes #7554 without closing it.

Changes

• Parse the complete remote tag response, preserve peeled annotated-tag commits, and order candidates with the existing semantic-version comparator.
• Stop after the first reachable candidate while preserving stable, prerelease, comparator-equivalent, and local-fallback behavior.
• Add deterministic probe coverage for one-probe success, two-probe fallback, annotated tags, exhaustion, and comparator-equivalent textual tags.
• Preserve Ho Lim as Author of commit bf86e27a8, replayed from the verified perf(images): short-circuit reachable tag scan #7554 production commit cc02a6b64.
• Credit dfernandez365-rgb's earlier verified candidate 0e1a0e59 as prior art, as recorded in #7249. The replacement does not claim that perf(images): short-circuit reachable tag scan #7554 copied the candidate.
• Documentation writer receipt for exact head b67bf3a5a: no docs change required because the documented selection contract is unchanged.

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: internal reachability optimization; commands, configuration, output, and selection behavior are 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: exact-head nine-category maintainer review passed; published-image trust, digest pinning, override provenance, and fallback semantics are unchanged.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• 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: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved release tag selection to consistently choose the newest reachable version from the remote repository.
  • Correctly checks tag reachability before selecting a release, avoiding unreachable or stale tags.
  • Preserves the nearest local version as a fallback when no remote release tag is reachable.
  • Maintains consistent ordering when multiple tags represent equivalent versions.

[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: a30cb393-97a3-47f5-b13d-1aed520b8855

📥 Commits

Reviewing files that changed from the base of the PR and between 3e930f2 and b67bf3a.

📒 Files selected for processing (2)

• src/lib/sandbox-base-image/source-identity.test.ts
• src/lib/sandbox-base-image/source-identity.ts

---

📝 Walkthrough

Walkthrough

The remote tag resolver now probes sorted release candidates newest-first and returns on the first reachable commit. Tests add Trace2 instrumentation and cover annotated tags, probe counts, comparator-equivalent spellings, unreachable candidates, and local fallback.

Changes

Remote release tag resolution

Layer / File(s)	Summary
Ordered reachability selection src/lib/sandbox-base-image/source-identity.ts	gitRemoteReachableVersionTag materializes sorted tag/commit candidates, checks them newest-first, and returns the first ancestor of HEAD.
Reachability probe coverage src/lib/sandbox-base-image/source-identity.test.ts	Adds Git Trace2 helpers and tests for reachable, unreachable, annotated, comparator-equivalent, and local-fallback tag scenarios with expected probe counts.

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

Sequence Diagram(s)

sequenceDiagram
  participant Resolver as gitRemoteReachableVersionTag
  participant Remote as git ls-remote
  participant Git as git merge-base
  Resolver->>Remote: collect remote release tags and peeled commits
  Resolver->>Git: probe candidates newest-first
  Git-->>Resolver: return ancestor result
  Resolver-->>Resolver: select first reachable tag or local fallback

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7554: Both update remote tag reachability selection and add Trace2-based probe-count tests.

Suggested labels: area: sandbox

Suggested reviewers: cv, senthilr-nv

🚥 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 change: short-circuiting the reachable tag scan.
Linked Issues check	✅ Passed	The code and tests implement newest-first short-circuiting, preserve peeled annotated tags, and cover local fallback and ordering cases.
Out of Scope Changes check	✅ Passed	The PR only changes the reachability scan and its tests, with no unrelated scope visible.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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/7249-reachable-tag-short-circuit-credit

---

_{Comment @coderabbitai help to get the list of available commands.}

[apurvvkumaria]

Exact-head maintainer evidence for b67bf3a5a on base 3e930f213:

• Authorship: bf86e27a8 retains Ho Lim as Author for the production change. b67bf3a5a contains only the comparator-equivalence regression. GitHub reports both commits as Verified, and each commit has the matching Signed-off-by: declaration.
• Prior art: dfernandez365-rgb published verified candidate 0e1a0e59 on Base-image fallback scans every remote release tag before selecting the newest reachable one #7249 before perf(images): short-circuit reachable tag scan #7554. The issue prescribed the same minimal ordered loop, while perf(images): short-circuit reachable tag scan #7554 used a distinct Trace2 test harness. This replacement credits that candidate as prior art and does not claim that perf(images): short-circuit reachable tag scan #7554 copied it.
• Focused behavior: npx vitest run --project cli src/lib/sandbox-base-image/source-identity.test.ts --reporter=verbose passed, 29 tests.
• Repository gates: npm run build:cli and npm run check:diff passed. The normal push also passed the CLI TypeScript and package/tag sync pre-push gates.
• Documentation writer: reviewed exact head b67bf3a5a; no docs change is required because commands, configuration, output, schema, and tag-selection behavior are unchanged.

Security review:

1. Secrets and credentials: PASS. No credential handling or literals changed.
2. Input validation: PASS. Existing tag normalization and complete remote-response parsing remain unchanged.
3. Authentication and authorization: PASS. No authentication boundary changed.
4. Dependencies: PASS. No dependency changed.
5. Error handling and logging: PASS. Remote failure and timeout behavior keep the existing fail-safe local fallback, and no logging changed.
6. Cryptography and data protection: PASS. No cryptographic operation changed.
7. Configuration and security headers: PASS. No configuration or HTTP surface changed.
8. Security testing: PASS. Tests cover annotated-tag peeling, unreachable candidates, full exhaustion, local fallback, prerelease ordering, comparator-equivalent text, and exact probe counts.
9. Holistic security posture: PASS. Published-image trust, digest pinning, override provenance, and repository refs remain unchanged.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit b67bf3a in the codex/7249-reachable... branch remains at 96%, unchanged from commit 3e930f2 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit b67bf3a in the codex/7249-reachable... branch remains at 81%, unchanged from commit 3e930f2 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 3e930f2	codex/7249-reachable... b67bf3a	+/-
src/lib/platform.ts	89%	84%	-5%
src/lib/shields/index.ts	72%	71%	-1%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	88%	+1%
src/lib/onboard/tracing.ts	80%	85%	+5%

---

_{Updated July 26, 2026 05:07 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: None

1 optional E2E recommendation

• sandbox-rebuild

Workflow run details

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