Skip to content

fix(mac): improve macOS installation stability with build verification, signing hardening, and diagnostics#838

Draft
hazeone wants to merge 2 commits into
mainfrom
cursor/clawx-0100
Draft

fix(mac): improve macOS installation stability with build verification, signing hardening, and diagnostics#838
hazeone wants to merge 2 commits into
mainfrom
cursor/clawx-0100

Conversation

@hazeone
Copy link
Copy Markdown
Contributor

@hazeone hazeone commented Apr 12, 2026

Summary

Addresses recurring macOS installation stability issues ("应用程序'ClawX'已不能再打开" / "文件已损坏") through a 5-phase improvement plan based on deep analysis of the ClawX build pipeline, CI logs, and best practices from VSCode, ClashParty/Mihomo Party, and the electron-builder ecosystem.

Root Causes Identified

  1. No post-build signature verification — CI only checks that electron-builder doesn't throw; broken signatures ship silently
  2. No explicit timestamp server — Missing secure timestamps can cause Gatekeeper rejection after cert expiry
  3. No startup integrity check — Corrupted installs from failed auto-updates go undetected
  4. No afterPack integrity verification — 10,000+ file operations in after-pack.cjs with no validation
  5. Insufficient user guidance — No Chinese-language troubleshooting for common macOS errors

Changes

Phase 1: CI Post-Build Verification (CRITICAL)

  • Added Verify macOS code signature and notarization step to release.yml
  • Runs codesign --verify --deep --strict (same as VSCode CI)
  • Validates secure timestamp presence
  • Runs spctl --assess (Gatekeeper acceptance test)
  • Runs xcrun stapler validate (notarization staple verification)
  • Covers both x64 and arm64 builds, plus DMG artifacts

Phase 2: Explicit Timestamp Server

  • Added timestamp: "http://timestamp.apple.com/ts01" to electron-builder.yml
  • Ensures secure timestamp is always embedded even in network-constrained CI

Phase 3: Startup Signature Self-Check + Updater Logging

  • Added macOS code signature verification at app startup (diagnostic only, non-blocking)
  • Logs a warning if the running .app bundle has a broken signature
  • Added update version logging to quitAndInstall() for post-mortem debugging

Phase 4: afterPack Integrity Verification

  • Added final file count and total size logging to after-pack.cjs
  • Added integrity verification of critical patched modules (node-domexception, lru-cache)
  • Build fails immediately if any integrity check fails

Phase 5: macOS Troubleshooting in Release Notes

  • Added detailed Chinese + English troubleshooting for:
    • "已损坏" (damaged) error → xattr -cr fix
    • "已不能再打开" (can't be opened) → reinstall steps
    • First-launch Gatekeeper bypass → right-click → Open
  • Restructured installation notes by platform

Related Issue(s)

Addresses recurring macOS "file is damaged" and "can't be opened" installation reports.

Type of Change

  • Bug fix
  • New feature
  • Documentation
  • Refactor
  • Other

Validation

  • pnpm run lint — passes cleanly
  • pnpm run typecheck — pre-existing failure (unrelated use-stick-to-bottom module)
  • pnpm test — pre-existing 5 test failures (unrelated plugin-install.test.ts mock issue)
  • node -c scripts/after-pack.cjs — syntax check passes
  • CI verification step is self-testing: it runs on every release build and fails the pipeline if signatures are invalid
  • The afterPack integrity check will surface any file corruption on the next build

Checklist

  • I ran relevant checks/tests locally.
  • I updated docs if behavior or interfaces changed.
  • I verified there are no unrelated changes in this PR.
Open in Web Open in Cursor 

cursoragent and others added 2 commits April 12, 2026 04:12
…d startup integrity check

Phase 1: Add CI verification step after macOS build that runs:
  - codesign --verify --deep --strict (same as VSCode CI)
  - Secure timestamp validation
  - spctl --assess (Gatekeeper acceptance)
  - xcrun stapler validate (notarization staple)
  Prevents shipping silently broken signatures.

Phase 2: Add explicit Apple TSA timestamp server to electron-builder.yml.
  Ensures secure timestamp is always embedded, preventing Gatekeeper
  rejection when signing cert expires.

Phase 3: Add startup code signature self-check on macOS (diagnostic).
  Logs a warning if the running .app bundle has a broken signature,
  helping diagnose 'can't be opened' reports from failed auto-updates.
  Also improves updater logging for post-mortem debugging.

Co-authored-by: Haze <hazeone@users.noreply.github.com>
…th macOS troubleshooting

Phase 4: Add integrity verification to after-pack.cjs:
  - Log final file count and size of Resources directory
  - Verify critical patched modules contain expected marker strings
  - Fail the build if any integrity check fails (catches silent
    write failures or encoding corruption before signing)

Phase 5: Improve release notes template with detailed macOS
troubleshooting in Chinese and English:
  - Instructions for 'damaged' (已损坏) error: xattr -cr fix
  - Instructions for 'can't be opened' (已不能再打开): reinstall steps
  - First-launch Gatekeeper bypass: right-click → Open
  - Structured by platform (macOS/Windows/Linux)

Co-authored-by: Haze <hazeone@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants