[agent] Run the agent when launched with no arguments

Double-clicking a .app passes no arguments, and after using Quit that is
the only way back a person would think to try. Printing usage and
exiting 2 is completely invisible from Finder: no window, no icon, no
error, nothing written anywhere a user would look. So "reopen the app"
meant "know it is a launchd agent and run launchctl kickstart" — which
made Quit a one-way door the moment it started working.

`agent` stays spelled out; the launchd plist names its role explicitly
and should keep doing so.

--help now exists and prints to stdout with exit 0, while an unknown role
prints to stderr with exit 2. Scripts tell those apart by stream and
status, and conflating them is how --help ends up looking like a failure.

install-server.sh verifies with --help rather than a bare call, which
would now start an agent that never exits and burn the whole timeout on
every healthy install.

Solves: no way to reopen the app after Quit
Tests: three guards — the empty argument shares the agent branch, help
       and error use different streams and statuses, and the installer
       does not verify with a bare invocation. All three behaviours also
       checked against the built binary: --help exits 0, an unknown role
       exits 2, and no arguments runs until killed

Author: drycode

install-server.sh

@@ -534,11 +534,12 @@ fi
 # 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.
+# --help, NOT a bare invocation. `tacet` with no arguments now runs the agent
+# — that is what double-clicking the app has to do — so verifying with a bare
+# call would start a menu-bar agent and block until the timeout every single
+# install. --help is the only invocation guaranteed to print and exit.
 set +e
-usage_out="$(run_bounded 20 "$APP_DST/Contents/MacOS/tacet" 2>&1)"
+usage_out="$(run_bounded 20 "$APP_DST/Contents/MacOS/tacet" --help 2>&1)"
 verify_rc=$?
 set -e
 

swift/Sources/tacet/main.swift

@@ -6,31 +6,61 @@ import TacetCore
 //
 //   tacet serve   → stdlib HTTP server (replaces src/tacet/*.py + FastAPI/uvicorn)
 //   tacet agent   → hotkey, recorder, paste (replaces client/init.lua + rec.swift)
+//   tacet         → agent, because that is what launching the app should do
 //
 // Splitting the roles (rather than always running both in one process) keeps
 // the two-machine setup working: the desktop runs `serve`, the laptop runs
 // `agent`, one signed binary for both.
 let args = CommandLine.arguments
-guard args.count >= 2 else {
-    FileHandle.standardError.write(Data("usage: tacet <serve|agent>\n".utf8))
-    exit(2)
+
+func writeUsage(to handle: FileHandle) {
+    handle.write(Data("""
+    usage: tacet [serve|agent]
+
+      serve    run the transcription server (whisper backend, HTTP)
+      agent    run the menu-bar dictation agent (hotkey, record, paste)
+      --help   this message
+
+    With no arguments tacet runs the agent.
+
+    """.utf8))
 }
 
-switch args[1] {
+switch args.count >= 2 ? args[1] : "" {
 case "serve":
     do {
         try TacetServer().serve()
     } catch {
         FileHandle.standardError.write(Data("tacet: \(error)\n".utf8))
         exit(1)
     }
-case "agent":
+
+// No arguments runs the agent, rather than printing usage and exiting 2.
+//
+// Double-clicking a .app passes no arguments, and after Quit that is the only
+// way back a person would think to try. Exiting 2 there is invisible: Finder
+// shows no window, no icon, no error, and nothing is written anywhere the user
+// would look. The old behaviour turned "reopen the app" into "know that it is
+// a launchd agent and run launchctl kickstart".
+//
+// `agent` stays spelled out because the launchd plist says it explicitly, and
+// a plist that names its role survives someone reading it a year from now.
+case "agent", "":
     let app = NSApplication.shared
     app.setActivationPolicy(.accessory) // LSUIElement-style: menu bar only
     let controller = AgentController(config: .load())
     controller.start()
     app.run()
+
+// Usage goes to stdout and exits 0 when it was ASKED for, and to stderr with a
+// non-zero exit when it was not. Scripts check one or the other; conflating
+// them is how `--help` ends up looking like a failure.
+case "--help", "-h", "help":
+    writeUsage(to: .standardOutput)
+    exit(0)
+
 default:
     FileHandle.standardError.write(Data("tacet: unknown role \(args[1])\n".utf8))
+    writeUsage(to: .standardError)
     exit(2)
 }

tests/test_agent_menu.py

@@ -57,3 +57,54 @@ def test_quit_is_still_wired_to_a_real_handler(self):
         assert "#selector(quitAction)" in code
         assert re.search(r"@objc[^\n]*func quitAction", code), \
             "quitAction must be @objc for #selector to resolve at runtime"
+
+
+MAIN = (
+    Path(__file__).resolve().parent.parent
+    / "swift" / "Sources" / "tacet" / "main.swift"
+)
+
+
+class TestCLIContract:
+    """Launching the app with no arguments must run the agent.
+
+    Double-clicking a .app passes none, and after using Quit that is the only
+    way back a person would think to try. The original behaviour printed usage
+    and exit(2), which from Finder is completely invisible: no window, no icon,
+    no error, nothing written anywhere a user would look. "Reopen the app"
+    became "know it is a launchd agent and run launchctl kickstart".
+    """
+
+    def test_no_arguments_runs_the_agent(self):
+        code = MAIN.read_text()
+        assert 'case "agent", "":' in code, (
+            "the empty argument must share the agent branch"
+        )
+
+    def test_help_exits_zero_on_stdout_and_errors_do_not(self):
+        # A script distinguishes "you asked for help" from "you got it wrong"
+        # by stream and status. Conflating them makes --help look like failure.
+        code = MAIN.read_text()
+        help_branch = code[code.index('case "--help"'):code.index("default:")]
+        assert "standardOutput" in help_branch
+        assert "exit(0)" in help_branch
+        default_branch = code[code.index("default:"):]
+        assert "standardError" in default_branch
+        assert "exit(2)" in default_branch
+
+
+class TestInstallerDoesNotVerifyWithABareCall:
+    """The installer must verify with --help, not a bare invocation.
+
+    A bare call now starts a menu-bar agent that never exits, so the
+    verification step would burn its full timeout on every healthy install and
+    then declare the binary broken.
+    """
+
+    def test_the_verification_passes_help(self):
+        server = Path(__file__).resolve().parent.parent / "install-server.sh"
+        code = server.read_text()
+        assert 'run_bounded 20 "$APP_DST/Contents/MacOS/tacet" --help' in code
+        assert 'run_bounded 20 "$APP_DST/Contents/MacOS/tacet" 2>&1' not in code, (
+            "the bare form would launch the agent and hang"
+        )