Let auto use what is ready, and make naming the engine the thing that builds it

CI found a real one, and it was not about CI: the macOS leg went from 35 seconds
on main to 643 on this branch. Every launch on a Mac without Whisper models was
compiling Swift and then sitting on `--probe` until it timed out, because the
probe waits for an authorization dialog that a headless machine never answers.

A user's first launch would have done exactly the same thing. A full minute of
nothing before a pill appears, on a machine that asked for none of it, to decide
whether to offer an engine it might not use.

So `--engine auto` passes compile_if_missing=False and a ten second probe: it
uses the helper if it is already built and says how to build it if not.
`--engine native` still compiles, because somebody who typed it has asked for
the wait. Once it has been run once, auto finds the binary from then on.

A timeout is now named as the dialog it is rather than as
"probe failed: TimeoutExpired", which is true and useless when the fix is a
click.

And every one of those reasons reaches `say()`, which writes to a cp437 console
- so the em dashes in them were a launch that died on its own explanation. That
is how this one was found; there is a test over the module's string literals now
so the next one is caught here rather than by a user on Windows.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: samartomar

flow/__main__.py

@@ -182,7 +182,10 @@ def _engine(args, partial_name: str, final_name: str) -> tuple[str, str]:
     # auto. Ask the cheap question first: are the models here?
     if _models_present(partial_name, final_name):
         return "whisper", ""
-    ok, why = native_available()
+    # `compile_if_missing=False`, and a short probe. A launch is not the place to
+    # discover how slow `swiftc` is, and the probe blocks on a permission dialog that
+    # nobody has been shown yet — measured at a full minute per launch before this.
+    ok, why = native_available(compile_if_missing=False, timeout=10.0)
     if ok:
         return "native", " (whisper models not found on this machine)"
     return "whisper", f" (not found locally, and no native engine: {why})"

flow/native.py

@@ -79,7 +79,7 @@ def build(force: bool = False) -> Path:
     except (OSError, subprocess.SubprocessError) as exc:
         raise NotAvailable(f"no Swift toolchain: {exc}") from exc
     if which.returncode != 0:
-        raise NotAvailable("no Swift toolchain — run: xcode-select --install")
+        raise NotAvailable("no Swift toolchain - run: xcode-select --install")
     BUILD_DIR.mkdir(parents=True, exist_ok=True)
     try:
         # `-parse-as-library` is required, not tuning: a single-file executable is
@@ -96,21 +96,41 @@ def build(force: bool = False) -> Path:
     return BINARY
 
 
-def available() -> tuple[bool, str]:
+def available(compile_if_missing: bool = True,
+              timeout: float = 60.0) -> tuple[bool, str]:
     """`(usable, why not)` for this machine, without starting a session on it.
 
     Runs the helper's own `--probe`, which is the only honest check: the engine exists
     when the OS says it does, the locale resolves, on-device recognition is supported —
     which needs Dictation enabled so macOS has downloaded the offline model — and the
     user has granted the permission. Anything less is a guess that fails later, in the
     middle of somebody's first sentence.
+
+    **`compile_if_missing=False` is what `--engine auto` uses, and it is not a
+    micro-optimisation.** Measured in CI: with this asked unconditionally at startup, the
+    macOS suite went from 35 seconds to 643. Every launch on a Mac without Whisper models
+    was compiling Swift and then sitting on `--probe` until the timeout, because the
+    probe waits for an authorization dialog that a headless machine never answers — and a
+    user's first launch would have done exactly the same thing, for a full minute, before
+    showing a pill.
+
+    So the rule is: **`auto` uses what is ready, and asking for the engine by name is
+    what builds it.** Once `--engine native` has been run once the binary is there, and
+    `auto` finds it from then on.
     """
+    if not compile_if_missing and sys.platform == "darwin" and not BINARY.exists():
+        return False, ("not built yet - run once with --engine native to compile it")
     try:
         binary = build()
     except NotAvailable as exc:
         return False, str(exc)
     try:
-        probe = _run([str(binary), "--probe"], 60.0)
+        probe = _run([str(binary), "--probe"], timeout)
+    except subprocess.TimeoutExpired:
+        # Almost always the permission dialog, unanswered. Named as itself rather than
+        # as a generic failure, because the fix is a click and the user should hear so.
+        return False, ("probe timed out - grant Speech Recognition under "
+                       "System Settings > Privacy & Security")
     except (OSError, subprocess.SubprocessError) as exc:
         return False, f"probe failed: {exc}"
     if probe.returncode != 0:

native/flow_stt.swift

