fix(installer): fast-fail on Intel Mac before any download (#7297)

[jason-ma-nv]

Summary

The public installer previously cloned NemoClaw on Intel macOS before it failed because OpenShell supports Apple Silicon only. It now rejects Intel macOS before ref resolution or network work and reports the supported architecture.

Product scope verdict: PASS. This fixes an existing public-installer defect reported in #7297 and adds no integration, recipe, image, third-party stack, or supported product surface.

Related Issue

Fixes #7297

Changes

• Add an installer bootstrap guard that rejects Darwin on x86_64 before release-ref resolution or clone.
• Preserve --help and --version behavior, plus installation on Apple Silicon macOS and Linux.
• Add a focused test with distinct sentinels for ref resolution, clone, and installer execution.

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: Canonical docs already require Apple Silicon for macOS and list Intel macOS as unsupported. The change affects rejection timing and message clarity, not the support contract.
• 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: Automated nine-category review passed for PR SHA 48b28e5 and base SHA fe56943 with no findings: fix(installer): fast-fail on Intel Mac before any download (#7297) #7299 (comment). This does not claim human sensitive-path approval.
• 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: docs/get-started/prerequisites.mdx already identifies Apple Silicon as the tested macOS platform, and docs/reference/platform-support.mdx lists Intel macOS as unsupported. The diff does not change the support contract or installation procedure.
• Agent: Codex Desktop
• PR: fix(installer): fast-fail on Intel Mac before any download (#7297) #7299

DGX Station Hardware Evidence

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

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 check:diff passed 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: npx vitest run --project integration test/install-macos-arch-guard.test.ts passed 4/4.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; the diff changes one installer guard and its focused test.
• 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: Jason Ma jama@nvidia.com
Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • The installer now detects unsupported Intel-based Macs and stops before downloading or running installation steps.
  • Apple Silicon Macs and supported Linux systems continue through the installation process as expected.

[coderabbitai]

📝 Walkthrough

Walkthrough

The installer bootstrap now rejects Intel macOS before downloading or cloning. Tests emulate supported and unsupported OS/architecture combinations and verify the corresponding bootstrap outcomes.

Changes

Platform compatibility

Layer / File(s)	Summary
Add and invoke platform guard install.sh	Adds require_supported_platform to reject macOS x86_64, and invokes it before install ref resolution and repository cloning.
Test supported and unsupported platforms test/install-macos-arch-guard.test.ts	Stubs uname to verify Intel macOS fails before the installer entrypoint, while Apple Silicon macOS and Linux reach it.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR adds an early macOS x86_64 guard and test coverage, matching the issue's fast-fail, message, and no-download requirements.
Out of Scope Changes check	✅ Passed	The changes stay focused on the installer guard and its test coverage, with no obvious unrelated additions.
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 accurately summarizes the main change: the installer now fails early on Intel Macs before downloading or cloning.

✨ 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/7297-macos-intel-fast-fail

---

_{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 48b28e5 in the fix/7297-macos-intel... branch remains at 96%, unchanged from commit fe56943 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 48b28e5 in the fix/7297-macos-intel... branch remains at 80%, unchanged from commit fe56943 in the main branch.

Show a code coverage summary of the most impacted files.

File	main fe56943	fix/7297-macos-intel... 48b28e5	+/-
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/state/m...ock-identity.ts	95%	95%	0%
src/lib/state/m...lock-storage.ts	97%	97%	0%
src/lib/adapter...shell/client.ts	88%	90%	+2%
src/lib/state/m...-acquisition.ts	84%	87%	+3%

---

_{Updated July 23, 2026 18:29 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 1 warning · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 more warning, the same number of suggestions.

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: cloud-onboard

1 optional E2E recommendation

• bootstrap-install-smoke

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/install-macos-arch-guard.test.ts`:
- Around line 20-31: Strengthen runBootstrap so the test stubs both
resolve_release_tag and clone_nemoclaw_ref with distinct failure/sentinel
markers, alongside exec_installer_from_ref. Add assertions for Intel macOS that
none of these preflight or download markers appear, proving bootstrap_main exits
before ref resolution or cloning rather than only skipping the downstream
installer call.

🪄 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: d13bbd77-1ad7-43c9-a84c-7c636e914013

📥 Commits

Reviewing files that changed from the base of the PR and between d5fa194 and 8e98a1b.

📒 Files selected for processing (2)

• install.sh
• test/install-macos-arch-guard.test.ts

[senthilr-nv]

Automated security review — PR SHA 48b28e5, base SHA fe56943

Verdict: PASS. No security finding blocks independent human review. This is an automated nine-category review, not human sensitive-path approval.

Findings: None.

Category	Verdict	Evidence
Secrets and credentials	PASS	The diff adds no secret, credential, token, key, or sensitive log data.
Input validation and sanitization	PASS	The guard compares uname output with exact OS and architecture values. It does not evaluate or interpolate user input.
Authentication and authorization	PASS	The diff changes no identity, permission, endpoint, or resource-access path.
Dependencies and third-party libraries	PASS	The diff adds no dependency or registry change.
Error handling and logging	PASS	The new error identifies an unsupported platform and exposes no internal state or sensitive data.
Cryptography and data protection	PASS	The diff changes no cryptographic or data-protection behavior.
Configuration and security headers	PASS	The diff changes no container, service, port, CORS, CSP, permission, or runtime configuration.
Security testing	PASS	The focused test proves Intel macOS exits before ref resolution, clone, or installer execution, and proves supported platforms continue.
System security	PASS	The guard reduces exposure by rejecting an unsupported platform before network work. It does not weaken an existing control.

Files reviewed:

• install.sh
• test/install-macos-arch-guard.test.ts

[senthilr-nv]

Approved for head 48b28e5 against base fe56943 after all required checks and exact-pair E2E gates passed.