@hasna/recordings 0.2.14 → 0.3.2

package/scripts/vacuity-mutation-battery.ts

@@ -0,0 +1,266 @@
+/**
+ * Mutation battery for the indexOf/-1 vacuity sweep (OPE41-00029).
+ *
+ * A converted ordering assertion is only proven non-vacuous by an input that makes it FAIL. This
+ * driver takes a manifest of mutations and, for each one:
+ *
+ *   1. asserts the mutation actually CHANGED the file — a positive control, because a needle that
+ *      never matched, or an occurrence index past the last match, would otherwise read as a caught
+ *      mutation when nothing was mutated at all;
+ *   2. runs the target test CLEAN and requires it to PASS — without this control an already-red
+ *      test makes every mutation look caught, which is the inverse trap;
+ *   3. applies the mutation and requires the named test to FAIL;
+ *   4. restores the file byte-for-byte from the copy held in memory, never from git, so sibling
+ *      working-tree edits are never reverted.
+ *
+ * Mutation kinds, and why one is not enough:
+ *
+ *   delete     — remove the Nth occurrence of a needle. The occurrence index is not optional.
+ *                `options: .atomic` occurs twice in RecordingsApp.swift and only the SECOND is
+ *                inside the region under test, so deleting the first must stay GREEN; a harness
+ *                that always deletes the first records a false survivor and sends someone to
+ *                "fix" a guard that was working. Three more needles are masked the same way by an
+ *                earlier occurrence that is the helper's own DEFINITION rather than its call site.
+ *   swap       — exchange two needles' text so the ordering flips. An ordering assertion that
+ *                survives a REORDER is the same vacuity class this sweep exists to close wearing
+ *                different clothes, and it is entirely invisible to a deletion-only harness.
+ *   duplicate  — insert a second copy of a needle. This is what separates a uniqueness bound from
+ *                a bare `toContain`: the `toContain` stays green on a duplicate, the bound does not.
+ *   corrupt    — replace a string literal in the TEST at an exact byte offset with a sentinel that
+ *                cannot occur in any source. Equivalent, from the assertion's point of view, to
+ *                deleting that needle from the source, but it needs no map from haystack variable
+ *                to source path, so it covers every converted site mechanically.
+ *
+ * Needles may contain \n and \t as escapes, because several properties can only be pinned by a
+ * whole-line needle (a bare helper name matches its own definition first).
+ *
+ * Exit codes come from spawnSync status, never through a pipe. Runs are strictly serial: a sibling
+ * assertion in capture-probe.test.ts scans a shared /tmp, so concurrent suites corrupt each other.
+ *
+ * Usage: bun scripts/vacuity-mutation-battery.ts <manifest.tsv> [--only <substring>]
+ * Manifest, tab-separated: kind <TAB> testFile <TAB> testName <TAB> targetFile <TAB> a <TAB> b
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+type Kind = "delete" | "swap" | "duplicate" | "corrupt";
+type Row = { kind: Kind; testFile: string; testName: string; target: string; a: string; b: string };
+
+const [manifestPath, ...rest] = process.argv.slice(2);
+if (!manifestPath) {
+  console.error("usage: bun scripts/vacuity-mutation-battery.ts <manifest.tsv> [--only <substr>]");
+  process.exit(2);
+}
+const onlyIndex = rest.indexOf("--only");
+const only = onlyIndex >= 0 ? rest[onlyIndex + 1] : undefined;
+
+const rows: Row[] = readFileSync(manifestPath, "utf8")
+  .split("\n")
+  .filter((line) => line.trim() && !line.startsWith("#"))
+  .map((line, index) => {
+    const [kind, testFile, testName, target, a, b] = line.split("\t");
+    // Fail loudly on a malformed row. Redirecting the generator with `2>&1` merges its progress line
+    // into the manifest, which parsed as a row with an undefined target and crashed the driver 164
+    // rows in — after all the expensive work, and with a stack trace that named the wrong cause.
+    if (!kind || !testFile || !testName || !target) {
+      console.error(`manifest line ${index + 1} is malformed (${line.split("\t").length} fields): ${line.slice(0, 120)}`);
+      process.exit(2);
+    }
+    return { kind: kind as Kind, testFile, testName, target, a: a ?? "", b: b ?? "" };
+  })
+  .filter((r) => !only || `${r.testFile} ${r.testName} ${r.a}`.includes(only));
+
+/** Byte offset of the nth (1-based) occurrence, or -1. */
+function nthIndex(haystack: string, needle: string, n: number): number {
+  let at = -1;
+  for (let i = 0; i < n; i++) {
+    at = haystack.indexOf(needle, i === 0 ? 0 : at + 1);
+    if (at < 0) return -1;
+  }
+  return at;
+}
+
+/** TSV cannot carry literal tabs or newlines, so needles arrive escaped. */
+function unescape(text: string): string {
+  return text.replace(/\\n/g, "\n").replace(/\\t/g, "\t");
+}
+
+/** Apply a mutation, or return undefined — which the caller treats as a control FAILURE. */
+function mutate(row: Row, original: string): string | undefined {
+  const a = unescape(row.a);
+  const b = unescape(row.b);
+
+  if (row.kind === "corrupt") {
+    // Deliberately NOT unescaped: this mutates the test file's RAW bytes, and a `\n` inside a
+    // TypeScript string literal is two bytes on disk. Unescaping it would move the offset and the
+    // guard below would reject every row — silently, as a control failure rather than a survivor.
+    const offset = Number(row.a);
+    if (!Number.isFinite(offset)) return undefined;
+    if (original.slice(offset, offset + row.b.length) !== row.b) return undefined;
+    return (
+      original.slice(0, offset) +
+      row.b +
+      "__OPE41_00029_ABSENT__" +
+      original.slice(offset + row.b.length)
+    );
+  }
+
+  if (row.kind === "delete") {
+    const at = nthIndex(original, a, Number(row.b || "1"));
+    if (at < 0) return undefined;
+    return original.slice(0, at) + original.slice(at + a.length);
+  }
+
+  if (row.kind === "duplicate") {
+    const at = nthIndex(original, a, Number(row.b || "1"));
+    if (at < 0) return undefined;
+    return original.slice(0, at + a.length) + a + original.slice(at + a.length);
+  }
+
+  if (row.kind === "swap") {
+    const atA = original.indexOf(a);
+    const atB = original.indexOf(b);
+    if (atA < 0 || atB < 0 || a === b) return undefined;
+    const firstAt = Math.min(atA, atB);
+    const secondAt = Math.max(atA, atB);
+    const [first, second] = atA < atB ? [a, b] : [b, a];
+    if (firstAt + first.length > secondAt) return undefined; // overlapping; cannot swap cleanly
+    return (
+      original.slice(0, firstAt) +
+      second +
+      original.slice(firstAt + first.length, secondAt) +
+      first +
+      original.slice(secondAt + second.length)
+    );
+  }
+  return undefined;
+}
+
+/**
+ * `bun test -t` takes a REGEX, not a substring.
+ *
+ * A test named `rendering RecordingEngine.logResolvedTrigger()'s format string parses as expected`
+ * contains `()`, which as a pattern is an empty capture group, so the literal parentheses in the
+ * name are never matched and bun reports `matched 0 tests` and exits 1. Unescaped, that presented as
+ * RED-ON-CLEAN — a refusal to conclude rather than a false pass, but still two sites left unproven
+ * for a reason that had nothing to do with them.
+ */
+function escapeForTestFilter(name: string): string {
+  return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function runTest(testFile: string, testName: string): { code: number; output: string } {
+  const filter = escapeForTestFilter(testName);
+  const result = spawnSync("bun", ["test", testFile, "-t", filter, "--timeout", "120000"], {
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return { code: result.status ?? 1, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+
+/** Did the filter select anything? 0 pass 0 fail exits 0 and would read as a clean pass. */
+function ranSomething(output: string): boolean {
+  const p = output.match(/(\d+)\s+pass/);
+  const f = output.match(/(\d+)\s+fail/);
+  return (p ? Number(p[1]) : 0) + (f ? Number(f[1]) : 0) > 0;
+}
+
+type Verdict =
+  | "KILLED"
+  | "KILLED-UNATTRIBUTED"
+  | "SURVIVED"
+  | "MUTATION-NOT-APPLIED"
+  | "RED-ON-CLEAN"
+  | "FILTER-MATCHED-NOTHING";
+
+/**
+ * A red test is not automatically proof that the converted assertion fired.
+ *
+ * Most of these suites EXECUTE the script they also read, so deleting a needle from
+ * `install_macos_app.sh` can break the run and fail `expect(result.exitCode).toBe(0)` long before
+ * the ordering assertion is reached. The driver would see a non-zero exit and record KILLED while
+ * the assertion under test did nothing at all — a kill credited to the wrong cause is exactly the
+ * "evidence that does not prove the claim" this sweep exists to remove.
+ *
+ * So a kill only counts when the failure output carries one of the guard's own messages. Anything
+ * else is reported as KILLED-UNATTRIBUTED and proves nothing about the site.
+ *
+ * The patterns are deliberately fragments rather than whole sentences. Suites add their own named
+ * guards — "test override is missing entirely: ...", "resolver function is missing entirely: ..." —
+ * and a signal list enumerating only the helper's own wording reported those as UNATTRIBUTED, which
+ * cost two hand-attributions that the driver should have made itself.
+ */
+const GUARD_SIGNAL =
+  /(is missing entirely|marker is missing|marker is not unique|too small to assert anything about|is missing or out of order|no longer sanitizes)/;
+
+function attributed(output: string): boolean {
+  return GUARD_SIGNAL.test(output);
+}
+
+const results: { row: Row; verdict: Verdict }[] = [];
+const cleanCache = new Map<string, "ok" | "red" | "no-match">();
+
+for (const [n, row] of rows.entries()) {
+  const label = `[${n + 1}/${rows.length}] ${row.kind} ${row.testFile} :: ${row.testName}`;
+  const original = readFileSync(row.target, "utf8");
+
+  const mutated = mutate(row, original);
+  if (mutated === undefined || mutated === original) {
+    results.push({ row, verdict: "MUTATION-NOT-APPLIED" });
+    console.log(`${label}\n    MUTATION-NOT-APPLIED  ${row.a.slice(0, 70)}`);
+    continue;
+  }
+
+  // The cache records WHY a clean run was unusable, not merely that it was. Collapsing both causes
+  // into one boolean made every row after the first report RED-ON-CLEAN, so a broken `-t` filter
+  // masqueraded as a failing test and pointed the reader at the wrong thing to fix.
+  const cleanKey = `${row.testFile} ${row.testName}`;
+  if (!cleanCache.has(cleanKey)) {
+    const clean = runTest(row.testFile, row.testName);
+    cleanCache.set(
+      cleanKey,
+      !ranSomething(clean.output) ? "no-match" : clean.code === 0 ? "ok" : "red",
+    );
+  }
+  const cleanState = cleanCache.get(cleanKey);
+  if (cleanState !== "ok") {
+    const verdict: Verdict = cleanState === "no-match" ? "FILTER-MATCHED-NOTHING" : "RED-ON-CLEAN";
+    results.push({ row, verdict });
+    console.log(`${label}\n    ${verdict} - no mutation verdict can be drawn here`);
+    continue;
+  }
+
+  try {
+    writeFileSync(row.target, mutated, "utf8");
+    const after = runTest(row.testFile, row.testName);
+    const verdict: Verdict =
+      after.code === 0 ? "SURVIVED" : attributed(after.output) ? "KILLED" : "KILLED-UNATTRIBUTED";
+    results.push({ row, verdict });
+    console.log(`${label}\n    ${verdict} (mutated exit ${after.code})  ${row.a.slice(0, 60)}`);
+  } finally {
+    writeFileSync(row.target, original, "utf8");
+  }
+}
+
+const tally = results.reduce<Record<string, number>>((acc, r) => {
+  acc[r.verdict] = (acc[r.verdict] ?? 0) + 1;
+  return acc;
+}, {});
+console.log(`\n==== BATTERY SUMMARY (${results.length} mutations) ====`);
+for (const [verdict, count] of Object.entries(tally).sort()) console.log(`${verdict}: ${count}`);
+
+const notKilled = results.filter((r) => r.verdict !== "KILLED");
+if (notKilled.length) {
+  console.log(`\n---- NOT KILLED (${notKilled.length}) ----`);
+  for (const s of notKilled) {
+    console.log(
+      `${s.verdict}\t${s.row.kind}\t${s.row.testFile}\t${s.row.testName}\t${s.row.a.slice(0, 60)}`,
+    );
+  }
+}
+
+// An instrument that always exits 0 is not a gate. Anything other than a clean kill — a survivor, a
+// kill credited to the wrong cause, or a control that could not be applied — has to be able to fail
+// a caller, or the summary is decoration that a script above it will happily ignore.
+process.exit(notKilled.length === 0 ? 0 : 1);

package/src/native/Recordings/App/MenuBarStatusView.swift

@@ -13,8 +13,10 @@ struct MenuBarStatusLabel: View {
     private var presentation: MenuBarPresentation {
         MenuBarPresentation(
             isRecording: store.engine.isRecording,
+            isWarmingUpCapture: store.engine.isWarmingUpCapture,
             canStartRecording: store.engine.canStartRecording,
-            statusMessage: store.engine.statusMessage
+            statusMessage: store.engine.statusMessage,
+            blockedReason: store.engine.blockedReason
         )
     }
 }
@@ -22,6 +24,9 @@ struct MenuBarStatusLabel: View {
 struct MenuBarStatusView: View {
     @ObservedObject var store: RecordingsStore
     let openRecordings: () -> Void
+    /// Bar-only builds have no workspace window to open; the entry point is hidden so
+    /// the affordance does not exist where the surface cannot exist.
+    let barOnly: Bool
 
     var body: some View {
         VStack(alignment: .leading, spacing: 12) {
@@ -43,16 +48,18 @@ struct MenuBarStatusView: View {
                     .frame(maxWidth: .infinity)
             }
             .buttonStyle(.borderedProminent)
-            .tint(store.engine.isRecording ? .red : .accentColor)
+            .tint(store.engine.captureIsActive ? .red : .accentColor)
             .disabled(!presentation.primaryActionEnabled)
 
             Divider()
 
-            Button(action: openRecordings) {
-                Label("Open Recordings", systemImage: "macwindow")
-                    .frame(maxWidth: .infinity, alignment: .leading)
+            if !barOnly {
+                Button(action: openRecordings) {
+                    Label("Open Recordings", systemImage: "macwindow")
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                }
+                .buttonStyle(.plain)
             }
-            .buttonStyle(.plain)
 
             SettingsLink {
                 Label("Settings", systemImage: "gearshape")
@@ -73,27 +80,32 @@ struct MenuBarStatusView: View {
     }
 
     private var statusColor: Color {
-        store.engine.isRecording ? .red : .accentColor
+        if store.engine.captureIsActive { return .red }
+        // The popover repeats the menu-bar signal rather than relying on the caption text, which
+        // is rendered `.secondary` and reads as an aside.
+        return presentation.isBlocked ? .orange : .accentColor
     }
 
     private var presentation: MenuBarPresentation {
         MenuBarPresentation(
             isRecording: store.engine.isRecording,
+            isWarmingUpCapture: store.engine.isWarmingUpCapture,
             canStartRecording: store.engine.canStartRecording,
-            statusMessage: store.engine.statusMessage
+            statusMessage: store.engine.statusMessage,
+            blockedReason: store.engine.blockedReason
         )
     }
 
     private var recordButtonTitle: String {
-        store.engine.isRecording ? "Stop and Transcribe" : "Start Recording"
+        store.engine.captureIsActive ? "Stop and Transcribe" : "Start Recording"
     }
 
     private var recordButtonIcon: String {
-        store.engine.isRecording ? "stop.fill" : "mic.fill"
+        store.engine.captureIsActive ? "stop.fill" : "mic.fill"
     }
 
     private func toggleRecording() {
-        if store.engine.isRecording {
+        if store.engine.captureIsActive {
             store.engine.stopAndTranscribe()
         } else {
             store.engine.startRecording()

package/src/native/Recordings/App/RecordingsApp.swift

@@ -56,6 +56,8 @@ final class RecordingsAppDelegate: NSObject, NSApplicationDelegate {
 final class RecordingsAppState: ObservableObject {
     let store: RecordingsStore?
     let declaresMenuBar: Bool
+    let barOnly: Bool
+    let declaresWindow: Bool
     let runtimeSmokeProbe: RuntimeSmokeProbe?
     private let runtimeSmokeMode: String?
     private let runtimeSmokeOutputPath: String?
@@ -67,6 +69,8 @@ final class RecordingsAppState: ObservableObject {
 
     init(plan: PermissionRequestLaunchPlan) {
         declaresMenuBar = plan.declaresMenuBar
+        barOnly = plan.isBarOnly
+        declaresWindow = plan.declaresWindow
         runtimeSmokeMode = plan.runtimeSmokeMode
         runtimeSmokeOutputPath = plan.runtimeSmokeOutputPath
         runtimeSmokeAcknowledgementPath = plan.runtimeSmokeAcknowledgementPath
@@ -86,6 +90,14 @@ final class RecordingsAppState: ObservableObject {
     }
 
     func openRecordings() {
+        // Bar launches never create the workspace window — on any path, including the
+        // reopen handler and the runtime smoke. Keyed on declaresWindow (NOT on
+        // declaresMainWindow, which excludes every runtime smoke): a full build's
+        // normal-mode smoke must keep exercising the window, and only bar builds finish
+        // windowless. This was the cycle-2 P1 of the terminated PR #269 lineage — a
+        // windowless branch keyed on declaresMainWindow made the FULL smoke fail
+        // deterministically on every build.
+        guard declaresWindow else { return }
         if let store {
             showWindow(contentView: NSHostingView(rootView: ContentView(store: store)))
         } else if runtimeSmokeMode == "normal" {
@@ -181,6 +193,23 @@ final class RecordingsAppState: ObservableObject {
         runtimeSmokeProbe.completed = { [weak self, weak runtimeSmokeProbe] in
             guard let self, let runtimeSmokeProbe else { return }
             let accessibility = RuntimeSmokeAccessibilitySnapshot.processMenuBarExtras()
+            if self.barOnly {
+                // Windowless by construction: the bar smoke must never create the
+                // workspace window, and it reports the windowless state directly. This
+                // branch keys on barOnly, NOT on declaresMainWindow — that property
+                // excludes every runtime smoke and made the FULL build's smoke fail
+                // deterministically in the terminated PR #269 lineage (cycle-2 P1). A
+                // nil-window comparison would also read as a retained window (nil ===
+                // nil), so the windowless result is finished here explicitly.
+                self.finishRuntimeSmoke(
+                    mode: mode,
+                    surfaceCount: runtimeSmokeProbe.surfaceAppearances,
+                    labels: runtimeSmokeProbe.renderedLabels,
+                    accessibility: accessibility,
+                    retainedWindowReused: false
+                )
+                return
+            }
             self.openRecordings()
             let firstWindow = self.mainWindow
             self.openRecordings()
@@ -202,6 +231,9 @@ final class RecordingsAppState: ObservableObject {
         retainedWindowReused: Bool,
         attempt: Int = 0
     ) {
+        // Only the non-bar smoke reaches this (bar launches finish windowless in the
+        // probe completion handler above), so the settled state is exactly the retained
+        // window being key, unchanged from the base contract.
         let windowSettled = NSApplication.shared.isActive && (mainWindow?.isKeyWindow ?? false)
         guard windowSettled || attempt >= 60 else {
             DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) { [weak self] in
@@ -316,7 +348,11 @@ struct RecordingsApp: App {
     @SceneBuilder var body: some Scene {
         MenuBarExtra(isInserted: menuBarInsertion) {
             if let store = state.store {
-                MenuBarStatusView(store: store, openRecordings: state.openRecordings)
+                MenuBarStatusView(
+                    store: store,
+                    openRecordings: state.openRecordings,
+                    barOnly: state.barOnly
+                )
             } else if state.runtimeSmokeProbe != nil {
                 EmptyView()
             }

package/src/native/Recordings/App/RuntimeSmoke.swift

@@ -21,8 +21,12 @@ final class RuntimeSmokeProbe: ObservableObject {
     var presentation: MenuBarPresentation {
         MenuBarPresentation(
             isRecording: phase == .recording,
+            // The smoke probe drives phases directly and never runs a real recorder, so it has
+            // no warm-up window.
+            isWarmingUpCapture: false,
             canStartRecording: phase == .idle,
-            statusMessage: phase == .transcribing ? "Transcribing" : "Ready"
+            statusMessage: phase == .transcribing ? "Transcribing" : "Ready",
+            blockedReason: nil
         )
     }
 

package/src/native/Recordings/App/SidebarView.swift

@@ -37,7 +37,7 @@ struct SidebarView: View {
                 withAnimation(.spring(response: 0.3, dampingFraction: 0.85)) { store.pane = .record }
             } label: {
                 rowLabel(icon: "mic.fill", label: "Record", count: nil,
-                         selected: store.pane == .record, accentDot: store.engine.isRecording)
+                         selected: store.pane == .record, accentDot: store.engine.captureIsActive)
             }
             .buttonStyle(.plain)
         }

package/src/native/Recordings/Package.swift

@@ -20,10 +20,24 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/sindresorhus/KeyboardShortcuts", exact: "1.12.0"),
-        // Swift Testing pinned to the toolchain-matched release. The stations build with
-        // CommandLineTools (no bundled Testing module), so the package is required — but it
-        // must track the compiler: the archived 0.99 shim under the 6.2 compiler silently
-        // corrupted `#expect` Bool-comparison evaluation, passing false assertions.
+        // Swift Testing. The stations build with CommandLineTools (no bundled Testing
+        // module), so the package is required. The original rule here was "the pin must
+        // track the compiler", because an archived 0.99 shim under the 6.2 compiler once
+        // silently corrupted `#expect` Bool-comparison evaluation, passing false assertions.
+        //
+        // Measured on station06 (Apple Swift 6.3.2, swiftlang-6.3.2.1.108): the 6.3.x line
+        // CANNOT be used here. From swift-6.3-RELEASE onward swift-testing's own manifest adds
+        // `.linkedLibrary("_TestingInterop")` under `#if compiler(>=6.3)`. That library ships
+        // in the toolchain at `$(xcode-select -p)/Library/Developer/usr/lib`, which is not on
+        // SwiftPM's default search path, so `swift build --build-tests` fails with
+        // `ld: library '_TestingInterop' not found`. It links only if every invocation adds
+        // `-Xlinker -L$(xcode-select -p)/Library/Developer/usr/lib`, which nothing in this repo
+        // supplies. Repinning to 6.3.2 would therefore break `swift test` for every caller.
+        //
+        // So the pin stays on the 6.2 line, and the rule it was standing in for is now
+        // enforced directly instead of by version matching: ExpectationIntegrityTests asserts
+        // that `#expect` both admits true Bool comparisons and *records issues* for false ones.
+        // That turns the silent failure mode into a red test, which a version pin never could.
         .package(url: "https://github.com/apple/swift-testing.git", revision: "swift-6.2-RELEASE"),
     ],
     targets: [
@@ -46,7 +60,12 @@ let package = Package(
         .executableTarget(
             name: "RecordingsUpdateBroker",
             dependencies: ["RecordingsUpdateProtocol", "RecordingsVerifierLauncher"],
-            path: "Updater/Broker"
+            path: "Updater/Broker",
+            // PeerIdentity resolves the XPC peer's audit token into a PID and EUID with
+            // audit_token_to_pid/_euid, which live in libbsm. Without this the broker
+            // compiles and then fails at link, which `swift build --target` does not
+            // surface because it stops short of linking the executable product.
+            linkerSettings: [.linkedLibrary("bsm")]
         ),
         .target(
             name: "RecordingsVerifierLauncher",

package/src/native/Recordings/RecordingsLib/EnhancementScreen.swift

@@ -0,0 +1,91 @@
+import Foundation
+
+/// Deterministic local pre-screen for the CLI's enhancement decision.
+///
+/// The helper CLI owns the real decision (`needsEnhancement` in `src/lib/enhancer.ts`):
+/// in `auto` post-processing mode it rewrites transcripts that carry an explicit
+/// configured trigger phrase or an instruction-shaped opening. Delivery may only run
+/// ahead of persistence when that rewrite provably cannot happen — the user asked for
+/// the rewritten text, so an eligible transcript must keep pasting the helper's output.
+///
+/// This screen therefore mirrors the CLI's detection *conservatively*: it answers
+/// "may the helper enhance this?" and fails closed (true) whenever it cannot decide.
+/// The trigger list is config-owned and arrives as the same frozen JSON array the
+/// engine already forwards to the helper via `--enhance-triggers-json`, so both sides
+/// read one source of truth for the configurable half. The instruction patterns mirror
+/// the CLI's built-in regexes; `EnhancementScreenTests` and the `enhancer.test.ts`
+/// "cross-language fixture" suite pin both implementations to one shared fixture table
+/// so they cannot drift apart silently.
+public enum EnhancementScreen {
+    /// Built-in instruction shapes, mirrored from `instructionPatterns` in
+    /// `src/lib/enhancer.ts`. Order and wording must match the CLI; the shared fixture
+    /// tests fail when either side changes alone.
+    static let instructionPatternSources: [String] = [
+        #"(?:write|draft|compose|create)\s+(?:an?\s+)?(?:email|message|response|reply|letter|note|text|slack|dm)"#,
+        #"(?:give|provide|send)\s+(?:them|him|her|it|the\s+agent|the\s+team)\s+(?:full\s+)?instructions"#,
+        #"(?:tell|ask)\s+(?:them|him|her|it|the\s+agent)\s+(?:to|that)"#,
+        #"(?:make\s+it|make\s+this)\s+(?:sound|look|read)\s+(?:more\s+)?(?:professional|formal|casual|friendly|better)"#,
+        #"(?:ok\s+so|okay\s+so|alright\s+so)\s+(?:say|write|tell|put)"#,
+        #"(?:i\s+need|i\s+want)\s+(?:the\s+agent|it|them|you)\s+to\s+(?:build|create|implement|design|make)"#,
+    ]
+
+    private static let instructionPatterns: [NSRegularExpression]? = {
+        var patterns: [NSRegularExpression] = []
+        for source in instructionPatternSources {
+            guard let pattern = try? NSRegularExpression(
+                pattern: source,
+                options: [.caseInsensitive]
+            ) else { return nil }
+            patterns.append(pattern)
+        }
+        return patterns
+    }()
+
+    /// True when the helper CLI could rewrite `text` in `auto` mode — or when this
+    /// screen cannot prove it will not (malformed trigger JSON, an unbuildable
+    /// pattern): enhancement-eligible speech must never be pasted raw ahead of the
+    /// helper, so every unprovable case persists first.
+    public static func mayRequireEnhancement(text: String, enhanceTriggersJSON: String) -> Bool {
+        guard let triggers = decodeTriggers(enhanceTriggersJSON) else { return true }
+        let lowered = text.lowercased()
+        for trigger in triggers {
+            let loweredTrigger = trigger.lowercased()
+            // An EMPTY configured trigger matches EVERYTHING in the CLI:
+            // `needsEnhancement` tests `lower.includes(trigger.toLowerCase())` and
+            // JavaScript's `includes("")` is true for every string, so one empty row
+            // makes the helper rewrite every transcript (MEASURED on the CLI:
+            // needs=true, reason `Explicit trigger: ""`). This screen must answer
+            // may-enhance for the same input or it admits that speech to
+            // paste-before-persistence and pastes raw text where the user asked for
+            // the rewrite.
+            //
+            // Special-cased rather than left to `contains`, because Swift's answer for
+            // an empty needle depends on which overload resolves — Foundation's
+            // `range(of:)`-based one answers false, the stdlib `Collection` one answers
+            // true — and NO machine has ever executed this file, so neither answer may
+            // be assumed. That overload claim is an UNVERIFIED INFERENCE from the
+            // language, not a measurement; `return true` is the fail-closed answer
+            // under either.
+            guard !loweredTrigger.isEmpty else { return true }
+            if lowered.contains(loweredTrigger) { return true }
+        }
+
+        guard let instructionPatterns else { return true }
+        let range = NSRange(text.startIndex..., in: text)
+        return instructionPatterns.contains { pattern in
+            pattern.firstMatch(in: text, range: range) != nil
+        }
+    }
+
+    /// Decodes the frozen trigger array the engine forwards to the helper. An empty
+    /// string means "no configured triggers" (the built-in patterns still apply);
+    /// anything else must parse as a JSON string array or the screen fails closed.
+    private static func decodeTriggers(_ json: String) -> [String]? {
+        let trimmed = json.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return [] }
+        guard let data = trimmed.data(using: .utf8),
+              let decoded = try? JSONDecoder().decode([String].self, from: data)
+        else { return nil }
+        return decoded
+    }
+}

package/src/native/Recordings/RecordingsLib/FnKeyMonitor.swift

@@ -12,15 +12,31 @@ final class FnKeyMonitor: @unchecked Sendable {
     private var healthCheckTimer: Timer?
     private var fnIsDown = false
 
-    var isRunning: Bool { eventTap != nil }
+    /// Whether the tap exists *and* is still enabled.
+    ///
+    /// `eventTap != nil` was not enough: macOS disables a tap when Accessibility is revoked
+    /// at runtime, and only `stop()` ever cleared the handle — so a dead tap reported itself
+    /// as running, the engine saw no blocker, and the `!isRunning` retry guard prevented
+    /// recovery. Ask the tap, not the handle.
+    var isRunning: Bool {
+        guard let eventTap else { return false }
+        return CGEvent.tapIsEnabled(tap: eventTap)
+    }
 
     private static let fnKeyCode: UInt16 = 63
 
     /// Start monitoring. Returns true if successful.
     func start() -> Bool {
-        guard eventTap == nil else {
-            fputs("[FnKeyMonitor] Already running\n", stderr)
-            return true
+        if eventTap != nil {
+            guard !isRunning else {
+                fputs("[FnKeyMonitor] Already running\n", stderr)
+                return true
+            }
+            // A handle we still hold but that the system has disabled cannot be revived by
+            // re-enabling it here — the grant that backed it is gone. Tear it down so the
+            // code below can build a fresh one once trust returns.
+            fputs("[FnKeyMonitor] Existing tap is disabled — discarding it before retry\n", stderr)
+            stop()
         }
 
         let eventMask: CGEventMask = 1 << CGEventType.flagsChanged.rawValue
@@ -63,6 +79,13 @@ final class FnKeyMonitor: @unchecked Sendable {
                 if !CGEvent.tapIsEnabled(tap: tap) {
                     fputs("[FnKeyMonitor] Tap was disabled, re-enabling\n", stderr)
                     CGEvent.tapEnable(tap: tap, enable: true)
+                    // If it will not come back, the permission behind it is gone. Drop the
+                    // tap so `isRunning` turns false and the engine can report a blocker and
+                    // rebuild, instead of polling a corpse every three seconds forever.
+                    if !CGEvent.tapIsEnabled(tap: tap) {
+                        fputs("[FnKeyMonitor] Re-enable failed — tearing down\n", stderr)
+                        self.stop()
+                    }
                 }
             }
 

package/src/native/Recordings/RecordingsLib/Info.plist

@@ -17,11 +17,11 @@
     <key>CFBundleIdentifier</key>
     <string>com.hasna.recordings</string>
     <key>CFBundleVersion</key>
-    <string>0.2.14</string>
+    <string>0.3.2</string>
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.2.14</string>
+    <string>0.3.2</string>
     <key>LSMinimumSystemVersion</key>
     <string>26.0</string>
     <key>NSMicrophoneUsageDescription</key>