From 595f5ee2f9c22e6957b322e4273f5cd9913c4456 Mon Sep 17 00:00:00 2001
From: Daniel Young <dan@drycodeworks.com>
Date: Thu, 6 Aug 2026 14:05:30 -0400
Subject: [PATCH] [install] Name quarantine as the wedge cause, not
 /Applications
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The message a user sees when the installed bundle never starts told them
the wrong thing. It blamed "Gatekeeper assessment on a bundle in
/Applications" and called ~/Applications "known-good", which is
backwards: a quarantined bundle hangs in ~/Applications identically, and
an unquarantined one runs fine in /Applications. The variable is the
xattr, not the directory. Isolating #25 established that.

Acting on the old advice also cost you the recovery. It sent people to
reinstall elsewhere without saying that the first blocked launch wedges
the path, so deleting the xattr or replacing the bundle in place looks
like it should work and does not.

The detail block bypasses err(), which prefixes every line with ERROR:.
Fifteen of those is a wall, and this is read by someone already stuck.

Solves: #25 follow-up — the diagnostic contradicted the isolation
Tests: new assertion pins the message to com.apple.quarantine and a
       working recovery, and rejects the disproved advice returning;
       mutation-checked by restoring the old wording, which fails it
---
 install-server.sh                 | 37 ++++++++++++++++++++++++-------
 tests/test_install_server_args.py | 19 ++++++++++++++--
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/install-server.sh b/install-server.sh
index 5d2eaf9..b504d1a 100755
--- a/install-server.sh
+++ b/install-server.sh
@@ -527,11 +527,11 @@ fi
 # no matter what grep says, so the check condemned a working binary.
 #
 # BOUNDED, because "does not run" and "does not finish" are different failures
-# and only one of them used to be handled. A bundle can block in dyld before
-# reaching main — Gatekeeper assessment on a bundle in /Applications does
-# exactly this (issue #25) — and an unbounded check then hangs the installer
-# forever with no output, no error, and no service. A verification step that
-# can wedge is worse than no verification step.
+# and only one of them used to be handled. A bundle carrying
+# com.apple.quarantine blocks in dyld before reaching main (issue #25), and an
+# unbounded check then hangs the installer forever with no output, no error,
+# and no service. A verification step that can wedge is worse than no
+# verification step.
 # run_bounded is defined above the source guard so the tests can reach it.
 
 # --help, NOT a bare invocation. `tacet` with no arguments now runs the agent
@@ -544,10 +544,31 @@ verify_rc=$?
 set -e
 
 if [[ "$verify_rc" -eq 124 ]]; then
+  # The headline goes through err(); the rest does not. err() prefixes every
+  # line with ERROR:, and fifteen of those is a wall nobody reads at the moment
+  # they are already stuck.
   err "installed ${APP_DST} but it did not finish starting within 20s."
-  err "The process blocks before reaching main — nothing it logs will say so."
-  err "A bundle in /Applications does this under Gatekeeper assessment (#25);"
-  err "installing to ~/Applications (no cask, no TACET_APP_DIR) is known-good."
+  cat >&2 <<EOF
+
+The process blocks before reaching main, so nothing it logs will say why.
+
+Almost always this is com.apple.quarantine on the bundle (issue #25). Nothing
+launches tacet through LaunchServices — launchd starts it and this script execs
+it — so the first-launch consent gate has nobody to answer it and the process
+waits forever. Notarization does not help; the gate is consent, not assessment.
+
+  xattr -p com.apple.quarantine ${APP_DST}
+
+Removing the attribute does NOT recover this path. The first blocked launch
+wedges the path itself, and neither deleting the xattr nor replacing the bundle
+clears it — only a path that has never wedged:
+
+  rm -rf ${APP_DST}
+  TACET_APP_DIR=~/Applications ./install-server.sh
+
+The Homebrew cask strips quarantine from 0.1.2 on, so a current
+'brew install --cask drycodeworks/tap/tacet' should not reach this message.
+EOF
   exit 1
 fi
 if [[ "$usage_out" != *"usage: tacet"* ]]; then
diff --git a/tests/test_install_server_args.py b/tests/test_install_server_args.py
index 7995c26..057072c 100644
--- a/tests/test_install_server_args.py
+++ b/tests/test_install_server_args.py
@@ -59,8 +59,8 @@ def test_the_usage_text_documents_the_env_overrides(self, tmp_path):
 class TestVerificationIsBounded:
     """The installed binary is executed to prove it works. That must not hang.
 
-    A bundle can block in dyld before reaching main — Gatekeeper assessment on
-    a bundle in /Applications does exactly that (#25). Unbounded, the installer
+    A bundle carrying com.apple.quarantine blocks in dyld before reaching main
+    (#25) — the consent gate has no UI to answer it. Unbounded, the installer
     waits forever: no output, no error, no service, nothing in any log.
     """
 
@@ -78,6 +78,21 @@ def test_a_timeout_is_reported_differently_from_a_broken_binary(self):
         code = SCRIPT.read_text()
         assert 'verify_rc" -eq 124' in code, "the timeout status must be handled"
 
+    def test_the_timeout_message_names_quarantine_and_the_real_recovery(self):
+        # This message is read by someone already stuck, so being wrong here is
+        # expensive. It used to blame /Applications and call ~/Applications
+        # "known-good", which is backwards: a quarantined bundle hangs in
+        # ~/Applications too, and an unquarantined one runs fine in
+        # /Applications. The variable is the xattr, not the directory.
+        code = SCRIPT.read_text()
+        timeout_branch = code[code.index('verify_rc" -eq 124'):code.index("Shared secret")]
+        assert "com.apple.quarantine" in timeout_branch, \
+            "the message must name the actual cause"
+        assert "TACET_APP_DIR" in timeout_branch, \
+            "the message must give a recovery that works"
+        assert "known-good" not in timeout_branch, \
+            "the disproved /Applications-vs-~/Applications advice is back"
+
     def test_the_fallback_exists_because_macos_ships_no_timeout(self):
         # A stock macOS has neither timeout(1) nor gtimeout. Relying on
         # coreutils would leave the check silently unbounded on exactly the