@hasna/recordings 0.2.10 → 0.2.13

package/dist/index.js

@@ -30,8 +30,12 @@ class RecordingsV1Client {
     const url = new URL(this.baseUrl + path);
     if (opts.query) {
       for (const [key, value] of Object.entries(opts.query)) {
-        if (value !== undefined && value !== null)
+        if (Array.isArray(value)) {
+          for (const item of value)
+            url.searchParams.append(key, String(item));
+        } else if (value !== undefined && value !== null) {
           url.searchParams.set(key, String(value));
+        }
       }
     }
     const headers = { Accept: "application/json", ...this.baseHeaders, ...opts.init?.headers };
@@ -194,23 +198,200 @@ 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";
 
 // src/lib/config.ts
-import { copyFileSync, existsSync, readFileSync, mkdirSync, readdirSync, statSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { copyFileSync, existsSync, readFileSync, mkdirSync as mkdirSync2, readdirSync, realpathSync as realpathSync2, statSync } from "fs";
+import { dirname as dirname2, join as join2, resolve as resolve2, sep as sep2 } from "path";
+import { homedir as homedir2 } from "os";
+
+// src/lib/install-maintenance.ts
+import { randomUUID } from "crypto";
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
 import { homedir } from "os";
+import { basename, dirname, isAbsolute, join, 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"] || homedir();
+  return join(home, ".hasna");
+}
+function installMaintenanceMarkerPath(env = process.env) {
+  return join(stateParent(env), INSTALL_MAINTENANCE_MARKER_NAME);
+}
+function storeReaderLeasesPath(env = process.env) {
+  return join(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 join(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 = join(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 = randomUUID();
+  const pendingLease = join(readerRoot, `.pending-${process.pid}-${nonce}`);
+  const activeLease = join(readerRoot, `lease-${process.pid}-${nonce}`);
+  const releasedLease = join(readerRoot, `.released-${process.pid}-${nonce}`);
+  let active = false;
+  try {
+    mkdirSync(pendingLease, { mode: 448 });
+    const owner = join(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",
@@ -227,17 +408,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() || join(getDataDir(), "config.json");
+  config.config_warnings = [];
+  let explicitPostProcessingMode = false;
+  let explicitTranscriberModel = false;
+  const filePath = configPath || findConfigFile() || join2(getDataDir(), "config.json");
   let fileProvidedOpenAIKey = false;
   if (existsSync(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 {}
@@ -254,12 +441,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) {
@@ -277,14 +487,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 = join(getDataDir(), "recordings.db");
+    config.db_path = join2(getDataDir(), "recordings.db");
   }
   if (!config.audio_dir) {
-    config.audio_dir = join(getDataDir(), "audio");
+    config.audio_dir = join2(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"]) {
@@ -303,36 +585,68 @@ function getDataDir() {
   if (projectLocalDir)
     return projectLocalDir;
   const home = getHomeDir();
-  const newDir = join(home, ".hasna", "recordings");
-  const oldDir = join(home, ".recordings");
+  const newDir = join2(home, ".hasna", "recordings");
+  const oldDir = join2(home, ".recordings");
   if (existsSync(oldDir)) {
+    const releaseLease = acquireLocalStoreReaderLease();
     try {
-      mergeDirectoryContents(oldDir, newDir);
-    } catch {}
+      try {
+        if (existsSync(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 ? join(dir, ".recordings", entry) : join(dir, ".recordings");
-      if (existsSync(candidate))
-        return candidate;
-    }
-    const parent = dirname(dir);
+    if (excludeBoundary && dir === boundary)
+      break;
+    const candidate = entry ? join2(dir, ".recordings", entry) : join2(dir, ".recordings");
+    if (existsSync(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 (existsSync(join2(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 = join(sourceDir, entry);
-    const targetPath = join(targetDir, entry);
+    const sourcePath = join2(sourceDir, entry);
+    const targetPath = join2(targetDir, entry);
     const sourceStats = statSync(sourcePath);
     if (sourceStats.isDirectory()) {
       mergeDirectoryContents(sourcePath, targetPath);
@@ -342,7 +656,7 @@ function mergeDirectoryContents(sourceDir, targetDir) {
   }
 }
 function loadSecretKey(keyName) {
-  const secretsPath = join(getHomeDir(), ".secrets");
+  const secretsPath = join2(getHomeDir(), ".secrets");
   if (!existsSync(secretsPath))
     return "";
   for (const candidate of listSecretFiles(secretsPath)) {
@@ -369,7 +683,7 @@ function listSecretFiles(path) {
     if (!stats.isDirectory())
       return [];
     return readdirSync(path).sort().flatMap((entry) => {
-      const child = join(path, entry);
+      const child = join2(path, entry);
       try {
         const childStats = statSync(child);
         if (childStats.isDirectory())
@@ -384,14 +698,19 @@ function listSecretFiles(path) {
   }
 }
 function getHomeDir() {
-  return process.env["HOME"] || process.env["USERPROFILE"] || homedir();
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir2();
 }
 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/database.ts
@@ -480,8 +799,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");
@@ -537,6 +856,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 {
@@ -561,20 +937,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();
@@ -586,6 +978,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) {
@@ -624,12 +1030,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();
@@ -702,16 +1103,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 {
@@ -777,7 +1168,7 @@ function setAgentFocus(idOrName, projectId, db) {
 }
 
 // src/version.ts
-var VERSION = "0.2.10";
+var VERSION = "0.2.13";
 
 // src/db/feedback.ts
 function saveFeedback(input) {
@@ -1070,6 +1461,7 @@ function resolveStorageClient(name, env = process.env, fetchImpl) {
 }
 
 // src/store.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
 var APP = "recordings";
 function listQuery(filter) {
   if (!filter)
@@ -1079,6 +1471,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,
@@ -1095,58 +1488,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) ? randomUUID2() : 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) {
@@ -1157,6 +1555,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;
@@ -1238,6 +1666,17 @@ 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")}`;
+}
 var cached = null;
 function getStore(env = process.env) {
   if (env === process.env && cached)
@@ -1255,17 +1694,20 @@ function __resetStore() {
 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;
 }
 function resetClient() {
   _client = null;
+  _clientApiKey = null;
 }
 async function transcribeAudio(audioPath, config, options = {}) {
   const client = getClient(config);
@@ -1276,7 +1718,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();
@@ -1303,7 +1745,7 @@ async function transcribeBuffer(buffer, filename, config, options = {}) {
       file,
       model: config.transcription_model,
       language: config.language || undefined,
-      prompt: buildVerbatimPrompt(options.prompt),
+      prompt: buildVerbatimPrompt(options.prompt ?? config.transcription_prompt),
       response_format: "json"
     });
     const durationMs = Date.now() - startTime;
@@ -1360,18 +1802,21 @@ function getMimeType(filename) {
 // 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 resetEnhancementClient() {
   _enhancementClient = null;
+  _enhancementClientApiKey = null;
 }
 function needsEnhancement(text, config) {
   const lower = text.toLowerCase().trim();
@@ -1417,6 +1862,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:
@@ -1437,13 +1883,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",
@@ -1461,7 +1908,7 @@ ${systemPrompt}` : basePrompt;
     return {
       original: rawText,
       enhanced,
-      model: config.enhancement_model,
+      model,
       reasoning: null
     };
   } catch (error) {
@@ -1469,40 +1916,64 @@ ${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/lib/recorder.ts
 import { spawn } from "child_process";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import { existsSync as existsSync2 } from "fs";
 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",
@@ -1513,20 +1984,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",
@@ -1539,11 +1996,20 @@ function startRecording(config) {
   }
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
   const filename = `recording-${timestamp}.${config.audio_format}`;
-  const filepath = join2(config.audio_dir, filename);
+  const filepath = join3(config.audio_dir, filename);
   const args = buildRecordArgs(filepath, config);
-  _recordProcess = spawn(args[0], args.slice(1), {
-    stdio: ["pipe", "pipe", "pipe"]
-  });
+  const releaseLease = isGlobalRecordingsStatePath(filepath) ? acquireLocalStoreReaderLease() : () => {};
+  let recordProcess;
+  try {
+    recordProcess = spawn(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) {
@@ -1552,14 +2018,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;
 }
@@ -1600,7 +2070,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 = join2(config.audio_dir, filename);
+  const filepath = join3(config.audio_dir, filename);
   const args = [
     "rec",
     "-r",
@@ -1614,16 +2084,21 @@ 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 && !existsSync2(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 && !existsSync2(filepath)) {
+      const stderr = await new Response(proc.stderr).text();
+      throw new RecordingError(`Recording failed (exit ${exitCode}): ${stderr}`);
+    }
+    return filepath;
+  } finally {
+    releaseLease();
   }
-  return filepath;
 }
 export {
   transcribeBuffer,
@@ -1636,6 +2111,9 @@ export {
   resetClient,
   recordDuration,
   processText,
+  normalizePostProcessingMode,
+  normalizePostProcessingConfig,
+  normalizeModelSlots,
   needsEnhancement,
   loadConfig,
   isRecording,
@@ -1655,6 +2133,9 @@ export {
   RecordingError,
   HasnaHttpError,
   EnhancementError,
+  DEFAULT_TRANSCRIPTION_MODEL,
+  DEFAULT_REALTIME_TRANSCRIPTION_MODEL,
+  DEFAULT_REALTIME_SESSION_MODEL,
   DEFAULT_CONFIG,
   APP
 };