[install] Parse arguments, and bound the binary check

Two failures found by typing `./install-server.sh --help` at a machine
with a working install.

There was no argument parsing at all, so --help — and every typo — fell
through to the install path. It rebuilt the bundle and, on a machine able
to sign, would have replaced a working one. A typo is not consent, so an
unknown flag is now an error and there is a real --help.

Then the install wedged. The step that proves the installed binary runs
executed it with no bound, and a bundle can block in dyld before reaching
main — Gatekeeper assessment on a bundle in /Applications does exactly
that (#25). Ten minutes with no output, no error and no service. "Does
not run" and "does not finish" are different failures and only the first
was handled; a verification step that can wedge is worse than none.

run_bounded prefers timeout(1) but falls back to background-and-poll,
because a stock macOS ships neither timeout nor gtimeout — depending on
coreutils would leave the check unbounded on exactly the machines it
protects. It sits above the source guard so the tests can reach it; the
same mistake with render_plists made every test report "command not
found".

Solves: --help performing an install, and an unbounded verification step
Tests: eleven cases — help and unknown flags touch no filesystem and exit
       0/2, the bounded helper is actually used, a timeout reports
       differently from a broken binary, and run_bounded kills a hanging
       command and reports 124 both with coreutils and on the fallback

Author: drycode

install-server.sh

@@ -360,15 +360,86 @@ PLIST
   log "Rendered both plists (tacet: ${BIND}:${PORT}, whisper: 127.0.0.1:${WHISPER_PORT})"
 }
 
+# Run a command with a wall-clock bound, printing its output and returning its
+# status — or 124 if it had to be killed. Defined ABOVE the source guard so the
+# tests can exercise it directly; the same mistake with render_plists made every
+# test report "command not found".
+#
+# Prefers a real timeout(1) when one is installed (coreutils), otherwise falls
+# back to background-and-poll. The fallback is the point: a stock macOS has
+# neither timeout(1) nor gtimeout, so depending on coreutils would leave this
+# silently unbounded on exactly the machines it protects.
+run_bounded() {
+  local secs="$1"; shift
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$secs" "$@"
+    return $?
+  fi
+  if command -v gtimeout >/dev/null 2>&1; then
+    gtimeout "$secs" "$@"
+    return $?
+  fi
+  local out_file pid waited=0 rc
+  out_file="$(mktemp)"
+  "$@" >"$out_file" 2>&1 &
+  pid=$!
+  while kill -0 "$pid" 2>/dev/null; do
+    if (( waited >= secs )); then
+      kill -9 "$pid" 2>/dev/null || true
+      wait "$pid" 2>/dev/null || true
+      rm -f "$out_file"
+      return 124
+    fi
+    sleep 1
+    waited=$((waited + 1))
+  done
+  wait "$pid"
+  rc=$?
+  cat "$out_file"
+  rm -f "$out_file"
+  return $rc
+}
+
 # line only runs when the script is executed directly.
 if [[ "${BASH_SOURCE[0]}" != "$0" ]]; then
   return 0
 fi
 
-if [[ "${1:-}" == "--doctor" ]]; then
-  run_doctor
-  exit $?
-fi
+usage() {
+  cat <<'EOS'
+tacet — server setup.
+
+Run this on the Mac that transcribes. It installs Tacet.app, downloads the
+whisper model, renders both launchd plists from ~/.config/tacet/config.toml,
+and loads the services.
+
+  ./install-server.sh              install or update
+  ./install-server.sh --doctor     read-only diagnosis, changes nothing
+  ./install-server.sh --help       this message
+
+Environment:
+  TACET_APP_DIR     install the bundle here instead of ~/Applications
+  TACET_ALLOW_ADHOC build without a Developer ID (local dev only)
+
+Safe to re-run: every step checks current state first.
+EOS
+}
+
+# Argument handling is explicit, and an unknown flag is an ERROR rather than
+# something to ignore. Falling through to "install" meant `--help` performed a
+# real installation — it rebuilt the bundle, and on a machine that could sign
+# it would have replaced a working one. A typo should not install anything.
+case "${1:-}" in
+  --doctor)  run_doctor; exit $? ;;
+  -h|--help) usage; exit 0 ;;
+  "")        ;;  # no arguments: install
+  *)
+    err "unknown option: $1"
+    echo >&2
+    usage >&2
+    exit 2
+    ;;
+esac
 
 # ==============================================================================
 # Install
@@ -454,10 +525,33 @@ fi
 # Captured, not piped: `tacet` with no arguments prints usage and exits 2 —
 # correct behaviour — and under `set -o pipefail` that makes the pipeline fail
 # no matter what grep says, so the check condemned a working binary.
-usage_out="$("$APP_DST/Contents/MacOS/tacet" 2>&1 || true)"
+#
+# 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.
+# run_bounded is defined above the source guard so the tests can reach it.
+
+# `tacet` with no arguments exits 2 by design, so a non-zero status here is
+# expected and only the OUTPUT decides. 124 is the one status that means
+# something different: the timeout fired and nothing can be concluded.
+set +e
+usage_out="$(run_bounded 20 "$APP_DST/Contents/MacOS/tacet" 2>&1)"
+verify_rc=$?
+set -e
+
+if [[ "$verify_rc" -eq 124 ]]; then
+  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."
+  exit 1
+fi
 if [[ "$usage_out" != *"usage: tacet"* ]]; then
   err "installed ${APP_DST} but the binary does not run — aborting."
