[MylesShannon]

Changelog title

Restore macOS privileged helper communication after upgrades

Changelog body

• Preserve the helper-specific signing identifier needed to communicate with the macOS background helper and complete setup.
• Replace an enabled but unreachable helper once per app version after an upgrade, and keep setup incomplete until helper communication and firewall configuration succeed.

Bumps

• services: minor
• nvpair-cluster-manager: none
• nvpair-engine-manager: none
• nvpair-errors: none
• nvpair-job-scheduler: none
• nvpair-manual-nodes: none
• nvpair-node-info: none
• nvpair-node-scanner: none
• nvpair-node-settings: none
• nvpair-proxy: none
• nvpair-tui: none
• nvpair-ui-broker: none
• nvpair-workload-manager: none

Description

Addresses #175. In PAIR 1.0.0 (build 1.0.0.85), the running helper is signed as com.nvidia.nvpair, while its XPC peer correctly requires com.nvidia.nvpair.helper. Filename-derived signing can strip the .helper suffix, leaving registration enabled but XPC unreachable and setup incomplete.

Embed the daemon's canonical CFBundleIdentifier in both Mach-O architecture slices so standalone and recursive signing preserve its identity. Add a signing regression test and a release validator using the existing shared Swift requirements.

On upgrade, treat an enabled but unreachable helper as stale even when its daemon version cannot be read. Persist the repair attempt and invalidate cached setup completion before unregistering, then register the replacement, re-check status, and configure the firewall. Replacement is limited to once per app version across launches. Registration errors, unreachable helpers, and a remaining version mismatch leave setup incomplete. Pending approval and firewall failures retain the normal next-launch setup path without another replacement cycle.

Scope

macOS helper build metadata, startup recovery, signing and recovery regression coverage, signature validation tooling, and release acceptance documentation. Existing XPC authentication, Developer ID trust, and identifier pinning remain intact. The control tool retains the enclosing application's Bundle.main required by ServiceManagement. No Go service implementation changes.

Validation

• Linux, Node.js 26.13.0, locked public dependencies: make check and npm --prefix desktop run dead-code:check pass. Includes lint, all TypeScript targets, build-script checks, service contracts, SPDX headers, 297 Vitest tests, and 26 Node tests.
• Fifteen helper setup tests exercise the real setup wrapper and configuration persistence with the native control tool mocked. Coverage includes the missing daemon version on upgrade, successful replacement, failed unregister/register, unreachable replacement, persisted retry limits, interrupted repair, retry after an app-version change, approval, fresh registration, healthy startup, version refresh, and firewall failure/retry. The upgrade regression failed before the recovery change.
• git diff --check passes. Prior sh -n validation of both added shell scripts passes; they are unchanged by the recovery update.
• Prior Apple Silicon macOS testing of the same native implementation: npm run build:helper:mac and npm run test:helper-signing:mac pass for the universal daemon. Without the embedded plist, the regression test fails. Incorrect identifiers in the x86_64 slice are rejected even when arm64 is correct.
• The full validator rejects the affected installed helper, missing artifacts, and ad hoc signatures; it accepts the affected release's correctly signed control tool and app.
• The maintainer reported verification of the initial signing change with an internally signed build. The startup recovery update still needs signed-build verification.

Release integration and outstanding checks

Release maintainers must invoke npm run verify:helper-signatures:mac -- "/path/to/NVIDIA PAIR.app" after the final signing pass and fail the release if it exits nonzero. Repeat against each extracted DMG/ZIP. The public source change supplies the validator; release signing integration is still required.

• Verify an NVIDIA-signed candidate containing the startup recovery update against the complete pinned requirements for every architecture.
• Upgrade in place from the affected release without unregistering its helper or clearing user data. Verify one replacement attempt, reachable XPC status and matching versions, successful firewall configuration, and setup completion persisting across two quits/relaunches and a reboot.
• Verify clean installation and approval-pending recovery with the signed candidate.

A development app skips helper setup, so the absence of its prompt is not validation of this fix. The signed-build acceptance procedure is documented in desktop/docs/macos-privileged-helper.md.

Risk

Packaging metadata must survive every signing pass. The first launch of each app version may replace a stale helper and require macOS approval. A failed replacement is not repeatedly attempted for the same version. No signing credentials or private signing implementation are included.

Checklist

• I have read the Contributing Guidelines.
• Every commit is signed off (git commit -s), certifying the Developer Certificate of Origin.
• Relevant automated or manual checks cover the change, as recorded above.
• Relevant documentation is updated.
• I checked the diff, changed filenames, and commit messages for credentials, private data, internal URLs, internal issue identifiers, and generated artifacts.
• I recorded validation commands and results above, including outstanding checks.
• I declared version bumps in the release-intent block. No Go service implementation changes; all component bumps are none. Version files and changelog are left to automation.

[Noah-Tervalon-Nvidia]

This looks great, but one thing is missing - when someone upgrades from 1.0.0 to whichever version has this they won't get the fix. Since the 1.0.0 version causes the daemon to fail it'll be unreachable, and in desktop/src/electron/services/mac-privilege-service.ts unreachable is treated as healthy so we wouldn't re-register the correctly signed helper.

Pretty sure the fix is just treat enabled && !reachable as stale, run uninstall() + install() once per app version, then re-check status(). Also stop reporting firewallConfigured: true without reaching the daemon (i.e. treat unreachable as failure rather than success).

[Noah-Tervalon-Nvidia]

moving out of draft as well. I have verified this with an internally signed build, with the fix, I'll do another round of verification and then we can merge this in.

[MylesShannon]

I’ve pushed an update addressing the upgrade path. Enabled but unreachable helpers now get one unregister/register attempt per app version, persisted across restarts, followed by another status check. Setup stays incomplete if the helper remains unreachable or firewall configuration fails.

I added regression coverage, and all local checks pass. It’s ready for another round of signed-build testing. Thanks for catching this.

[MylesShannon]

Testing the signed build exposed another upgrade-recovery case. I opened #201 as a follow-up to #192, with the additional fix isolated in its own commit. #192 should merge first.