@hasna/recordings 0.2.10 → 0.2.13

package/dist/storage.js

@@ -33,23 +33,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",
@@ -66,17 +243,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 {}
@@ -93,12 +276,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) {
@@ -116,14 +322,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"]) {
@@ -142,36 +420,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);
@@ -181,7 +491,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)) {
@@ -208,7 +518,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())
@@ -223,14 +533,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
@@ -319,8 +634,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");
@@ -376,6 +691,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 {
@@ -400,20 +772,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();
@@ -425,6 +813,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) {
@@ -463,12 +865,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();
@@ -541,16 +938,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 {
@@ -616,7 +1003,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) {
@@ -909,6 +1296,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)
@@ -918,6 +1306,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,
@@ -934,58 +1323,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) {
@@ -996,6 +1390,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;
@@ -1077,6 +1501,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)