fix: root-fix helper "update available" nag for bundled owners (v1.43 W1)

[JasonYeYuhe]

W1 — structurally fix the helper "update available" nag (v1.43)

Root-fixes the perpetual, unclearable "Update available →1.30.0" nag that DEVID users see in Settings → Managed CLI Helper. Two helpers can own the local UDS socket: the Swift helper embedded in the app bundle (updates with the app) and the standalone .pkg Python helper. HelperInstaller.refresh() compared whichever owner's hello version against the published .pkg manifest — so a bundled owner was forever told to "update" a helper it can't update independently (installing the .pkg doesn't evict a bundled owner that owns the socket).

What changed (all additive on the wire)

1. New additive hello field implementation — "swift-bundled" (Swift helper) / "python-pkg" (Python helper). Older helpers omit it → decoded as nil → legacy path unchanged. Element-for-element mirror; the additive-only evolution rule is now written into Protocol.swift's head comment.
2. Nag suppression — HelperInstaller gains a .bundled(version:) state; refresh() delegates to a pure, testable resolveState(...) that returns .bundled for a swift-bundled owner regardless of the manifest (and skips the manifest fetch for it). Every .pkg/older-helper path is preserved byte-for-byte.
3. Controlled helper swap — after an in-place app update, ensureRegistered() is a no-op and the KeepAlive LaunchAgent keeps the old helper process alive until re-login. kickstartBundledHelperIfAppUpdated(...) detects an app-binary change via a persisted app-version sentinel and launchctl kickstart -ks our own LaunchAgent once per new app version, so the new bundle's helper takes over immediately. DEVID-only (#if DEVID_BUILD).
4. UI owner split — CompanionCLISection renders .bundled as "built-in — updates with the app" and hides the .pkg-only Check for Updates / Uninstall… controls.

Why an app-version sentinel and not a helper-version compare (review-driven)

The first cut gated the swap on implementation == "swift-bundled" + a helper-version compare. Dual review (codex + agy) independently caught a P1: the existing v1.42 install base runs a bundled helper reporting 1.23.0 with no implementation field, so a field/version-gated swap can't identify it as stale — the nag would persist for exactly the users the fix targets, until re-login. The app-version sentinel sidesteps owner identification entirely: it kickstarts only our own LaunchAgent label (never the separately-labelled .pkg helper) once per new app version, which also covers a helper-binary change that keeps the same version number. This let us drop the app-side version mirror + the 3-way CI pin the first cut added.

Testing

• Python: pytest helper/ — 950 passed (incl. implementation == "python-pkg" hello assertion).
• HelperSwift: swift test — 624 tests (incl. "swift-bundled" hello assertion).
• CLIPulseCore: swift test default + -Xswiftc -DDEVID_BUILD — 0 failures. New pure-logic tests for resolveState (bundled-never-nags regression pin, .pkg/older-helper legacy paths preserved, nil/socket/manifest branches) and shouldKickstartHelperForAppUpdate (changed / first-run / same-version / build-bump).
• Regression-red proof: with the bundled short-circuit disabled, test_resolveState_bundledOwnerNeverNagsEvenWhenManifestNewer fails producing exactly the shipped bug (updateAvailable(1.29.0 → 1.30.0)), confirming the test guards it.
• Compile matrix: xcodebuild app target — non-DEVID macOS, DEVID macOS, iOS, and MAS archive all build (the #if DEVID_BUILD launchctl exec never compiles into the sandboxed MAS build).
• Review: two rounds of codex + agy + an adversarial multi-lens workflow audit. Round 1 caught the P1 above → sentinel redesign; a confirmed P3 dead pairing-hint removed (follow-up filed to mirror paired into the Swift hello). Round 2 caught a P2 post-swap UI race (an in-flight refresh() capturing the pre-swap helper could leave a stale nag) → fixed with a monotonic-epoch guard in refresh() (last-started wins, so a slow manifest fetch can't clobber a newer result) + refreshAfterHelperRespawn() that reconciles the UI once the kickstarted helper rebinds; plus P3 comment-accuracy fixes (bundled owners now bypass the .pkg compare). Final: agy SHIP, codex re-check clean.

Known transient

On the first launch after upgrading from a pre-v1.43 helper, there's a ~1–2s window (old helper still owner, before the kickstart's respawn binds) where the section could briefly show the old nag before settling to .bundled; it self-heals via the existing re-probe hook.

🤖 Generated with Claude Code