dev: native desktop acceptance is not represented in routing or evidence gates (Tauri macOS case study)

[lidge-jun]

Problem

CodexClaw's development discipline did not turn a broad “audit regressions since v2.59.0” request into a complete Tauri/macOS artifact and user-interaction acceptance matrix. Source reviews and ordinary macOS CI covered different objects from the installed app and universal release. Problems consequently surfaced at user acceptance and then serially in release dry-runs.

This is a workflow/routing/evidence-granularity bug, not a claim that CodexClaw should automatically detect arbitrary application defects. Agent execution mistakes contributed directly. The existing rules already prohibit claiming success from unperformed checks; adding more prose alone would not address the whole failure.

Observed with CodexClaw 0.2.34+codex.20260920202248, during OpenCodex's v2.59.0-to-v2.61.0-candidate work on 2026-09-22. The v2.59.0 tag does not contain desktop/ or app/. Therefore the new Tauri surface needs first-release acceptance, not an invented “known-good v2.59 desktop” regression baseline. The version range contains new-feature defects, pre-existing pipeline defects, and repair-introduced defects; these must not be collapsed into one regression verdict.

Observed sequence and public evidence

Boundary	What escaped the earlier check	Evidence
Native presentation	The user found blocked scrolling and square outer/background corners, particularly with another window behind the tray popup. The popup was a Tauri/web surface; the existing Swift WidgetKit extension did not make it a native menu-bar surface.	Native panel repair #5490; integration evidence and explicit capture limits
Installed signed sidecar	Bundle creation/signature inspection was insufficient to prove that embedded Bun ocx resolve could execute. The repair added the minimal JIT entitlement and an actual bundled-CLI execution assertion.	Published integration plan/amendment; final-artifact verifier
Earlier masked bundle assertion	Once an upstream updater-signing failure was removed, verification failed on a hardcoded Contents/MacOS/OpenCodex; the bundle actually declared a different executable.	#5338, #5351: derive the path from CFBundleExecutable.
Universal release versus host-only CI	The release lacked the x86_64 Rust target; after that was fixed, Tauri lacked the required ocx-universal-apple-darwin sidecar. Ordinary host-architecture .app verification did not exercise either boundary.	#5526, #5530, dry-run 35718064920
Repair and self-confirming oracle	The agent then introduced an invalid lipo -verify_arch ... <file> command. Read-only reviews passed; a source-string assertion repeated the same wrong command. The actual runner rejected the filename as an architecture. This is a newly introduced repair error, not an established v2.59 regression.	#5535, dry-run 35720315462

The released-source CI definition makes the mismatch concrete: ordinary widget/bundle CI builds the host architecture, ad-hoc signs, disables updater artifacts, and pins Bun 1.3.14. Release packaging uses project Bun, universal architectures, Developer ID/notarization and distribution/updater formats. Keeping secrets out of ordinary PR CI is correct; treating its coverage as release-equivalent would not be.

The Tauri–Rust–Swift–Xcode boundary that the audit must cover

This is the actual wiring of the repaired candidate, not a claim that the original popup was Swift or that WidgetKit implements the menu bar. The original popup used the Tauri/web route; the new native route landed in #5490. Source links below are pinned to OpenCodex 7bd9985963fd344a2c512fa5cf3c0f57f6ba83bd.

flowchart TD
  T[Tauri Rust process and existing status item] --> R[macOS native_tray.rs]
  R -->|Borrow NSStatusItem on AppKit main thread; C ABI| S[Swift NativeTray static library]
  S --> P[AppKit NSPanel]
  P --> H[NSHostingController with SwiftUI content]
  H --> G[NSGlassEffectView or native fallback]
  R -->|Bounded runtime queries and copied JSON snapshot| S
  S -->|Integer action callback| R
  W[Separate SwiftPM WidgetKit product] --> E[OpenCodexWidget.appex]
  E --> B[Tauri app Contents/PlugIns]
  C[Separate compiled Bun CLI for both architectures] --> L[lipo universal ocx sidecar]
  L --> M[Tauri app Contents/MacOS]

Loading

1. Runtime ownership and FFI are separate from widget integration

• lib.rs selects native_tray.rs as popup on macOS and the web popup on other platforms. Tauri continues to own the process, application lifecycle, existing tray/status item and proxy attachment; Swift does not start a second application/run loop.
• native_tray.rs declares extern "C" show/hide/visible/update functions. The Tauri with_inner_tray_icon callback obtains the actual NSStatusItem and calls Swift on the AppKit main thread. Rust owns runtime requests and sends a display snapshot; the Swift side copies the borrowed JSON bytes synchronously.
• Popover.swift exports the matching @_cdecl("ocx_native_tray_…") functions and C-compatible action callback. Despite that historical filename/class name, the final presentation uses NativeTrayPanel: NSPanel, not a WidgetKit view or the abandoned NSPopover design. Main-thread use, borrowed-pointer lifetime, JSON copying and callback teardown are integration obligations that isolated Swift model tests do not prove.

