@hasna/recordings 0.2.14 → 0.3.1

package/dist/cli/index.js

@@ -5,7 +5,7 @@ var __require = import.meta.require;
 // src/cli/index.ts
 import { Command } from "commander";
 
-// node_modules/@hasna/events/dist/commander.js
+// ../../node_modules/.bun/@hasna+events@0.1.11/node_modules/@hasna/events/dist/commander.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { homedir } from "os";
@@ -900,13 +900,13 @@ function collectValues(value, previous) {
 
 // src/cli/index.ts
 import chalk from "chalk";
-import { spawnSync as spawnSync4 } from "child_process";
+import { spawnSync as spawnSync7 } from "child_process";
 import {
-  existsSync as existsSync4,
-  readFileSync as readFileSync3,
+  existsSync as existsSync8,
+  readFileSync as readFileSync4,
   readdirSync as readdirSync2
 } from "fs";
-import { dirname as dirname4, join as pathJoin } from "path";
+import { dirname as dirname5, join as pathJoin } from "path";
 import { fileURLToPath } from "url";
 
 // src/lib/config.ts
@@ -1335,7 +1335,8 @@ function findProjectRecordingsPath(entry) {
 function findRepositoryRoot(start) {
   let dir = start;
   while (true) {
-    if (existsSync2(join3(dir, ".git")))
+    const gitPath = join3(dir, ".git");
+    if (isRepositoryMarker(gitPath))
       return dir;
     const parent = dirname2(dir);
     if (parent === dir)
@@ -1343,6 +1344,15 @@ function findRepositoryRoot(start) {
     dir = parent;
   }
 }
+function isRepositoryMarker(gitPath) {
+  try {
+    if (statSync(gitPath).isFile())
+      return true;
+    return existsSync2(join3(gitPath, "HEAD"));
+  } catch {
+    return false;
+  }
+}
 function canonicalExistingPath(path) {
   try {
     return realpathSync2(path);
@@ -1371,14 +1381,17 @@ function loadSecretKey(keyName) {
     try {
       const content = readFileSync(candidate, "utf-8");
       const match = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*"([^"]+)"`));
-      if (match)
-        return match[1];
+      const doubleQuotedValue = match?.[1];
+      if (doubleQuotedValue !== undefined)
+        return doubleQuotedValue;
       const match2 = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*'([^']+)'`));
-      if (match2)
-        return match2[1];
+      const singleQuotedValue = match2?.[1];
+      if (singleQuotedValue !== undefined)
+        return singleQuotedValue;
       const match3 = content.match(new RegExp(`${keyName}\\s*=\\s*(.+)`));
-      if (match3)
-        return match3[1].trim().replace(/^["']|["']$/g, "");
+      const unquotedValue = match3?.[1];
+      if (unquotedValue !== undefined)
+        return unquotedValue.trim().replace(/^["']|["']$/g, "");
     } catch {}
   }
   return "";
@@ -1536,6 +1549,7 @@ var MIGRATIONS = [
   ALTER TABLE agents ADD COLUMN active_project_id TEXT REFERENCES projects(id) ON DELETE SET NULL;
   `
 ];
+var CURRENT_MIGRATION_LEVEL = MIGRATIONS.length - 1;
 function getDatabase(dbPath) {
   if (_db)
     return _db;
@@ -1559,7 +1573,11 @@ function runMigrations(db) {
   const currentLevel = result?.max_id ?? -1;
   for (let i = currentLevel + 1;i < MIGRATIONS.length; i++) {
     try {
-      db.run(MIGRATIONS[i]);
+      const migration = MIGRATIONS[i];
+      if (migration === undefined) {
+        throw new Error(`Missing SQLite migration at version ${i}`);
+      }
+      db.run(migration);
       db.query("INSERT INTO _migrations (id) VALUES (?)").run(i);
     } catch (e) {
       if (isBenignMigrationError(e)) {
@@ -1909,7 +1927,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.14";
+var VERSION = "0.3.1";
 
 // src/db/feedback.ts
 function saveFeedback(input) {
@@ -1917,29 +1935,54 @@ function saveFeedback(input) {
   db.query("INSERT INTO feedback (message, email, category, version) VALUES (?, ?, ?, ?)").run(input.message, input.email ?? null, input.category ?? "general", input.version ?? VERSION);
 }
 
+// src/lib/retired-deployment-modes.ts
+var RETIRED_DEPLOYMENT_MODES = [
+  "local",
+  "self_hosted",
+  "cloud",
+  "remote",
+  "hybrid"
+];
+function normalizeModeToken(value) {
+  return value.trim().toLowerCase().replace(/-/g, "_");
+}
+function asRetiredDeploymentMode(value) {
+  const token = normalizeModeToken(value);
+  return RETIRED_DEPLOYMENT_MODES.includes(token) ? token : null;
+}
+function retiredDeploymentModeError(rawValue, sourceEnvKey, replacement) {
+  const mode = asRetiredDeploymentMode(rawValue);
+  const value = mode === "local" ? replacement.onBox : replacement.offBox;
+  return new Error(`${sourceEnvKey}=${rawValue} names a deployment mode, and deployment modes are removed: ` + `${RETIRED_DEPLOYMENT_MODES.join(" | ")} no longer select anything. ` + `Set ${replacement.envKey}=${value} instead ` + `(${replacement.envKey} takes ${replacement.onBox} or ${replacement.offBox}).`);
+}
+
 // src/http/client.ts
-var DEPRECATED_MODE_ALIASES = ["self_hosted", "remote", "hybrid"];
+var SERVER_BACKEND_VALUES = ["sqlite", "postgresql", "postgres"];
 function envToken(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
-function normalizeMode(value) {
-  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
-  if (normalized === "local")
-    return { mode: "local", deprecatedAlias: null };
-  if (normalized === "cloud")
-    return { mode: "cloud", deprecatedAlias: null };
-  if (DEPRECATED_MODE_ALIASES.includes(normalized)) {
-    return { mode: "cloud", deprecatedAlias: normalized };
+function clientStoreReplacement(envKey) {
+  return { envKey, onBox: "sqlite", offBox: "http" };
+}
+function normalizeClientStore(value, sourceEnvKey, replacementEnvKey) {
+  const normalized = normalizeModeToken(value);
+  if (normalized === "sqlite")
+    return "sqlite";
+  if (normalized === "http" || normalized === "https")
+    return "http";
+  if (asRetiredDeploymentMode(value)) {
+    throw retiredDeploymentModeError(value, sourceEnvKey, clientStoreReplacement(replacementEnvKey));
   }
-  throw new Error(`Unknown storage mode: ${value}. Use local or cloud.`);
+  throw new Error(`Unknown client store: ${value}. Use sqlite or http.`);
 }
-function defaultCloudBaseUrl(name) {
+function defaultApiBaseUrl(name) {
   return `https://${name}.hasna.xyz`;
 }
 function envKeys(name) {
   const token = envToken(name);
   return {
-    modeKeys: [`HASNA_${token}_STORAGE_MODE`, `HASNA_${token}_MODE`, `${token}_STORAGE_MODE`, `${token}_MODE`],
+    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
+    retiredModeKeys: [`HASNA_${token}_STORAGE_MODE`, `HASNA_${token}_MODE`, `${token}_STORAGE_MODE`, `${token}_MODE`],
     apiUrlKeys: [`HASNA_${token}_API_URL`, `${token}_API_URL`],
     apiKeyKeys: [`HASNA_${token}_API_KEY`, `${token}_API_KEY`]
   };
@@ -1952,6 +1995,20 @@ function firstEnv(env, keys) {
   }
   return null;
 }
+function assertNoRetiredMode(env, keys) {
+  for (const key of keys.retiredModeKeys) {
+    const value = env[key]?.trim();
+    if (!value)
+      continue;
+    const normalized = normalizeModeToken(value);
+    if (SERVER_BACKEND_VALUES.includes(normalized))
+      continue;
+    if (asRetiredDeploymentMode(value)) {
+      throw retiredDeploymentModeError(value, key, clientStoreReplacement(keys.storeKeys[0]));
+    }
+    throw new Error(`${key}=${value} is not a client store. ${key} no longer selects one; ` + `set ${keys.storeKeys[0]}=sqlite or ${keys.storeKeys[0]}=http instead.`);
+  }
+}
 function toV1BaseUrl(apiUrl) {
   const url = new URL(apiUrl);
   if (url.protocol !== "http:" && url.protocol !== "https:") {
@@ -1967,45 +2024,42 @@ function toV1BaseUrl(apiUrl) {
 }
 function resolveTransport(name, env = process.env) {
   const keys = envKeys(name);
-  const modeHit = firstEnv(env, keys.modeKeys);
+  assertNoRetiredMode(env, keys);
+  const storeHit = firstEnv(env, keys.storeKeys);
   const urlHit = firstEnv(env, keys.apiUrlKeys);
   const keyHit = firstEnv(env, keys.apiKeyKeys);
-  let mode = "local";
-  let deprecatedAlias = null;
+  let requested = "sqlite";
   let modeSource = "default";
-  if (modeHit) {
-    const normalized = normalizeMode(modeHit.value);
-    mode = normalized.mode;
-    deprecatedAlias = normalized.deprecatedAlias;
-    modeSource = modeHit.key;
+  if (storeHit) {
+    requested = normalizeClientStore(storeHit.value, storeHit.key, keys.storeKeys[0]);
+    modeSource = storeHit.key;
   } else if (urlHit && keyHit) {
-    mode = "cloud";
+    requested = "http";
     modeSource = "auto:api-url+api-key";
   }
-  if (mode === "local") {
-    return { transport: "local", mode, deprecatedAlias, modeSource, baseUrl: null, apiKeyPresent: Boolean(keyHit), misconfigured: false, warning: null };
+  if (requested === "sqlite") {
+    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: Boolean(keyHit), misconfigured: false, warning: null };
   }
   if (!keyHit) {
     return {
-      transport: "local",
-      mode,
-      deprecatedAlias,
+      transport: "sqlite",
+      requested,
       modeSource,
       baseUrl: null,
       apiKeyPresent: false,
       misconfigured: true,
-      warning: `${modeSource}=cloud but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to cloud.`
+      warning: `${modeSource}=http but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to the API.`
     };
   }
-  const rawUrl = urlHit?.value ?? defaultCloudBaseUrl(name);
+  const rawUrl = urlHit?.value ?? defaultApiBaseUrl(name);
   let baseUrl;
   try {
     baseUrl = toV1BaseUrl(rawUrl);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    return { transport: "local", mode, deprecatedAlias, modeSource, baseUrl: null, apiKeyPresent: true, misconfigured: true, warning: `Invalid API URL: ${message}.` };
+    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: true, misconfigured: true, warning: `Invalid API URL: ${message}.` };
   }
-  return { transport: "cloud-http", mode, deprecatedAlias, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
+  return { transport: "http", requested, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
 }
 
 class HasnaHttpError extends Error {
@@ -2117,6 +2171,8 @@ function createHttpTransport(options) {
       const jitter = Math.floor(Math.random() * (backoff / 2 + 1));
       await sleep(backoff + jitter);
     }
+    if (last === null)
+      throw new Error(`Request to ${rel} completed without a result`);
     throw last.error;
   }
   return {
@@ -2188,17 +2244,17 @@ function createStorageClient(name, transport) {
 function resolveStorageClient(name, env = process.env, fetchImpl) {
   const resolution = resolveTransport(name, env);
   if (resolution.misconfigured) {
-    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for cloud mode.`);
+    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the /v1 API.`);
   }
-  if (resolution.transport === "local" || !resolution.baseUrl) {
-    return { transport: "local", client: null, resolution };
+  if (resolution.transport === "sqlite" || !resolution.baseUrl) {
+    return { transport: "sqlite", client: null, resolution };
   }
   const keys = envKeys(name);
   const apiKey = firstEnv(env, keys.apiKeyKeys)?.value;
   if (!apiKey)
-    throw new Error(`Client for '${name}' resolved to cloud-http without an API key.`);
+    throw new Error(`Client for '${name}' resolved to the /v1 API without an API key.`);
   const transport = createHttpTransport({ name, baseUrl: resolution.baseUrl, apiKey, ...fetchImpl ? { fetchImpl } : {} });
-  return { transport: "cloud-http", client: createStorageClient(name, transport), resolution };
+  return { transport: "http", client: createStorageClient(name, transport), resolution };
 }
 
 // src/store.ts
@@ -2222,12 +2278,15 @@ function listQuery(filter) {
 }
 function unwrap(res, key) {
   if (res && typeof res === "object" && key in res) {
-    return res[key];
+    const value = res[key];
+    if (value === undefined)
+      throw new Error(`Response field ${key} is undefined`);
+    return value;
   }
   return res;
 }
 var localStore = {
-  mode: "local",
+  mode: "sqlite",
   baseUrl: null,
   async createRecording(input, idempotencyKey) {
     return withLocalStoreReaderLease(() => createRecording(input, undefined, idempotencyKey));
@@ -2280,7 +2339,7 @@ var localStore = {
 };
 function apiStore(client) {
   return {
-    mode: "cloud-http",
+    mode: "http",
     baseUrl: client.baseUrl,
     async createRecording(input, idempotencyKey) {
       const keyCandidate = idempotencyKey === undefined && (input.id === undefined || input.id === null) ? randomUUID5() : idempotencyKey;
@@ -2448,7 +2507,7 @@ function getStore(env = process.env) {
   if (env === process.env && cached)
     return cached;
   const resolved = resolveStorageClient(APP, env);
-  const store = resolved.transport === "cloud-http" ? apiStore(resolved.client) : localStore;
+  const store = resolved.transport === "http" ? apiStore(resolved.client) : localStore;
   if (env === process.env)
     cached = store;
   return store;
@@ -2509,10 +2568,14 @@ function startRecording(config) {
   const filename = `recording-${timestamp}.${config.audio_format}`;
   const filepath = join4(config.audio_dir, filename);
   const args = buildRecordArgs(filepath, config);
+  const [command, ...commandArgs] = args;
+  if (command === undefined) {
+    throw new RecordingError("Recording command is empty.");
+  }
   const releaseLease = isGlobalRecordingsStatePath(filepath) ? acquireLocalStoreReaderLease() : () => {};
   let recordProcess;
   try {
-    recordProcess = spawn2(args[0], args.slice(1), {
+    recordProcess = spawn2(command, commandArgs, {
       stdio: ["pipe", "pipe", "pipe"]
     });
   } catch (error) {
@@ -2621,6 +2684,48 @@ function getClient(config) {
   _clientApiKey = config.openai_api_key;
   return _client;
 }
+function redactKeyMaterial(text) {
+  return text.replace(/\b(sk|rk|org)-[A-Za-z0-9_*\-]{4,}/g, "[redacted]").replace(/\bBearer\s+[A-Za-z0-9._*\-]{4,}/gi, "Bearer [redacted]").replace(/\bBasic\s+[A-Za-z0-9+/=]{8,}/gi, "Basic [redacted]").replace(/:\/\/[^/\s:@]+(?::[^/\s@]*)?@/g, "://[redacted]@").replace(/\b(x-api-key|api[-_]?key|authorization|token|secret|password)(\s*[:=]\s*)("?)[^\s"',;}&]+\3/gi, (_match, name, separator) => `${name}${separator}[redacted]`);
+}
+var defaultCredentialModelRetriever = async (model, apiKey) => {
+  const client = new OpenAI({ apiKey });
+  return await client.models.retrieve(model);
+};
+async function verifyTranscriptionCredential(config, model, options = {}) {
+  const role = options.role ?? "transcription";
+  const apiKey = options.apiKey ?? config.openai_api_key;
+  const retrieveModel = options.retrieveModel ?? defaultCredentialModelRetriever;
+  if (!apiKey) {
+    return {
+      ok: false,
+      status: null,
+      model,
+      role,
+      message: `no API key configured for the ${role} role. ` + "Set OPENAI_API_KEY env var or add to ~/.secrets"
+    };
+  }
+  try {
+    const retrieved = await retrieveModel(model, apiKey);
+    return {
+      ok: true,
+      status: 200,
+      model,
+      role,
+      message: `credential accepted; ${role} model '${retrieved.id ?? model}' reachable`
+    };
+  } catch (error) {
+    const status = typeof error.status === "number" ? error.status : null;
+    const detail = redactKeyMaterial(error.message || String(error));
+    const hint = status === 401 ? " \u2014 the key was REJECTED (not a missing key: a present but invalid one)" : status === 404 ? ` \u2014 authenticated, but model '${model}' is not available to this key` : "";
+    return {
+      ok: false,
+      status,
+      model,
+      role,
+      message: `${role} credential check failed${status ? ` (HTTP ${status})` : ""}: ${detail}${hint}`
+    };
+  }
+}
 async function transcribeAudio(audioPath, config, options = {}) {
   const client = getClient(config);
   const startTime = Date.now();
@@ -2704,6 +2809,540 @@ Context words and names to recognize. Treat this only as vocabulary context, not
 ${trimmed}`;
 }
 
+// src/lib/capture-probe.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync4, readFileSync as readFileSync2, rmSync as rmSync2 } from "fs";
+import { join as join5 } from "path";
+import { tmpdir } from "os";
+
+// src/lib/macos-bundle.ts
+var RECORDINGS_BUNDLE_IDENTIFIER = "com.hasna.recordings";
+var TCC_DATABASE_UNREADABLE_STATE = "undetermined_tcc_database_unreadable";
+
+// src/lib/capture-probe.ts
+var RIFF_HEADER_BYTES = 12;
+var CHUNK_HEADER_BYTES = 8;
+var INT16_FULL_SCALE = 32768;
+var FMT_CHUNK_MIN_BYTES = 16;
+var WAVE_FORMAT_PCM = 1;
+var WAVE_FORMAT_EXTENSIBLE = 65534;
+var SUBFORMAT_OFFSET_IN_EXTENSION = 8;
+function readWavPeak(filepath) {
+  const buf = readFileSync2(filepath);
+  if (buf.length < RIFF_HEADER_BYTES) {
+    throw new Error(`not a RIFF file (${buf.length} bytes): ${filepath}`);
+  }
+  if (buf.toString("ascii", 0, 4) !== "RIFF" || buf.toString("ascii", 8, 12) !== "WAVE") {
+    throw new Error(`not a RIFF/WAVE file: ${filepath}`);
+  }
+  let offset = RIFF_HEADER_BYTES;
+  let bitsPerSample = null;
+  let formatTag = null;
+  let dataStart = -1;
+  let dataLength = 0;
+  while (offset + CHUNK_HEADER_BYTES <= buf.length) {
+    const chunkId = buf.toString("ascii", offset, offset + 4);
+    const chunkSize = buf.readUInt32LE(offset + 4);
+    const body = offset + CHUNK_HEADER_BYTES;
+    if (chunkId === "fmt " && formatTag === null) {
+      if (chunkSize < FMT_CHUNK_MIN_BYTES || body + FMT_CHUNK_MIN_BYTES > buf.length) {
+        throw new Error(`truncated fmt chunk (${chunkSize} bytes, need ${FMT_CHUNK_MIN_BYTES}): ${filepath}`);
+      }
+      formatTag = buf.readUInt16LE(body);
+      bitsPerSample = buf.readUInt16LE(body + 14);
+      if (formatTag === WAVE_FORMAT_EXTENSIBLE) {
+        const extensionStart = body + FMT_CHUNK_MIN_BYTES;
+        const subFormatAt = extensionStart + SUBFORMAT_OFFSET_IN_EXTENSION;
+        if (chunkSize < FMT_CHUNK_MIN_BYTES + 10 || subFormatAt + 2 > buf.length) {
+          throw new Error(`WAVE_FORMAT_EXTENSIBLE without a readable SubFormat GUID: ${filepath}`);
+        }
+        formatTag = buf.readUInt16LE(subFormatAt);
+      }
+    } else if (chunkId === "data" && dataStart < 0) {
+      dataStart = body;
+      const remaining = buf.length - body;
+      dataLength = chunkSize === 0 ? remaining : Math.min(chunkSize, remaining);
+    }
+    const declaredAdvance = chunkSize + chunkSize % 2;
+    offset = body + Math.min(declaredAdvance, Math.max(0, buf.length - body));
+  }
+  if (dataStart < 0) {
+    throw new Error(`no data chunk in WAV: ${filepath}`);
+  }
+  if (bitsPerSample === null || formatTag === null) {
+    throw new Error(`no fmt chunk in WAV, so the sample format is unknown: ${filepath}`);
+  }
+  if (formatTag !== WAVE_FORMAT_PCM) {
+    throw new Error(`expected uncompressed PCM (format tag ${WAVE_FORMAT_PCM}), got tag ${formatTag}: ${filepath}`);
+  }
+  if (bitsPerSample !== 16) {
+    throw new Error(`expected 16-bit PCM, got ${bitsPerSample}-bit: ${filepath}`);
+  }
+  const samples = Math.floor(dataLength / 2);
+  let maxAbs = 0;
+  for (let i = 0;i < samples; i++) {
+    const value = Math.abs(buf.readInt16LE(dataStart + i * 2));
+    if (value > maxAbs)
+      maxAbs = value;
+  }
+  return { samples, peak: maxAbs / INT16_FULL_SCALE };
+}
+var DEFAULT_PROBE_SECONDS = 1;
+var MAX_PROBE_SECONDS = 60;
+var DEFAULT_RECORD_EXECUTABLE = "rec";
+var SILENCE_PEAK_THRESHOLD = 0.001;
+var PROBE_TIMEOUT_GRACE_MS = 1e4;
+function probeMicrophoneCapture(config, options = {}) {
+  const requested = options.seconds ?? DEFAULT_PROBE_SECONDS;
+  const seconds = Math.min(Math.max(requested, 1), MAX_PROBE_SECONDS);
+  const executable = options.executable ?? DEFAULT_RECORD_EXECUTABLE;
+  const base = {
+    tool: null,
+    seconds,
+    samples: 0,
+    peak: 0,
+    silent: null
+  };
+  const filepath = join5(tmpdir(), `recordings-capture-probe-${process.pid}-${Date.now()}.wav`);
+  try {
+    const result = spawnSync2(executable, [
+      "-q",
+      "-r",
+      String(config.sample_rate),
+      "-c",
+      "1",
+      "-b",
+      "16",
+      filepath,
+      "trim",
+      "0",
+      String(seconds)
+    ], {
+      stdio: ["ignore", "ignore", "pipe"],
+      encoding: "utf8",
+      timeout: options.timeoutMs ?? seconds * 1000 + PROBE_TIMEOUT_GRACE_MS
+    });
+    if (result.signal) {
+      return {
+        ...base,
+        ok: false,
+        message: `'${executable}' did not finish within ` + `${((options.timeoutMs ?? seconds * 1000 + PROBE_TIMEOUT_GRACE_MS) / 1000).toFixed(1)}s ` + `and was killed (${result.signal}). The input device is most likely busy or absent.`
+      };
+    }
+    if (result.error) {
+      return {
+        ...base,
+        ok: false,
+        message: `could not run '${executable}': ${result.error.message}`
+      };
+    }
+    if (!existsSync4(filepath)) {
+      const stderr = (result.stderr || "").trim();
+      return {
+        ...base,
+        ok: false,
+        message: `'${executable}' wrote no audio file${stderr ? `: ${stderr}` : ""}`
+      };
+    }
+    let peak;
+    try {
+      peak = readWavPeak(filepath);
+    } catch (error) {
+      return {
+        ...base,
+        ok: false,
+        message: `could not read captured audio: ${error.message}`
+      };
+    }
+    const tool = executable;
+    if (peak.samples === 0) {
+      return {
+        ...base,
+        tool,
+        ok: false,
+        message: "capture produced no samples"
+      };
+    }
+    if (peak.peak <= SILENCE_PEAK_THRESHOLD) {
+      const subject = captureProbeSubject();
+      return {
+        ...base,
+        tool,
+        samples: peak.samples,
+        peak: peak.peak,
+        ok: false,
+        silent: true,
+        message: `captured ${peak.samples} samples with no usable signal ` + `(peak ${peak.peak.toFixed(6)}, at or below the ${SILENCE_PEAK_THRESHOLD} silence threshold). ` + (process.platform === "darwin" ? "On macOS this is what a process WITHOUT the Microphone permission receives \u2014 " + "CoreAudio zero-fills its buffers instead of returning an error. " + "Also rule out a hardware-muted or unselected input device. " : "The input device delivered no signal \u2014 check that it is selected and not muted. ") + `This probe's capture is attributed to ${subject.subject}. ${subject.note}`
+      };
+    }
+    return {
+      tool,
+      seconds,
+      samples: peak.samples,
+      peak: peak.peak,
+      silent: false,
+      ok: true,
+      message: `captured ${peak.samples} samples, peak amplitude ${peak.peak.toFixed(6)} ` + `(proves capture for ${captureProbeSubject().subject})`
+    };
+  } finally {
+    rmSync2(filepath, { force: true });
+  }
+}
+function captureProbeSubject(env = process.env, options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "darwin") {
+    return {
+      headless: false,
+      subject_known: true,
+      subject: "this process",
+      note: "microphone access is not gated by TCC on this platform"
+    };
+  }
+  const overSsh = Boolean(env.SSH_CONNECTION || env.SSH_TTY || env.SSH_CLIENT);
+  const inTmux = Boolean(env.TMUX || env.TMUX_PANE);
+  const termProgram = env.TERM_PROGRAM?.trim();
+  const hasTty = options.hasTty ?? Boolean(process.stdin.isTTY || process.stdout.isTTY);
+  if (overSsh) {
+    const subject2 = "the SSH session (sshd), not Recordings.app";
+    return {
+      headless: true,
+      subject_known: true,
+      subject: subject2,
+      note: "Running over SSH: macOS cannot display a consent prompt to a session with no GUI, " + "so Microphone stays not_determined and a silent capture here says NOTHING about " + "whether Recordings.app can record. Judge the app by its own TCC entry and its log."
+    };
+  }
+  if (inTmux) {
+    const subject2 = "the tmux server, not Recordings.app and not this pane's shell";
+    return {
+      headless: false,
+      subject_known: true,
+      subject: subject2,
+      note: "Running inside tmux: TCC attributes this capture to the tmux binary, which holds its " + "own grant. tmux also snapshots the environment at pane creation, so SSH variables may " + "be missing even in a remote session \u2014 treat a silent result as inconclusive about both " + "Recordings.app and about whether anyone could have been prompted."
+    };
+  }
+  if (!termProgram && !hasTty) {
+    return {
+      headless: true,
+      subject_known: false,
+      subject: "an unidentified responsible process (not Recordings.app)",
+      note: "The responsible process could not be identified: no SSH variables, no TERM_PROGRAM and " + "no tty, which is what launchd, cron, CI and sudo look like. Whatever holds the grant, it " + "is not Recordings.app, and nothing here can be shown a consent prompt. Inconclusive."
+    };
+  }
+  const subject = `${termProgram || "the terminal application running this command"}, not Recordings.app`;
+  return {
+    headless: false,
+    subject_known: Boolean(termProgram),
+    subject,
+    note: `Grants are per responsible process: this probe exercises ${subject}. ` + "A pass proves the microphone hardware and the input device work; it does not " + "transfer to Recordings.app, which needs its own grant."
+  };
+}
+var TCC_UNREADABLE_STATE = TCC_DATABASE_UNREADABLE_STATE;
+function classifyPermissionState(permissionState) {
+  switch (permissionState) {
+    case "allowed":
+    case "allowed_identity_unverified":
+    case "denied":
+    case "limited":
+    case "unknown":
+    case "stale_allowed_for_previous_app_build":
+    case "unverified_no_installed_bundle":
+      return "requested";
+    case "not_determined":
+      return "never_requested";
+    default:
+      break;
+  }
+  if (permissionState.startsWith("unknown("))
+    return "requested";
+  if (permissionState.endsWith("_identity_unverified"))
+    return "requested";
+  return "unknown";
+}
+function microphoneGrantInstruction(options) {
+  const candidates = [options.installedAppPath, ...options.otherAppPaths ?? []].filter((path) => Boolean(path)).filter((path, index, all) => all.indexOf(path) === index).filter((path) => existsSync4(path));
+  const bundlePath = candidates[0] ?? null;
+  const steps = [];
+  if (!bundlePath) {
+    steps.push("No Recordings.app bundle was found on disk, so there is nothing to grant Microphone to yet. " + "Install the app first ('recordings app install').");
+    return {
+      bundle_path: null,
+      bundle_identifier: RECORDINGS_BUNDLE_IDENTIFIER,
+      candidate_bundle_paths: candidates,
+      steps
+    };
+  }
+  if (candidates.length > 1) {
+    steps.push(`AMBIGUOUS: ${candidates.length} Recordings.app bundles exist (${candidates.join(", ")}). ` + "A TCC grant is bound to the bundle's code signature, so granting one does not grant the " + "other, and the toggle in Settings does not say which is which. Remove the bundles you are " + "not running before granting, or the grant may attach to the wrong one.");
+  }
+  steps.push(`At the keyboard on the machine itself (not over SSH), launch ${bundlePath} and start a ` + "recording once. macOS shows the consent sheet titled " + `"\u201CRecordings\u201D would like to access the microphone" \u2014 click Allow.`);
+  steps.push("If no sheet appears, open System Settings \u2192 Privacy & Security \u2192 Microphone " + "and switch ON the row named \u201CRecordings\u201D. " + `That row is bundle ${RECORDINGS_BUNDLE_IDENTIFIER} at ${bundlePath}; the binary that ` + `receives the grant is ${join5(bundlePath, "Contents", "MacOS", "Recordings")}.`);
+  if (options.requestState === "never_requested") {
+    steps.push("Note: the app has never requested microphone access on this machine (no TCC entry exists), " + "so the Microphone list will NOT contain a \u201CRecordings\u201D row until the app asks once. " + "Do the launch-and-record step first; the Settings toggle only exists afterwards.");
+  } else if (options.requestState === "unknown") {
+    steps.push("Note: whether the app has already asked could NOT be determined \u2014 the permission state " + `did not resolve (e.g. ${TCC_UNREADABLE_STATE}: the user TCC database could not be read). ` + "So a \u201CRecordings\u201D row may or may not already be in the Microphone list. Full Disk Access " + "is inherited from the session's responsible process, not granted per-tool, so re-read the " + "state from a plain ssh shell (whose parent holds it) rather than granting it to tmux or " + "bun \u2014 and not under sudo, which changes the responsible process. Do not conclude anything " + "from this state alone.");
+  }
+  steps.push("Confirm afterwards with 'recordings app status --json' \u2014 microphone_permission must read " + "allowed, and a fresh line in ~/.hasna/recordings/Recordings.log must read " + "'RecordingEngine init; microphone=Microphone allowed'.");
+  steps.push("The grant is bound to the bundle's code signature: re-signing or rebuilding the app with a " + "different identity voids it and this instruction has to be repeated.");
+  return {
+    bundle_path: bundlePath,
+    bundle_identifier: RECORDINGS_BUNDLE_IDENTIFIER,
+    candidate_bundle_paths: candidates,
+    steps
+  };
+}
+
+// src/lib/persistence-probe.ts
+import { Database as Database2 } from "bun:sqlite";
+import { existsSync as existsSync5 } from "fs";
+var AUTO_FLIP_MODE_SOURCE = "auto:api-url+api-key";
+function safeBaseUrl(baseUrl) {
+  if (!baseUrl)
+    return baseUrl;
+  try {
+    const url = new URL(baseUrl);
+    if (!url.username && !url.password)
+      return baseUrl;
+    url.username = "";
+    url.password = "";
+    return `${url.toString().replace(/\/+$/, "")} (credentials in the URL redacted)`;
+  } catch {
+    return "[unparseable URL redacted]";
+  }
+}
+function readLocalRecordingCount(dbPath) {
+  try {
+    const db = new Database2(dbPath, { readonly: true });
+    try {
+      const row = db.query("SELECT COUNT(*) AS count FROM recordings").get();
+      return typeof row?.count === "number" ? row.count : null;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
+function localStoreIsBehindSchema(dbPath) {
+  if (!existsSync5(dbPath))
+    return null;
+  try {
+    const db = new Database2(dbPath, { readonly: true });
+    try {
+      const row = db.query("SELECT MAX(id) AS max_id FROM _migrations").get();
+      const level = typeof row?.max_id === "number" ? row.max_id : -1;
+      return level < CURRENT_MIGRATION_LEVEL;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
+function describeActiveStore(config, env = process.env) {
+  const localDbPath = config.db_path;
+  const localDbPresent = existsSync5(localDbPath);
+  const localDbRecordings = localDbPresent ? readLocalRecordingCount(localDbPath) : null;
+  let resolution;
+  try {
+    resolution = resolveTransport(APP, env);
+  } catch (error) {
+    return {
+      transport: "sqlite",
+      mode_source: "unresolved",
+      base_url: null,
+      local_db_path: localDbPath,
+      local_db_present: localDbPresent,
+      local_db_recordings: localDbRecordings,
+      divergent: false,
+      warning: redactKeyMaterial(`could not resolve the active store: ${error.message}`)
+    };
+  }
+  const divergent = resolution.transport === "http" && (localDbRecordings ?? 0) > 0;
+  const warnings = [];
+  if (resolution.warning)
+    warnings.push(resolution.warning);
+  if (resolution.transport === "http" && localDbPresent && localDbRecordings === null) {
+    warnings.push(`writes go to ${safeBaseUrl(resolution.baseUrl)}, and ${localDbPath} exists but could not be counted, ` + "so whether a second dataset is sitting there is UNKNOWN \u2014 not 'none'.");
+  }
+  if (divergent) {
+    warnings.push(`writes go to ${safeBaseUrl(resolution.baseUrl)}, but ${localDbPath} still holds ` + `${localDbRecordings} recordings from an earlier on-box-only period. ` + "That file is NOT the live store \u2014 auditing it undercounts and looks like data loss.");
+  }
+  if (resolution.transport === "http" && resolution.modeSource === AUTO_FLIP_MODE_SOURCE) {
+    warnings.push("the API transport was selected by the mere PRESENCE of " + "HASNA_RECORDINGS_API_URL + HASNA_RECORDINGS_API_KEY, with no store variable set. " + "Check `launchctl getenv HASNA_RECORDINGS_API_URL` too: a launchd session variable " + "is inherited by the GUI app as well as by shells, and is invisible in a login profile.");
+  }
+  return {
+    transport: resolution.transport,
+    mode_source: resolution.modeSource,
+    base_url: safeBaseUrl(resolution.baseUrl),
+    local_db_path: localDbPath,
+    local_db_present: localDbPresent,
+    local_db_recordings: localDbRecordings,
+    divergent,
+    warning: warnings.length > 0 ? warnings.join(" ") : null
+  };
+}
+var PROBE_SEVERITY_GLYPHS = {
+  pass: "\u2713",
+  warn: "?",
+  fail: "\u2717"
+};
+function persistenceOutcomeSeverity(outcome) {
+  switch (outcome) {
+    case "proved":
+      return "pass";
+    case "skipped":
+      return "warn";
+    case "failed":
+      return "fail";
+  }
+}
+function renderPersistenceMarker(outcome, paint) {
+  const severity = persistenceOutcomeSeverity(outcome);
+  return paint[severity](PROBE_SEVERITY_GLYPHS[severity]);
+}
+var PERSISTENCE_PROBE_TAG = "check-probe";
+var PERSISTENCE_PROBE_MARKER_PREFIX = "recordings check --probe persistence round-trip";
+async function probeRecordingPersistence(options = {}) {
+  const store = options.store ?? getStore();
+  const stamp = (options.now?.() ?? new Date).toISOString();
+  const marker = `${PERSISTENCE_PROBE_MARKER_PREFIX} ${stamp}`;
+  const transport = store.mode === "http" ? "http" : "sqlite";
+  const base = {
+    attempted: false,
+    transport,
+    base_url: safeBaseUrl(store.baseUrl),
+    recording_id: null,
+    read_back: false,
+    cleaned_up: false,
+    created_local_store: false,
+    reachable: null
+  };
+  if (transport === "sqlite" && options.localStoreIsLegacy === true && !options.allowLocalMigration) {
+    return {
+      ...base,
+      ok: false,
+      outcome: "skipped",
+      message: "NOT MEASURED: the local SQLite store is behind the current schema, and writing to it " + "would apply pending migrations to a legacy file. Migrate deliberately " + "('recordings migrate') or re-run with --probe-store-write to accept the migration as " + "part of the probe."
+    };
+  }
+  if (transport === "http" && !options.allowRemoteWrite) {
+    let reachable = null;
+    let reachabilityDetail = "";
+    try {
+      await store.getRecordingStats();
+      reachable = true;
+      reachabilityDetail = " The store did answer a read-only stats request, so it is reachable " + "and the credential is accepted.";
+    } catch (error) {
+      reachable = false;
+      reachabilityDetail = " The store did NOT answer a read-only stats request: " + `${redactKeyMaterial(error.message)}.`;
+    }
+    return {
+      ...base,
+      reachable,
+      ok: false,
+      outcome: "skipped",
+      message: `NOT MEASURED: the write round-trip was skipped, because it would add a marker recording ` + `to the shared API store at ${safeBaseUrl(store.baseUrl)}, which is production for every ` + `machine pointed at it. Re-run with --probe-store-write to prove the write path for real.` + reachabilityDetail
+    };
+  }
+  let created = null;
+  try {
+    created = await store.createRecording({
+      raw_text: marker,
+      processing_mode: "raw",
+      model_used: "check-probe",
+      duration_ms: 0,
+      tags: ["diagnostic", PERSISTENCE_PROBE_TAG],
+      metadata: { persistence_probe: true, probed_at: stamp }
+    });
+  } catch (error) {
+    return {
+      ...base,
+      attempted: true,
+      ok: false,
+      outcome: "failed",
+      message: `store rejected the write: ${redactKeyMaterial(error.message)}. ` + "If this was a timeout rather than a refusal, the write may still have committed under " + `an id this process never saw \u2014 check with 'recordings search "${PERSISTENCE_PROBE_MARKER_PREFIX}"'.`
+    };
+  }
+  if (!created?.id) {
+    return {
+      ...base,
+      attempted: true,
+      ok: false,
+      outcome: "failed",
+      message: "store accepted the write but returned no id"
+    };
+  }
+  let readBack = false;
+  let readError = null;
+  try {
+    const fetched = await store.getRecording(created.id);
+    readBack = fetched?.raw_text === marker;
+    if (fetched && !readBack) {
+      readError = "the stored transcript did not match what was written";
+    } else if (!fetched) {
+      readError = "the write was accepted but the recording could not be read back";
+    }
+  } catch (error) {
+    readError = `read-back failed: ${redactKeyMaterial(error.message)}`;
+  }
+  let cleanedUp = false;
+  let cleanupError = null;
+  try {
+    const deleteReported = await store.deleteRecording(created.id);
+    if (!deleteReported) {
+      cleanupError = "the store reported nothing to delete";
+    } else {
+      const stillThere = await store.getRecording(created.id);
+      if (stillThere) {
+        cleanupError = "the store reported the delete succeeded but the recording is still readable";
+      } else {
+        cleanedUp = true;
+      }
+    }
+  } catch (error) {
+    cleanupError = redactKeyMaterial(error.message);
+  }
+  const createdLocalStore = transport === "sqlite" && options.localStoreExistedBefore === false;
+  const where = store.baseUrl ? `the API store at ${safeBaseUrl(store.baseUrl)}` : "the local SQLite store";
+  const createdNote = createdLocalStore ? " (this probe CREATED and migrated the local SQLite store, which did not exist before)" : "";
+  if (readError) {
+    return {
+      ...base,
+      attempted: true,
+      recording_id: created.id,
+      cleaned_up: cleanedUp,
+      created_local_store: createdLocalStore,
+      ok: false,
+      outcome: "failed",
+      message: `${readError} (${where}, id ${created.id.slice(0, 8)})${createdNote}`
+    };
+  }
+  if (!cleanedUp) {
+    return {
+      ...base,
+      attempted: true,
+      recording_id: created.id,
+      read_back: true,
+      cleaned_up: false,
+      created_local_store: createdLocalStore,
+      ok: false,
+      outcome: "failed",
+      message: `wrote and read back a marker recording in ${where}, but could NOT confirm its removal ` + `(${cleanupError ?? "cleanup failed"}). The probe recording ${created.id} may still be ` + `there \u2014 remove it with 'recordings delete ${created.id}'.${createdNote}`
+    };
+  }
+  return {
+    ...base,
+    attempted: true,
+    recording_id: created.id,
+    read_back: true,
+    cleaned_up: true,
+    created_local_store: createdLocalStore,
+    ok: true,
+    outcome: "proved",
+    message: `wrote, read back and confirmed removal of a marker recording in ${where}${createdNote}`
+  };
+}
+
 // src/lib/enhancer.ts
 import OpenAI2 from "openai";
 var _enhancementClient = null;
@@ -2968,80 +3607,805 @@ ${block}` : block;
 }
 
 // src/cli/macos-permissions.ts
-import { spawnSync as spawnSync2 } from "child_process";
-import { join as join5 } from "path";
-var defaultPermissionHelperRunner = (executable, arguments_, options) => spawnSync2(executable, arguments_, options);
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync6, mkdtempSync, rmSync as rmSync3, statSync as statSync2, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join6 } from "path";
+var defaultPermissionHelperRunner = (executable, arguments_, options) => spawnSync3(executable, arguments_, options);
 function runMacOSPermissionRequest(appPath, runner = defaultPermissionHelperRunner) {
-  const executable = join5(appPath, "Contents", "MacOS", "Recordings");
+  const executable = join6(appPath, "Contents", "MacOS", "Recordings");
   const result = runner(executable, ["--request-permissions", "--open-permission-settings"], { stdio: "inherit" });
   return {
     exitCode: result.error ? 1 : result.status ?? 1,
     errorMessage: result.error?.message
   };
 }
-
-// src/lib/machine.ts
-import { hostname } from "os";
-function currentMachineId(env = process.env, hostName = hostname()) {
-  const configured = env.HASNA_MACHINE_ID?.trim();
-  if (configured)
-    return configured;
-  return hostName.trim();
+var CODESIGN_REQUIREMENT_SATISFIED_STATUS = 0;
+var CODESIGN_REQUIREMENT_UNSATISFIED_STATUS = 3;
+function tccDatabasePaths(home) {
+  return [
+    join6(home, "Library", "Application Support", "com.apple.TCC", "TCC.db"),
+    join6("/", "Library", "Application Support", "com.apple.TCC", "TCC.db")
+  ];
 }
-
-// src/lib/bun-runtime.ts
-import { accessSync, constants as fsConstants, realpathSync as realpathSync3, statSync as statSync2 } from "fs";
-import { isAbsolute as isAbsolute2 } from "path";
-import { randomBytes } from "crypto";
-import { spawnSync as spawnSync3 } from "child_process";
-var BUN_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-var INSTALLER_ENVIRONMENT_KEYS = [
-  "HOME",
-  "SSH_CONNECTION",
-  "RECORDINGS_EXPECTED_TEAM_IDENTIFIER",
-  "RECORDINGS_LAUNCH_TIMEOUT_SECONDS",
-  "RECORDINGS_LOCK_STALE_SECONDS",
-  "RECORDINGS_MAINTENANCE_STALE_SECONDS",
-  "RECORDINGS_READER_DRAIN_TIMEOUT_MS",
-  "RECORDINGS_SQLITE_BUSY_TIMEOUT_MS"
-];
-var INSTALLER_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
-function validateBunExecutable(candidate) {
-  if (!isAbsolute2(candidate))
-    return { reason: "path is not absolute" };
-  let executable;
+function tccAuthValueLabel(value) {
+  switch (value) {
+    case "0":
+      return "denied";
+    case "1":
+      return "unknown";
+    case "2":
+      return "allowed";
+    case "3":
+      return "limited";
+    default:
+      return `unknown(${value})`;
+  }
+}
+var defaultCodesignRequirementRunner = (requirementPath, appPath) => spawnSync3("/usr/bin/codesign", ["--verify", "--verbose=2", "-R", requirementPath, appPath], { encoding: "utf8", stdio: ["ignore", "ignore", "ignore"] });
+function verifyStoredRequirementWithCodesign(csreqHex, appPath, runner = defaultCodesignRequirementRunner, bundleExists = existsSync6) {
+  const normalized = csreqHex.trim();
+  if (normalized.length === 0 || normalized.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(normalized)) {
+    return "unverifiable";
+  }
+  if (!appPath || !bundleExists(appPath))
+    return "unverifiable";
+  let scratchDirectory = null;
   try {
-    executable = realpathSync3(candidate);
-    if (!statSync2(executable).isFile())
-      return { reason: "resolved path is not a regular file" };
-    accessSync(executable, fsConstants.X_OK);
+    scratchDirectory = mkdtempSync(join6(tmpdir2(), "recordings-tcc-csreq-"));
+    const requirementPath = join6(scratchDirectory, "tcc-requirement.bin");
+    writeFileSync2(requirementPath, Buffer.from(normalized, "hex"));
+    const result = runner(requirementPath, appPath);
+    if (result.error)
+      return "unverifiable";
+    if (result.status === CODESIGN_REQUIREMENT_SATISFIED_STATUS)
+      return "satisfied";
+    if (result.status === CODESIGN_REQUIREMENT_UNSATISFIED_STATUS)
+      return "unsatisfied";
+    return "unverifiable";
   } catch {
-    return { reason: "path is missing, inaccessible, or not executable" };
+    return "unverifiable";
+  } finally {
+    if (scratchDirectory)
+      rmSync3(scratchDirectory, { recursive: true, force: true });
   }
-  const nonce = randomBytes(24).toString("hex");
-  const probe = spawnSync3(executable, [
-    "-e",
-    `
-        import { realpathSync, statSync } from "node:fs";
-        const expected = process.argv[1];
-        const nonce = process.argv[2];
-        const actual = process.execPath;
-        if (!expected || !nonce || realpathSync(actual) !== realpathSync(expected)) process.exit(66);
-        if (!statSync(actual).isFile()) process.exit(66);
-        if (!/^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/.test(Bun.version)) {
-          process.exit(66);
-        }
-        process.stdout.write(nonce + ":" + Bun.version);
-      `,
-    executable,
-    nonce
-  ], {
-    encoding: "utf8",
-    env: {
-      HOME: "/tmp",
-      PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
-      TMPDIR: "/tmp"
-    },
+}
+var defaultTccPermissionProbe = {
+  databasePresence: (dbPath) => {
+    try {
+      statSync2(dbPath);
+      return "present";
+    } catch (error) {
+      return error.code === "ENOENT" ? "absent" : "indeterminate";
+    }
+  },
+  readAccessRow: (dbPath, service) => {
+    const sql = "select ifnull(auth_value, '') || '|' || ifnull(hex(csreq), '') from access where service = '" + service.replace(/'/g, "''") + "' and client = '" + RECORDINGS_BUNDLE_IDENTIFIER + "' and client_type = 0 order by last_modified desc limit 1;";
+    const result = spawnSync3("/usr/bin/sqlite3", [dbPath, sql], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (result.error)
+      return { kind: "unreadable", detail: result.error.message };
+    if (result.status !== 0) {
+      const detail = (result.stderr ?? "").trim() || `sqlite3 exited ${result.status}`;
+      if (/no such table/i.test(detail))
+        return { kind: "absent" };
+      return { kind: "unreadable", detail };
+    }
+    const value = result.stdout?.trim() ?? "";
+    if (!value)
+      return { kind: "absent" };
+    const [authValue = "", csreqHex = ""] = value.split("|");
+    return { kind: "row", row: { authValue, csreqHex } };
+  },
+  verifyStoredRequirement: (csreqHex, appPath) => verifyStoredRequirementWithCodesign(csreqHex, appPath),
+  describeStoredRequirement: (csreqHex) => describeStoredRequirementWithCsreq(csreqHex)
+};
+function describeStoredRequirementWithCsreq(csreqHex, runner = (requirementPath) => spawnSync3("/usr/bin/csreq", ["-r", requirementPath, "-t"], {
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "ignore"]
+})) {
+  const normalized = csreqHex.trim();
+  if (normalized.length === 0 || normalized.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(normalized)) {
+    return null;
+  }
+  let scratchDirectory = null;
+  try {
+    scratchDirectory = mkdtempSync(join6(tmpdir2(), "recordings-tcc-decode-"));
+    const requirementPath = join6(scratchDirectory, "tcc-requirement.bin");
+    writeFileSync2(requirementPath, Buffer.from(normalized, "hex"));
+    const result = runner(requirementPath);
+    if (result.error || result.status !== 0)
+      return null;
+    const text = (result.stdout ?? "").trim();
+    return text.length > 0 ? text : null;
+  } catch {
+    return null;
+  } finally {
+    if (scratchDirectory)
+      rmSync3(scratchDirectory, { recursive: true, force: true });
+  }
+}
+function resolveTccGrant(options) {
+  const probe = options.probe ?? defaultTccPermissionProbe;
+  let sawUnreadableDatabase = false;
+  for (const dbPath of tccDatabasePaths(options.home)) {
+    const presence = probe.databasePresence(dbPath);
+    if (presence === "indeterminate") {
+      sawUnreadableDatabase = true;
+      continue;
+    }
+    if (presence === "absent")
+      continue;
+    const lookup = probe.readAccessRow(dbPath, options.service);
+    if (lookup.kind === "unreadable") {
+      sawUnreadableDatabase = true;
+      continue;
+    }
+    if (lookup.kind === "absent")
+      continue;
+    const row = lookup.row;
+    const storedRequirement = probe.describeStoredRequirement?.(row.csreqHex) ?? null;
+    const durability = classifyTccGrantDurability({
+      designatedRequirement: storedRequirement,
+      adHocSigned: false
+    });
+    const authValue = row.authValue.trim();
+    if (authValue.length === 0)
+      continue;
+    const label = tccAuthValueLabel(authValue);
+    if (label !== "allowed") {
+      return { state: label, storedRequirement, durability };
+    }
+    if (!options.appPath) {
+      return { state: "unverified_no_installed_bundle", storedRequirement, durability };
+    }
+    switch (probe.verifyStoredRequirement(row.csreqHex, options.appPath)) {
+      case "satisfied":
+        return { state: "allowed", storedRequirement, durability };
+      case "unsatisfied":
+        return { state: "stale_allowed_for_previous_app_build", storedRequirement, durability };
+      default:
+        return { state: "allowed_identity_unverified", storedRequirement, durability };
+    }
+  }
+  return {
+    state: sawUnreadableDatabase ? TCC_DATABASE_UNREADABLE_STATE : "not_determined",
+    storedRequirement: null,
+    durability: "unknown"
+  };
+}
+function classifyTccGrantDurability(options) {
+  if (options.adHocSigned)
+    return "dies_on_rebuild_cdhash_pinned";
+  const requirement = options.designatedRequirement?.trim();
+  if (!requirement)
+    return "unknown";
+  const operators = requirement.replace(/"[^"]*"/g, '""');
+  if (/\bcdhash\b/i.test(operators))
+    return "dies_on_rebuild_cdhash_pinned";
+  if (/\banchor\s+apple\s+generic\b/i.test(operators))
+    return "survives_rebuild_developer_id";
+  if (/\banchor\s+apple\b/i.test(operators))
+    return "survives_rebuild_certificate_anchored";
+  if (/\bcertificate\s+(root|leaf|\d+)\b|\banchor\s+H""/i.test(operators)) {
+    return "survives_rebuild_certificate_anchored";
+  }
+  return "unknown";
+}
+function describeTccAuthorizationSubject(appPath) {
+  if (!appPath) {
+    return `${RECORDINGS_BUNDLE_IDENTIFIER} (no installed bundle found \u2014 nothing to report a grant for)`;
+  }
+  return `${appPath} (${RECORDINGS_BUNDLE_IDENTIFIER})`;
+}
+
+// src/cli/macos-shortcut.ts
+import { spawnSync as spawnSync4 } from "child_process";
+import { existsSync as existsSync7 } from "fs";
+var TRIGGER_DEFAULTS_EXECUTABLE = process.platform === "darwin" ? "/usr/bin/defaults" : process.env.RECORDINGS_TEST_DEFAULTS_EXECUTABLE ?? null;
+var RECORDINGS_BUNDLE_ID = RECORDINGS_BUNDLE_IDENTIFIER;
+var SHORTCUT_USER_DEFAULTS_PREFIX = "KeyboardShortcuts_";
+var TOGGLE_RECORDING_SHORTCUT_NAME = "toggleRecording";
+var USE_FN_KEY_DEFAULTS_KEY = "useFnKey";
+var DEFAULT_TOGGLE_RECORDING_CHORD = "f5";
+var TOGGLE_RECORDING_DEFAULTS_KEY = `${SHORTCUT_USER_DEFAULTS_PREFIX}${TOGGLE_RECORDING_SHORTCUT_NAME}`;
+var TRIGGER_GRANT_REQUIREMENTS = [
+  {
+    id: "hotkey",
+    label: "Hotkey",
+    mechanism: "Carbon RegisterEventHotKey, via KeyboardShortcuts 1.12.0",
+    tccService: null,
+    settingsPath: null
+  },
+  {
+    id: "fn",
+    label: "fn/Globe",
+    mechanism: "CGEventTap (.defaultTap \u2014 it swallows fn)",
+    tccService: "kTCCServiceAccessibility",
+    settingsPath: "System Settings > Privacy & Security > Accessibility"
+  }
+];
+var NON_CHORD_KEYS = {
+  fn: "fn/Globe is not a Carbon key, so it cannot be part of a chord. Enable it with: recordings shortcut --fn on",
+  function: "fn/Globe is not a Carbon key, so it cannot be part of a chord. Enable it with: recordings shortcut --fn on",
+  globe: "fn/Globe is not a Carbon key, so it cannot be part of a chord. Enable it with: recordings shortcut --fn on",
+  "\uD83C\uDF10": "fn/Globe is not a Carbon key, so it cannot be part of a chord. Enable it with: recordings shortcut --fn on"
+};
+var CARBON_MODIFIERS = {
+  cmd: 256,
+  shift: 512,
+  opt: 2048,
+  ctrl: 4096
+};
+var MODIFIER_ALIASES = {
+  cmd: "cmd",
+  command: "cmd",
+  meta: "cmd",
+  super: "cmd",
+  "\u2318": "cmd",
+  shift: "shift",
+  "\u21E7": "shift",
+  opt: "opt",
+  option: "opt",
+  alt: "opt",
+  "\u2325": "opt",
+  ctrl: "ctrl",
+  control: "ctrl",
+  "\u2303": "ctrl"
+};
+var MODIFIER_GLYPHS = [
+  ["ctrl", "\u2303"],
+  ["opt", "\u2325"],
+  ["shift", "\u21E7"],
+  ["cmd", "\u2318"]
+];
+var CARBON_KEY_CODES = {
+  a: 0,
+  s: 1,
+  d: 2,
+  f: 3,
+  h: 4,
+  g: 5,
+  z: 6,
+  x: 7,
+  c: 8,
+  v: 9,
+  b: 11,
+  q: 12,
+  w: 13,
+  e: 14,
+  r: 15,
+  y: 16,
+  t: 17,
+  o: 31,
+  u: 32,
+  i: 34,
+  p: 35,
+  l: 37,
+  j: 38,
+  k: 40,
+  n: 45,
+  m: 46,
+  "1": 18,
+  "2": 19,
+  "3": 20,
+  "4": 21,
+  "6": 22,
+  "5": 23,
+  "9": 25,
+  "7": 26,
+  "8": 28,
+  "0": 29,
+  equal: 24,
+  minus: 27,
+  rightbracket: 30,
+  leftbracket: 33,
+  quote: 39,
+  semicolon: 41,
+  backslash: 42,
+  comma: 43,
+  slash: 44,
+  period: 47,
+  grave: 50,
+  tab: 48,
+  space: 49,
+  return: 36,
+  enter: 36,
+  delete: 51,
+  escape: 53,
+  esc: 53,
+  f1: 122,
+  f2: 120,
+  f3: 99,
+  f4: 118,
+  f5: 96,
+  f6: 97,
+  f7: 98,
+  f8: 100,
+  f9: 101,
+  f10: 109,
+  f11: 103,
+  f12: 111,
+  f13: 105,
+  f14: 107,
+  f15: 113,
+  f16: 106,
+  f17: 64,
+  f18: 79,
+  f19: 80,
+  f20: 90,
+  home: 115,
+  end: 119,
+  pageup: 116,
+  pagedown: 121,
+  left: 123,
+  right: 124,
+  down: 125,
+  up: 126
+};
+var KEY_LABELS = new Map;
+for (const [name, code] of Object.entries(CARBON_KEY_CODES)) {
+  if (!KEY_LABELS.has(code))
+    KEY_LABELS.set(code, name);
+}
+
+class ShortcutParseError extends Error {
+}
+function listBindableKeys() {
+  return Object.keys(CARBON_KEY_CODES);
+}
+function parseShortcutChord(input) {
+  const trimmed = input.trim();
+  if (!trimmed)
+    throw new ShortcutParseError("Shortcut is empty");
+  const normalized = trimmed.replace(/[\u2303\u2325\u21E7\u2318]/g, (glyph) => `${glyph}+`).toLowerCase();
+  const tokens = normalized.split("+").map((token) => token.trim()).filter((token) => token.length > 0);
+  if (tokens.length === 0)
+    throw new ShortcutParseError(`Could not parse shortcut "${input}"`);
+  let carbonModifiers = 0;
+  const keyTokens = [];
+  for (const token of tokens) {
+    const modifier = MODIFIER_ALIASES[token];
+    if (modifier) {
+      carbonModifiers |= CARBON_MODIFIERS[modifier];
+      continue;
+    }
+    keyTokens.push(token);
+  }
+  if (keyTokens.length === 0) {
+    throw new ShortcutParseError(`"${input}" is only modifiers \u2014 a shortcut needs a real key, e.g. "f13" or "ctrl+opt+r"`);
+  }
+  if (keyTokens.length > 1) {
+    throw new ShortcutParseError(`"${input}" names more than one key (${keyTokens.join(", ")}) \u2014 bind exactly one`);
+  }
+  const [keyToken] = keyTokens;
+  if (keyToken === undefined) {
+    throw new ShortcutParseError(`Could not parse shortcut "${input}"`);
+  }
+  const nonChordReason = NON_CHORD_KEYS[keyToken];
+  if (nonChordReason)
+    throw new ShortcutParseError(nonChordReason);
+  const carbonKeyCode = CARBON_KEY_CODES[keyToken];
+  if (carbonKeyCode === undefined) {
+    throw new ShortcutParseError(`Unknown key "${keyToken}" \u2014 see 'recordings shortcut --keys'`);
+  }
+  return { carbonKeyCode, carbonModifiers };
+}
+function formatShortcut(shortcut) {
+  let prefix = "";
+  for (const [token, glyph] of MODIFIER_GLYPHS) {
+    if ((shortcut.carbonModifiers & CARBON_MODIFIERS[token]) === CARBON_MODIFIERS[token]) {
+      prefix += glyph;
+    }
+  }
+  const label = KEY_LABELS.get(shortcut.carbonKeyCode);
+  return `${prefix}${label ? label.toUpperCase() : `keycode ${shortcut.carbonKeyCode}`}`;
+}
+var defaultBundleIdentifierReader = (bundlePath) => {
+  if (TRIGGER_DEFAULTS_EXECUTABLE === null)
+    return null;
+  if (!existsSync7(`${bundlePath}/Contents/Info.plist`) && !existsSync7(`${bundlePath}/Contents/Info`)) {
+    return null;
+  }
+  const result = spawnSync4(TRIGGER_DEFAULTS_EXECUTABLE, ["read", `${bundlePath}/Contents/Info`, "CFBundleIdentifier"], { encoding: "utf8" });
+  if (result.status !== 0)
+    return null;
+  return result.stdout.trim() || null;
+};
+var PROCESS_LISTER_EXECUTABLE = process.platform === "darwin" ? "/bin/ps" : process.env.RECORDINGS_TEST_PS_EXECUTABLE ?? "/bin/ps";
+var defaultProcessLister = () => {
+  const result = spawnSync4(PROCESS_LISTER_EXECUTABLE, ["-Awwo", "comm="], { encoding: "utf8" });
+  if (result.status !== 0)
+    return null;
+  return result.stdout;
+};
+function runningAppBundlePaths(probes = {}) {
+  const listProcesses = probes.listProcesses ?? defaultProcessLister;
+  const readBundleIdentifier = probes.readBundleIdentifier ?? defaultBundleIdentifierReader;
+  const listing = listProcesses();
+  if (!listing)
+    return [];
+  const suffixPattern = /\/Contents\/MacOS\/[^/]+$/;
+  const paths = new Set;
+  const identifierCache = new Map;
+  const readCached = (candidate) => {
+    const cached2 = identifierCache.get(candidate);
+    if (cached2 !== undefined)
+      return cached2;
+    const identifier = readBundleIdentifier(candidate);
+    identifierCache.set(candidate, identifier);
+    return identifier;
+  };
+  for (const raw of listing.split(`
+`)) {
+    const line = raw.trim();
+    const suffix = suffixPattern.exec(line);
+    if (!suffix)
+      continue;
+    const bundle = line.slice(0, suffix.index);
+    for (let index = bundle.indexOf("/");index !== -1; index = bundle.indexOf("/", index + 1)) {
+      const candidate = bundle.slice(index);
+      if (!isThisApp(candidate, readCached))
+        continue;
+      paths.add(candidate);
+      break;
+    }
+  }
+  return [...paths].sort();
+}
+function isThisApp(candidate, readBundleIdentifier) {
+  return readBundleIdentifier(candidate) === RECORDINGS_BUNDLE_ID;
+}
+function readDefault(key) {
+  if (TRIGGER_DEFAULTS_EXECUTABLE === null)
+    return null;
+  const result = spawnSync4(TRIGGER_DEFAULTS_EXECUTABLE, ["read", RECORDINGS_BUNDLE_ID, key], {
+    encoding: "utf8"
+  });
+  if (result.status !== 0)
+    return null;
+  return result.stdout.trim();
+}
+function writeDefault(key, value) {
+  if (TRIGGER_DEFAULTS_EXECUTABLE === null) {
+    throw new Error(`cannot write ${key}: this machine has no readable app UserDefaults domain`);
+  }
+  const result = spawnSync4(TRIGGER_DEFAULTS_EXECUTABLE, ["write", RECORDINGS_BUNDLE_ID, key, "-string", value], {
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    throw new Error(`defaults write ${key} failed: ${result.stderr?.trim() || `exit ${result.status}`}`);
+  }
+}
+function parseStoredShortcut(raw) {
+  if (!raw)
+    return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.carbonKeyCode !== "number" || typeof parsed.carbonModifiers !== "number") {
+      return null;
+    }
+    return { carbonKeyCode: parsed.carbonKeyCode, carbonModifiers: parsed.carbonModifiers };
+  } catch {
+    return null;
+  }
+}
+function readTriggerState() {
+  const rawShortcut = readDefault(TOGGLE_RECORDING_DEFAULTS_KEY);
+  const rawFn = readDefault(USE_FN_KEY_DEFAULTS_KEY);
+  return {
+    shortcut: parseStoredShortcut(rawShortcut),
+    rawShortcut,
+    useFnKey: rawFn === "1" || rawFn?.toLowerCase() === "true"
+  };
+}
+function writeShortcut(shortcut) {
+  writeDefault(TOGGLE_RECORDING_DEFAULTS_KEY, JSON.stringify({ carbonKeyCode: shortcut.carbonKeyCode, carbonModifiers: shortcut.carbonModifiers }));
+}
+function writeUseFnKey(enabled) {
+  if (TRIGGER_DEFAULTS_EXECUTABLE === null) {
+    throw new Error(`cannot write ${USE_FN_KEY_DEFAULTS_KEY}: this machine has no readable app UserDefaults domain`);
+  }
+  const result = spawnSync4(TRIGGER_DEFAULTS_EXECUTABLE, ["write", RECORDINGS_BUNDLE_ID, USE_FN_KEY_DEFAULTS_KEY, "-bool", enabled ? "true" : "false"], { encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error(`defaults write ${USE_FN_KEY_DEFAULTS_KEY} failed: ${result.stderr?.trim() || `exit ${result.status}`}`);
+  }
+}
+
+// src/cli/trigger-probe.ts
+import { closeSync, openSync, readSync, statSync as statSync3 } from "fs";
+var FN_BLOCKING_ACCESSIBILITY_STATES = [
+  "denied",
+  "stale_allowed_for_previous_app_build"
+];
+var APP_LOG_TAIL_BYTES = 1024 * 1024;
+var TRIGGER_LOG_MARKER = "trigger bindings:";
+function resolveHotkeyBinding(state) {
+  const base = { defaults_key: TOGGLE_RECORDING_DEFAULTS_KEY };
+  if (state.shortcut) {
+    return {
+      ...base,
+      state: "bound",
+      chord: formatShortcut(state.shortcut),
+      shortcut: state.shortcut,
+      stored_raw: state.rawShortcut,
+      can_fire: "yes"
+    };
+  }
+  if (state.rawShortcut === null) {
+    return {
+      ...base,
+      state: "default_pending",
+      chord: formatShortcut(parseShortcutChord(DEFAULT_TOGGLE_RECORDING_CHORD)),
+      shortcut: null,
+      stored_raw: null,
+      can_fire: "yes"
+    };
+  }
+  const normalized = state.rawShortcut.trim().toLowerCase();
+  if (normalized === "0" || normalized === "false") {
+    return {
+      ...base,
+      state: "cleared",
+      chord: null,
+      shortcut: null,
+      stored_raw: state.rawShortcut,
+      can_fire: "no"
+    };
+  }
+  return {
+    ...base,
+    state: "unreadable",
+    chord: null,
+    shortcut: null,
+    stored_raw: state.rawShortcut,
+    can_fire: "unknown"
+  };
+}
+function resolveFnTrigger(useFnKey, accessibilityPermission) {
+  const base = {
+    use_fn_key: useFnKey,
+    accessibility_permission: accessibilityPermission,
+    defaults_key: USE_FN_KEY_DEFAULTS_KEY
+  };
+  if (!useFnKey)
+    return { ...base, can_fire: "no" };
+  if (accessibilityPermission !== null) {
+    if (FN_BLOCKING_ACCESSIBILITY_STATES.includes(accessibilityPermission)) {
+      return { ...base, can_fire: "no" };
+    }
+    if (accessibilityPermission.startsWith("allowed"))
+      return { ...base, can_fire: "yes" };
+  }
+  return { ...base, can_fire: "unknown" };
+}
+function parseTriggerBindingsLog(logText) {
+  if (!logText)
+    return null;
+  const lines = logText.split(`
+`);
+  for (let index = lines.length - 1;index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined)
+      continue;
+    const markerAt = line.indexOf(TRIGGER_LOG_MARKER);
+    if (markerAt === -1)
+      continue;
+    const body = line.slice(markerAt + TRIGGER_LOG_MARKER.length);
+    const useFnKey = matchBoolean(body, "useFnKey");
+    const fnMonitorRunning = matchBoolean(body, "fnMonitorRunning");
+    if (useFnKey === null || fnMonitorRunning === null)
+      continue;
+    const blocked = matchField2(body, "blocked", null);
+    return {
+      observed_at: /^\[([^\]]+)\]/.exec(line)?.[1] ?? null,
+      shortcut_stored: matchField2(body, "shortcutStored", "shortcutArmed"),
+      use_fn_key: useFnKey,
+      fn_monitor_running: fnMonitorRunning,
+      microphone: matchField2(body, "microphone", "accessibility"),
+      accessibility: matchField2(body, "accessibility", "blocked"),
+      blocked: blocked === null || blocked === "none" ? null : blocked
+    };
+  }
+  return null;
+}
+function matchField2(body, field, nextField) {
+  const start = body.indexOf(`${field}=`);
+  if (start === -1)
+    return null;
+  const valueAt = start + field.length + 1;
+  if (nextField === null)
+    return body.slice(valueAt).trim() || null;
+  const end = body.indexOf(` ${nextField}=`, valueAt);
+  if (end === -1)
+    return body.slice(valueAt).trim() || null;
+  return body.slice(valueAt, end).trim() || null;
+}
+function matchBoolean(body, field) {
+  const match = new RegExp(`(?:^|\\s)${field}=(true|false)(?:\\s|$)`).exec(body);
+  if (!match)
+    return null;
+  return match[1] === "true";
+}
+function readAppLogTail(logPath, maxBytes = APP_LOG_TAIL_BYTES) {
+  if (!logPath)
+    return null;
+  let handle = null;
+  try {
+    const size = statSync3(logPath).size;
+    if (size === 0)
+      return null;
+    const length = Math.min(size, maxBytes);
+    const buffer = Buffer.allocUnsafe(length);
+    handle = openSync(logPath, "r");
+    const read = readSync(handle, buffer, 0, length, size - length);
+    return buffer.subarray(0, read).toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    if (handle !== null) {
+      try {
+        closeSync(handle);
+      } catch {}
+    }
+  }
+}
+function diagnoseTrigger(input) {
+  const hotkey = resolveHotkeyBinding(input.trigger);
+  const fn = resolveFnTrigger(input.trigger.useFnKey, input.accessibilityPermission);
+  const failures = [];
+  const warnings = [];
+  const notes = [];
+  const canFire = hotkey.can_fire !== "no" || fn.can_fire !== "no";
+  if (!canFire) {
+    failures.push(`No recording trigger can fire: ${describeHotkey(hotkey)}, and ${describeFn(fn)}. ` + `Nothing will start a recording from the keyboard. Fix it with one of:
+` + `    recordings shortcut --reset        (bind the app's default hotkey again)
+` + `    recordings shortcut --set "f13"    (bind a hotkey of your choosing)
+` + "    recordings shortcut --fn on        (use fn/Globe as push-to-talk)");
+  }
+  if (hotkey.state === "unreadable") {
+    warnings.push(`The stored hotkey value is not a shortcut this CLI can read (${hotkey.stored_raw}). ` + "The app decodes it with the same JSON shape, so it most likely registers no hotkey " + "either \u2014 but that is not proved here, so it is not counted as a failure. Re-bind it " + "with 'recordings shortcut --reset' to be certain.");
+  }
+  if (hotkey.state === "default_pending") {
+    notes.push(`No hotkey is stored, so the app registers its own default ${hotkey.chord} the next ` + "time it launches. Nothing is wrong; it is just not written down yet.");
+  }
+  if (hotkey.state === "cleared" && fn.can_fire !== "no") {
+    notes.push("The hotkey was explicitly cleared (the app stores a disabled marker rather than " + "removing the key), so fn/Globe is the only trigger.");
+  }
+  if (fn.use_fn_key && fn.can_fire === "no") {
+    warnings.push(`fn/Globe is enabled but its Accessibility grant is ${fn.accessibility_permission}, and ` + "the fn trigger is a CGEventTap that macOS will not create without it. Grant it in " + "System Settings > Privacy & Security > Accessibility, then quit and reopen the app.");
+  }
+  if (fn.use_fn_key && fn.can_fire === "unknown") {
+    warnings.push(`fn/Globe is enabled and its Accessibility grant reads ${fn.accessibility_permission ?? "unmeasured"}` + " \u2014 that is not a denial and not a pass, so whether the fn tap can be created is " + "undecided here. 'recordings app permissions' reports the grant in full.");
+  }
+  const observation = input.observation;
+  if (!observation) {
+    notes.push("The app has not logged a resolved trigger, so whether its fn event tap is running is " + "unknown. The app writes that line at launch and on every trigger change; if it is " + "absent the app has not run since the log was last truncated.");
+  } else {
+    const when = observation.observed_at ? ` at ${observation.observed_at}` : "";
+    notes.push(`The app last reported${when}: fn tap ${observation.fn_monitor_running ? "running" : "NOT running"}` + `, useFnKey=${observation.use_fn_key}, hotkey ${observation.shortcut_stored ?? "unreported"}.`);
+    if (observation.use_fn_key !== input.trigger.useFnKey) {
+      warnings.push(`The app is running with useFnKey=${observation.use_fn_key} while storage now says ` + `${input.trigger.useFnKey}${when ? ` (last reported${when})` : ""}. A running instance keeps ` + "the trigger it registered with, so the current setting is NOT armed \u2014 quit and " + "reopen the app.");
+    } else if (hotkey.state === "bound" && observation.shortcut_stored !== null && observation.shortcut_stored !== `carbonKeyCode=${hotkey.shortcut.carbonKeyCode} carbonModifiers=${hotkey.shortcut.carbonModifiers}`) {
+      warnings.push(`The app registered hotkey ${observation.shortcut_stored}${when} while storage now holds ` + `${hotkey.chord}. The running instance keeps what it registered with, so the stored ` + "hotkey is NOT armed \u2014 quit and reopen the app.");
+    }
+    if (observation.use_fn_key && !observation.fn_monitor_running) {
+      warnings.push(`The app itself reported its fn event tap NOT running${when}. It retries while ` + "Accessibility is trusted, so this may since have recovered \u2014 it is reported, not " + "counted as a failure. 'recordings app log' shows what happened next.");
+    }
+    if (observation.blocked) {
+      warnings.push(`The app reported its trigger blocked${when}: ${observation.blocked}`);
+    }
+  }
+  return {
+    can_fire: canFire,
+    summary: `hotkey ${describeHotkey(hotkey)}, ${describeFn(fn)}`,
+    defaults_domain: RECORDINGS_BUNDLE_ID,
+    hotkey,
+    fn,
+    app_observation: observation,
+    failures,
+    warnings,
+    notes
+  };
+}
+function describeHotkey(hotkey) {
+  switch (hotkey.state) {
+    case "bound":
+      return hotkey.chord;
+    case "default_pending":
+      return `${hotkey.chord} (the app's default, registered at next launch)`;
+    case "cleared":
+      return "cleared (nothing is registered)";
+    case "unreadable":
+      return `unreadable (${hotkey.stored_raw})`;
+  }
+}
+function describeFn(fn) {
+  if (!fn.use_fn_key)
+    return "fn/Globe off";
+  if (fn.can_fire === "no")
+    return `fn/Globe on but Accessibility is ${fn.accessibility_permission}`;
+  if (fn.can_fire === "unknown")
+    return "fn/Globe on, Accessibility undecided";
+  return "fn/Globe on";
+}
+function probeTriggerDiagnostics(input) {
+  if (TRIGGER_DEFAULTS_EXECUTABLE === null)
+    return null;
+  return diagnoseTrigger({
+    trigger: readTriggerState(),
+    accessibilityPermission: input.accessibilityPermission,
+    observation: parseTriggerBindingsLog(readAppLogTail(input.appLogPath))
+  });
+}
+function describeTriggerPickup(runningBundlePaths) {
+  return { armed: runningBundlePaths.length === 0, runningBundlePaths };
+}
+
+// src/lib/machine.ts
+import { hostname } from "os";
+function currentMachineId(env = process.env, hostName = hostname()) {
+  const configured = env.HASNA_MACHINE_ID?.trim();
+  if (configured)
+    return configured;
+  return hostName.trim();
+}
+
+// src/lib/bun-runtime.ts
+import { accessSync, constants as fsConstants, realpathSync as realpathSync3, statSync as statSync4 } from "fs";
+import { isAbsolute as isAbsolute2 } from "path";
+import { randomBytes } from "crypto";
+import { spawnSync as spawnSync5 } from "child_process";
+var BUN_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+var INSTALLER_ENVIRONMENT_KEYS = [
+  "HOME",
+  "SSH_CONNECTION",
+  "RECORDINGS_EXPECTED_TEAM_IDENTIFIER",
+  "RECORDINGS_LAUNCH_TIMEOUT_SECONDS",
+  "RECORDINGS_LOCK_STALE_SECONDS",
+  "RECORDINGS_MAINTENANCE_STALE_SECONDS",
+  "RECORDINGS_READER_DRAIN_TIMEOUT_MS",
+  "RECORDINGS_SQLITE_BUSY_TIMEOUT_MS"
+];
+var INSTALLER_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
+function validateBunExecutable(candidate) {
+  if (!isAbsolute2(candidate))
+    return { reason: "path is not absolute" };
+  let executable;
+  try {
+    executable = realpathSync3(candidate);
+    if (!statSync4(executable).isFile())
+      return { reason: "resolved path is not a regular file" };
+    accessSync(executable, fsConstants.X_OK);
+  } catch {
+    return { reason: "path is missing, inaccessible, or not executable" };
+  }
+  const nonce = randomBytes(24).toString("hex");
+  const probe = spawnSync5(executable, [
+    "-e",
+    `
+        import { realpathSync, statSync } from "node:fs";
+        const expected = process.argv[1];
+        const nonce = process.argv[2];
+        const actual = process.execPath;
+        if (!expected || !nonce || realpathSync(actual) !== realpathSync(expected)) process.exit(66);
+        if (!statSync(actual).isFile()) process.exit(66);
+        if (!/^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$/.test(Bun.version)) {
+          process.exit(66);
+        }
+        process.stdout.write(nonce + ":" + Bun.version);
+      `,
+    executable,
+    nonce
+  ], {
+    encoding: "utf8",
+    env: {
+      HOME: "/tmp",
+      PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+      TMPDIR: "/tmp"
+    },
     maxBuffer: 1024,
     stdio: ["ignore", "pipe", "ignore"],
     timeout: 5000
@@ -3086,17 +4450,17 @@ function createInstallerEnvironment(environment, bunExecutable) {
 import { createHash as createHash2 } from "crypto";
 import {
   chmodSync as chmodSync2,
-  closeSync,
+  closeSync as closeSync2,
   constants,
   fstatSync,
   fsyncSync,
-  mkdtempSync,
-  openSync,
-  readFileSync as readFileSync2,
-  rmSync as rmSync2,
-  writeFileSync as writeFileSync2
+  mkdtempSync as mkdtempSync2,
+  openSync as openSync2,
+  readFileSync as readFileSync3,
+  rmSync as rmSync4,
+  writeFileSync as writeFileSync3
 } from "fs";
-import { isAbsolute as isAbsolute3, join as join6 } from "path";
+import { isAbsolute as isAbsolute3, join as join7 } from "path";
 var LOWER_SHA256 = /^[a-f0-9]{64}$/;
 var LOWER_SOURCE_SHA = /^[a-f0-9]{40}$/;
 var RELEASE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
@@ -3169,7 +4533,7 @@ function prepareReleaseInstallInputs(input) {
   if (!isAbsolute3(snapshotRoot)) {
     throw new Error("release snapshot root must be absolute");
   }
-  const snapshotDirectory = mkdtempSync(join6(snapshotRoot, "recordings-release-install."));
+  const snapshotDirectory = mkdtempSync2(join7(snapshotRoot, "recordings-release-install."));
   let cleaned = false;
   const cleanup = () => {
     if (cleaned)
@@ -3178,12 +4542,12 @@ function prepareReleaseInstallInputs(input) {
     try {
       chmodSync2(snapshotDirectory, 448);
     } catch {}
-    rmSync2(snapshotDirectory, { recursive: true, force: true });
+    rmSync4(snapshotDirectory, { recursive: true, force: true });
   };
   try {
-    const manifestSnapshot = join6(snapshotDirectory, `${input.manifestSha256}.manifest.json`);
+    const manifestSnapshot = join7(snapshotDirectory, `${input.manifestSha256}.manifest.json`);
     const envelopeDigest = createHash2("sha256").update(envelopeBytes).digest("hex");
-    const envelopeSnapshot = join6(snapshotDirectory, `${envelopeDigest}.envelope.json`);
+    const envelopeSnapshot = join7(snapshotDirectory, `${envelopeDigest}.envelope.json`);
     writeSnapshot(manifestSnapshot, manifestBytes);
     writeSnapshot(envelopeSnapshot, envelopeBytes);
     chmodSync2(snapshotDirectory, 320);
@@ -3198,15 +4562,15 @@ function assertAbsolutePath(value, label) {
     throw new Error(`${label} path must be absolute`);
 }
 function readBoundedRegularFile(path, label, maximum) {
-  const descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  const descriptor = openSync2(path, constants.O_RDONLY | constants.O_NOFOLLOW);
   try {
     const metadata = fstatSync(descriptor);
     if (!metadata.isFile() || metadata.size < 1 || metadata.size > maximum) {
       throw new Error(`${label} must be a non-empty bounded regular file`);
     }
-    return readFileSync2(descriptor);
+    return readFileSync3(descriptor);
   } finally {
-    closeSync(descriptor);
+    closeSync2(descriptor);
   }
 }
 function parseObject(bytes, label) {
@@ -3285,12 +4649,73 @@ function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function writeSnapshot(path, bytes) {
-  writeFileSync2(path, bytes, { flag: "wx", mode: 256 });
-  const descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  writeFileSync3(path, bytes, { flag: "wx", mode: 256 });
+  const descriptor = openSync2(path, constants.O_RDONLY | constants.O_NOFOLLOW);
   try {
     fsyncSync(descriptor);
   } finally {
-    closeSync(descriptor);
+    closeSync2(descriptor);
+  }
+}
+
+// src/cli/desktop-snapshot.ts
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync4, mkdtempSync as mkdtempSync3, renameSync as renameSync2, rmSync as rmSync5, statSync as statSync5 } from "fs";
+import { dirname as dirname4, join as join8, resolve as resolve3 } from "path";
+import { spawnSync as spawnSync6 } from "child_process";
+var SCREEN_CAPTURE_EXECUTABLE = "/usr/sbin/screencapture";
+var DEFAULT_DESKTOP_SNAPSHOT = "desktop-snapshot.png";
+function runScreenCapture(executable, arguments_) {
+  const result = spawnSync6(executable, arguments_, {
+    encoding: "utf8",
+    stdio: ["ignore", "ignore", "pipe"]
+  });
+  return {
+    error: result.error,
+    status: result.status,
+    stderr: result.stderr
+  };
+}
+function exportDesktopSnapshot(output = DEFAULT_DESKTOP_SNAPSHOT, dependencies = {}) {
+  if ((dependencies.platform ?? process.platform) !== "darwin") {
+    throw new Error("Desktop snapshots are only supported on macOS");
+  }
+  const destination = resolve3(dependencies.cwd ?? process.cwd(), output);
+  const destinationDirectory = dirname4(destination);
+  mkdirSync4(destinationDirectory, { recursive: true });
+  const stagingDirectory = mkdtempSync3(join8(destinationDirectory, ".recordings-desktop-"));
+  chmodSync3(stagingDirectory, 448);
+  const stagingPath = join8(stagingDirectory, "snapshot.png");
+  try {
+    const capture = dependencies.capture ?? runScreenCapture;
+    const result = capture(SCREEN_CAPTURE_EXECUTABLE, [
+      "-x",
+      "-m",
+      "-C",
+      "-t",
+      "png",
+      stagingPath
+    ]);
+    if (result.error) {
+      throw new Error(`Could not run macOS screencapture: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+      const detail = result.stderr?.trim();
+      throw new Error(detail ? `Desktop snapshot failed: ${detail}` : "Desktop snapshot failed; allow Screen Recording access for the invoking terminal");
+    }
+    let size = 0;
+    try {
+      const snapshot = statSync5(stagingPath);
+      if (snapshot.isFile())
+        size = snapshot.size;
+    } catch {}
+    if (size === 0) {
+      throw new Error("Desktop snapshot produced no image; allow Screen Recording access for the invoking terminal");
+    }
+    chmodSync3(stagingPath, 384);
+    renameSync2(stagingPath, destination);
+    return destination;
+  } finally {
+    rmSync5(stagingDirectory, { recursive: true, force: true });
   }
 }
 
@@ -3330,13 +4755,13 @@ program.command("record").description("Record from microphone, transcribe, and o
       console.log(chalk.blue("Recording... Press") + chalk.yellow(" Enter ") + chalk.blue("to stop."));
     }
     audioPath = startRecording(config);
-    await new Promise((resolve3) => {
+    await new Promise((resolve4) => {
       process.stdin.setRawMode?.(true);
       process.stdin.resume();
       process.stdin.once("data", () => {
         process.stdin.setRawMode?.(false);
         process.stdin.pause();
-        resolve3();
+        resolve4();
       });
     });
     stopRecording();
@@ -3525,7 +4950,7 @@ ${text}`;
     process.exit(1);
   }
 });
-program.command("save <text>").description("Save raw text as a recording (no audio). Routes to the self_hosted API when configured, else local.").option("-t, --tags <tags>", "Comma-separated tags").option("--enhance", "Enhance the text via the configured model before saving").option("--model <model>", "Value for model_used", "direct-input").action(async (rawText, opts) => {
+program.command("save <text>").description("Save raw text as a recording (no audio). Routes to the /v1 API when configured, else the on-box SQLite store.").option("-t, --tags <tags>", "Comma-separated tags").option("--enhance", "Enhance the text via the configured model before saving").option("--model <model>", "Value for model_used", "direct-input").action(async (rawText, opts) => {
   const parentOpts = program.opts();
   let processedText;
   let mode = "raw";
@@ -3727,13 +5152,13 @@ program.command("projects").description("List registered projects").option("-n,
   printPaginationHints(page.length, projects.length, pagination);
 });
 program.command("init").description("Initialize .recordings/ in current directory").action(() => {
-  const { mkdirSync: mkdirSync4, writeFileSync: writeFileSync3, existsSync: existsSync5 } = __require("fs");
-  const { join: join7 } = __require("path");
-  const dir = join7(process.cwd(), ".recordings");
-  const audioDir = join7(dir, "audio");
-  const configFile = join7(dir, "config.json");
-  mkdirSync4(audioDir, { recursive: true });
-  if (!existsSync5(configFile)) {
+  const { mkdirSync: mkdirSync5, writeFileSync: writeFileSync4, existsSync: existsSync9 } = __require("fs");
+  const { join: join9 } = __require("path");
+  const dir = join9(process.cwd(), ".recordings");
+  const audioDir = join9(dir, "audio");
+  const configFile = join9(dir, "config.json");
+  mkdirSync5(audioDir, { recursive: true });
+  if (!existsSync9(configFile)) {
     const defaultConf = {
       transcription_model: "gpt-4o-transcribe",
       realtime_session_model: "gpt-realtime",
@@ -3746,7 +5171,7 @@ program.command("init").description("Initialize .recordings/ in current director
       post_processing_mode: "auto",
       auto_enhance: true
     };
-    writeFileSync3(configFile, JSON.stringify(defaultConf, null, 2));
+    writeFileSync4(configFile, JSON.stringify(defaultConf, null, 2));
   }
   console.log(chalk.green("Initialized .recordings/ directory"));
   console.log(chalk.dim("  config: .recordings/config.json"));
@@ -3754,7 +5179,7 @@ program.command("init").description("Initialize .recordings/ in current director
   console.log(chalk.dim("  db:     .recordings/recordings.db"));
 });
 var appCommand = program.command("app").description("Manage the macOS app installed from this package");
-appCommand.command("install").description("Install a release or explicitly approved local-only Recordings.app artifact").requiredOption("--artifact <path>", "Finalized Recordings.app ZIP artifact").requiredOption("--manifest <path>", "Artifact provenance manifest").option("--envelope <path>", "Signed release envelope (required for release artifacts)").option("--expected-team-id <team>", "Required Developer ID TeamIdentifier for release artifacts").requiredOption("--manifest-sha256 <sha256>", "Authenticated release-manifest SHA-256").requiredOption("--expected-source-sha <sha>", "Exact approved 40-character source commit").requiredOption("--expected-version <version>", "Exact approved release version").option("--expected-hostname <hostname>", "Exact deployment hostname to verify before any install mutation").option("--artifact-policy <policy>", "Artifact policy: release or local-only", "release").option("--approved-target <station>", "Exact approved target; fleet for release artifacts", "fleet").option("--approved-target-identity-kind <kind>", "Target identity kind: hardware_uuid_sha256 or tailscale_node_id_sha256").option("--approved-target-identity-sha256 <sha256>", "Authenticated SHA-256 of the approved target identity; none for release artifacts", "none").option("--acknowledge-local-signing-and-permissions", "Acknowledge local-only ad-hoc identity and possible permission reauthorization").option("--expected-old-identity-sha256 <sha256>", "Exact installed identity approved for migration").option("--expected-new-identity-sha256 <sha256>", "Exact candidate identity approved for migration").option("--allow-signing-identity-migration", "Allow one reviewed signer change that requires new macOS permission approval").option("--launch", "Launch and verify the canonical app after installation").option("--launch-timeout <seconds>", "Canonical process launch timeout").action((opts) => {
+appCommand.command("install").description("Install a release or explicitly approved local-only Recordings.app artifact").requiredOption("--artifact <path>", "Finalized Recordings.app ZIP artifact").requiredOption("--manifest <path>", "Artifact provenance manifest").option("--envelope <path>", "Signed release envelope (required for release artifacts)").option("--expected-team-id <team>", "Required Developer ID TeamIdentifier for release artifacts").requiredOption("--manifest-sha256 <sha256>", "Authenticated release-manifest SHA-256").requiredOption("--expected-source-sha <sha>", "Exact approved 40-character source commit").requiredOption("--expected-version <version>", "Exact approved release version").option("--expected-hostname <hostname>", "Exact deployment hostname to verify before any install mutation").option("--artifact-policy <policy>", "Artifact policy: release or local-only", "release").option("--approved-target <station>", "Exact approved target; fleet for release artifacts", "fleet").option("--approved-target-identity-kind <kind>", "Target identity kind: hardware_uuid_sha256 or tailscale_node_id_sha256").option("--approved-target-identity-sha256 <sha256>", "Authenticated SHA-256 of the approved target identity; none for release artifacts", "none").option("--acknowledge-local-signing-and-permissions", "Acknowledge local-only ad-hoc identity and possible permission reauthorization").option("--expected-old-identity-sha256 <sha256>", "Exact installed identity approved for migration").option("--expected-new-identity-sha256 <sha256>", "Exact candidate identity approved for migration").option("--allow-signing-identity-migration", "Allow one reviewed signer change that requires new macOS permission approval").option("--allow-adhoc-identity-migration", "Accept that replacing an ad-hoc signed local-only app voids its Microphone and Accessibility grants").option("--launch", "Launch and verify the canonical app after installation").option("--launch-timeout <seconds>", "Canonical process launch timeout").action((opts) => {
   if (process.platform !== "darwin") {
     console.error(chalk.red("Recordings.app installation is only supported on macOS"));
     process.exit(1);
@@ -3768,7 +5193,7 @@ appCommand.command("install").description("Install a release or explicitly appro
     try {
       assertReleaseOnlyOptions(opts);
       if (opts.expectedHostname) {
-        const hostnameResult = spawnSync4("/bin/hostname", ["-s"], {
+        const hostnameResult = spawnSync7("/bin/hostname", ["-s"], {
           encoding: "utf8",
           stdio: ["ignore", "pipe", "ignore"],
           env: {
@@ -3797,14 +5222,14 @@ appCommand.command("install").description("Install a release or explicitly appro
       process.exit(1);
     }
     const updateClientPath = "/Applications/Recordings.app/Contents/Helpers/recordings-update-client";
-    if (!existsSync4(updateClientPath)) {
+    if (!existsSync8(updateClientPath)) {
       preparedInputs.cleanup();
       console.error(chalk.red("Root-owned Recordings update broker client is not installed."));
       process.exit(1);
     }
     const result2 = (() => {
       try {
-        return spawnSync4(updateClientPath, [
+        return spawnSync7(updateClientPath, [
           "install",
           "--artifact",
           opts.artifact,
@@ -3851,7 +5276,7 @@ appCommand.command("install").description("Install a release or explicitly appro
     process.exit(1);
   }
   const installerPath = getMacOSInstallerPath();
-  if (!existsSync4(installerPath)) {
+  if (!existsSync8(installerPath)) {
     console.error(chalk.red(`App installer missing from package: ${installerPath}`));
     process.exit(1);
   }
@@ -3890,6 +5315,9 @@ appCommand.command("install").description("Install a release or explicitly appro
   if (opts.allowSigningIdentityMigration) {
     installerArgs.push("--allow-signing-identity-migration");
   }
+  if (opts.allowAdhocIdentityMigration) {
+    installerArgs.push("--allow-adhoc-identity-migration");
+  }
   if (opts.expectedOldIdentitySha256) {
     installerArgs.push("--expected-old-identity-sha256", opts.expectedOldIdentitySha256);
   }
@@ -3899,7 +5327,7 @@ appCommand.command("install").description("Install a release or explicitly appro
   if (opts.launch)
     installerArgs.push("--launch");
   const installerEnvironment = createInstallerEnvironment(process.env, bunExecutable);
-  const result = spawnSync4("/bin/bash", installerArgs, {
+  const result = spawnSync7("/bin/bash", installerArgs, {
     stdio: "inherit",
     env: installerEnvironment
   });
@@ -3911,8 +5339,12 @@ appCommand.command("install").description("Install a release or explicitly appro
 });
 appCommand.command("status").description("Show installed Recordings.app status").option("--verbose", "Show package paths, code hash, and log path").action((opts) => {
   const status = getMacOSAppStatus();
+  const trigger = probeTriggerDiagnostics({
+    accessibilityPermission: process.platform === "darwin" ? status.accessibility_permission : null,
+    appLogPath: status.log_path
+  });
   if (program.opts().json) {
-    console.log(JSON.stringify(status, null, 2));
+    console.log(JSON.stringify({ ...status, trigger }, null, 2));
     return;
   }
   console.log(chalk.bold("Recordings.app"));
@@ -3925,6 +5357,10 @@ appCommand.command("status").description("Show installed Recordings.app status")
     console.log(`Microphone: ${status.microphone_permission}`);
     console.log(`Accessibility: ${status.accessibility_permission}`);
   }
+  if (trigger) {
+    console.log(`Trigger: ${trigger.summary}${trigger.can_fire ? "" : " \u2014 NOTHING CAN FIRE"}`);
+    console.log(chalk.dim("  'recordings check' reports the trigger in full and exits non-zero when nothing can fire."));
+  }
   if (opts.verbose) {
     console.log(`Package: ${status.package_root}`);
     console.log(`Installed app: ${status.installed ? status.installed_app_path : "missing"}`);
@@ -3945,9 +5381,11 @@ appCommand.command("permissions").description("Show macOS permission state for R
   const status = getMacOSAppStatus();
   const permissions = {
     platform: status.platform,
-    bundle_id: "com.hasna.recordings",
+    bundle_id: RECORDINGS_BUNDLE_IDENTIFIER,
     installed_app_path: status.installed_app_path,
+    installed: status.installed,
     legacy_install_paths: status.legacy_install_paths,
+    permission_subject: describeTccAuthorizationSubject(status.installed_app_path),
     microphone: status.microphone_permission,
     accessibility: status.accessibility_permission,
     app_code_hash: status.app_code_hash,
@@ -3955,14 +5393,24 @@ appCommand.command("permissions").description("Show macOS permission state for R
     signing_identifier: status.signing_identifier,
     team_identifier: status.team_identifier,
     designated_requirement: status.designated_requirement,
+    microphone_grant_durability: status.microphone_grant_durability,
+    accessibility_grant_durability: status.accessibility_grant_durability,
+    microphone_stored_requirement: status.microphone_stored_requirement,
+    accessibility_stored_requirement: status.accessibility_stored_requirement,
+    ambiguous_installations: status.ambiguous_installations,
+    warnings: buildPermissionWarnings(status),
     log_path: status.log_path
   };
   if (program.opts().json) {
     console.log(JSON.stringify(permissions, null, 2));
     return;
   }
-  console.log(`Microphone: ${permissions.microphone}`);
-  console.log(`Accessibility: ${permissions.accessibility}`);
+  console.log(`Subject: ${permissions.permission_subject}`);
+  console.log(`Microphone: ${permissions.microphone} (${permissions.microphone_grant_durability})`);
+  console.log(`Accessibility: ${permissions.accessibility} (${permissions.accessibility_grant_durability})`);
+  for (const warning of permissions.warnings) {
+    console.log(chalk.yellow(`Warning: ${warning}`));
+  }
   console.log(`Log: ${permissions.log_path}`);
 });
 appCommand.command("reset-permissions").description("Reset macOS Microphone and Accessibility permissions for Recordings.app").action(() => {
@@ -3993,12 +5441,12 @@ appCommand.command("request-permissions").description("Open Recordings.app and t
 });
 appCommand.command("log").description("Show the Recordings.app diagnostic log").option("-n, --lines <lines>", "Number of lines to print", String(DEFAULT_LOG_LINES)).action((opts) => {
   const status = getMacOSAppStatus();
-  if (!existsSync4(status.log_path)) {
+  if (!existsSync8(status.log_path)) {
     console.log("");
     return;
   }
   const lines = Math.max(1, parseInt(opts.lines, 10) || DEFAULT_LOG_LINES);
-  const result = spawnSync4("tail", ["-n", String(lines), status.log_path], {
+  const result = spawnSync7("tail", ["-n", String(lines), status.log_path], {
     encoding: "utf8"
   });
   if (result.error) {
@@ -4009,6 +5457,14 @@ appCommand.command("log").description("Show the Recordings.app diagnostic log").
   if (result.stderr)
     process.stderr.write(result.stderr);
 });
+appCommand.command("snapshot [output]").description("Write the current main desktop to a PNG for local debugging").action((output) => {
+  const path = exportDesktopSnapshot(output);
+  if (program.opts().json) {
+    console.log(JSON.stringify({ path }, null, 2));
+  } else {
+    console.log(chalk.green(`Desktop snapshot written: ${path}`));
+  }
+});
 appCommand.command("open").description("Open the installed Recordings.app").action(() => {
   const status = getMacOSAppStatus();
   if (process.platform !== "darwin") {
@@ -4019,18 +5475,60 @@ appCommand.command("open").description("Open the installed Recordings.app").acti
     console.error(chalk.red("Recordings.app is not installed. Run: recordings app install"));
     process.exit(1);
   }
-  const result = spawnSync4("open", [status.installed_app_path], { stdio: "inherit" });
+  const result = spawnSync7("open", [status.installed_app_path], { stdio: "inherit" });
   if (result.error) {
     console.error(chalk.red(result.error.message));
     process.exit(1);
   }
   process.exit(result.status ?? 1);
 });
-program.command("check").description("Check system dependencies (sox, API keys)").action(async () => {
+program.command("check").description("Check system dependencies (sox, API keys) and macOS capture permissions. " + "Use --probe to exercise the microphone and credential for real.").option("--probe", "Prove capability instead of reporting presence: record a short sample and assert signal, and make one authenticated API request").option("--probe-seconds <seconds>", `Length of the capture probe in seconds (1-${MAX_PROBE_SECONDS})`, String(DEFAULT_PROBE_SECONDS)).option("--probe-store-write", "Allow the persistence probe to write a marker recording to a SHARED API store. Off by default: that store is production for every machine pointed at it").action(async (opts) => {
   const config = loadConfig();
   const parentOpts = program.opts();
   const deps = await checkRecordingDeps();
   const enhKey = config.enhancement_api_key || config.openai_api_key;
+  const transcriberModel = resolveTranscriberModel(config);
+  const transcriptionModel = config.transcription_model;
+  const macStatus = process.platform === "darwin" ? getMacOSAppStatus() : null;
+  const trigger = probeTriggerDiagnostics({
+    accessibilityPermission: macStatus?.accessibility_permission ?? null,
+    appLogPath: macStatus?.log_path ?? null
+  });
+  const activeStore = describeActiveStore(config);
+  const localStoreWasLegacy = localStoreIsBehindSchema(config.db_path);
+  let capture = null;
+  let credential = null;
+  let enhancementCredential = null;
+  let persistence = null;
+  if (opts.probe) {
+    const parsedSeconds = Number.parseInt(String(opts.probeSeconds), 10);
+    const seconds = Number.isFinite(parsedSeconds) && parsedSeconds > 0 ? Math.min(parsedSeconds, MAX_PROBE_SECONDS) : DEFAULT_PROBE_SECONDS;
+    capture = deps.available ? probeMicrophoneCapture(config, { seconds }) : {
+      ok: false,
+      tool: null,
+      seconds,
+      samples: 0,
+      peak: 0,
+      silent: null,
+      message: deps.message
+    };
+    credential = await verifyTranscriptionCredential(config, transcriptionModel, {
+      apiKey: config.openai_api_key,
+      role: "transcription"
+    });
+    enhancementCredential = enhKey ? await verifyTranscriptionCredential(config, transcriberModel, {
+      apiKey: enhKey,
+      role: "enhancement"
+    }) : null;
+    persistence = await probeRecordingPersistence({
+      allowRemoteWrite: Boolean(opts.probeStoreWrite),
+      allowLocalMigration: Boolean(opts.probeStoreWrite),
+      localStoreExistedBefore: activeStore.local_db_present,
+      localStoreIsLegacy: localStoreWasLegacy
+    });
+  }
+  const probeFailed = Boolean(opts.probe && (capture && !capture.ok || credential && !credential.ok || enhancementCredential && !enhancementCredential.ok || persistence && persistence.outcome === "failed"));
+  const triggerFailed = trigger !== null && !trigger.can_fire;
   if (parentOpts.json) {
     console.log(JSON.stringify({
       recording: {
@@ -4041,14 +5539,30 @@ program.command("check").description("Check system dependencies (sox, API keys)"
       openai_api_key_configured: Boolean(config.openai_api_key),
       enhancement_api_key_configured: Boolean(enhKey),
       enhancement_model: config.enhancement_model,
-      transcriber_model: resolveTranscriberModel(config),
+      transcriber_model: transcriberModel,
       realtime_session_model: config.realtime_session_model,
       realtime_transcription_model: config.realtime_transcription_model,
       post_processing_mode: config.post_processing_mode,
       transcription_prompt_configured: Boolean(config.transcription_prompt?.trim()),
       transcriber_prompt_configured: Boolean(config.transcriber_prompt?.trim()),
-      config_warnings: config.config_warnings ?? []
+      config_warnings: config.config_warnings ?? [],
+      microphone_permission: macStatus?.microphone_permission ?? "unsupported",
+      accessibility_permission: macStatus?.accessibility_permission ?? "unsupported",
+      active_store: activeStore,
+      capture_probe: capture,
+      capture_probe_subject: captureProbeSubject(),
+      microphone_grant_instruction: macStatus ? microphoneGrantInstruction({
+        installedAppPath: macStatus.installed_app_path,
+        otherAppPaths: macStatus.legacy_install_paths,
+        requestState: classifyPermissionState(macStatus.microphone_permission)
+      }) : null,
+      credential_probe: credential,
+      enhancement_credential_probe: enhancementCredential,
+      persistence_probe: persistence,
+      trigger
     }, null, 2));
+    if (probeFailed || triggerFailed)
+      process.exitCode = 1;
     return;
   }
   if (deps.available) {
@@ -4057,16 +5571,84 @@ program.command("check").description("Check system dependencies (sox, API keys)"
     console.log(chalk.red(`\u2717 ${deps.message}`));
   }
   if (config.openai_api_key) {
-    console.log(chalk.green(`\u2713 OpenAI API key configured`));
+    console.log(chalk.green(`\u2713 OpenAI API key present`) + chalk.dim(opts.probe ? "" : " (presence only \u2014 run 'recordings check --probe' to verify it is accepted)"));
   } else {
     console.log(chalk.red(`\u2717 OpenAI API key not found. Set OPENAI_API_KEY env var or add to ~/.secrets`));
   }
   if (enhKey) {
-    console.log(chalk.green(`\u2713 Enhancement API key configured (model: ${resolveTranscriberModel(config)})`));
+    console.log(chalk.green(`\u2713 Enhancement API key present (model: ${transcriberModel})`) + chalk.dim(opts.probe ? "" : " (presence only \u2014 'recordings check --probe' verifies it is accepted)"));
   } else {
     console.log(chalk.yellow(`\u26A0 Enhancement API key not configured \u2014 enhancement disabled`));
   }
+  console.log(chalk.green("\u2713") + ` Active store: ${activeStore.transport}` + (activeStore.base_url ? ` \u2192 ${activeStore.base_url}` : ` \u2192 ${activeStore.local_db_path}`) + chalk.dim(` (selected by ${activeStore.mode_source})`));
+  if (activeStore.divergent) {
+    console.log(chalk.yellow("\u26A0") + ` Two datasets present: ${activeStore.local_db_recordings} recordings sit in ` + `${activeStore.local_db_path}, which is NOT the live store.`);
+  }
+  if (activeStore.warning) {
+    console.log(chalk.dim(`  ${activeStore.warning}`));
+  }
+  if (macStatus) {
+    const micState = macStatus.microphone_permission;
+    const micOk = micState.startsWith("allowed");
+    const micVerified = micState === "allowed";
+    const micStaleGrant = micState === "stale_allowed_for_previous_app_build";
+    const micUnreadable = micState === TCC_UNREADABLE_STATE;
+    console.log((micOk ? chalk.green("\u2713") : micUnreadable ? chalk.yellow("?") : chalk.red("\u2717")) + ` Microphone permission: ${micState}`);
+    if (micOk) {
+      console.log(chalk.dim(micVerified ? `  Note: this is the TCC row for bundle id ${RECORDINGS_BUNDLE_IDENTIFIER}, and its ` + "stored code-signing requirement still validates against the installed bundle \u2014 " + "so the grant binds to the app that is installed, not to a previous build." : `  Note: this is the TCC row for bundle id ${RECORDINGS_BUNDLE_IDENTIFIER}. The row's ` + "code-signing requirement was NOT verified against the installed bundle, so a " + "bundle re-signed with a different identity can still be denied at runtime. " + "Confirm in the app's log."));
+    }
+    if (micStaleGrant) {
+      console.log(chalk.dim("  The TCC row says allowed, but its stored code-signing requirement does NOT match " + "the installed bundle \u2014 the grant belongs to a previous build and macOS will deny " + "at runtime. Toggling it in System Settings will not fix it; the row must be reset " + "(`recordings app reset-permissions`) and re-granted so it binds to the bundle " + "that is installed now."));
+    }
+    if (micUnreadable) {
+      console.log(chalk.dim("  Could not read the TCC database. This is NOT a denial and NOT proof the app never " + "asked. Reading it needs Full Disk Access, which is held by the session's " + "RESPONSIBLE process and inherited by its children \u2014 not granted per-tool: on " + "a fleet Mac `bun` is explicitly denied and still reads the database over SSH, " + "because it inherits sshd's grant. So re-run from a plain ssh shell rather than " + "granting Full Disk Access to tmux or bun, and not under sudo, which changes the " + "responsible process. A missing sqlite3, a locked database or a corrupt file " + "produce this same state, so the cause is not established either."));
+    }
+    if (!micOk && !micUnreadable) {
+      console.log(chalk.dim("  Recordings.app cannot capture audio without this. macOS does not error when it is " + "missing \u2014 it delivers silent audio. This grant CANNOT be set remotely; it needs a " + "human at the keyboard:"));
+      const instruction = microphoneGrantInstruction({
+        installedAppPath: macStatus.installed_app_path,
+        otherAppPaths: macStatus.legacy_install_paths,
+        requestState: classifyPermissionState(macStatus.microphone_permission)
+      });
+      for (const [index, step] of instruction.steps.entries()) {
+        console.log(chalk.dim(`  ${index + 1}. ${step}`));
+      }
+    }
+    console.log((macStatus.accessibility_permission.startsWith("allowed") ? chalk.green("\u2713") : chalk.yellow("\u26A0")) + ` Accessibility permission: ${macStatus.accessibility_permission}`);
+  }
+  if (trigger)
+    reportTriggerDiagnosis(trigger);
+  if (capture) {
+    console.log((capture.ok ? chalk.green("\u2713") : chalk.red("\u2717")) + ` Microphone capture probe: ${capture.message}`);
+    const subject = captureProbeSubject();
+    console.log(chalk.dim(`  subject: ${subject.note}`) + (subject.subject_known ? "" : chalk.yellow(" [subject unidentified \u2014 inconclusive]")));
+  }
+  if (credential) {
+    console.log((credential.ok ? chalk.green("\u2713") : chalk.red("\u2717")) + ` Transcription credential (${credential.model}): ${credential.message}`);
+  }
+  if (enhancementCredential) {
+    console.log((enhancementCredential.ok ? chalk.green("\u2713") : chalk.red("\u2717")) + ` Enhancement credential (${enhancementCredential.model}): ${enhancementCredential.message}`);
+  }
+  if (persistence) {
+    const persistenceMarker = renderPersistenceMarker(persistence.outcome, {
+      pass: chalk.green,
+      warn: chalk.yellow,
+      fail: chalk.red
+    });
+    console.log(persistenceMarker + ` Persistence round-trip: ${persistence.message}`);
+  }
+  if (probeFailed || triggerFailed)
+    process.exitCode = 1;
 });
+function reportTriggerDiagnosis(trigger) {
+  console.log((trigger.can_fire ? chalk.green("\u2713") : chalk.red("\u2717")) + ` Recording trigger: ${trigger.summary}`);
+  for (const failure of trigger.failures)
+    console.log(chalk.red(`  ${failure}`));
+  for (const warning of trigger.warnings)
+    console.log(chalk.yellow(`  \u26A0 ${warning}`));
+  for (const note of trigger.notes)
+    console.log(chalk.dim(`  ${note}`));
+}
 program.command("listen").description("Push-to-talk mode \u2014 press Space to start/stop recording, Esc to quit").option("-t, --tags <tags>", "Comma-separated tags for all recordings").option("--no-enhance", "Skip AI enhancement").option("--post-processing <mode>", "Post-processing mode: off, auto, or always").option("--prompt <prompt>", "Vocabulary/context prompt for transcription").option("--transcriber-prompt <prompt>", "Instructions for post-transcription cleanup").option("--system-prompt <prompt>", "Alias for --transcriber-prompt").option("--transcriber-model <model>", "Model for post-transcription cleanup").option("-l, --language <lang>", "Language code").option("--copy", "Copy output to clipboard").option("--paste", "Copy output to clipboard AND paste into frontmost app").action(async (opts) => {
   const config = loadConfig();
   ensureDataDir(config);
@@ -4181,19 +5763,212 @@ Bye.`));
     }
   });
 });
-program.command("shortcut").description("Set up a global keyboard shortcut for recording (macOS)").option("--raycast", "Generate Raycast script command").option("--karabiner", "Set up Fn key via Karabiner-Elements").option("--skhd", "Generate skhd hotkey config").option("--hammerspoon", "Generate Hammerspoon config").option("--script", "Just output the shell script path").action((opts) => {
-  const { writeFileSync: writeFileSync3, mkdirSync: mkdirSync4, chmodSync: chmodSync3 } = __require("fs");
+program.command("shortcut").description("Show or change the global recording trigger (macOS). Exits non-zero when a change was " + "written while Recordings.app was running, because the running instance keeps the " + "trigger it registered with \u2014 the write is stored but not armed until it is reopened.").option("--set <chord>", 'Set the app hotkey, e.g. "f13" or "ctrl+opt+r"').option("--reset", "Reset the app hotkey to the app's built-in default").option("--fn <state>", "Use fn/Globe as push-to-talk: on|off").option("--keys", "List the key names accepted by --set").option("--script", "Write the app-less toggle script and print its path").option("--raycast", "Generate a Raycast script command (requires Raycast)").option("--karabiner", "Generate a Karabiner-Elements rule (requires Karabiner-Elements)").option("--skhd", "Print an skhd hotkey config (requires skhd)").option("--hammerspoon", "Print a Hammerspoon config (requires Hammerspoon)").action((opts) => {
+  const { writeFileSync: writeFileSync4, mkdirSync: mkdirSync5, chmodSync: chmodSync4, existsSync: existsSync9 } = __require("fs");
   const { join: pathJoin2 } = __require("path");
   const { homedir: getHome } = __require("os");
+  const { spawnSync: runSync } = __require("child_process");
   const home = getHome();
   const scriptDir = pathJoin2(home, ".hasna", "recordings");
-  mkdirSync4(scriptDir, { recursive: true });
   const scriptPath = pathJoin2(scriptDir, "record-toggle.sh");
   const pidFile = pathJoin2(scriptDir, ".recording.pid");
   const recordingsBin = pathJoin2(home, ".bun", "bin", "recordings");
-  const script = `#!/bin/bash
+  const audioDir = pathJoin2(scriptDir, "audio");
+  if (opts.keys) {
+    console.log(chalk.bold(`Keys accepted by --set (combine with cmd/ctrl/opt/shift):
+`));
+    console.log(listBindableKeys().join(" "));
+    console.log(chalk.dim(`
+  fn/Globe is not in this list \u2014 it is a separate trigger, not a chord:
+`) + "    recordings shortcut --fn on");
+    return;
+  }
+  const appDefaultsReachable = TRIGGER_DEFAULTS_EXECUTABLE !== null;
+  function requireMacOS(what) {
+    if (appDefaultsReachable)
+      return true;
+    console.error(chalk.red(`${what} is only available on macOS`));
+    process.exitCode = 1;
+    return false;
+  }
+  let runningBundlesCache = null;
+  function runningBundles() {
+    runningBundlesCache ??= runningAppBundlePaths();
+    return runningBundlesCache;
+  }
+  function grantTargetPaths() {
+    const running = runningBundles();
+    if (running.length > 0)
+      return { paths: running, running: true };
+    const status = getMacOSAppStatus();
+    return {
+      paths: [...status.installed ? [status.installed_app_path] : [], ...status.legacy_install_paths],
+      running: false
+    };
+  }
+  function showState() {
+    const state = readTriggerState();
+    console.log(chalk.bold(`Recording trigger
+`));
+    if (state.shortcut) {
+      console.log(`  Hotkey          ${chalk.cyan(formatShortcut(state.shortcut))}`);
+    } else if (state.rawShortcut) {
+      console.log(`  Hotkey          ${chalk.yellow(`unreadable (${state.rawShortcut})`)}`);
+    } else {
+      console.log(`  Hotkey          ${chalk.dim("not set \u2014 the app writes its default")} ` + `${chalk.cyan(DEFAULT_TOGGLE_RECORDING_CHORD.toUpperCase())} ${chalk.dim("on next launch")}`);
+    }
+    console.log(`  fn/Globe key    ${state.useFnKey ? chalk.cyan("on") : chalk.dim("off")}`);
+    console.log();
+    function showGrantTargets() {
+      const running = runningBundles();
+      const status = getMacOSAppStatus();
+      const installed = [
+        ...status.installed ? [status.installed_app_path] : [],
+        ...status.legacy_install_paths
+      ];
+      console.log(chalk.bold(`Which bundle the grants apply to
+`));
+      if (running.length === 1) {
+        const [runningBundle] = running;
+        if (runningBundle === undefined)
+          throw new Error("Running app bundle path is missing");
+        console.log(`  Running         ${chalk.cyan(runningBundle)}`);
+      } else if (running.length > 1) {
+        console.log(`  Running         ${chalk.red(`${running.length} instances \u2014 grants are ambiguous`)}`);
+        for (const path of running)
+          console.log(`                  ${path}`);
+      } else {
+        console.log(`  Running         ${chalk.yellow("not running")}`);
+      }
+      if (installed.length > 0) {
+        console.log(`  Installed       ${installed.join(`
+                  `)}`);
+      }
+      if (installed.length > 1) {
+        console.log(chalk.yellow("  More than one installed copy \u2014 a grant given to one does not cover the others."));
+      }
+      console.log(chalk.dim(`
+  This command reports the app's stored trigger, not its permission state:
+` + `  a CLI inherits the terminal's grants, so it cannot measure the app's.
+` + "  Use 'recordings app permissions' for the bundle's actual grants."));
+      console.log();
+    }
+    showGrantTargets();
+    console.log(chalk.bold(`Permissions each trigger needs
+`));
+    for (const requirement of TRIGGER_GRANT_REQUIREMENTS) {
+      const grant = requirement.tccService ? chalk.yellow(requirement.tccService.replace(/^kTCCService/, "")) : chalk.green("none");
+      console.log(`  ${requirement.label.padEnd(15)} ${grant} \u2014 ${requirement.mechanism}`);
+      if (requirement.settingsPath) {
+        console.log(`  ${" ".repeat(15)} ${requirement.settingsPath} > enable Recordings`);
+      }
+    }
+    console.log();
+    console.log(chalk.bold(`Change it
+`));
+    console.log(`  recordings shortcut --set f13`);
+    console.log(`  recordings shortcut --set "ctrl+opt+r"`);
+    console.log(`  recordings shortcut --fn on`);
+    console.log(`  recordings shortcut --reset`);
+    console.log(chalk.dim(`
+  Or in the app: Settings > Recording Shortcut.`));
+    console.log(chalk.dim("  A changed hotkey is picked up the next time the app launches."));
+  }
+  function reportPickup() {
+    const pickup = describeTriggerPickup(runningBundles());
+    if (pickup.armed) {
+      console.log(chalk.dim("  Recordings.app is not running; it will register this on next launch."));
+      return;
+    }
+    console.log(chalk.yellow("  Recordings.app is running and still holds the previous trigger.") + `
+  Quit and reopen it to arm this one:`);
+    for (const path of pickup.runningBundlePaths)
+      console.log(chalk.dim(`    ${path}`));
+    console.log(chalk.dim("  Exiting non-zero: the value was written, but the trigger that fires right now is " + "still the old one."));
+    process.exitCode = 1;
+  }
+  if (opts.set !== undefined) {
+    if (!requireMacOS("Setting the app hotkey"))
+      return;
+    let shortcut;
+    try {
+      shortcut = parseShortcutChord(String(opts.set));
+    } catch (error) {
+      if (error instanceof ShortcutParseError) {
+        console.error(chalk.red(error.message));
+        process.exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+    writeShortcut(shortcut);
+    console.log(chalk.green(`Hotkey set to ${formatShortcut(shortcut)}`));
+    console.log(chalk.dim(`  ${RECORDINGS_BUNDLE_IDENTIFIER} ${TOGGLE_RECORDING_DEFAULTS_KEY}`));
+    reportPickup();
+    return;
+  }
+  if (opts.reset) {
+    if (!requireMacOS("Resetting the app hotkey"))
+      return;
+    const shortcut = parseShortcutChord(DEFAULT_TOGGLE_RECORDING_CHORD);
+    writeShortcut(shortcut);
+    console.log(chalk.green(`Hotkey reset to ${formatShortcut(shortcut)}`));
+    console.log(chalk.dim(`  ${RECORDINGS_BUNDLE_IDENTIFIER} ${TOGGLE_RECORDING_DEFAULTS_KEY}`));
+    reportPickup();
+    return;
+  }
+  if (opts.fn !== undefined) {
+    if (!requireMacOS("Changing the fn/Globe trigger"))
+      return;
+    const raw = String(opts.fn).toLowerCase();
+    const enable = raw === "on" || raw === "true" || raw === "yes" || raw === "1";
+    const disable = raw === "off" || raw === "false" || raw === "no" || raw === "0";
+    if (!enable && !disable) {
+      console.error(chalk.red(`--fn expects on or off, got "${opts.fn}"`));
+      process.exitCode = 1;
+      return;
+    }
+    writeUseFnKey(enable);
+    console.log(chalk.green(`fn/Globe trigger ${enable ? "enabled" : "disabled"}`));
+    console.log(chalk.dim(`  ${RECORDINGS_BUNDLE_IDENTIFIER} ${USE_FN_KEY_DEFAULTS_KEY}`));
+    if (enable) {
+      const fnGrant = TRIGGER_GRANT_REQUIREMENTS.find((entry) => entry.id === "fn");
+      if (fnGrant?.settingsPath) {
+        console.log(`
+  fn is a ${fnGrant.mechanism}, so it needs ` + `${fnGrant.tccService?.replace(/^kTCCService/, "") ?? "no"} permission:
+` + `    ${fnGrant.settingsPath} > enable Recordings`);
+        const target = grantTargetPaths();
+        if (target.paths.length === 0) {
+          console.log(chalk.dim("    (no installed Recordings.app found to grant it to)"));
+        }
+        for (const path of target.paths) {
+          console.log(chalk.dim(`    grant it to: ${path}${target.running ? "" : " (not running \u2014 installed copy)"}`));
+        }
+      }
+      console.log(chalk.dim(`
+  While enabled the app swallows fn, so fn stops reaching other apps
+` + "  (emoji picker, input-source switching). Turn it off with --fn off."));
+    }
+    console.log();
+    reportPickup();
+    return;
+  }
+  const wantsExternalLauncher = Boolean(opts.script) || Boolean(opts.raycast) || Boolean(opts.karabiner) || Boolean(opts.skhd) || Boolean(opts.hammerspoon);
+  if (!wantsExternalLauncher) {
+    if (!requireMacOS("Reading the app hotkey"))
+      return;
+    showState();
+    return;
+  }
+  function writeToggleScript() {
+    mkdirSync5(scriptDir, { recursive: true });
+    const script = `#!/bin/bash
 # Toggle recording on/off. Run this from a global hotkey.
 # Each press toggles: start recording -> stop + transcribe + copy to clipboard
+#
+# This is the app-less path. If Recordings.app is running, prefer its own hotkey
+# ("recordings shortcut --set ..."): the app streams transcription and pastes into
+# the focused field, which this script cannot do.
 set -e
 
 PID_FILE="${pidFile}"
@@ -4206,7 +5981,7 @@ if [ -f "$PID_FILE" ]; then
   rm -f "$PID_FILE"
 
   # Find the most recent audio file
-  AUDIO_DIR="${pathJoin2(scriptDir, "audio")}"
+  AUDIO_DIR="${audioDir}"
   LATEST=$(ls -t "$AUDIO_DIR"/*.wav 2>/dev/null | head -1)
 
   if [ -n "$LATEST" ]; then
@@ -4218,8 +5993,6 @@ if [ -f "$PID_FILE" ]; then
     fi
     if [ -n "$TEXT" ]; then
       echo -n "$TEXT" | pbcopy
-      # Optional: paste into frontmost app
-      # osascript -e 'delay 0.1' -e 'tell application "System Events" to keystroke "v" using command down'
     fi
   fi
 
@@ -4227,19 +6000,39 @@ if [ -f "$PID_FILE" ]; then
   osascript -e 'display notification "Recording saved and copied to clipboard" with title "Recordings"' 2>/dev/null || true
 else
   # Start recording in background
-  mkdir -p "${pathJoin2(scriptDir, "audio")}"
-  rec -r 16000 -c 1 -b 16 "${pathJoin2(scriptDir, "audio")}/recording-$(date +%Y%m%dT%H%M%S).wav" trim 0 300 &
+  mkdir -p "${audioDir}"
+  rec -r 16000 -c 1 -b 16 "${audioDir}/recording-$(date +%Y%m%dT%H%M%S).wav" trim 0 300 &
   echo $! > "$PID_FILE"
 
   # Notification
   osascript -e 'display notification "Recording started..." with title "Recordings"' 2>/dev/null || true
 fi
 `;
-  writeFileSync3(scriptPath, script, "utf-8");
-  chmodSync3(scriptPath, 493);
+    writeFileSync4(scriptPath, script, "utf-8");
+    chmodSync4(scriptPath, 493);
+  }
+  function launcherMissing(label, present, install) {
+    if (present)
+      return false;
+    console.error(chalk.red(`${label} is not installed \u2014 nothing would fire this hotkey.`));
+    console.error(chalk.dim(`  Install it with: ${install}`));
+    console.error(chalk.dim(`  Or use the app's own hotkey, which needs no extra software:
+` + "    recordings shortcut --set f13"));
+    process.exitCode = 1;
+    return true;
+  }
   if (opts.karabiner) {
+    if (!requireMacOS("Karabiner-Elements setup"))
+      return;
+    console.log(chalk.yellow("The app can use fn/Globe natively \u2014 no driver, no reboot:") + `
+  recordings shortcut --fn on
+`);
+    if (launcherMissing("Karabiner-Elements", existsSync9("/Applications/Karabiner-Elements.app"), "brew install --cask karabiner-elements")) {
+      return;
+    }
     const karabinerDir = pathJoin2(home, ".config", "karabiner", "assets", "complex_modifications");
-    mkdirSync4(karabinerDir, { recursive: true });
+    mkdirSync5(karabinerDir, { recursive: true });
+    writeToggleScript();
     const rule = {
       title: "Recordings \u2014 Fn key to toggle recording",
       rules: [
@@ -4263,23 +6056,27 @@ fi
       ]
     };
     const karabinerPath = pathJoin2(karabinerDir, "recordings-fn.json");
-    writeFileSync3(karabinerPath, JSON.stringify(rule, null, 2) + `
+    writeFileSync4(karabinerPath, JSON.stringify(rule, null, 2) + `
 `, "utf-8");
-    console.log(chalk.green("Karabiner-Elements rule created!"));
+    console.log(chalk.green("Karabiner-Elements rule written:"));
     console.log(chalk.dim(`  ${karabinerPath}
 `));
-    console.log("To activate:");
+    console.log("It does nothing until you enable it:");
     console.log("  1. Open Karabiner-Elements");
     console.log("  2. Go to Complex Modifications tab");
     console.log("  3. Click Add Predefined Rule");
     console.log('  4. Enable "Fn key toggles speech recording"');
-    console.log(chalk.dim(`
-  Press Fn to start recording, Fn again to stop + copy to clipboard`));
     return;
   }
   if (opts.raycast) {
+    if (!requireMacOS("Raycast setup"))
+      return;
+    if (launcherMissing("Raycast", existsSync9("/Applications/Raycast.app"), "brew install --cask raycast")) {
+      return;
+    }
+    writeToggleScript();
     const raycastDir = pathJoin2(home, ".config", "raycast", "script-commands");
-    mkdirSync4(raycastDir, { recursive: true });
+    mkdirSync5(raycastDir, { recursive: true });
     const raycastScript = `#!/bin/bash
 
 # Required parameters:
@@ -4294,15 +6091,20 @@ fi
 ${scriptPath}
 `;
     const raycastPath = pathJoin2(raycastDir, "toggle-recording.sh");
-    writeFileSync3(raycastPath, raycastScript, "utf-8");
-    chmodSync3(raycastPath, 493);
-    console.log(chalk.green("Raycast script command created!"));
+    writeFileSync4(raycastPath, raycastScript, "utf-8");
+    chmodSync4(raycastPath, 493);
+    console.log(chalk.green("Raycast script command written:"));
     console.log(chalk.dim(`  ${raycastPath}`));
-    console.log(chalk.dim("  Open Raycast > Script Commands > reload to see it"));
-    console.log(chalk.dim("  Then assign a hotkey in Raycast preferences"));
+    console.log(chalk.dim("  Raycast > Script Commands > reload, then assign a hotkey."));
     return;
   }
   if (opts.skhd) {
+    if (!requireMacOS("skhd setup"))
+      return;
+    const skhdPresent = runSync("/usr/bin/env", ["which", "skhd"], { encoding: "utf8" }).status === 0;
+    if (launcherMissing("skhd", skhdPresent, "brew install koekeishiya/formulae/skhd"))
+      return;
+    writeToggleScript();
     console.log(chalk.bold(`Add to ~/.skhdrc:
 `));
     console.log(chalk.cyan(`  fn - space : ${scriptPath}`));
@@ -4311,6 +6113,12 @@ ${scriptPath}
     return;
   }
   if (opts.hammerspoon) {
+    if (!requireMacOS("Hammerspoon setup"))
+      return;
+    if (launcherMissing("Hammerspoon", existsSync9("/Applications/Hammerspoon.app"), "brew install --cask hammerspoon")) {
+      return;
+    }
+    writeToggleScript();
     console.log(chalk.bold(`Add to ~/.hammerspoon/init.lua:
 `));
     console.log(chalk.cyan(`  hs.hotkey.bind({"ctrl"}, "space", function()
@@ -4320,35 +6128,8 @@ ${scriptPath}
   Then reload Hammerspoon config`));
     return;
   }
-  console.log(chalk.bold("Global shortcut script created:"));
-  console.log(chalk.cyan(`  ${scriptPath}
-`));
-  console.log(`Bind it to a hotkey using any of these:
-`);
-  console.log(chalk.bold("  Karabiner-Elements") + chalk.dim(" (for Fn key specifically)"));
-  console.log(`    brew install --cask karabiner-elements`);
-  console.log(`    recordings shortcut --karabiner
-`);
-  console.log(chalk.bold("  Raycast"));
-  console.log(`    recordings shortcut --raycast
-`);
-  console.log(chalk.bold("  skhd"));
-  console.log(`    recordings shortcut --skhd
-`);
-  console.log(chalk.bold("  Hammerspoon"));
-  console.log(`    recordings shortcut --hammerspoon
-`);
-  console.log(chalk.bold("  macOS Automator"));
-  console.log(`    1. Open Automator > Quick Action`);
-  console.log(`    2. Add "Run Shell Script" action`);
-  console.log(`    3. Paste: ${scriptPath}`);
-  console.log(`    4. Save as "Toggle Recording"`);
-  console.log(`    5. System Settings > Keyboard > Shortcuts > Services`);
-  console.log(`    6. Assign a shortcut to "Toggle Recording"
-`);
-  console.log(chalk.bold("  Alfred"));
-  console.log(`    Create a workflow with a Hotkey trigger \u2192 Run Script: ${scriptPath}
-`);
+  writeToggleScript();
+  console.log(scriptPath);
 });
 function buildTranscriptionMetadata(config, processed, sources = {}) {
   const transcriptionPromptConfigured = Boolean(config.transcription_prompt?.trim());
@@ -4382,7 +6163,7 @@ async function readSaveTextInput(text, opts) {
   }
   let rawText;
   if (opts.textFile !== undefined) {
-    rawText = readFileSync3(opts.textFile, "utf8");
+    rawText = readFileSync4(opts.textFile, "utf8");
   } else if (opts.stdin) {
     rawText = await Bun.stdin.text();
   } else {
@@ -4596,7 +6377,7 @@ function relativeHint(value) {
   return `${Math.floor(hours / 24)}d ago`;
 }
 program.command("mcp").description("Install recordings MCP server into Claude Code, Codex, or Gemini").option("--claude", "Install into Claude Code (via `claude mcp add`)").option("--codex", "Install into Codex (~/.codex/config.toml)").option("--gemini", "Install into Gemini (~/.gemini/settings.json)").option("--all", "Install into all supported agents").option("--uninstall", "Remove recordings MCP from config").action(async (opts) => {
-  const { readFileSync: readFileSync4, writeFileSync: writeFileSync3, existsSync: fileExists } = __require("fs");
+  const { readFileSync: readFileSync5, writeFileSync: writeFileSync4, existsSync: fileExists } = __require("fs");
   const { join: pathJoin2 } = __require("path");
   const { homedir: getHome } = __require("os");
   const { execSync } = __require("child_process");
@@ -4629,14 +6410,14 @@ program.command("mcp").description("Install recordings MCP server into Claude Co
       if (target === "codex") {
         const configPath = pathJoin2(home, ".codex", "config.toml");
         if (fileExists(configPath)) {
-          const content = readFileSync4(configPath, "utf-8");
+          const content = readFileSync5(configPath, "utf-8");
           if (opts.uninstall) {
             const { content: next, removed } = removeCodexServerBlock(content, "recordings");
-            writeFileSync3(configPath, next, "utf-8");
+            writeFileSync4(configPath, next, "utf-8");
             console.log(removed ? chalk.green(`Removed from Codex: ${configPath}`) : chalk.yellow(`Codex: no recordings MCP block found in ${configPath}`));
           } else {
             const next = upsertCodexStdioBlock(content, "recordings", mcpCmd);
-            writeFileSync3(configPath, next, "utf-8");
+            writeFileSync4(configPath, next, "utf-8");
             console.log(chalk.green(`Installed into Codex: ${configPath}`));
           }
         } else {
@@ -4647,7 +6428,7 @@ program.command("mcp").description("Install recordings MCP server into Claude Co
         const configPath = pathJoin2(home, ".gemini", "settings.json");
         let config = {};
         if (fileExists(configPath)) {
-          config = JSON.parse(readFileSync4(configPath, "utf-8"));
+          config = JSON.parse(readFileSync5(configPath, "utf-8"));
         }
         const servers = config["mcpServers"] || {};
         if (opts.uninstall) {
@@ -4656,7 +6437,7 @@ program.command("mcp").description("Install recordings MCP server into Claude Co
           servers["recordings"] = { command: mcpCmd, args: ["--stdio"] };
         }
         config["mcpServers"] = servers;
-        writeFileSync3(configPath, JSON.stringify(config, null, 2) + `
+        writeFileSync4(configPath, JSON.stringify(config, null, 2) + `
 `, "utf-8");
         console.log(chalk.green(`${action} Gemini: ${configPath}`));
       }
@@ -4686,58 +6467,105 @@ program.command("feedback <message>").description("Send feedback").option("--ema
 function getMacOSAppStatus() {
   const packageRoot = findPackageRoot();
   const home = process.env.HOME || process.env.USERPROFILE || "";
-  const installedAppPath = pathJoin(home, "Applications", "Recordings.app");
+  const canonicalAppPath = pathJoin(home, "Applications", "Recordings.app");
+  const legacyInstallPaths = findLegacyMacOSAppPaths(home, canonicalAppPath);
+  const installedAppPath = resolveInstalledAppPath(home, canonicalAppPath, legacyInstallPaths);
+  const installedAppPathForGrants = existsSync8(installedAppPath) ? installedAppPath : null;
   const executablePath = pathJoin(installedAppPath, "Contents", "MacOS", "Recordings");
   const logPath = pathJoin(home, ".hasna", "recordings", "Recordings.log");
   const installerPath = getMacOSInstallerPath(packageRoot);
   const nativeSourcesPath = pathJoin(packageRoot, "src", "native", "Recordings");
   const signingInfo = getCodeSigningInfo(installedAppPath);
-  const legacyInstallPaths = findLegacyMacOSAppPaths(home, installedAppPath);
-  const permissionStatus = legacyInstallPaths.length > 0 ? "ambiguous_multiple_installations" : null;
+  const ambiguousInstallations = [canonicalAppPath, ...legacyInstallPaths].filter((path) => existsSync8(path)).length > 1;
+  const microphoneGrant = getTccGrant("kTCCServiceMicrophone", home, installedAppPathForGrants);
+  const accessibilityGrant = getTccGrant("kTCCServiceAccessibility", home, installedAppPathForGrants);
   return {
     platform: process.platform,
     package_root: packageRoot,
     installer_path: installerPath,
-    installer_available: existsSync4(installerPath),
+    installer_available: existsSync8(installerPath),
     native_sources_path: nativeSourcesPath,
-    native_sources_available: existsSync4(pathJoin(nativeSourcesPath, "Package.swift")),
+    native_sources_available: existsSync8(pathJoin(nativeSourcesPath, "Package.swift")),
     installed_app_path: installedAppPath,
     legacy_install_paths: legacyInstallPaths,
-    installed: existsSync4(installedAppPath),
+    installed: existsSync8(installedAppPath),
     executable_path: executablePath,
-    executable: existsSync4(executablePath),
+    executable: existsSync8(executablePath),
     app_code_hash: signingInfo.cdHash,
     ad_hoc_signed: signingInfo.adHoc,
     signing_identifier: signingInfo.identifier,
     team_identifier: signingInfo.teamIdentifier,
     designated_requirement: signingInfo.designatedRequirement,
     signature_authorities: signingInfo.authorities,
-    microphone_permission: permissionStatus ?? getTccPermission("kTCCServiceMicrophone", home),
-    accessibility_permission: permissionStatus ?? getTccPermission("kTCCServiceAccessibility", home),
+    microphone_permission: microphoneGrant.state,
+    accessibility_permission: accessibilityGrant.state,
+    ambiguous_installations: ambiguousInstallations,
+    microphone_grant_durability: microphoneGrant.durability,
+    accessibility_grant_durability: accessibilityGrant.durability,
+    microphone_stored_requirement: microphoneGrant.storedRequirement,
+    accessibility_stored_requirement: accessibilityGrant.storedRequirement,
     log_path: logPath
   };
 }
+function buildPermissionWarnings(status) {
+  const warnings = [];
+  if (status.platform !== "darwin")
+    return warnings;
+  if (!status.installed) {
+    warnings.push(`no app bundle exists at ${status.installed_app_path}, so the states above describe no ` + "installed code \u2014 install the app before trusting them");
+  }
+  if (status.ambiguous_installations) {
+    warnings.push("more than one Recordings.app is installed, so the states above may describe a bundle " + `other than the one macOS granted: reporting on ${status.installed_app_path}, also ` + `present are ${status.legacy_install_paths.join(", ")}`);
+  }
+  for (const [service, durability] of [
+    ["Microphone", status.microphone_grant_durability],
+    ["Accessibility", status.accessibility_grant_durability]
+  ]) {
+    if (durability === "dies_on_rebuild_cdhash_pinned") {
+      warnings.push(`the ${service} grant is pinned to one exact build, so the next rebuild will silently ` + "revoke it \u2014 re-sign with a stable certificate identity to keep it");
+    }
+  }
+  for (const [service, state] of [
+    ["Microphone", status.microphone_permission],
+    ["Accessibility", status.accessibility_permission]
+  ]) {
+    if (state === "undetermined_tcc_database_unreadable") {
+      warnings.push(`the TCC database holding the ${service} decision could not be read, so that state is ` + "unknown rather than ungranted \u2014 the usual cause is that this process lacks Full " + "Disk Access");
+    }
+  }
+  return warnings;
+}
+function resolveInstalledAppPath(home, canonicalPath, legacyPaths) {
+  const preference = [
+    canonicalPath,
+    pathJoin("/", "Applications", "Recordings.app"),
+    pathJoin(home, ".hasna", "recordings", "Recordings.app")
+  ];
+  for (const candidate of preference) {
+    if (existsSync8(candidate))
+      return candidate;
+  }
+  return legacyPaths.find((candidate) => existsSync8(candidate)) ?? canonicalPath;
+}
 function findLegacyMacOSAppPaths(home, canonicalPath) {
   const candidates = [
     pathJoin(home, ".hasna", "recordings", "Recordings.app"),
     pathJoin("/", "Applications", "Recordings.app")
   ];
   const userApplications = pathJoin(home, "Applications");
-  if (existsSync4(userApplications)) {
+  if (existsSync8(userApplications)) {
     for (const entry of readdirSync2(userApplications, { withFileTypes: true })) {
       if (entry.isDirectory() && entry.name.startsWith("Recordings.app.")) {
         candidates.push(pathJoin(userApplications, entry.name));
       }
     }
   }
-  return [...new Set(candidates)].filter((candidate) => candidate !== canonicalPath && existsSync4(candidate)).sort();
+  return [...new Set(candidates)].filter((candidate) => candidate !== canonicalPath && existsSync8(candidate)).sort();
 }
 function resetMacOSPermissions() {
   const services = ["Microphone", "Accessibility"];
   for (const service of services) {
-    const result = spawnSync4("tccutil", ["reset", service, "com.hasna.recordings"], {
-      stdio: "inherit"
-    });
+    const result = spawnSync7("/usr/bin/tccutil", ["reset", service, RECORDINGS_BUNDLE_IDENTIFIER], { stdio: "inherit" });
     if (result.error) {
       console.error(chalk.red(result.error.message));
       process.exit(1);
@@ -4745,7 +6573,7 @@ function resetMacOSPermissions() {
   }
 }
 function getCodeSigningInfo(appPath) {
-  if (process.platform !== "darwin" || !existsSync4(appPath)) {
+  if (process.platform !== "darwin" || !existsSync8(appPath)) {
     return {
       cdHash: null,
       adHoc: false,
@@ -4755,7 +6583,7 @@ function getCodeSigningInfo(appPath) {
       authorities: []
     };
   }
-  const result = spawnSync4("/usr/bin/codesign", ["-d", "-r-", "--verbose=4", appPath], {
+  const result = spawnSync7("/usr/bin/codesign", ["-d", "-r-", "--verbose=4", appPath], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -4766,58 +6594,31 @@ ${result.stderr}`;
   const identifier = output.match(/^Identifier=(.+)$/m)?.[1]?.trim() ?? null;
   const teamIdentifier = output.match(/^TeamIdentifier=(.+)$/m)?.[1]?.trim() ?? null;
   const designatedRequirement = output.match(/^designated => (.+)$/m)?.[1]?.trim() ?? null;
-  const authorities = [...output.matchAll(/^Authority=(.+)$/gm)].map((match) => match[1].trim());
+  const authorities = [...output.matchAll(/^Authority=(.+)$/gm)].flatMap((match) => {
+    const authority = match[1];
+    return authority === undefined ? [] : [authority.trim()];
+  });
   return { cdHash, adHoc, identifier, teamIdentifier, designatedRequirement, authorities };
 }
-function getTccPermission(service, home) {
-  if (process.platform !== "darwin")
-    return "unsupported";
-  const dbPaths = [
-    pathJoin(home, "Library", "Application Support", "com.apple.TCC", "TCC.db"),
-    pathJoin("/", "Library", "Application Support", "com.apple.TCC", "TCC.db")
-  ];
-  const sql = "select auth_value from access where service = '" + service.replace(/'/g, "''") + "' and client = 'com.hasna.recordings' order by last_modified desc limit 1;";
-  for (const dbPath of dbPaths) {
-    if (!existsSync4(dbPath))
-      continue;
-    const result = spawnSync4("/usr/bin/sqlite3", [dbPath, sql], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    });
-    const value = result.stdout.trim();
-    if (!value)
-      continue;
-    return `${tccAuthValueLabel(value)}_identity_unverified`;
-  }
-  return "not_determined";
-}
-function tccAuthValueLabel(value) {
-  switch (value) {
-    case "0":
-      return "denied";
-    case "1":
-      return "unknown";
-    case "2":
-      return "allowed";
-    case "3":
-      return "limited";
-    default:
-      return `unknown(${value})`;
+function getTccGrant(service, home, appPath) {
+  if (process.platform !== "darwin") {
+    return { state: "unsupported", storedRequirement: null, durability: "unknown" };
   }
+  return resolveTccGrant({ service, home, appPath });
 }
 function findPackageRoot() {
-  let current = dirname4(fileURLToPath(import.meta.url));
+  let current = dirname5(fileURLToPath(import.meta.url));
   while (true) {
     const packagePath = pathJoin(current, "package.json");
-    if (existsSync4(packagePath)) {
+    if (existsSync8(packagePath)) {
       try {
-        const pkg = JSON.parse(readFileSync3(packagePath, "utf8"));
+        const pkg = JSON.parse(readFileSync4(packagePath, "utf8"));
         if (pkg.name === "@hasna/recordings") {
           return current;
         }
       } catch {}
     }
-    const parent = dirname4(current);
+    const parent = dirname5(current);
     if (parent === current) {
       return process.cwd();
     }