@hasna/recordings 0.2.14 → 0.3.1

package/dist/index.js

@@ -627,7 +627,8 @@ function findProjectRecordingsPath(entry) {
 function findRepositoryRoot(start) {
   let dir = start;
   while (true) {
-    if (existsSync(join2(dir, ".git")))
+    const gitPath = join2(dir, ".git");
+    if (isRepositoryMarker(gitPath))
       return dir;
     const parent = dirname2(dir);
     if (parent === dir)
@@ -635,6 +636,15 @@ function findRepositoryRoot(start) {
     dir = parent;
   }
 }
+function isRepositoryMarker(gitPath) {
+  try {
+    if (statSync(gitPath).isFile())
+      return true;
+    return existsSync(join2(gitPath, "HEAD"));
+  } catch {
+    return false;
+  }
+}
 function canonicalExistingPath(path) {
   try {
     return realpathSync2(path);
@@ -663,14 +673,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 "";
@@ -795,6 +808,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;
@@ -818,7 +832,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)) {
@@ -1168,7 +1186,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) {
@@ -1176,29 +1194,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`]
   };
@@ -1211,6 +1254,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:") {
@@ -1226,45 +1283,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 {
@@ -1376,6 +1430,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 {
@@ -1447,17 +1503,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
@@ -1481,12 +1537,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));
@@ -1539,7 +1598,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) ? randomUUID2() : idempotencyKey;
@@ -1682,7 +1741,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;
@@ -1709,6 +1768,9 @@ function resetClient() {
   _client = null;
   _clientApiKey = null;
 }
+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]`);
+}
 async function transcribeAudio(audioPath, config, options = {}) {
   const client = getClient(config);
   const startTime = Date.now();
@@ -1998,10 +2060,14 @@ function startRecording(config) {
   const filename = `recording-${timestamp}.${config.audio_format}`;
   const filepath = join3(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 = spawn(args[0], args.slice(1), {
+    recordProcess = spawn(command, commandArgs, {
       stdio: ["pipe", "pipe", "pipe"]
     });
   } catch (error) {
@@ -2100,21 +2166,527 @@ async function recordDuration(seconds, config) {
     releaseLease();
   }
 }
+// src/lib/capture-probe.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync3, readFileSync as readFileSync2, rmSync as rmSync2 } from "fs";
+import { join as join4 } 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 = join4(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 (!existsSync3(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) => existsSync3(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 ${join4(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
+  };
+}
+async function captureProbePrecondition() {
+  const deps = await checkRecordingDeps();
+  return deps.available ? { ready: true, message: deps.message } : { ready: false, message: deps.message };
+}
+// src/lib/persistence-probe.ts
+import { Database as Database2 } from "bun:sqlite";
+import { existsSync as existsSync4 } 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 describeActiveStore(config, env = process.env) {
+  const localDbPath = config.db_path;
+  const localDbPresent = existsSync4(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 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}`
+  };
+}
 export {
   transcribeBuffer,
   transcribeAudio,
   stopRecording,
   startRecording,
+  safeBaseUrl,
   resolveTransport,
   resolveStorageClient,
   resetEnhancementClient,
   resetClient,
   recordDuration,
+  readWavPeak,
   processText,
+  probeRecordingPersistence,
+  probeMicrophoneCapture,
   normalizePostProcessingMode,
   normalizePostProcessingConfig,
   normalizeModelSlots,
   needsEnhancement,
+  microphoneGrantInstruction,
   loadConfig,
   isRecording,
   getStore,
@@ -2122,20 +2694,33 @@ export {
   getCurrentFile,
   ensureDataDir,
   enhanceText,
+  describeActiveStore,
   createStorageClient,
   createHttpTransport,
+  classifyPermissionState,
   checkRecordingDeps,
+  captureProbeSubject,
+  captureProbePrecondition,
   __resetStore,
   TranscriptionError,
+  TCC_UNREADABLE_STATE,
+  SILENCE_PEAK_THRESHOLD,
   RecordingsV1Client,
   ApiError as RecordingsV1ApiError,
   RecordingNotFoundError,
   RecordingError,
+  RECORDINGS_BUNDLE_IDENTIFIER,
+  PERSISTENCE_PROBE_TAG,
+  PERSISTENCE_PROBE_MARKER_PREFIX,
+  MAX_PROBE_SECONDS,
   HasnaHttpError,
   EnhancementError,
   DEFAULT_TRANSCRIPTION_MODEL,
+  DEFAULT_RECORD_EXECUTABLE,
   DEFAULT_REALTIME_TRANSCRIPTION_MODEL,
   DEFAULT_REALTIME_SESSION_MODEL,
+  DEFAULT_PROBE_SECONDS,
   DEFAULT_CONFIG,
+  AUTO_FLIP_MODE_SOURCE,
   APP
 };