perf(readiness): reduce Homebrew trust operations

[ericksoa]

Outcome

macOS gateway readiness now grants temporary Homebrew formula trust once per observation. The live observation sequence fell from 10 trust-wrapper calls and 119.95 seconds to 1 trust-wrapper call and 9.46 seconds on the reproducing Mac, below the 30-second freshness window.

Reason

Each trusted wrapper call grants and removes formula trust. Repeating identical formula reads and using Homebrew formula evaluation for both service samples made a healthy gateway observation stale before onboarding could use it.

Related issues

Fixes #11112

Changes

• Expose the existing checksum-verified Homebrew operation runner so readiness can cache one successful formula identity result for one observation.
• Use wrapped brew info --json=v2 as the single source for installed-keg state, official tap identity, and the exact formula-defined service and gateway paths.
• Sample both supported launchd labels twice with launchctl print. Require one running job, its exact formula-defined program, one positive PID, and the expected gateway binary.
• Clear formula evidence after every managed or external observation.
• Extend the Homebrew 6 readiness and service regressions for cache lifetime, repeated launchd samples, missing installations, malformed formula service paths, foreign programs, malformed PIDs, and ambiguous labels.

Verification

• npm exec vitest -- run --project cli src/lib/readiness/gateway-production.test.ts src/lib/onboard/docker-driver-gateway-service-homebrew.test.ts src/lib/onboard/docker-driver-gateway-service.test.ts src/lib/onboard/homebrew-formula-operation.test.ts — 145 tests passed.
• npm run typecheck:cli — passed.
• npm run checks:repository — passed.
• npm run validate:pr — passed against origin/main at 0e5f18654524c2fe00292f18227dfb1a03cded2e.
• Live macOS comparison through the shipped temporary-trust wrapper — the pre-fix 10-call sequence took 119.95 seconds; the candidate one-trust observation with two launchd and executable samples took 9.46 seconds. The Homebrew 6 sh.brew.openshell service stayed running with the same PID and formula-defined program.
• npm run test:changed — 4,262 tests passed and 15 unrelated ambient-host tests failed. The failures require Linux Podman tools, inspect live host ports, or encounter the installed OpenShell 0.0.101 formula while this branch pins 0.0.106; none exercise the changed readiness cache.
• The diff contains no secrets, API keys, or credentials.

Review notes

The checksum-verified wrapper remains the only source of formula identity and executable paths. The cache lasts for one observation. Both live service/PID samples and both executable samples remain uncached, so service replacement, formula path drift, foreign launchd programs, and ambiguous active labels fail closed.

The docker-driver-* module names are historical. This change selects no compute runtime and adds no Docker command. Managed Docker and the managed/portable OpenShell Podman driver on macOS share this Homebrew gateway readiness path, so both receive the fix. The separate native Podman provider uses the Linux systemd path and never invokes the Homebrew cache. External and other supervised gateways use the attachment path and clear the cache without consuming it.

---

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

Summary by CodeRabbit

• Bug Fixes

  • Improved macOS Homebrew gateway detection and startup validation.
  • Prevented uninstalled or incorrectly configured Homebrew formulas from being treated as valid.
  • Strengthened verification of gateway service identity, executable paths, and running process IDs.
  • Improved handling of malformed service metadata and command failures.

