@hasna/recordings 0.2.11 → 0.2.13

package/dist/cli/index.js

@@ -900,25 +900,206 @@ function collectValues(value, previous) {
 
 // src/cli/index.ts
 import chalk from "chalk";
-import { spawnSync } from "child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname3, join as pathJoin } from "path";
+import { spawnSync as spawnSync4 } from "child_process";
+import {
+  existsSync as existsSync4,
+  readFileSync as readFileSync3,
+  readdirSync as readdirSync2
+} from "fs";
+import { dirname as dirname4, join as pathJoin } from "path";
 import { fileURLToPath } from "url";
 
 // src/lib/config.ts
-import { copyFileSync, existsSync as existsSync2, readFileSync, mkdirSync, readdirSync, statSync } from "fs";
-import { dirname, join as join2, resolve } from "path";
+import { copyFileSync, existsSync as existsSync2, readFileSync, mkdirSync as mkdirSync2, readdirSync, realpathSync as realpathSync2, statSync } from "fs";
+import { dirname as dirname2, join as join3, resolve as resolve2, sep as sep2 } from "path";
+import { homedir as homedir3 } from "os";
+
+// src/lib/install-maintenance.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
 import { homedir as homedir2 } from "os";
+import { basename, dirname, isAbsolute, join as join2, relative, resolve, sep } from "path";
+import { spawnSync } from "child_process";
+var INSTALL_MAINTENANCE_MARKER_NAME = ".recordings-install-maintenance";
+var STORE_READER_LEASES_NAME = ".recordings-store-readers";
+function stateParent(env = process.env) {
+  const home = env["HOME"] || env["USERPROFILE"] || homedir2();
+  return join2(home, ".hasna");
+}
+function installMaintenanceMarkerPath(env = process.env) {
+  return join2(stateParent(env), INSTALL_MAINTENANCE_MARKER_NAME);
+}
+function storeReaderLeasesPath(env = process.env) {
+  return join2(stateParent(env), STORE_READER_LEASES_NAME);
+}
+function pathExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+function assertPrivateDirectory(path) {
+  const details = lstatSync(path);
+  if (!details.isDirectory() || details.isSymbolicLink()) {
+    throw new Error(`Local Recordings coordination path is not a secure directory: ${path}`);
+  }
+  if (typeof process.getuid === "function" && details.uid !== process.getuid()) {
+    throw new Error(`Local Recordings coordination path has an unexpected owner: ${path}`);
+  }
+  if ((details.mode & 18) !== 0) {
+    throw new Error(`Local Recordings coordination path is group/world writable: ${path}`);
+  }
+}
+function ensureReaderRoot(env) {
+  const parent = stateParent(env);
+  const readerRoot = storeReaderLeasesPath(env);
+  mkdirSync(parent, { recursive: true, mode: 448 });
+  assertPrivateDirectory(parent);
+  try {
+    mkdirSync(readerRoot, { mode: 448 });
+  } catch (error) {
+    if (error.code !== "EEXIST")
+      throw error;
+  }
+  assertPrivateDirectory(readerRoot);
+  return readerRoot;
+}
+function processStartIdentity() {
+  const result = spawnSync("/bin/ps", ["-o", "lstart=", "-p", String(process.pid)], {
+    encoding: "utf8",
+    env: { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC0" }
+  });
+  const identity = result.status === 0 ? result.stdout.trim().replace(/\s+/g, " ") : "";
+  if (!identity) {
+    throw new Error("Could not establish the local Store reader process identity");
+  }
+  return identity;
+}
+function maintenanceUnavailable() {
+  return new Error("Local Recordings storage is temporarily unavailable during app installation maintenance");
+}
+function assertMaintenanceAbsent(env) {
+  if (pathExists(installMaintenanceMarkerPath(env)))
+    throw maintenanceUnavailable();
+}
+function canonicalPotentialPath(path) {
+  const absolutePath = resolve(path);
+  let existingPath = absolutePath;
+  const missingEntries = [];
+  while (true) {
+    try {
+      return join2(realpathSync(existingPath), ...missingEntries);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        return absolutePath;
+      const parent = dirname(existingPath);
+      if (parent === existingPath)
+        return absolutePath;
+      missingEntries.unshift(basename(existingPath));
+      existingPath = parent;
+    }
+  }
+}
+function pathIsWithin(root, candidate) {
+  const relativePath = relative(root, candidate);
+  return relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+function isGlobalRecordingsStatePath(path, env = process.env) {
+  const globalStateRoot = join2(stateParent(env), "recordings");
+  return pathIsWithin(resolve(globalStateRoot), resolve(path)) || pathIsWithin(canonicalPotentialPath(globalStateRoot), canonicalPotentialPath(path));
+}
+function removeActiveLease(activeLease, releasedLease) {
+  try {
+    renameSync(activeLease, releasedLease);
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  rmSync(releasedLease, { recursive: true, force: true });
+}
+function acquireLocalStoreReaderLease(env = process.env) {
+  assertMaintenanceAbsent(env);
+  const readerRoot = ensureReaderRoot(env);
+  const nonce = randomUUID3();
+  const pendingLease = join2(readerRoot, `.pending-${process.pid}-${nonce}`);
+  const activeLease = join2(readerRoot, `lease-${process.pid}-${nonce}`);
+  const releasedLease = join2(readerRoot, `.released-${process.pid}-${nonce}`);
+  let active = false;
+  try {
+    mkdirSync(pendingLease, { mode: 448 });
+    const owner = join2(pendingLease, "owner");
+    writeFileSync(owner, `${process.pid}
+${processStartIdentity()}
+`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 384
+    });
+    chmodSync(owner, 384);
+    renameSync(pendingLease, activeLease);
+    active = true;
+    assertMaintenanceAbsent(env);
+  } catch (error) {
+    if (active)
+      removeActiveLease(activeLease, releasedLease);
+    else
+      rmSync(pendingLease, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return () => {
+    if (released)
+      return;
+    removeActiveLease(activeLease, releasedLease);
+    released = true;
+  };
+}
+async function withLocalStoreReaderLease(operation, env = process.env) {
+  const release = acquireLocalStoreReaderLease(env);
+  try {
+    return await operation();
+  } finally {
+    release();
+  }
+}
+
+// src/lib/config.ts
+var POST_PROCESSING_MODES = new Set([
+  "off",
+  "auto",
+  "always"
+]);
+var DEFAULT_TRANSCRIPTION_MODEL = "gpt-4o-transcribe";
+var DEFAULT_REALTIME_SESSION_MODEL = "gpt-realtime";
+var DEFAULT_REALTIME_TRANSCRIPTION_MODEL = "gpt-realtime-whisper";
 var DEFAULT_CONFIG = {
   openai_api_key: "",
   enhancement_api_key: "",
-  transcription_model: "gpt-4o-transcribe",
+  transcription_model: DEFAULT_TRANSCRIPTION_MODEL,
+  realtime_session_model: DEFAULT_REALTIME_SESSION_MODEL,
+  realtime_transcription_model: DEFAULT_REALTIME_TRANSCRIPTION_MODEL,
   enhancement_model: "gpt-4o",
+  transcriber_model: "gpt-4o",
   language: "en",
   audio_format: "wav",
   sample_rate: 16000,
   record_command: "sox",
   hotkey: "space",
+  transcription_prompt: "",
+  transcriber_prompt: "",
+  post_processing_mode: "auto",
   auto_enhance: true,
   enhance_triggers: [
     "say it better",
@@ -935,17 +1116,23 @@ var DEFAULT_CONFIG = {
   keyword_transforms: {},
   db_path: "",
   audio_dir: "",
-  max_recording_seconds: 1800
+  max_recording_seconds: 1800,
+  config_warnings: []
 };
 function loadConfig(configPath) {
   const config = { ...DEFAULT_CONFIG };
-  const filePath = configPath || findConfigFile() || join2(getDataDir(), "config.json");
+  config.config_warnings = [];
+  let explicitPostProcessingMode = false;
+  let explicitTranscriberModel = false;
+  const filePath = configPath || findConfigFile() || join3(getDataDir(), "config.json");
   let fileProvidedOpenAIKey = false;
   if (existsSync2(filePath)) {
     try {
       const raw = readFileSync(filePath, "utf-8");
       const fileConfig = JSON.parse(raw);
       const expanded = expandEnvBackedConfig(fileConfig);
+      explicitPostProcessingMode = typeof fileConfig.post_processing_mode === "string";
+      explicitTranscriberModel = typeof fileConfig.transcriber_model === "string";
       Object.assign(config, expanded);
       fileProvidedOpenAIKey = typeof expanded.openai_api_key === "string" && expanded.openai_api_key.length > 0;
     } catch {}
@@ -962,12 +1149,35 @@ function loadConfig(configPath) {
   if (process.env.RECORDINGS_MODEL) {
     config.transcription_model = process.env.RECORDINGS_MODEL;
   }
+  if (process.env.RECORDINGS_REALTIME_SESSION_MODEL) {
+    config.realtime_session_model = process.env.RECORDINGS_REALTIME_SESSION_MODEL;
+  }
+  if (process.env.RECORDINGS_REALTIME_TRANSCRIPTION_MODEL) {
+    config.realtime_transcription_model = process.env.RECORDINGS_REALTIME_TRANSCRIPTION_MODEL;
+  }
   if (process.env.RECORDINGS_ENHANCEMENT_MODEL) {
     config.enhancement_model = process.env.RECORDINGS_ENHANCEMENT_MODEL;
   }
+  if (process.env.RECORDINGS_TRANSCRIBER_MODEL) {
+    config.transcriber_model = process.env.RECORDINGS_TRANSCRIBER_MODEL;
+    explicitTranscriberModel = true;
+  }
   if (process.env.RECORDINGS_LANGUAGE) {
     config.language = process.env.RECORDINGS_LANGUAGE;
   }
+  if (process.env.RECORDINGS_TRANSCRIPTION_PROMPT) {
+    config.transcription_prompt = process.env.RECORDINGS_TRANSCRIPTION_PROMPT;
+  }
+  if (process.env.RECORDINGS_TRANSCRIBER_PROMPT) {
+    config.transcriber_prompt = process.env.RECORDINGS_TRANSCRIBER_PROMPT;
+  }
+  if (process.env.RECORDINGS_POST_PROCESSING_MODE) {
+    config.post_processing_mode = normalizePostProcessingMode(process.env.RECORDINGS_POST_PROCESSING_MODE, config.post_processing_mode ?? "auto");
+    explicitPostProcessingMode = true;
+  }
+  if (process.env.RECORDINGS_AUTO_ENHANCE) {
+    config.auto_enhance = parseBooleanEnv(process.env.RECORDINGS_AUTO_ENHANCE, config.auto_enhance);
+  }
   if (process.env.HASNA_RECORDINGS_DB_PATH) {
     config.db_path = process.env.HASNA_RECORDINGS_DB_PATH;
   } else if (process.env.RECORDINGS_DB_PATH) {
@@ -985,14 +1195,86 @@ function loadConfig(configPath) {
   if (!config.enhancement_api_key) {
     config.enhancement_api_key = config.openai_api_key || loadSecretKey("OPENAI_API_KEY");
   }
+  if (!explicitTranscriberModel) {
+    config.transcriber_model = config.enhancement_model;
+  }
+  normalizeModelSlots(config);
+  normalizePostProcessingConfig(config, explicitPostProcessingMode);
   if (!config.db_path) {
-    config.db_path = join2(getDataDir(), "recordings.db");
+    config.db_path = join3(getDataDir(), "recordings.db");
   }
   if (!config.audio_dir) {
-    config.audio_dir = join2(getDataDir(), "audio");
+    config.audio_dir = join3(getDataDir(), "audio");
+  }
+  return config;
+}
+function normalizeModelSlots(config) {
+  const warnings = config.config_warnings ?? [];
+  config.config_warnings = warnings;
+  const boundedModel = config.transcription_model?.trim() || DEFAULT_TRANSCRIPTION_MODEL;
+  if (isRealtimeOnlyModel(boundedModel)) {
+    warnings.push(`Ignoring RECORDINGS_MODEL=${boundedModel}; bounded transcription uses ${DEFAULT_TRANSCRIPTION_MODEL}.`);
+    config.transcription_model = DEFAULT_TRANSCRIPTION_MODEL;
+  } else {
+    config.transcription_model = boundedModel;
+  }
+  const realtimeSessionModel = config.realtime_session_model?.trim() || DEFAULT_REALTIME_SESSION_MODEL;
+  if (isTranscriptionOnlyModel(realtimeSessionModel)) {
+    warnings.push(`Ignoring realtime session model ${realtimeSessionModel}; use ${DEFAULT_REALTIME_TRANSCRIPTION_MODEL} as realtime_transcription_model instead.`);
+    config.realtime_session_model = DEFAULT_REALTIME_SESSION_MODEL;
+  } else {
+    config.realtime_session_model = realtimeSessionModel;
+  }
+  const realtimeTranscriptionModel = config.realtime_transcription_model?.trim() || DEFAULT_REALTIME_TRANSCRIPTION_MODEL;
+  if (!isRealtimeTranscriptionModel(realtimeTranscriptionModel)) {
+    warnings.push(`Ignoring realtime transcription model ${realtimeTranscriptionModel}; realtime transcription uses ${DEFAULT_REALTIME_TRANSCRIPTION_MODEL}.`);
+    config.realtime_transcription_model = DEFAULT_REALTIME_TRANSCRIPTION_MODEL;
+  } else {
+    config.realtime_transcription_model = realtimeTranscriptionModel;
+  }
+  return config;
+}
+function isTranscriptionOnlyModel(model) {
+  const m = model.trim().toLowerCase();
+  return m === "whisper-1" || m === DEFAULT_REALTIME_TRANSCRIPTION_MODEL || m.includes("transcribe");
+}
+function isRealtimeOnlyModel(model) {
+  const m = model.trim().toLowerCase();
+  return m.startsWith("gpt-realtime");
+}
+function isRealtimeTranscriptionModel(model) {
+  const m = model.trim().toLowerCase();
+  return m === DEFAULT_REALTIME_TRANSCRIPTION_MODEL || m.startsWith("gpt-realtime") && m.includes("whisper");
+}
+function normalizePostProcessingMode(value, fallback = "auto") {
+  const mode = value?.trim().toLowerCase();
+  if (mode && POST_PROCESSING_MODES.has(mode)) {
+    return mode;
+  }
+  return fallback;
+}
+function normalizePostProcessingConfig(config, preferPostProcessingMode = true) {
+  if (preferPostProcessingMode) {
+    config.post_processing_mode = normalizePostProcessingMode(config.post_processing_mode, "auto");
+    config.auto_enhance = config.post_processing_mode !== "off";
+    return config;
+  }
+  if (config.auto_enhance === false) {
+    config.post_processing_mode = "off";
+  } else {
+    config.post_processing_mode = normalizePostProcessingMode(config.post_processing_mode, "auto");
   }
+  config.auto_enhance = config.post_processing_mode !== "off";
   return config;
 }
+function parseBooleanEnv(value, fallback) {
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized))
+    return true;
+  if (["0", "false", "no", "off"].includes(normalized))
+    return false;
+  return fallback;
+}
 function expandEnvBackedConfig(config) {
   const expanded = { ...config };
   for (const key of ["openai_api_key", "enhancement_api_key"]) {
@@ -1011,36 +1293,68 @@ function getDataDir() {
   if (projectLocalDir)
     return projectLocalDir;
   const home = getHomeDir();
-  const newDir = join2(home, ".hasna", "recordings");
-  const oldDir = join2(home, ".recordings");
+  const newDir = join3(home, ".hasna", "recordings");
+  const oldDir = join3(home, ".recordings");
   if (existsSync2(oldDir)) {
+    const releaseLease = acquireLocalStoreReaderLease();
     try {
-      mergeDirectoryContents(oldDir, newDir);
-    } catch {}
+      try {
+        if (existsSync2(oldDir))
+          mergeDirectoryContents(oldDir, newDir);
+      } catch {}
+    } finally {
+      releaseLease();
+    }
   }
   return newDir;
 }
 function findProjectRecordingsPath(entry) {
-  const home = resolve(getHomeDir());
-  let dir = resolve(process.cwd());
+  const cwd = canonicalExistingPath(process.cwd());
+  const home = canonicalExistingPath(getHomeDir());
+  const repositoryRoot = findRepositoryRoot(cwd);
+  const cwdIsInsideHome = cwd === home || cwd.startsWith(`${home}${sep2}`);
+  const repositoryIsInsideHome = repositoryRoot !== null && repositoryRoot !== home && repositoryRoot.startsWith(`${home}${sep2}`);
+  const boundary = cwdIsInsideHome ? repositoryIsInsideHome ? repositoryRoot : home : repositoryRoot ?? cwd;
+  const excludeBoundary = boundary === home;
+  let dir = cwd;
   while (true) {
-    if (dir !== home) {
-      const candidate = entry ? join2(dir, ".recordings", entry) : join2(dir, ".recordings");
-      if (existsSync2(candidate))
-        return candidate;
-    }
-    const parent = dirname(dir);
+    if (excludeBoundary && dir === boundary)
+      break;
+    const candidate = entry ? join3(dir, ".recordings", entry) : join3(dir, ".recordings");
+    if (existsSync2(candidate))
+      return candidate;
+    if (dir === boundary)
+      break;
+    const parent = dirname2(dir);
     if (parent === dir)
       break;
     dir = parent;
   }
   return null;
 }
+function findRepositoryRoot(start) {
+  let dir = start;
+  while (true) {
+    if (existsSync2(join3(dir, ".git")))
+      return dir;
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function canonicalExistingPath(path) {
+  try {
+    return realpathSync2(path);
+  } catch {
+    return resolve2(path);
+  }
+}
 function mergeDirectoryContents(sourceDir, targetDir) {
-  mkdirSync(targetDir, { recursive: true });
+  mkdirSync2(targetDir, { recursive: true });
   for (const entry of readdirSync(sourceDir)) {
-    const sourcePath = join2(sourceDir, entry);
-    const targetPath = join2(targetDir, entry);
+    const sourcePath = join3(sourceDir, entry);
+    const targetPath = join3(targetDir, entry);
     const sourceStats = statSync(sourcePath);
     if (sourceStats.isDirectory()) {
       mergeDirectoryContents(sourcePath, targetPath);
@@ -1050,7 +1364,7 @@ function mergeDirectoryContents(sourceDir, targetDir) {
   }
 }
 function loadSecretKey(keyName) {
-  const secretsPath = join2(getHomeDir(), ".secrets");
+  const secretsPath = join3(getHomeDir(), ".secrets");
   if (!existsSync2(secretsPath))
     return "";
   for (const candidate of listSecretFiles(secretsPath)) {
@@ -1077,7 +1391,7 @@ function listSecretFiles(path) {
     if (!stats.isDirectory())
       return [];
     return readdirSync(path).sort().flatMap((entry) => {
-      const child = join2(path, entry);
+      const child = join3(path, entry);
       try {
         const childStats = statSync(child);
         if (childStats.isDirectory())
@@ -1092,14 +1406,19 @@ function listSecretFiles(path) {
   }
 }
 function getHomeDir() {
-  return process.env["HOME"] || process.env["USERPROFILE"] || homedir2();
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir3();
 }
 function ensureDataDir(config) {
-  const { mkdirSync: mkdirSync2 } = __require("fs");
-  mkdirSync2(config.audio_dir, { recursive: true });
+  const { mkdirSync: mkdirSync3 } = __require("fs");
   const dbDir = config.db_path.substring(0, config.db_path.lastIndexOf("/"));
-  if (dbDir)
-    mkdirSync2(dbDir, { recursive: true });
+  const releaseLease = [config.audio_dir, dbDir].some((path) => path.length > 0 && isGlobalRecordingsStatePath(path)) ? acquireLocalStoreReaderLease() : () => {};
+  try {
+    mkdirSync3(config.audio_dir, { recursive: true });
+    if (dbDir)
+      mkdirSync3(dbDir, { recursive: true });
+  } finally {
+    releaseLease();
+  }
 }
 
 // src/db/sqlite-adapter.ts
@@ -1134,8 +1453,8 @@ class SqliteAdapter {
 }
 
 // src/db/database.ts
-import { mkdirSync as mkdirSync2 } from "fs";
-import { dirname as dirname2 } from "path";
+import { mkdirSync as mkdirSync3 } from "fs";
+import { dirname as dirname3 } from "path";
 var _db = null;
 var _adapter = null;
 var MIGRATIONS = [
@@ -1221,8 +1540,8 @@ function getDatabase(dbPath) {
   if (_db)
     return _db;
   const path = dbPath || loadConfig().db_path;
-  const dir = dirname2(path);
-  mkdirSync2(dir, { recursive: true });
+  const dir = dirname3(path);
+  mkdirSync3(dir, { recursive: true });
   _adapter = new SqliteAdapter(path);
   _db = _adapter.raw;
   _db.run("PRAGMA busy_timeout = 5000");
@@ -1278,6 +1597,63 @@ function shortUuid() {
   return crypto.randomUUID().slice(0, 8);
 }
 
+// src/db/errors.ts
+class ProjectNotFoundError extends Error {
+  ref;
+  constructor(ref) {
+    super(`project not found: ${ref}`);
+    this.name = "ProjectNotFoundError";
+    this.ref = ref;
+  }
+}
+
+class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+// src/lib/recording-create-identity.ts
+var MAX_RECORDING_IDENTITY_LENGTH = 255;
+function validateIdentityValue(value, label, nullMeansAbsent = false) {
+  if (value === undefined || nullMeansAbsent && value === null)
+    return;
+  if (typeof value !== "string") {
+    throw new ValidationError(`${label} must be a string`);
+  }
+  if (value.length === 0) {
+    throw new ValidationError(`${label} must not be empty`);
+  }
+  if (value.length > MAX_RECORDING_IDENTITY_LENGTH) {
+    throw new ValidationError(`${label} must not exceed ${MAX_RECORDING_IDENTITY_LENGTH} characters`);
+  }
+  if (value !== value.trim()) {
+    throw new ValidationError(`${label} must not contain leading or trailing whitespace`);
+  }
+  if (/[\u0000-\u001f\u007f]/.test(value)) {
+    throw new ValidationError(`${label} must not contain control characters`);
+  }
+  if (/[^\u0020-\u007e]/.test(value)) {
+    throw new ValidationError(`${label} must contain only printable ASCII characters`);
+  }
+  return value;
+}
+function recordingCreateIdentity(input, idempotencyKey, options = {}) {
+  const bodyId = validateIdentityValue(input.id, "recording id", true);
+  const headerKey = validateIdentityValue(idempotencyKey, "idempotency key");
+  if (bodyId !== undefined && headerKey !== undefined && bodyId !== headerKey) {
+    throw new ValidationError("recording id conflicts with idempotency key");
+  }
+  const effectiveKey = headerKey ?? bodyId;
+  const { id: _runtimeId, ...inputWithoutId } = input;
+  const persistedId = options.bindIdempotencyKeyToId === false ? bodyId : effectiveKey;
+  return {
+    input: persistedId === undefined ? inputWithoutId : { ...inputWithoutId, id: persistedId },
+    idempotencyKey: effectiveKey
+  };
+}
+
 // src/db/recordings.ts
 function parseRow(row) {
   return {
@@ -1302,20 +1678,36 @@ function parseRow(row) {
     created_at: row["created_at"]
   };
 }
-function createRecording(input, db) {
+function createRecording(input, db, idempotencyKey) {
   const d = db || getDatabase();
-  const id = shortUuid();
-  const tagsJson = JSON.stringify(input.tags || []);
-  const metadataJson = JSON.stringify(input.metadata || {});
-  d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, metadataJson);
-  if (input.tags && input.tags.length > 0) {
-    const insertTag = d.query("INSERT OR IGNORE INTO recording_tags (recording_id, tag) VALUES (?, ?)");
-    for (const tag of input.tags) {
-      insertTag.run(id, tag);
+  input = recordingCreateIdentity(input, idempotencyKey).input;
+  const id = input.id || shortUuid();
+  const create = d.transaction(() => {
+    if (input.id) {
+      const existing = getRecording(input.id, d);
+      if (existing?.id === input.id)
+        return existing;
     }
-  }
-  return getRecording(id, d);
+    const tagsJson = JSON.stringify(input.tags || []);
+    const metadataJson = JSON.stringify(input.metadata || {});
+    const insertResult = d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO NOTHING`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, metadataJson);
+    if (insertResult.changes === 0) {
+      const existing = getRecording(id, d);
+      if (existing?.id === id)
+        return existing;
+      throw new Error("recording id conflict could not be read back");
+    }
+    if (input.tags && input.tags.length > 0) {
+      const insertTag = d.query("INSERT OR IGNORE INTO recording_tags (recording_id, tag) VALUES (?, ?)");
+      for (const tag of input.tags) {
+        insertTag.run(id, tag);
+      }
+    }
+    return getRecording(id, d);
+  });
+  return create();
 }
 function getRecording(id, db) {
   const d = db || getDatabase();
@@ -1327,6 +1719,20 @@ function getRecording(id, db) {
 }
 function listRecordings(filter, db) {
   const d = db || getDatabase();
+  const { where, params } = buildRecordingWhere(filter);
+  const limit = filter?.limit || 50;
+  const offset = filter?.offset || 0;
+  const sql = `SELECT * FROM recordings ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`;
+  const rows = d.query(sql).all(...params, limit, offset);
+  return rows.map(parseRow);
+}
+function countRecordings(filter, db) {
+  const d = db || getDatabase();
+  const { where, params } = buildRecordingWhere(filter);
+  const row = d.query(`SELECT COUNT(*) as c FROM recordings ${where}`).get(...params);
+  return row.c;
+}
+function buildRecordingWhere(filter) {
   const conditions = [];
   const params = [];
   if (filter?.agent_id) {
@@ -1365,12 +1771,7 @@ function listRecordings(filter, db) {
     params.push(filter.until);
   }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-  const limit = filter?.limit || 50;
-  const offset = filter?.offset || 0;
-  const sql = `SELECT * FROM recordings ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`;
-  params.push(limit, offset);
-  const rows = d.query(sql).all(...params);
-  return rows.map(parseRow);
+  return { where, params };
 }
 function deleteRecording(id, db) {
   const d = db || getDatabase();
@@ -1443,16 +1844,6 @@ function listProjects(db) {
   return rows.map(parseProject);
 }
 
-// src/db/errors.ts
-class ProjectNotFoundError extends Error {
-  ref;
-  constructor(ref) {
-    super(`project not found: ${ref}`);
-    this.name = "ProjectNotFoundError";
-    this.ref = ref;
-  }
-}
-
 // src/db/agents.ts
 function parseAgent(row) {
   return {
@@ -1518,7 +1909,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.11";
+var VERSION = "0.2.13";
 
 // src/db/feedback.ts
 function saveFeedback(input) {
@@ -1811,6 +2202,7 @@ function resolveStorageClient(name, env = process.env, fetchImpl) {
 }
 
 // src/store.ts
+import { createHash, randomUUID as randomUUID5 } from "crypto";
 var APP = "recordings";
 function listQuery(filter) {
   if (!filter)
@@ -1820,6 +2212,7 @@ function listQuery(filter) {
     project_id: filter.project_id,
     session_id: filter.session_id,
     processing_mode: filter.processing_mode,
+    tags: filter.tags,
     search: filter.search,
     since: filter.since,
     until: filter.until,
@@ -1836,58 +2229,63 @@ function unwrap(res, key) {
 var localStore = {
   mode: "local",
   baseUrl: null,
-  async createRecording(input) {
-    return createRecording(input);
+  async createRecording(input, idempotencyKey) {
+    return withLocalStoreReaderLease(() => createRecording(input, undefined, idempotencyKey));
   },
   async getRecording(id) {
-    return getRecording(id);
+    return withLocalStoreReaderLease(() => getRecording(id));
   },
   async listRecordings(filter) {
-    return listRecordings(filter);
+    return withLocalStoreReaderLease(() => listRecordings(filter));
+  },
+  async countRecordings(filter) {
+    return withLocalStoreReaderLease(() => countRecordings(filter));
   },
   async searchRecordings(query, filter) {
-    return searchRecordings(query, filter);
+    return withLocalStoreReaderLease(() => searchRecordings(query, filter));
   },
   async deleteRecording(id) {
-    return deleteRecording(id);
+    return withLocalStoreReaderLease(() => deleteRecording(id));
   },
   async getRecordingStats() {
-    return getRecordingStats();
+    return withLocalStoreReaderLease(() => getRecordingStats());
   },
   async registerAgent(name, description, role) {
-    return registerAgent(name, description, role);
+    return withLocalStoreReaderLease(() => registerAgent(name, description, role));
   },
   async getAgent(idOrName) {
-    return getAgent(idOrName);
+    return withLocalStoreReaderLease(() => getAgent(idOrName));
   },
   async listAgents() {
-    return listAgents();
+    return withLocalStoreReaderLease(() => listAgents());
   },
   async heartbeatAgent(idOrName) {
-    return heartbeatAgent(idOrName);
+    return withLocalStoreReaderLease(() => heartbeatAgent(idOrName));
   },
   async setAgentFocus(idOrName, projectId) {
-    return setAgentFocus(idOrName, projectId);
+    return withLocalStoreReaderLease(() => setAgentFocus(idOrName, projectId));
   },
   async registerProject(name, path, description) {
-    return registerProject(name, path, description);
+    return withLocalStoreReaderLease(() => registerProject(name, path, description));
   },
   async getProject(idOrPath) {
-    return getProject(idOrPath);
+    return withLocalStoreReaderLease(() => getProject(idOrPath));
   },
   async listProjects() {
-    return listProjects();
+    return withLocalStoreReaderLease(() => listProjects());
   },
   async saveFeedback(input) {
-    saveFeedback(input);
+    await withLocalStoreReaderLease(() => saveFeedback(input));
   }
 };
 function apiStore(client) {
   return {
     mode: "cloud-http",
     baseUrl: client.baseUrl,
-    async createRecording(input) {
-      const res = await client.create("recordings", input);
+    async createRecording(input, idempotencyKey) {
+      const keyCandidate = idempotencyKey === undefined && (input.id === undefined || input.id === null) ? randomUUID5() : idempotencyKey;
+      const identity = recordingCreateIdentity(input, keyCandidate, { bindIdempotencyKeyToId: false });
+      const res = await client.create("recordings", identity.input, identity.idempotencyKey);
       return unwrap(res, "recording");
     },
     async getRecording(id) {
@@ -1898,6 +2296,36 @@ function apiStore(client) {
       const { items } = await client.list("recordings", listQuery(filter));
       return items;
     },
+    async countRecordings(filter) {
+      const pageLimit = 500;
+      const maxPageRequests = 1e4;
+      let offset = 0;
+      let pageRequests = 0;
+      const seenPageKeys = new Set;
+      while (pageRequests < maxPageRequests) {
+        pageRequests += 1;
+        const { items, raw } = await client.list("recordings", {
+          ...listQuery(filter),
+          limit: pageLimit,
+          offset
+        });
+        const count = raw && typeof raw === "object" ? raw.count : undefined;
+        if (typeof count !== "number" || !Number.isFinite(count)) {
+          throw new Error("Recordings API response is missing a valid count");
+        }
+        if (count > items.length)
+          return count;
+        if (items.length === 0)
+          return offset;
+        offset += items.length;
+        const pageKey = recordingPageFingerprint(items);
+        if (seenPageKeys.has(pageKey)) {
+          throw new Error("Recordings API ignored pagination while counting legacy results");
+        }
+        seenPageKeys.add(pageKey);
+      }
+      throw new Error(`Recordings API exceeded ${maxPageRequests} pages while counting legacy results`);
+    },
     async searchRecordings(query, filter) {
       const { items } = await client.list("recordings", listQuery({ ...filter ?? {}, search: query }));
       return items;
@@ -1979,6 +2407,42 @@ function apiStore(client) {
     }
   };
 }
+function recordingPageFingerprint(items) {
+  const hash = createHash("sha256");
+  const ids = items.map((item) => String(item.id ?? "")).sort();
+  for (const id of ids) {
+    hash.update(String(id.length));
+    hash.update(":");
+    hash.update(id);
+    hash.update(";");
+  }
+  return `${items.length}:${hash.digest("hex")}`;
+}
+async function countStoreRecordings(store, filter) {
+  if (store.countRecordings)
+    return store.countRecordings(filter);
+  const pageLimit = 500;
+  const maxPageRequests = 1e4;
+  const { limit: _limit, offset: _offset, ...unpaginated } = filter ?? {};
+  const seenPageKeys = new Set;
+  let offset = 0;
+  for (let pageRequests = 0;pageRequests < maxPageRequests; pageRequests += 1) {
+    const items = await store.listRecordings({
+      ...unpaginated,
+      limit: pageLimit,
+      offset
+    });
+    if (items.length === 0)
+      return offset;
+    const pageKey = recordingPageFingerprint(items);
+    if (seenPageKeys.has(pageKey)) {
+      throw new Error("Legacy Store ignored pagination while counting recordings");
+    }
+    seenPageKeys.add(pageKey);
+    offset += items.length;
+  }
+  throw new Error(`Legacy Store exceeded ${maxPageRequests} pages while counting recordings`);
+}
 var cached = null;
 function getStore(env = process.env) {
   if (env === process.env && cached)
@@ -1992,7 +2456,7 @@ function getStore(env = process.env) {
 
 // src/lib/recorder.ts
 import { spawn as spawn2 } from "child_process";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { existsSync as existsSync3 } from "fs";
 
 // src/types/index.ts
@@ -2021,16 +2485,6 @@ class EnhancementError extends Error {
 var _recordProcess = null;
 var _currentFile = null;
 async function checkRecordingDeps() {
-  try {
-    const proc = Bun.spawn(["which", "sox"], {
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    await proc.exited;
-    if (proc.exitCode === 0) {
-      return { available: true, tool: "sox", message: "sox is available" };
-    }
-  } catch {}
   try {
     const proc = Bun.spawn(["which", "rec"], {
       stdout: "pipe",
@@ -2041,20 +2495,6 @@ async function checkRecordingDeps() {
       return { available: true, tool: "rec", message: "rec is available" };
     }
   } catch {}
-  try {
-    const proc = Bun.spawn(["which", "ffmpeg"], {
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    await proc.exited;
-    if (proc.exitCode === 0) {
-      return {
-        available: true,
-        tool: "ffmpeg",
-        message: "ffmpeg is available"
-      };
-    }
-  } catch {}
   return {
     available: false,
     tool: "none",
@@ -2067,11 +2507,20 @@ function startRecording(config) {
   }
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
   const filename = `recording-${timestamp}.${config.audio_format}`;
-  const filepath = join3(config.audio_dir, filename);
+  const filepath = join4(config.audio_dir, filename);
   const args = buildRecordArgs(filepath, config);
-  _recordProcess = spawn2(args[0], args.slice(1), {
-    stdio: ["pipe", "pipe", "pipe"]
-  });
+  const releaseLease = isGlobalRecordingsStatePath(filepath) ? acquireLocalStoreReaderLease() : () => {};
+  let recordProcess;
+  try {
+    recordProcess = spawn2(args[0], args.slice(1), {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (error) {
+    releaseLease();
+    throw error;
+  }
+  _recordProcess = recordProcess;
+  _currentFile = filepath;
   if (config.max_recording_seconds > 0) {
     setTimeout(() => {
       if (_recordProcess && _currentFile === filepath) {
@@ -2080,14 +2529,18 @@ function startRecording(config) {
       }
     }, config.max_recording_seconds * 1000);
   }
-  _currentFile = filepath;
-  _recordProcess.on("error", (err) => {
-    _recordProcess = null;
-    _currentFile = null;
+  recordProcess.on("error", (err) => {
+    if (_recordProcess === recordProcess) {
+      _recordProcess = null;
+      _currentFile = null;
+    }
+    releaseLease();
     throw new RecordingError(`Recording process error: ${err.message}`);
   });
-  _recordProcess.on("exit", () => {
-    _recordProcess = null;
+  recordProcess.on("exit", () => {
+    if (_recordProcess === recordProcess)
+      _recordProcess = null;
+    releaseLease();
   });
   return filepath;
 }
@@ -2122,7 +2575,7 @@ function buildRecordArgs(filepath, config) {
 async function recordDuration(seconds, config) {
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
   const filename = `recording-${timestamp}.${config.audio_format}`;
-  const filepath = join3(config.audio_dir, filename);
+  const filepath = join4(config.audio_dir, filename);
   const args = [
     "rec",
     "-r",
@@ -2136,29 +2589,36 @@ async function recordDuration(seconds, config) {
     "0",
     seconds.toString()
   ];
-  const proc = Bun.spawn(args, {
-    stdout: "pipe",
-    stderr: "pipe"
-  });
-  const exitCode = await proc.exited;
-  if (exitCode !== 0 && !existsSync3(filepath)) {
-    const stderr = await new Response(proc.stderr).text();
-    throw new RecordingError(`Recording failed (exit ${exitCode}): ${stderr}`);
+  const releaseLease = isGlobalRecordingsStatePath(filepath) ? acquireLocalStoreReaderLease() : () => {};
+  try {
+    const proc = Bun.spawn(args, {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const exitCode = await proc.exited;
+    if (exitCode !== 0 && !existsSync3(filepath)) {
+      const stderr = await new Response(proc.stderr).text();
+      throw new RecordingError(`Recording failed (exit ${exitCode}): ${stderr}`);
+    }
+    return filepath;
+  } finally {
+    releaseLease();
   }
-  return filepath;
 }
 
 // src/lib/transcriber.ts
 import OpenAI from "openai";
 import { createReadStream } from "fs";
 var _client = null;
+var _clientApiKey = null;
 function getClient(config) {
-  if (_client)
-    return _client;
   if (!config.openai_api_key) {
     throw new TranscriptionError("OpenAI API key not configured. Set OPENAI_API_KEY env var or add to ~/.secrets");
   }
+  if (_client && _clientApiKey === config.openai_api_key)
+    return _client;
   _client = new OpenAI({ apiKey: config.openai_api_key });
+  _clientApiKey = config.openai_api_key;
   return _client;
 }
 async function transcribeAudio(audioPath, config, options = {}) {
@@ -2170,7 +2630,7 @@ async function transcribeAudio(audioPath, config, options = {}) {
       file: stream,
       model: config.transcription_model,
       language: config.language || undefined,
-      prompt: buildVerbatimPrompt(options.prompt),
+      prompt: buildVerbatimPrompt(options.prompt ?? config.transcription_prompt),
       response_format: "json"
     });
     stream.destroy();
@@ -2198,7 +2658,7 @@ async function transcribeAudioStream(audioPath, config, options = {}) {
       file: fileStream,
       model: config.transcription_model,
       language: config.language || undefined,
-      prompt: buildVerbatimPrompt(options.prompt),
+      prompt: buildVerbatimPrompt(options.prompt ?? config.transcription_prompt),
       response_format: "text",
       stream: true
     });
@@ -2247,14 +2707,16 @@ ${trimmed}`;
 // src/lib/enhancer.ts
 import OpenAI2 from "openai";
 var _enhancementClient = null;
+var _enhancementClientApiKey = null;
 function getEnhancementClient(config) {
-  if (_enhancementClient)
-    return _enhancementClient;
   const key = config.enhancement_api_key || config.openai_api_key;
   if (!key) {
     throw new EnhancementError("API key not configured for enhancement. Set OPENAI_API_KEY or RECORDINGS_ENHANCEMENT_KEY");
   }
+  if (_enhancementClient && _enhancementClientApiKey === key)
+    return _enhancementClient;
   _enhancementClient = new OpenAI2({ apiKey: key });
+  _enhancementClientApiKey = key;
   return _enhancementClient;
 }
 function needsEnhancement(text, config) {
@@ -2301,6 +2763,7 @@ function extractInstruction(text, trigger) {
 }
 async function enhanceText(rawText, instruction, config, systemPrompt) {
   const client = getEnhancementClient(config);
+  const model = resolveTranscriberModel(config);
   let basePrompt = `You are a writing assistant. The user has dictated speech that needs to be transformed into polished output.
 
 Rules:
@@ -2321,13 +2784,14 @@ Rules:
 Keyword Transformations:
 ${transformRules}`;
   }
-  const fullPrompt = systemPrompt ? `${basePrompt}
+  const transcriberPrompt = combinePrompts(config.transcriber_prompt, systemPrompt);
+  const fullPrompt = transcriberPrompt ? `${basePrompt}
 
-Additional context:
-${systemPrompt}` : basePrompt;
+Transcriber instructions:
+${transcriberPrompt}` : basePrompt;
   try {
     const response = await client.chat.completions.create({
-      model: config.enhancement_model,
+      model,
       messages: [
         {
           role: "system",
@@ -2345,7 +2809,7 @@ ${systemPrompt}` : basePrompt;
     return {
       original: rawText,
       enhanced,
-      model: config.enhancement_model,
+      model,
       reasoning: null
     };
   } catch (error) {
@@ -2353,29 +2817,109 @@ ${systemPrompt}` : basePrompt;
     throw new EnhancementError(`Enhancement failed: ${describeTranscriptionFailure(msg)}`);
   }
 }
-async function processText(rawText, config, systemPrompt, options) {
-  const force = options?.force === true;
-  if (!force && !config.auto_enhance) {
-    return { text: rawText, mode: "raw", enhancement_model: null };
+async function processText(rawText, config, systemPromptOrOptions, legacyOptions) {
+  const options = {
+    ...normalizeProcessTextOptions(systemPromptOrOptions),
+    ...legacyOptions
+  };
+  const postProcessingMode = options.force ? "always" : options.postProcessingMode ?? normalizePostProcessingMode(config.post_processing_mode, config.auto_enhance === false ? "off" : "auto");
+  if (postProcessingMode === "off") {
+    return {
+      text: rawText,
+      mode: "raw",
+      enhancement_model: null,
+      post_processing_mode: "off",
+      enhancement_reason: null
+    };
   }
-  const detection = needsEnhancement(rawText, config);
-  if (!force && !detection.needs) {
-    return { text: rawText, mode: "raw", enhancement_model: null };
+  const detection = postProcessingMode === "always" ? {
+    needs: true,
+    reason: "Always-on post-processing",
+    instruction: rawText
+  } : needsEnhancement(rawText, config);
+  if (!detection.needs) {
+    return {
+      text: rawText,
+      mode: "raw",
+      enhancement_model: null,
+      post_processing_mode: postProcessingMode,
+      enhancement_reason: detection.reason
+    };
   }
-  const instruction = detection.needs ? detection.instruction : rawText;
-  const result = await enhanceText(rawText, instruction, config, systemPrompt);
+  const result = await enhanceText(rawText, detection.instruction, config, options.systemPrompt);
   return {
     text: result.enhanced,
     mode: "enhanced",
-    enhancement_model: result.model
+    enhancement_model: result.model,
+    post_processing_mode: postProcessingMode,
+    enhancement_reason: detection.reason
   };
 }
+function resolveTranscriberModel(config) {
+  return config.transcriber_model || config.enhancement_model;
+}
+function normalizeProcessTextOptions(value) {
+  if (typeof value === "string")
+    return { systemPrompt: value };
+  return value ?? {};
+}
+function combinePrompts(...prompts) {
+  return prompts.map((prompt) => prompt?.trim() ?? "").filter(Boolean).join(`
+
+`);
+}
 
 // src/cli/options.ts
+var POST_PROCESSING_MODES2 = new Set(["off", "auto", "always"]);
 function applyEnhancementOptions(config, opts) {
-  if (opts.enhance === false || opts.noEnhance === false) {
+  if (opts.postProcessing) {
+    const requestedMode = opts.postProcessing.trim().toLowerCase();
+    if (!POST_PROCESSING_MODES2.has(requestedMode)) {
+      throw new Error("Invalid post-processing mode. Use one of: off, auto, always.");
+    }
+  }
+  const disableEnhancement = opts.enhance === false || opts.noEnhance === false;
+  if (disableEnhancement) {
     config.auto_enhance = false;
+    config.post_processing_mode = "off";
+    normalizePostProcessingConfig(config, true);
+  } else if (opts.postProcessing) {
+    config.post_processing_mode = normalizePostProcessingMode(opts.postProcessing, config.post_processing_mode ?? "auto");
+    normalizePostProcessingConfig(config, true);
+  } else {
+    normalizePostProcessingConfig(config, false);
+  }
+  if (opts.transcriberPrompt !== undefined) {
+    config.transcriber_prompt = opts.transcriberPrompt;
+  } else if (opts.systemPrompt !== undefined) {
+    config.transcriber_prompt = opts.systemPrompt;
+  }
+  if (opts.enhancementModel) {
+    config.enhancement_model = opts.enhancementModel;
+  }
+  if (opts.transcriberModel) {
+    config.transcriber_model = opts.transcriberModel;
+  } else if (opts.enhancementModel) {
+    config.transcriber_model = opts.enhancementModel;
+  }
+  if (opts.transcriptionModel) {
+    config.transcription_model = opts.transcriptionModel;
+  }
+  if (opts.enhanceTriggersJson !== undefined) {
+    const triggers = JSON.parse(opts.enhanceTriggersJson);
+    if (!Array.isArray(triggers) || !triggers.every((trigger) => typeof trigger === "string")) {
+      throw new Error("Invalid enhancement triggers snapshot; expected a JSON string array.");
+    }
+    config.enhance_triggers = triggers;
   }
+  if (opts.keywordTransformsJson !== undefined) {
+    const transforms = JSON.parse(opts.keywordTransformsJson);
+    if (typeof transforms !== "object" || transforms === null || Array.isArray(transforms) || !Object.values(transforms).every((value) => typeof value === "string")) {
+      throw new Error("Invalid keyword transforms snapshot; expected a JSON string map.");
+    }
+    config.keyword_transforms = transforms;
+  }
+  normalizeModelSlots(config);
   return config;
 }
 
@@ -2416,22 +2960,355 @@ function upsertCodexStdioBlock(content, name, mcpCmd) {
   const trimmed = cleaned.replace(/\s+$/, "");
   const block = `[mcp_servers.${name}]
 command = "${mcpCmd}"
-args = []
+args = ["--stdio"]
 `;
   return trimmed.length > 0 ? `${trimmed}
 
 ${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);
+function runMacOSPermissionRequest(appPath, runner = defaultPermissionHelperRunner) {
+  const executable = join5(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();
+}
+
+// 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;
+  try {
+    executable = realpathSync3(candidate);
+    if (!statSync2(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 = 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"
+    },
+    maxBuffer: 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 5000
+  });
+  const output = probe.stdout?.trim() ?? "";
+  const prefix = `${nonce}:`;
+  const version = output.startsWith(prefix) ? output.slice(prefix.length) : "";
+  if (probe.error || probe.status !== 0 || !BUN_VERSION_PATTERN.test(version)) {
+    return { reason: "behavioral Bun -e probe failed" };
+  }
+  return { executable, version };
+}
+function resolveInstallBunExecutable(environment, activeExecutable = process.execPath) {
+  if (environment.RECORDINGS_BUN_EXECUTABLE !== undefined) {
+    const explicit = validateBunExecutable(environment.RECORDINGS_BUN_EXECUTABLE);
+    if (!("executable" in explicit)) {
+      throw new Error(`RECORDINGS_BUN_EXECUTABLE is not a validated general Bun interpreter: ${explicit.reason}`);
+    }
+    return explicit.executable;
+  }
+  const active = validateBunExecutable(activeExecutable);
+  if ("executable" in active)
+    return active.executable;
+  throw new Error("The active recordings executable is not a general Bun interpreter; rerun app install from the Bun-interpreted package CLI or set RECORDINGS_BUN_EXECUTABLE to an explicitly trusted absolute Bun executable");
+}
+function createInstallerEnvironment(environment, bunExecutable) {
+  const sanitized = {};
+  for (const key of INSTALLER_ENVIRONMENT_KEYS) {
+    const value = environment[key];
+    if (value !== undefined)
+      sanitized[key] = value;
+  }
+  sanitized.PATH = INSTALLER_PATH;
+  sanitized.LC_ALL = "C";
+  sanitized.LANG = "C";
+  sanitized.TZ = "UTC0";
+  sanitized.RECORDINGS_BUN_EXECUTABLE = bunExecutable;
+  return sanitized;
+}
+
+// src/lib/release-install-policy.ts
+import { createHash as createHash2 } from "crypto";
+import {
+  chmodSync as chmodSync2,
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  mkdtempSync,
+  openSync,
+  readFileSync as readFileSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { isAbsolute as isAbsolute3, join as join6 } 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.-]+)?$/;
+var TEAM_ID = /^[A-Z0-9]{10}$/;
+var SHORT_HOSTNAME = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+var MAX_MANIFEST_BYTES = 16 * 1024 * 1024;
+var MAX_ENVELOPE_BYTES = 1024 * 1024;
+function assertReleaseOnlyOptions(options) {
+  if (options.approvedTarget !== "fleet") {
+    throw new Error("release installs require --approved-target fleet");
+  }
+  if (options.approvedTargetIdentityKind !== undefined || options.approvedTargetIdentitySha256 !== "none") {
+    throw new Error("release installs reject local-only target identity controls");
+  }
+  if (options.acknowledgeLocalSigningAndPermissions) {
+    throw new Error("release installs reject local-only signing acknowledgement controls");
+  }
+  if (options.expectedOldIdentitySha256 !== undefined || options.expectedNewIdentitySha256 !== undefined || options.allowSigningIdentityMigration) {
+    throw new Error("release installs reject local-only signing migration controls");
+  }
+  if (options.launch) {
+    throw new Error("release --launch is unsupported until the signed update client provides canonical post-install launch verification");
+  }
+  if (options.launchTimeout !== undefined) {
+    throw new Error("release --launch-timeout is unsupported without a verified release launch path");
+  }
+}
+function assertExpectedReleaseHostname(expected, actual) {
+  if (!SHORT_HOSTNAME.test(expected)) {
+    throw new Error("expected hostname is invalid; use one exact short hostname");
+  }
+  if (actual !== expected) {
+    throw new Error(`install target hostname ${actual || "<empty>"} does not match the expected hostname ${expected}`);
+  }
+}
+function parseLaunchTimeout(value) {
+  const timeout = value ?? "10";
+  if (!/^(?:[1-9]|[1-9][0-9]|1[01][0-9]|120)$/.test(timeout)) {
+    throw new Error("launch timeout must be an integer between 1 and 120 seconds");
+  }
+  return timeout;
+}
+function prepareReleaseInstallInputs(input) {
+  assertAbsolutePath(input.artifactPath, "artifact");
+  assertAbsolutePath(input.manifestPath, "manifest");
+  assertAbsolutePath(input.envelopePath, "envelope");
+  if (!LOWER_SHA256.test(input.manifestSha256)) {
+    throw new Error("manifest SHA-256 must be 64 lowercase hexadecimal characters");
+  }
+  if (!LOWER_SOURCE_SHA.test(input.expectedSourceSha)) {
+    throw new Error("source SHA must be 40 lowercase hexadecimal characters");
+  }
+  if (!RELEASE_VERSION.test(input.expectedVersion)) {
+    throw new Error("release version is invalid");
+  }
+  if (!input.expectedTeamId || !TEAM_ID.test(input.expectedTeamId)) {
+    throw new Error("Team ID must be 10 uppercase alphanumeric characters");
+  }
+  const manifestBytes = readBoundedRegularFile(input.manifestPath, "manifest", MAX_MANIFEST_BYTES);
+  const actualManifestSha256 = createHash2("sha256").update(manifestBytes).digest("hex");
+  if (actualManifestSha256 !== input.manifestSha256) {
+    throw new Error("manifest does not match the operator-approved SHA-256");
+  }
+  const envelopeBytes = readBoundedRegularFile(input.envelopePath, "envelope", MAX_ENVELOPE_BYTES);
+  const manifest = parseObject(manifestBytes, "manifest");
+  const envelope = parseObject(envelopeBytes, "envelope");
+  assertReleaseManifest(manifest, input);
+  assertReleaseEnvelope(envelope, manifest, manifestBytes.byteLength, input);
+  const snapshotRoot = input.snapshotRoot ?? "/private/tmp";
+  if (!isAbsolute3(snapshotRoot)) {
+    throw new Error("release snapshot root must be absolute");
+  }
+  const snapshotDirectory = mkdtempSync(join6(snapshotRoot, "recordings-release-install."));
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned)
+      return;
+    cleaned = true;
+    try {
+      chmodSync2(snapshotDirectory, 448);
+    } catch {}
+    rmSync2(snapshotDirectory, { recursive: true, force: true });
+  };
+  try {
+    const manifestSnapshot = join6(snapshotDirectory, `${input.manifestSha256}.manifest.json`);
+    const envelopeDigest = createHash2("sha256").update(envelopeBytes).digest("hex");
+    const envelopeSnapshot = join6(snapshotDirectory, `${envelopeDigest}.envelope.json`);
+    writeSnapshot(manifestSnapshot, manifestBytes);
+    writeSnapshot(envelopeSnapshot, envelopeBytes);
+    chmodSync2(snapshotDirectory, 320);
+    return { manifestPath: manifestSnapshot, envelopePath: envelopeSnapshot, cleanup };
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+function assertAbsolutePath(value, label) {
+  if (!isAbsolute3(value))
+    throw new Error(`${label} path must be absolute`);
+}
+function readBoundedRegularFile(path, label, maximum) {
+  const descriptor = openSync(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);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+function parseObject(bytes, label) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error(`${label} is not valid JSON`);
+  }
+  if (!isObject(parsed))
+    throw new Error(`${label} must be a JSON object`);
+  return parsed;
+}
+function assertReleaseManifest(manifest, input) {
+  if (manifest.schema_version !== 4 || manifest.artifact_type !== "recordings-macos-app" || manifest.bundle_id !== "com.hasna.recordings") {
+    throw new Error("manifest is not a schema-v4 Recordings release artifact");
+  }
+  if (manifest.git_sha !== input.expectedSourceSha) {
+    throw new Error("manifest source SHA does not match the operator-approved source");
+  }
+  if (manifest.bundle_version !== input.expectedVersion) {
+    throw new Error("manifest version does not match the operator-approved version");
+  }
+  const signing = objectField(manifest, "signing", "manifest");
+  if (manifest.team_id !== input.expectedTeamId || signing.team_id !== input.expectedTeamId || signing.helper_team_id !== input.expectedTeamId) {
+    throw new Error("manifest Team ID does not match the operator-approved Team ID");
+  }
+  for (const localOnlyField of [
+    "artifact_policy",
+    "approved_target",
+    "approved_target_identity_kind",
+    "approved_target_identity_sha256",
+    "builder_identity_kind",
+    "builder_identity_sha256",
+    "non_notarized"
+  ]) {
+    if (Object.hasOwn(manifest, localOnlyField)) {
+      throw new Error("release manifest contains local-only policy fields");
+    }
+  }
+}
+function assertReleaseEnvelope(envelope, manifest, manifestByteCount, input) {
+  const payload = objectField(envelope, "payload", "envelope");
+  if (payload.purpose !== "update") {
+    throw new Error("release app install requires an update envelope");
+  }
+  if (payload.manifest_sha256 !== input.manifestSha256 || payload.manifest_byte_count !== manifestByteCount) {
+    throw new Error("release envelope does not bind the authenticated manifest snapshot");
+  }
+  if (payload.source_commit !== input.expectedSourceSha || payload.version !== input.expectedVersion || payload.signing_team_identifier !== input.expectedTeamId) {
+    throw new Error("release envelope does not match the operator-approved provenance");
+  }
+  const archive = objectField(manifest, "archive", "manifest");
+  const binding = objectField(manifest, "binding", "manifest");
+  if (payload.build !== manifest.bundle_build_version || !LOWER_SHA256.test(stringField(archive, "sha256", "manifest archive")) || payload.artifact_sha256 !== archive.sha256 || !LOWER_SHA256.test(stringField(binding, "bundle_tree_sha256", "manifest binding")) || payload.candidate_tree_sha256 !== binding.bundle_tree_sha256) {
+    throw new Error("release envelope and manifest artifact provenance differ");
+  }
+  const signature = stringField(envelope, "signature", "envelope");
+  if (!/^[A-Za-z0-9+/]{86}==$/.test(signature)) {
+    throw new Error("release envelope signature encoding is invalid");
+  }
+}
+function objectField(value, key, label) {
+  const field = value[key];
+  if (!isObject(field))
+    throw new Error(`${label} is missing ${key}`);
+  return field;
+}
+function stringField(value, key, label) {
+  const field = value[key];
+  if (typeof field !== "string")
+    throw new Error(`${label} is missing ${key}`);
+  return field;
+}
+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);
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
 // src/cli/index.ts
 var program = new Command;
 program.name("recordings").description("Speech-to-text recording tool \u2014 record, transcribe, and enhance with AI").version(VERSION).option("--json", "Output as JSON").option("--agent <name>", "Agent name or ID").option("--project <name>", "Project name or ID").option("--session <id>", "Session ID");
 registerEventsCommands(program, { source: "recordings" });
-program.command("record").description("Record from microphone, transcribe, and optionally enhance").option("-d, --duration <seconds>", "Record for specific duration").option("--no-enhance", "Skip AI enhancement").option("-t, --tags <tags>", "Comma-separated tags").option("-l, --language <lang>", "Language code (e.g. en, es, fr)").action(async (opts) => {
+var DEFAULT_LIST_LIMIT = 20;
+var MAX_HUMAN_LIST_LIMIT = 50;
+var DEFAULT_LOG_LINES = 40;
+program.command("record").description("Record from microphone, transcribe, and optionally enhance").option("-d, --duration <seconds>", "Record for specific duration").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("-t, --tags <tags>", "Comma-separated tags").option("-l, --language <lang>", "Language code (e.g. en, es, fr)").action(async (opts) => {
   const config = loadConfig();
   ensureDataDir(config);
+  const parentOpts = program.opts();
   if (opts.language)
     config.language = opts.language;
+  if (opts.prompt !== undefined)
+    config.transcription_prompt = opts.prompt;
   applyEnhancementOptions(config, opts);
   const deps = await checkRecordingDeps();
   if (!deps.available) {
@@ -2441,39 +3318,50 @@ program.command("record").description("Record from microphone, transcribe, and o
   let audioPath;
   if (opts.duration) {
     const seconds = parseInt(opts.duration, 10);
-    console.log(chalk.blue(`Recording for ${seconds} seconds...`));
+    if (!parentOpts.json) {
+      console.log(chalk.blue(`Recording for ${seconds} seconds...`));
+    }
     audioPath = await recordDuration(seconds, config);
-    console.log(chalk.green("Recording complete."));
+    if (!parentOpts.json) {
+      console.log(chalk.green("Recording complete."));
+    }
   } else {
-    console.log(chalk.blue("Recording... Press") + chalk.yellow(" Enter ") + chalk.blue("to stop."));
+    if (!parentOpts.json) {
+      console.log(chalk.blue("Recording... Press") + chalk.yellow(" Enter ") + chalk.blue("to stop."));
+    }
     audioPath = startRecording(config);
-    await new Promise((resolve2) => {
+    await new Promise((resolve3) => {
       process.stdin.setRawMode?.(true);
       process.stdin.resume();
       process.stdin.once("data", () => {
         process.stdin.setRawMode?.(false);
         process.stdin.pause();
-        resolve2();
+        resolve3();
       });
     });
     stopRecording();
-    console.log(chalk.green("Recording stopped."));
+    if (!parentOpts.json) {
+      console.log(chalk.green("Recording stopped."));
+    }
+  }
+  if (!parentOpts.json) {
+    console.log(chalk.blue("Transcribing..."));
   }
-  console.log(chalk.blue("Transcribing..."));
   const transcription = await transcribeAudio(audioPath, config);
-  console.log(chalk.dim(`Raw: ${transcription.text}`));
+  if (!parentOpts.json) {
+    console.log(chalk.dim(`Raw: ${transcription.text}`));
+  }
   const processed = await processText(transcription.text, config);
-  if (processed.mode === "enhanced") {
+  if (!parentOpts.json && processed.mode === "enhanced") {
     console.log(chalk.green(`
 Enhanced output:`));
     console.log(processed.text);
-  } else {
+  } else if (!parentOpts.json) {
     console.log(chalk.green(`
 Output:`));
     console.log(transcription.text);
   }
   const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : [];
-  const parentOpts = program.opts();
   const recording = await getStore().createRecording({
     audio_path: audioPath,
     raw_text: transcription.text,
@@ -2486,7 +3374,12 @@ Output:`));
     tags,
     agent_id: parentOpts.agent || undefined,
     project_id: parentOpts.project || undefined,
-    session_id: parentOpts.session || undefined
+    session_id: parentOpts.session || undefined,
+    machine_id: currentMachineId(),
+    metadata: buildTranscriptionMetadata(config, processed, {
+      transcriptionPromptFromRequest: opts.prompt !== undefined,
+      transcriberPromptFromRequest: opts.transcriberPrompt !== undefined || opts.systemPrompt !== undefined
+    })
   });
   if (parentOpts.json) {
     console.log(JSON.stringify(recording, null, 2));
@@ -2495,25 +3388,33 @@ Output:`));
 Saved as ${recording.id.slice(0, 8)}`));
   }
 });
-program.command("transcribe <file>").description("Transcribe an existing audio file").option("--no-enhance", "Skip AI enhancement").option("--stream", "Stream transcription deltas while the file is processed").option("-t, --tags <tags>", "Comma-separated tags").option("--prompt <prompt>", "Vocabulary/context prompt for transcription").option("--system-prompt <prompt>", "System prompt for enhancement context").action(async (file, opts) => {
+program.command("transcribe <file>").description("Transcribe an existing audio file").option("--no-enhance", "Skip AI enhancement").option("--stream", "Stream transcription deltas while the file is processed").option("-t, --tags <tags>", "Comma-separated tags").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("--post-processing <mode>", "Post-processing mode: off, auto, or always").option("--transcription-model <model>", "Model for bounded audio transcription").option("--transcriber-model <model>", "Model for post-transcription cleanup").option("--enhancement-model <model>", "Enhancement model fallback").option("--enhance-triggers-json <json>", "Frozen JSON string array of enhancement triggers").option("--keyword-transforms-json <json>", "Frozen JSON string map of keyword transforms").option("-l, --language <lang>", "Language code (e.g. en, es, fr)").option("--recording-id <id>", "Stable recording ID for idempotent retries").action(async (file, opts) => {
+  const recordingId = recordingCreateIdentity({
+    id: opts.recordingId,
+    raw_text: ""
+  }).input.id;
   const config = loadConfig();
   ensureDataDir(config);
+  if (opts.language)
+    config.language = opts.language;
+  if (opts.prompt !== undefined)
+    config.transcription_prompt = opts.prompt;
   applyEnhancementOptions(config, opts);
   const parentOpts = program.opts();
   if (!parentOpts.json) {
     console.log(chalk.blue("Transcribing..."));
   }
   const transcription = opts.stream ? await transcribeAudioStream(file, config, {
-    prompt: opts.prompt,
     onDelta: parentOpts.json ? undefined : (delta) => process.stdout.write(delta)
-  }) : await transcribeAudio(file, config, { prompt: opts.prompt });
+  }) : await transcribeAudio(file, config);
   if (opts.stream && !parentOpts.json) {
     process.stdout.write(`
 `);
   }
-  const processed = await processText(transcription.text, config, opts.systemPrompt);
+  const processed = await processText(transcription.text, config);
   const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : [];
   const recording = await getStore().createRecording({
+    id: recordingId,
     audio_path: file,
     raw_text: transcription.text,
     processed_text: processed.mode === "enhanced" ? processed.text : undefined,
@@ -2525,23 +3426,83 @@ program.command("transcribe <file>").description("Transcribe an existing audio f
     tags,
     agent_id: parentOpts.agent || undefined,
     project_id: parentOpts.project || undefined,
-    session_id: parentOpts.session || undefined
-  });
-  if (processed.mode === "enhanced") {
+    session_id: parentOpts.session || undefined,
+    machine_id: currentMachineId(),
+    metadata: buildTranscriptionMetadata(config, processed, {
+      transcriptionPromptFromRequest: opts.prompt !== undefined,
+      transcriberPromptFromRequest: opts.transcriberPrompt !== undefined || opts.systemPrompt !== undefined
+    })
+  }, recordingId);
+  if (parentOpts.json) {
+    console.log(JSON.stringify(recording, null, 2));
+  } else if (processed.mode === "enhanced") {
     console.log(chalk.green("Enhanced:"));
     console.log(processed.text);
   } else {
     console.log(chalk.green("Transcription:"));
     console.log(transcription.text);
   }
+  if (!parentOpts.json) {
+    console.log(chalk.dim(`Saved as ${recording.id.slice(0, 8)}`));
+  }
+});
+program.command("save-text [text]").description("Save already-transcribed text as a recording").option("--text-file <path>", "Read transcript text from a UTF-8 file").option("--stdin", "Read transcript text from stdin").option("--audio-path <path>", "Audio file path associated with this transcript").option("--model-used <model>", "Model/source used to produce the raw transcript").option("--source <source>", "Transcript source label for metadata", "direct_text").option("--duration-ms <ms>", "Recording duration in milliseconds").option("-l, --language <lang>", "Language code").option("-t, --tags <tags>", "Comma-separated tags").option("--no-enhance", "Skip AI enhancement").option("--post-processing <mode>", "Post-processing mode: off, auto, or always").option("--transcriber-prompt <prompt>", "Instructions for post-transcription cleanup").option("--system-prompt <prompt>", "Alias for --transcriber-prompt").option("--transcription-model <model>", "Model for bounded audio transcription").option("--transcriber-model <model>", "Model for post-transcription cleanup").option("--enhancement-model <model>", "Enhancement model fallback").option("--enhance-triggers-json <json>", "Frozen JSON string array of enhancement triggers").option("--keyword-transforms-json <json>", "Frozen JSON string map of keyword transforms").option("--recording-id <id>", "Stable recording ID for idempotent retries").action(async (text, opts) => {
+  const recordingId = recordingCreateIdentity({
+    id: opts.recordingId,
+    raw_text: ""
+  }).input.id;
+  const rawText = await readSaveTextInput(text, opts);
+  const config = loadConfig();
+  ensureDataDir(config);
+  if (opts.language)
+    config.language = opts.language;
+  applyEnhancementOptions(config, opts);
+  const processed = await processText(rawText, config);
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : [];
+  const parentOpts = program.opts();
+  const metadata = {
+    ...buildTranscriptionMetadata(config, processed, {
+      transcriberPromptFromRequest: opts.transcriberPrompt !== undefined || opts.systemPrompt !== undefined
+    }),
+    transcription_source: opts.source || "direct_text",
+    realtime: {
+      fast_path: opts.source === "realtime_fast_path",
+      model: opts.modelUsed || config.realtime_transcription_model || "direct-input",
+      bounded_fallback: false
+    }
+  };
+  const recording = await getStore().createRecording({
+    id: recordingId,
+    audio_path: opts.audioPath || undefined,
+    raw_text: rawText,
+    processed_text: processed.mode === "enhanced" ? processed.text : undefined,
+    processing_mode: processed.mode,
+    model_used: opts.modelUsed || "direct-input",
+    enhancement_model: processed.enhancement_model || undefined,
+    duration_ms: opts.durationMs ? parseInt(opts.durationMs, 10) : 0,
+    language: opts.language || undefined,
+    tags,
+    agent_id: parentOpts.agent || undefined,
+    project_id: parentOpts.project || undefined,
+    session_id: parentOpts.session || undefined,
+    machine_id: currentMachineId(),
+    metadata
+  }, recordingId);
   if (parentOpts.json) {
     console.log(JSON.stringify(recording, null, 2));
+  } else if (processed.mode === "enhanced") {
+    console.log(processed.text);
   } else {
-    console.log(chalk.dim(`Saved as ${recording.id.slice(0, 8)}`));
+    console.log(rawText);
   }
 });
-program.command("rewrite <text>").description("Rewrite provided text using an instruction").requiredOption("-i, --instruction <instruction>", "Rewrite instruction").action(async (text, opts) => {
+program.command("rewrite <text>").description("Rewrite provided text using an instruction").requiredOption("-i, --instruction <instruction>", "Rewrite instruction").option("--prompt <prompt>", "Frozen transcription vocabulary/context prompt").option("--transcriber-prompt <prompt>", "Frozen post-transcription instructions").option("--system-prompt <prompt>", "Alias for --transcriber-prompt").option("--post-processing <mode>", "Frozen post-processing mode").option("--language <lang>", "Frozen transcription language").option("--transcription-model <model>", "Frozen transcription model").option("--transcriber-model <model>", "Frozen rewrite model").option("--enhancement-model <model>", "Frozen enhancement fallback model").option("--enhance-triggers-json <json>", "Frozen JSON string array of enhancement triggers").option("--keyword-transforms-json <json>", "Frozen JSON string map of keyword transforms").action(async (text, opts) => {
   const config = loadConfig();
+  if (opts.language !== undefined)
+    config.language = opts.language;
+  if (opts.prompt !== undefined)
+    config.transcription_prompt = opts.prompt;
+  applyEnhancementOptions(config, opts);
   const parentOpts = program.opts();
   const instruction = `Instruction: ${opts.instruction}
 
@@ -2589,7 +3550,8 @@ program.command("save <text>").description("Save raw text as a recording (no aud
       tags,
       agent_id: parentOpts.agent,
       project_id: parentOpts.project,
-      session_id: parentOpts.session
+      session_id: parentOpts.session,
+      machine_id: currentMachineId()
     });
     if (parentOpts.json) {
       console.log(JSON.stringify(recording, null, 2));
@@ -2602,65 +3564,67 @@ program.command("save <text>").description("Save raw text as a recording (no aud
     process.exit(1);
   }
 });
-program.command("list").description("List recordings").option("-n, --limit <n>", "Max results", "20").option("--mode <mode>", "Filter by mode: raw or enhanced").option("-t, --tags <tags>", "Filter by tags").option("--since <date>", "After date (ISO)").option("--until <date>", "Before date (ISO)").action(async (opts) => {
+program.command("list").description("List recordings in compact form").option("-n, --limit <n>", "Max results", "20").option("--offset <n>", "Skip this many results").option("--cursor <n>", "Pagination cursor alias for --offset").option("--mode <mode>", "Filter by mode: raw or enhanced").option("-t, --tags <tags>", "Filter by tags").option("--since <date>", "After date (ISO)").option("--until <date>", "Before date (ISO)").option("--verbose", "Show more metadata per row without dumping full text").action(async (opts) => {
   const parentOpts = program.opts();
-  const recordings = await getStore().listRecordings({
-    limit: parseInt(opts.limit, 10),
+  const pagination = resolvePagination(opts, parentOpts);
+  const filter = {
+    limit: pagination.limit,
     processing_mode: opts.mode,
-    tags: opts.tags ? opts.tags.split(",") : undefined,
+    tags: parseCsvList(opts.tags),
     since: opts.since,
     until: opts.until,
+    offset: pagination.offset,
     agent_id: parentOpts.agent,
     project_id: parentOpts.project,
     session_id: parentOpts.session
-  });
+  };
+  const store = getStore();
+  const recordings = await store.listRecordings(filter);
   if (parentOpts.json) {
     console.log(JSON.stringify(recordings, null, 2));
     return;
   }
-  if (recordings.length === 0) {
-    console.log(chalk.dim("No recordings found."));
-    return;
-  }
-  console.log(chalk.bold(`${recordings.length} recording(s):
-`));
-  for (const r of recordings) {
-    console.log(formatRecordingLine(r));
-  }
-});
-program.command("show <id>").description("Show recording details").action(async (id) => {
-  const parentOpts = program.opts();
-  const recording = await getStore().getRecording(id);
-  if (!recording) {
-    console.error(chalk.red(`Recording not found: ${id}`));
-    process.exit(1);
-  }
-  if (parentOpts.json) {
-    console.log(JSON.stringify(recording, null, 2));
-    return;
-  }
-  console.log(formatRecordingDetail(recording));
+  const total = await countStoreRecordings(store, withoutPagination(filter));
+  printRecordingCollection("recordings", recordings, {
+    total,
+    offset: pagination.offset,
+    limit: pagination.limit,
+    verbose: Boolean(opts.verbose),
+    capped: pagination.capped,
+    empty: "No recordings found."
+  });
 });
-program.command("search <query>").description("Search recordings by text content").option("-n, --limit <n>", "Max results", "20").action(async (query, opts) => {
+program.command("show <id>").description("Show recording details").action((id) => printRecordingDetail(id));
+program.command("inspect <id>").description("Inspect recording details (alias for show)").action((id) => printRecordingDetail(id));
+program.command("search <query>").description("Search recordings by text content in compact form").option("-n, --limit <n>", "Max results", "20").option("--offset <n>", "Skip this many results").option("--cursor <n>", "Pagination cursor alias for --offset").option("--mode <mode>", "Filter by mode: raw or enhanced").option("-t, --tags <tags>", "Filter by tags").option("--since <date>", "After date (ISO)").option("--until <date>", "Before date (ISO)").option("--session <id>", "Filter by session ID").option("--verbose", "Show more metadata per row without dumping full text").action(async (query, opts) => {
   const parentOpts = program.opts();
-  const results = await getStore().searchRecordings(query, {
-    limit: parseInt(opts.limit, 10),
+  const pagination = resolvePagination(opts, parentOpts);
+  const filter = {
+    limit: pagination.limit,
+    offset: pagination.offset,
+    processing_mode: opts.mode,
+    tags: parseCsvList(opts.tags),
+    since: opts.since,
+    until: opts.until,
     agent_id: parentOpts.agent,
-    project_id: parentOpts.project
-  });
+    project_id: parentOpts.project,
+    session_id: opts.session || parentOpts.session
+  };
+  const store = getStore();
+  const results = await store.searchRecordings(query, filter);
   if (parentOpts.json) {
     console.log(JSON.stringify(results, null, 2));
     return;
   }
-  if (results.length === 0) {
-    console.log(chalk.dim("No results."));
-    return;
-  }
-  console.log(chalk.bold(`${results.length} result(s):
-`));
-  for (const r of results) {
-    console.log(formatRecordingLine(r));
-  }
+  const total = await countStoreRecordings(store, withoutPagination({ ...filter, search: query }));
+  printRecordingCollection("results", results, {
+    total,
+    offset: pagination.offset,
+    limit: pagination.limit,
+    verbose: Boolean(opts.verbose),
+    capped: pagination.capped,
+    empty: "No results."
+  });
 });
 program.command("delete <id>").description("Delete a recording").action(async (id) => {
   const deleted = await getStore().deleteRecording(id);
@@ -2684,74 +3648,260 @@ program.command("stats").description("Show recording statistics").action(async (
   console.log(`  Raw:        ${stats.raw}`);
   console.log(`  Enhanced:   ${stats.enhanced}`);
   console.log(`  Duration:   ${(stats.total_duration_ms / 1000).toFixed(1)}s`);
-  if (Object.keys(stats.by_model).length > 0) {
+  const modelEntries = Object.entries(stats.by_model).sort((a, b) => b[1] - a[1]);
+  if (modelEntries.length > 0) {
     console.log(`  By model:`);
-    for (const [model, count] of Object.entries(stats.by_model)) {
-      console.log(`    ${model}: ${count}`);
+    for (const [model, count] of modelEntries.slice(0, 10)) {
+      console.log(`    ${truncateText(model, 80)}: ${count}`);
+    }
+    if (modelEntries.length > 10) {
+      console.log(chalk.dim(`    ...${modelEntries.length - 10} more model(s). Use --json for the full breakdown.`));
     }
   }
 });
-program.command("agents").description("List registered agents").action(async () => {
+program.command("agents").description("List registered agents").option("-n, --limit <n>", "Max results").option("--offset <n>", "Skip this many results").option("--cursor <n>", "Pagination cursor alias for --offset").option("--verbose", "Show descriptions and timestamps").action(async (opts) => {
   const parentOpts = program.opts();
+  const pagination = resolvePagination(opts, parentOpts);
   const agents = await getStore().listAgents();
+  const page = parentOpts.json ? maybePageJson(agents, pagination, opts) : pageItems(agents, pagination);
   if (parentOpts.json) {
-    console.log(JSON.stringify(agents, null, 2));
+    console.log(JSON.stringify(page, null, 2));
     return;
   }
-  if (agents.length === 0) {
-    console.log(chalk.dim("No agents registered."));
+  if (page.length === 0) {
+    console.log(chalk.dim(agents.length === 0 ? "No agents registered." : "No agents at this cursor."));
+    if (agents.length > 0)
+      console.log(chalk.dim("Try a lower --cursor."));
     return;
   }
-  for (const a of agents) {
-    console.log(`${chalk.cyan(a.id)} ${chalk.bold(a.name)} (${a.role}) \u2014 last seen ${a.last_seen_at}`);
+  console.log(formatPageHeader("agents", page.length, agents.length, pagination.offset, pagination.limit));
+  for (const a of page) {
+    const line = `${chalk.cyan(truncateText(a.id, 80))} ${chalk.bold(truncateText(a.name, 80))} (${truncateText(a.role, 40)})`;
+    if (opts.verbose) {
+      console.log(`${line}
+  last seen: ${truncateText(a.last_seen_at, 40)}${a.description ? `
+  ${truncateText(a.description, 140)}` : ""}`);
+    } else {
+      console.log(`${line} \u2014 ${truncateText(relativeHint(a.last_seen_at), 40)}`);
+    }
   }
+  printPaginationHints(page.length, agents.length, pagination);
 });
-program.command("projects").description("List registered projects").action(async () => {
+var projectCommand = program.command("project").description("Manage registered projects");
+projectCommand.command("register").description("Register a project in the active Store").requiredOption("--name <name>", "Project name").requiredOption("--path <path>", "Stable project path or URI").option("--description <description>", "Project description").action(async (opts) => {
   const parentOpts = program.opts();
+  const project = await getStore().registerProject(opts.name, opts.path, opts.description);
+  if (parentOpts.json) {
+    console.log(JSON.stringify(project, null, 2));
+    return;
+  }
+  console.log(`${chalk.cyan(truncateText(project.id, 80))} ${chalk.bold(truncateText(project.name, 80))} \u2014 ${truncatePath(project.path, 120)}`);
+});
+program.command("projects").description("List registered projects").option("-n, --limit <n>", "Max results").option("--offset <n>", "Skip this many results").option("--cursor <n>", "Pagination cursor alias for --offset").option("--verbose", "Show descriptions and timestamps").action(async (opts) => {
+  const parentOpts = program.opts();
+  const pagination = resolvePagination(opts, parentOpts);
   const projects = await getStore().listProjects();
+  const page = parentOpts.json ? maybePageJson(projects, pagination, opts) : pageItems(projects, pagination);
   if (parentOpts.json) {
-    console.log(JSON.stringify(projects, null, 2));
+    console.log(JSON.stringify(page, null, 2));
     return;
   }
-  if (projects.length === 0) {
-    console.log(chalk.dim("No projects registered."));
+  if (page.length === 0) {
+    console.log(chalk.dim(projects.length === 0 ? "No projects registered." : "No projects at this cursor."));
+    if (projects.length > 0)
+      console.log(chalk.dim("Try a lower --cursor."));
     return;
   }
-  for (const p of projects) {
-    console.log(`${chalk.cyan(p.id.slice(0, 8))} ${chalk.bold(p.name)} \u2014 ${p.path}`);
+  console.log(formatPageHeader("projects", page.length, projects.length, pagination.offset, pagination.limit));
+  for (const p of page) {
+    const line = `${chalk.cyan(truncateText(p.id, 8))} ${chalk.bold(truncateText(p.name, 80))}`;
+    if (opts.verbose) {
+      console.log(`${line}
+  path: ${truncatePath(p.path, 120)}
+  updated: ${truncateText(p.updated_at, 40)}${p.description ? `
+  ${truncateText(p.description, 140)}` : ""}`);
+    } else {
+      console.log(`${line} \u2014 ${truncatePath(p.path, 96)}`);
+    }
   }
+  printPaginationHints(page.length, projects.length, pagination);
 });
 program.command("init").description("Initialize .recordings/ in current directory").action(() => {
-  const { mkdirSync: mkdirSync3, writeFileSync, existsSync: existsSync5 } = __require("fs");
-  const { join: join4 } = __require("path");
-  const dir = join4(process.cwd(), ".recordings");
-  const audioDir = join4(dir, "audio");
-  const configFile = join4(dir, "config.json");
-  mkdirSync3(audioDir, { recursive: true });
+  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 defaultConf = {
       transcription_model: "gpt-4o-transcribe",
+      realtime_session_model: "gpt-realtime",
+      realtime_transcription_model: "gpt-realtime-whisper",
       enhancement_model: "gpt-4o",
+      transcriber_model: "gpt-4o",
       language: "en",
+      transcription_prompt: "",
+      transcriber_prompt: "",
+      post_processing_mode: "auto",
       auto_enhance: true
     };
-    writeFileSync(configFile, JSON.stringify(defaultConf, null, 2));
+    writeFileSync3(configFile, JSON.stringify(defaultConf, null, 2));
   }
   console.log(chalk.green("Initialized .recordings/ directory"));
   console.log(chalk.dim("  config: .recordings/config.json"));
   console.log(chalk.dim("  audio:  .recordings/audio/"));
   console.log(chalk.dim("  db:     .recordings/recordings.db"));
 });
-var appCommand = program.command("app").description("Manage the macOS menu bar app installed from this package");
-appCommand.command("install").description("Build and install Recordings.app from the installed package").option("--mode <mode>", "Swift build mode: debug or release", "release").action((opts) => {
-  const status = getMacOSAppStatus();
-  if (!status.installer_available) {
-    console.error(chalk.red(`App installer missing from package: ${status.installer_path}`));
+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) => {
+  if (process.platform !== "darwin") {
+    console.error(chalk.red("Recordings.app installation is only supported on macOS"));
+    process.exit(1);
+  }
+  if (opts.artifactPolicy === "release") {
+    if (!opts.envelope) {
+      console.error(chalk.red("Release installation requires --envelope."));
+      process.exit(1);
+    }
+    let preparedInputs;
+    try {
+      assertReleaseOnlyOptions(opts);
+      if (opts.expectedHostname) {
+        const hostnameResult = spawnSync4("/bin/hostname", ["-s"], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          env: {
+            PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+            LC_ALL: "C",
+            LANG: "C",
+            TZ: "UTC0"
+          }
+        });
+        if (hostnameResult.error || hostnameResult.status !== 0) {
+          throw new Error("could not determine the install target hostname");
+        }
+        assertExpectedReleaseHostname(opts.expectedHostname, hostnameResult.stdout.trim());
+      }
+      preparedInputs = prepareReleaseInstallInputs({
+        artifactPath: opts.artifact,
+        manifestPath: opts.manifest,
+        envelopePath: opts.envelope,
+        manifestSha256: opts.manifestSha256,
+        expectedSourceSha: opts.expectedSourceSha,
+        expectedVersion: opts.expectedVersion,
+        expectedTeamId: opts.expectedTeamId
+      });
+    } catch (error) {
+      console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+      process.exit(1);
+    }
+    const updateClientPath = "/Applications/Recordings.app/Contents/Helpers/recordings-update-client";
+    if (!existsSync4(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, [
+          "install",
+          "--artifact",
+          opts.artifact,
+          "--manifest",
+          preparedInputs.manifestPath,
+          "--envelope",
+          preparedInputs.envelopePath
+        ], {
+          stdio: "inherit",
+          env: {
+            HOME: process.env.HOME ?? "",
+            PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+            LC_ALL: "C",
+            LANG: "C",
+            TZ: "UTC0"
+          }
+        });
+      } finally {
+        preparedInputs.cleanup();
+      }
+    })();
+    if (result2.error) {
+      console.error(chalk.red(result2.error.message));
+      process.exit(1);
+    }
+    process.exit(result2.status ?? 1);
+  }
+  if (opts.artifactPolicy !== "local-only" && opts.artifactPolicy !== "local_only") {
+    console.error(chalk.red("Artifact policy must be release or local-only."));
+    process.exit(1);
+  }
+  let launchTimeout;
+  try {
+    launchTimeout = parseLaunchTimeout(opts.launchTimeout);
+  } catch (error) {
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    process.exit(1);
+  }
+  let bunExecutable;
+  try {
+    bunExecutable = resolveInstallBunExecutable(process.env);
+  } catch (error) {
+    console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+    process.exit(1);
+  }
+  const installerPath = getMacOSInstallerPath();
+  if (!existsSync4(installerPath)) {
+    console.error(chalk.red(`App installer missing from package: ${installerPath}`));
     process.exit(1);
   }
-  const result = spawnSync("bash", [status.installer_path, "--mode", opts.mode], {
+  const installerArgs = [
+    installerPath,
+    "--artifact",
+    opts.artifact,
+    "--manifest",
+    opts.manifest,
+    "--manifest-sha256",
+    opts.manifestSha256,
+    "--expected-source-sha",
+    opts.expectedSourceSha,
+    "--expected-version",
+    opts.expectedVersion,
+    "--artifact-policy",
+    opts.artifactPolicy,
+    "--approved-target",
+    opts.approvedTarget,
+    "--launch-timeout",
+    launchTimeout
+  ];
+  if (opts.expectedHostname) {
+    installerArgs.push("--expected-hostname", opts.expectedHostname);
+  }
+  if (opts.approvedTargetIdentityKind) {
+    installerArgs.push("--approved-target-identity-kind", opts.approvedTargetIdentityKind);
+  }
+  installerArgs.push("--approved-target-identity-sha256", opts.approvedTargetIdentitySha256);
+  if (opts.expectedTeamId) {
+    installerArgs.push("--expected-team-id", opts.expectedTeamId);
+  }
+  if (opts.acknowledgeLocalSigningAndPermissions) {
+    installerArgs.push("--acknowledge-local-signing-and-permissions");
+  }
+  if (opts.allowSigningIdentityMigration) {
+    installerArgs.push("--allow-signing-identity-migration");
+  }
+  if (opts.expectedOldIdentitySha256) {
+    installerArgs.push("--expected-old-identity-sha256", opts.expectedOldIdentitySha256);
+  }
+  if (opts.expectedNewIdentitySha256) {
+    installerArgs.push("--expected-new-identity-sha256", opts.expectedNewIdentitySha256);
+  }
+  if (opts.launch)
+    installerArgs.push("--launch");
+  const installerEnvironment = createInstallerEnvironment(process.env, bunExecutable);
+  const result = spawnSync4("/bin/bash", installerArgs, {
     stdio: "inherit",
-    env: process.env
+    env: installerEnvironment
   });
   if (result.error) {
     console.error(chalk.red(result.error.message));
@@ -2759,22 +3909,36 @@ appCommand.command("install").description("Build and install Recordings.app from
   }
   process.exit(result.status ?? 1);
 });
-appCommand.command("status").description("Show installed Recordings.app status").action(() => {
+appCommand.command("status").description("Show installed Recordings.app status").option("--verbose", "Show package paths, code hash, and log path").action((opts) => {
   const status = getMacOSAppStatus();
   if (program.opts().json) {
     console.log(JSON.stringify(status, null, 2));
     return;
   }
-  console.log(`Package: ${status.package_root}`);
+  console.log(chalk.bold("Recordings.app"));
+  console.log(`Installed: ${status.installed ? "yes" : "no"}`);
+  console.log(`Executable: ${status.executable ? "available" : "missing"}`);
   console.log(`Installer: ${status.installer_available ? "available" : "missing"}`);
   console.log(`Native sources: ${status.native_sources_available ? "available" : "missing"}`);
-  console.log(`Installed app: ${status.installed ? status.installed_app_path : "missing"}`);
-  console.log(`Executable: ${status.executable ? "available" : "missing"}`);
-  console.log(`Code hash: ${status.app_code_hash ?? "unavailable"}`);
+  console.log(`Legacy duplicates: ${status.legacy_install_paths.length}`);
   if (process.platform === "darwin") {
     console.log(`Microphone: ${status.microphone_permission}`);
     console.log(`Accessibility: ${status.accessibility_permission}`);
+  }
+  if (opts.verbose) {
+    console.log(`Package: ${status.package_root}`);
+    console.log(`Installed app: ${status.installed ? status.installed_app_path : "missing"}`);
+    console.log(`Executable path: ${status.executable_path}`);
+    for (const legacyPath of status.legacy_install_paths) {
+      console.log(`Legacy app: ${legacyPath}`);
+    }
+    console.log(`Signing identifier: ${status.signing_identifier ?? "unavailable"}`);
+    console.log(`Team identifier: ${status.team_identifier ?? "unavailable"}`);
+    console.log(`Designated requirement: ${status.designated_requirement ?? "unavailable"}`);
+    console.log(`Code hash: ${status.app_code_hash ?? "unavailable"}`);
     console.log(`Log: ${status.log_path}`);
+  } else {
+    console.log(chalk.dim("Use --verbose for paths/code hash/log, or --json for the full status object."));
   }
 });
 appCommand.command("permissions").description("Show macOS permission state for Recordings.app").action(() => {
@@ -2782,10 +3946,15 @@ appCommand.command("permissions").description("Show macOS permission state for R
   const permissions = {
     platform: status.platform,
     bundle_id: "com.hasna.recordings",
+    installed_app_path: status.installed_app_path,
+    legacy_install_paths: status.legacy_install_paths,
     microphone: status.microphone_permission,
     accessibility: status.accessibility_permission,
     app_code_hash: status.app_code_hash,
     ad_hoc_signed: status.ad_hoc_signed,
+    signing_identifier: status.signing_identifier,
+    team_identifier: status.team_identifier,
+    designated_requirement: status.designated_requirement,
     log_path: status.log_path
   };
   if (program.opts().json) {
@@ -2816,27 +3985,20 @@ appCommand.command("request-permissions").description("Open Recordings.app and t
   if (opts.reset) {
     resetMacOSPermissions();
   }
-  const result = spawnSync("open", [
-    "-n",
-    status.installed_app_path,
-    "--args",
-    "--request-permissions",
-    "--open-permission-settings"
-  ], { stdio: "inherit" });
-  if (result.error) {
-    console.error(chalk.red(result.error.message));
-    process.exit(1);
+  const result = runMacOSPermissionRequest(status.installed_app_path);
+  if (result.errorMessage) {
+    console.error(chalk.red(result.errorMessage));
   }
-  process.exit(result.status ?? 1);
+  process.exit(result.exitCode);
 });
-appCommand.command("log").description("Show the Recordings.app diagnostic log").option("-n, --lines <lines>", "Number of lines to print", "120").action((opts) => {
+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)) {
     console.log("");
     return;
   }
-  const lines = Math.max(1, parseInt(opts.lines, 10) || 120);
-  const result = spawnSync("tail", ["-n", String(lines), status.log_path], {
+  const lines = Math.max(1, parseInt(opts.lines, 10) || DEFAULT_LOG_LINES);
+  const result = spawnSync4("tail", ["-n", String(lines), status.log_path], {
     encoding: "utf8"
   });
   if (result.error) {
@@ -2857,7 +4019,7 @@ 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 = spawnSync("open", [status.installed_app_path], { stdio: "inherit" });
+  const result = spawnSync4("open", [status.installed_app_path], { stdio: "inherit" });
   if (result.error) {
     console.error(chalk.red(result.error.message));
     process.exit(1);
@@ -2878,7 +4040,14 @@ 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
+      enhancement_model: config.enhancement_model,
+      transcriber_model: resolveTranscriberModel(config),
+      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 ?? []
     }, null, 2));
     return;
   }
@@ -2893,16 +4062,18 @@ program.command("check").description("Check system dependencies (sox, API keys)"
     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: ${config.enhancement_model})`));
+    console.log(chalk.green(`\u2713 Enhancement API key configured (model: ${resolveTranscriberModel(config)})`));
   } else {
     console.log(chalk.yellow(`\u26A0 Enhancement API key not configured \u2014 enhancement disabled`));
   }
 });
-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("-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) => {
+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);
   if (opts.language)
     config.language = opts.language;
+  if (opts.prompt !== undefined)
+    config.transcription_prompt = opts.prompt;
   applyEnhancementOptions(config, opts);
   const deps = await checkRecordingDeps();
   if (!deps.available) {
@@ -2980,7 +4151,12 @@ Bye.`));
             tags,
             agent_id: parentOpts.agent || undefined,
             project_id: parentOpts.project || undefined,
-            session_id: parentOpts.session || undefined
+            session_id: parentOpts.session || undefined,
+            machine_id: currentMachineId(),
+            metadata: buildTranscriptionMetadata(config, processed, {
+              transcriptionPromptFromRequest: opts.prompt !== undefined,
+              transcriberPromptFromRequest: opts.transcriberPrompt !== undefined || opts.systemPrompt !== undefined
+            })
           });
           process.stdout.write("\r" + " ".repeat(60) + "\r");
           const modeLabel = processed.mode === "enhanced" ? chalk.green("  [enhanced] ") : chalk.dim("  [raw] ");
@@ -3006,12 +4182,12 @@ 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, mkdirSync: mkdirSync3, chmodSync } = __require("fs");
+  const { writeFileSync: writeFileSync3, mkdirSync: mkdirSync4, chmodSync: chmodSync3 } = __require("fs");
   const { join: pathJoin2 } = __require("path");
   const { homedir: getHome } = __require("os");
   const home = getHome();
   const scriptDir = pathJoin2(home, ".hasna", "recordings");
-  mkdirSync3(scriptDir, { recursive: true });
+  mkdirSync4(scriptDir, { recursive: true });
   const scriptPath = pathJoin2(scriptDir, "record-toggle.sh");
   const pidFile = pathJoin2(scriptDir, ".recording.pid");
   const recordingsBin = pathJoin2(home, ".bun", "bin", "recordings");
@@ -3059,11 +4235,11 @@ else
   osascript -e 'display notification "Recording started..." with title "Recordings"' 2>/dev/null || true
 fi
 `;
-  writeFileSync(scriptPath, script, "utf-8");
-  chmodSync(scriptPath, 493);
+  writeFileSync3(scriptPath, script, "utf-8");
+  chmodSync3(scriptPath, 493);
   if (opts.karabiner) {
     const karabinerDir = pathJoin2(home, ".config", "karabiner", "assets", "complex_modifications");
-    mkdirSync3(karabinerDir, { recursive: true });
+    mkdirSync4(karabinerDir, { recursive: true });
     const rule = {
       title: "Recordings \u2014 Fn key to toggle recording",
       rules: [
@@ -3087,7 +4263,7 @@ fi
       ]
     };
     const karabinerPath = pathJoin2(karabinerDir, "recordings-fn.json");
-    writeFileSync(karabinerPath, JSON.stringify(rule, null, 2) + `
+    writeFileSync3(karabinerPath, JSON.stringify(rule, null, 2) + `
 `, "utf-8");
     console.log(chalk.green("Karabiner-Elements rule created!"));
     console.log(chalk.dim(`  ${karabinerPath}
@@ -3103,7 +4279,7 @@ fi
   }
   if (opts.raycast) {
     const raycastDir = pathJoin2(home, ".config", "raycast", "script-commands");
-    mkdirSync3(raycastDir, { recursive: true });
+    mkdirSync4(raycastDir, { recursive: true });
     const raycastScript = `#!/bin/bash
 
 # Required parameters:
@@ -3118,8 +4294,8 @@ fi
 ${scriptPath}
 `;
     const raycastPath = pathJoin2(raycastDir, "toggle-recording.sh");
-    writeFileSync(raycastPath, raycastScript, "utf-8");
-    chmodSync(raycastPath, 493);
+    writeFileSync3(raycastPath, raycastScript, "utf-8");
+    chmodSync3(raycastPath, 493);
     console.log(chalk.green("Raycast script command created!"));
     console.log(chalk.dim(`  ${raycastPath}`));
     console.log(chalk.dim("  Open Raycast > Script Commands > reload to see it"));
@@ -3174,51 +4350,253 @@ ${scriptPath}
   console.log(`    Create a workflow with a Hotkey trigger \u2192 Run Script: ${scriptPath}
 `);
 });
+function buildTranscriptionMetadata(config, processed, sources = {}) {
+  const transcriptionPromptConfigured = Boolean(config.transcription_prompt?.trim());
+  const transcriberPromptConfigured = Boolean(config.transcriber_prompt?.trim());
+  return {
+    transcription_prompt: {
+      configured: transcriptionPromptConfigured,
+      source: sources.transcriptionPromptFromRequest ? "request" : transcriptionPromptConfigured ? "config" : "none"
+    },
+    transcriber_prompt: {
+      configured: transcriberPromptConfigured,
+      source: sources.transcriberPromptFromRequest ? "request" : transcriberPromptConfigured ? "config" : "none"
+    },
+    post_processing: {
+      mode: processed.post_processing_mode,
+      applied: processed.mode === "enhanced",
+      reason: processed.enhancement_reason,
+      model: processed.enhancement_model
+    },
+    transcriber_model: resolveTranscriberModel(config)
+  };
+}
+async function readSaveTextInput(text, opts) {
+  const sourceCount = [
+    text !== undefined,
+    opts.textFile !== undefined,
+    Boolean(opts.stdin)
+  ].filter(Boolean).length;
+  if (sourceCount !== 1) {
+    throw new Error("Provide transcript text as an argument, --text-file, or --stdin");
+  }
+  let rawText;
+  if (opts.textFile !== undefined) {
+    rawText = readFileSync3(opts.textFile, "utf8");
+  } else if (opts.stdin) {
+    rawText = await Bun.stdin.text();
+  } else {
+    rawText = text ?? "";
+  }
+  if (!rawText.trim()) {
+    throw new Error("Transcript text is empty");
+  }
+  return rawText;
+}
+function resolvePagination(opts, parentOpts, defaultLimit = DEFAULT_LIST_LIMIT) {
+  const parsedLimit = parseNonNegativeInt(opts.limit, defaultLimit);
+  const requestedLimit = Math.min(Math.max(parsedLimit || defaultLimit, 1), 500);
+  const offset = parseNonNegativeInt(opts.cursor ?? opts.offset, 0);
+  const humanLimit = Math.min(requestedLimit, MAX_HUMAN_LIST_LIMIT);
+  return {
+    limit: parentOpts.json ? requestedLimit : humanLimit,
+    offset,
+    capped: !parentOpts.json && requestedLimit > humanLimit
+  };
+}
+function parseNonNegativeInt(value, fallback) {
+  if (value === undefined)
+    return fallback;
+  if (!/^\d+$/.test(value.trim()))
+    return fallback;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : fallback;
+}
+function parseCsvList(value) {
+  if (!value)
+    return;
+  const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : undefined;
+}
+function withoutPagination(filter) {
+  const { limit: _limit, offset: _offset, ...rest } = filter;
+  return rest;
+}
+function maybePageJson(items, pagination, opts) {
+  if (opts.limit === undefined && opts.offset === undefined && opts.cursor === undefined) {
+    return items;
+  }
+  return pageItems(items, pagination);
+}
+function pageItems(items, pagination) {
+  return items.slice(pagination.offset, pagination.offset + pagination.limit);
+}
+function formatPageHeader(label, shown, total, offset, limit) {
+  const start = total === 0 ? 0 : offset + 1;
+  const end = offset + shown;
+  return chalk.bold(`${label}: showing ${shown} of ${total} (${start}-${end}, limit ${limit})
+`);
+}
+function printPaginationHints(shown, total, pagination) {
+  const next = pagination.offset + shown;
+  if (pagination.capped) {
+    console.log(chalk.dim(`Limit capped at ${pagination.limit} for terminal output; use --json for larger machine-readable exports.`));
+  }
+  if (next < total) {
+    console.log(chalk.dim(`Next page: add --cursor ${next}`));
+  }
+}
+function printRecordingCollection(label, recordings, options) {
+  if (recordings.length === 0) {
+    console.log(chalk.dim(options.empty));
+    if (options.total > 0) {
+      console.log(chalk.dim("Try a lower --cursor or remove filters."));
+    }
+    return;
+  }
+  const total = Math.max(options.total, options.offset + recordings.length);
+  console.log(formatPageHeader(label, recordings.length, total, options.offset, options.limit));
+  for (const recording of recordings) {
+    console.log(options.verbose ? formatRecordingVerboseLine(recording) : formatRecordingLine(recording));
+  }
+  console.log("");
+  printPaginationHints(recordings.length, total, {
+    limit: options.limit,
+    offset: options.offset,
+    capped: options.capped
+  });
+  console.log(chalk.dim("Details: recordings show <id> or inspect <id>. Use --verbose for metadata, --json for raw records."));
+}
+async function printRecordingDetail(id) {
+  const parentOpts = program.opts();
+  const recording = await getStore().getRecording(id);
+  if (!recording) {
+    console.error(chalk.red(`Recording not found: ${id}`));
+    process.exitCode = 1;
+    return;
+  }
+  if (parentOpts.json) {
+    console.log(JSON.stringify(recording, null, 2));
+    return;
+  }
+  console.log(formatRecordingDetail(recording));
+}
 function formatRecordingLine(r) {
-  const id = chalk.cyan(r.id.slice(0, 8));
+  const id = chalk.cyan(truncateText(r.id, 8));
   const mode = r.processing_mode === "enhanced" ? chalk.green("enhanced") : chalk.dim("raw");
-  const text = (r.processed_text || r.raw_text).slice(0, 80);
-  const date = chalk.dim(r.created_at.slice(0, 16));
-  const tags = r.tags.length > 0 ? chalk.yellow(` [${r.tags.join(", ")}]`) : "";
+  const text = truncateText(r.processed_text || r.raw_text, 100);
+  const date = chalk.dim(truncateText(r.created_at, 16));
+  const tags = r.tags.length > 0 ? chalk.yellow(` [${summarizeTags(r.tags)}]`) : "";
   return `${id} ${mode} ${date}${tags}
-  ${text}${text.length >= 80 ? "..." : ""}`;
+  ${text}`;
+}
+function formatRecordingVerboseLine(r) {
+  const lines = [formatRecordingLine(r)];
+  const model = r.enhancement_model ? `${truncateText(r.model_used, 80)} -> ${truncateText(r.enhancement_model, 80)}` : truncateText(r.model_used, 80);
+  lines.push(`  model: ${model}`);
+  if (r.duration_ms)
+    lines.push(`  duration: ${(r.duration_ms / 1000).toFixed(1)}s`);
+  if (r.language)
+    lines.push(`  language: ${truncateText(r.language, 20)}`);
+  if (r.audio_path)
+    lines.push(`  audio: ${truncatePath(r.audio_path, 120)}`);
+  const scopes = [
+    r.agent_id ? `agent=${truncateText(r.agent_id, 80)}` : null,
+    r.project_id ? `project=${truncateText(r.project_id, 80)}` : null,
+    r.session_id ? `session=${truncateText(r.session_id, 80)}` : null
+  ].filter(Boolean);
+  if (scopes.length > 0)
+    lines.push(`  scope: ${scopes.join(" ")}`);
+  return lines.join(`
+`);
 }
 function formatRecordingDetail(r) {
   const lines = [
-    chalk.bold(`Recording ${r.id.slice(0, 8)}`),
+    chalk.bold(`Recording ${truncateText(r.id, 8)}`),
     "",
     `  Mode:     ${r.processing_mode === "enhanced" ? chalk.green("enhanced") : chalk.dim("raw")}`,
-    `  Model:    ${r.model_used}`
+    `  Model:    ${truncateText(r.model_used, 80)}`
   ];
   if (r.enhancement_model) {
-    lines.push(`  Enhanced: ${r.enhancement_model}`);
+    lines.push(`  Enhanced: ${truncateText(r.enhancement_model, 80)}`);
   }
   if (r.duration_ms) {
     lines.push(`  Duration: ${(r.duration_ms / 1000).toFixed(1)}s`);
   }
   if (r.language) {
-    lines.push(`  Language: ${r.language}`);
+    lines.push(`  Language: ${truncateText(r.language, 20)}`);
   }
   if (r.audio_path) {
-    lines.push(`  Audio:    ${r.audio_path}`);
+    lines.push(`  Audio:    ${truncatePath(r.audio_path, 240)}`);
   }
   if (r.tags.length > 0) {
-    lines.push(`  Tags:     ${r.tags.join(", ")}`);
+    lines.push(`  Tags:     ${r.tags.map((tag) => truncateText(tag, 80)).join(", ")}`);
   }
-  lines.push(`  Created:  ${r.created_at}`);
+  lines.push(`  Created:  ${truncateText(r.created_at, 40)}`);
   lines.push("");
   lines.push(chalk.bold("Raw text:"));
-  lines.push(r.raw_text);
+  lines.push(stripTerminalControls(r.raw_text));
   if (r.processed_text && r.processed_text !== r.raw_text) {
     lines.push("");
     lines.push(chalk.bold("Enhanced text:"));
-    lines.push(r.processed_text);
+    lines.push(stripTerminalControls(r.processed_text));
   }
   return lines.join(`
 `);
 }
+function truncateText(value, max) {
+  const normalized = sanitizeInline(value);
+  const prefix = [];
+  for (const point of normalized) {
+    if (prefix.length === max) {
+      return `${prefix.slice(0, Math.max(0, max - 3)).join("")}...`;
+    }
+    prefix.push(point);
+  }
+  return normalized;
+}
+function stripTerminalControls(value) {
+  return value.replace(/(?:\u001b\]|\u009d)[\s\S]*?(?:\u0007|\u001b\\|\u009c)/g, "").replace(/(?:\u001b[PX^_]|\u0090|\u0098|\u009e|\u009f)[\s\S]*?(?:\u001b\\|\u009c)/g, "").replace(/(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "").replace(/\u001b[@-_]/g, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "");
+}
+function sanitizeInline(value) {
+  return stripTerminalControls(value).replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function summarizeTags(tags) {
+  const shown = tags.slice(0, 3).map((tag) => truncateText(tag, 20));
+  if (tags.length > shown.length)
+    shown.push(`+${tags.length - shown.length}`);
+  return shown.join(", ");
+}
+function truncatePath(value, max) {
+  const normalized = sanitizeInline(value);
+  const keep = Math.max(8, max - 15);
+  const tail = [];
+  let length = 0;
+  for (const point of normalized) {
+    length += 1;
+    if (tail.length === keep)
+      tail.shift();
+    tail.push(point);
+  }
+  return length <= max ? normalized : `...${tail.join("")}`;
+}
+function relativeHint(value) {
+  const time = Date.parse(value);
+  if (!Number.isFinite(time))
+    return value;
+  const seconds = Math.max(0, Math.floor((Date.now() - time) / 1000));
+  if (seconds < 60)
+    return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60)
+    return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24)
+    return `${hours}h ago`;
+  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: readFileSync3, writeFileSync, existsSync: fileExists } = __require("fs");
+  const { readFileSync: readFileSync4, writeFileSync: writeFileSync3, existsSync: fileExists } = __require("fs");
   const { join: pathJoin2 } = __require("path");
   const { homedir: getHome } = __require("os");
   const { execSync } = __require("child_process");
@@ -3244,21 +4622,21 @@ program.command("mcp").description("Install recordings MCP server into Claude Co
           try {
             execSync("claude mcp remove recordings", { stdio: "pipe" });
           } catch {}
-          execSync(`claude mcp add --transport stdio --scope user recordings -- ${mcpCmd}`, { stdio: "pipe" });
+          execSync(`claude mcp add --transport stdio --scope user recordings -- ${mcpCmd} --stdio`, { stdio: "pipe" });
         }
         console.log(chalk.green(`${action} Claude Code (user scope in ~/.claude.json)`));
       }
       if (target === "codex") {
         const configPath = pathJoin2(home, ".codex", "config.toml");
         if (fileExists(configPath)) {
-          const content = readFileSync3(configPath, "utf-8");
+          const content = readFileSync4(configPath, "utf-8");
           if (opts.uninstall) {
             const { content: next, removed } = removeCodexServerBlock(content, "recordings");
-            writeFileSync(configPath, next, "utf-8");
+            writeFileSync3(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);
-            writeFileSync(configPath, next, "utf-8");
+            writeFileSync3(configPath, next, "utf-8");
             console.log(chalk.green(`Installed into Codex: ${configPath}`));
           }
         } else {
@@ -3269,16 +4647,16 @@ 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(readFileSync3(configPath, "utf-8"));
+          config = JSON.parse(readFileSync4(configPath, "utf-8"));
         }
         const servers = config["mcpServers"] || {};
         if (opts.uninstall) {
           delete servers["recordings"];
         } else {
-          servers["recordings"] = { command: mcpCmd, args: [] };
+          servers["recordings"] = { command: mcpCmd, args: ["--stdio"] };
         }
         config["mcpServers"] = servers;
-        writeFileSync(configPath, JSON.stringify(config, null, 2) + `
+        writeFileSync3(configPath, JSON.stringify(config, null, 2) + `
 `, "utf-8");
         console.log(chalk.green(`${action} Gemini: ${configPath}`));
       }
@@ -3308,13 +4686,14 @@ 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, ".hasna", "recordings", "Recordings.app");
+  const installedAppPath = pathJoin(home, "Applications", "Recordings.app");
   const executablePath = pathJoin(installedAppPath, "Contents", "MacOS", "Recordings");
   const logPath = pathJoin(home, ".hasna", "recordings", "Recordings.log");
-  const installerPath = pathJoin(packageRoot, "scripts", "install_macos_app.sh");
+  const installerPath = getMacOSInstallerPath(packageRoot);
   const nativeSourcesPath = pathJoin(packageRoot, "src", "native", "Recordings");
   const signingInfo = getCodeSigningInfo(installedAppPath);
-  const permissionCodeHash = signingInfo.adHoc ? signingInfo.cdHash : null;
+  const legacyInstallPaths = findLegacyMacOSAppPaths(home, installedAppPath);
+  const permissionStatus = legacyInstallPaths.length > 0 ? "ambiguous_multiple_installations" : null;
   return {
     platform: process.platform,
     package_root: packageRoot,
@@ -3323,20 +4702,40 @@ function getMacOSAppStatus() {
     native_sources_path: nativeSourcesPath,
     native_sources_available: existsSync4(pathJoin(nativeSourcesPath, "Package.swift")),
     installed_app_path: installedAppPath,
+    legacy_install_paths: legacyInstallPaths,
     installed: existsSync4(installedAppPath),
     executable_path: executablePath,
     executable: existsSync4(executablePath),
     app_code_hash: signingInfo.cdHash,
     ad_hoc_signed: signingInfo.adHoc,
-    microphone_permission: getTccPermission("kTCCServiceMicrophone", home, permissionCodeHash),
-    accessibility_permission: getTccPermission("kTCCServiceAccessibility", home, permissionCodeHash),
+    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),
     log_path: logPath
   };
 }
+function findLegacyMacOSAppPaths(home, canonicalPath) {
+  const candidates = [
+    pathJoin(home, ".hasna", "recordings", "Recordings.app"),
+    pathJoin("/", "Applications", "Recordings.app")
+  ];
+  const userApplications = pathJoin(home, "Applications");
+  if (existsSync4(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();
+}
 function resetMacOSPermissions() {
   const services = ["Microphone", "Accessibility"];
   for (const service of services) {
-    const result = spawnSync("tccutil", ["reset", service, "com.hasna.recordings"], {
+    const result = spawnSync4("tccutil", ["reset", service, "com.hasna.recordings"], {
       stdio: "inherit"
     });
     if (result.error) {
@@ -3347,9 +4746,16 @@ function resetMacOSPermissions() {
 }
 function getCodeSigningInfo(appPath) {
   if (process.platform !== "darwin" || !existsSync4(appPath)) {
-    return { cdHash: null, adHoc: false };
+    return {
+      cdHash: null,
+      adHoc: false,
+      identifier: null,
+      teamIdentifier: null,
+      designatedRequirement: null,
+      authorities: []
+    };
   }
-  const result = spawnSync("codesign", ["-d", "--verbose=4", appPath], {
+  const result = spawnSync4("/usr/bin/codesign", ["-d", "-r-", "--verbose=4", appPath], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"]
   });
@@ -3357,32 +4763,31 @@ function getCodeSigningInfo(appPath) {
 ${result.stderr}`;
   const cdHash = output.match(/^CDHash=([a-fA-F0-9]+)/m)?.[1]?.toLowerCase() ?? null;
   const adHoc = /Signature=adhoc/.test(output);
-  return { cdHash, adHoc };
+  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());
+  return { cdHash, adHoc, identifier, teamIdentifier, designatedRequirement, authorities };
 }
-function getTccPermission(service, home, currentCodeHash) {
+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 || '|' || ifnull(hex(csreq), '') from access where service = '" + service.replace(/'/g, "''") + "' and client = 'com.hasna.recordings' order by last_modified desc limit 1;";
+  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 = spawnSync("sqlite3", [dbPath, sql], {
+    const result = spawnSync4("/usr/bin/sqlite3", [dbPath, sql], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
     const value = result.stdout.trim();
     if (!value)
       continue;
-    const [authValue, csreqHex = ""] = value.split("|");
-    const label = tccAuthValueLabel(authValue ?? "");
-    if (label === "allowed" && currentCodeHash && csreqHex && !csreqHex.toLowerCase().includes(currentCodeHash.toLowerCase())) {
-      return "stale_allowed_for_previous_app_build";
-    }
-    return label;
+    return `${tccAuthValueLabel(value)}_identity_unverified`;
   }
   return "not_determined";
 }
@@ -3401,24 +4806,27 @@ function tccAuthValueLabel(value) {
   }
 }
 function findPackageRoot() {
-  let current = dirname3(fileURLToPath(import.meta.url));
+  let current = dirname4(fileURLToPath(import.meta.url));
   while (true) {
     const packagePath = pathJoin(current, "package.json");
     if (existsSync4(packagePath)) {
       try {
-        const pkg = JSON.parse(readFileSync2(packagePath, "utf8"));
+        const pkg = JSON.parse(readFileSync3(packagePath, "utf8"));
         if (pkg.name === "@hasna/recordings") {
           return current;
         }
       } catch {}
     }
-    const parent = dirname3(current);
+    const parent = dirname4(current);
     if (parent === current) {
       return process.cwd();
     }
     current = parent;
   }
 }
+function getMacOSInstallerPath(packageRoot = findPackageRoot()) {
+  return pathJoin(packageRoot, "scripts", "install_macos_app.sh");
+}
 program.parseAsync().catch((error) => {
   const msg = error instanceof Error ? error.message : String(error);
   console.error(`ERROR: ${msg}`);