fix(platform): provision pinned OpenShell for macOS shards

[cjagwani]

Summary

Makes the four-way macOS platform watcher usable with NemoClaw's fail-closed Homebrew contract. Each macOS shard now installs the repository-pinned, checksum-verified OpenShell formula before Vitest, while platform-only fixtures remain isolated from unrelated host Homebrew state.

Related Issue

Part of #7451.

Changes

• Install the pinned OpenShell Homebrew formula in every macOS platform shard through scripts/install-openshell.sh.
• Run that installer non-interactively with GH_TOKEN and GITHUB_TOKEN explicitly unset.
• Lock the installer step, ordering, environment, and token-sanitized command in the platform workflow contract test.
• Force systemd gateway ownership fixtures to exercise Linux semantics explicitly.
• Give spawned onboarding fixtures a controlled PATH that excludes host Homebrew binaries.
• Document that platform matrix fail-fast is disabled and that each macOS shard provisions pinned OpenShell.

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:
• 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: Nine-category review found no weakened trust boundary. The CI-only install uses NemoClaw's pinned, checksum-verifying installer, unsets GitHub tokens, and leaves production fail-closed Homebrew validation unchanged.
• 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: docs-updated
• Evidence: test/e2e/docs/README.md accurately records pinned OpenShell provisioning, shard budgets, fail-fast behavior, and WSL root-contract routing; no Fern or changelog change is appropriate.
• 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 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 — gateway-host-runtime.test.ts 27/27; onboard-exit-handler.test.ts 4/4; platform workflow contract 2/2; npm run test:changed passed with no additional test files selected.
• 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 to one focused CI-platform correction.
• 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)

npm run docs exited successfully with 0 errors; Fern reported 2 existing warnings.

---

Signed-off-by: Charan Jagwani cjagwani@nvidia.com

Summary by CodeRabbit

• Tests

  • Improved onboarding test reliability by standardizing the simulated platform and controlling the test execution PATH for spawned scripts.
  • Strengthened coverage for onboarding bootstrap and later nonzero exit handling scenarios.

• Documentation

  • Clarified CI test coverage details, including four independent Vitest shards on macOS and WSL with fail-fast disabled and updated shard timing expectations.

• CI / Workflow

  • Updated the macOS test workflow to install a pinned runtime (with non-interactive mode) before running remaining macOS steps, and adjusted workflow validation accordingly.

[coderabbitai]

📝 Walkthrough

Walkthrough

Onboarding tests now force Linux platform detection and fixture-specific executable paths for spawned scripts. The macOS Vitest workflow installs pinned OpenShell, with tests validating the step and documentation describing four independent macOS and WSL shards.

Changes

Onboarding test runtime

Layer / File(s)	Summary
Linux platform test setup src/lib/onboard/gateway-host-runtime.test.ts	Vitest lifecycle imports and a per-test Linux process.platform stub were added.
Fixture path for spawned scripts test/onboard-exit-handler.test.ts	A fixture PATH is constructed and applied to both spawned Node scripts.

macOS OpenShell CI setup

Layer / File(s)	Summary
Pinned OpenShell workflow step .github/workflows/platform-vitest-main.yaml, test/platform-vitest-main-workflow.test.ts	The macOS job installs pinned OpenShell before dependencies, while tests verify step ordering, environment, and command.
Vitest shard execution documentation test/e2e/docs/README.md	The workflow documentation describes four independent macOS and WSL shards with fail-fast disabled and WSL root-required contracts on shard 1.

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

Possibly related PRs

• NVIDIA/NemoClaw#7319: Updates the install script behavior used by the pinned OpenShell macOS workflow step.
• NVIDIA/NemoClaw#7548: Also updates the macOS platform workflow and its step-ordering tests.

Suggested labels: platform: macos, area: ci, area: install, bug-fix

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

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

✨ 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/7451-platform-doc-fail-fast

---

_{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 dd69a84 in the codex/7451-platform-... branch remains at 96%, unchanged from commit b4ef301 in the main branch.

---

_{Updated July 26, 2026 01:53 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 `@test/onboard-exit-handler.test.ts`:
- Around line 24-26: Update ONBOARD_FIXTURE_PATH to include only the explicit
fixture and system directories, removing path.dirname(process.execPath). Ensure
the affected spawned flows invoke Node using process.execPath directly rather
than resolving it through PATH, including the additional occurrences identified
in the comment.

🪄 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: 5246603b-1390-4548-a085-93e8df088eef

📥 Commits

Reviewing files that changed from the base of the PR and between 029c7aa and be59d80.

📒 Files selected for processing (3)

• src/lib/onboard/gateway-host-runtime.test.ts
• test/e2e/docs/README.md
• test/onboard-exit-handler.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 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: cloud-onboard

1 optional E2E recommendation

• openshell-version-pin

Workflow run details

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