2. Xcode provides the compiler/SDK; Cargo performs the production linkage

• desktop/src-tauri/build.rs discovers app/Sources/NativeTray/*.swift and invokes xcrun --sdk macosx swiftc -parse-as-library -emit-library -static. It maps Cargo aarch64 to Swift arm64, passes an architecture-specific macOS target and emits libNativeTray.a into Cargo's output directory. Cargo then links that archive into the Rust/Tauri executable, with Swift runtime search/RPATH settings; Mach-O autolinking supplies the used system frameworks.
• app/Package.swift exposes the NativeTray static library, executable test targets, MenuBarCore and the separate WidgetKit product for SwiftPM/Xcode development. There is no checked-in .xcodeproj/.xcworkspace in this source tree. A successful SwiftPM/Xcode NativeTray build is not proof that Cargo linked the correct archive into the final Tauri app. The build paths also declare minimum OS versions in different places (SwiftPM macOS 14 versus the direct tray compiler target macOS 13), which needs an explicit compatibility decision rather than assumed equivalence.
• Surface.swift compiles the Liquid Glass branch under Swift compiler 6.2+ and activates it on macOS 26+. Older runtime systems use NSVisualEffectView. Release build.rs checks the archive for an NSGlassEffectView reference to prevent an older build toolchain silently removing the promised feature. That symbol check still does not prove visible material, clipping or interaction on the installed app. The selected Xcode developer directory, SDK, compiler and deployment target therefore belong in the receipt, not just the runner label macos-latest.

3. WidgetKit and the Bun sidecar each have independent packaging contracts

• build-widget.sh separately builds the OpenCodexWidget SwiftPM product for arm64 and x86_64, combines those slices, assembles an .appex, sets bundle metadata and signs it. The product's @main declaration, -application-extension compile option and _NSExtensionMain linker entry must stay consistent. A registered extension or successful model test alone does not prove a usable widget configuration.
• tauri.conf.json embeds that extension at Contents/PlugIns/OpenCodexWidget.appex. The native menu-bar code is instead linked into the host executable. Widget success cannot stand in for menu-bar success, or vice versa.
• The Bun ocx is a third executable path: prepare-sidecar.ts prepares target-suffixed binaries; the release workflow combines the two macOS CLI slices into ocx-universal-apple-darwin; Tauri embeds it as an external binary. Universal Swift/widget success does not prove universal CLI presence, and successful codesign inspection does not prove the embedded CLI can execute with its final entitlements.

Additional acceptance scenarios for this integration

Require evidence for each actual boundary: matching exported/imported ABI symbols and linked Swift archive; correct main-thread status-item presentation; identical declared architectures in host/CLI/extension; final embedded paths read from bundle metadata; Developer ID/team/runtime/entitlement verification of the resulting nested bundle; notarization/stapling where the distribution path requires them; and safe bundled CLI execution plus native panel interaction from that same artifact. Use a hosted macOS runner or authorized native session when local execution is prohibited. Record missing evidence as not_verified; do not turn compiler output, one Swift test executable, a browser screenshot, or WidgetKit registration into proof of the complete app.

What already exists, and why it was insufficient

• cxc-dev §3 already distinguishes build, tests, bug resolution and feature completion, and requires actual evidence. dev-devops/references/cross-platform-release.md already requires native OS/session proof when CI cannot observe the claim. Those rules were not translated into a sufficiently explicit coverage plan early enough.
• cxc-dev's surface-routing table has web/frontend and DevOps owners but no explicit native-desktop/Tauri route that composes UI, host bridge, sidecar, bundle and installed-artifact proof.
• The render-observation implementation recognizes .html/.svg/.css/.jsx/.tsx, not Swift/AppKit or Rust native-window changes. It records observation tool invocation, not which app/artifact/scenario was observed; the Stop message is advisory. A browser or window-only capture does not establish native desktop-background composition.
• The goalplan has a concrete representation gap: CriterionSurface is only logic | web | tui, and computeQaRequired only recognizes web/tui. Native desktop obligations cannot currently be expressed as their own surface with corresponding evidence requirements.
• The source-bound receipt shape binds command/source/session/cycle evidence, but does not itself identify target architecture, SDK/toolchain, bundle digest, signing mode, installed executable, or covered acceptance row. The C-to-D check gate verifies command/exit/time/session/epoch/source, not desktop capability coverage. Source freshness is necessary but is not artifact equivalence.

Accountability and limits: the agent wrote the bad lipo invocation and reviewers missed it. Source-review PASS was not runtime PASS. Later user instructions prohibited local execution and authorized immediate merges; those restrictions must be honored and are not the root cause of the earlier omissions. The correct response is authorized hosted execution or explicit not_verified, never silently overriding the user. The overall release goal remained in CHECK and publication was still outstanding in the examined evidence; this issue does not allege a demonstrated false final D/completion or a broken published v2.61.0 release.

Requested change

1. Add a native-desktop routing/acceptance owner reachable from cxc-dev for Tauri, AppKit/SwiftUI, WidgetKit, native window effects and embedded runtimes. Reuse the existing DevOps/testing owners rather than creating another generic checklist.
2. Add an explicit native-desktop criterion/delivery surface and preserve compatibility for existing logic/web/tui plans. Classify each baseline-to-candidate row as unchanged/regressed/new/removed/repair-introduced, with a real baseline oracle or explicitly “baseline absent.” Establish separate UI, runtime, packaging and distribution verdicts.
3. Before declaring regression audit or release readiness, map ordinary CI against the actual release path: architectures, Bun/Rust/Xcode/SDK, sidecar preparation, signing/entitlements, nested extensions, DMG/updater generation, final-artifact execution and install/upgrade coexistence. Exercise supported non-publishing release-equivalent jobs early. Never expose signing secrets to untrusted PR code.
4. Link evidence to an acceptance row and final artifact identity. Distinguish source review, host-only build, signed bundle inspection, bundled runtime launch, native interaction and publication. An earlier failure must leave every downstream unexecuted row pending; review all newly reachable downstream assertions after a repair.
5. Extend native render observation without pretending every .swift/.rs file is UI or that one screenshot proves all scenarios. Include desktop versus another window behind the popup, light/dark material, bounded scrolling/footer, focus/Escape/reopen, supported OS/SDK fallback, and source/artifact freshness.
6. Add a no-local-execution path that retains these rows as hosted-required or not-verified. Human acceptance can cover its stated scenario only. Source-string tests and reviewer attestations cannot replace native tool execution.

Acceptance tests for CodexClaw

• A Swift native-panel change triggers native-surface evidence requirements; a non-UI Swift model change does not blindly demand screenshots.
• A screenshot of the React dashboard cannot satisfy the macOS native-panel background-composition row.
• An ad-hoc arm64 .app receipt cannot satisfy a universal Developer ID/DMG/updater release row.
• A CLI digest/source mismatch or changed signing configuration invalidates affected artifact evidence, without invalidating unrelated evidence gratuitously.
• A build that fails before bundle launch leaves launch/installation/notarization rows unverified.
• A fixture containing the historical wrong lipo argument order is rejected by an independent behavioral/tool-usage oracle, even when source assertions echo the command.
• A no-local-tests instruction results in hosted-only or not-verified output, never a local run or a false pass.
• A baseline with no desktop surface produces new-feature acceptance obligations rather than a “no desktop regressions” conclusion.

Investigation scope

Independent Sol read-only analysis confirmed the routing, criterion-surface, render-observation and receipt-scope gaps. Its separate observation about the MLB release gate is intentionally excluded: that component is CodexClaw’s own product-release gate, not evidence that it governed this OpenCodex release.

Read-only source/history, recorded user reports and public hosted logs/PRs; no local test/build/runtime execution and no signing secrets or private account screenshots. No CodexClaw implementation or new release dispatch is part of this issue filing. Related #195 addresses CI result interpretation; this issue addresses whether the checked object/scenario matches the desktop release claim even when a job genuinely succeeds.

[lidge-jun]

Closing as superseded. The guidance half of this issue shipped in 0.2.37 via #237: the cxc-dev routing entry for native desktop work, dev-devops/references/native-desktop-acceptance.md (separate UI/runtime/packaging/distribution verdicts, CI-vs-release-path map, artifact identity guidance, popup scenarios, no-local-execution path), macos-system-approvals.md, and the desktop goalplan criterion surface.

The parts that need code or schema changes (native render observation, artifact identity inside receipts, and an executed tool-usage oracle such as the lipo case) plus the goalplan --surface / unknown-flag parser gaps are tracked in #239. An audit of main at 8b26616 found no request from this issue that is not covered by #237 or #239.

[lidge-jun]

Closing. The guidance half landed on main as 0.2.37 and was first published in v0.2.38: native desktop acceptance and macOS approvals references, plus the desktop criterion surface. The code follow-ups split into #239 also shipped in v0.2.38: per-verb CLI flag validation, criterion-bound artifact identity in the QA receipt and final gate, presented native criteria with a native observation advisory, and a behavioral lipo oracle. The remaining limits are listed on #239.