• Reliability

  • Readiness checks now refresh Homebrew and macOS service information after both successful and failed gateway observations.
  • Added safer failure reporting and recovery during gateway startup checks.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[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: e866d75f-db27-49aa-b598-acae49f3d0dd

📥 Commits

Reviewing files that changed from the base of the PR and between 0e5f186 and 39e98b6.

📒 Files selected for processing (5)

• src/lib/onboard/docker-driver-gateway-service-homebrew.test.ts
• src/lib/onboard/docker-driver-gateway-service.test.ts
• src/lib/onboard/docker-driver-gateway-service.ts
• src/lib/readiness/gateway-production.test.ts
• src/lib/readiness/gateway-production.ts

Included review availability: Your plan provides up to 12 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Homebrew gateway discovery now uses validated brew info --json=v2 metadata and trusted executable paths. Active service identity now uses launchctl. Readiness observations cache formula metadata and reset cached evidence across observation boundaries.

Changes

Homebrew gateway readiness

Layer / File(s)	Summary
Validate Homebrew formula metadata src/lib/onboard/docker-driver-gateway-service.ts, src/lib/onboard/docker-driver-gateway-service.test.ts, src/lib/onboard/docker-driver-gateway-service-homebrew.test.ts	The Homebrew operation uses brew info --json=v2. Formula resolution validates installation, official tap, absolute service commands, and expected gateway paths.
Resolve active Homebrew service identity src/lib/onboard/docker-driver-gateway-service.ts, src/lib/onboard/docker-driver-gateway-service-homebrew.test.ts	Service identity checks use launchctl, trusted program paths, running state, and positive numeric PIDs.
Cache and reset readiness evidence src/lib/readiness/gateway-production.ts, src/lib/readiness/gateway-production.test.ts	Readiness probes reuse cached formula metadata and reset cached service evidence after managed observations, owner resolution, and attachment probing.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 39e98

This change reduces macOS Homebrew readiness-check latency by caching validated formula metadata within an observation while retaining repeated runtime identity samples and resetting evidence between observations. Current coverage supports the intended behavior without an identified merge-blocking risk.

Sequence Diagram(s)

sequenceDiagram
  participant ReadinessObserver
  participant HomebrewOperation
  participant launchctl
  participant GatewayService
  ReadinessObserver->>HomebrewOperation: request cached formula metadata
  HomebrewOperation-->>ReadinessObserver: return trusted service paths
  ReadinessObserver->>launchctl: query supported service labels
  launchctl-->>ReadinessObserver: return state, program, and PID
  ReadinessObserver->>GatewayService: collect managed gateway observations
  GatewayService-->>ReadinessObserver: return readiness evidence

Loading

Suggested reviewers: jyaunches, laitingsheng

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.35% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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 primary change: reducing Homebrew trust operations during readiness checks.
Linked Issues check	✅ Passed	The changes address issue [#11112] by caching Homebrew formula evidence per observation, reducing trusted wrapper calls, preserving freshness, and validating recovery and trust evidence through expand…
Out of Scope Changes check	✅ Passed	The changes are within scope. Formula validation, launchctl identity checks, installer operation handling, cache lifecycle, and related tests support the objective of reducing Homebrew readiness overh…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/11112-homebrew-readiness-performance

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 39e98b6 in the fix/11112-homebrew-r... branch remains at 96%, unchanged from commit 0e5f186 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 39e98b6 in the fix/11112-homebrew-r... branch remains at 83%, unchanged from commit 0e5f186 in the main branch.

Show a line coverage summary of the most impacted files.

File	main 0e5f186	fix/11112-homebrew-r... 39e98b6	+/-
src/lib/inferen...ocal-runtime.ts	97%	87%	-10%
src/lib/onboard...ure-evidence.ts	95%	88%	-7%
src/lib/onboard...-diagnostics.ts	99%	96%	-3%
src/lib/onboard...eway-service.ts	87%	86%	-1%
src/lib/onboard...-transaction.ts	69%	70%	+1%
src/lib/readine...y-production.ts	85%	86%	+1%
src/lib/onboard...ed-lifecycle.ts	75%	77%	+2%
src/lib/onboard.../application.ts	69%	71%	+2%
src/lib/onboard...on-authority.ts	81%	88%	+7%
src/lib/onboard...ght-messages.ts	72%	82%	+10%

---

_{Updated September 06, 2026 16:15 UTC}

[github-actions]

PR Review Advisor finished for commit 39e98b6. Include the Advisor findings in the complete PR feedback collection. Verify and group valid findings before repair.

All previous runs