docs(task-054): fix bricked v0.8.1 DMG install path — corrected unsigned first-launch docs (Plan B) - #42
Merged
Conversation
…for v0.8.1 DMG The v0.8.1 release was bricked by the docs, not the binary. On Apple Silicon a browser-downloaded (quarantined) unsigned app hits Gatekeeper's "damaged" verdict, which right-click -> Open does NOT clear. Corrected README/RELEASE to the working remedy (xattr -dr com.apple.quarantine) with a security caveat and a TASK-028 (signed+notarized) pointer as the real fix. Verified the shipped asset (sha e77d15cf...) is pristine tauri:build output: a fresh rebuild is structurally identical (adhoc/linker-signed, v0.8.1, same layout), so it was not hand re-packed; the visible .VolumeIcon.icns is a standard Tauri dot-file hidden by Finder default. Bytes intact; de-quarantined binary execs. Docs-only Plan B (no source/schema/IPC/tauri.conf/signing/updater/CI change). Release asset unchanged (not yanked, not re-uploaded). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fixes sole SW-4 blocker: literal </content> and </invoke> tool-call residue at the end of ops-review.md removed; Plan B content intact, file ends with a single newline. handoff.md updated (<=2KB) to mark the blocker resolved and ready for SW-4 recheck. Docs-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds task-level RELEASE.md (deployment size: patch, rollback: automated, compatibility matrix) plus committed SW-3/SW-4/SW-5/Docs evidence. Signed tag task-054/v0.8.1 deferred (SSH key passphrase unavailable non- interactively, same as task-052/053). PR #42 promoted to ready-for-review.
There was a problem hiding this comment.
Pull request overview
This PR updates the macOS v0.8.1 prebuilt install documentation and associated OpenSpec artifacts to provide a working first-launch path for Apple Silicon users hitting Gatekeeper’s “Vire is damaged and can’t be opened” dialog for the unsigned, quarantined DMG.
Changes:
- Update
README.mdand rootRELEASE.mdto document the one-time quarantine removal (xattr -dr com.apple.quarantine /Applications/Vire.app) and clarify why right-click → Open doesn’t resolve this specific failure mode. - Add TASK-054 OpenSpec change artifacts (proposal/design/spec/QA/review/security/ops evidence/handoff) recording diagnosis, constraints, and verification results.
- Expand root
RELEASE.mdwith a TASK-054 subsection asserting the shipped DMG asset is unchanged and documenting the corrected install path.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| RELEASE.md | Updates v0.8.1 smoke checklist first-launch guidance and adds a TASK-054 narrative subsection documenting the corrected install path. |
| README.md | Corrects the prebuilt install “first launch” steps to the working quarantine-removal remedy with a security caveat and TASK-028 pointer. |
| openspec/changes/task-054-fix-broken-dmg-release/arch-review.md | Records architecture assessment and decision gates (Plan A vs Plan B, containment). |
| openspec/changes/task-054-fix-broken-dmg-release/design.md | Documents the diagnosed mechanism and Plan A/Plan B design choices for release distribution. |
| openspec/changes/task-054-fix-broken-dmg-release/docs.md | Documents the docs-gate checks ensuring guidance is accurate and safely scoped. |
| openspec/changes/task-054-fix-broken-dmg-release/handoff.md | Summarizes final state and next actions for Janne (merge + deferred signed tag). |
| openspec/changes/task-054-fix-broken-dmg-release/ops-review.md | Captures release-packaging diagnosis and verification evidence for the “damaged” dialog remediation. |
| openspec/changes/task-054-fix-broken-dmg-release/proposal.md | Introduces the incident writeup and branch-aware Plan A/Plan B proposal. |
| openspec/changes/task-054-fix-broken-dmg-release/qa.md | Records QA recheck results and scenario coverage for the updated distribution/docs requirement. |
| openspec/changes/task-054-fix-broken-dmg-release/RELEASE.md | Adds SW-6 release gate artifact for the docs-only patch posture and rollback plan. |
| openspec/changes/task-054-fix-broken-dmg-release/review.md | Records SW-4 review gate artifact and verification checklist. |
| openspec/changes/task-054-fix-broken-dmg-release/sec.md | Records SW-5 security gate artifact confirming docs-only scope and safe quarantine guidance. |
| openspec/changes/task-054-fix-broken-dmg-release/tasks.md | Defines the task checklist and decision gates for containment and Plan A/Plan B execution. |
| openspec/changes/task-054-fix-broken-dmg-release/specs/release-distribution/spec.md | Updates the release-distribution requirement to require an installable browser-download path (signed/notarized or accurate quarantine-removal docs). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+74
to
+78
| 3. **First launch — the app is not code-signed or notarized.** Try to open the installed app the | ||
| normal way first: double-click `Vire.app` in `/Applications`. | ||
|
|
||
| Because this build is unsigned **and** it was downloaded through a web browser (so macOS tags it | ||
| with the `com.apple.quarantine` attribute), Apple Silicon's Gatekeeper will most likely block that |
| signature, which is valid. | ||
| 2. Simulated a browser download: `ditto` the app, applied `com.apple.quarantine`, then | ||
| `xattr -dr com.apple.quarantine` → attribute cleared. | ||
| 3. Bounded launch of the de-quarantined binary: the process **execed and stayed alive** (not |
| 1. **Asset present & downloadable** — the `v0.8.1` release page lists `Vire_0.8.1_aarch64.dmg`; downloading it yields the sha256 above. ✅ verified (asset uploaded, download round-trip matches). | ||
| 2. **Mount + drag** — double-click the DMG to mount, drag **only `Vire.app`** onto the `Applications` shortcut. (Human step — physical Mac.) | ||
| 3. **First launch (unsigned Gatekeeper)** — the app is not code-signed/notarized; on first open **right-click `Vire.app` → Open** and confirm. Do not disable Gatekeeper or strip quarantine. (Human step.) | ||
| 3. **First launch (unsigned Gatekeeper)** — the app is not code-signed/notarized. A browser-downloaded copy carries `com.apple.quarantine`, so on Apple Silicon Gatekeeper reports **"Vire is damaged and can't be opened"** — a policy verdict, not corruption, and **right-click → Open does not clear it**. Remedy: after copying to `/Applications`, run `xattr -dr com.apple.quarantine /Applications/Vire.app`, then open normally. This bypasses Gatekeeper because the build is unsigned; a signed + notarized build (TASK-028) is the real fix. (Human step. Corrected in TASK-054 — see below.) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TASK-054 — fix the broken v0.8.1 DMG release (Plan B: unsigned + honest quarantine-removal docs)
Root cause: the docs, not the binary. On Apple Silicon a browser-downloaded (quarantined)
unsigned app hits Gatekeeper's "Vire is damaged and can't be opened" verdict. The previously
documented remedy (right-click → Open; "do not strip quarantine") does not clear that dialog,
so v0.8.1 had no working documented install path.
Plan B selected by Janne (no Apple Developer Program / no Developer ID cert / no notarization creds).
Changes (docs-only)
README.mdprebuilt install step 3 — corrected to the working remedyxattr -dr com.apple.quarantine /Applications/Vire.app, with a security caveat and a pointer toTASK-028 (signed + notarized) as the real fix.
xattrframed as the fallback when the "damaged"dialog appears.
RELEASE.mdv0.8.1 smoke step 3 + new TASK-054 subsection. Shipped-asset sha unchanged.ops-review.md— full diagnosis, verification, and asset-action record.Verification (local, this branch)
sha256 e77d15cf…is pristinetauri:buildoutput: a freshnpm run tauri:buildis structurally identical (ad-hoc/linker-signed
Vire.app, Identifiervire-3e8c42af…, v0.8.1,same DMG layout) → not hand re-packed. Visible
.VolumeIcon.icnsis a standard Tauri dot-filehidden by Finder default.
execs (not signature-killed) → app opens by the documented path.
Release asset
Unchanged. Not yanked (Q2 not approved, not needed), not re-uploaded (asset already pristine; the
fix is docs). Fresh verify-build
7280ff43…was not uploaded.Scope
No source / schema / IPC / capability /
tauri.conf.json/ signing / notarization / auto-updater /release-feed / CI change or claim. Physical-Mac launch remains a standing human-UAT gate.
🤖 Generated with Claude Code