-  err "got: ${usage_out}"
+  err "got: ${usage_out:-<no output>}"
   exit 1
 fi
 log "Installed."

tests/test_install_server_args.py

@@ -0,0 +1,117 @@
+"""install-server.sh's argument handling, and the bounded verification step.
+
+Both of these were found the same way on 2026-08-05: by typing
+`./install-server.sh --help` at a machine with a working install, which
+performed a real installation, rebuilt the bundle, and then wedged for ten
+minutes on a binary that never finished starting.
+
+Neither failure was visible. The install printed progress and blocked; the
+flag printed nothing to say it had been misread.
+"""
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+SCRIPT = Path(__file__).resolve().parent.parent / "install-server.sh"
+
+
+def run(*args: str, home: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["bash", str(SCRIPT), *args],
+        capture_output=True,
+        text=True,
+        env={"PATH": "/usr/bin:/bin", "HOME": str(home)},
+    )
+
+
+class TestArgumentHandling:
+    def test_help_prints_usage_and_installs_nothing(self, tmp_path):
+        # The original bug: no argument parsing at all, so every unrecognised
+        # flag fell through to the install path.
+        r = run("--help", home=tmp_path)
+        assert r.returncode == 0
+        assert "install or update" in r.stdout
+        assert not any(tmp_path.iterdir()), \
+            f"--help touched the filesystem: {list(tmp_path.iterdir())}"
+
+    def test_short_help_works_too(self, tmp_path):
+        r = run("-h", home=tmp_path)
+        assert r.returncode == 0
+        assert "--doctor" in r.stdout
+
+    def test_an_unknown_flag_is_an_error_not_an_install(self, tmp_path):
+        r = run("--bogus", home=tmp_path)
+        assert r.returncode == 2, "a typo must not be interpreted as consent"
+        assert "unknown option" in r.stderr
+        assert not any(tmp_path.iterdir()), \
+            f"an unknown flag touched the filesystem: {list(tmp_path.iterdir())}"
+
+    def test_the_usage_text_documents_the_env_overrides(self, tmp_path):
+        # TACET_APP_DIR is the documented escape hatch when a cask install is
+        # not the bundle you want (issue #25), so it has to be discoverable.
+        r = run("--help", home=tmp_path)
+        assert "TACET_APP_DIR" in r.stdout
+        assert "TACET_ALLOW_ADHOC" in r.stdout
+
+
+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
+    waits forever: no output, no error, no service, nothing in any log.
+    """
+
+    def test_the_binary_check_goes_through_the_bounded_helper(self):
+        code = SCRIPT.read_text()
+        # The bare form is the bug. Anything invoking the installed binary for
+        # verification has to go through run_bounded.
+        assert 'run_bounded 20 "$APP_DST/Contents/MacOS/tacet"' in code
+        assert 'usage_out="$("$APP_DST/Contents/MacOS/tacet"' not in code, \
+            "the unbounded form is back"
+
+    def test_a_timeout_is_reported_differently_from_a_broken_binary(self):
+        # "did not run" and "did not finish" need different messages: the
+        # second one has no output to show, and the fix is different.
+        code = SCRIPT.read_text()
+        assert 'verify_rc" -eq 124' in code, "the timeout status must be handled"
+
+    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
+        # machines it protects.
+        code = SCRIPT.read_text()
+        bounded = code[code.index("run_bounded() {"):]
+        for tool in ("timeout", "gtimeout"):
+            assert f'command -v {tool}' in bounded
+        assert "kill -9" in bounded, "the fallback must actually enforce the bound"
+        assert "return 124" in bounded, "the fallback must report a timeout as 124"
+
+
+class TestRunBoundedBehaviour:
+    """Exercise run_bounded itself, both with and without coreutils."""
+
+    def _call(self, tmp_path, command: str, *, with_timeout: bool):
+        # PATH without /opt/homebrew means no timeout(1) — the fallback path.
+        path = "/opt/homebrew/bin:/usr/bin:/bin" if with_timeout else "/usr/bin:/bin"
+        # `set +e` after sourcing: install-server.sh sets errexit, so a 124
+        # return would kill this shell before it could report the status. The
+        # real call site wraps the invocation the same way, for the same reason.
+        program = f'source {SCRIPT}\nset +e\nrun_bounded 3 {command}\necho "rc=$?"\n'
+        return subprocess.run(
+            ["bash", "-c", program], capture_output=True, text=True,
+            env={"PATH": path, "HOME": str(tmp_path)},
+        ).stdout
+
+    @pytest.mark.parametrize("with_timeout", [True, False], ids=["coreutils", "fallback"])
+    def test_a_hanging_command_is_killed_and_reported_as_124(self, tmp_path, with_timeout):
+        out = self._call(tmp_path, "/bin/sleep 30", with_timeout=with_timeout)
+        assert "rc=124" in out, out
+
+    @pytest.mark.parametrize("with_timeout", [True, False], ids=["coreutils", "fallback"])
+    def test_a_fast_command_returns_its_own_output_and_status(self, tmp_path, with_timeout):
+        out = self._call(tmp_path, "/bin/echo hello", with_timeout=with_timeout)
+        assert "hello" in out
+        assert "rc=0" in out, out