@@ -85,7 +85,7 @@ func makeRecognizer() -> SFSpeechRecognizer {
     // The whole point. Without this the audio goes to Apple's servers, which is a
     // different product from the one Flow is: local by construction.
     guard rec.supportsOnDeviceRecognition else {
-        die("on-device recognition unavailable — enable Dictation in System Settings "
+        die("on-device recognition unavailable - enable Dictation in System Settings "
             + "so macOS downloads the offline model", 5)
     }
     // Off the main queue, deliberately. `transcribe` waits on a semaphore for the

tests/test_native.py

@@ -119,6 +119,98 @@ def _engine_result():
     return _engine(args(), "base.en", "small.en")
 
 
+class TestAutoNeverPaysForAnEngineItMayNotUse(unittest.TestCase):
+    """The regression CI found, pinned so it cannot come back.
+
+    Asking `available()` unconditionally at startup took the macOS CI leg from **35
+    seconds to 643**. Every launch on a Mac without Whisper models was compiling Swift
+    and then sitting on `--probe` until it timed out, because the probe waits for an
+    authorization dialog a headless machine never answers.
+
+    A user's first launch would have done the same thing: a full minute of nothing
+    before a pill appeared, on a machine that had asked for none of it. So `auto` uses
+    what is *ready*, and naming the engine is what builds it.
+    """
+
+    def test_auto_will_not_compile_anything(self):
+        seen = {}
+
+        def fake(compile_if_missing=True, timeout=60.0):
+            seen["compile"] = compile_if_missing
+            seen["timeout"] = timeout
+            return False, "not built yet"
+
+        with mock.patch.object(sys, "platform", "darwin"), \
+                mock.patch("flow.__main__._models_present", return_value=False), \
+                mock.patch.object(native, "available", fake):
+            _engine(args(), "base.en", "small.en")
+        self.assertFalse(seen["compile"])
+
+    def test_and_will_not_wait_a_minute_on_a_permission_dialog(self):
+        seen = {}
+
+        def fake(compile_if_missing=True, timeout=60.0):
+            seen["timeout"] = timeout
+            return False, "not built yet"
+
+        with mock.patch.object(sys, "platform", "darwin"), \
+                mock.patch("flow.__main__._models_present", return_value=False), \
+                mock.patch.object(native, "available", fake):
+            _engine(args(), "base.en", "small.en")
+        self.assertLessEqual(seen["timeout"], 15.0)
+
+    def test_naming_the_engine_is_what_builds_it(self):
+        # The other half of the rule. Somebody who typed `--engine native` has asked for
+        # the compile and is willing to wait for it.
+        seen = {}
+
+        def fake(compile_if_missing=True, timeout=60.0):
+            seen["compile"] = compile_if_missing
+            return True, ""
+
+        with mock.patch.object(sys, "platform", "darwin"), \
+                mock.patch.object(native, "available", fake):
+            self.assertEqual(_engine(args("native"), "base.en", "small.en")[0],
+                             "native")
+        self.assertTrue(seen["compile"])
+
+    def test_an_unbuilt_helper_says_how_to_build_it(self):
+        with mock.patch.object(sys, "platform", "darwin"), \
+                mock.patch.object(Path, "exists", return_value=False):
+            ok, why = native.available(compile_if_missing=False)
+        self.assertFalse(ok)
+        self.assertIn("--engine native", why)
+
+    def test_a_probe_that_hangs_is_named_as_the_dialog_it_is(self):
+        # "probe failed: TimeoutExpired" is true and useless. The fix is a click, and
+        # the sentence should say so.
+        with mock.patch.object(sys, "platform", "darwin"), \
+                mock.patch.object(Path, "exists", return_value=True), \
+                mock.patch.object(native, "_run",
+                                  side_effect=subprocess.TimeoutExpired("probe", 10)):
+            ok, why = native.available(timeout=10.0)
+        self.assertFalse(ok)
+        self.assertIn("Speech Recognition", why)
+
+    def test_every_reason_survives_the_console_the_startup_line_prints_to(self):
+        # `say()` writes to a cp437 console on Windows, and these strings reach it
+        # through `_engine`. An em dash here is a launch that dies on its own
+        # explanation — which is exactly how this was found.
+        for reason in ("not built yet", "no Swift toolchain", "probe timed out"):
+            with self.subTest(reason=reason):
+                pass
+        import inspect
+
+        source = inspect.getsource(native)
+        for line in source.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#") or '"' not in line:
+                continue
+            for chunk in line.split('"')[1::2]:
+                with self.subTest(chunk=chunk[:40]):
+                    chunk.encode("cp437")
+
+
 class TestTheModelPresenceCheckNeverDownloads(unittest.TestCase):
     """It is asked *because* the network may be unusable; it must not use it."""